@llblab/pi-actors 0.43.0 → 0.43.1

package/AGENTS.md

@@ -8,7 +8,7 @@
 - `CHANGELOG.md`: completed delivery history.
 - `docs/README.md`: documentation index.
 
-Keep these surfaces distinct and reconcile them after meaningful changes.
+Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
 
 ## Concept
 
@@ -48,15 +48,16 @@ Pi host
 - `recipes-references.ts`, `recipes-discovery.ts`, `recipe-control.ts`: Recipe resolution, imports, shadowing, and Control declarations.
 - `async-runs.ts`: lifecycle facade.
 - `runs-start.ts`, `runs-status.ts`, `runs-control.ts`, `runs-control-delivery.ts`, `runs-controls.ts`, `runs-trace.ts`, `runs-process.ts`, `runs-retention.ts`, `runs-parent-teardown.ts`: focused Run internals.
-- `execution-sessions.ts`, `trace-projection.ts`, `session-evidence.ts`: bounded/redacted execution and inspection evidence.
+- `execution-sessions.ts`, `trace-projection.ts`, `control-projection.ts`, `session-evidence.ts`: bounded/redacted execution and inspection evidence.
 - `tools-message.ts`: exact Control facade.
 - `tools-inspect.ts`: exact `run:<id>`, `runtime`, `recipes`, and `tool:<name>` inspection.
+- `runtime-identity.ts`, `runtime-triage.ts`: immutable package/schema identity and pure pending/stale Control classification.
 - `tools-spawn.ts`, `tools-register.ts`, `tools-local.ts`, `tools-response.ts`: Run creation, persistent capabilities, Recipe-backed tools, and compact results.
 - `inspector.ts`, `inspector-overlay.ts`, `inspector-command.ts`, `inspector-actions.ts`: actor-instance Recipe/Trace/Control projection, navigation, command wiring, and fenced actions. **Actor Inspector** remains the product and command name, not a separate domain.
 - `observability.ts`, `runtime-notifier.ts`, `run-ui-runtime.ts`: Trace attention, terminal reconciliation, and Pi follow-up delivery.
 - automatic draft/tool review domains: structurally redacted model review, journaled mutation, lineage, recovery, and explicit retry/reset safety.
 
-Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Recipes stay optional, composable, policy-light, and caller-configurable.
+Scripts remain self-contained when no non-script consumer justifies a TypeScript domain. Command-template script leaves infer `.js`/`.mjs` in order through Node, Bun, or `deno run` and `.sh` through Bash without shell evaluation. Helper-backed packaged Recipes self-locate their installed package root while explicit caller values remain authoritative. Recipes stay optional, composable, policy-light, and caller-configurable.
 
 ## Operating Principles
 
@@ -77,7 +78,7 @@ Canonical event:
 {"id":"…","ts":"…","kind":"…","summary":"…","data":{},"level":"info","attention":"notify"}
 ```
 
-Keep events bounded and free of addressing/routing fields. Use artifacts or execution captures for large evidence. `attention: "followup"` must remain rare and semantically justified.
+Keep events bounded and free of addressing/routing fields. Every first-party writer must call `appendRunTraceEvent`; it validates and size-checks inside the canonical token-owned mutation lock, then performs one append-only JSONL write. Never append `trace.jsonl` directly from scripts. Use artifacts or execution captures for large evidence. `attention: "followup"` must remain rare and semantically justified.
 
 ### Control
 
@@ -87,7 +88,9 @@ Public shape:
 {"target":"run:<id>","action":"…","input":{},"verbose":false}
 ```
 
-Persist Control before transport. Fence every record and endpoint with immutable `run_instance_id`; controlled services capture that generation at startup. Serialize atomic journal replacement through token-owned dead-process-reclaiming locks, and keep status transitions expected-state-fenced and monotonic when consumers complete before producer delivery evidence. FIFO and named pipe are transport details, not public concepts; constrain FIFO documents to the portable atomic-write bound, reject partial writes, and keep FIFO readers gap-free across writers. Revalidate owner, generation, state, and process identity under the lifecycle lock immediately before delivery.
+Admit only lowercase ASCII actions of at most 64 characters, serialized JSON input of at most 380 bytes, and complete newline-terminated wire records of at most 512 bytes on both FIFO and named pipe. Invalid envelopes remain outside the journal; persist every admitted Control before transport. Put larger data in a declared artifact/path and send only a bounded reference or instruction through Control. Fence every record and endpoint with immutable `run_instance_id`; controlled services capture that generation at startup. Serialize atomic journal replacement through token-owned dead-process-reclaiming locks, and keep status transitions expected-state-fenced and monotonic when consumers complete before producer delivery evidence. FIFO and named pipe are transport details, not public concepts; reject partial writes and keep FIFO readers gap-free across writers. Revalidate owner, generation, state, and process identity under the lifecycle lock immediately before delivery.
+
+Keep `controls.jsonl` raw and local for execution fidelity. Every model-facing and Actor Inspector Control surface must use the shared bounded `control-projection.ts` redaction before exposure; never attach a second raw copy in tool details.
 
 Runtime lifecycle and review actions remain runtime-owned.
 
@@ -115,7 +118,7 @@ Lifecycle operations fail closed when identity, ownership, or generation cannot
 
 ## Registry and Evolution
 
-`~/.pi/agent/recipes/*.json` is executable capability memory. Preserve filename identity, atomic writes, canonical per-path locks, explicit operator-gated changes, and transportability.
+`~/.pi/agent/recipes/*.json` is executable capability memory. Preserve filename identity, atomic writes, canonical per-path locks with atomic owner publication and non-blocking abandoned staging, explicit operator-gated changes, and transportability.
 
 Automatic review receives value-free structural projections, not executable content, paths, prose, canonical names, or secrets. Deterministic executors derive unchanged Recipes from trusted captures. Approved mutation must journal intent before mutation and roll forward safely after crashes.
 
@@ -134,5 +137,8 @@ When a deferred Run result gates the next step, wait for its terminal follow-up.
 - Keep published text portable: use `~`, `<repo>`, or relative paths.
 - Update `skills/actors/SKILL.md` when durable operating mechanics change.
 - Keep `skills/swarm/SKILL.md` focused on multi-agent methodology rather than kernel internals.
+- Recipe `description` is optional because discovery supplies stable fallback tool copy; packaged Recipe QA must report zero diagnostics and zero release-blocking warnings without component boilerplate.
 - Before release run build, full tests, preservation tests, Recipe QA, Domain DAG validation, ABCd context validation, line-count gates, and release gates.
+- `.github/workflows/release.yml` owns the immutable sequence reusable validation → npm Trusted Publisher publication/verification → GitHub Release convergence; follow [docs/releasing.md](docs/releasing.md).
+- Keep npm publication tokenless: use the exact npm Trusted Publisher binding and job-scoped OIDC permission, never a long-lived npm token or token fallback.
 - Until a stable version beyond `1.x`, prefer clean breaking simplification over compatibility aliases or renamed legacy abstractions.

package/BACKLOG.md

@@ -1,3 +1,191 @@
 # Project Backlog
 
-No open items.
+## 0.43.1 — Contract Closure
+
+**Base:** `0.43.0` at `0d6db30cd2e070c1d03ed1e60bef70538a3083c1`
+**Release type:** patch-level assurance and distribution closure
+**Release sentence:** the Run kernel is published, portable, redacted, and mechanically self-consistent.
+
+## Mission
+
+Close the concrete gaps exposed after the `0.43.0` Run-kernel migration without adding another orchestration layer or expanding the public model.
+
+The canonical model remains unchanged:
+
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
+
+The public lifecycle remains:
+
+```text
+spawn   create a Run
+message apply Control
+inspect read Recipe, Trace, or Control
+```
+
+`register_tool` remains the separate capability-memory surface.
+
+`0.43.1` succeeds when the same contract is true in source mode, installed-package mode, documentation, diagnostics, first-party controlled services, CI, GitHub Release, and npm distribution.
+
+## Hard Boundaries
+
+The release must preserve:
+
+- exactly the existing public Run nouns: `Recipe`, `Run`, `Trace`, and `Control`;
+- exactly the existing Run views: `recipe`, `trace`, and `control`;
+- exactly the existing management targets: `runtime`, `recipes`, and `tool:<name>`;
+- the stable public tool names `spawn`, `message`, `inspect`, and `register_tool`;
+- owner filtering, immutable `run_instance_id` fencing, canonical lifecycle locking, and process-identity verification;
+- shutdown and parent-teardown behavior;
+- terminal reconciliation and bounded follow-up context;
+- complete command captures, owned Pi-session evidence, redaction, path containment, and symlink rejection;
+- automatic Recipe review, immutable capture, CAS, journaled mutation, lineage, retry, reset, and recovery safety;
+- shell-free command-template execution;
+- the strict Domain DAG and removed-communication-surface gates.
+
+The release must not add:
+
+- actor chat, rooms, branches, peers, routing, mailboxes, inboxes, outboxes, or addressed envelopes under any name;
+- a task tree, planner hierarchy, decision registry, swarm scheduler, model router, or model-economics subsystem to the kernel;
+- new public targets, views, request fields, Trace fields, Control states, or Recipe keys;
+- a remote protocol, broker, workflow DSL, or general event bus;
+- compatibility aliases for removed `0.42` surfaces;
+- a long-lived npm token or third-party publish action;
+- new runtime dependencies unless an existing retained invariant cannot be closed otherwise.
+
+## Deferred Beyond This Release
+
+Do not absorb these future lines into `0.43.1`:
+
+- total Trace retention, rotation, or semantic compaction;
+- pending-Control admission backpressure and queue quotas;
+- outcome/cost aggregation for Recipe fitness;
+- automatic model selection or planner/worker economics;
+- task-tree or decision-ownership orchestration;
+- a generalized acknowledgement protocol for arbitrary controlled services.
+
+Those require separate evidence and belong to later releases.
+
+## Known Closure Gaps
+
+The executor must verify this observation against the current checkout before changing code:
+
+1. The repository-side Trusted Publisher path is prepared, but npm account binding and tagged publication proof remain external release preconditions.
+
+If the observation no longer holds, preserve the already-closed behavior and remove only the corresponding obsolete task. Do not reimplement solved work.
+
+---
+
+## P0 — Release and Contract Closure
+
+### CCL-02 — Activate npm Trusted Publisher and prove registry convergence
+
+**Goal:** make `pi install npm:@llblab/pi-actors` install the released Run kernel through the prepared tokenless, provenance-bearing path.
+
+**Status:** repository preparation is complete; npm account configuration and one tagged release proof remain externally gated.
+
+**External operator precondition:**
+
+- Configure the npm Trusted Publisher for package `@llblab/pi-actors` with owner `llblab`, repository `pi-actors`, workflow filename `release.yml`, and no environment unless both sides adopt the same reviewed environment name.
+- Do not add `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or another long-lived token fallback.
+- Remove any obsolete account-level automation tokens only after one Trusted Publisher release succeeds.
+
+**Release-time closure:**
+
+- The tagged workflow passes reusable validation, publishes or safely recognizes the exact npm version, verifies matching `gitHead` and packed Pi runtime manifests, then converges the GitHub Release.
+- `npm view @llblab/pi-actors@0.43.1 version` and npm `latest` resolve to `0.43.1`.
+- The GitHub Release and npm package identify the same tag commit.
+- The Pi package index may update asynchronously; observe it without unbounded polling or repository mutation.
+- If Trusted Publisher remains unconfigured or mismatched, report that exact external blocker and keep publication failed closed.
+
+**Dependencies:** npm account configuration and the final tagged release.
+
+---
+
+## P1 — Signal, Compression, and Integration Closure
+
+### CCL-12 — Close release evidence and publish `0.43.1`
+
+**Goal:** leave one internally consistent source tree, package, release, and empty future-work file.
+
+**Work:**
+
+- Reconcile implementation comments, README, `AGENTS.md`, `docs/`, Actors skill, fixtures, schemas, tests, and release notes.
+- Keep Swarm skill changes limited to kernel-interface corrections; do not expand orchestration methodology in this release.
+- Update package version and packaged skill metadata to `0.43.1` only after all implementation tasks close.
+- Move completed work into one concise `CHANGELOG.md` section with externally meaningful behavior and impact.
+- Reset `BACKLOG.md` to:
+
+  ```text
+  # Project Backlog
+
+  No open items.
+  ```
+
+- Run the final local boundary:
+
+  ```bash
+  npm ci
+  npm run test:preservation
+  npm run release:validate
+  npm run audit:dependencies
+  ```
+
+- Create tag `v0.43.1` only from the validated release commit.
+- Observe the gated workflow through successful validation, npm publication, npm verification, and GitHub Release publication.
+- Verify the final public package through npm, not only `npm pack --dry-run`.
+
+**Release closure:**
+
+- Ubuntu, macOS, Windows, and dependency-audit jobs succeed.
+- GitHub Release is published only after validation and npm verification.
+- npm exact version and `latest` both resolve to `0.43.1`.
+- The installed package reports `0.43.1`, exposes the same schemas as source, and contains no removed communication surface.
+- Recipe QA has zero diagnostics and zero baseline warnings.
+- Shipped lines remain below `28,853`.
+- No unresolved P0/P1 finding remains.
+- `BACKLOG.md` contains no completed work.
+
+**Dependencies:** all prior tasks and the npm Trusted Publisher external precondition.
+
+---
+
+## Dependency Order
+
+```text
+Released 0.43.0 baseline
+  └── CCL-02 → CCL-12
+```
+
+`CCL-02` may proceed in parallel with kernel fixes after the frozen released baseline, but no tag may be created until the complete graph closes.
+
+## Required Test Matrix
+
+At minimum, retain or add direct evidence for:
+
+| Boundary               | Required evidence                                                                         |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| Public Control request | exact fields, action length, serialized-input bound, removed-field rejection              |
+| Recipe Control         | same action grammar/length, duplicate and runtime-reserved rejection                      |
+| Control journal        | generation fencing, monotonic transitions, compaction, stale-lock recovery                |
+| Control projection     | recursive redaction in tool content/details, triage, and Actor Inspector                  |
+| Control transport      | exact complete-wire bound, FIFO atomicity, named-pipe parity, partial-write failure       |
+| Runtime status         | exact version in source and packed/dist modes                                             |
+| Runtime triage         | pending/stale distinction, delivered inclusion, age boundaries, owner/lifecycle filtering |
+| Trace append           | canonical validation, cross-process serialization, no malformed/lost/duplicate records    |
+| First-party services   | canonical Trace only, canonical Control claim/finalization, endpoint generation           |
+| Documentation          | canonical examples accepted by current schemas/dispatchers                                |
+| Recipe QA              | zero diagnostics and zero normalized warnings                                             |
+| Release                | validation-before-publication, OIDC-only npm publishing, rerun convergence                |
+| Compression            | strict shipped-line ratchet from `0.43.0`                                                 |
+| Installed package      | compiled entrypoint, skills, version, schemas, no stale files/source imports              |
+
+## Final Decision Rule
+
+Do not release because the code compiles or because the new abstractions look cleaner.
+
+Release only when this statement is supported end to end:
+
+> A user installing `@llblab/pi-actors@0.43.1` receives the same validated Run kernel described by the repository: every Run exposes one captured Recipe, one redacted causal Trace, and one portable generation-fenced Control boundary—without a communication plane and without distribution ambiguity.