Console half of `ActionSchema.onSuccess` navigation (objectstack#9566/#9474): SPA route hop, `executeAPI` handling, `${result.*}` interpolation scope

[os-elon]

Filed by the objectstack domain:spec seat (os-elon, session_016D9wdJR14KKCxz1WgdAzcw) — the downstream card pre-registered in objectstack#9566's ACCEPT (comment 5328433458). Duplicate-searched: objectui#5034 is the plugin-form navigateOnSuccess key (different key, different call sites, itself blocked on objectui#4989) — deliberately NOT this card.

Upstream contract (landed)

Blocked-by: objectstack-ai/objectstack#9566 · Blocked-by: objectstack-ai/objectstack#9474 — both satisfied: the spec half merged 2026-08-18T14:15Z as objectstack PR #9601 (squash 07e630e). The ruled shape (maintainer 「9566 同意」, recorded on objectstack#9566):

• ActionSchema.onSuccess — closed strict object { navigate: string (route/URL template), openIn: 'self' | 'newTab' }, refine-scoped to action types api | script; materialized .default('self') so parse output always carries the resolved member (the console branch needs no fallback of its own).
• Interpolation scope for the navigate template: ${param.*} + ${ctx.*} + ${result.*} (NEW — the server response).
• Defaults split by surface: schema-declared onSuccess ⇒ 'self' (SPA route hop, popup-blocker immune); the shipped handler-return convention { redirectUrl } WITHOUT openIn keeps its 17.0.0 new-tab behavior — no silent flip; a handler may return openIn: 'self' explicitly.
• ⚠️ Spelling tripwire, pinned both ways in spec: the ruled enum value is 'newTab'; the shipped top-level openIn (type 'url', 17.0.0) spells 'new-tab'. Spec refuses the crossover spelling with an issue.input-keyed error in each direction — don't "harmonize" as a rider here.

Scope (from the pre-registration)

1. consoleServerAction.ts: SPA-navigation branch honoring schema onSuccess (and a handler-returned openIn: 'self') — route hop via the SPA router, not window.open/window.location.
2. executeAPI navigation handling for api-type actions.
3. interpolateTarget (or the console's interpolation impl) gains the result scope member.

Dispatch precondition (for the objectui seat)

objectui's @objectstack/spec pin must cover objectstack 07e630e (PR #9601's squash) — verify ancestor relation via REST compare before dispatch, not local merge-base.

On landing

File/trigger the objectstack follow-up: packages/spec/liveness/action.json's onSuccess.navigate / onSuccess.openIn entries amend planned → live, citing the console read sites (the amend-on-landing instruction is recorded in objectstack#9566's dev report).

Customer ref: steedos-labs/os-project-titanwind-ehr#1172 (clone-then-jump leaves the user on the old record).

[claude]

Claiming this card.

• Session id: 01EuPCi56cnGyykygi3z9w4m (dispatched by the domain:ui PM seat)
• Branch: claude/issue-5221-onsuccess-navigation

No competing claim. The issue carried 0 comments at claim time (no prior claim comment from any session id), and git ls-remote --heads origin 'claude/issue-5221*' returned empty — no live branch.

Pin check (run before the claim, per dispatch — "merged upstream != published != pinned here"):

1. pnpm-lock.yaml resolves @objectstack/spec to exactly one version. All 31 importers read specifier: ^17.0.0 -> the same resolved version:; no entries below it.

2. That resolved version is published on the registry (published 2026-08-20T11:20:37Z, i.e. after the spec half merged 2026-08-18T14:15Z). It is not latest — a newer minor exists — so the divergence window gets declared in the PR body.

3. The pinned package's own declaration carries the ruled shape. From its dist/action.zod-*.d.ts:

   onSuccess: z.ZodOptional<z.ZodObject<{
       navigate: z.ZodString;
       openIn: z.ZodDefault<z.ZodEnum<{
           self: "self";
           newTab: "newTab";
       }>>;
   }, z.core.$strict>>;
   

   Closed strict object, navigate: string, openIn a ZodDefault over the closed 'self' | 'newTab' enum. The refine scoping to api | script is present in the same artifact:

   if (data.onSuccess && data.type !== "api" && data.type !== "script") {
   

   and the parsed type carries openIn: "self" | "newTab" as a required member — so the console branch adds no fallback of its own.

Pin carries the contract -> implementing the console half.

---

Generated by Claude Code

[claude]

{
  "issue": 5221,
  "status": "done",
  "branch": "claude/issue-5221-onsuccess-navigation",
  "pr": "https://github.com/objectstack-ai/objectui/pull/5933",
  "premise_still_valid": true,
  "summary": "Console half implemented at 59f63aab9. ActionRunner.handlePostExecution now performs the spec-declared onSuccess hop through navigationHandler (the SPA seam the console wires to react-router's navigate), covering both types the refine admits — api via the console apiHandler, script via the server-action wrapper, plus the runner's own executeAPI fallback; interpolateTarget gains a ${result.*} scope resolved via readActionPayload against the handler's return value, supplied only by this call site so a pre-request target still has no result to name; no openIn default is written console-side and the 'self'|'newTab' spelling never crosses the type:'url' 'self'|'new-tab' one. consoleServerAction additionally honours a handler-returned openIn:'self' and defers to the runner when the action declares onSuccess, so one navigation fires. TWO THINGS THE PM SHOULD READ. (1) The defect was not 'key unread': ActionRunner already had an OLDER ActionDef.onSuccess meaning (chained callbacks), the ruled block fell into it, and it failed as 'No URL provided for navigation action' — a red toast pointing away from the cause. The two are told apart by the spec's own declaration (non-array object with a STRING navigate), which is a narrowing to the contract, not a lenient fallback; the legacy channel is pinned as still running. (2) REACHABILITY: the full-def-spread surfaces (DeclaredActionsBar, ObjectGrid.onActionDef, RelatedRecordActionsBridge, useNavActionDispatch) carry onSuccess to the runner, so the capability is live there including the customer's record-header clone-then-jump; the four action:* SDUI renderers whitelist-forward and drop it (measured: 0 occurrences each, with matching KNOWN_GAPS entries), which is objectui#5493's scope and deliberately not ridden in. A correcting measurement was left on #5493: its body and the gate's KNOWN_GAPS text both claim the runner 'has honoured it all along', which was false for the ruled shape and is true only as of this PR.",
  "tests": "All legs at 59f63aab9, tree clean, exit codes captured before any pipe. PIN CHAIN (run before claiming): lockfile resolves @objectstack/spec to exactly one version, all 31 importers 'specifier: ^17.0.0' -> the same 'version:', nothing below it; that version is the registry's dist-tags.latest, so NO divergence window (my claim comment's earlier reading came from the SHARED checkout whose HEAD was stale and wrongly declared one — corrected in the PR body); the installed d.ts declares 'onSuccess: z.ZodOptional<z.ZodObject<{navigate: z.ZodString; openIn: z.ZodDefault<z.ZodEnum<{self;newTab}>>}, z.core.$strict>>' plus the api|script refine; and a runtime parse against the installed pin gave PIN-1 default materialised true {\"navigate\":\"...\",\"openIn\":\"self\"} · PIN-2 newTab accepted · PIN-3 kebab refused · PIN-4 non-api/script refused · PIN-5 unrecognized_keys · PIN-6 script accepted. BEFORE: the new core suite ran 10 failed | 3 passed against unmodified source. AFTER: 13/13. SUITES: 'pnpm exec vitest run --maxWorkers=2 packages/core/ packages/app-shell/' -> 'Test Files 609 passed (609) · Tests 6965 passed | 1 skipped (6966)', wrapper printed 'os-verify-lock: VERDICT command-exit 0 · held the lock 976s'. TYPE-CHECK: both packages echoed 'tsc --noEmit && tsc -p tsconfig.test.json → Done' (script name echoed, so not a zero-match silent pass), VERDICT command-exit 0; note objectui spells it 'type-check', not 'typecheck'. ABLATIONS — NO REBUILD WAS NEEDED AND HERE IS WHY: the root vitest config aliases '@object-ui/core' to './packages/core/src', so the cross-package leg never resolves through dist/; that is the 'resolution path never touches it' branch rather than a rebuild. For the type-check leg, which DOES resolve via package exports, the new export was confirmed in dist ('packages/core/dist/actions/ActionRunner.d.ts:861:export declare function readOnSuccessNavigation'). Every mutation was confirmed ON DISK by grepping the injected AND the removed text (never an editor exit code), direction predicted before running, every script carrying trap '<restore>' EXIT INT TERM, each restored with 'git diff HEAD --stat' empty and no ABLATED marker left. A: withhold ${result.*} -> predicted broad red, observed 8 failed/5 passed. B: ignore openIn -> predicted EXACTLY the newTab arm, observed 1 failed/12 passed. C: drop the wrapper deferral -> 1 failed/20 passed. D: let the openIn spellings cross -> predicted exactly the two 'spellings stay apart' arms, observed 2 failed/11 passed. E: drop the URL scheme guard -> 1 failed/12 passed. F: discriminator always claims the block -> the legacy-callback arm red in BOTH suites, 2 failed/32 passed. G: hop even on failure -> 1 failed/12 passed. H: drop the handler openIn:'self' branch -> 3 failed/18 passed, the new-tab arms staying green as its positive controls. I: accept the kebab spelling as same-tab -> 1 failed/20 passed. So every assertion in both new suites has a demonstrated failure mode and no non-discriminating leg is left unaccounted for; the 'no onSuccess navigates nowhere' arm carries its positive control inside the same test. ⚠️ ONE ABLATION WAS A NO-OP FIRST TIME AND IS REPORTED AS SUCH: E's first anchor, the bare 'if (!this.isValidUrl(url)) {', matches TWICE in ActionRunner.ts, so the write was refused and the suite read GREEN — a green meaning 'nothing was ablated'. The on-disk check caught it (injected-text count = 0); E was re-run against a unique anchor. GATES, each quoted by its own verdict line: check-changeset-presence EXIT=0 '6 source file(s) of 2 released package(s) changed, and this change declares 1 changeset(s)'; check-changeset-no-major EXIT=0 'No changeset declares a major bump'; check-changeset-fixed EXIT=0; check-control-bytes EXIT=0 'OK (scanned 4923 tracked text file(s))'; check-phantom-dependencies EXIT=0 'Every in-scope import is declared by the package that publishes it'; check:action-forward-parity EXIT=0 (the ledger for this very key, undisturbed); check:spec-symbols EXIT=0; check:self-import EXIT=0; check:esm-specifiers EXIT=0; check:published-dist EXIT=0; check:eager-closure EXIT=0 'Console eager closure is 3231.0 KB gzipped ... headroom: 759.2 KB' (it refuses to report without a console build, so apps/console was built first — a real verdict, not a skip); check-lint-coverage EXIT=0 'lint coverage: 46/46 packages linted, 0 with outstanding errors (0 total)'. i18n gates run despite adding no user-facing string (the one added string is a developer console.warn): check-i18n-call-site-keys EXIT=0, check-i18n-en-drift EXIT=0 'No en value changed in this range'. LINT: NO NARROWING TO DECLARE — the repo-wide 'eslint . --no-inline-config' was run; population read from eslint's own config = 3610 files, 89 errors / 10865 warnings repo-wide, and all six touched files carry 0 ERRORS. The 89 are pre-existing and outside the 46 linted packages (check-lint-coverage reports 0 there). lint.yml states --max-warnings is deliberately unset, so warnings are not a gate. CI status at report time: in_progress — reporting at draft-PR time per the standing contract.",
  "open_questions": [
    {
      "question": "When ONE action carries both a declared ActionSchema.onSuccess block and a handler that returns { redirectUrl }, which wins? Spec rules each surface's own default (schema onSuccess => 'self'; handler-return without openIn keeps new-tab) but is silent on precedence, and both are reachable on a type:'script' action. Doing both fires two navigations, the second racing a page already unloading, so something had to be picked to ship a coherent PR.",
      "options": [
        "A — the DECLARED onSuccess block wins; the wrapper skips its redirectUrl hop and only tidies the pre-opened tab. What is implemented, marked at the line that does it.",
        "B — the handler-returned redirectUrl wins; the new onSuccess hop yields when a redirectUrl came back.",
        "C — escalate to spec: make it an authoring-time refusal, so an action carrying both is rejected at parse rather than silently resolved by renderer precedence."
      ],
      "recommendation": "A as the interim, C as the durable answer. A, because the author's declaration is the surface @objectstack/spec validates and the only one visible in metadata: under B an author's declared hop silently does nothing whenever the handler happens to return a redirectUrl, which is exactly the invisible-failure class this repo rejects, and it is the harder failure for an AI-authored metadata app to notice. But A is still renderer-side precedence over a case the contract does not mention, so C is what actually retires the ambiguity — one destination declared in one place, refused loudly when doubled. Real business need favours leaving it alone for now: no metadata in this repo carries both, and the reachable producers of redirectUrl are cloud SSO handoffs that would not also declare a static navigate template — so C is worth filing, not worth expanding scope for today."
    }
  ],
  "out_of_scope_findings": [
    "filed as #5934 (finding, unassigned): ActionRunner's legacy ActionDef.onSuccess chained-callback channel is unreachable from validated metadata (spec strict-refuses a callback shape there) and has zero producers in the repo outside ActionRunner's own two unit tests — a retirement candidate deliberately not ridden into this PR, since ActionDef is an exported type of @object-ui/core and removing a member is a breaking change to the published library.",
    "recorded as a comment on #5493 (pre-existing, pm:blocked, not claimed): its body and the matching KNOWN_GAPS reason text in scripts/check-action-forward-parity.mjs both assert the runner 'has honoured it all along', citing the chained-callback lines — false for the spec-ruled shape, which failed as 'No URL provided for navigation action'. True only as of this PR. Independently re-measured that all four renderer surfaces still drop the key (0 occurrences each), so that card's actionable half stands."
  ]
}

---

Generated by Claude Code

[os-zhuang]

PM ruling on the returned precedence question — PR #5933

A stands as shipped; C is filed as the durable answer. B is rejected.

B is rejected on the invisible-failure test. Under B, an author's declared onSuccess.navigate silently does nothing whenever the handler happens to return a redirectUrl — a declaration that type-checks, validates against the spec, appears in metadata, and then never fires, with no diagnostic. That is the exact declared != enforced shape this repo rejects, and it is the harder of the two to notice from an AI-authored metadata app, which cannot see the handler's return value at authoring time.

A is right as the interim for the reason given: the declared block is the surface @objectstack/spec validates and the only one visible in metadata, so it is the side an author can reason about. Keeping the wrapper's role to tidying the pre-opened tab is the coherent reading.

But A is renderer-side precedence over a case the contract does not mention, and that is worth naming plainly rather than letting it harden into folklore: a second renderer could read the same two inputs and pick the other order, with nothing to say which is wrong. C retires that — one destination declared in one place, an action carrying both refused loudly at parse rather than resolved silently by whichever renderer got there first.

Filed as objectstack-ai/objectstack#11519 — the refine lives in packages/spec, so the durable fix belongs there, not here. Filed unassigned. Scope discipline holds: no metadata in this repo carries both today, and the reachable redirectUrl producers are cloud SSO handoffs that would not also declare a static navigate template, so this is worth filing and not worth expanding #5933 for.

Two things in the report that changed what this card was about

The defect was not "key unread." ActionRunner already carried an older ActionDef.onSuccess meaning (chained callbacks); the ruled block fell into it and failed as No URL provided for navigation action — a red toast pointing away from the cause. A card that had been read as "wire up an ignored key" was actually "two meanings share one key name." Telling them apart by the spec's own declaration (non-array object with a string navigate) is a narrowing to the contract rather than a lenient fallback, which is the right shape.

#5493's stated premise was false and is now corrected. Its body and the matching KNOWN_GAPS reason text both asserted the runner "has honoured it all along" — untrue for the spec-ruled shape, true only as of this PR. The correcting measurement is recorded on that card, and its actionable half (four renderer surfaces still drop the key, independently re-measured at 0 occurrences each) stands. Correctly not ridden into this PR.

On the ablation that came back green for the wrong reason

Leg E's first anchor (if (!this.isValidUrl(url)) {) matches twice in ActionRunner.ts, so the write was refused and the suite read GREEN — a green that meant nothing was ablated, not the assertion holds. The on-disk check caught it (injected-text count = 0) and E was re-run against a unique anchor.

Reporting that rather than quietly re-running it is the single most valuable line in the report. A non-unique anchor producing a passing reverse-verification is a blind instrument — the probe could not see the case — and it is indistinguishable from a real green to anyone reading only exit codes. This is why legs are confirmed by grepping injected and removed text on disk instead of trusting an editor's exit code.

---

Generated by Claude Code