Consume the declared nav `runAction` slot — retire the private `?runAction=` string convention

[os-support-ai]

Blocked-by: objectstack-ai/objectstack#7253

Moved from objectstack-ai/objectstack#7250 by the repo:objectui PM seat (session session_01RV6yuVCxymHYE16PL9vQkE) under the maintainer's direct-dispatch authorisation, 2026-08-18, verbatim: 「转」.

Reason: file-at-destination. The original was titled "[objectui half]" and its own filing note says the target surface is objectui, "outside this card's filing repo" — it was filed in the platform repo only because that is where its spec half lived. This is the consumer half of a contract-first split, and consumer halves belong in the consuming repo.

⚠️ Three pieces of cross-repo machinery were rewritten in this move — check them if the unlock scan behaves oddly:

1. Blocked-by: is now the full cross-repo form (objectstack-ai/objectstack#7253) so this repo's unlock scan can resolve it. It was a bare #7253 and would have resolved to the wrong repo's #7253 after the move — that is the single most dangerous thing about transferring a blocked card, and it is why the line is rewritten rather than copied.
2. pm:blocking did not carry over. The original had it, meaning open downstream dependents exist. That label is a cache derived by the triage sweep from the Blocked-by: reverse index, not hand-maintained — ⛔ so I have not hand-hung it here. It should reappear on the next sweep if dependents still point at this work. Flagging because until then, this card's unlock fan-out is under-counted in priority ordering.
3. Step 4 below lands in objectstack, not here — see the scope note at the end.

Original thread has 2 comments; read them there.

Follow-up consumer card for objectstack-ai/objectstack#4848 (spec half landed by the claude/issue-4848-runaction-contract PR).

What the spec half now declares

ObjectNavItemSchema.runAction (optional): an object nav item declares the action to auto-run once on arrival at the object's list surface. The reference is validated (defineStack cross-reference walk + validate-action-name-refs, error severity, did-you-mean). runAction + recordId is parse-rejected. Ledgered planned + authorWarn until a shell consumes the declared slot.

What objectui needs to do

1. NavigationRenderer / shell: when an object nav item carries runAction, land on the list surface and auto-run the declared action once (same semantics EnvironmentListToolbar.tsx's useAutoRunCreate gives the raw ?runAction= query param today — consume-once, autoTrigger the matching toolbar action).
2. CloudOnboardingNext.tsx: stop hand-concatenating ${envsRoute}?runAction=create_environment; drive the deep link from declared metadata via the slot.
3. Decide whether the URL query param remains the wire encoding of the declared slot (likely yes — the slot then owns the param name in ONE place) and pin the param name pair-wise (the transitional hardening objectstack-ai/objectstack#4848's 2026-08-06 on-hold comment suggested: concatenation side and consumer side asserting the same constant).
4. After landing: flip the framework liveness ledger row app.json → apps.navigation.children.runAction from planned/authorWarn to live with a NavigationRenderer evidence pointer.

⛔ Transitional guard — do not remove it early

cloud#1048's comment + pin test (cloud welcome.page.test.ts) keeps guarding the cloud-owned names (ENVIRONMENTS_ROUTE, create_environment) until this lands. Do not remove it before this card is done.

⚠️ Scope note added on move: step 4 is not in this repo

The liveness-ledger flip is a framework-side action — the ledger lives in objectstack. So this card cannot fully close itself here. When the objectui work lands, the ledger flip goes back to objectstack as a follow-up (or rides a framework PR), and this card should say so in its closing comment rather than silently leaving a planned row behind. That row is the mechanism by which the platform knows the slot is inert; leaving it stale re-creates the declared-but-unread shape this whole contract was built to close.

Refs: objectstack-ai/objectstack#4848 (ruling comment 5203605940), cloud#844, cloud#1048.

[os-support-ai]

Unlock scan (objectstack-wide triage seat, fire ~19:47Z 2026-08-18): the rewritten cross-repo blocker objectstack-ai/objectstack#7253 is a MERGED spec PR (2026-08-10, pre-GA), so the declared runAction slot exists upstream. pm:blocked → pm:queue.

Premise-first for the dispatching seat/dev: verify the installed @objectstack/spec (17.0.0 GA pin) actually carries ObjectNavItemSchema.runAction before coding — merged 08-10 predates the GA publish, so it is expected present, but verify rather than inherit; if absent, report premise_still_valid: false and re-block on the next pin bump. Also per the retired framework card's work list: the framework liveness ledger row flip (planned/authorWarn → live with a NavigationRenderer evidence pointer) lands framework-side — when this card's PR is accepted, the accepting seat files that follow-up in objectstack with a Blocked-by: back-link, per the cross-repo follow-up rule.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 17
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5216-nav-runaction-slot
Worktree: objectui-issue-5216
Domain: repo:objectui (execution seat)
File surface: the navigation consumer that today reads the private ?runAction= string convention, plus whatever declares/forwards the nav item. The card names it by behaviour — locating it is your first deliverable; declare the exact file list in your report. ⛔ OUT: packages/components/src/renderers/complex/data-table.tsx + packages/plugin-dashboard/** (#5120, PR5353 in review), packages/plugin-grid/src/ObjectGrid.tsx (#5349 filed, not dispatched — leave it alone).
Container & model: M, mode:subagent, model: opus.
Clause-②: no, on the consumption side — you are consuming a slot the spec already declares, and retiring a private string convention. Nothing widens. ⚠️ If your measurement says the declared slot cannot carry what the private convention carried, that is a fork — stop and report, do not extend the spec from here.
Serial constraints cleared: packages/layout + packages/i18n were freed this round (PR5346 merged); packages/app-shell's layout subtree was touched by PR5339 and PR5346 — rebase on current main and re-read before you plan.

⛔ ZONE 0 — a hard premise gate. Do this before writing a single line.

The unlock scan says the blocker objectstack-ai/objectstack#7253 is a merged spec PR (2026-08-10, pre-GA), so the declared runAction slot is expected to be in the 17.0.0 pin. Expected is not measured. Verify against the installed package:

node --input-type=module -e "import {ObjectNavItemSchema} from '@objectstack/spec/ui';
 console.log(Object.keys(ObjectNavItemSchema.shape ?? {}).includes('runAction'))"

(adjust the import path/symbol to whatever the nav item schema is actually exported as — finding it is part of the check).

• Present ⇒ proceed.
• Absent ⇒ STOP. Report premise_still_valid: false and say so plainly; ⛔ do not work around it by declaring the key objectui-side.

⚠️ Counter-probe the answer either way — probe a key you know that schema has, through the same call. A probe that returns false because the import path was wrong looks identical to a probe that returns false because the key is missing. That exact trap voided two readings on #5042 this week (once node_modules was absent so probe and control were empty; once the filename was view.ts instead of view.zod.ts).

Why I am this insistent: two cards this round were stopped by precisely this gap — merged upstream ≠ published ≠ pinned here, three distinct states. GanttConfigSchema.viewMode (#5074) and ListMapConfigSchema (#5042) are both merged on objectstack main and both invisible to this repo, because they landed after the 17.0.0 GA cut and the changeset backlog is unreleased. Both now sit behind #5328. Your card's blocker merged before the cut, which is why it is expected to be fine — but that is an argument, not a reading. If it turns out absent, this card joins #5328 and I will re-block it.

The work, once the gate passes

Consume the declared runAction slot and retire the private ?runAction=<name> string convention. The point is the same one this repo keeps relearning: a private convention that no schema declares is a second de-facto contract, invisible to every gate — and here the spec has already published the real one, so the convention is pure debt.

• Report what the private convention could express that the declared slot cannot, if anything. That is the fork condition; if the answer is "nothing", say so with the evidence.
• ⛔ Do not leave a compatibility shim that keeps reading ?runAction= "just in case" unless you can name a producer that still emits it — and if you can, that producer is the real work, not the shim.

Cross-repo follow-up — file it, don't just mention it

Per the unlock scan and the cross-repo rule: when this lands, the framework's liveness ledger row flips (planned/authorWarn → live, with a NavigationRenderer evidence pointer) on the objectstack side. That follow-up is filed in objectstack-ai/objectstack with a Blocked-by: back-link to this card. I will file it when I accept the PR — you do not need to, but say in your report whether your implementation actually gives that row its evidence pointer, and where.

Tests

• A nav item declaring runAction runs that action on navigation.
• The private ?runAction= string no longer drives anything — this is the retirement; it must fail before your edit.
• An undefined action name behaves as the spec says (the upstream schema already rejects a runAction naming an undefined action — defineStack throws "deep-link references action '…' (via runAction)"; check what the client should do and pin it).
• Nothing else in the nav path regresses — packages/layout's NavigationRenderer just had its dead label resolvers removed (PR5346); read that change before touching the file.

Reverse-verify: restore the consumer, keep the tests, predict which go red before running, report predicted vs observed. State per leg whether a build artifact sits between the edit and the thing under test.

Gates

Derive from your diff (scripts/pm/dispatch-gates.mjs is objectstack-only). Run vitest from the repo root — the reason is not that package-scoped runs are refused (17 packages own a standalone vitest.config.ts and are not refused) but that a package-scoped run uses a different config than CI does. If you add user-visible copy, expect check:i18n-keys / check:i18n-drift and all ten locale packs. Changeset per check-changeset-presence.mjs's verdict; patch or minor, ⛔ never major.

⛔ Do not background a long check and end your turn. ⛔ No exhaustive paginated API sweeps.

Deliver

Draft PR against main, first body line Fixes #5216. Put the Zone 0 probe's output in the PR body — it is the reason the card was dispatchable. Push the branch early. Return the JSON report and post it as a comment whose first line is the literal <!-- os-dev-report --> marker.

---

Generated by Claude Code

[os-support-ai]

{
 "issue": 5216,
 "status": "done",
 "branch": "claude/issue-5216-nav-runaction-slot",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5354",
 "premise_still_valid": true,
 "summary": "ZONE 0 PASSED, measured not inherited: installed @objectstack/spec 17.0.0 exports ObjectNavItemSchema from '@objectstack/spec/ui' and its shape carries runAction=true; counter-probes through the same import discriminate (recordId=true, objectName=true, zzNotAKey=false), so the true is a reading, not a wrong-import artefact. Implemented the declared slot end to end. types: NavigationItem.runAction derived from the spec's object-nav variant (#3177 pattern), AND declared in objectui's own nav Zod schema, which strips unknown keys, so before this an entry carrying a deep link validated clean through `objectui validate` with the deep link discarded (objectstack#4115 class). layout: NAV_RUN_ACTION_PARAM is the param name's one definition, sited with resolveHref (its only writer); resolveHref encodes the slot onto the LIST landings only. app-shell: useNavRunAction is the single read-once/consume-once implementation; the deep link is now honoured on EVERY object list, not just sys_environment; urlParams registers the name by re-export so the reserved-param collision check is complete without a second spelling; CloudOnboardingNext stops hand-concatenating. FORK CONDITION: none. What the private convention could express that the declared slot cannot is NOTHING on the nav path -- measured, it was produced in exactly one file and consumed in exactly one, comparing a bare literal against a hard-coded create_environment, i.e. a single-value private protocol between two files, strictly LESS expressive than the slot. The one real gap is that the welcome CTA is not a nav item (page widget, route from page metadata), which is not a fork: the slot contributes the param name and encoding, and the widget now takes both from it while sourcing the action NAME from its own declared page metadata (properties.createAction, default create_environment, the name cloud's transitional pin test guards). One contract, two declared producers. Clause-2 honoured: nothing widened, no spec change. No compatibility shim, and none is warranted -- no producer outside this repo emits the string (cloud supplies the bare environmentsRoute and the query was concatenated here), so producer and consumer both moved in this PR. TWO MEASUREMENTS THAT CONTRADICT THE CARD, both reported in the PR body: (1) the installed 17.0.0 pin ACCEPTS runAction together with recordId -- the parse-level exclusivity the card describes is NOT in this pin. I checked the local objectstack checkout: the superRefine DOES exist on objectstack main (packages/spec/src/ui/app.zod.ts, 'runAction cannot be combined with recordId'), so this is the same merged-but-unpublished state as #5074/#5042, not a defect -- nothing filed. It made my list-surface-only precedence load-bearing rather than defensive, and my independent verdict matches the spec's own. (2) runAction: '' parses ACCEPTED, hence empty-string-is-absent handling. Cloud's transitional guard is untouched, as instructed.",
 "tests": "All at f1eb6dafe, vitest run FROM THE REPO ROOT (never package-scoped -- CI's config). Union after the final commit: `pnpm exec vitest run --maxWorkers=2 packages/layout/ packages/types/ packages/app-shell/src/__tests__/ packages/app-shell/src/hooks/ packages/app-shell/src/environment/ packages/app-shell/src/console/home/ packages/app-shell/src/urlParams.test.ts packages/app-shell/src/views/ packages/core/src/actions/` -> 'Test Files 407 passed (407) / Tests 4299 passed | 1 skipped (4300)', exit 0. type-check on types+layout+app-shell: all three 'Done', EXIT=0. eslint on the 11 changed files: 0 errors (209 pre-existing no-explicit-any/react-refresh warnings). Gates derived from the diff (dispatch-gates.mjs is objectstack-only): check:control-bytes OK (4752 files), check:self-import OK, check:esm-specifiers OK, check:phantom-deps OK (confirms app-shell may import @object-ui/layout), check:spec-symbols OK, check-changeset-presence OK (1 changeset for 11 src files of 3 released packages), check-changeset-no-major OK. Manual control-byte grep over all 12 touched files: clean. NEW TESTS: 33 across 3 files (resolveHref.runAction.test.ts, useNavRunAction.test.tsx, navRunAction.privateConventionRetired.test.ts). ARTIFACT POSITION, per leg: NO build artifact sits between the edit and any vitest leg -- vitest.config.mts aliases @object-ui/layout, /types and /app-shell to src (verified at lines 245-282), so an ablation here cannot go falsely green off a stale dist. The type-check leg DOES read dist/*.d.ts; I built the dependency closure (`pnpm --workspace-concurrency=2 --filter '@object-ui/app-shell^...' build`) BEFORE judging anything, and confirmed the rebuilt artifact carries the new export (packages/layout/dist/NavigationRenderer.d.ts:218 'export declare const NAV_RUN_ACTION_PARAM = \"runAction\"'), so the green typecheck is not cache. REVERSE-VERIFICATION, two legs, predicted BEFORE running, fix committed first so restoration had a real recovery point (no git stash, ever): LEG A -- revert only the withRunAction APPLICATION in resolveHref, keeping the constant exported so failures land as assertions rather than a blunt import error. Predicted 5 red in resolveHref.runAction.test.ts (the four positive encodings plus the unresolved-recordId-template fallback), absence cases green, other two files green. OBSERVED exactly that: 'Tests 5 failed | 28 passed (33)', and the 5 named failures are the 5 predicted. LEG B -- restore EnvironmentListToolbar.tsx + CloudOnboardingNext.tsx to origin/main. Predicted 4 red in the retirement pin (2 of the 4 it.each file cases plus the 2 named behaviour cases), with the ObjectView/hook it.each cases and all three 'one definition' cases green, and the EXISTING deep-link suites green. OBSERVED exactly that: 'Tests 4 failed | 134 passed (138)'. Leg B's second half is the load-bearing part: the pre-existing deep-link suites pass happily against the restored private convention, which is why they cannot be what retires it and why the source-scan pin is needed. Both legs restored via `git checkout <branch> -- <paths>`; tree confirmed clean at f1eb6dafe afterwards, and the union above was run at that restored state.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Liveness-ledger evidence pointer (asked for explicitly): yes, the implementation gives that row real evidence, and it is split across two files rather than the single NavigationRenderer pointer the card anticipated:

• producer — packages/layout/src/NavigationRenderer.tsx: NAV_RUN_ACTION_PARAM (the param name's one definition) and withRunAction, applied inside resolveHref's object branch on the list landings only.
• consumer — packages/app-shell/src/hooks/useNavRunAction.ts, wired generically at packages/app-shell/src/views/ObjectView.tsx (every object list) and, with the extra entitlement gate, at packages/app-shell/src/environment/EnvironmentListToolbar.tsx.

A NavigationRenderer-only pointer would overstate it in one direction and understate it in the other: NavigationRenderer writes the deep link but never runs anything, and the thing that makes the row genuinely live — an actual shell consuming the declared slot — lives in app-shell. Worth carrying both into the objectstack follow-up.

---

Generated by Claude Code