@llblab/pi-kit 0.38.4 → 0.39.0

package/node_modules/@llblab/pi-actors/docs/output-projection-map.md

@@ -0,0 +1,130 @@
+# Runtime Output Projection Map
+
+Status: F1.1 source ownership audit, updated for the F1.2 helper and F1.3a1 compact launch migration on candidate `16a3417` and the retained working tree. This map is not production migration, live UI/native acceptance or default activation proof. The [AX contract](agent-experience.md#document-envelope-and-yaml-syntax) owns the adopted format; [BACKLOG.md](../BACKLOG.md) alone owns remaining work. Line references are navigation anchors for this audited source, not permanent identities.
+
+## Reading the Map
+
+- **Runtime metadata:** Target is native block YAML, bare when there is no separately selected body. A body-bearing document has `---` above/below its metadata, followed by unchanged selected text/Markdown. Tool synchrony does not choose framing.
+- **Selected content:** Actor reports, stdout/stderr excerpts, literal requested sources and opaque advice/diagnostics are not objects to parse and reserialize. Preserve their existing selection/privacy/clipping basis; do not promise recovery of discarded upstream bytes.
+- **Machine data:** SDK/Recipe inputs, `details`, canonical journals, inventories, fingerprints and helper protocols keep their machine formats. A runtime-generated readable view of those facts is a separate YAML projection.
+- **UI chrome:** Selection, columns, stripes, modal choices, animation and paging are not serialization formats. Owned metadata documents are in scope; changing their appearance must preserve their native UI behavior.
+
+```text
+JSON arguments -> SDK/context/admission/execution owners
+  -> selected facts/details -> owned tool text -> host tool result
+  -> selected producer text -------------------> opaque body
+
+Terminal observation -> frozen completion/attention capture
+  -> budgeted text + compiler frame/hints -> Pi delivery
+  -> stored acceptance/recovery + compact/expanded renderer
+```
+
+## Public Tool Surfaces
+
+### 1. Host Adaptation and Shared Text Primitives
+
+- **Owners:** `index.ts:12` delegates composition; `lib/extension-runtime.ts:131` `withCurrentThinkingContext` prepares context, then applies response spacing at `:152–154`. Core/runtime tools register at `:164–167` and `:270`.
+- **Current:** `lib/tools-response.ts:83` `formatMarkdownField` and `:90` `formatInspectNextAction` produce list-key pseudo-records for unmigrated consumers; `:95` `formatLiteralBlock` dynamically fences literals. `:178` `jsonText` and `:318` `maybeJsonText` select generated pretty JSON for readable verbose output. `:17` `renderYamlMetadata` uses the declared `yaml@2.9.0` public API and now serves compact asynchronous launch receipts. It prefers plain safe keys, with library scalar-node quoting for BOM-bearing keys; other runtime consumers remain unmigrated.
+- **Transition boundary:** These helpers have mixed consumers, including retained completion codecs. Do not replace all calls or serialize arbitrary `content` in `spaceToolResult` (`:144`). That wrapper adds spacing and preserves other content/details; `spaceToolError` (`:164`) retains its existing Error/primitive behavior. The target requires one visual blank line after host invocation/arguments for every result/error, without changing selected body text or echoing inputs. Current exactly-one-leading-LF helpers prove their wired text convention, not full rendered/host coverage. Context-preparation failures can precede the catch; host `isError` handling is downstream.
+- **Proof owners:** `tests/tools-response.test.ts` covers closed hints, opaque values, immutable inputs, whole locations, old handoff and spacing; installed owner replay is in `tests/installed.scripts.test.ts:2492,2597–2620`. Emitter and compact-launch properties prove native types, selected observations, whole-row fitting and prefix spacing; full host UI and codec migration remain separate. The installed owner replay now requires all 18 response tests, not the former eight. Its 49,152-byte/64-level execution ceilings need caller-specific reconciliation; atomic key enumeration and arbitrary Proxy execution are not bounded by its scalar/node preflight.
+
+### 2. Spawn and Registered Asynchronous Launch Receipts
+
+- **Owners:** `lib/tools-spawn.ts:124` `createSpawnToolDefinition.execute` selects `maybeJsonText(details, verbose, compactAsyncRunStatus(details))` at `:222`. `lib/tools-local.ts:146` `createRuntimeToolDefinition` uses the same compact launch projection in its async branch (`:236–279`).
+- **Current:** `tools-response.ts:243` `compactAsyncRunStatus` now emits bare block YAML through the shared emitter, with native `launchModelPolicy` (`:205`) groups, nested `run_files` and a separate owned observation label. One original JSON selection of navigation becomes native nodes; original hooks/errors and unchanged details stay distinct. Exactly one leading LF belongs to host invocation spacing. Spawn verbose still selects full pretty JSON without the compact limit; the registered async invocation has no equivalent invocation-level verbose switch.
+- **Target / guard:** Compact launch facts, provenance, actual reuse and complete navigation are now **bare YAML**; full spawn-verbose migration is separately open. A launch receipt is not the future Actor result. Preserve 16 KiB whole-field/row omission, unavailable catalog facts and optional hint suppression only when the complete direct row is available. `tools-access.ts:19` owns session-bound navigation; formatting must not reread/adopt files or disclose non-enumerable catalog causes. `writeSpawnDraftRecipe` persists JSON input/source and is not a text-projection conversion.
+- **Proof owners:** `tests/tools-response.test.ts` launch/type/observer/whole-row/16-KiB boundary families; `tests/tools.test.ts` launch/schema/delegation/policy families; installed dist owner replay and packed retirement's direct-location witness. SDK launch parsing/assertions are updated in completion-boundary/session-navigation fixtures without changing old completion parsing or cleanup. Fresh full source/packed SDK and loaded-host acceptance remain later gates, not inferred from earlier literal-JSON witnesses.
+
+### 3. Synchronous Registered Output and Local Usage/Launch Errors
+
+- **Owners:** `tools-spawn.ts:86` `spawnGuardText` / `:106` `runIdFromTarget`; `tools-local.ts:69` `formatRuntimeToolUsageHint`, `:128` `formatRuntimeToolArgumentError`, and execute's `dispatchEntered` cutoff. `lib/execution.ts:1081` `executeRegisteredTool` returns selected `formatted.text` plus machine details at `:1142`.
+- **Current:** Local guards are pseudo-fields; usage guidance mixes prose, JSON call examples and argument lists. `lib/execution-output.ts:91` `formatOutput` and `:112` `formatFailureOutput` own stdout/stderr trim/tail selection, runtime labels and truncation notices.
+- **Target / guard:** Owned guard/guidance facts become YAML. Actual JSON invocation examples remain instructional source; selected command/report JSON remains content. If separately selected body text is present, use a delimited header without changing existing source selection. Do not claim current formatted tails are original complete stdout. After executor entry/async handoff, the local catch preserves its original failure rather than treating wording as a repairable argument error. Host schema/clone/coercion errors may occur before facade guards.
+- **Proof owners:** `tests/tools-spawn.test.ts`, `tests/tools-local.test.ts`, `tests/tools.test.ts:304`, `tests/execution-output.test.ts`; packed dispatch-failure preservation at installed `:2656`.
+
+### 4. Control Receipts and Public Failures
+
+- **Owners:** `lib/tools-message.ts:23` `controlGuardText`, `:66` `compactControlResult`, `:120` `createControlToolDefinition`; conservative actor-local failure catch at `:224`, replacement-state withholding at `:246–248`, verbose JSON at `:258`.
+- **Current:** Pseudo-fields distinguish request, delivery, handling, legacy kill attempt/closure uncertainty and one selected next action. Verbose text is JSON of request/result, also retained separately as machine `details`; exact cause chains stay private.
+- **Target / guard:** Metadata-only receipts/refusals become bare YAML, including native option sequences and nested verbose facts. Preserve whole identity/option bounds and existing caller facts. No private causes, inferred correlation, automatic retry, new recipient lease or no-effects/closure claim follows. Kill/archive/prune/dependency failures remain separately owned and may follow effects.
+- **Proof owners:** `tests/tools-message.test.ts` guard/host/refusal/privacy/context-change families; `tests/runs-control-delivery.test.ts` and awaited-Control cases in `tests/async-runs.test.ts`. YAML migration does not resolve those authority/transport gates.
+
+### 5. Inspect: Compact, Verbose and Schema
+
+- **Owners:** `lib/tools-inspect.ts:188` `compactRuntime`, `:201` `formatInspectFailure`, `:508` `inspectRun`, `:597` `inspectTool`, `:637` `compactResult`, execute at `:728`; `tools-response.ts:436` `formatInspectionHint` / `:443` `compactRecipeRegistry`.
+- **Current:** Compact paths use pseudo-fields. **Every verbose view and `tool:* view=schema` even without verbose** selects generated pretty JSON. Compact Run views supply a run/view header, not a newly available body/status snapshot. Recipe/source hints and authored advice have distinct typed versus opaque paths.
+- **Target / guard:** Runtime-generated compact/verbose/JSON-Schema presentation becomes YAML. Underlying `tool.parameters` JSON Schema and machine details do not change. `view=schema` is generated definition metadata, not the literal-source-file exception. Preserve filtering/redaction, partiality, exact portable sources and selected next actions; no new read, default snapshot or timing route is authorized.
+- **Proof owners:** `tests/tools-inspect.test.ts` refusals, schemas, views, privacy, current-session navigation and failed-priority families; installed inspection contracts at `:2492`.
+
+### 6. Registration, Listing, Deletion and Draft Promotion
+
+- **Owners:** `lib/tools-register.ts:61` delegates to Registry. `lib/registry.ts:94` `registryListText`, `:176` `registrationReceiptText`, `:352` `draftReceiptText`, `:501` `registryDeletionText` and their list/promote/delete/register transaction callers.
+- **Current:** Pseudo-fields and real selected sequences for tool/result/source/callability, args/warnings/names/coverage; source references may be fenced literals. Draft promotion has its own selected/coerced display facts. Delete has a manual reload note.
+- **Target / guard:** Metadata-only returns become bare YAML. Preserve actual persistence versus current callability, reuse of selected values, warning priority, whole-group omissions and source references. Do not normalize old flags into stronger activation truth. Formatting/notifier/unlink/reactivation failures may follow writes; a reload instruction is not permission to reload.
+- **Proof owners:** `tests/registry.test.ts` ordinary/draft/list/delete/activation-order families; `tests/registration-truth.test.ts` and installed registry/runtime owner replay.
+
+### 7. Registry Refusals and Transaction Diagnostics
+
+- **Owners:** `registry.ts` `assertRegisterToolInputModes` (`:776`), `reservedRegistrationNameText` / `executeRegisterToolUnlocked` (`:827,:840`), `duplicateRegistrationText` (`:374`), `assertTemplateIsNotNestedRecipe` / `getInputTemplate` (`:588,:606`), `normalizeDefaults` / `buildAuthoredRecipe` (`:653,:702`). Selected error formatters are `draftPathFailureText`, `sourceNormalizationFailureText`, `candidateAdmissionFailureText`, `draftRecipeFailureText`, `registrationTransactionFailureText` (`:315,:279,:254,:384,:231`).
+- **Current → target:** Locally selected pseudo-record facts become bare YAML, with opaque selected advice/reasons/diagnostics and complete or explicitly omitted source literals. This is not a global exception wrapper.
+- **Guard / proof:** Preserve guard/getter/String/join/Error order, existing diagnostic clipping, source-mode/duplicate predicates, cleanup and post-effect faults. A joined legacy diagnostic/summary is not a newly complete list; do not parse it into one or add raw causes/body/value echoes. Exact cases live in `tests/registry.test.ts` source/defaults/template/path/diagnostic/transaction groups; runtime/source/dependency failures retain their own owners.
+
+### 8. Registry, Callback, Watcher and Teardown Notices
+
+- **Owners:** `registry.ts:224` `registryNoticeText`; `lib/runtime.ts:96` `notify`, `:189` `formatRecipeToolWarnings`, `:336` `createRecipeToolReloadWatcher`. Runtime callback/steer diagnostics are in `run-ui-runtime.ts:49,151,335,400,692`; watcher/retirement notices in `observability.ts:254,1007,1016`.
+- **Current → target:** Owned pseudo-record reports/category sequences/counts become bare YAML when metadata-only; selected diagnostics stay opaque. Keep the actual `ctx.ui.notify`/forwarding owner: runtime's notifier is `hasUI`-gated, but the reload watcher has direct notify sites. Progress/chrome is separate below.
+- **Guard / proof:** Do not add a model-output cap to uncapped UI text, expose raw causes, change callback/rearm/dedup or read new error properties. Retirement notification is inside the stop path, so notifier failure can follow effects. Steer UI preview versus persisted error bounds remain separate. `tests/runtime.test.ts`, `tests/registry.test.ts:74,113`, callback/teardown cases in `tests/run-ui-runtime.test.ts`, watcher/retirement cases in `tests/observability.test.ts` own these boundaries.
+
+## Captured Delivery and UI
+
+F1.6 source-audit correction: Pi 1.0 native custom-message storage, session reconstruction and pre-provider context hooks preserve `details`. `convertToLlm` drops both details and customType afterward; it does not replace stored native entries. Current stripped-details tests deliberately simulate degradation, not a normal storage defect. Minimal content correlation still preserves that supported fallback; it is not needed for the model to perform kernel acceptance. Native content-block arrays alone also do not establish independent renderer fallback.
+
+### 9. Terminal Observation and Frozen Completion Text
+
+- **Owners:** `observability.ts` `terminalSemanticResult`, `observeRun`, `readyRunCompletions`, `collectRunCompletionBatchMembers` (`:577,:627,:1460,:1485`) → `run-ui-runtime.ts:313` `admitCompletionTransitions` → `run-delivery.ts:893,898` admission/capture and `:2033` `retainSharedCompletionTexts`.
+- **Current:** Private source/generation-bound members freeze selected primary/final-response text, diagnostics or separately labeled legacy fallback and a captured layout/budget. This private capture is not a public YAML document.
+- **Target / guard:** Only metadata serialization changes. Do not merge source classes, substitute raw stdout after loss, create primary kind for fallback or reread sources during rendering. Current-session locations are observed/rechecked before journal mutation. Preserve frozen equal shares, unchanged source fences and exact replay.
+- **Proof owners:** `tests/run-ui-runtime.test.ts:935–988`, `tests/run-delivery.test.ts` primary/diagnostic/artifact binding families, `tests/runs-context-exports.test.ts` source loss/replay. S1 numbering and native/clock work remain independent.
+
+### 10. Completion Projection, Compiler Frame and Native Renderer
+
+- **Owners:** `run-delivery.ts:1510` `completionRecordRow`, `:1683` `assembleFrontmatter`, `:1886` `projectCompletionRecords`, `:2110` `projectRunCompletionBatchPresentation`, `:2233` `readRunCompletionPresentation`, `:2283` retained projection, `:2328` message formatting. `run-ui-runtime.ts:68` `registerRunCompletionRenderer` is wired at `extension-runtime.ts:122`.
+- **Current:** Headers contain flow-JSON `references`/`run_files`; raw bodies and separate cut/uncertainty markers follow. Omission/inventory service text still uses pseudo-records/JSON. HTML compiler frames/closed completion markers and `details.pi_actors_presentation` bind ranges/hashes. Valid compact views render compiler text separately from native Markdown bodies; expansion/invalid hints expose original text.
+- **Prepared wire core:** `run-delivery.ts` `encodeCompletionYamlCarrier` / `readCompletionYamlCarrier` provide the accepted pure/nondefault mechanics; the prototype encodes and typed native view decodes them. Working source now also has a partial, unverified private candidate capture/layout route and strict-core Pi correlation. Default capture still uses `frontmatter_v2`; compiled/SDK integration and candidate acceptance are not established. They encode one `_completion` packet ID/codec and relative body/marker lengths, then derive dense ranges while decoding. Canonical bare headers are independent YAML fragments separated by codec-owned blank lines, not one mapping or a standard YAML multi-document stream; body-present headers are delimited and raw parts remain opaque. All-omitted is bare service metadata, not a fake Run. Empty selected bodies are distinct from absent bodies; empty-marker-only wrappers are refused. Input uses named top-level result keys with explicit depth/work bounds; fresh source admission and carrier acceptance remain F1.6v-gated, and meaningful service warnings must not be hidden wholesale.
+- **Prepared source projection (nondefault):** `projectRunCompletionYamlPrototype` projects current AX/frontmatter selected snapshots through one shared private fitter; it returns content, a format/digest-only hint and fitting facts, not a newly admitted or relabeled Batch. Frozen budgets/prefixes remain immutable. Canonical header/raw-part costs are measured additively, with unsupported data distinct from byte overflow; final content must agree with the unchanged core encoder/decoder. This prototype API remains data-only and source-class restricted. The partial private captured-layout route reuses internal YAML assembly rather than relabeling an old frozen snapshot; its independent quota/inventory, replay and epoch evidence is still incomplete. Native renderer support is prepared below; actual carrier acceptance remains a separate gate.
+- **Prepared native view (nondefault):** `readRunCompletionPresentation` derives frozen typed segments from the strict core and exact minimal format/digest hint; the registered renderer hides whole decoded reference/location nodes, retains every service fact and renders each body as independent native Markdown with literal Text metadata/markers. Valid-core missing/invalid hints and declared-new malformed content expose original full Text; expansion keeps that same source. Malformed content without a safely readable own new-format declaration retains historical dispatch, not a body-scanning heuristic. Headless widths/padding and old-history preservation are proved. Repo SDK 1.0.0's public `CustomMessageComponent` falls back to one Markdown component when a renderer is absent, returns undefined or throws, joining text-block arrays; a fresh component probe confirms this boundary, not session/interactive dispatch. Preserve that fallback unchanged: full content supplied to Markdown is neither independent-body rendering nor literal-visibility proof. Independent Markdown belongs only to the validated registered compact branch; registered degraded/expanded views keep original Text. Actual source-admitted native storage/context/provider/reopen and loaded terminal/phone behavior remain separate acceptance.
+- **Selected-source bridge preservation:** A collector-supported legacy artifact declaration containing a lone UTF-16 surrogate is accepted and escaped by the old codec but refused by the pure YAML core; validator support does not assert that its target exists. The private bridge must preserve such known string-valued metadata slots as an explicit `utf16_code_units` mapping of four-hex-digit units, without U+FFFD repair, reference deletion, body encoding or machine/history mutation. Ordinary strings stay strings. Source-family probes reached depth eight and an exact 49,152-byte equal-share packet; these are representative witnesses, not universal compatibility proof. Pure projection/fitting precedes native renderer dispatch. One private optimizer distinguishes unsupported data from byte overflow; no public selector or newly budgeted Batch mislabeled as an old layout. Meaningful service warnings remain visible, and final output must satisfy the unchanged core's whole-packet contract.
+- **Concrete coupling:** `readFrontmatterFrame` (`run-delivery.ts:1628`) validates single-line fields/values and complete ordered coverage. The retained compact branch in `run-ui-runtime.ts` hides only single `references: ` / `run_files: ` lines; the new typed-segment branch handles whole decoded nodes. A serializer-only switch to nested YAML breaks validation or exposes orphaned reference children. Header parsing, whole-node hiding, fitting, hint/frame generation and source/body rendering must move together for new captures.
+- **Target / guard:** Block-YAML metadata with body-dependent delimiters; opaque independent body blocks and exact omission markers. Keep old codecs/bytes/hints, 48 KiB/64 shown/256 captured limits and whole references. The F1.6 necessity audit supports deleting fresh prefix hashes and duplicate coordinate/range tables, not moving the whole payload. The target carries one packet identity and minimal relative opaque-body/marker segments in YAML; absolute ranges are derived. Full admitted-source compatibility and actual carrier acceptance remain unproved, so the current HTML reader/producer are not removed in place. `completionInventoryText` (`:434`) remains machine JSON.
+- **Proof owners:** `tests/run-delivery.test.ts` YAML/body injection, scalar/CRLF/Unicode cuts, historical fingerprints, compiler hints, whole omissions/inventory; `tests/run-ui-runtime.test.ts:728,783`; `tests/pi.test.ts` stripped/forged/malformed-frame cases. The pure codec/projection and native-view groups prove prepared nested YAML and headless rendering; retained Pi/default groups do not prove fresh-carrier admission or loaded-host behavior.
+
+### 11. Pi Delivery and Acceptance/Recovery
+
+- **Owners:** `lib/pi.ts:53` `createRunCompletionBatchEntry`, `:73` `sendRunCompletionBatch`, `:128` `completionBatchMessage`, `:160` context deduplication, `:268` session evidence; `session-evidence.ts:159` bounded active entries. `run-ui-runtime.ts` `reconcileCompletionBatch`, `flushCompletionBatch`, `onTurnEnd` and `projectContext` own reconcile/flush/turn-end/context delivery.
+- **Current:** `pi-actors-run-batch` content and private correlation/presentation details pass through active boundary proposals or idle follow-up send. Details take precedence; stripped-details recovery uses closed content correlation or retained headers, not body equality. Bounded parent-chain evidence distinguishes present/absent/conflict/unknown.
+- **Guard / proof:** A proposed entry is not acceptance; unknown/conflicting delivery cannot authorize resend, ACK or reallocation. Do not replace content framing with an assumed hidden-details channel. Successful delivery stays silent. `tests/pi.test.ts`, `tests/session-evidence.test.ts`, run-ui active-boundary/restart/recovery/send-failure families and installed source/packed SDK fixtures own the integration. No alternate carrier or loaded-client proof was run here.
+
+### 12. Notify, Followup and Urgent Steer
+
+- **Owners:** `observability.ts:197` `deliverRunAttentionNotifications`, `:1326` `formatRunAttentionMessage`, `:1342,1365` AX checkpoint/path formatting, `:1374` `formatRunSteerMessage`; `run-ui-runtime.ts:247,400` steer admission/flush; `run-delivery.ts:1064` durable steer admission; `pi.ts:39,83` sink/send.
+- **Current:** Pseudo-record run/checkpoint/body fields plus JSON-literal paths in fenced groups. Notify reaches UI; followup also sends `pi-actors-run-trace` with `display:false`. Urgent delivery freezes content before `pi-actors-run-steer`/`deliverAs:steer`.
+- **Target / guard:** Owned metadata becomes YAML; separately selected text stays outside a delimited header, metadata-only events remain bare YAML. Legacy non-string event bodies need source classification before conversion. Preserve saved steer content verbatim, first-eight reference coverage, startup priming/order/seen IDs and existing distinct ordinary/16 KiB steer bounds. No inferred private tail count or source-policy change.
+- **Proof owners:** Attention/reference/privacy cases in `tests/observability.test.ts`; ordering/bounds/recovery/saved-text cases in `tests/run-ui-runtime.test.ts`; durable steer cases in `tests/run-delivery.test.ts`; installed packed coordinator epochs.
+
+### 13. Inspector, Trace and Progress Chrome
+
+- **Owners:** `inspector-command.ts:13` command/UI entry; `inspector.ts:100,120,128` selected kill feedback and owner/generation action; `inspector-overlay.ts:411,467,490,640` kill/confirmation/popup recognition and `:743,804,826,896,919,935,945` list/detail/document projections. `trace-projection.ts:196,243,293` supplies observed Trace/Control/agent data; session privacy remains in `session-evidence.ts`. `observability.ts:935,947` → `run-ui-runtime.ts:504` owns animated status.
+- **Current:** Literal semantic documents use pseudo-records/nested sequences with ephemeral compiler-label provenance, selected text uses native wrapping, and popup coloring recognizes current anchored AX feedback. Trace previews retain existing normalization/160-unit selection and unknown-loss semantics. Stripes, ranks, paging, focus, animation and modal choice labels are UI chrome, not model serialization.
+- **Target / guard:** Owned document metadata is a YAML migration owner; do not interpret source lines as metadata or turn all chrome into YAML. Preserve original selected body/preview basis, columns/separators, safety/choices, frozen underlay and once-only generation action. A syntax change must update anchored feedback recognition without granting source labels meaning.
+- **Proof owners:** `tests/inspector.test.ts`, `tests/inspector-overlay.test.ts` documents/wrapping/Trace gaps/modal/safety families, `tests/trace-projection.test.ts`, session privacy and run-ui callback-animation tests. Headless/source tests do not prove actual terminal/phone rendering.
+
+## Explicit Exclusions and Capability Boundaries
+
+- **Private/unwired helpers:** `tools-response.ts:107` `renderRunSnapshot` has text/JSON render paths but no inspected production tool callsite. `compactRecipeImports` / `compactRecipeDoctor` and `observability.ts:1571` `formatRunTransitionMessage` likewise have no inspected production egress. This is a bounded callsite finding, not proof they can be deleted or public snapshot support is active.
+- **Helper JSON with real consumers:** `skills/music-player/scripts/playback.mjs:1406` `controlMain` emits status JSON at `:1428`; `skills/music-player/genapps/music-player.mjs:70` `readPlayback` parses that stdout at `:82`. YAML conversion there would break a machine consumer. The GenApp's `render` (`:147`) contains Telegram button transport markup at `:153`, not the pi-actors completion footer; never mass-strip HTML comments.
+- **Capability output versus kernel metadata:** `skills/project-work/scripts/project-utils.mjs:26,49` package/Skill summaries and `skills/actors/scripts/run-utils.mjs:96,137` reports emit JSON as capability stdout. `skills/project-work/recipes/package-summary.json` invokes that producer. If selected as Actor output, preserve it as content; changing a capability's own format requires its consumer/Skill contract, not a global runtime object serializer. Canonical status/checkpoint/socket/journal JSON and compiler/build diagnostics are not public YAML migration targets merely because they use `JSON.stringify`.
+- **Validation anchors:** Installed owner replay (`tests/installed.scripts.test.ts:2492`), packed steer/coordinator epochs (`:3498`), source/packed public spawn/primary/overflow (`:4446`, fixture `tests/fixtures/completion-boundary-sdk.mjs`), and playback/GenApp contract cases (`:3083`) identify existing proof owners. They were not rerun by the audit, and their existence does not prove a new YAML serializer, service carrier, native convergence or loaded UI.
+
+## Dependency Facts, Not a Second Work Plan
+
+Bare tool receipts can be addressed in their projection owners without redefining Run execution. Completion changes are coupled across byte fitting, frozen capture compatibility, nested-header validation, whole-node hiding, compiler ranges and stripped-details recovery. Service-carrier replacement has a further evidence gate. There is no safe global `JSON.stringify` or `formatMarkdownField` replacement: both cross metadata, source, historical replay and machine-data boundaries. Remaining implementation and acceptance are tracked only by F1 in `BACKLOG.md`.

package/node_modules/@llblab/pi-actors/docs/releasing.md

@@ -2,6 +2,23 @@
 
 Stable releases use one immutable tag workflow. The workflow runs normal product validation on Ubuntu, macOS, and Windows plus the dependency audit before any publication, publishes and verifies the exact npm package through Trusted Publisher, then creates or converges the GitHub Release from the matching changelog section. Architecture review uses the project-local Domain DAG Skill during architecture-affecting development; release automation does not run policy, line-count, source-style, or Domain DAG gates.
 
+## CI Trigger Boundary
+
+- **Ordinary branch push (`dev`, feature branches, or `main`):** No standalone validation or publication workflow. Updating an open PR emits its PR event, which owns the development checks.
+- **Pull request:** One validation workflow runs the complete Ubuntu/macOS/Windows product matrix and one Ubuntu dependency audit. A branch push must not start a second copy of these checks.
+- **Version-tag push (`v*.*.*`):** Only the release workflow starts. It invokes reusable validation once for the immutable tagged commit, then performs exact-tag/package preflight, npm publication/verification and GitHub Release convergence. This explicit pre-publication gate is retained; no standalone push-validation workflow runs alongside it.
+- **`workflow_call`:** Reuses the validation implementation for that release gate; it is not an independent push trigger. The release and PR paths share the same platform/audit contract, not copied job definitions.
+
+## Product Test Shards
+
+The adopted CI layout has three isolated test jobs on each supported OS: `installed` runs the heavy `installed.scripts.test.ts` package/SDK owner; `owners-a` and `owners-b` receive alternating entries from the sorted discovery of every other top-level `*.test.ts` file. New test files join automatically. The partition must be exhaustive and non-overlapping; do not split or filter assertions inside an owner, omit platform cases, or change fixture/SDK watchdogs.
+
+Each job uses a separate checkout and test-agent state, Node24 and the existing single-worker/preload flags. Package validation (types, Recipe QA, committed build parity and extension import) plus dry-pack runs once per OS on `installed`, not on every shard. Local `npm test` and `npm run validate` remain complete unsharded entrypoints. The reusable workflow must wait for all nine test jobs and the single dependency audit before release publication; one successful shard never substitutes for the full gate. This layout reduces aggregate critical-path pressure, not the cost or correctness obligations of an individual native test.
+
+Simple tools/registration fixtures bind original runner births and actual `close`, then validate canonical success and fresh ESRCH again at deletion. Their joint acceptance phase has one10-second watchdog, replacing the old approximately2-second result/exit polling assumption; this is a fixture allowance, not a product/SDK/workload deadline. Missing post-close results fail promptly; uncertainty retains roots without signals or automatic wait inflation.
+
+Implementation and native CI acceptance are tracked in BACKLOG until the complete sharded candidate passes.
+
 ## One-time npm Trusted Publisher setup
 
 Configure the existing public package `@llblab/pi-actors` on npmjs.com with a GitHub Actions Trusted Publisher using these exact values:
@@ -19,10 +36,10 @@ Do not create `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another long-lived npm publish
 
 1. Merge the validated release tree through the repository's guarded `dev` to `main` flow.
 2. Create one immutable `v<package.version>` tag on the verified `main` commit.
-3. Let `.github/workflows/release.yml` invoke the reusable `npm run validate` and dependency-audit workflow.
+3. Let `.github/workflows/release.yml` invoke the reusable complete product-validation and dependency-audit workflow.
 4. Let the publication job verify the tag commit, package manifests, and non-empty changelog section.
 5. Publish the exact public npm package through OIDC when the version does not exist.
 6. Verify npm version, `gitHead`, Pi extension/skill metadata, and packed runtime manifests.
 7. Create or update the GitHub Release only after npm verification succeeds.
 
-A rerun skips `npm publish` only when the exact existing version reports the same tagged `gitHead`; contradictory identity fails closed because npm versions are immutable. Registry lookup retries remain bounded. A missing or mismatched Trusted Publisher usually surfaces as npm authentication or not-found failure and must be corrected in npm package settings—never by adding a token fallback.
+A rerun skips `npm publish` only when the exact existing version reports the same tagged `gitHead`; contradictory identity fails closed because npm versions are immutable. After npm accepts publication, public metadata and the tarball may remain unavailable while the registry processes the package. Verification waits up to ten minutes, checks online metadata and tarball availability every ten seconds, and bounds each npm command by the remaining deadline. Exact version, `gitHead`, Pi metadata, or packed-manifest mismatches fail immediately once both registry reads succeed; availability retries never relax identity checks or repeat publication. A verification timeout leaves publication accepted but not yet verified: do not republish or move the tag. Wait for the exact public version and `gitHead`, then rerun the failed publication job so it skips the existing package and finishes GitHub Release convergence. A missing or mismatched Trusted Publisher usually surfaces as npm authentication or not-found failure and must be corrected in npm package settings—never by adding a token fallback.