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

package/dist/esm/Placement.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Where a node runs, declared.
+ *
+ * This is the ONE placement model. `@smthrs/core` re-exports it, `@smthrs/flow`
+ * annotates with it, and `@smthrs/registry` lowers a descriptor's frontmatter
+ * literal into it. It used to be a typed enum in `@smthrs/core` and an opaque
+ * `Schema.Unknown` in `@smthrs/flow`, with a cast in the registry standing
+ * between them, so a directive lost its type the moment it crossed a package.
+ *
+ * It lives here because `KeyMaterial.placement` is the field it ends up in, and
+ * `@smthrs/plan` is the lowest package core, flow and the registry all depend
+ * on. A placement is serializable detail that identifies a host profile; it
+ * never contains a host implementation, credentials, or any other runtime
+ * handle.
+ *
+ * The four tags still read `flows/core/Placement/...`. They are hashed into
+ * `KeyMaterial.placement` and therefore into the step key of every node that
+ * declares a placement, so retagging them would re-key production work and
+ * miss its cached results. The tag is a wire value, not a location.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+/**
+ * Serializable host-selection details. These fields identify a host profile;
+ * they never contain a host implementation, credentials, or other runtime
+ * handle.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Options {
+    readonly image?: string | undefined;
+    readonly profile?: string | undefined;
+    readonly target?: string | undefined;
+}
+/**
+ * A serializable directive describing where a flow node should run.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type Placement = Data.TaggedEnum<{
+    readonly "flows/core/Placement/Local": Readonly<Record<never, never>>;
+    readonly "flows/core/Placement/Client": Readonly<Record<never, never>>;
+    readonly "flows/core/Placement/Sandbox": Options;
+    readonly "flows/core/Placement/Remote": Options;
+}>;
+/**
+ * Creates a placement directive for the local process host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const local: () => Placement;
+/**
+ * Creates a placement directive for the viewer's browser host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const client: () => Placement;
+/**
+ * Creates a placement directive for an isolated sandbox host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const sandbox: (options?: Options) => Placement;
+/**
+ * Creates a placement directive for a remote control-plane host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export declare const remote: (options?: Options) => Placement;
+/**
+ * The annotation key a declared placement is carried under.
+ *
+ * One key, here, because both graph builders read it: `@smthrs/core` publishes
+ * it as `Annotations.Placement` and `@smthrs/flow` as `Flow.Placement`. While
+ * they were two keys with two value types, crossing between them was a cast.
+ *
+ * @category annotations
+ * @since 1.0.0-rc.0
+ */
+export declare const Annotation: Context.Service<{
+    readonly _tag: "flows/core/Placement/Local";
+} | {
+    readonly _tag: "flows/core/Placement/Client";
+} | {
+    readonly _tag: "flows/core/Placement/Sandbox";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+} | {
+    readonly _tag: "flows/core/Placement/Remote";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+}, {
+    readonly _tag: "flows/core/Placement/Local";
+} | {
+    readonly _tag: "flows/core/Placement/Client";
+} | {
+    readonly _tag: "flows/core/Placement/Sandbox";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+} | {
+    readonly _tag: "flows/core/Placement/Remote";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+}>;
+//# sourceMappingURL=Placement.d.ts.map

package/dist/esm/Placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Placement.d.ts","sourceRoot":"","sources":["../../src/Placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC;IACtC,QAAQ,CAAC,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACrE,QAAQ,CAAC,6BAA6B,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAA;IACtE,QAAQ,CAAC,8BAA8B,EAAE,OAAO,CAAA;IAChD,QAAQ,CAAC,6BAA6B,EAAE,OAAO,CAAA;CAChD,CAAC,CAAA;AAIF;;;;;GAKG;AACH,eAAO,MAAM,KAAK,QAAO,SAAyD,CAAA;AAElF;;;;;GAKG;AACH,eAAO,MAAM,MAAM,QAAO,SAA0D,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,UAAS,OAAY,KAAG,SACc,CAAA;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,MAAM,GAAI,UAAS,OAAY,KAAG,SAAwE,CAAA;AAEvH;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU;;;;;;qBA/DJ,MAAM,GAAG,SAAS;uBAChB,MAAM,GAAG,SAAS;sBACnB,MAAM,GAAG,SAAS;;;qBAFnB,MAAM,GAAG,SAAS;uBAChB,MAAM,GAAG,SAAS;sBACnB,MAAM,GAAG,SAAS;;;;;;;qBAFnB,MAAM,GAAG,SAAS;uBAChB,MAAM,GAAG,SAAS;sBACnB,MAAM,GAAG,SAAS;;;qBAFnB,MAAM,GAAG,SAAS;uBAChB,MAAM,GAAG,SAAS;sBACnB,MAAM,GAAG,SAAS;EA6DwC,CAAA"}

package/dist/esm/Placement.js

@@ -0,0 +1,65 @@
+/**
+ * Where a node runs, declared.
+ *
+ * This is the ONE placement model. `@smthrs/core` re-exports it, `@smthrs/flow`
+ * annotates with it, and `@smthrs/registry` lowers a descriptor's frontmatter
+ * literal into it. It used to be a typed enum in `@smthrs/core` and an opaque
+ * `Schema.Unknown` in `@smthrs/flow`, with a cast in the registry standing
+ * between them, so a directive lost its type the moment it crossed a package.
+ *
+ * It lives here because `KeyMaterial.placement` is the field it ends up in, and
+ * `@smthrs/plan` is the lowest package core, flow and the registry all depend
+ * on. A placement is serializable detail that identifies a host profile; it
+ * never contains a host implementation, credentials, or any other runtime
+ * handle.
+ *
+ * The four tags still read `flows/core/Placement/...`. They are hashed into
+ * `KeyMaterial.placement` and therefore into the step key of every node that
+ * declares a placement, so retagging them would re-key production work and
+ * miss its cached results. The tag is a wire value, not a location.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+const constructors = Data.taggedEnum();
+/**
+ * Creates a placement directive for the local process host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const local = () => constructors["flows/core/Placement/Local"]();
+/**
+ * Creates a placement directive for the viewer's browser host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const client = () => constructors["flows/core/Placement/Client"]();
+/**
+ * Creates a placement directive for an isolated sandbox host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const sandbox = (options = {}) => constructors["flows/core/Placement/Sandbox"]({ ...options });
+/**
+ * Creates a placement directive for a remote control-plane host.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ */
+export const remote = (options = {}) => constructors["flows/core/Placement/Remote"]({ ...options });
+/**
+ * The annotation key a declared placement is carried under.
+ *
+ * One key, here, because both graph builders read it: `@smthrs/core` publishes
+ * it as `Annotations.Placement` and `@smthrs/flow` as `Flow.Placement`. While
+ * they were two keys with two value types, crossing between them was a cast.
+ *
+ * @category annotations
+ * @since 1.0.0-rc.0
+ */
+export const Annotation = Context.Service("@smthrs/plan/Placement");
+//# sourceMappingURL=Placement.js.map

package/dist/esm/Placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Placement.js","sourceRoot":"","sources":["../../src/Placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,IAAI,MAAM,aAAa,CAAA;AA6BnC,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAa,CAAA;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,GAAc,EAAE,CAAC,YAAY,CAAC,4BAA4B,CAAC,EAAE,CAAA;AAElF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,GAAc,EAAE,CAAC,YAAY,CAAC,6BAA6B,CAAC,EAAE,CAAA;AAEpF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,UAAmB,EAAE,EAAa,EAAE,CAC1D,YAAY,CAAC,8BAA8B,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,UAAmB,EAAE,EAAa,EAAE,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAA;AAEvH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAY,wBAAwB,CAAC,CAAA","sourcesContent":["/**\n * Where a node runs, declared.\n *\n * This is the ONE placement model. `@smthrs/core` re-exports it, `@smthrs/flow`\n * annotates with it, and `@smthrs/registry` lowers a descriptor's frontmatter\n * literal into it. It used to be a typed enum in `@smthrs/core` and an opaque\n * `Schema.Unknown` in `@smthrs/flow`, with a cast in the registry standing\n * between them, so a directive lost its type the moment it crossed a package.\n *\n * It lives here because `KeyMaterial.placement` is the field it ends up in, and\n * `@smthrs/plan` is the lowest package core, flow and the registry all depend\n * on. A placement is serializable detail that identifies a host profile; it\n * never contains a host implementation, credentials, or any other runtime\n * handle.\n *\n * The four tags still read `flows/core/Placement/...`. They are hashed into\n * `KeyMaterial.placement` and therefore into the step key of every node that\n * declares a placement, so retagging them would re-key production work and\n * miss its cached results. The tag is a wire value, not a location.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Data from \"effect/Data\"\n\n/**\n * Serializable host-selection details. These fields identify a host profile;\n * they never contain a host implementation, credentials, or other runtime\n * handle.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport interface Options {\n  readonly image?: string | undefined\n  readonly profile?: string | undefined\n  readonly target?: string | undefined\n}\n\n/**\n * A serializable directive describing where a flow node should run.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type Placement = Data.TaggedEnum<{\n  readonly \"flows/core/Placement/Local\": Readonly<Record<never, never>>\n  readonly \"flows/core/Placement/Client\": Readonly<Record<never, never>>\n  readonly \"flows/core/Placement/Sandbox\": Options\n  readonly \"flows/core/Placement/Remote\": Options\n}>\n\nconst constructors = Data.taggedEnum<Placement>()\n\n/**\n * Creates a placement directive for the local process host.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const local = (): Placement => constructors[\"flows/core/Placement/Local\"]()\n\n/**\n * Creates a placement directive for the viewer's browser host.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const client = (): Placement => constructors[\"flows/core/Placement/Client\"]()\n\n/**\n * Creates a placement directive for an isolated sandbox host.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const sandbox = (options: Options = {}): Placement =>\n  constructors[\"flows/core/Placement/Sandbox\"]({ ...options })\n\n/**\n * Creates a placement directive for a remote control-plane host.\n *\n * @category constructors\n * @since 1.0.0-rc.0\n */\nexport const remote = (options: Options = {}): Placement => constructors[\"flows/core/Placement/Remote\"]({ ...options })\n\n/**\n * The annotation key a declared placement is carried under.\n *\n * One key, here, because both graph builders read it: `@smthrs/core` publishes\n * it as `Annotations.Placement` and `@smthrs/flow` as `Flow.Placement`. While\n * they were two keys with two value types, crossing between them was a cast.\n *\n * @category annotations\n * @since 1.0.0-rc.0\n */\nexport const Annotation = Context.Service<Placement>(\"@smthrs/plan/Placement\")\n"]}

package/dist/esm/Plan.d.ts

@@ -0,0 +1,440 @@
+/**
+ * The plan: a node graph with every step key computed, inert until run.
+ *
+ * The way a plan is produced is a law: **planning performs no I/O**.
+ * Everything in this module is therefore a pure function of declarations plus
+ * the injected `Crypto` service: no filesystem, no clock, no network. A node's
+ * key is a function of what it consumes, so an edited declaration re-keys that
+ * node and everything downstream of it, and nothing else. That is the entire
+ * invalidation mechanism. Invalidation is re-keying, which **rejects**
+ * Skyframe's reverse-dependency index and invalidating node visitor outright
+ * because content addressing subsumes them. Key invalidation never retains a
+ * reverse-dependency index; annotation uses only a temporary reachability cache.
+ *
+ * Growth is append-only: {@link append} adds a pre-keyed subgraph to the same
+ * plan and never rewrites a node already in it.
+ *
+ * @since 0.1.0
+ */
+import type * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as KeyMaterial from "./KeyMaterial.ts";
+import * as StepKey from "./StepKey.ts";
+/**
+ * What a node does to the world, declared. Paths only — measuring them is
+ * run-time work, so a digest here would break the no-I/O law.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+export declare const NodeEffects: Schema.Struct<{
+    readonly reads: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+        readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+        readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>]>, Schema.TaggedStruct<"Filegroup", {
+        readonly name: Schema.NonEmptyString;
+        readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+            readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+            readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        }>]>>;
+    }>]>>;
+    readonly writes: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+        readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+        readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    }>, Schema.TaggedStruct<"TreeArtifact", {
+        readonly path: Schema.NonEmptyString;
+    }>]>, Schema.TaggedStruct<"Filegroup", {
+        readonly name: Schema.NonEmptyString;
+        readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+            readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+            readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        }>, Schema.TaggedStruct<"TreeArtifact", {
+            readonly path: Schema.NonEmptyString;
+        }>]>>;
+    }>]>>;
+    /**
+     * Paths the node declares it will DELETE. A removal mutates the world exactly
+     * as a write does, so {@link produces} folds the two together and both the
+     * conflict pass and the reader-after-writer pass see them as one set.
+     */
+    readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
+}>;
+/**
+ * The value form of {@link NodeEffects}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type NodeEffects = typeof NodeEffects.Type;
+/**
+ * The plan-time write-conflict strategies of the effect taxonomy.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+export declare const PairStrategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+/**
+ * The value form of {@link PairStrategy}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type PairStrategy = typeof PairStrategy.Type;
+/**
+ * The runtime half of a conflict annotation: what the scheduler
+ * does when the overlap the plan predicted actually bites, or when a
+ * scheduled node's inputs are invalidated under it.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+export declare const RuntimeStrategy: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
+/**
+ * The value form of {@link RuntimeStrategy}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type RuntimeStrategy = typeof RuntimeStrategy.Type;
+/**
+ * One resolved overlap between two writers that no dependency path already
+ * orders. Conflict is a property of the PAIR, not of one declaration.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+export declare const ConflictAnnotation: Schema.Struct<{
+    readonly with: Schema.NonEmptyString;
+    readonly paths: Schema.$Array<Schema.String>;
+    readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+    readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
+}>;
+/**
+ * The value form of {@link ConflictAnnotation}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type ConflictAnnotation = typeof ConflictAnnotation.Type;
+/**
+ * A keyed node of the plan.
+ *
+ * `dependsOn` is the *edge* set: material references, any ordering edge a
+ * `serialize` verdict added, and the reader-after-writer edges that put a
+ * node behind whoever produces the paths it reads. Ordering edges are
+ * deliberately NOT part of the key — a node ordered behind another still
+ * computes the same result, so re-keying it would throw away a legitimate
+ * cache hit.
+ *
+ * `strategy` and `runtime` are this declaration's own preferences, recorded so
+ * a later elaboration can resolve a pair against them without re-reading the
+ * flow source.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+export declare const PlanNode: Schema.Struct<{
+    readonly id: Schema.NonEmptyString;
+    readonly kind: Schema.Literals<readonly ["step", "agent", "merge"]>;
+    readonly key: Schema.brand<Schema.String, "@smthrs/keys/Key">;
+    readonly material: Schema.Struct<{
+        readonly version: Schema.Literal<"flows/key-material/v2">;
+        readonly kind: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+        readonly nondeterministic: Schema.optional<Schema.Literal<true>>;
+        readonly body: Schema.Unknown;
+        readonly inputs: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
+            readonly value: Schema.Unknown;
+        }>, Schema.TaggedStruct<"Ref", {
+            readonly from: Schema.NonEmptyString;
+            readonly path: Schema.$Array<Schema.String>;
+        }>, Schema.TaggedStruct<"Pending", {
+            readonly from: Schema.NonEmptyString;
+        }>]>>;
+        readonly layers: Schema.$Array<Schema.String>;
+        readonly capabilities: Schema.$Array<Schema.String>;
+        readonly effects: Schema.optional<Schema.Unknown>;
+        readonly placement: Schema.optional<Schema.Unknown>;
+    }>;
+    readonly effects: Schema.Struct<{
+        readonly reads: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+            readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+            readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        }>]>, Schema.TaggedStruct<"Filegroup", {
+            readonly name: Schema.NonEmptyString;
+            readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            }>]>>;
+        }>]>>;
+        readonly writes: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+            readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+            readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        }>, Schema.TaggedStruct<"TreeArtifact", {
+            readonly path: Schema.NonEmptyString;
+        }>]>, Schema.TaggedStruct<"Filegroup", {
+            readonly name: Schema.NonEmptyString;
+            readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            }>, Schema.TaggedStruct<"TreeArtifact", {
+                readonly path: Schema.NonEmptyString;
+            }>]>>;
+        }>]>>;
+        /**
+         * Paths the node declares it will DELETE. A removal mutates the world exactly
+         * as a write does, so {@link produces} folds the two together and both the
+         * conflict pass and the reader-after-writer pass see them as one set.
+         */
+        readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
+    }>;
+    readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
+    readonly conflicts: Schema.$Array<Schema.Struct<{
+        readonly with: Schema.NonEmptyString;
+        readonly paths: Schema.$Array<Schema.String>;
+        readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+        readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
+    }>>;
+    readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+    readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
+    readonly priority: Schema.Int;
+    readonly generation: Schema.Int;
+}>;
+/**
+ * The value form of {@link PlanNode}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type PlanNode = typeof PlanNode.Type;
+/**
+ * A plan: the whole keyed graph plus the digest an approval binds to.
+ *
+ * `nodes` follows material-dependency order within each generation. Inferred
+ * edges can point to later entries; schedule from the complete `dependsOn`
+ * graph, never by iterating the array alone.
+ *
+ * `baseDigest` is the digest at generation 0: what a human approved and what
+ * a `RUNNING` run pins. `digest` advances with every appended elaboration.
+ *
+ * @since 0.1.0
+ * @category schemas
+ * @slop
+ */
+export declare const Plan: Schema.Struct<{
+    readonly planId: Schema.NonEmptyString;
+    readonly flow: Schema.NonEmptyString;
+    readonly generation: Schema.Int;
+    readonly baseDigest: Schema.brand<Schema.String, "@smthrs/keys/Key">;
+    readonly digest: Schema.brand<Schema.String, "@smthrs/keys/Key">;
+    readonly nodes: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.NonEmptyString;
+        readonly kind: Schema.Literals<readonly ["step", "agent", "merge"]>;
+        readonly key: Schema.brand<Schema.String, "@smthrs/keys/Key">;
+        readonly material: Schema.Struct<{
+            readonly version: Schema.Literal<"flows/key-material/v2">;
+            readonly kind: Schema.Literals<readonly ["sealed", "compensable", "irreversible"]>;
+            readonly nondeterministic: Schema.optional<Schema.Literal<true>>;
+            readonly body: Schema.Unknown;
+            readonly inputs: Schema.$Array<Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
+                readonly value: Schema.Unknown;
+            }>, Schema.TaggedStruct<"Ref", {
+                readonly from: Schema.NonEmptyString;
+                readonly path: Schema.$Array<Schema.String>;
+            }>, Schema.TaggedStruct<"Pending", {
+                readonly from: Schema.NonEmptyString;
+            }>]>>;
+            readonly layers: Schema.$Array<Schema.String>;
+            readonly capabilities: Schema.$Array<Schema.String>;
+            readonly effects: Schema.optional<Schema.Unknown>;
+            readonly placement: Schema.optional<Schema.Unknown>;
+        }>;
+        readonly effects: Schema.Struct<{
+            readonly reads: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            }>]>, Schema.TaggedStruct<"Filegroup", {
+                readonly name: Schema.NonEmptyString;
+                readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+                }>]>>;
+            }>]>>;
+            readonly writes: Schema.$Array<Schema.Union<readonly [Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            }>, Schema.TaggedStruct<"TreeArtifact", {
+                readonly path: Schema.NonEmptyString;
+            }>]>, Schema.TaggedStruct<"Filegroup", {
+                readonly name: Schema.NonEmptyString;
+                readonly entries: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.TaggedStruct<"Glob", {
+                    readonly include: Schema.NonEmptyArray<Schema.NonEmptyString>;
+                    readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+                }>, Schema.TaggedStruct<"TreeArtifact", {
+                    readonly path: Schema.NonEmptyString;
+                }>]>>;
+            }>]>>;
+            /**
+             * Paths the node declares it will DELETE. A removal mutates the world exactly
+             * as a write does, so {@link produces} folds the two together and both the
+             * conflict pass and the reader-after-writer pass see them as one set.
+             */
+            readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
+        }>;
+        readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
+        readonly conflicts: Schema.$Array<Schema.Struct<{
+            readonly with: Schema.NonEmptyString;
+            readonly paths: Schema.$Array<Schema.String>;
+            readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+            readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
+        }>>;
+        readonly strategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
+        readonly runtime: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
+        readonly priority: Schema.Int;
+        readonly generation: Schema.Int;
+    }>>;
+}>;
+/**
+ * The value form of {@link Plan}.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type Plan = typeof Plan.Type;
+/**
+ * What a planner hands {@link compile}: a node without its key.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface NodeDraft {
+    readonly id: string;
+    readonly material: KeyMaterial.KeyMaterial;
+    readonly effects: NodeEffects;
+    readonly kind?: PlanNode["kind"] | undefined;
+    readonly priority?: number | undefined;
+    /** This declaration's preferred plan-time verdict for a detected overlap. */
+    readonly conflictStrategy?: PairStrategy | undefined;
+    /** This declaration's preferred runtime response. */
+    readonly runtimeStrategy?: RuntimeStrategy | undefined;
+}
+declare const PlanError_base: Schema.Class<PlanError, Schema.TaggedStruct<"@smthrs/plan/PlanError", {
+    readonly code: Schema.Literals<readonly ["cycle", "unknown_dependency", "duplicate_node", "overlap_forbidden", "invalid_effects", "invalid_node", "invalid_plan", "graph_too_large"]>;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A graph the compiler refuses.
+ *
+ * @since 0.1.0
+ * @category errors
+ * @slop
+ */
+export declare class PlanError extends PlanError_base {
+}
+/**
+ * Maximum number of nodes retained by one compiled plan.
+ *
+ * Effect analysis also has a yielding work budget, since a node ceiling alone
+ * does not bound dense conflicts to practical work.
+ *
+ * @since 1.0.0
+ * @category limits
+ * @slop
+ */
+export declare const maximumPlanNodes = 10000;
+/**
+ * Compiles drafts into a plan: material-dependency order, dependency-digest
+ * substitution, overlap annotation, and the plan digest. No I/O.
+ * Inferred edges extend `dependsOn` without reordering the node array.
+ *
+ * Traversal uses explicit stacks. Because the conflict and reader/writer
+ * passes consider a quadratic number of node pairs, plans are bounded by
+ * {@link maximumPlanNodes} and fail with `graph_too_large` above that limit
+ * or the effect-analysis work budget. Analysis yields periodically.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const compile: (options: {
+    readonly planId: string;
+    readonly flow: string;
+    readonly nodes: ReadonlyArray<NodeDraft>;
+}) => Effect.Effect<Plan, PlanError | StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Appends an elaborated subgraph to an existing plan.
+ *
+ * The plan GROWS; it is never invalidated. Nodes already in it keep their id,
+ * key, edges, and generation byte for byte, and the new nodes arrive pre-keyed
+ * against them, so a `hit` shows instantly. New nodes retain their material
+ * dependency order; scheduling must honor their complete `dependsOn` graph.
+ * Re-ordering after a reconciliation happens by re-keying *future* steps,
+ * never by rewriting history.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export declare const append: (plan: Plan, drafts: ReadonlyArray<NodeDraft>) => Effect.Effect<Plan, PlanError | StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * Verifies an imported plan against the same key and topology rules as the
+ * compiler. Valid compiler-owned immutable values need no second compilation.
+ *
+ * Generation boundaries are replayed when reconstructing conflict annotations:
+ * an append may annotate new nodes, but cannot rewrite an earlier generation.
+ * Recorded material-dependency order is verified without sorting inferred edges.
+ * Keys and approval digests retain their existing format. The returned snapshot
+ * is immutable; later caller mutation cannot change the verified value.
+ *
+ * @since 1.0.0
+ * @category validation
+ */
+export declare const verify: (input: unknown) => Effect.Effect<Plan, PlanError | StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+/**
+ * The nodes added by the newest generation: what {@link module:PlanStore}
+ * appends and what the `subgraph-appended` journal record names.
+ *
+ * @since 0.1.0
+ * @category accessors
+ * @slop
+ */
+export declare const generationNodes: (plan: Plan) => ReadonlyArray<PlanNode>;
+/**
+ * Whether `input` is a compiler-owned immutable snapshot that already passed
+ * {@link verify}: such values take verify's trusted fast path and need no
+ * second schema validation.
+ *
+ * @since 1.0.0
+ * @category guards
+ * @slop
+ */
+export declare const isVerified: (input: unknown) => input is Plan;
+/**
+ * The approval digest of every generation before the newest: the digest this
+ * plan carried before its last append. {@link module:PlanStore}'s append
+ * matches it against the stored envelope, so an append proves the recorded
+ * plan's integrity from the already-verified prefix instead of decoding and
+ * re-verifying every stored row.
+ *
+ * @since 1.0.0
+ * @category accessors
+ * @slop
+ */
+export declare const prefixDigest: (plan: Plan) => Effect.Effect<StepKey.StepKey, StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
+export {};
+//# sourceMappingURL=Plan.d.ts.map

package/dist/esm/Plan.d.ts.map

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