ConnectorActionDescriptor declares nothing about whether an action reads or writes, so the platform cannot count what a connector_action did

[os-zhuang]

Package: @objectstack/spec (packages/spec/src/integration/connector-descriptor.ts)
Found while wiring #4354's per-run summaries into connector_action.

The gap

ConnectorActionDescriptor describes an action's shape and nothing about its effect:

export interface ConnectorActionDescriptor {
  readonly key: string;
  readonly label: string;
  readonly description?: string;
  readonly inputSchema?: Record<string, unknown>;
  readonly outputSchema?: Record<string, unknown>;
}

So crm.push_opportunity and crm.lookup_account are indistinguishable to the runtime. Nothing in the authorable Connector schema fills this in either — registerConnector reads actions for dispatch only.

Why it matters now

#4354 makes every flow run report selected / acted, and selected > 0 AND acted = 0 over consecutive runs is the broken-sweep alert. For a connector_action the platform has to pick one of three answers, and two of them are wrong:

• acted: 0 understates a Salesforce create. Every healthy connector-driven sweep then trips the alert, and operators learn to ignore it — which disables the detector for the flows that really are dead.
• acted: 1 overstates a lookup. A sweep whose only "action" is a connector read then looks busy forever, so the alert never fires. That is Surface flow run summaries (selected / acted / skipped) — a scheduled flow that does nothing is currently indistinguishable from one with nothing to do #4354's original bug restored, one layer out.
• unknown is the honest one, and it is what shipped: the executor reports metrics: { unmeasuredEffect: true }, the run summary carries an unmeasured tally, and the documented alert became selected > 0 AND acted = 0 AND unmeasured = 0.

That is correct but weaker than it needs to be. A connector-driven flow currently contributes no signal at all: it can neither confirm work happened nor be flagged for doing none. Every ObjectStack app whose automation runs through connectors is in that blind spot.

Proposal

Let the action declare its effect, and let the runtime count it:

export interface ConnectorActionDescriptor {
  readonly key: string;
  readonly label: string;
  readonly description?: string;
  readonly inputSchema?: Record<string, unknown>;
  readonly outputSchema?: Record<string, unknown>;
  /**
   * What the action does upstream. `read` never mutates; `write` does.
   * Absent keeps today's behaviour — the run reports the effect as uncountable.
   */
  readonly effect?: 'read' | 'write';
}

Then connector_action reports acted: 1 for a successful write, acted: 0 for a read, and falls back to unmeasuredEffect only when the connector declared nothing. Optional on purpose: existing connectors keep working and lose nothing, and declaring it is a strict improvement rather than a migration.

Worth considering alongside it: a count rather than a boolean, for bulk actions that report how many upstream records they touched (outputSchema often already carries one). That can follow — the read/write split is the part that unblocks the alert.

Note the ADR-0076 D12 angle: this is a machine-readable surface that is currently silent rather than wrong, which is the right failure. The proposal is to let it be accurate.

Related: #4354 (the summaries this feeds), #4347 (the silent-failure class both exist to surface).

[os-zhuang]

裁决(PM 代决,维护者可否决):按提案落地 —— ConnectorActionDescriptor 增加可选 effect?: 'read' | 'write':声明 write → acted:1,声明 read → acted:0,不声明 → 维持 unmeasuredEffect: true 现状。

两轴理由:

• 长远合理性:纯增量、无迁移,把 Surface flow run summaries (selected / acted / skipped) — a scheduled flow that does nothing is currently indistinguishable from one with nothing to do #4354 的 broken-sweep 告警从「诚实但盲」升级为「可准确」;ADR-0076 D12 的「沉默而非错误」原则不变,只是让愿意声明的 connector 变得可度量。
• 防 AI 犯错:让 AI 写 connector 时有一个正确的声明位可填,而不是在 acted:0/1 两个都错的答案里瞎选(一个制造误报让操作员学会忽略告警,一个让告警永不触发)。

count 型效果(bulk 场景)暂不做,待真实需求。已入队待派。

---

Generated by Claude Code

[os-zhuang]

分诊级别建议：给 ConnectorActionDescriptor 增加 reads/writes 声明面是新契约词表，创业阶段聚焦原则下需要真实业务拉动佐证与维护者拍板——建议摘 pm:queue 换 needs-user-decision 进决策箱。交分诊座位定夺。背景：维护者 2026-08-06 拍板 spec 车道缩盘方案，见 #5837。

---

Generated by Claude Code

[os-zhuang]

标签落实（维护者 2026-08-06 指示，session_01LeEfA7CFwbJb7JJmXm2KM3）：按 08-06 降级建议执行 pm:queue → needs-user-decision——ConnectorActionDescriptor 增加 reads/writes 声明面属新契约词表，创业阶段聚焦原则下需真实业务拉动佐证与拍板。

---

Generated by Claude Code