@smthrs/journal 0.0.0-stage → 1.0.0-rc.3

package/CHANGELOG.md

@@ -0,0 +1,149 @@
+# @smthrs/journal
+
+## [Unreleased]
+
+### Fixed
+
+- A lossy batch the writer fails to commit is logged and counted on the new
+  `flows_journal_lost` counter (`JournalMetrics.lostEntries`, `lost(code)`),
+  so telemetry lost with no `flush` caller is no longer silent. A final flush
+  that fails while the journal closes is logged instead of ignored.
+- Migration `0003_startup_index` lives in `src/migrations/` beside the other
+  migrations instead of `src/internal/`.
+
+- The migration modules `0001_initial` and `0002_checkpoints` export their
+  Effect as a named binding (`initial`, `checkpoints`) instead of a default
+  export, and `Migrations` imports them by name. The CommonJS build converts
+  each source file with esbuild in Node interop mode, where a default import
+  of a sibling module resolves to that module's whole exports object rather
+  than the Effect, so `Migrations.set.migrations["0001_initial"].pipe` was
+  undefined under `require` while the ESM build kept working.
+
+## [1.0.0-rc.0] - 2026-08-31
+
+### Breaking Changes
+
+- The stores and `SqlJournal` now require Effect's `SqlClient` service plus
+  `DurableWriter` (the renamed `Database` service) instead of the bundled
+  `Database` service.
+- `emitDurable`, `checkpoint`, and `compact` require a well-formed `OwnerId`.
+  An omitted, null, or malformed owner fails `invalid_event` instead of
+  silently selecting the unfenced write path. `emitDurableUnfenced` is the one
+  sanctioned ownerless admission.
+- `JournalEvent.RunId`, `JournalEvent.SourceId`, and `Input.eventType` reject
+  the empty string and ill-formed UTF-16 at decode. SQLite binds a lone
+  surrogate as U+FFFD, so two distinct identifiers collapsed to one persisted
+  key and destroyed run isolation.
+- `JournalEvent.RunId`, `JournalEvent.SourceId`, and `Input.eventType` are
+  limited to 1,024 UTF-16 code units. `Seq` and `SourceSeq` exclude
+  `Number.MAX_SAFE_INTEGER`, whose successor is not a distinct integer the
+  journal can allocate.
+- `EntriesOptions.limit` and the `entries` service reject pages above 10,000
+  entries, which would otherwise be decoded into memory in full.
+- `OwnerId.pid` is a non-negative integer. A fractional, `NaN`, or negative
+  pid used to degrade into `fence_lost`, which reads as "someone else owns
+  this run" and sends the caller hunting a race that never happened.
+- Durable read failures report the new `read_failed` code instead of `unknown`,
+  which is now reserved for a genuinely unclassified journal defect.
+- `payload` and `meta` are encoded with sorted object keys, so producer
+  idempotency compares JSON values rather than one serialization of them. The
+  sort runs over the ENCODED JSON, so the persisted bytes keep every
+  `JSON.stringify` semantic.
+- `JournalEvent.Entry.eventType` uses the same bounded identifier as
+  `Input.eventType`. It was a bare `Schema.String`, so a consumer decoding a
+  committed row accepted event types no emit could have produced.
+- Every identifier rejects NUL. SQLite's `length()` stops at the first one, so
+  the column's own non-empty check failed and the caller was told `sink_failed`
+  about an identifier it had just supplied.
+- `entries`, `stream`, `checkpoint`, `latestCheckpoint`, and `compact` decode
+  the schemas this package publishes instead of hand-checking a subset of them.
+  A lone-surrogate run id was refused at `emit` and answered with an empty page
+  at `entries`.
+
+### Added
+
+- `emitDurableUnfenced`, `checkpoint`, `latestCheckpoint`, `compact`, the
+  `Checkpoint` and `Compacted` model, and `SqlJournal.CompactionPolicy` for
+  automatic threshold-driven checkpoint-and-compact.
+- `SqlJournalOptions.sourceEventCache` bounds the in-process
+  producer-idempotency index, and `SqlJournalOptions.redact` chooses the
+  redactor applied at the single encode chokepoint.
+- `TestJournalOptions` forwards `sourceEventCache`, `redact`, and `compaction`,
+  so the sanctioned test bundle can exercise every layer option.
+- `SqlJournalOptions.maxEntryBytes` bounds one entry's encoded bytes. It is
+  unset by default: `capacity` bounds entry COUNT, so without it a handful of
+  multi-megabyte payloads is the memory bill.
+- Package-owned documentation under `docs/`, generated into
+  `docs/pages/api/journal.md` by `scripts/docs.mjs` and drift-checked by the
+  `//packages/journal:docsPages` target.
+
+### Fixed
+
+- `Redaction.defaultRules` covers GitHub tokens, AWS access keys, Slack tokens,
+  Google API keys, URL passwords, quoted `KEY="value"` assignments, and
+  embedded JSON credential members. The bearer rule consumes the full RFC 6750
+  token alphabet instead of stopping at the first `+`, `/`, or `~`.
+- `Redaction.redact` mirrors `JSON.stringify`'s `toJSON` step, so a `Date`
+  persists as its ISO string instead of `{}`. The canonical encoder now runs
+  after encoding rather than over the raw redactor output, so the same `Date`
+  survives `Redaction.makeNoop()` too, and a redactor returning a cycle fails
+  `invalid_event` instead of killing the emit with a defect.
+- `Redaction.isSensitiveKey` recognises `credential`, `credentials`, `dsn`, the
+  connection-string family, a plural form of every name it knew, and a trailing
+  `key` word. The permanent journal redacted strictly less than the one-shot
+  `smithers bug` report, which inverted the risk.
+- The redacting console redacts the label `count`, `countReset`, `time`, and
+  `timeEnd` print. All four were bound straight to the delegate as if they
+  carried no output, and `timeLog` already redacted its label, so a timer could
+  never be found again under the name it was registered with.
+- The compaction policy's per-run counter is serialized. Two settlements that
+  overlapped both issued the seeding COUNT and the later reply overwrote the
+  newer count with a stale one, so ten committed events produced no compaction
+  at all.
+- A `Rule` with `replace` omitted now replaces the whole match, as its JSDoc
+  always said. It used to emit `"123-45-678=[REDACTED]"` for a match containing
+  no `=`, leaking every character but the last.
+- A non-global `Rule.pattern` redacts every match instead of only the first.
+- `Redaction.redactJsonString` fails closed. It used to return the original
+  secret JSON when re-encoding the redacted value failed.
+- A payload with a throwing getter, a hostile `Proxy`, or extreme nesting fails
+  the emit with a typed `invalid_event` instead of an unrecoverable defect that
+  tore down the enclosing `transact` transaction.
+- `Journal.stream` emits its first entry after one page instead of
+  materializing a run's whole history first.
+- A lossy entry admitted before a compaction can no longer land below the
+  committed compaction floor, where it was persisted and unreadable forever.
+- Automatic compaction runs off the layer-wide allocation permit, so a slow
+  `CompactionPolicy.capture` no longer stalls emits on unrelated runs, and
+  `capture` is bounded by a timeout.
+- `checkpoint`'s receipt is decoded from the bytes it persisted, so it agrees
+  with `latestCheckpoint` and no longer aliases the caller's mutable state.
+- One conflicted lossy entry no longer destroys its whole persisted batch.
+- Entries published to `changes` are frozen, so one subscriber cannot mutate
+  another subscriber's view.
+- Module headers and the README cite pages that exist. `docs/specs/` was never
+  imported into this repository.
+- The internal `@slop` review markers no longer ship in the published
+  declarations. Every export they marked now carries the prose that retires
+  them, so a consumer's editor hover shows the contract rather than a note to
+  ourselves.
+
+## [0.1.0] - 2026-08-05
+
+This release predates the storage split. The run, attempt, and cache stores and
+the deferred/clock migration named below moved to `@smthrs/run-store`,
+`@smthrs/step-cache`, and `@smthrs/engine-store`; this package's `0002`
+migration creates `flows_journal_checkpoints`.
+
+### Fixed
+
+- Kept journal admission, JSON validation, persistence normalization, and
+  ownership heartbeat loss in typed Effect failure/interruption channels.
+- Replaced structural `_tag` probing with Schema and Effect SQL error guards.
+
+### Added
+
+- Added the non-blocking journal, fenced run and attempt stores, run
+  coordinator, migrations, and content-addressed cache.
+- Added migration 0002 for durable deferred completions and absolute clock
+  deadlines.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
+# @smthrs/journal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://journal.smithers.sh
+
+An append-only event history for [Effect](https://effect.website) applications.
+`@smthrs/journal` records what a long-running piece of work did, in order, in
+SQLite. Rows are appended and never updated, so the history reads the same on
+the tenth pass as on the first, and a process that dies halfway through leaves
+behind everything it had already committed.
+
+It is a set of Effect services: every write returns a typed receipt or a typed
+failure, and the database arrives as a layer you compose. It belongs to the
+Smithers durable flow engine, but it runs on its own, and no other Smithers
+package is required.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+`effect` is a peer dependency at exactly `4.0.0-rc.115`. Two copies of `effect`
+in one program are two sets of service tags, so a journal layer built against
+one copy cannot be provided to a program holding the other.
+
+Node.js 26.4.0 or later is required for the Node SQLite driver. The package
+ships as both ESM and CommonJS with TypeScript declarations.
+
+## Write one run and read it back
+
+```ts
+import * as DurableWriter from "@smthrs/database/DurableWriter"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import { Journal, JournalEvent, Migrations, SqlJournal } from "@smthrs/journal"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+
+const database = Layer.provideMerge(
+  DurableWriter.layer(),
+  NodeDatabase.layer({ filename: "history.db" })
+)
+
+const journalLayer = SqlJournal.layer({ capacity: 1024, overflow: "reject" }).pipe(
+  Layer.provide(Layer.provideMerge(Migrations.layer, database))
+)
+
+const runId = "run-1" as JournalEvent.RunId
+const sourceId = "engine" as JournalEvent.SourceId
+
+const program = Effect.gen(function*() {
+  const journal = yield* Journal.Journal
+
+  const created = yield* journal.emitDurableUnfenced({
+    runId,
+    sourceId,
+    eventType: "run.created",
+    payload: { flow: "build", token: "ghp_0123456789abcdefghijklmnopqrstuvwxyz" }
+  })
+  console.log("durable:", created._tag, "seq", created.seq)
+
+  yield* journal.emitLossy({
+    runId,
+    sourceId,
+    eventType: "step.progress",
+    payload: { step: "compile", percent: 40 }
+  })
+  yield* journal.flush
+
+  const page = yield* journal.entries({ runId, limit: 100 })
+  for (const entry of page.entries) {
+    console.log(entry.seq, entry.eventType, JSON.stringify(entry.payload))
+  }
+})
+
+await Effect.runPromise(program.pipe(Effect.provide(journalLayer), Effect.orDie))
+```
+
+```text
+durable: Accepted seq 0
+0 run.created {"flow":"build","token":"[REDACTED]"}
+1 step.progress {"percent":40,"step":"compile"}
+```
+
+The token came back as `[REDACTED]` because it was scrubbed before the row was
+encoded, so the credential is not in `history.db` and never was. `SqlJournal.layer`
+needs both database services: `SqlClient` to read through and `DurableWriter`
+to write through.
+
+## What the journal guarantees
+
+- **Two channels, one order.** `emitDurable` and `emitDurableUnfenced` are on
+  disk before the call returns. `emitLossy` goes through a bounded queue that
+  drops under pressure rather than stalling the writer. Both land in one
+  per-run `seq`, so the cheap channel cannot reorder the expensive one.
+- **Every write gets an answer.** An emission returns `Accepted`, `Duplicate`,
+  or `Dropped`, and every failure is a `JournalError` carrying one of fourteen
+  stable codes, from `invalid_event` and `fence_lost` through `queue_overflow`
+  and `sink_failed`.
+- **A retry is not a second event.** Producer identity is
+  `(runId, sourceId, sourceSeq)`, unique in the database, so a producer that
+  replays after a crash gets `Duplicate` back rather than doubling its history.
+- **Credentials never reach the file.** Payloads are scrubbed on the write
+  path, before encoding, because a row is permanent and gets replayed verbatim
+  to every later reader.
+- **A stale process cannot append.** `emitDurable` takes an `OwnerId` and
+  commits only while the injected `Consensus` strategy still records that
+  owner as holding the run. A process that was replaced fails `fence_lost`
+  instead of writing into a history it no longer owns.
+- **State and its entry commit together.** `transact` runs your own writes and
+  the entries describing them in one transaction and defers publication until
+  it commits, so the two can never disagree. Committing locally is not remote
+  atomicity: external effects still need idempotency keys, fencing tokens, or
+  compensation.
+- **A long run stops growing.** A checkpoint pins replay state to a sequence,
+  and `compact` deletes the entries below it.
+
+`Seq` is canonical per-run replay order; `SourceSeq` identifies producer
+retries. Rejected and dropped admissions may consume either sequence, so gaps
+are valid.
+
+Post-commit compaction preserves the durable writer caller's Effect
+interruption policy. Ordinary callers can interrupt a slow capture; a write
+inside an uninterruptible cancellation finalizer keeps that policy, so
+journaling cannot abandon the cleanup that follows the commit.
+
+## Public API
+
+The root exports each module as a namespace, and each is also importable from
+the matching `@smthrs/journal/*` subpath. The
+[API reference](https://journal.smithers.sh/reference/api/) lists every export
+with its one-line summary.
+
+| Namespace        | What it holds                                                                                                                                                                                                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `Journal`        | The service and its operations, the `Checkpoint` and `Compacted` models, typed errors, receipts, read options, constructors, and the no-op layer.                                                                                                                  |
+| `JournalEvent`   | Branded `RunId`, `Seq`, `SourceId`, and `SourceSeq`; the `Input` and committed `Entry` schemas; deterministic `makeEventId`.                                                                                                                                       |
+| `SqlJournal`     | `SqlJournalOptions`, `CompactionPolicy`, the database-backed `layer(options)` fenced by `SqlConsensus`, and `layerWith(options)` over an injected strategy.                                                                                                        |
+| `OwnerId`        | The fencing token `emitDurable` accepts, carrying `hostId`, `pid`, and `nonce`.                                                                                                                                                                                    |
+| `Consensus`      | The injectable ownership strategy: `claim`, `activate`, `heartbeat`, `reconfirm`, `release`, `steal`, `recover`, and the commit-time `guard`; typed outcomes; `LivenessEvidence`; the lease constants; `layerLocal`, `layerNoop`, `make`, `makeLocal`, `makeNoop`. |
+| `SqlConsensus`   | The default database-backed strategy over `flows_consensus_leases`: `make` and `layer`.                                                                                                                                                                            |
+| `Redaction`      | The payload redaction applied to entries before they are written, its rule set, and `makeNoop`.                                                                                                                                                                    |
+| `Projection`     | The reproducible `Projection` model and its identity constructor.                                                                                                                                                                                                  |
+| `JournalMetrics` | The `flows_journal_writes` counter and the per-channel views `SqlJournal` updates on every emission receipt.                                                                                                                                                       |
+| `Migrations`     | `set`, `run`, and `layer` for this package's tables: `flows_journal_events` with its indexes, `flows_journal_checkpoints`, `flows_journal_dedup`, and the `flows_consensus_leases` lease table.                                                                    |
+
+Two test entry points sit outside the root:
+`@smthrs/journal/test/TestJournal` provides the production journal over an
+in-memory database (Node only), and `@smthrs/journal/test/Notifying` wraps a
+service so a hook fires around every operation, which is how you inject a crash
+at an exact transition.
+
+## What a fenced write needs
+
+`emitDurable`, `checkpoint`, and `compact` gate their write on the
+`Consensus` strategy the journal was built with: the write joins the
+strategy's `guard` inside its own transaction and commits only while the
+strategy still records the supplied owner as holding the run. `SqlJournal.layer`
+fences through `SqlConsensus`, whose lease lives in `flows_consensus_leases`, a
+table this package's own migrations create; `SqlJournal.layerWith` takes any
+strategy, such as `Consensus.layerLocal` for a single process or the browser.
+An owner takes the run through the strategy's `claim` and `activate`, which
+[`@smthrs/run-store`](https://run-store.smithers.sh) drives for a durable run.
+
+`emitDurableUnfenced` is the sanctioned path for a genuinely ownerless
+admission, such as an import or a repair tool. Reaching for it to dodge
+`fence_lost` writes exactly the zombie entry the fence exists to reject.
+
+## Where the journal sits
+
+The journal holds the history and nothing else. Run and attempt state live in
+[`@smthrs/run-store`](https://run-store.smithers.sh), sealed step results in
+[`@smthrs/step-cache`](https://step-cache.smithers.sh), and the durable
+deferred and clock tables in
+[`@smthrs/engine-store`](https://engine-store.smithers.sh). Those stores hold
+the executable state, which is not derived from journal entries; `transact` is
+what keeps the two halves consistent, because every one of them writes through
+the same `DurableWriter`.
+
+SQLite and PostgreSQL share this journal and migration ladder; see
+[database configuration](../database/docs/concepts/sqlite-only.md).
+
+Rewinding SQL histories expose `Journal.Service.generation(runId)`, which reads
+`{ generation, afterSeq }` from `flows_journal_generations` (initially zero and
+`-1`). The SQL layer installs this table idempotently on existing databases.
+Time travel increments the generation in the archive transaction. Append-only
+adapters may omit the operation; truncating adapters must implement it. The
+`JournalGeneration.initialize` subpath shares the table installation with time
+travel without adding a migration below an already applied migration block.
+
+## Documentation
+
+- [State and event authority](./docs/concepts/state-event-authority.md)
+- [Installation](https://journal.smithers.sh/installation/)
+- [Quickstart](https://journal.smithers.sh/quickstart/)
+- [The two channels](https://journal.smithers.sh/concepts/two-channels/)
+- [The owner fence](https://journal.smithers.sh/concepts/owner-fence/)
+- [Checkpoints and compaction](https://journal.smithers.sh/concepts/compaction/)
+- [API reference](https://journal.smithers.sh/reference/api/)
+- [Troubleshooting](https://journal.smithers.sh/troubleshooting/)
+
+## License
+
+MIT

package/dist/cjs/CallFact.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Versioned facts for an authorized native cell invocation and its delivered result.
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+/** Stable harness coordinates, independent of physical attempt or publication order.
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Identity: Schema.Struct<{
+    /** Public logical run identity, not an authentication session credential. */
+    readonly runId: Schema.String;
+    readonly frame: Schema.Int;
+    readonly cell: Schema.String;
+    readonly ordinal: Schema.Int;
+    readonly declaration: Schema.String;
+    readonly layers: Schema.$Array<Schema.String>;
+}>;
+/** A call annotation contains data only and never changes an action key.
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Call: Schema.Struct<{
+    readonly callId: Schema.String;
+    readonly identity: Schema.Struct<{
+        /** Public logical run identity, not an authentication session credential. */
+        readonly runId: Schema.String;
+        readonly frame: Schema.Int;
+        readonly cell: Schema.String;
+        readonly ordinal: Schema.Int;
+        readonly declaration: Schema.String;
+        readonly layers: Schema.$Array<Schema.String>;
+    }>;
+    readonly flowName: Schema.String;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    /**
+     * The resolved declaration's display projection, as its owner encoded it.
+     *
+     * JSON rather than a struct because the vocabulary belongs to
+     * `@smthrs/registry` (`Descriptor.FlowActivity`, `Descriptor.CallPresentation`),
+     * which sits above this package: `@smthrs/harness` `Cell.displayDescriptor`
+     * encodes it from a typed call and the reading card validates each field
+     * before it is displayed, so the journal carries it and claims nothing about
+     * it. Absent means the declaration claimed nothing.
+     */
+    readonly descriptor: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+/** Decoded authorized call coordinates.
+ * @category models
+ * @since 1.0.0
+ */
+export type Call = typeof Call.Type;
+declare const Annotation_base: Context.ServiceClass<Annotation, "@smthrs/journal/CallFact/Annotation", {
+    readonly phase: "invoked" | "settled";
+    readonly call: Call;
+}>;
+/** Native action annotation; only the existing controller record settles a call.
+ * @category services
+ * @since 1.0.0
+ */
+export declare class Annotation extends Annotation_base {
+}
+/** Public result vocabulary. Executable outcomes remain in the protected attempt row.
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Result: Schema.Union<readonly [Schema.Struct<{
+    readonly outcome: Schema.Literal<"success">;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly code: Schema.optionalKey<Schema.Never>;
+}>, Schema.Struct<{
+    readonly outcome: Schema.Literal<"failure">;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly message: Schema.optional<Schema.String>;
+    readonly code: Schema.optional<Schema.String>;
+}>]>;
+/** Bounded, redacted event projection; a truncation marker is still JSON.
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Fact: Schema.Union<readonly [Schema.Struct<{
+    readonly phase: Schema.Literal<"invoked">;
+    readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly descriptor: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly version: Schema.Literal<1>;
+    readonly callId: Schema.String;
+    readonly identity: Schema.Struct<{
+        /** Public logical run identity, not an authentication session credential. */
+        readonly runId: Schema.String;
+        readonly frame: Schema.Int;
+        readonly cell: Schema.String;
+        readonly ordinal: Schema.Int;
+        readonly declaration: Schema.String;
+        readonly layers: Schema.$Array<Schema.String>;
+    }>;
+    readonly flowName: Schema.String;
+}>, Schema.Struct<{
+    readonly phase: Schema.Literal<"settled">;
+    readonly outcome: Schema.Literals<readonly ["success", "failure"]>;
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly message: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly code: Schema.optional<Schema.String>;
+    readonly version: Schema.Literal<1>;
+    readonly callId: Schema.String;
+    readonly identity: Schema.Struct<{
+        /** Public logical run identity, not an authentication session credential. */
+        readonly runId: Schema.String;
+        readonly frame: Schema.Int;
+        readonly cell: Schema.String;
+        readonly ordinal: Schema.Int;
+        readonly declaration: Schema.String;
+        readonly layers: Schema.$Array<Schema.String>;
+    }>;
+    readonly flowName: Schema.String;
+}>]>;
+/** Decoded public native call fact.
+ * @category models
+ * @since 1.0.0
+ */
+export type Fact = typeof Fact.Type;
+/** The immutable native journal is the durable outbox consumed by the native bridge.
+ * @category events
+ * @since 1.0.0
+ */
+export declare const eventType = "flows.harness.call-fact.v1";
+export {};
+//# sourceMappingURL=CallFact.d.ts.map

package/dist/cjs/CallFact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CallFact.d.ts","sourceRoot":"","sources":["../../src/CallFact.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB,6EAA6E;;;;;;;EAO7E,CAAA;AAEF;;;GAGG;AACH,eAAO,MAAM,IAAI;;;QAbf,6EAA6E;;;;;;;;;;IAkB7E;;;;;;;;;OASG;;EAEH,CAAA;AAEF;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;;oBAOjB,SAAS,GAAG,SAAS;mBACtB,IAAI;;AANrB;;;GAGG;AACH,qBAAa,UAAW,SAAQ,eAGW;CAAG;AAE9C;;;GAGG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;IAajB,CAAA;AASF;;;GAGG;AACH,eAAO,MAAM,IAAI;;;;;;;QA5Ef,6EAA6E;;;;;;;;;;;;;;;;;;QAA7E,6EAA6E;;;;;;;;;IA2F7E,CAAA;AAEF;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC;;;GAGG;AACH,eAAO,MAAM,SAAS,+BAA+B,CAAA"}

package/dist/cjs/CallFact.js

@@ -0,0 +1,106 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var CallFact_exports = {};
+__export(CallFact_exports, {
+  Annotation: () => Annotation,
+  Call: () => Call,
+  Fact: () => Fact,
+  Identity: () => Identity,
+  Result: () => Result,
+  eventType: () => eventType
+});
+module.exports = __toCommonJS(CallFact_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const Identity = Schema.Struct({
+  /** Public logical run identity, not an authentication session credential. */
+  runId: Schema.String,
+  frame: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  cell: Schema.String,
+  ordinal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  declaration: Schema.String,
+  layers: Schema.Array(Schema.String)
+});
+const Call = Schema.Struct({
+  callId: Schema.String.check(Schema.isPattern(/^cell-call-v1:[0-9a-f]{64}$/)),
+  identity: Identity,
+  flowName: Schema.String,
+  input: Schema.Json,
+  /**
+   * The resolved declaration's display projection, as its owner encoded it.
+   *
+   * JSON rather than a struct because the vocabulary belongs to
+   * `@smthrs/registry` (`Descriptor.FlowActivity`, `Descriptor.CallPresentation`),
+   * which sits above this package: `@smthrs/harness` `Cell.displayDescriptor`
+   * encodes it from a typed call and the reading card validates each field
+   * before it is displayed, so the journal carries it and claims nothing about
+   * it. Absent means the declaration claimed nothing.
+   */
+  descriptor: Schema.optional(Schema.Json)
+});
+class Annotation extends Context.Service()("@smthrs/journal/CallFact/Annotation") {
+}
+const Result = Schema.Union([
+  Schema.Struct({
+    outcome: Schema.Literal("success"),
+    value: Schema.Json,
+    message: Schema.optional(Schema.String),
+    code: Schema.optionalKey(Schema.Never)
+  }),
+  Schema.Struct({
+    outcome: Schema.Literal("failure"),
+    value: Schema.Json,
+    message: Schema.optional(Schema.String),
+    code: Schema.optional(Schema.String)
+  })
+]);
+const coordinates = {
+  version: Schema.Literal(1),
+  callId: Call.fields.callId,
+  identity: Identity,
+  flowName: Schema.String
+};
+const Fact = Schema.Union([
+  Schema.Struct({
+    ...coordinates,
+    phase: Schema.Literal("invoked"),
+    input: Schema.Json,
+    descriptor: Schema.optional(Schema.Json)
+  }),
+  Schema.Struct({
+    ...coordinates,
+    phase: Schema.Literal("settled"),
+    outcome: Schema.Literals(["success", "failure"]),
+    value: Schema.Json,
+    message: Schema.optional(Schema.Json),
+    code: Schema.optional(Schema.String)
+  })
+]);
+const eventType = "flows.harness.call-fact.v1";
+//# sourceMappingURL=CallFact.js.map

package/dist/cjs/CallFact.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/CallFact.ts"],
+  "sourcesContent": ["/**\n * Versioned facts for an authorized native cell invocation and its delivered result.\n * @since 1.0.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Schema from \"effect/Schema\"\n\n/** Stable harness coordinates, independent of physical attempt or publication order.\n * @category schemas\n * @since 1.0.0\n */\nexport const Identity = Schema.Struct({\n  /** Public logical run identity, not an authentication session credential. */\n  runId: Schema.String,\n  frame: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),\n  cell: Schema.String,\n  ordinal: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),\n  declaration: Schema.String,\n  layers: Schema.Array(Schema.String)\n})\n\n/** A call annotation contains data only and never changes an action key.\n * @category schemas\n * @since 1.0.0\n */\nexport const Call = Schema.Struct({\n  callId: Schema.String.check(Schema.isPattern(/^cell-call-v1:[0-9a-f]{64}$/)),\n  identity: Identity,\n  flowName: Schema.String,\n  input: Schema.Json,\n  /**\n   * The resolved declaration's display projection, as its owner encoded it.\n   *\n   * JSON rather than a struct because the vocabulary belongs to\n   * `@smthrs/registry` (`Descriptor.FlowActivity`, `Descriptor.CallPresentation`),\n   * which sits above this package: `@smthrs/harness` `Cell.displayDescriptor`\n   * encodes it from a typed call and the reading card validates each field\n   * before it is displayed, so the journal carries it and claims nothing about\n   * it. Absent means the declaration claimed nothing.\n   */\n  descriptor: Schema.optional(Schema.Json)\n})\n\n/** Decoded authorized call coordinates.\n * @category models\n * @since 1.0.0\n */\nexport type Call = typeof Call.Type\n\n/** Native action annotation; only the existing controller record settles a call.\n * @category services\n * @since 1.0.0\n */\nexport class Annotation extends Context.Service<Annotation, {\n  readonly phase: \"invoked\" | \"settled\"\n  readonly call: Call\n}>()(\"@smthrs/journal/CallFact/Annotation\") {}\n\n/** Public result vocabulary. Executable outcomes remain in the protected attempt row.\n * @category schemas\n * @since 1.0.0\n */\nexport const Result = Schema.Union([\n  Schema.Struct({\n    outcome: Schema.Literal(\"success\"),\n    value: Schema.Json,\n    message: Schema.optional(Schema.String),\n    code: Schema.optionalKey(Schema.Never)\n  }),\n  Schema.Struct({\n    outcome: Schema.Literal(\"failure\"),\n    value: Schema.Json,\n    message: Schema.optional(Schema.String),\n    code: Schema.optional(Schema.String)\n  })\n])\n\nconst coordinates = {\n  version: Schema.Literal(1),\n  callId: Call.fields.callId,\n  identity: Identity,\n  flowName: Schema.String\n}\n\n/** Bounded, redacted event projection; a truncation marker is still JSON.\n * @category schemas\n * @since 1.0.0\n */\nexport const Fact = Schema.Union([\n  Schema.Struct({\n    ...coordinates,\n    phase: Schema.Literal(\"invoked\"),\n    input: Schema.Json,\n    descriptor: Schema.optional(Schema.Json)\n  }),\n  Schema.Struct({\n    ...coordinates,\n    phase: Schema.Literal(\"settled\"),\n    outcome: Schema.Literals([\"success\", \"failure\"]),\n    value: Schema.Json,\n    message: Schema.optional(Schema.Json),\n    code: Schema.optional(Schema.String)\n  })\n])\n\n/** Decoded public native call fact.\n * @category models\n * @since 1.0.0\n */\nexport type Fact = typeof Fact.Type\n\n/** The immutable native journal is the durable outbox consumed by the native bridge.\n * @category events\n * @since 1.0.0\n */\nexport const eventType = \"flows.harness.call-fact.v1\"\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,cAAyB;AACzB,aAAwB;AAMjB,MAAM,WAAW,OAAO,OAAO;AAAA;AAAA,EAEpC,OAAO,OAAO;AAAA,EACd,OAAO,OAAO,IAAI,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAAA,EACxD,MAAM,OAAO;AAAA,EACb,SAAS,OAAO,IAAI,MAAM,OAAO,uBAAuB,CAAC,CAAC;AAAA,EAC1D,aAAa,OAAO;AAAA,EACpB,QAAQ,OAAO,MAAM,OAAO,MAAM;AACpC,CAAC;AAMM,MAAM,OAAO,OAAO,OAAO;AAAA,EAChC,QAAQ,OAAO,OAAO,MAAM,OAAO,UAAU,6BAA6B,CAAC;AAAA,EAC3E,UAAU;AAAA,EACV,UAAU,OAAO;AAAA,EACjB,OAAO,OAAO;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWd,YAAY,OAAO,SAAS,OAAO,IAAI;AACzC,CAAC;AAYM,MAAM,mBAAmB,QAAQ,QAGrC,EAAE,qCAAqC,EAAE;AAAC;AAMtC,MAAM,SAAS,OAAO,MAAM;AAAA,EACjC,OAAO,OAAO;AAAA,IACZ,SAAS,OAAO,QAAQ,SAAS;AAAA,IACjC,OAAO,OAAO;AAAA,IACd,SAAS,OAAO,SAAS,OAAO,MAAM;AAAA,IACtC,MAAM,OAAO,YAAY,OAAO,KAAK;AAAA,EACvC,CAAC;AAAA,EACD,OAAO,OAAO;AAAA,IACZ,SAAS,OAAO,QAAQ,SAAS;AAAA,IACjC,OAAO,OAAO;AAAA,IACd,SAAS,OAAO,SAAS,OAAO,MAAM;AAAA,IACtC,MAAM,OAAO,SAAS,OAAO,MAAM;AAAA,EACrC,CAAC;AACH,CAAC;AAED,MAAM,cAAc;AAAA,EAClB,SAAS,OAAO,QAAQ,CAAC;AAAA,EACzB,QAAQ,KAAK,OAAO;AAAA,EACpB,UAAU;AAAA,EACV,UAAU,OAAO;AACnB;AAMO,MAAM,OAAO,OAAO,MAAM;AAAA,EAC/B,OAAO,OAAO;AAAA,IACZ,GAAG;AAAA,IACH,OAAO,OAAO,QAAQ,SAAS;AAAA,IAC/B,OAAO,OAAO;AAAA,IACd,YAAY,OAAO,SAAS,OAAO,IAAI;AAAA,EACzC,CAAC;AAAA,EACD,OAAO,OAAO;AAAA,IACZ,GAAG;AAAA,IACH,OAAO,OAAO,QAAQ,SAAS;AAAA,IAC/B,SAAS,OAAO,SAAS,CAAC,WAAW,SAAS,CAAC;AAAA,IAC/C,OAAO,OAAO;AAAA,IACd,SAAS,OAAO,SAAS,OAAO,IAAI;AAAA,IACpC,MAAM,OAAO,SAAS,OAAO,MAAM;AAAA,EACrC,CAAC;AACH,CAAC;AAYM,MAAM,YAAY;",
+  "names": []
+}