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

package/dist/cjs/EngineEvent.d.ts

@@ -0,0 +1,890 @@
+/**
+ * Versioned engine history contracts over the open journal. These schemas do
+ * not change journal admission or make history the engine's recovery store.
+ *
+ * @since 1.0.0
+ */
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Event from "./JournalEvent.ts";
+/**
+ * Required lineage coordinates for a root or derived run.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Lineage: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"root">;
+    readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    readonly lineageId: Schema.brand<Schema.String, "@smthrs/journal/LineageId">;
+    readonly rootRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    readonly round: Schema.Literal<0>;
+    readonly parentRunId: Schema.Null;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["child", "fork", "continuation"]>;
+    readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    readonly lineageId: Schema.brand<Schema.String, "@smthrs/journal/LineageId">;
+    readonly rootRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    readonly round: Schema.Int;
+    readonly parentRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+}>]>;
+/**
+ * Required lineage coordinates for a root or derived run.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Lineage = typeof Lineage.Type;
+/**
+ * Encoded values only: class instances must first pass their own codec.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Success: Schema.TaggedStruct<"Success", {
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * Failure channels stay distinct, including interruption and encoding failure.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Failure: Schema.TaggedStruct<"Failure", {
+    readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+    readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * Encoded success or a classified failure.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const ResultEnvelope: Schema.Union<readonly [Schema.TaggedStruct<"Success", {
+    readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, Schema.TaggedStruct<"Failure", {
+    readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+    readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>]>;
+/**
+ * Encoded success or a classified failure.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type ResultEnvelope = typeof ResultEnvelope.Type;
+/**
+ * Completion and its outcome are inseparable; live states cannot carry either.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const AttemptLifecycle: Schema.Union<readonly [Schema.Struct<{
+    readonly heartbeatAtMs: Schema.optionalKey<Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">>;
+    readonly checkpoint: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly finishedAtMs: Schema.optionalKey<Schema.Never>;
+    readonly result: Schema.optionalKey<Schema.Never>;
+    readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    readonly state: Schema.Literal<"running">;
+}>, Schema.Struct<{
+    readonly heartbeatAtMs: Schema.optionalKey<Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">>;
+    readonly checkpoint: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly finishedAtMs: Schema.optionalKey<Schema.Never>;
+    readonly result: Schema.optionalKey<Schema.Never>;
+    readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    readonly state: Schema.Literal<"suspended">;
+}>, Schema.Struct<{
+    readonly finishedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    readonly result: Schema.TaggedStruct<"Success", {
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>;
+    readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    readonly state: Schema.Literal<"succeeded">;
+}>, Schema.Struct<{
+    readonly finishedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    readonly result: Schema.TaggedStruct<"Failure", {
+        readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+        readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>;
+    readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    readonly state: Schema.Literal<"failed">;
+}>]>;
+/**
+ * Wall clocks can move backwards; completion need not be after start.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type AttemptLifecycle = typeof AttemptLifecycle.Type;
+/**
+ * Complete identity and state of one versioned attempt event.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const AttemptPayload: Schema.Struct<{
+    readonly version: Schema.Literal<2>;
+    readonly lineage: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"root">;
+        readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly lineageId: Schema.brand<Schema.String, "@smthrs/journal/LineageId">;
+        readonly rootRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly round: Schema.Literal<0>;
+        readonly parentRunId: Schema.Null;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["child", "fork", "continuation"]>;
+        readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly lineageId: Schema.brand<Schema.String, "@smthrs/journal/LineageId">;
+        readonly rootRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly round: Schema.Int;
+        readonly parentRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    }>]>;
+    readonly executionId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    readonly stepKeyDigest: Schema.brand<Schema.String, "@smthrs/journal/DispatchId">;
+    readonly attempt: Schema.Int;
+    readonly lifecycle: Schema.Union<readonly [Schema.Struct<{
+        readonly heartbeatAtMs: Schema.optionalKey<Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">>;
+        readonly checkpoint: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly finishedAtMs: Schema.optionalKey<Schema.Never>;
+        readonly result: Schema.optionalKey<Schema.Never>;
+        readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+        readonly state: Schema.Literal<"running">;
+    }>, Schema.Struct<{
+        readonly heartbeatAtMs: Schema.optionalKey<Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">>;
+        readonly checkpoint: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly finishedAtMs: Schema.optionalKey<Schema.Never>;
+        readonly result: Schema.optionalKey<Schema.Never>;
+        readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+        readonly state: Schema.Literal<"suspended">;
+    }>, Schema.Struct<{
+        readonly finishedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+        readonly result: Schema.TaggedStruct<"Success", {
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>;
+        readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+        readonly state: Schema.Literal<"succeeded">;
+    }>, Schema.Struct<{
+        readonly finishedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+        readonly result: Schema.TaggedStruct<"Failure", {
+            readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+            readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>;
+        readonly startedAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+        readonly state: Schema.Literal<"failed">;
+    }>]>;
+}>;
+/**
+ * Complete identity and state of one versioned attempt event.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type AttemptPayload = typeof AttemptPayload.Type;
+/**
+ * Durable wait identities; ownership and cancellation remain independent facts.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const Wait: Schema.Union<readonly [Schema.TaggedStruct<"Deferred", {
+    readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+}>, Schema.TaggedStruct<"Clock", {
+    readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+    readonly dueAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+}>]>;
+/**
+ * A complete execution observation, without operational ownership leases.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const ExecutionLifecycle: Schema.Union<readonly [Schema.Struct<{
+    readonly state: Schema.Literal<"running">;
+    readonly waits: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Deferred", {
+        readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+    }>, Schema.TaggedStruct<"Clock", {
+        readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+        readonly dueAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    }>]>>;
+}>, Schema.Struct<{
+    readonly state: Schema.Literal<"suspended">;
+    readonly waits: Schema.NonEmptyArray<Schema.Union<readonly [Schema.TaggedStruct<"Deferred", {
+        readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+    }>, Schema.TaggedStruct<"Clock", {
+        readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+        readonly dueAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    }>]>>;
+}>, Schema.Struct<{
+    readonly state: Schema.Literal<"completed">;
+    readonly result: Schema.Union<readonly [Schema.TaggedStruct<"Success", {
+        readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, Schema.TaggedStruct<"Failure", {
+        readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+        readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>]>;
+}>]>;
+/**
+ * Versioned execution, deferred and clock observations. Every variant records
+ * its semantic identity and encoded value independently of diagnostics.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const StatePayload: Schema.Struct<{
+    readonly version: Schema.Literal<2>;
+    readonly lineage: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"root">;
+        readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly lineageId: Schema.brand<Schema.String, "@smthrs/journal/LineageId">;
+        readonly rootRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly round: Schema.Literal<0>;
+        readonly parentRunId: Schema.Null;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literals<readonly ["child", "fork", "continuation"]>;
+        readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly lineageId: Schema.brand<Schema.String, "@smthrs/journal/LineageId">;
+        readonly rootRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly round: Schema.Int;
+        readonly parentRunId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    }>]>;
+    readonly executionId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+    readonly event: Schema.Union<readonly [Schema.TaggedStruct<"Execution", {
+        readonly lifecycle: Schema.Union<readonly [Schema.Struct<{
+            readonly state: Schema.Literal<"running">;
+            readonly waits: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Deferred", {
+                readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+            }>, Schema.TaggedStruct<"Clock", {
+                readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+                readonly dueAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+            }>]>>;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"suspended">;
+            readonly waits: Schema.NonEmptyArray<Schema.Union<readonly [Schema.TaggedStruct<"Deferred", {
+                readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+            }>, Schema.TaggedStruct<"Clock", {
+                readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+                readonly dueAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+            }>]>>;
+        }>, Schema.Struct<{
+            readonly state: Schema.Literal<"completed">;
+            readonly result: Schema.Union<readonly [Schema.TaggedStruct<"Success", {
+                readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            }>, Schema.TaggedStruct<"Failure", {
+                readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+                readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            }>]>;
+        }>]>;
+    }>, Schema.TaggedStruct<"DeferredCompleted", {
+        readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+        readonly result: Schema.Union<readonly [Schema.TaggedStruct<"Success", {
+            readonly value: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>, Schema.TaggedStruct<"Failure", {
+            readonly reason: Schema.Literals<readonly ["error", "defect", "interrupted", "encoding"]>;
+            readonly detail: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>]>;
+    }>, Schema.TaggedStruct<"ClockScheduled", {
+        readonly clockId: Schema.brand<Schema.String, "@smthrs/journal/CommandId">;
+        readonly waitId: Schema.brand<Schema.String, "@smthrs/journal/WaitId">;
+        readonly dueAtMs: Schema.brand<Schema.Int, "@smthrs/journal/TimestampMs">;
+    }>]>;
+}>;
+/**
+ * Versioned execution, deferred and clock observations.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type StatePayload = typeof StatePayload.Type;
+/**
+ * Event family for complete execution, deferred and clock observations.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const stateEventType = "flows.engine.v2.state-event";
+/**
+ * New identity prevents old readers mistaking complete state for historical markers.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const attemptEventType = "flows.engine.v2.attempt-lifecycle";
+declare const EventError_base: Schema.Class<EventError, Schema.TaggedStruct<"@smthrs/journal/EngineEventError", {
+    readonly code: Schema.Literals<readonly ["malformed", "unsupported", "foreign", "transition"]>;
+    readonly message: Schema.String;
+    readonly cause: Schema.Unknown;
+}>, Cause.YieldableError>;
+/**
+ * Malformed, foreign, unsupported or inconsistent event evidence.
+ *
+ * @category errors
+ * @since 1.0.0
+ */
+export declare class EventError extends EventError_base {
+}
+/**
+ * Every consumer chooses its source allowlist and unknown-namespace policy.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface Consumer {
+    readonly runId: Event.RunId;
+    readonly lineageId: Event.LineageId;
+    readonly rootRunId: Event.RunId;
+    readonly round: number;
+    readonly parentRunId: Event.RunId | null;
+    readonly sources: ReadonlyArray<Event.SourceId>;
+    readonly unknown: "ignore" | "surface";
+}
+/**
+ * A known event or the explicitly selected extension outcome.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Decoded = {
+    readonly _tag: "Attempt";
+    readonly entry: Event.Entry;
+    readonly payload: AttemptPayload;
+} | {
+    readonly _tag: "State";
+    readonly entry: Event.Entry;
+    readonly payload: StatePayload;
+} | {
+    readonly _tag: "Ignored";
+} | {
+    readonly _tag: "Unknown";
+    readonly entry: Event.Entry;
+};
+/**
+ * Decode untrusted committed input. Unknown events in the known engine namespace
+ * are unsupported errors, never ignored. Original schema/accessor errors stay
+ * in cause; foreign identity includes the conflicting evidence in cause.
+ *
+ * @category decoders
+ * @since 1.0.0
+ */
+export declare const decodeEntry: (input: unknown, consumer: Consumer) => Effect.Effect<Decoded, EventError>;
+/**
+ * Construct a versioned submission, validating before journal redaction.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const attempt: (payload: AttemptPayload, sourceId: Event.SourceId, sourceSeq: Event.SourceSeq, diagnostics?: Schema.Json) => Event.Input;
+/**
+ * Construct a versioned execution, deferred or clock submission. Existing
+ * unversioned writers are unchanged and cannot manufacture missing lineage.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const stateEvent: (payload: StatePayload, sourceId: Event.SourceId, sourceSeq: Event.SourceSeq, diagnostics?: Schema.Json) => Event.Input;
+/**
+ * Historical attempt markers deliberately remain incomplete evidence. No
+ * result, timestamp, round or lineage root is invented for old rows.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const CurrentAttempt: Schema.Union<readonly [Schema.Struct<{
+    readonly eventType: Schema.Literal<"flows.engine.attempt-started">;
+    readonly payload: Schema.Struct<{
+        readonly version: Schema.optionalKey<Schema.Never>;
+        readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly stepKeyDigest: Schema.brand<Schema.String, "@smthrs/journal/DispatchId">;
+        readonly attempt: Schema.Int;
+        readonly tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+    }>;
+}>, Schema.Struct<{
+    readonly eventType: Schema.Literal<"flows.engine.attempt-finished">;
+    readonly payload: Schema.Struct<{
+        readonly version: Schema.optionalKey<Schema.Never>;
+        readonly runId: Schema.brand<Schema.String, "@smthrs/journal/JournalEvent/RunId">;
+        readonly stepKeyDigest: Schema.brand<Schema.String, "@smthrs/journal/DispatchId">;
+        readonly attempt: Schema.Int;
+        readonly state: Schema.Literals<readonly ["succeeded", "failed"]>;
+    }>;
+}>]>;
+/**
+ * Decode current markers using their recorded lineage, without upgrading bytes.
+ *
+ * @category decoders
+ * @since 1.0.0
+ */
+export declare const decodeCurrentAttempt: (input: unknown, consumer: Consumer) => Effect.Effect<{
+    entry: Event.Entry;
+    marker: {
+        readonly eventType: "flows.engine.attempt-started";
+        readonly payload: {
+            readonly runId: string & import("effect/Brand").Brand<"@smthrs/journal/JournalEvent/RunId">;
+            readonly stepKeyDigest: string & import("effect/Brand").Brand<"@smthrs/journal/DispatchId">;
+            readonly attempt: number;
+            readonly tier: "sealed" | "compensable" | "irreversible";
+            readonly version?: never;
+        };
+    } | {
+        readonly eventType: "flows.engine.attempt-finished";
+        readonly payload: {
+            readonly runId: string & import("effect/Brand").Brand<"@smthrs/journal/JournalEvent/RunId">;
+            readonly state: "succeeded" | "failed";
+            readonly stepKeyDigest: string & import("effect/Brand").Brand<"@smthrs/journal/DispatchId">;
+            readonly attempt: number;
+            readonly version?: never;
+        };
+    };
+    lineageId: string & import("effect/Brand").Brand<"@smthrs/journal/LineageId">;
+}, EventError, never>;
+/**
+ * Where a declaration was written, as a durable record may carry it.
+ *
+ * Repo-relative by contract: a journal is read on machines that are not the
+ * one that wrote it, so an absolute path is at best noise and at worst an
+ * operator's home directory published into a run's history. A writer that
+ * cannot make a path relative omits the field.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const DeclaredAt: Schema.Struct<{
+    readonly path: Schema.NonEmptyString;
+    readonly line: Schema.Int;
+}>;
+/**
+ * A declaration path as {@link DeclaredAt} may carry it: relative to the
+ * root, or nothing.
+ *
+ * It lives beside the schema that refuses an absolute path, because obeying
+ * that refusal is the writer's one job and every writer obeys it the same
+ * way. A path outside the root is omitted rather than recorded with `..`
+ * segments, because a reader resolving those would have to know the root,
+ * which is exactly the machine-specific fact this strips. A root that is the
+ * filesystem itself strips nothing, so it is read as no root.
+ *
+ * @category accessors
+ * @since 1.0.0
+ */
+export declare const relativePath: (root: string | undefined, path: string) => string | undefined;
+/**
+ * One node of the graph a run was driven from.
+ *
+ * `kind` is open text because the two executors name kinds differently and
+ * both are true: the plan scheduler's node is a `step`, an `agent` or a
+ * `merge`, while the interpreter's is the authoring variant it was observed
+ * at. A closed union here would force one of them to lie.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeSummary: Schema.Struct<{
+    readonly id: Schema.NonEmptyString;
+    readonly kind: Schema.String;
+    readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
+    readonly tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+    readonly key: Schema.optionalKey<Schema.String>;
+    readonly generation: Schema.optionalKey<Schema.Int>;
+    readonly action: Schema.optionalKey<Schema.String>;
+    readonly effects: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly declaredAt: Schema.optionalKey<Schema.Struct<{
+        readonly path: Schema.NonEmptyString;
+        readonly line: Schema.Int;
+    }>>;
+}>;
+/**
+ * One edge of that graph, with the reason the builder drew it.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const EdgeSummary: Schema.Struct<{
+    readonly from: Schema.NonEmptyString;
+    readonly to: Schema.NonEmptyString;
+    readonly reason: Schema.Literals<readonly ["value", "continuation", "failure"]>;
+}>;
+/**
+ * The immutable name of a tree a host read declaration sites out of.
+ *
+ * Exactly the forty lowercase hex digits the only producer emits: a jj
+ * working-copy commit id, or a git commit for a tree that still matches one
+ * (`SourceRevision.objectId`). It is narrowed here rather than left as text
+ * because a reader puts it straight into a contents route's `?ref=`, and
+ * `DeclaredAt` beside it refuses an absolute path for the same class of
+ * reason: a field that only ever holds one shape should refuse the others at
+ * the boundary rather than at whatever spawns a process downstream.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const SourceRevision: Schema.NonEmptyString;
+/**
+ * The graph, or one page of it, carried beside a plan record.
+ *
+ * `edges` is optional because only one writer can answer it honestly. A plan
+ * names its edges through each node's `dependsOn` and knows no reason for
+ * them; an interpreter knows the reason it drew each one. A writer without
+ * reasons omits the field rather than labelling every edge `value`.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeGraph: Schema.Struct<{
+    readonly nodes: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.NonEmptyString;
+        readonly kind: Schema.String;
+        readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
+        readonly tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+        readonly key: Schema.optionalKey<Schema.String>;
+        readonly generation: Schema.optionalKey<Schema.Int>;
+        readonly action: Schema.optionalKey<Schema.String>;
+        readonly effects: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly declaredAt: Schema.optionalKey<Schema.Struct<{
+            readonly path: Schema.NonEmptyString;
+            readonly line: Schema.Int;
+        }>>;
+    }>>;
+    readonly edges: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly from: Schema.NonEmptyString;
+        readonly to: Schema.NonEmptyString;
+        readonly reason: Schema.Literals<readonly ["value", "continuation", "failure"]>;
+    }>>>;
+    /**
+     * The revision of the tree the nodes on this page were read out of.
+     *
+     * A `declaredAt` is a path and a line, and neither says which bytes were
+     * at that line: a working tree moves, so the same path after an edit or a
+     * branch switch is a different file. Only the writer can answer this —
+     * like the root a path is made relative to — so it travels with the page
+     * the sites travel on, and a reader can ask for the file AT this revision
+     * instead of whatever is on disk when they look.
+     *
+     * Optional because only a writer served out of a version-controlled tree
+     * can name one. A writer that cannot says nothing, and a reader that has
+     * nothing shows no code rather than code it cannot bind (D-068).
+     */
+    readonly sourceRevision: Schema.optionalKey<Schema.NonEmptyString>;
+}>;
+/**
+ * A plan was recorded and a run is about to be driven under it.
+ *
+ * `nodes` is the node COUNT the record has always carried. The node list
+ * arrives beside it as `graph`, optional and paged, because a journal entry
+ * has a byte bound: what does not fit follows as {@link SubgraphAppended}
+ * pages rather than being clipped.
+ *
+ * Everything an executor cannot honestly answer is optional rather than
+ * invented. The interpreter drives a graph with no plan id, no plan digest
+ * and no store to record an outcome with, and saying so is the point of this
+ * schema.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const PlanRecordedPayload: Schema.Struct<{
+    readonly planId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly flow: Schema.NonEmptyString;
+    readonly digest: Schema.optionalKey<Schema.String>;
+    readonly baseDigest: Schema.optionalKey<Schema.String>;
+    readonly generation: Schema.Int;
+    readonly nodes: Schema.Int;
+    readonly outcome: Schema.optionalKey<Schema.String>;
+    readonly page: Schema.optionalKey<Schema.Int>;
+    readonly pages: Schema.optionalKey<Schema.Int>;
+    readonly graph: Schema.optionalKey<Schema.Struct<{
+        readonly nodes: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.NonEmptyString;
+            readonly kind: Schema.String;
+            readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
+            readonly tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+            readonly key: Schema.optionalKey<Schema.String>;
+            readonly generation: Schema.optionalKey<Schema.Int>;
+            readonly action: Schema.optionalKey<Schema.String>;
+            readonly effects: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly declaredAt: Schema.optionalKey<Schema.Struct<{
+                readonly path: Schema.NonEmptyString;
+                readonly line: Schema.Int;
+            }>>;
+        }>>;
+        readonly edges: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly from: Schema.NonEmptyString;
+            readonly to: Schema.NonEmptyString;
+            readonly reason: Schema.Literals<readonly ["value", "continuation", "failure"]>;
+        }>>>;
+        /**
+         * The revision of the tree the nodes on this page were read out of.
+         *
+         * A `declaredAt` is a path and a line, and neither says which bytes were
+         * at that line: a working tree moves, so the same path after an edit or a
+         * branch switch is a different file. Only the writer can answer this —
+         * like the root a path is made relative to — so it travels with the page
+         * the sites travel on, and a reader can ask for the file AT this revision
+         * instead of whatever is on disk when they look.
+         *
+         * Optional because only a writer served out of a version-controlled tree
+         * can name one. A writer that cannot says nothing, and a reader that has
+         * nothing shows no code rather than code it cannot bind (D-068).
+         */
+        readonly sourceRevision: Schema.optionalKey<Schema.NonEmptyString>;
+    }>>;
+}>;
+/**
+ * An elaboration appended a pre-keyed subgraph to the same plan, or the next
+ * page of a graph too large for one record.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const SubgraphAppendedPayload: Schema.Struct<{
+    readonly planId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly flow: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly digest: Schema.optionalKey<Schema.String>;
+    readonly baseDigest: Schema.optionalKey<Schema.String>;
+    readonly generation: Schema.Int;
+    readonly nodeIds: Schema.$Array<Schema.NonEmptyString>;
+    readonly page: Schema.optionalKey<Schema.Int>;
+    readonly pages: Schema.optionalKey<Schema.Int>;
+    readonly graph: Schema.optionalKey<Schema.Struct<{
+        readonly nodes: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.NonEmptyString;
+            readonly kind: Schema.String;
+            readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
+            readonly tier: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+            readonly key: Schema.optionalKey<Schema.String>;
+            readonly generation: Schema.optionalKey<Schema.Int>;
+            readonly action: Schema.optionalKey<Schema.String>;
+            readonly effects: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            readonly declaredAt: Schema.optionalKey<Schema.Struct<{
+                readonly path: Schema.NonEmptyString;
+                readonly line: Schema.Int;
+            }>>;
+        }>>;
+        readonly edges: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly from: Schema.NonEmptyString;
+            readonly to: Schema.NonEmptyString;
+            readonly reason: Schema.Literals<readonly ["value", "continuation", "failure"]>;
+        }>>>;
+        /**
+         * The revision of the tree the nodes on this page were read out of.
+         *
+         * A `declaredAt` is a path and a line, and neither says which bytes were
+         * at that line: a working tree moves, so the same path after an edit or a
+         * branch switch is a different file. Only the writer can answer this —
+         * like the root a path is made relative to — so it travels with the page
+         * the sites travel on, and a reader can ask for the file AT this revision
+         * instead of whatever is on disk when they look.
+         *
+         * Optional because only a writer served out of a version-controlled tree
+         * can name one. A writer that cannot says nothing, and a reader that has
+         * nothing shows no code rather than code it cannot bind (D-068).
+         */
+        readonly sourceRevision: Schema.optionalKey<Schema.NonEmptyString>;
+    }>>;
+}>;
+/**
+ * A plan node was admitted and its work is about to start.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeScheduledPayload: Schema.Struct<{
+    readonly planId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly nodeId: Schema.NonEmptyString;
+    readonly kind: Schema.String;
+    readonly planKey: Schema.optionalKey<Schema.String>;
+    readonly dispatchKey: Schema.optionalKey<Schema.String>;
+    readonly attempt: Schema.Int;
+    readonly priority: Schema.optionalKey<Schema.Int>;
+    readonly waited: Schema.optionalKey<Schema.Int>;
+    readonly action: Schema.optionalKey<Schema.String>;
+}>;
+/**
+ * A bounded look at what a node settled with.
+ *
+ * `preview` is JSON text, redacted before it was encoded and cut to a fixed
+ * ceiling afterwards, so a long value costs a durable row a known number of
+ * bytes rather than however many it happens to hold. `truncated` says the cut
+ * happened, which is also the warning that the text is a PREFIX of JSON and
+ * no longer parses. `bytes` is the size of the encoding the preview was cut
+ * from, so a reader can say how much was left out without being shown it; a
+ * value too large for a writer to redact at all is named by the size of its
+ * own encoding, with an empty preview and the flag set.
+ *
+ * Redaction comes first and truncation second on purpose: cutting the text
+ * first can split a credential across the boundary, and a textual redactor
+ * scanning the remains would no longer recognise it.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeResultSummary: Schema.Struct<{
+    readonly preview: Schema.String;
+    readonly bytes: Schema.Int;
+    readonly truncated: Schema.Boolean;
+}>;
+/**
+ * A plan node reached an outcome.
+ *
+ * The outcomes are Skyframe's evaluation states: `built` ran,
+ * `clean` was served from records, `failed` raised, `skipped` was never
+ * reached, and `deferred` is a scheduling debt the plan scheduler alone
+ * records.
+ *
+ * `attempts` is the executor's own count. For the plan scheduler it is the
+ * node's; for the interpreter it is the highest durable attempt any of this
+ * node's dispatches ran as, because the interpreter settles each node once
+ * and a retry happens underneath it inside one dispatch.
+ *
+ * `stepKeyDigests` names the dispatches the node drove, and it is the join
+ * `flows.engine.attempt-started` could not make on its own: an attempt record
+ * carries a step key digest and no node id, so an attempt belongs to the node
+ * whose settlement claims its digest. A retried dispatch keeps ONE digest —
+ * the attempt is folded into no key — so the list is distinct dispatches, not
+ * attempts. A writer that derives no digests omits the field; a node that
+ * dispatched nothing records an empty list, which is a different statement.
+ *
+ * `result` is what the node settled with: the success value for `built` and
+ * `clean`, the typed failure for `failed`, bounded and redacted by the writer.
+ * Absent when the writer kept none.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeSettledPayload: Schema.Struct<{
+    readonly planId: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly nodeId: Schema.NonEmptyString;
+    readonly planKey: Schema.optionalKey<Schema.String>;
+    readonly dispatchKey: Schema.optionalKey<Schema.String>;
+    readonly stepKeyDigests: Schema.optionalKey<Schema.$Array<Schema.NonEmptyString>>;
+    readonly outcome: Schema.Literals<readonly ["built", "clean", "failed", "skipped", "deferred"]>;
+    readonly attempts: Schema.Int;
+    readonly rebases: Schema.optionalKey<Schema.Int>;
+    readonly action: Schema.optionalKey<Schema.String>;
+    readonly result: Schema.optionalKey<Schema.Struct<{
+        readonly preview: Schema.String;
+        readonly bytes: Schema.Int;
+        readonly truncated: Schema.Boolean;
+    }>>;
+}>;
+/**
+ * A scheduled node's dispatch identity was invalidated and re-keyed.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeInvalidatedPayload: Schema.Struct<{
+    readonly planId: Schema.NonEmptyString;
+    readonly nodeId: Schema.NonEmptyString;
+    readonly planKey: Schema.String;
+    readonly from: Schema.String;
+    readonly to: Schema.String;
+    readonly reason: Schema.Literal<"measured-inputs-changed">;
+}>;
+/**
+ * The reconciliation seam returned a verdict for a deviation.
+ *
+ * @category schemas
+ * @since 1.0.0
+ */
+export declare const NodeReconciledPayload: Schema.Struct<{
+    readonly planId: Schema.NonEmptyString;
+    readonly nodeId: Schema.NonEmptyString;
+    readonly trigger: Schema.String;
+    readonly verdict: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+/**
+ * Where a declaration was written, as a durable record carries it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type DeclaredAt = typeof DeclaredAt.Type;
+/**
+ * One node of the graph a run was driven from.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeSummary = typeof NodeSummary.Type;
+/**
+ * One edge of the graph a run was driven from.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type EdgeSummary = typeof EdgeSummary.Type;
+/**
+ * The graph, or one page of it, carried beside a plan record.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeGraph = typeof NodeGraph.Type;
+/**
+ * A plan was recorded and a run is about to be driven under it.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type PlanRecordedPayload = typeof PlanRecordedPayload.Type;
+/**
+ * An elaboration appended a subgraph, or the next page of a large graph.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type SubgraphAppendedPayload = typeof SubgraphAppendedPayload.Type;
+/**
+ * A plan node was admitted and its work is about to start.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeScheduledPayload = typeof NodeScheduledPayload.Type;
+/**
+ * A bounded look at what a node settled with.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeResultSummary = typeof NodeResultSummary.Type;
+/**
+ * A plan node reached an outcome.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeSettledPayload = typeof NodeSettledPayload.Type;
+/**
+ * A scheduled node's dispatch identity was invalidated and re-keyed.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeInvalidatedPayload = typeof NodeInvalidatedPayload.Type;
+/**
+ * The reconciliation seam's verdict for one deviation.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type NodeReconciledPayload = typeof NodeReconciledPayload.Type;
+/**
+ * The event type each node and plan payload is recorded under.
+ *
+ * Readers and writers share these identities, so a value here is stored
+ * history and changing one requires migrating it.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export declare const nodeEventTypes: {
+    readonly planRecorded: "flows.engine.plan-recorded";
+    readonly subgraphAppended: "flows.engine.subgraph-appended";
+    readonly nodeScheduled: "flows.engine.node-scheduled";
+    readonly nodeSettled: "flows.engine.node-settled";
+    readonly nodeInvalidated: "flows.engine.node-invalidated";
+    readonly nodeReconciled: "flows.engine.node-reconciled";
+};
+export {};
+//# sourceMappingURL=EngineEvent.d.ts.map