@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.4

package/docs/guides/coordinate-two-processes.md

@@ -0,0 +1,120 @@
+---
+title: "Coordinate two processes over one store"
+description: "Share a wake bus so a resume does not wait for the next poll, let a follower learn of runs another engine created, and prove cross-process behavior in a test."
+sidebar:
+  order: 8
+---
+
+Two engines over one database do not share memory. Everything they know about
+each other comes from rows. This guide covers the three seams that make that
+practical: the wake bus that makes same-process resumes immediate, the catalog
+read that lets a follower see another engine's runs, and the test composition
+that gives you two real connections.
+
+## Share a wake bus inside one process
+
+Polling is the correct fallback and the slow path. `WakeBus` is an in-process,
+edge-triggered bus that shortens it:
+
+```ts
+import { WakeBus } from "@smthrs/engine-store"
+
+const bus = WakeBus.layer
+```
+
+An engine composition resolves the bus optionally. Provide this layer when your
+host has its own wake sources, an HTTP handler completing a deferred, say, so
+they and the engine share one bus. Provide nothing and the composition builds a
+private one.
+
+```ts
+import * as Effect from "effect/Effect"
+
+const complete = (executionId: string) =>
+  Effect.gen(function*() {
+    const wakeBus = yield* WakeBus.WakeBus
+    // ... make the durable write first, then announce it.
+    yield* wakeBus.wake(executionId)
+  })
+```
+
+Announce only after the durable write returns. A wake is not durable: with no
+waiters it is dropped, and the polling fallback covers the run. Registration is
+removed when a waiting fiber is interrupted, including scope closure and losing
+a race against the polling sleep, so an abandoned wait leaks nothing.
+
+`WakeBus.layerNoop()` drops every wake, which is what a test asserting the
+polling fallback provides. `waiters(executionId)` reports the current count, for
+tests and diagnostics: a count observed now says nothing about a moment later.
+
+Cross-process delivery stays store-driven. The other process learns from the
+row, not from the bus.
+
+## Let a follower learn of another engine's runs
+
+[`@smthrs/sync`](/api/smithers-sync) serves a workspace subscription over a
+`RunCatalog`, and its own implementations are static or in-process, so a
+follower composed against one sees the runs that existed when it started and
+never learns of another. `RunCatalogRead` is the durable read that fixes that:
+
+```ts
+import { RunCatalogRead } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const runs = Effect.gen(function*() {
+  const catalog = yield* RunCatalogRead.RunCatalogRead
+  return yield* catalog.listRunIds({ limit: 500 })
+})
+```
+
+`RunCatalogRead.layer` provides it and needs `SqlClient`. `listRunIds` returns
+the workspace's runs oldest first, bounded by `limit`, which defaults to
+`defaultLimit` of 10,000. A workspace with more runs than the bound is followed
+by its most recent ones; an older run stays readable through a run-scoped
+subscription, which names it directly.
+
+It reads a set rather than a cursor tail on purpose. Retention deletes runs, and
+a follower that only ever appended what appeared after a cursor would keep every
+collected run in its view forever and hold a journal stream open for each one.
+
+Nothing here polls. The interval belongs to `RunCatalog.makePolling` in
+[`@smthrs/sync`](/api/smithers-sync), so the durable side has no policy and no fiber of
+its own. `RunCatalogError` carries `invalid_options` (the limit was not a
+non-negative safe integer) or `list_failed`; on a failure the caller keeps
+whatever view it had, and the next read converges.
+
+## Prove cross-process behavior in a test
+
+Two independently constructed bundles pointed at one file is what a second
+process actually looks like: two connections, two engines, no shared object
+graph. `test/TestStores.layerAt(filename)` is built for exactly that:
+
+```ts
+import * as TestStores from "@smthrs/engine-store/test/TestStores"
+
+const first = TestStores.layerAt("./tmp/shared.db")
+const second = TestStores.layerAt("./tmp/shared.db")
+```
+
+`layerAt` re-exports the `SqlClient` connection alongside `DurableEngineState`,
+because the in-memory variant of that service is a map a second bundle would not
+see.
+
+Use a real file. `:memory:` gives each connection its own private database, so
+it cannot prove anything durable across compositions. `TestStores.layer` is the
+private in-memory bundle, which is right for a case that only needs one engine.
+
+## Give two engines two source ids
+
+Set a distinct `journalSource` per engine so their journal records are
+distinguishable, and a distinct `owner.hostId` when they genuinely represent
+different hosts. The `OwnerId` nonce already distinguishes incarnations, so two
+processes on one host may share a `hostId`.
+
+## Related
+
+- [Durable waits](../concepts/durable-waits.md): the wake, park, and sweep model
+  the bus accelerates.
+- [Test against a durable store](./testing.md): the rest of the test surface.
+- [Sync followers](/docs/guides/sync-followers/) on smithers.sh: the consumer
+  side of the catalog read.

package/docs/guides/defer-work-with-selection.md

@@ -0,0 +1,171 @@
+---
+title: "Defer work with selection beliefs"
+description: "Record suspected edges, let the scheduler postpone sink nodes a change probably does not affect, then repay that debt with a guess-free recertification pass."
+sidebar:
+  order: 9
+---
+
+Selection is the one advisory seam in this package. It guesses which sink nodes
+a change probably does not affect and postpones them, and it proposes flows a
+plan never reaches. It never changes a step key, a cache row, or a correctness
+decision, and the default admits everything.
+
+## The belief shape
+
+A `SuspectedEdge` says "changes matching this path pattern tend to affect this
+flow":
+
+```ts
+import { Selection } from "@smthrs/engine-store"
+
+const edge: Selection.SuspectedEdge = {
+  scope: "packages/ui/src/**",
+  affects: "flows/IntegrationTests",
+  confidence: 0.8,
+  validFromMs: 0,
+  evidence: ["run-42:seq-118"]
+}
+```
+
+`confidence` is in `[0, 1]` and is moved by outcomes, never by hand.
+`validFromMs` keeps the edge inert until a snapshot's `pinnedAtMs` reaches it.
+`evidence` references the journal facts the guess was learned from.
+
+A `BeliefSnapshot` pins the edge set at plan time, which is what keeps selection
+a pure function of data in hand: a belief updated mid-run cannot change what
+that run defers.
+
+## Persist and train the beliefs
+
+```ts
+import { SelectionStore } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const train = Effect.gen(function*() {
+  const store = yield* SelectionStore.SelectionStore
+  yield* store.upsert([edge])
+  const snapshot = yield* store.snapshot()
+  yield* store.train([{ scope: edge.scope, affects: edge.affects, outcome: "miss" }])
+  return snapshot
+})
+```
+
+`SelectionStore.layer` persists through this package's own migration set and
+needs `DurableWriter` and `SqlClient`.
+
+- `upsert(edges)` inserts or replaces by `(scope, affects)`. It refuses an
+  edge whose scope breaks the scope grammar with `invalid_input`.
+- `list()` returns every stored edge, and fails with `decode_failed` on a row
+  that no longer decodes, including a scope stored before the wildcard cap.
+- `snapshot()` returns a `BeliefSnapshot` pinned at the injected clock's current
+  time, never `Date.now()`.
+- `train(observations)` applies the asymmetric rule in one transaction: a hit
+  gains five percent of the remaining headroom, `confidence + 0.05 * (1 -
+  confidence)`; a miss halves, `confidence * 0.5`. Training only touches
+  matching stored edges, ignores unknown pairs rather than creating them, and
+  never writes journal records. At most `maxEvidenceEntries` (128) newest
+  evidence entries are retained per edge.
+
+`SelectionStoreError` distinguishes `invalid_input`, `decode_failed` for a
+corrupt row, and `persistence_failed`.
+
+## Wire selection into a scheduler run
+
+`PlanScheduler.Options.selection` carries the whole opt-in, and every field is
+optional because every default is inert:
+
+```ts
+const scheduler = PlanScheduler.layer({
+  runId: "plan-1",
+  owner,
+  sourceId: "planner",
+  selection: {
+    changed: ["packages/ui/src/Button.tsx"],
+    beliefs: snapshot,
+    policy: { deferBelow: 0.3 }
+  }
+})
+```
+
+`deferBelow` defaults to zero, which defers nothing. A sink whose best matched
+likelihood is strictly below the threshold is deferred; a likelihood exactly at
+the threshold is admitted. `full: true` is the run-level override: every verdict
+is treated as `Admit` and the override is journaled, the way a `--fresh` flag
+ignores the cache.
+
+## Choose a selector
+
+`Selection.layerNoop` admits everything, and is the behavioral default: a run
+under it is byte-identical to a run before the seam existed.
+
+`Selection.layerHeuristic` is pure glob matching over live edges, where live
+means `validFromMs <= pinnedAtMs`. A scope glob must match the whole path:
+`**` matches any run of characters including `/`, `*` matches a run within one
+segment, `?` matches one non-`/` character, and every other character is
+literal. A scope carries at most `Selection.maxScopeWildcards` (8) `*` or `**`
+tokens. Matching runs in time linear in the path and never backtracks. A matching edge supplies the likelihood, a
+sink can defer only when a live edge names it, and a `Candidate.stats` failure
+ratio raises the likelihood so flaky sinks stay inline. Stats alone never defer.
+
+`Selection.layer(service)` installs your own. A model-backed layer belongs
+elsewhere, because `@smthrs/engine-store` carries no model dependency.
+
+A selector returns one `Selected` per candidate carrying a `Verdict`:
+
+| Verdict   | Meaning                                                                                       |
+| --------- | --------------------------------------------------------------------------------------------- |
+| `Admit`   | Run the node normally.                                                                        |
+| `Defer`   | Postpone the sink; carries the `edge` and the `likelihood`.                                   |
+| `Propose` | Name a flow no real dependency reaches; carries the `flow`, the `edge`, and the `confidence`. |
+
+Only sink nodes, plan nodes nothing depends on, are offered as candidates.
+
+## Read and repay the debt
+
+A deferred node is journaled as `flows.engine.selection-deferred` and settles
+`deferred`. It never dispatched, wrote no cache row, and is never reported as
+passed.
+
+```ts
+const owed = Selection.debt("plan-1")
+```
+
+`debt(runId)` folds the journal: each `selection-deferred` record opens a debt
+under its plan key, and a later `node-settled` under the same key with `built`,
+`clean`, or `failed` closes it. A `skipped` settlement does not, because that
+work never ran. A `failed` one does, because the guess-free pass executed the
+work and surfaced the miss, which is the training signal.
+
+`debt(runId, { repaidBy })` widens only the close side, accepting matching
+settlements from explicitly named repaying runs. The fold never guesses which
+other runs were guess-free passes.
+
+`PlanScheduler.recertify({ plan, deferringRunId, options })` is the driver:
+it re-drives the compiled plan under the caller's fresh run id with the `full`
+selection override, then returns `{ runId, report, remaining }`, where
+`remaining` is the deferring run's debt computed with `repaidBy`. Repayment is a
+read-side join; the deferring run's journal is never rewritten.
+
+Scheduling the cadence, nightly or per merge, is a product concern. This is the
+primitive one pass runs.
+
+## Present it
+
+Three pure helpers render selection without any IO:
+
+- `Selection.risk({ changed, beliefs })` returns `{ level, reasons }`, where
+  level is `high` at confidence at or above 0.7, `medium` at or above 0.4, else
+  `low`, and each reason reads `<scope> -> <affects> (<confidence>)`. It is an
+  annotation, never a gate.
+- `Selection.card(input)` renders the plan card, one string per line: `clean`
+  renders as `cached`, `built` as `run`, a `deferred` row carries its fail
+  likelihood and the recertification cadence, and each proposal names the edge
+  that suggested it.
+- `Selection.proposeReadSet({ beliefs, flow, paths })` returns the workspace
+  paths live edges select for a flow, deduplicated in input order. It is the
+  feeder for a `boundaryMode: "expected"` declaration.
+
+## Related
+
+- [Drive a plan to completion](./drive-a-plan.md): where the `deferred` outcome
+  appears.

package/docs/guides/delete-old-run-history.md

@@ -0,0 +1,154 @@
+---
+title: "Delete old run history"
+description: "Run an explicit retention pass over finished runs: the age threshold, the dry run, the lineage guard that keeps a run a live one still needs, and what smthrs gc does."
+sidebar:
+  order: 5
+---
+
+Nothing in the durable stores forgets on its own. A finished run keeps its row,
+every attempt, every journal event, and every archived frame forever, and
+journal compaction is off by default, so the file only grows. That is the right
+default, because a run's history is the only account of what an agent did to a
+repository. Deleting it is an operator decision, taken explicitly.
+
+## Run a pass
+
+`Retention.retain` deletes up to `limit` aged terminal runs and their dependents
+in one transaction:
+
+```ts
+import { Retention } from "@smthrs/engine-store"
+import * as Effect from "effect/Effect"
+
+const collect = Effect.gen(function*() {
+  const retention = yield* Retention.Retention
+  return yield* retention.retain({
+    olderThanMs: 30 * 24 * 60 * 60 * 1000,
+    limit: 1000,
+    dryRun: true
+  })
+})
+```
+
+`Retention.layer` provides the service and needs `SqlClient` and
+[`@smthrs/journal`](/api/journal)'s `Journal`.
+
+`olderThanMs` is how long a run must have been finished, measured from
+`finished_at_ms` or from `created_at_ms` for a terminal row that never recorded
+one. Zero collects every terminal run; a negative value is read as zero.
+
+`limit` bounds one pass and defaults to `Retention.defaultLimit`, which is 1000.
+Retention is idempotent. For a fixed, finite, acyclic lineage and a positive
+integer limit, each successful non-dry pass removes at least one collectable
+run while any remain. This includes continuation chains longer
+than the bound. Selection prioritizes deeper continuation children before
+parents, then age and run id; the report lists selected runs oldest first.
+Parents pinned by children excluded by age or live lineage do not consume the
+bound. Protected runs remain until eligible. Zero or a negative limit deletes
+nothing.
+
+`dryRun` computes and reports the pass without deleting anything. Under a dry
+run the report names exactly the runs a real pass would remove, which is what
+makes it worth trusting.
+
+## Read the report
+
+`RetainReport` carries the `cutoffMs`, the `runIds` deleted oldest first, per
+table counts (`runs`, `attempts`, `clockDeadlines`, `deferredCompletions`,
+`journalEntries`, `journalCheckpoints`, `archiveEntries`,
+`timeTravelReceipts`), the `dryRun` flag, and two retention lists:
+
+- `retainedForLiveDescendants`: aged terminal runs left in place because a
+  descendant is not terminal, or is terminal and is not being deleted by this
+  pass.
+- `retainedForLiveAncestors`: aged terminal runs left in place because an
+  ancestor is not terminal. That ancestor can still read the run's settled
+  result through `agent/await`, which answers out of the run row.
+
+A run retained for both reasons is reported under `retainedForLiveDescendants`,
+and at most `limit` runs are reported, so the report costs no more than the
+pass.
+
+## Three properties make it safe on a live workspace
+
+**One transaction.** Every delete runs inside a single `journal.transact`, so a
+crash leaves either a run with all of its rows or none of them, never a run row
+whose history is gone or history whose run row is gone.
+
+**Terminal and aged only.** A run is a candidate only when its status is
+`completed`, `failed`, or `cancelled` and it finished before the cutoff. A
+`pending`, `running`, or `suspended` row belongs to work that can still resume,
+at any age.
+
+**Nothing a live run still needs.** A candidate is retained when a live run
+stands on either side of it in the lineage, over both relations that make one
+run the parent of another: the `flows_run_parents` edge a spawned child is
+recorded under, and the `parent_run_id` column the rounds of one trampoline
+lineage are chained through. The lineage filters run before the bound, which is
+what makes a bounded pass converge: otherwise a workspace whose oldest thousand
+aged runs all hang under one parked parent would fill the window with runs the
+pass then has to retain, pass after pass.
+
+Journal history is deleted outright rather than compacted to a checkpoint.
+`Journal.checkpoint` and `Journal.compact` are owner-fenced and require a
+`running` run under the exact owner, so neither can be called for a finished,
+ownerless run at all. Deleting is strictly stronger, and it happens in the same
+transaction as the run row.
+
+## Collect across both of a project's databases
+
+A project keeps its history in two files, the control plane's database and the
+engine's, and a sweep of one without the other leaves half of a deleted run
+behind. `Retention.collect` is the host-facing pass, taking the database as a
+service and running once per file:
+
+```ts
+import { Retention } from "@smthrs/engine-store"
+
+const pass = Retention.collect({
+  olderThanMs: Date.now() - 30 * 24 * 60 * 60 * 1000,
+  database: ".flows/engine.db",
+  dryRun: false
+})
+```
+
+Note the difference in units: `Service.retain` takes a duration, while
+`collect` takes an absolute epoch millisecond threshold. `collect` returns a
+`Retention.Report` with the `database` label, the threshold, the `runs`
+removed, `deleted` row counts per table (empty under a dry run), and the
+`dryRun` flag.
+
+`collect` reads eligibility and deletes inside one retryable write transaction.
+A concurrent attachment to a live parent cannot slip between that scan and
+deletion. If contention causes a retry, the pass recomputes its candidates.
+Dry runs read the same guard inside a transaction without modifying history
+or schema; their report is a snapshot, not a reservation for a later sweep.
+
+`collect` runs the same deletion and the same lineage guard as `retain`, so
+neither can hold a shorter table list than the other. It handles a database
+that composed fewer stores: the control plane's file migrates the run store and
+the journal and nothing else, so the guard drops the edge-table half of the walk
+there and keeps the `parent_run_id` half.
+
+`Retention.eligible(olderThanMs, limit?)` returns just the candidate run ids,
+for a tool that wants to show them before deleting anything.
+
+## The CLI already does this
+
+[`smthrs gc`](/cli/gc) is `collect` over a project's databases, with
+`--older-than` defaulting to 30 days and `--dry-run` available. It refuses
+`--older-than 0s`, because that is "delete all history" wearing the spelling of
+a retention policy. After retention it runs `ArtifactGc` over the engine's
+`.flows/objects` directory with the default 14-day grace, so blobs the deleted
+runs were the last to reference are collected too.
+
+Nothing schedules any of this. Automatic retention stays opt-in, for the same
+reason artifact collection does: deletion is the irreversible direction, and a
+human approving a plan must be approving the deletions.
+
+## Related
+
+- [Collect unreferenced artifacts](./collect-unreferenced-artifacts.md): the
+  blob half of reclaiming space.
+- [Retention](/docs/guides/retention/) on smithers.sh: the operator's
+  procedure.