Skip to content

refactor(reasons): declare the R3 apple-runner reasons in ReasonTable rows - #4922

Merged
thymikee merged 8 commits into
mainfrom
t3/apple-runner-error-reasons
Nov 22, 2026
Merged

thymikee merged 8 commits into
mainfrom
t3/apple-runner-error-reasons

Conversation

@thymikee

@thymikee thymikee commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Summary

R3, part 1 of 2: packages/apple-runner. Part 2, packages/platform-apple and the macOS helper, is #4924.

  • 13 tables, 41 rows, owned by apple runner or prepare. Each sits beside its classifier: the 13 runner code→reason mappings (RUNNER_ERROR_CODES rows read RUNNER_ERROR_REASONS), the startup-failure vocabulary, the lost reply, and the launch, cache, budget, transport, product, sequence, and session refusals. keyboard_dismiss_unavailable stays for R7.
  • Published-value change: wrapPrepareHealthFailure published reason: appErr.message and overwrote any typed reason. It now publishes prepare_rebuilt_runner_unhealthy. The message moves to rebuiltFailureMessage and the inner reason to rebuiltFailureReason.
  • RunnerCommand and its wire types move to the types-only runner-command-types.ts, which keeps runner-contract.ts under the 1,000-line cap.
  • chore(gates): the two runner reason-docs guards now read the tables.

Value

base 4075dd1 head
R89 untyped values / sites 266 / 352 249 / 334
Reason tables / rows 20 / 74 33 / 115

Before / after

prepare ios-runner fails after the cached runner and its rebuild both fail the health check:

  • before: details.reason: "Runner health timed out"
  • after: details.reason: "prepare_rebuilt_runner_unhealthy", details.rebuiltFailureMessage: "Runner health timed out"

Every other value keeps its spelling byte for byte.

Validation

At head 494f7bb, these pass: typecheck, lint, check:layering, check:fallow, check:runner-error-codes (Swift unchanged), generate:reasons, the apple-runner tests (988), and both runner reason-docs guards. The base Coverage run failed only on those two guards. CI owns the full gate.

🤖 Generated with Claude Code

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Size Report

Metric Base Current Diff
Installed (including dependencies) 6.50 MB 6.50 MB +3.2 kB
Package (unpacked) 6.50 MB 6.50 MB +3.2 kB
Package (download) 1.98 MB 1.98 MB +809 B

Startup median (7 runs, lower is better):

Scenario Base Current Diff
CLI --version 17.0 ms 17.0 ms +0.0 ms
CLI --help 38.5 ms 35.8 ms -2.7 ms

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 2 new findings on ca33ea9. The verdict and the full list are in the summary comment.

@thymikee

Copy link
Copy Markdown
Member Author

Fixed the Fallow audit failure at 910dfe29d7: readTableReasons in runner-refusal-reason-docs.test.ts was over the cognitive-complexity limit, so its two cases (object member, table row) are now separate helpers with the same checks. The audit also warns that runner-startup-reason-docs.test.ts went from 3 test cases to 1. That is intended: the two removed cases tested the hand-written array parser this PR deletes, and parsing is now done by scripts/reasons/collect.ts, whose own tests (test/repo-guards/reason-tables.test.ts) cover rows it cannot read.

thymikee and others added 3 commits November 21, 2026 20:10
Every `details.reason` the Apple runner host publishes now reads a ReasonTable row owned by
`apple runner` (or `prepare`) beside the code that classifies it: the 13 runner code mappings in
RUNNER_ERROR_CODES, the startup-failure vocabulary, the lost reply, and the launch, cache, budget,
transport, product, sequence, and session refusals.

`wrapPrepareHealthFailure` published the error message as the reason and overwrote any typed
reason. It now publishes `prepare_rebuilt_runner_unhealthy`, with the message in
`rebuiltFailureMessage` and the inner reason in `rebuiltFailureReason`.

The RunnerCommand wire types move to runner-command-types.ts so runner-contract.ts stays under the
file-line cap; the module is types only, so no import closure changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RUNNER_STARTUP_FAILURE_REASONS is now a ReasonTable, so the startup-reason docs guard reads it with
collectReasonTables, the reader the error reasons page uses, instead of its own array parser.
RUNNER_ERROR_CODES rows now read `RUNNER_ERROR_REASONS.member.reason`, so the refusal-docs guard
resolves that reference to the row in the same file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee
thymikee force-pushed the t3/apple-runner-error-reasons branch from 910dfe2 to c332f7b Compare November 21, 2026 19:11
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The code in c332f7b is ready. The renames keep every published reason spelling unchanged, and the only new value is the declared prepare_rebuilt_runner_unhealthy reason on the prepare failure path.

CI shows all 22 checks passing at this commit, so nothing else must happen before merge. Not verified here: typecheck, tests, generate:reasons and the guards were not run locally, and the ReasonTable owner union including prepare was confirmed only through the passing typecheck in CI. No live device run was needed, since no dispatch, capture or lifecycle behavior changes.

Not blocking, and fine to take or leave: the rebuilt-health failure in runner-lifecycle-prepare-artifact.test.ts has no typed reason, so the rebuiltFailureReason branch in runner-lifecycle.ts is never exercised; the row comment and generated error-reasons.md name rebuiltFailureMessage but not rebuiltFailureReason; and runner-contract.ts both imports and re-exports the four moved types, which leaves two spellings of one symbol in the package.

The two earlier inline threads no longer apply at this commit, so they can be resolved: #4922 (comment) (the startup reasons test now reads the tables through collectReasonTables) and #4922 (comment) (the refusal reasons test now resolves TABLE.member.reason, with a fixture for R.busy.reason).

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 21, 2026
…-reasons

* origin/main:
  docs(commands): generate blocks for every public command and halve hand-written prose (#4919)
  fix(depgraph): budget the blast-radius query, not the whole-tree scan (#4920)
  refactor: remove dead exports and stale fallow exemptions (#4931)
  refactor(reasons): declare the R6a reasons in ReasonTable rows (#4938)

# Conflicts:
#	website/docs/docs/error-reasons.md
@apex-sentinel-staging

This comment has been minimized.

@thymikee thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee

Copy link
Copy Markdown
Member Author

The code at a0052db looks correct. The PR-owned code is identical to c332f7b, which the earlier clean review covered, and the merge changed nothing there. The two earlier resolved threads are benign for the same reason: #4922 (comment).

CI is green: 21 checks, none failing. Not verified here: generate:reasons was not rerun, because the exported tree had no node_modules. Page consistency rests on the CI guards. Please confirm that CI step passes on this head, or paste the generate:reasons output showing no diff. No other step is needed before merge.

Not blocking: RUNNER_PRODUCT_REPAIR_FAILURE_REASONS in https://github.com/callstack/agent-device/blob/a0052db/packages/apple-runner/src/runner-macos-products.ts#L14 repeats the two literals that RUNNER_MACOS_PRODUCT_REASONS now declares. You could initialize the Set from RUNNER_MACOS_PRODUCT_REASONS.productMissing.reason and .productRepairFailed.reason. This can be taken or left.

Could the legacy refusal-doc guard leave named ReasonTable row parsing with scripts/reasons/collect.ts, as the startup-doc guard already does, and use the shared memberPath helper to resolve each RUNNER_ERROR_CODES lookup against the collected rows? That would keep the wire-code mapping check in the guard and give the ReasonTable syntax one reader.

…ollector

Build the macOS product repair reasons from their reason rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

Head 9d6a695. On the previous head a0052db, pnpm generate:reasons left git status --porcelain empty, and the docs.yml check job (gate command-docs, which runs reason-tables.test.ts) was green. I also applied both suggestions. RUNNER_PRODUCT_REPAIR_FAILURE_REASONS now reads RUNNER_MACOS_PRODUCT_REASONS.productMissing.reason and .productRepairFailed.reason. The refusal-doc guard now reads its ReasonTable rows with collectReasonTables. It resolves each RUNNER_ERROR_CODES TABLE.member.reason lookup against the collected rows with memberPath, and it still accepts literal reasons. That removed objectMemberReason, rowReasons and readReferencedReason, plus the unused object kind and its fixtures (net -56 lines). Targeted vitest, tsc, oxlint, format and fallow audit are clean. CI is re-running on the new head.

@apex-sentinel-staging

This comment has been minimized.

@apex-sentinel-staging apex-sentinel-staging Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Apex Sentinel: 1 new finding on 9d6a695. The verdict and the full list are in the summary comment.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

This PR is ready at 23117ce. Both items from the earlier review (#4922 (comment)) are fixed: the Set is now built from the table rows, and the guard reads them through collect.ts and memberPath. Not blocking, and fine to take or leave: the head extractor in test/repo-guards/runner-refusal-reason-docs.test.ts keeps only the first three segments of a table reference, so R.busy.reason.constructor.name would read as runner_busy while it evaluates to String. Requiring exactly three segments before resolving a reference, with a rejection fixture for a longer path, would close that gap. The current rows use exact references, and the wire output still satisfies R3.

The thread #4922 (comment) no longer applies: readRunnerCodeRow now asserts non-computed named rows and members, and the reject fixtures are present. Please resolve it.

All 21 checks pass. The PR has merge conflicts with main, and they must be resolved before merge. Not verified here: the guard tests, tsc and generate:reasons were not run locally, so this rests on the passing checks and a read of the diff.

…-reasons

* origin/main:
  refactor(reasons): declare the R5 provider reasons in ReasonTable rows (#4932)
  refactor(reasons): declare the platform-android reasons in ReasonTable rows (#4928)

# Conflicts:
#	website/docs/docs/error-reasons.md
@apex-sentinel-staging

This comment has been minimized.

@thymikee

Copy link
Copy Markdown
Member Author

The R3 apple-runner reason rows look correct at a20a328, and the earlier review at 23117ce still holds. Required evidence is satisfied. All 21 checks pass, and there are no conflicts. Not verified here: the docs and guard tests were not re-run locally (CI and the empty apple-runner delta were used instead), and the android and provider upstream rows were not diffed because they came from main. Nothing remains before merge.

Not blocking, and fine to take or leave: runner-error-classification.ts:355 repeats runner_forwarding_unavailable as both the rule label and the details.reason predicate, while the producer in runner-transport.ts:24 gets the same value from RUNNER_TRANSPORT_REASONS.forwardingUnavailable. The copies agree today, so this is only duplication. One shared row could feed the emitted reason, the predicate and the label.

Could the HTTP forwarding failure marker live in the existing RUNNER_EXCHANGE_REASONS table in runner-error-classification.ts, which already owns the policy for it and is already imported by runner-transport.ts?

… its rule and its producer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member Author

Adopted at 3fbf6c7166. runner_forwarding_unavailable is now a row in RUNNER_EXCHANGE_REASONS in runner-error-classification.ts. The classifier rule label, its details.reason predicate, and the producer in runner-transport.ts (which already imported from that module) all read that one row. The module-private RUNNER_TRANSPORT_REASONS table is gone. Local runs: pnpm typecheck passes; the apple-runner tests plus the reason-table and refusal-doc guards pass 991/991; the page is regenerated; oxlint is clean.

@apex-sentinel-staging

Copy link
Copy Markdown

Apex Sentinel · ✅ Approve · review of 3fbf6c7

Since the review of a20a328: 0 new · 0 still open · 0 no longer raised

No open findings.

Reviewed with this repository's own Sentinel configuration (d1ace8139eb2).

💬 Talking to Sentinel

In a finding's thread, reply with:

Command What it does
@apex-sentinel-staging note <context> Adds context; Sentinel re-checks the cited code
@apex-sentinel-staging pivot <why> Says the finding is wrong; Sentinel re-checks the cited code
@apex-sentinel-staging like Marks the finding as useful
@apex-sentinel-staging dislike <why> Marks it as not useful, so it is not raised again

On this conversation, comment @apex-sentinel-staging review to run a full review once again.

@thymikee

Copy link
Copy Markdown
Member Author

The code in 3fbf6c7 looks good, and the evidence gap from the earlier review is now closed. All 21 checks pass. No further changes are needed before merge. Not verified here: tests were not run locally; this review relies on the passing checks and the diff.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee
thymikee merged commit 7bd4395 into main Nov 22, 2026
21 checks passed
@thymikee
thymikee deleted the t3/apple-runner-error-reasons branch November 22, 2026 11:16
thymikee added a commit that referenced this pull request Nov 22, 2026
* origin/main:
  feat(contracts): allow third-party snapshot producers (#4905)
  refactor(reasons): declare the R3 apple-runner reasons in ReasonTable rows (#4922)
  refactor(reasons): declare the R4 reasons in ReasonTable rows (#4934)
  refactor(snapshot): one shared model for occluding system surfaces (#4956)

# Conflicts:
#	website/docs/docs/error-reasons.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant