Give duly_catalog_apply a UI home: object-bound twin on the catalog list toolbar

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code

[os-warren]

Fixes#27

duly_catalog_apply is the product's biggest adoption path — instantiate a customer's existing role catalog onto their people, instead of asking 400 people to hand-type their own duties — and it had no button. global_nav was retired in protocol 17 and every surviving action location is object-bound, so an object-less action was reachable only over POST /api/v1/actions/global/... or MCP. A pilot whose first step requires someone to write curl does not happen.

This adds the adjudicated object-bound twin: duly_catalog_apply_to_people, bound to duly_catalog_item, placed on its list_toolbar, wired to the same applyCatalogHandler function reference. The global action stays registered and headless — it is what REST and MCP use. No ai.exposed.

The input shape I measured, and which I chose

The adjudication flagged one thing it could not verify: whether a list_toolbar action can express position_codeplus a multi-user picker as its input, with the two-step form (select catalog rows → modal for the people) as the fallback. Measured first, four ways:

Layer	Measurement
Spec, author time	ActionSchema has no refinement coupling locations to params. This exact declaration — objectName + list_toolbar + text + user/multiple — parses clean.
Renderer, param collection	objectui packages/core/src/actions/ActionRunner.ts opens the param dialog whenever params is a non-empty array, before dispatch, with no location gate.
Renderer, the picker	resolveActionParams carries multiple through its inline branch → paramToField maps user onto the user widget with it → UserField delegates to LookupField, whose multi-select is the picker.
Dispatcher, submit	The bag the dialog produces, { position_code, users: [...] }, passes the spec's own validateActionParams (ADR-0104 D2) — and a scalar in users is refused with invalid_shape. Enforced, not merely declared.

So the one-step form ships. The fallback was not needed, and it would have cost more than UX: it needs the handler to read _selectedIds instead of position_code, which is a second implementation of the thing this action already does — the one thing the card forbade.

Corroborated at runtime: booting the stack the way the CLI does, ql.getSchema('duly_catalog_item').actions is ["duly_catalog_apply_to_people"] — the array the list toolbar filters by location, and the first rung the REST route resolves declarations from.

Why the twin is spread from the global rather than restated

exportconstCatalogApplyToPeopleAction=defineAction({
...CatalogApplyAction,name: CATALOG_APPLY_TO_PEOPLE_ACTION,objectName: CATALOG_ITEM_OBJECT,target: CATALOG_APPLY_TO_PEOPLE_ACTION,label: 'Apply to people',locations: ['list_toolbar'],});

params, requiredPermissions, description, icon, variant and type cannot drift from the global, because there is only one copy. That matters in a specific direction: the dispatcher validates the params of the action you called, so a twin that fell behind would 400 on a dialog the global route accepts — or, worse, quietly stop requiring users. defineAction deep-copies on parse (measured), so the two declarations share no mutable state.

requiredPermissions: ['duly.catalog.apply'] rides that spread deliberately. An object-bound action that skipped the capability its global twin requires is a bypass, not a convenience — objectui's action:bar filters its own set through the shared capability gate before placement, and the platform action route answers 403.

A distinct name, not a second declaration of duly_catalog_apply — and that is measured, not stylistic. defineStack accepts two actions sharing one name without a word (filed upstream, below).

The trap with no author-time gate — ablated

An action whose handler is not registered renders, is clickable, and fails at call time; pnpm validate passes green. Both legs were run from a committed tree, each with a trap … EXIT INT TERM restore, and each mutation confirmed on disk before anything was read.

Ablation 1 — delete the twin's registerAction line (marker count 1 → 0 on disk, git diff --stat = 1 deletion):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 6 Actions"
pnpm test → exit 1 3 failed | 379 passed
× catalog-action-placement › is wired under the key its dispatch reaches, and nowhere else
× catalog-action-placement › is wired to the SAME handler function reference as the global action
× catalog-instantiate › every declared script action has a handler under a key that can reach it

That is the trap reproduced exactly: validate stays green and still counts 6 actions, while the button would 404. Restore leg confirmed on disk (marker back to 1, tree clean).

Ablation 2 — delete the barrel entry (array-entry count 1 → 0, import/re-export left intact and asserted):

pnpm validate → exit 0 "✓ Validation passed" "UI: 1 Apps 5 Views 5 Actions" ← quietly 5, not 6
pnpm test → exit 1 8 failed | 374 passed

AGENTS.md rule 2's failure, measured: dead metadata that type-checks and validates.

(A first attempt at ablation 2 was voided by its own on-disk check and re-run — the marker I picked also matched the import line, so the count went 2→1 rather than →0. The mutation had landed; the check was wrong. Reported here rather than silently re-run.)

No dist/ sat between the mutation and the reading: the tests import ../src/... by relative path, not through a package exports map, pnpm validate loads objectstack.config.ts from source, and the kernel-booting suites already pin artifactPath at a nonexistent file for this reason.

Gates

All four green at 06416fb, the final commit, re-run after it:

pnpm validate exit 0 ✓ Validation passed (370ms) UI: 1 Apps 5 Views 6 Actions
pnpm typecheck exit 0
pnpm test exit 0 Test Files 13 passed (13) Tests 382 passed (382)
pnpm build exit 0 ✓ Build complete (653ms) 6 Actions, 2 handlers bundled

Bundling 2 handlers is unchanged from main (verified against a pristine origin/main tree) — that count is dulyFunctions, not action handlers, which are wired through onEnable. pnpm test was also re-run with dist/ present and stayed at 382 passed.

Platform gaps filed upstream

Two, both found by measurement here, both reported rather than worked around (AGENTS.md rule 9):

• Startup [action-governance] reports every OBJECT-LESS declared action as "registered handler with NO declaration — REFUSED at dispatch", and the route contradicts it objectstack#14123 — startup [action-governance] reports every object-less declared action as "registered handler with NO declaration — REFUSED at dispatch", and the REST route contradicts it. Pre-existing on main (reproduced on a pristine origin/main tree): global:duly_catalog_apply and global:duly_catalog_sync are both named in that warning on every boot. Root cause measured — the audit sources declarations from meta.listObjects() + meta.loadMany('action'), and loadMany('action') returns [], so only object-BOUND actions survive it; the route resolves the same actions via ql.registry.getItem('action', name) and dispatches fine. The warning's second remedy — "drop the registration" — would have broken this app's onboarding path. Worth knowing for Document the MCP surface — ask the system what is late #21: the REST route in Object-less ("global") actions have no UI home in protocol 17 — the onboarding flow is API-only #27's premise does work.
• defineStack accepts two actions sharing one name without a word — including two GLOBAL ones, where the <object>:<name> handler map then silently shadows one objectstack#14124 — defineStack accepts two actions sharing one name, including two global ones, where the object-colon-name handler map then collapses to one key and whichever handler registers second silently shadows the other. This is why the twin has its own name.

Neither is fixed here.

A third, not filed: the GitHub body sanitizer does not merely strip a short angle-bracket fragment, it truncates the remainder of the stored body. The first version of this PR description was cut mid-sentence at the fragment that used to sit in the line above, silently dropping everything after it — including the whole File surface section below. Worth knowing wherever the repo's sanitizer guidance lives: the marker-eating half is documented, this half is sharper.

File surface

Beyond the surface named on the card, and flagged deliberately:

• src/actions/catalog.handlers.ts — two name constants and one registerAction line. No handler body touched. The twin cannot be reachable without a registration entry (the card anticipates this: "if your twin needs its own registration entry, assert the wiring in a test and ablate it"), and registerCatalogActionHandlers is the catalog's registration point — splitting it across two files would contradict that function's own contract.
• src/actions/index.ts — the barrel entry, required by AGENTS.md rule 2. Ablation 2 shows what its absence costs.

src/apps/duly.app.ts was not touched.nav_catalog already lands on the Role catalog list, so the toolbar button completes the path with no nav change; the adjudicated scope has three items and none of them is nav. One thing worth PM's attention, measured while I was there: ObjectNavItemSchema.runAction is a real declared slot — "auto-run this declared action once on arrival at the object's list surface" — and objectui arms it only for an action that renders at list_toolbar on that object (ObjectView.tsx, actionRendersAt(a, 'list_toolbar')). So this twin is exactly what would make a one-click "Apply role catalog" nav entry possible. Not taken: it is new declared surface with no pull yet, and it is a separate decision. It costs one line whenever that decision is made.

objectstack.config.ts, AGENTS.md, src/objects/duty.object.ts and the handler bodies: untouched. No changesets in this repo.

Generated by Claude Code