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

package/dist/cjs/internal/JournalRecords.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Stable engine event constructors over the open journal envelope.
+ *
+ * @since 0.1.0
+ */
+import { Journal, JournalEvent } from "@smthrs/journal";
+import type { EngineEvent } from "@smthrs/journal";
+import * as Effect from "effect/Effect";
+/**
+ * The addressing every engine record shares: which run wrote it, which source
+ * inside that run, and which journal lineage it belongs to.
+ *
+ * Only `lineageId` is a semantic requirement rather than bookkeeping — a
+ * record without one is a record no time-travel frame can address — which is
+ * why it is required here rather than optional.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface EventOptions {
+    readonly runId: string;
+    readonly sourceId: string;
+    readonly sourceSeq?: number | undefined;
+    /**
+     * The journal lineage this record addresses itself to — minted by the engine
+     * (`FlowEngine.Lineage`) and carried on every engine record.
+     *
+     * Time travel (`packages/smithers/flows/time-travel/docs/README.md`) makes a frame the position
+     * `(lineageId, seq)`, and time travel's replay skips any entry whose
+     * `meta.lineageId` names a different lineage. An engine record without it is
+     * a record no frame can address, which is why this is required rather than
+     * optional: the omission used to make `TimeTravel.inspect` fail `not_found`
+     * on every journal the production composition wrote.
+     */
+    readonly lineageId: string;
+    /**
+     * The step-cache key whose sealed row holds this record's result, when one
+     * exists. Replay reads it to hand the projection the sealed value instead of
+     * re-deriving it.
+     */
+    readonly cacheKey?: string | undefined;
+    /**
+     * What a re-emission of this producer identity means.
+     *
+     * The default, `content`, is the strict reading: the identity names one set
+     * of bytes. `identity` is for a record whose sequence is derived from the
+     * event itself, where a collision IS the same event observed twice and the
+     * bytes that differ are metadata about the observation — a node settled
+     * `built` by the walk that ran it and `clean` by the resumed walk that
+     * replayed it is one node settling once, seen twice.
+     */
+    readonly dedupe?: JournalEvent.Dedupe | undefined;
+}
+/**
+ * The run's state advanced. Replaying these records in order is how time
+ * travel derives the state AT a frame, rather than reading the run row's
+ * latest value.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const runDecision: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * An action attempt was admitted and its body is about to run. Paired with
+ * {@link attemptFinished}; an unmatched one is crash evidence.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const attemptStarted: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * An action attempt settled, successfully or not. Closes the span opened by
+ * {@link attemptStarted}.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const attemptFinished: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A durable deferred was resolved from outside the run. Journaled because the
+ * resolution is the only evidence of it — a replay cannot re-derive a value
+ * that arrived over the network. The record names the completion row and the
+ * digests of its encoded `exit` and `metadata`; the values stay in the row,
+ * because the journal is redacted and replayed to subscribers.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const deferredCompleted: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A run observed a deferred's result, so registration sweeps stop waking it
+ * for that result. The result itself stays in its row for replay.
+ *
+ * @since 1.0.0
+ * @category events
+ */
+export declare const deferredConsumed: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A durable timer stopped being pending: it fired, or its run settled first.
+ * Without it a rebuilt deadline index would re-arm a clock that already
+ * completed (issue #2037).
+ *
+ * @since 1.0.0
+ * @category events
+ */
+export declare const clockCompleted: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * The {@link clockCompleted} record for one clock, under the producer identity
+ * every completer of that clock shares, so a retried completion collapses.
+ *
+ * @since 1.0.0
+ * @category events
+ */
+export declare const clockCompletedFor: (journalSource: string, lineageId: string, clock: {
+    readonly flowName: string;
+    readonly executionId: string;
+    readonly clockName: string;
+}, completedAtMs: number) => JournalEvent.Input;
+/**
+ * A durable timer was armed. Journaling the schedule rather than the firing is
+ * what lets a resumed run re-arm the same deadline instead of restarting the
+ * wait.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const clockScheduled: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * The run was interrupted — cancelled, fenced out, or torn down — as opposed
+ * to failing. Recorded so a later reader can tell a cancelled run from a
+ * broken one.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const interrupted: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * The jj pointer and plan digest in force at this point in the journal. These
+ * are the two tier-2 facts replay cannot derive, which is why the engine emits
+ * them and time travel's snapshot projector folds them into frame anchors.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const snapshotIdentified: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A hard-mode step wrote outside its declared write set, so its result was
+ * refused. The record is the forensic trail for a declaration that does not
+ * match what the step actually does.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const hardViolation: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * An expected-mode step wrote paths its declaration did not predict. Unlike
+ * {@link hardViolation} the result still stands — the declaration was a
+ * prediction, and this is the record of it being wrong.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const expectedSetDeviation: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * An isolated execution produced a diff bundle: its content address, the paths
+ * it changed, and the deviations the declaration did not predict. One of the
+ * two record types copy-back writes.
+ *
+ * It is written once the attempt's copy-back has settled, not before it — the
+ * rebase loop owns the window in between, and a bundle that lost every race
+ * was never a proposal the host saw. A crash inside that window leaves the
+ * attempt row unfinished, so the replay re-executes and journals the bundle it
+ * actually applies. An execution the declaration invalidated journals nothing
+ * here at all; its `hard-violation` record carries the identity instead.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const diffBundleCaptured: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A diff bundle reached the host. Carries the rebase count, the deduplicated
+ * `queued` effect keys, and the `dispatched` keys the delivery stage sent.
+ * `dispatched` is present and empty when no `EffectDispatcher` is composed, so
+ * the absence of delivery is a journal fact rather than an inference.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const copyBackSettled: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A plan was recorded and a run is about to be driven under it. Carries the
+ * plan id, its generation-0 digest, and its node count, so
+ * `packages/smithers/flows/plan/docs/api.md` asks the audit question, "show me the plan this ran
+ * under". This record answers it exactly rather than reconstructing it.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const planRecorded: (options: EventOptions, payload: EngineEvent.PlanRecordedPayload) => JournalEvent.Input;
+/**
+ * An elaboration appended a pre-keyed subgraph to the SAME plan. The plan
+ * grows; it is never invalidated, so this record names the new generation, the
+ * advanced digest, and the node ids added — never a replacement graph.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const subgraphAppended: (options: EventOptions, payload: EngineEvent.SubgraphAppendedPayload) => JournalEvent.Input;
+/**
+ * A plan node was admitted to the scheduler: its caps and seats allowed it,
+ * and its effective priority selected it. Paired with `node-settled`, this is
+ * the queue-time evidence the journal measures.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const nodeScheduled: (options: EventOptions, payload: EngineEvent.NodeScheduledPayload) => JournalEvent.Input;
+/**
+ * A plan node reached an evaluation outcome. Skyframe's
+ * `EvaluationProgressReceiver.EvaluationState` is the prior art:
+ * `SUCCESS_VERSION_CHANGED`/`SUCCESS_VERSION_UNCHANGED` map onto `built`/
+ * `clean`, and where Skyframe splits failure by version we use `failed` and
+ * `skipped` — a content-addressed store never serves a failure from cache, so
+ * `FAIL_VERSION_UNCHANGED` has no analogue, while a dependent that never ran
+ * because its cone failed does. `deferred` is the one outcome outside the
+ * Skyframe quadruple: a scheduling debt recorded by probabilistic selection,
+ * not an evaluation state.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const nodeSettled: (options: EventOptions, payload: EngineEvent.NodeSettledPayload) => JournalEvent.Input;
+/**
+ * A scheduled node's dispatch identity was invalidated: its measured inputs no
+ * longer match the ones its key was computed from, so it is re-keyed and
+ * re-dispatched. Invalidation is re-keying — there is no dirty bit and no
+ * invalidating visitor to journal.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const nodeInvalidated: (options: EventOptions, payload: EngineEvent.NodeInvalidatedPayload) => JournalEvent.Input;
+/**
+ * The reconciliation seam returned a verdict for a deviation or an unabsorbed
+ * materialization conflict.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const nodeReconciled: (options: EventOptions, payload: EngineEvent.NodeReconciledPayload) => JournalEvent.Input;
+/**
+ * A selection guess postponed a sink node: it did not execute, wrote no cache
+ * row, and this record is the debt — node id, plan key, the suspected edge,
+ * and the likelihood — that a later guess-free pass repays. `Selection.debt`
+ * folds these against {@link nodeSettled} records to list what is still owed.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const selectionDeferred: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A selection guess proposed a flow no real dependency reaches. V1 records
+ * and surfaces the proposal; it never auto-appends plan nodes, so this record
+ * is the proposal's only artifact.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const selectionProposed: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A run forced full selection: every verdict was treated as `Admit`, the way
+ * `--fresh` ignores the cache. Journaled so a report can say the guesses were
+ * overridden rather than absent.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const selectionOverridden: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A selection layer returned a Defer or Propose verdict naming a non-sink.
+ * The verdict is ignored — only sinks are deferrable — and this observation
+ * records the layer disagreeing with the plan's shape, in the pattern of
+ * Skyframe's `GraphInconsistencyReceiver`: note it, never wire the detector
+ * to /dev/null.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const selectionInconsistent: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * Where a reused result came from: which run first produced it and under which
+ * key. A cache hit is otherwise invisible in the journal, and provenance is
+ * what makes one auditable after the fact.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const cacheProvenance: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * Two runs recorded different results under one step key — the journaled form
+ * of an under-specified declaration.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const cacheConflict: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * A cached output failed its digest check and the entry was evicted. Journaled
+ * because a repeat is a failing disk, not a coincidence.
+ *
+ * @since 0.1.0
+ * @category events
+ */
+export declare const cacheCorruption: (options: EventOptions, payload: unknown) => JournalEvent.Input;
+/**
+ * Reads a page of engine records without imposing an agent-shaped event union.
+ *
+ * @since 0.1.0
+ * @category queries
+ */
+export declare const entries: (runId: string, after: number | undefined, limit: number) => Effect.Effect<{
+    readonly entries: readonly JournalEvent.Entry[];
+    readonly hasMore: boolean;
+}, Journal.JournalError, Journal.Journal>;
+//# sourceMappingURL=JournalRecords.d.ts.map

package/dist/cjs/internal/JournalRecords.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JournalRecords.d.ts","sourceRoot":"","sources":["../../../src/internal/JournalRecords.ts"],"names":[],"mappings":"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"}

package/dist/cjs/internal/JournalRecords.js

@@ -0,0 +1,122 @@
+"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 JournalRecords_exports = {};
+__export(JournalRecords_exports, {
+  attemptFinished: () => attemptFinished,
+  attemptStarted: () => attemptStarted,
+  cacheConflict: () => cacheConflict,
+  cacheCorruption: () => cacheCorruption,
+  cacheProvenance: () => cacheProvenance,
+  clockCompleted: () => clockCompleted,
+  clockCompletedFor: () => clockCompletedFor,
+  clockScheduled: () => clockScheduled,
+  copyBackSettled: () => copyBackSettled,
+  deferredCompleted: () => deferredCompleted,
+  deferredConsumed: () => deferredConsumed,
+  diffBundleCaptured: () => diffBundleCaptured,
+  entries: () => entries,
+  expectedSetDeviation: () => expectedSetDeviation,
+  hardViolation: () => hardViolation,
+  interrupted: () => interrupted,
+  nodeInvalidated: () => nodeInvalidated,
+  nodeReconciled: () => nodeReconciled,
+  nodeScheduled: () => nodeScheduled,
+  nodeSettled: () => nodeSettled,
+  planRecorded: () => planRecorded,
+  runDecision: () => runDecision,
+  selectionDeferred: () => selectionDeferred,
+  selectionInconsistent: () => selectionInconsistent,
+  selectionOverridden: () => selectionOverridden,
+  selectionProposed: () => selectionProposed,
+  snapshotIdentified: () => snapshotIdentified,
+  subgraphAppended: () => subgraphAppended
+});
+module.exports = __toCommonJS(JournalRecords_exports);
+var import_journal = require("@smthrs/journal");
+var Effect = __toESM(require("effect/Effect"), 1);
+var import_EventTypes = require("../EventTypes.js");
+const meta = (options) => ({
+  lineageId: options.lineageId,
+  ...options.cacheKey === void 0 ? {} : { cacheKey: options.cacheKey }
+});
+const event = (options, eventType, payload) => new import_journal.JournalEvent.Input({
+  runId: options.runId,
+  sourceId: options.sourceId,
+  ...options.sourceSeq === void 0 ? {} : { sourceSeq: options.sourceSeq },
+  ...options.dedupe === void 0 ? {} : { dedupe: options.dedupe },
+  eventType,
+  payload,
+  meta: meta(options)
+});
+const runDecision = (options, payload) => event(options, import_EventTypes.EventTypes.runDecision, payload);
+const attemptStarted = (options, payload) => event(options, import_EventTypes.EventTypes.attemptStarted, payload);
+const attemptFinished = (options, payload) => event(options, import_EventTypes.EventTypes.attemptFinished, payload);
+const deferredCompleted = (options, payload) => event(options, import_EventTypes.EventTypes.deferredCompleted, payload);
+const deferredConsumed = (options, payload) => event(options, import_EventTypes.EventTypes.deferredConsumed, payload);
+const clockCompleted = (options, payload) => event(options, import_EventTypes.EventTypes.clockCompleted, payload);
+const clockCompletedFor = (journalSource, lineageId, clock, completedAtMs) => clockCompleted({
+  runId: clock.executionId,
+  lineageId,
+  sourceId: `${journalSource}:clock-completed:${JSON.stringify([clock.flowName, clock.executionId, clock.clockName])}`,
+  sourceSeq: 0
+}, {
+  flowName: clock.flowName,
+  executionId: clock.executionId,
+  clockName: clock.clockName,
+  completedAtMs
+});
+const clockScheduled = (options, payload) => event(options, import_EventTypes.EventTypes.clockScheduled, payload);
+const interrupted = (options, payload) => event(options, "flows.engine.interrupted", payload);
+const snapshotIdentified = (options, payload) => event(options, import_EventTypes.EventTypes.snapshotIdentified, payload);
+const hardViolation = (options, payload) => event(options, "flows.engine.hard-violation", payload);
+const expectedSetDeviation = (options, payload) => event(options, "flows.engine.expected-set-deviation", payload);
+const diffBundleCaptured = (options, payload) => event(options, "flows.engine.diff-bundle-captured", payload);
+const copyBackSettled = (options, payload) => event(options, "flows.engine.copy-back-settled", payload);
+const planRecorded = (options, payload) => event(options, import_EventTypes.EventTypes.planRecorded, payload);
+const subgraphAppended = (options, payload) => event(options, import_EventTypes.EventTypes.subgraphAppended, payload);
+const nodeScheduled = (options, payload) => event(options, "flows.engine.node-scheduled", payload);
+const nodeSettled = (options, payload) => event(options, "flows.engine.node-settled", payload);
+const nodeInvalidated = (options, payload) => event(options, "flows.engine.node-invalidated", payload);
+const nodeReconciled = (options, payload) => event(options, "flows.engine.node-reconciled", payload);
+const selectionDeferred = (options, payload) => event(options, "flows.engine.selection-deferred", payload);
+const selectionProposed = (options, payload) => event(options, "flows.engine.selection-proposed", payload);
+const selectionOverridden = (options, payload) => event(options, "flows.engine.selection-overridden", payload);
+const selectionInconsistent = (options, payload) => event(options, "flows.engine.selection-inconsistent", payload);
+const cacheProvenance = (options, payload) => event(options, "flows.engine.cache-provenance", payload);
+const cacheConflict = (options, payload) => event(options, "flows.engine.cache-conflict", payload);
+const cacheCorruption = (options, payload) => event(options, "flows.engine.cache-corruption", payload);
+const entries = (runId, after, limit) => Effect.flatMap(
+  import_journal.Journal.Journal,
+  (journal) => journal.entries({
+    runId,
+    ...after === void 0 ? {} : { after },
+    limit
+  })
+);
+//# sourceMappingURL=JournalRecords.js.map

package/dist/cjs/internal/JournalRecords.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/JournalRecords.ts"],
+  "sourcesContent": ["/**\n * Stable engine event constructors over the open journal envelope.\n *\n * @since 0.1.0\n */\n\nimport { Journal, JournalEvent } from \"@smthrs/journal\"\nimport type { EngineEvent } from \"@smthrs/journal\"\nimport * as Effect from \"effect/Effect\"\nimport { EventTypes } from \"../EventTypes.ts\"\n\n/**\n * The addressing every engine record shares: which run wrote it, which source\n * inside that run, and which journal lineage it belongs to.\n *\n * Only `lineageId` is a semantic requirement rather than bookkeeping \u2014 a\n * record without one is a record no time-travel frame can address \u2014 which is\n * why it is required here rather than optional.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface EventOptions {\n  readonly runId: string\n  readonly sourceId: string\n  readonly sourceSeq?: number | undefined\n  /**\n   * The journal lineage this record addresses itself to \u2014 minted by the engine\n   * (`FlowEngine.Lineage`) and carried on every engine record.\n   *\n   * Time travel (`packages/smithers/flows/time-travel/docs/README.md`) makes a frame the position\n   * `(lineageId, seq)`, and time travel's replay skips any entry whose\n   * `meta.lineageId` names a different lineage. An engine record without it is\n   * a record no frame can address, which is why this is required rather than\n   * optional: the omission used to make `TimeTravel.inspect` fail `not_found`\n   * on every journal the production composition wrote.\n   */\n  readonly lineageId: string\n  /**\n   * The step-cache key whose sealed row holds this record's result, when one\n   * exists. Replay reads it to hand the projection the sealed value instead of\n   * re-deriving it.\n   */\n  readonly cacheKey?: string | undefined\n  /**\n   * What a re-emission of this producer identity means.\n   *\n   * The default, `content`, is the strict reading: the identity names one set\n   * of bytes. `identity` is for a record whose sequence is derived from the\n   * event itself, where a collision IS the same event observed twice and the\n   * bytes that differ are metadata about the observation \u2014 a node settled\n   * `built` by the walk that ran it and `clean` by the resumed walk that\n   * replayed it is one node settling once, seen twice.\n   */\n  readonly dedupe?: JournalEvent.Dedupe | undefined\n}\n\n/**\n * The additive envelope every engine record carries.\n *\n * Kept a plain open record on purpose: `meta` is the journal's forward-compatible\n * side channel, so a consumer that does not know a key ignores it.\n */\nconst meta = (options: EventOptions): Readonly<Record<string, unknown>> => ({\n  lineageId: options.lineageId,\n  ...(options.cacheKey === undefined ? {} : { cacheKey: options.cacheKey })\n})\n\nconst event = (options: EventOptions, eventType: string, payload: unknown): JournalEvent.Input =>\n  new JournalEvent.Input({\n    runId: options.runId as JournalEvent.RunId,\n    sourceId: options.sourceId as JournalEvent.SourceId,\n    ...(options.sourceSeq === undefined ? {} : { sourceSeq: options.sourceSeq as JournalEvent.SourceSeq }),\n    ...(options.dedupe === undefined ? {} : { dedupe: options.dedupe }),\n    eventType,\n    payload,\n    meta: meta(options)\n  })\n\n/**\n * The run's state advanced. Replaying these records in order is how time\n * travel derives the state AT a frame, rather than reading the run row's\n * latest value.\n *\n * @since 0.1.0\n * @category events\n */\nexport const runDecision = (options: EventOptions, payload: unknown) => event(options, EventTypes.runDecision, payload)\n/**\n * An action attempt was admitted and its body is about to run. Paired with\n * {@link attemptFinished}; an unmatched one is crash evidence.\n *\n * @since 0.1.0\n * @category events\n */\nexport const attemptStarted = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.attemptStarted, payload)\n/**\n * An action attempt settled, successfully or not. Closes the span opened by\n * {@link attemptStarted}.\n *\n * @since 0.1.0\n * @category events\n */\nexport const attemptFinished = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.attemptFinished, payload)\n/**\n * A durable deferred was resolved from outside the run. Journaled because the\n * resolution is the only evidence of it \u2014 a replay cannot re-derive a value\n * that arrived over the network. The record names the completion row and the\n * digests of its encoded `exit` and `metadata`; the values stay in the row,\n * because the journal is redacted and replayed to subscribers.\n *\n * @since 0.1.0\n * @category events\n */\nexport const deferredCompleted = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.deferredCompleted, payload)\n/**\n * A run observed a deferred's result, so registration sweeps stop waking it\n * for that result. The result itself stays in its row for replay.\n *\n * @since 1.0.0\n * @category events\n */\nexport const deferredConsumed = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.deferredConsumed, payload)\n/**\n * A durable timer stopped being pending: it fired, or its run settled first.\n * Without it a rebuilt deadline index would re-arm a clock that already\n * completed (issue #2037).\n *\n * @since 1.0.0\n * @category events\n */\nexport const clockCompleted = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.clockCompleted, payload)\n/**\n * The {@link clockCompleted} record for one clock, under the producer identity\n * every completer of that clock shares, so a retried completion collapses.\n *\n * @since 1.0.0\n * @category events\n */\nexport const clockCompletedFor = (\n  journalSource: string,\n  lineageId: string,\n  clock: { readonly flowName: string; readonly executionId: string; readonly clockName: string },\n  completedAtMs: number\n) =>\n  clockCompleted({\n    runId: clock.executionId,\n    lineageId,\n    sourceId: `${journalSource}:clock-completed:${\n      JSON.stringify([clock.flowName, clock.executionId, clock.clockName])\n    }`,\n    sourceSeq: 0\n  }, {\n    flowName: clock.flowName,\n    executionId: clock.executionId,\n    clockName: clock.clockName,\n    completedAtMs\n  })\n/**\n * A durable timer was armed. Journaling the schedule rather than the firing is\n * what lets a resumed run re-arm the same deadline instead of restarting the\n * wait.\n *\n * @since 0.1.0\n * @category events\n */\nexport const clockScheduled = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.clockScheduled, payload)\n/**\n * The run was interrupted \u2014 cancelled, fenced out, or torn down \u2014 as opposed\n * to failing. Recorded so a later reader can tell a cancelled run from a\n * broken one.\n *\n * @since 0.1.0\n * @category events\n */\nexport const interrupted = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.interrupted\", payload)\n/**\n * The jj pointer and plan digest in force at this point in the journal. These\n * are the two tier-2 facts replay cannot derive, which is why the engine emits\n * them and time travel's snapshot projector folds them into frame anchors.\n *\n * @since 0.1.0\n * @category events\n */\nexport const snapshotIdentified = (options: EventOptions, payload: unknown) =>\n  event(options, EventTypes.snapshotIdentified, payload)\n/**\n * A hard-mode step wrote outside its declared write set, so its result was\n * refused. The record is the forensic trail for a declaration that does not\n * match what the step actually does.\n *\n * @since 0.1.0\n * @category events\n */\nexport const hardViolation = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.hard-violation\", payload)\n/**\n * An expected-mode step wrote paths its declaration did not predict. Unlike\n * {@link hardViolation} the result still stands \u2014 the declaration was a\n * prediction, and this is the record of it being wrong.\n *\n * @since 0.1.0\n * @category events\n */\nexport const expectedSetDeviation = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.expected-set-deviation\", payload)\n/**\n * An isolated execution produced a diff bundle: its content address, the paths\n * it changed, and the deviations the declaration did not predict. One of the\n * two record types copy-back writes.\n *\n * It is written once the attempt's copy-back has settled, not before it \u2014 the\n * rebase loop owns the window in between, and a bundle that lost every race\n * was never a proposal the host saw. A crash inside that window leaves the\n * attempt row unfinished, so the replay re-executes and journals the bundle it\n * actually applies. An execution the declaration invalidated journals nothing\n * here at all; its `hard-violation` record carries the identity instead.\n *\n * @since 0.1.0\n * @category events\n */\nexport const diffBundleCaptured = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.diff-bundle-captured\", payload)\n/**\n * A diff bundle reached the host. Carries the rebase count, the deduplicated\n * `queued` effect keys, and the `dispatched` keys the delivery stage sent.\n * `dispatched` is present and empty when no `EffectDispatcher` is composed, so\n * the absence of delivery is a journal fact rather than an inference.\n *\n * @since 0.1.0\n * @category events\n */\nexport const copyBackSettled = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.copy-back-settled\", payload)\n/**\n * A plan was recorded and a run is about to be driven under it. Carries the\n * plan id, its generation-0 digest, and its node count, so\n * `packages/smithers/flows/plan/docs/api.md` asks the audit question, \"show me the plan this ran\n * under\". This record answers it exactly rather than reconstructing it.\n *\n * @since 0.1.0\n * @category events\n */\nexport const planRecorded = (options: EventOptions, payload: EngineEvent.PlanRecordedPayload) =>\n  event(options, EventTypes.planRecorded, payload)\n/**\n * An elaboration appended a pre-keyed subgraph to the SAME plan. The plan\n * grows; it is never invalidated, so this record names the new generation, the\n * advanced digest, and the node ids added \u2014 never a replacement graph.\n *\n * @since 0.1.0\n * @category events\n */\nexport const subgraphAppended = (options: EventOptions, payload: EngineEvent.SubgraphAppendedPayload) =>\n  event(options, EventTypes.subgraphAppended, payload)\n/**\n * A plan node was admitted to the scheduler: its caps and seats allowed it,\n * and its effective priority selected it. Paired with `node-settled`, this is\n * the queue-time evidence the journal measures.\n *\n * @since 0.1.0\n * @category events\n */\nexport const nodeScheduled = (options: EventOptions, payload: EngineEvent.NodeScheduledPayload) =>\n  event(options, \"flows.engine.node-scheduled\", payload)\n/**\n * A plan node reached an evaluation outcome. Skyframe's\n * `EvaluationProgressReceiver.EvaluationState` is the prior art:\n * `SUCCESS_VERSION_CHANGED`/`SUCCESS_VERSION_UNCHANGED` map onto `built`/\n * `clean`, and where Skyframe splits failure by version we use `failed` and\n * `skipped` \u2014 a content-addressed store never serves a failure from cache, so\n * `FAIL_VERSION_UNCHANGED` has no analogue, while a dependent that never ran\n * because its cone failed does. `deferred` is the one outcome outside the\n * Skyframe quadruple: a scheduling debt recorded by probabilistic selection,\n * not an evaluation state.\n *\n * @since 0.1.0\n * @category events\n */\nexport const nodeSettled = (options: EventOptions, payload: EngineEvent.NodeSettledPayload) =>\n  event(options, \"flows.engine.node-settled\", payload)\n/**\n * A scheduled node's dispatch identity was invalidated: its measured inputs no\n * longer match the ones its key was computed from, so it is re-keyed and\n * re-dispatched. Invalidation is re-keying \u2014 there is no dirty bit and no\n * invalidating visitor to journal.\n *\n * @since 0.1.0\n * @category events\n */\nexport const nodeInvalidated = (options: EventOptions, payload: EngineEvent.NodeInvalidatedPayload) =>\n  event(options, \"flows.engine.node-invalidated\", payload)\n/**\n * The reconciliation seam returned a verdict for a deviation or an unabsorbed\n * materialization conflict.\n *\n * @since 0.1.0\n * @category events\n */\nexport const nodeReconciled = (options: EventOptions, payload: EngineEvent.NodeReconciledPayload) =>\n  event(options, \"flows.engine.node-reconciled\", payload)\n/**\n * A selection guess postponed a sink node: it did not execute, wrote no cache\n * row, and this record is the debt \u2014 node id, plan key, the suspected edge,\n * and the likelihood \u2014 that a later guess-free pass repays. `Selection.debt`\n * folds these against {@link nodeSettled} records to list what is still owed.\n *\n * @since 0.1.0\n * @category events\n */\nexport const selectionDeferred = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.selection-deferred\", payload)\n/**\n * A selection guess proposed a flow no real dependency reaches. V1 records\n * and surfaces the proposal; it never auto-appends plan nodes, so this record\n * is the proposal's only artifact.\n *\n * @since 0.1.0\n * @category events\n */\nexport const selectionProposed = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.selection-proposed\", payload)\n/**\n * A run forced full selection: every verdict was treated as `Admit`, the way\n * `--fresh` ignores the cache. Journaled so a report can say the guesses were\n * overridden rather than absent.\n *\n * @since 0.1.0\n * @category events\n */\nexport const selectionOverridden = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.selection-overridden\", payload)\n/**\n * A selection layer returned a Defer or Propose verdict naming a non-sink.\n * The verdict is ignored \u2014 only sinks are deferrable \u2014 and this observation\n * records the layer disagreeing with the plan's shape, in the pattern of\n * Skyframe's `GraphInconsistencyReceiver`: note it, never wire the detector\n * to /dev/null.\n *\n * @since 0.1.0\n * @category events\n */\nexport const selectionInconsistent = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.selection-inconsistent\", payload)\n/**\n * Where a reused result came from: which run first produced it and under which\n * key. A cache hit is otherwise invisible in the journal, and provenance is\n * what makes one auditable after the fact.\n *\n * @since 0.1.0\n * @category events\n */\nexport const cacheProvenance = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.cache-provenance\", payload)\n/**\n * Two runs recorded different results under one step key \u2014 the journaled form\n * of an under-specified declaration.\n *\n * @since 0.1.0\n * @category events\n */\nexport const cacheConflict = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.cache-conflict\", payload)\n/**\n * A cached output failed its digest check and the entry was evicted. Journaled\n * because a repeat is a failing disk, not a coincidence.\n *\n * @since 0.1.0\n * @category events\n */\nexport const cacheCorruption = (options: EventOptions, payload: unknown) =>\n  event(options, \"flows.engine.cache-corruption\", payload)\n\n/**\n * Reads a page of engine records without imposing an agent-shaped event union.\n *\n * @since 0.1.0\n * @category queries\n */\nexport const entries = (runId: string, after: number | undefined, limit: number) =>\n  Effect.flatMap(\n    Journal.Journal,\n    (journal) =>\n      journal.entries({\n        runId: runId as JournalEvent.RunId,\n        ...(after === undefined ? {} : { after: after as JournalEvent.Seq }),\n        limit\n      })\n  )\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/internal/NodeJournal.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The interpreter's node records, as journal entries.
+ *
+ * `@smthrs/flow` builds a record for the graph it drove and for every node it
+ * scheduled and settled, and says nothing about where they go. This module is
+ * the durable store's answer: one journal entry per record, addressed by the
+ * record's own `sourceId`, typed by the payload schemas `@smthrs/journal`
+ * publishes, and carrying the same event types the plan scheduler writes so a
+ * reader folds both executors with one decoder.
+ *
+ * Two facts live here rather than in the interpreter. The journal's producer
+ * identity is `(runId, sourceId, sourceSeq)`, so a resumed walk that
+ * re-derives the same `sourceId` collapses onto the row the first walk wrote:
+ * that is the exactly-once contract, and it holds because the identity is the
+ * record's, never a fresh one minted per observation. And a declaration site
+ * is made repo-relative here, because only the writer knows the root: a
+ * journal is read on machines that did not write it, and an absolute path is
+ * at best noise and at worst an operator's home directory published into a
+ * run's history.
+ *
+ * @since 0.1.0
+ */
+import type { FlowRuntime } from "@smthrs/flow";
+import { JournalEvent } from "@smthrs/journal";
+/**
+ * Where the records of one run are addressed from.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface Scope {
+    readonly runId: string;
+    /** The host's journal source, which every record of this run hangs under. */
+    readonly sourceId: string;
+    readonly lineageId: string;
+    /**
+     * The directory a declaration path is made relative to, when one is known.
+     *
+     * `undefined` means no path is recorded at all. That is the honest answer
+     * for a host that cannot say where its sources live, and it is better than
+     * a path a reader would have to guess the meaning of.
+     */
+    readonly root?: string | undefined;
+    /**
+     * The revision the sources those declaration paths point into were read
+     * at, when the host can name one.
+     *
+     * It lives here for the reason `root` does: a journal is read on machines
+     * that did not write it, and only the writer knows which tree it loaded.
+     * A path alone says where a node was declared and never which bytes were
+     * at that line, so a reader without this opens no code at all rather than
+     * whatever the working tree holds when they look (D-068).
+     */
+    readonly sourceRevision?: string | undefined;
+}
+/**
+ * A declaration path as a journal may carry it: relative to the root, or
+ * nothing.
+ *
+ * The rule lives with the schema that refuses an absolute path
+ * (`@smthrs/journal`'s `EngineEvent.DeclaredAt`), so every writer of a
+ * declaration site obeys it the same way. It is named here because this is
+ * the module that applies it, and because the store's own tests are written
+ * against it.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const relativePath: (root: string | undefined, path: string) => string | undefined;
+/**
+ * The directory declaration paths are recorded relative to.
+ *
+ * `process` is absent in a worker and in a browser, and a host that cannot
+ * name its own working directory records no declaration path at all rather
+ * than one a reader would have to guess the meaning of. `host` is the global
+ * object by default and is named here so both answers are reachable without
+ * taking the real one away from the runtime.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const hostRoot: (explicit: string | undefined, host?: {
+    readonly process?: {
+        readonly cwd?: () => string;
+    } | undefined;
+}) => string | undefined;
+/**
+ * How many bytes of a node's settled value a journal row keeps.
+ *
+ * A node record is a small row beside the plan record's 12,000-byte page
+ * budget, and it is written once per node of every graph: a value kept whole
+ * would put an agent transcript in a permanent row and a projection would
+ * clip it without saying so. Two kibibytes is enough to read what a node
+ * produced and small enough that the settlement stays a summary.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const maximumResultBytes = 2048;
+/**
+ * How large a settled value may be before it is summarized at all.
+ *
+ * Redacting a value rebuilds every member of it and runs the textual rules
+ * over every string, on the journal write path, for every node of every
+ * graph. Past this ceiling the walk is the cost rather than the row, and the
+ * honest answer is the size alone: the encoding is measured, `preview` is
+ * empty, and `truncated` says the text was cut to nothing. Anything below it
+ * is redacted whole and then cut.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export declare const maximumSummarizedBytes = 65536;
+/**
+ * What a node settled with, redacted and then bounded.
+ *
+ * REDACTION COMES FIRST. `Redaction.redact` is the journal's own write-path
+ * scrubber, and it is the one that reads a field NAME: `{ apiKey: "sk-..." }`
+ * is a credential because of the key, which no rule over encoded text can see
+ * once the value is a string inside a larger string. Running it over the
+ * decoded value also collapses cycles and names functions, so the encoding
+ * that follows always succeeds. Cutting the text first would be worse than
+ * useless: a credential split across the boundary is a credential the textual
+ * rules no longer recognise, and half of it would be kept.
+ *
+ * A value that will not encode even after redaction — a bigint, a value whose
+ * own `toJSON` throws — gets no summary at all rather than a fabricated one.
+ *
+ * `bytes` is the size of the encoding `preview` was cut from, which for a
+ * value past {@link maximumSummarizedBytes} is the value's own encoding: that
+ * branch keeps nothing, so there is no second number to disagree with.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const resultSummary: (value: unknown) => {
+    readonly preview: string;
+    readonly bytes: number;
+    readonly truncated: boolean;
+} | undefined;
+/**
+ * The journal entry one node record is written as.
+ *
+ * @since 0.1.0
+ * @category constructors
+ */
+export declare const entry: (scope: Scope, record: FlowRuntime.NodeRecord) => JournalEvent.Input;
+/**
+ * UTF-8 upper bound for the durable entry, including allocated envelope fields.
+ *
+ * Sequence/time reserve their largest JSON encodings so page boundaries never
+ * depend on the current journal position or clock, including after a resume.
+ * @since 1.0.0
+ * @category accessors
+ */
+export declare const encodedBytes: (scope: Scope, record: FlowRuntime.NodeRecord) => number;
+//# sourceMappingURL=NodeJournal.d.ts.map

package/dist/cjs/internal/NodeJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeJournal.d.ts","sourceRoot":"","sources":["../../../src/internal/NodeJournal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EAAe,YAAY,EAAa,MAAM,iBAAiB,CAAA;AAItE;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7C;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,gEAA2B,CAAA;AAapD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,GACnB,UAAU,MAAM,GAAG,SAAS,EAC5B,OAAM;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CAAe,KACpF,MAAM,GAAG,SAGX,CAAA;AAsBD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,OAAQ,CAAA;AAEvC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,QAAS,CAAA;AA2C5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B,GAAG,SA2BH,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,KAAK,EAAE,QAAQ,WAAW,CAAC,UAAU,KAAG,YAAY,CAAC,KA0DjF,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,EAAE,QAAQ,WAAW,CAAC,UAAU,KAAG,MAc3E,CAAA"}