Smithers Repository Maintenance

Smithers maintenance

Use the owning source and current docs on the revision being changed. The source CLI (makeCli() in packages/smithers/src/Cli.ts) is the CLI syntax contract; the installed release can be stale. The 1.0 CLI separates target graph commands (smthrs targets, show target, build|test|lint|docs|review|ci) from durable flow commands (smthrs flow list|plan|start, smthrs runs ...). A flow start receipt does not prove completion; inspect its run and action receipts.

• Graph or root files: read CONTRIBUTING.md, especially root-file and target-index generation. PACKAGE.ts declares targets; generated companions and the whole declaration-set index have explicit checks. Use pnpm run target-index when that contract calls for regeneration.
• Build/install/cache: read build, workspace remote caching, and cache trust. The install flow currently supports pnpm only; Bun can still run target tools. Install actions use expected filesystem boundaries and do not enter the shared engine cache. The target /ac cache differs from engine step-cache/artifacts; hosted and self-hosted cache implementations need matching route, bound, and credential behavior.
• Documentation: Author library documentation in each package's docs/ directory; it ships with the npm package. Run pnpm docs:check to verify tarball contents. Main-site projections use pnpm --filter @smithers/site run sync:docs.
• Benchmarks or performance claims: read scripts/bench/README.md. Distinguish the deterministic PR gate from scheduled observed timings, review candidate baselines, and retain methods and limitations with any claim.
• Evals: read the owning suite's README, including agent and seeded review. Keep offline deterministic gates and deliberate baseline updates separate from live model measurements and spending.
• Flows: read @smthrs/flow and CLI reference. A file flow at flows/<name>/flow.ts default-exports a tagged Flow.make from @smthrs/flow. Export its action implementations as the optional named layer (Declared.toLayer, AgentAction.layer, or Layer.mergeAll); the registry composes it against the local host platform and agent services. Export implementations directly; the host owns Action.Implementations. Acquire extra dependencies during layer construction so missing services are refused at load. Use stable Node.capture callbacks for canonical persisted composition and matching implementationVersion declarations/registrations for sealed idempotent actions. New authoring uses Effect Schema, not retired JSX/Zod task examples. A decision inside a flow (classify, filter, rank, route, yes/no over items) asks Jev through Classifier.make and the host Evaluator, as one request with one question per item, never through an LLM seat; see jev-check.
• Plans: read plan and plan-store. Node payloads are persisted as plaintext in node_json and approval cards without redaction; keep credentials out and resolve them at dispatch. Persisted plans are verified on write and read, and append uses an immutable-history compare-and-swap over the approved base and running prefix.
• Generated or untrusted flow declarations: read core planning rules. Graph.build executes bodies and planning callbacks with the caller's process authority; capability/effect metadata does not sandbox that code. Translate validated data into nodes with trusted code, or plan untrusted code in an externally isolated process.
• Runtime or persistence: read flows runtime, engine, and engine-store. @smthrs/flow declares behavior, the engine makes decisions, and the storage seam changes where state lives. Node and Bun use distinct native host/SQL adapters over the same SQLite migrations, journal, stores, cache, and recovery. Run migrations before SQL-backed services and use one writer for journal/state transitions; demonstrate cross-runtime recovery and cancellation. Browser bundling alone does not establish durable browser execution.
• Journal and ownership fencing: read journal and run-store. Ownership is arbitrated by the journal's injectable Consensus strategy (SqlConsensus over flows_consensus_leases by default, Consensus.layerLocal in-process); fenced durable emissions join its guard, so the run must be claimed and activated through it, and the journal and run store must share one strategy instance. RunStore mirrors the outcome on flows_runs, so a fixture that forges ownership in SQL writes both. emitDurableUnfenced is only for genuinely ownerless admission or repair, never a bypass for fence_lost. An expired lease alone does not authorize takeover; LivenessEvidence must be current, and an unknown probe counts as alive.
• Step cache migrations: read step-cache. The earlier 1.0 RC migration 2002 identity is accepted explicitly; preserve its ledger and cached results during upgrade. An unknown migration identity remains a failure, not a reason to delete a runtime database.
• Time travel: read time-travel before changing fork, rewind, or their receipts. A durable fork reuses completed prefix attempts by their original action identities and gives new work child-scoped keys; rewind archives future waits and refuses crossed irreversible effects or live descendants. Test recovery after an interrupted mutation.
• Sync: read sync before changing cursors, subscriptions, or gateway mounts. Persist applied cursor progress with consumer state; change feeds are hints and a re-list is authoritative. Preserve rewind generation handling: lineage_changed requires rebuilding the projection. Branch RPC code is not currently mounted by the gateway.
• Artifacts: read artifact storage. Its filesystem backend needs trusted host filesystem semantics; kernel-guarded filesystem access cannot substitute for them. Treat deletion as explicit and keep engine-store responsible for liveness/reachability.
• Browser host: read platform-browser. Its bash, filesystem, and jj views must share one volume; the tab uses the memory engine, and reload durability depends on the mount's sync(). Do not infer browser durability from a successful build or import.
• Bun host: read platform-bun before changing its filesystem or process adapters. Its trusted filesystem boundary runs the native smithers-jj-export helper (build with cargo build --locked --release -p smithers-ffi --bin smithers-jj-export or set an absolute SMITHERS_WORKSPACE_JJ_EXPORT_BINARY); PATH is never searched. Bun's host bundle is not the browser adapter.
• Node host: read platform-node before changing containment or process recovery. Confined operations require the smithers-jj-export helper built with the Rust toolchain rust-toolchain.toml pins; a missing helper refuses them. ProcessLedger.layerMemory cannot recover escaped children after a host crash, and permission checks belong around the host service bundle.