Repository navigation
Commit d9bf777
feat(spec): optional caller on IAutomationService.toggleFlow (#26545)
<!-- claude-projects-attribution: {"github_login":"os-support-ai"} -->
_Requested by **Yibo Wang** · [project
thread](https://claude.ai/code/project/chan_01BVUyyPie8gHwoPM18iABwB?thread=cmsg_01BVUyyPie8gHwoPM18iABwBXVayMXFjUu7EtXTKCGj4pc)_
Fixes #26506
Clause-②: yes (widening)
Metadata-protocol: none
## 维护者速读
- 改了什么:`IAutomationService.toggleFlow` 增加可选的第三个参数 `caller`,只携带
`userId`,用来告诉服务是谁开关了这个打包流程。
- 为什么改:管理员关掉打包流程时,激活台账行与审计行的操作人都是空,审计无法说明是哪位管理员做的;服务端修复 (#26474)
需要契约先有这个通道。
- 风险与回滚:参数可选,现有实现与调用方原样编译,运行时行为零变化;回滚即还原这一行签名。
- 先看:`packages/spec/src/contracts/automation-service.ts`(`toggleFlow`
签名与
TSDoc),`packages/spec/src/contracts/automation-toggle-flow-caller.pin.test.ts`。
- 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run
src/contracts/automation-toggle-flow-caller.pin.test.ts`,预期 2 个用例通过。
- 需要你做的:无,席位落地。
## What changes
`IAutomationService.toggleFlow?(name, enabled)` gains an optional third
parameter, `caller`, typed as `Pick` over `AutomationContext` narrowed
to the single key `'userId'`. A door that serves a person passes that
person's id, so the `sys_metadata_activation` row the switch writes, and
its `sys_audit_log` row, can name the admin instead of a null actor. The
method's TSDoc now says what the channel carries, that it is attribution
only (it grants nothing, and an implementation neither refuses nor
widens the switch on it), and that an absent caller, or one with no
`userId`, means an unattributed write.
The parameter is optional, so every current implementer
(`AutomationEngine.toggleFlow` in `@objectstack/service-automation`) and
every caller (the runtime's `POST /api/v1/automation/:name/toggle` door
and its test doubles) compiles unchanged. This is the contract half
only: the door passing the caller and the engine writing with it are the
server half, #26474.
## Why this shape
The order was to follow `execute(flowName, context?: AutomationContext)`
in the same contract, reusing `AutomationContext` or a narrow subset of
it. I took the subset, one key:
- **`userId` is the key the write records.** The engine stamps
`created_by` / `updated_by` from the context's user, and the audit
writer reads `user_id` from it. `AutomationContext.userId` is already
the contract's spelling for "the acting user", so `execute` and
`toggleFlow` name the person the same way.
- **No positions, permissions or posture.** `toggleFlow` is no authority
gate: ADR-0126 §5 gates the switch at the door that receives the
request, and the ledger write runs elevated. A channel carrying grants
would invite a second gate inside the service whose rules could drift
from the door's.
- **No tenant.** The activation ledger is deployment state with no
organization column (ADR-0126 as amended by ADR-0131 D6), so a tenant id
would carry nothing the write reads.
- **Not the whole `AutomationContext`.** Most of its keys (`record`,
`params`, `runAs`, `flowName`, `flowRunId`, `callerParamKeys`) describe
a run and mean nothing for a switch. Taking the whole type would leave
each implementer to decide which to ignore. With the narrow type, a
caller literal carrying `positions` or `record` does not compile
(pinned).
- **Not `ExecutionContext`.** Several store contracts take the caller as
`ExecutionContext | undefined` (`IAIConversationService`,
`ISharingService`). That would hand the service the caller's whole
principal, grants included, which is the second-gate risk above. The
order also pointed at the `AutomationContext` precedent in this
contract.
Widening later is additive: another key can join the `Pick` if a reader
ever needs it.
## Tests
`packages/spec/src/contracts/automation-toggle-flow-caller.pin.test.ts`,
compiled by `check:test-typecheck` under `tsconfig.test.json` and run by
vitest:
- type level: the third parameter is exactly the narrowed `Pick` or
`undefined`; the arity is 2 or 3; `name` and `enabled` keep their types
and places;
- additive: a two-parameter implementation (a function and a class)
still satisfies the contract, and a two-argument call still compiles;
- narrow: a caller literal with `positions`, or with `record`, is a
compile error (`@ts-expect-error`, which itself fails if the line ever
compiles);
- runtime: an implementation reads `caller?.userId` without a cast, and
reads it as absent when not passed; a two-parameter implementation runs
when a caller is passed.
Reverse verification (one-off, not kept): the signature reverted to the
two-parameter form via `scripts/ablation-replace.mjs` (anchor 1 to 0,
blob `8fc1e1cc` to `201b1e11`), then `tsc --noEmit -p
tsconfig.test.json`. The pin file turned red with 9 errors (TS2344 on
both identity asserts, TS2554 on each three-argument call, TS2493 and
TS7006 where the third parameter vanished). Restored: blob equals HEAD
and `git diff HEAD` is empty.
## Acceptance notes
- Until #26474's server half lands, the flow switch still writes a null
actor; this PR changes no runtime behaviour.
- The runtime tests that pin the door's call as
`toHaveBeenCalledWith(FLOW, false)`
(`automation-activation-posture-gate.test.ts`,
`http-dispatcher.test.ts`) will need the caller argument when the door
starts passing it. That is the server half's edit, noted here so it is
not a surprise.
- A non-human caller (an agent or service principal) has no `actor`
label on this channel; `AutomationContext` declares none. No reader
needs one today.
## Verification
All readings at head `f3ce50a7`, in the `objectstack-issue-26506`
worktree based on `origin/main` `3fcafcd3`.
- `pnpm --filter @objectstack/spec build` under the verify lock: VERDICT
command-exit 0.
- `pnpm --filter @objectstack/spec check:generated`: exit 0, all 14
generated artifacts up to date, and `git status` clean afterwards, so no
generated artifact moved (`api-surface/contracts.json` records
`IAutomationService` by name only).
- `pnpm --filter @objectstack/spec typecheck` (tsc, scripts typecheck,
`check:test-typecheck`) and vitest on the new pin,
`automation-service.test.ts` and
`automation-context-caller-param-keys.pin.test.ts`: VERDICT command-exit
0, Test Files 3 passed, Tests 22 passed.
- `pnpm exec eslint --no-inline-config` on both changed `.ts` files:
exit 0.
<details><summary>Derived gates: 79 derived, 75 run with exit 0, 4 NOT
MEASURED</summary>
`node scripts/pm/dispatch-gates.mjs --commands` derived 79 families from
the three changed paths; all were run serially and reconciled with
`--ran` (79 accounted, 0 unrun). Four exited 3, PREREQUISITE NOT MET,
because this container has a shallow clone and no full build. They read
nothing this diff touches, and CI runs them:
- `node scripts/check-plugin-teardown-shape.mjs --self-test` (needs an
unshallowed `main`)
- `pnpm --filter @objectstack/lint run check:doc-formula-expressions`
(needs built packages)
- `pnpm check:dual-build-cjs-loads` (needs every package's `dist`)
- `pnpm check:lean-entry-closure` (needs `@objectstack/objectql` built)
</details>
Not run locally: the full dogfood battery (the title has no `!` and the
declaration has no `(narrowing)` arm), `test:repo` and the repo-wide
lint, which are CI's.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes.
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
- [x] The *Before Submitting* list in CONTRIBUTING.md is done.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01WGufzgdxgk35nWqLB6EMzg
---
_Generated by [Claude
Code](https://claude.ai/code/session_01WGufzgdxgk35nWqLB6EMzg)_
Co-authored-by: Claude <noreply@anthropic.com>1 parent ab3c776 commit d9bf777
3 files changed
Lines changed: 120 additions & 1 deletion
File tree
- .changeset
- packages/spec/src/contracts
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
991 | 991 | | |
992 | 992 | | |
993 | 993 | | |
| 994 | + | |
| 995 | + | |
| 996 | + | |
| 997 | + | |
| 998 | + | |
| 999 | + | |
| 1000 | + | |
| 1001 | + | |
| 1002 | + | |
| 1003 | + | |
| 1004 | + | |
| 1005 | + | |
| 1006 | + | |
| 1007 | + | |
| 1008 | + | |
| 1009 | + | |
| 1010 | + | |
| 1011 | + | |
| 1012 | + | |
| 1013 | + | |
994 | 1014 | | |
995 | 1015 | | |
| 1016 | + | |
996 | 1017 | | |
997 | | - | |
| 1018 | + | |
998 | 1019 | | |
999 | 1020 | | |
1000 | 1021 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
0 commit comments