@smthrs/plan 1.0.0-rc.7 → 1.0.0-rc.9

package/dist/cjs/GraphBuildError.d.ts

@@ -68,7 +68,6 @@ import * as Schema from "effect/Schema";
  *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const GraphBuildErrorCode: Schema.Literals<readonly ["planned_value_computed", "invalid_all_member", "invalid_join", "invalid_continuation", "recursion_requires_boundary", "placement_requires_boundary", "cyclic_payload", "payload_too_deep", "graph_too_deep", "duplicate_node", "invalid_priority", "invalid_payload", "unstable_callback", "effect_outside_envelope", "effect_mode_widening", "effect_tier_widening", "capability_outside_grant", "write_conflict", "missing_key_material", "dependency_cycle", "plan_too_large", "payload_too_large", "invalid_node"]>;
 /**
@@ -76,7 +75,6 @@ export declare const GraphBuildErrorCode: Schema.Literals<readonly ["planned_val
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type GraphBuildErrorCode = typeof GraphBuildErrorCode.Type;
 declare const GraphBuildError_base: Schema.Class<GraphBuildError, Schema.TaggedStruct<"@smthrs/plan/GraphBuildError", {
@@ -102,7 +100,6 @@ declare const GraphBuildError_base: Schema.Class<GraphBuildError, Schema.TaggedS
  *
  * @since 0.1.0
  * @category errors
- * @slop
  */
 export declare class GraphBuildError extends GraphBuildError_base {
 }
@@ -113,9 +110,10 @@ export declare class GraphBuildError extends GraphBuildError_base {
  * written, so the drafts are withheld. An advisory one reports a narrowing the
  * author should see while the graph still compiles.
  *
+ * @param diagnostic - A recorded refusal.
+ * @returns `false` only for an advisory code (`capability_outside_grant`).
  * @since 0.1.0
  * @category predicates
- * @slop
  */
 export declare const isFatalDiagnostic: (diagnostic: GraphBuildError) => boolean;
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"GraphBuildError.d.ts","sourceRoot":"","sources":["../../src/GraphBuildError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,mBAAmB,ohBAwB9B,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;;;;;;;AAEjE;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,SAAQ,oBAKnC;CAAG;AAaL;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,YAAY,eAAe,KAAG,OAA8C,CAAA"}
+{"version":3,"file":"GraphBuildError.d.ts","sourceRoot":"","sources":["../../src/GraphBuildError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,eAAO,MAAM,mBAAmB,ohBAwB9B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAC,IAAI,CAAA;;;;;;;AAEjE;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAgB,SAAQ,oBAKnC;CAAG;AAaL;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAAI,YAAY,eAAe,KAAG,OAA8C,CAAA"}

package/dist/cjs/GraphBuildError.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/GraphBuildError.ts"],
-  "sourcesContent": ["/**\n * The refusals a plan-time build raises instead of producing a wrong plan.\n *\n * Every one of these fails LOUDLY at build time: a planned value that was computed on must not\n * bake `NaN` into a plan, an arm that returned something other than a node must\n * not silently vanish from the topology, and a recursive `.call()` must direct\n * the author to `.to()` or `.child()` rather than expanding forever. Each\n * failure therefore names the site (`node` plus the recorded property `path`)\n * and states the fix in `message`, because the author reading it is mid-body\n * and needs the correction, not a classification.\n *\n * The codes are a closed schema literal so a caller can switch on them, and so\n * a new refusal is a deliberate addition rather than a new free-form string.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * The stable code of a build refusal.\n *\n * `planned_value_computed` is a body computing on a step result;\n * `invalid_all_member` is a non-node handed to {@link module:Node.all};\n * `invalid_join` is a race, any, or quorum with a non-node member, no members,\n * or a quorum count its members cannot reach;\n * `invalid_continuation` is a branch arm or continuation that did not return a\n * node; `recursion_requires_boundary` is a flow calling itself inline, which\n * has to become a trampoline handoff or an explicit child boundary;\n * `placement_requires_boundary` is an inline call whose callee declares a\n * placement the enclosing flow cannot satisfy, which has to become that same\n * explicit child boundary; `cyclic_payload` is a payload that contains itself,\n * which no plan could serialize or hash; `payload_too_deep` is a payload\n * nested past the build bound, which has to be flattened into shallower data;\n * `graph_too_deep` is authored topology nested past the build bound, which\n * has to be split with `.child()` boundaries or trampoline handoffs;\n * `duplicate_node` is two structural graph addresses resolving to one durable\n * node id;\n * `invalid_priority` is a scheduling priority that is not a safe integer,\n * which no ordering could compare; `invalid_payload` is a payload member that\n * cannot be captured as inert JSON without executing author code or losing\n * identity; `unstable_callback` is a function with process-local identity in a\n * graph that requires stable callbacks. Declare its complete inert captures\n * with `Node.capture`, including semantic implementation versions. The two\n * depth refusals exist because graph building walks with an explicit stack\n * and refuses at a bound, rather than recursing until the native stack\n * overflows without a typed error.\n *\n * The four effect-authority refusals are raised when a declaration claims more\n * than the declaration enclosing it granted:\n * `effect_outside_envelope` is a read or write path the envelope does not\n * cover, and it names those paths in `path`; `effect_mode_widening` is an\n * `expected` declaration inside a `hermetic` envelope; `effect_tier_widening`\n * is a tier less reversible than the envelope's; and\n * `capability_outside_grant` is a called flow or action requiring a capability\n * the caller does not hold, which names the dropped capabilities in `path`. The\n * first three are fatal by {@link isFatalDiagnostic}; the fourth is advisory,\n * because dropping a capability narrows authority rather than widening it.\n *\n * The last six are raised by `@smthrs/core`'s graph builder, which uses this\n * one error rather than a second class of its own. `write_conflict` is two work\n * nodes overlapping under `onConflict: \"fail\"`, and `node` names the first of\n * the pair while `Graph.conflicts` carries both; `missing_key_material` is a\n * node that reached key compilation without any; `dependency_cycle` is a\n * dependency set that cannot be ordered, and `node` names a node in the cycle;\n * `plan_too_large` is a node, edge, conflict, or effect-path limit crossed, and\n * `node` names the node whose admission crossed it; `payload_too_large` is a\n * plan value with more members than the bound, and `path` names the offending\n * value path; `invalid_node` is a malformed node AST. All six are fatal.\n *\n * @since 0.1.0\n * @category schemas\n * @slop\n */\nexport const GraphBuildErrorCode = Schema.Literals([\n  \"planned_value_computed\",\n  \"invalid_all_member\",\n  \"invalid_join\",\n  \"invalid_continuation\",\n  \"recursion_requires_boundary\",\n  \"placement_requires_boundary\",\n  \"cyclic_payload\",\n  \"payload_too_deep\",\n  \"graph_too_deep\",\n  \"duplicate_node\",\n  \"invalid_priority\",\n  \"invalid_payload\",\n  \"unstable_callback\",\n  \"effect_outside_envelope\",\n  \"effect_mode_widening\",\n  \"effect_tier_widening\",\n  \"capability_outside_grant\",\n  \"write_conflict\",\n  \"missing_key_material\",\n  \"dependency_cycle\",\n  \"plan_too_large\",\n  \"payload_too_large\",\n  \"invalid_node\"\n])\n\n/**\n * The value form of {@link GraphBuildErrorCode}.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport type GraphBuildErrorCode = typeof GraphBuildErrorCode.Type\n\n/**\n * A build the planner refuses, naming the site and the fix.\n *\n * `node` is the node reference the failure belongs to \u2014 a planned value's\n * origin node, an `all` member name, a branch arm, or the node whose admission\n * crossed a bound. `path` is the property path recorded on a planned value\n * before it was misused, the effect paths an over-claiming declaration named,\n * the capabilities a call lost, or the value path of an oversized payload; it\n * is empty for every other code.\n *\n * This is the ONE build refusal. `@smthrs/core`'s graph builder raised a second\n * `GraphBuildError` of its own, with `paths`, `nodeId` and `nodes` in place of\n * these fields, and the two code sets diverged instead of merging. A conflict's\n * second node is read from `Graph.conflicts`, which carries the pair.\n *\n * @since 0.1.0\n * @category errors\n * @slop\n */\nexport class GraphBuildError extends Schema.TaggedError<GraphBuildError>()(\"@smthrs/plan/GraphBuildError\", {\n  code: GraphBuildErrorCode,\n  node: Schema.String,\n  path: Schema.Array(Schema.String),\n  message: Schema.String\n}) {}\n\n/**\n * The one advisory code. Everything else a build records blocks the drafts.\n *\n * A capability the caller does not grant is DROPPED, not granted: the callee\n * runs with less authority than it asked for, which is the safe direction. The\n * author still needs to know, because a flow that silently loses a capability\n * fails later at the action that needed it, so the build records the refusal\n * and lets the graph compile.\n */\nconst advisoryCodes: ReadonlySet<GraphBuildErrorCode> = new Set<GraphBuildErrorCode>([\"capability_outside_grant\"])\n\n/**\n * Whether a recorded refusal blocks the drafts a plan is compiled from.\n *\n * A fatal refusal means the graph describes something no plan could execute as\n * written, so the drafts are withheld. An advisory one reports a narrowing the\n * author should see while the graph still compiles.\n *\n * @since 0.1.0\n * @category predicates\n * @slop\n */\nexport const isFatalDiagnostic = (diagnostic: GraphBuildError): boolean => !advisoryCodes.has(diagnostic.code)\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBA,aAAwB;AAyDjB,MAAM,sBAAsB,OAAO,SAAS;AAAA,EACjD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AA8BM,MAAM,wBAAwB,OAAO,YAA6B,EAAE,gCAAgC;AAAA,EACzG,MAAM;AAAA,EACN,MAAM,OAAO;AAAA,EACb,MAAM,OAAO,MAAM,OAAO,MAAM;AAAA,EAChC,SAAS,OAAO;AAClB,CAAC,EAAE;AAAC;AAWJ,MAAM,gBAAkD,oBAAI,IAAyB,CAAC,0BAA0B,CAAC;AAa1G,MAAM,oBAAoB,CAAC,eAAyC,CAAC,cAAc,IAAI,WAAW,IAAI;",
+  "sourcesContent": ["/**\n * The refusals a plan-time build raises instead of producing a wrong plan.\n *\n * Every one of these fails LOUDLY at build time: a planned value that was computed on must not\n * bake `NaN` into a plan, an arm that returned something other than a node must\n * not silently vanish from the topology, and a recursive `.call()` must direct\n * the author to `.to()` or `.child()` rather than expanding forever. Each\n * failure therefore names the site (`node` plus the recorded property `path`)\n * and states the fix in `message`, because the author reading it is mid-body\n * and needs the correction, not a classification.\n *\n * The codes are a closed schema literal so a caller can switch on them, and so\n * a new refusal is a deliberate addition rather than a new free-form string.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\n\n/**\n * The stable code of a build refusal.\n *\n * `planned_value_computed` is a body computing on a step result;\n * `invalid_all_member` is a non-node handed to {@link module:Node.all};\n * `invalid_join` is a race, any, or quorum with a non-node member, no members,\n * or a quorum count its members cannot reach;\n * `invalid_continuation` is a branch arm or continuation that did not return a\n * node; `recursion_requires_boundary` is a flow calling itself inline, which\n * has to become a trampoline handoff or an explicit child boundary;\n * `placement_requires_boundary` is an inline call whose callee declares a\n * placement the enclosing flow cannot satisfy, which has to become that same\n * explicit child boundary; `cyclic_payload` is a payload that contains itself,\n * which no plan could serialize or hash; `payload_too_deep` is a payload\n * nested past the build bound, which has to be flattened into shallower data;\n * `graph_too_deep` is authored topology nested past the build bound, which\n * has to be split with `.child()` boundaries or trampoline handoffs;\n * `duplicate_node` is two structural graph addresses resolving to one durable\n * node id;\n * `invalid_priority` is a scheduling priority that is not a safe integer,\n * which no ordering could compare; `invalid_payload` is a payload member that\n * cannot be captured as inert JSON without executing author code or losing\n * identity; `unstable_callback` is a function with process-local identity in a\n * graph that requires stable callbacks. Declare its complete inert captures\n * with `Node.capture`, including semantic implementation versions. The two\n * depth refusals exist because graph building walks with an explicit stack\n * and refuses at a bound, rather than recursing until the native stack\n * overflows without a typed error.\n *\n * The four effect-authority refusals are raised when a declaration claims more\n * than the declaration enclosing it granted:\n * `effect_outside_envelope` is a read or write path the envelope does not\n * cover, and it names those paths in `path`; `effect_mode_widening` is an\n * `expected` declaration inside a `hermetic` envelope; `effect_tier_widening`\n * is a tier less reversible than the envelope's; and\n * `capability_outside_grant` is a called flow or action requiring a capability\n * the caller does not hold, which names the dropped capabilities in `path`. The\n * first three are fatal by {@link isFatalDiagnostic}; the fourth is advisory,\n * because dropping a capability narrows authority rather than widening it.\n *\n * The last six are raised by `@smthrs/core`'s graph builder, which uses this\n * one error rather than a second class of its own. `write_conflict` is two work\n * nodes overlapping under `onConflict: \"fail\"`, and `node` names the first of\n * the pair while `Graph.conflicts` carries both; `missing_key_material` is a\n * node that reached key compilation without any; `dependency_cycle` is a\n * dependency set that cannot be ordered, and `node` names a node in the cycle;\n * `plan_too_large` is a node, edge, conflict, or effect-path limit crossed, and\n * `node` names the node whose admission crossed it; `payload_too_large` is a\n * plan value with more members than the bound, and `path` names the offending\n * value path; `invalid_node` is a malformed node AST. All six are fatal.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const GraphBuildErrorCode = Schema.Literals([\n  \"planned_value_computed\",\n  \"invalid_all_member\",\n  \"invalid_join\",\n  \"invalid_continuation\",\n  \"recursion_requires_boundary\",\n  \"placement_requires_boundary\",\n  \"cyclic_payload\",\n  \"payload_too_deep\",\n  \"graph_too_deep\",\n  \"duplicate_node\",\n  \"invalid_priority\",\n  \"invalid_payload\",\n  \"unstable_callback\",\n  \"effect_outside_envelope\",\n  \"effect_mode_widening\",\n  \"effect_tier_widening\",\n  \"capability_outside_grant\",\n  \"write_conflict\",\n  \"missing_key_material\",\n  \"dependency_cycle\",\n  \"plan_too_large\",\n  \"payload_too_large\",\n  \"invalid_node\"\n])\n\n/**\n * The value form of {@link GraphBuildErrorCode}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type GraphBuildErrorCode = typeof GraphBuildErrorCode.Type\n\n/**\n * A build the planner refuses, naming the site and the fix.\n *\n * `node` is the node reference the failure belongs to \u2014 a planned value's\n * origin node, an `all` member name, a branch arm, or the node whose admission\n * crossed a bound. `path` is the property path recorded on a planned value\n * before it was misused, the effect paths an over-claiming declaration named,\n * the capabilities a call lost, or the value path of an oversized payload; it\n * is empty for every other code.\n *\n * This is the ONE build refusal. `@smthrs/core`'s graph builder raised a second\n * `GraphBuildError` of its own, with `paths`, `nodeId` and `nodes` in place of\n * these fields, and the two code sets diverged instead of merging. A conflict's\n * second node is read from `Graph.conflicts`, which carries the pair.\n *\n * @since 0.1.0\n * @category errors\n */\nexport class GraphBuildError extends Schema.TaggedError<GraphBuildError>()(\"@smthrs/plan/GraphBuildError\", {\n  code: GraphBuildErrorCode,\n  node: Schema.String,\n  path: Schema.Array(Schema.String),\n  message: Schema.String\n}) {}\n\n/**\n * The one advisory code. Everything else a build records blocks the drafts.\n *\n * A capability the caller does not grant is DROPPED, not granted: the callee\n * runs with less authority than it asked for, which is the safe direction. The\n * author still needs to know, because a flow that silently loses a capability\n * fails later at the action that needed it, so the build records the refusal\n * and lets the graph compile.\n */\nconst advisoryCodes: ReadonlySet<GraphBuildErrorCode> = new Set<GraphBuildErrorCode>([\"capability_outside_grant\"])\n\n/**\n * Whether a recorded refusal blocks the drafts a plan is compiled from.\n *\n * A fatal refusal means the graph describes something no plan could execute as\n * written, so the drafts are withheld. An advisory one reports a narrowing the\n * author should see while the graph still compiles.\n *\n * @param diagnostic - A recorded refusal.\n * @returns `false` only for an advisory code (`capability_outside_grant`).\n * @since 0.1.0\n * @category predicates\n */\nexport const isFatalDiagnostic = (diagnostic: GraphBuildError): boolean => !advisoryCodes.has(diagnostic.code)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBA,aAAwB;AAwDjB,MAAM,sBAAsB,OAAO,SAAS;AAAA,EACjD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AA4BM,MAAM,wBAAwB,OAAO,YAA6B,EAAE,gCAAgC;AAAA,EACzG,MAAM;AAAA,EACN,MAAM,OAAO;AAAA,EACb,MAAM,OAAO,MAAM,OAAO,MAAM;AAAA,EAChC,SAAS,OAAO;AAClB,CAAC,EAAE;AAAC;AAWJ,MAAM,gBAAkD,oBAAI,IAAyB,CAAC,0BAA0B,CAAC;AAc1G,MAAM,oBAAoB,CAAC,eAAyC,CAAC,cAAc,IAAI,WAAW,IAAI;",
   "names": []
 }

package/dist/cjs/KeyMaterial.d.ts

@@ -22,9 +22,12 @@ import * as Schema from "effect/Schema";
  * `Ref{from, path: []}` — which resolve to the same dependency digest — can
  * never collide.
  *
+ * - `Literal` hashes `value` inline.
+ * - `Ref` consumes the value at `path` inside node `from`'s result.
+ * - `Pending` consumes node `from`'s whole result.
+ *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const InputRef: Schema.Union<readonly [Schema.TaggedStruct<"Literal", {
     readonly value: Schema.Unknown;
@@ -35,11 +38,10 @@ export declare const InputRef: Schema.Union<readonly [Schema.TaggedStruct<"Liter
     readonly from: Schema.NonEmptyString;
 }>]>;
 /**
- * A reference to one declared input of a node.
+ * The value form of {@link InputRef}.
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type InputRef = typeof InputRef.Type;
 /**
@@ -48,7 +50,6 @@ export type InputRef = typeof InputRef.Type;
  *
  * @since 0.1.0
  * @category constants
- * @slop
  */
 export declare const version = "flows/key-material/v2";
 /**
@@ -58,9 +59,12 @@ export declare const version = "flows/key-material/v2";
  * interpreted, which is what keeps the compiler independent of whatever the
  * flow builder decides an effect declaration looks like.
  *
+ * `version` must equal {@link version}. `kind` is the effect tier. `inputs`
+ * are hashed in order; `layers` and `capabilities` name what the node runs
+ * with.
+ *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const KeyMaterial: Schema.Struct<{
     readonly version: Schema.Literal<"flows/key-material/v2">;
@@ -81,11 +85,10 @@ export declare const KeyMaterial: Schema.Struct<{
     readonly placement: Schema.optional<Schema.Unknown>;
 }>;
 /**
- * Everything that can change a node's result, handed to the digest.
+ * The value form of {@link KeyMaterial}.
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type KeyMaterial = typeof KeyMaterial.Type;
 /**
@@ -94,9 +97,11 @@ export type KeyMaterial = typeof KeyMaterial.Type;
  * {@link module:Plan} uses them as the edge set — one derivation, so an edge
  * and a hashed reference can never disagree.
  *
+ * @param material - The node's key material.
+ * @returns The `from` of every `Ref` and `Pending` input, first occurrence
+ * order, deduplicated.
  * @since 0.1.0
  * @category accessors
- * @slop
  */
 export declare const dependencies: (material: KeyMaterial) => ReadonlyArray<string>;
 //# sourceMappingURL=KeyMaterial.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"KeyMaterial.d.ts","sourceRoot":"","sources":["../../src/KeyMaterial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ;;;;;;;IAInB,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,0BAA0B,CAAA;AAE9C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;EAWtB,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,WAAW,KAAG,aAAa,CAAC,MAAM,CAMxE,CAAA"}
+{"version":3,"file":"KeyMaterial.d.ts","sourceRoot":"","sources":["../../src/KeyMaterial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ;;;;;;;IAInB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,0BAA0B,CAAA;AAE9C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;EAWtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,WAAW,KAAG,aAAa,CAAC,MAAM,CAMxE,CAAA"}

package/dist/cjs/KeyMaterial.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/KeyMaterial.ts"],
-  "sourcesContent": ["/**\n * The key-material contract: what a planner hands the step-key compiler.\n *\n * Revived from the deleted `packages/smithers/flows/keys/src/KeyMaterial.ts`.\n * It does NOT return to `@smthrs/keys`: that package owns generic derivation\n * and stored-key validation, while material is a *plan-shaped* concept. It\n * lives here, above `@smthrs/keys`, so the key package stays a leaf.\n *\n * Governing contract: the step-key rules at\n * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md. Material is computed with no I/O,\n * and two hardening rules shape it: the nominal, never shape-sniffed\n * `InputRef` and the hashed `version`.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\nimport * as Effects from \"./Effects.ts\"\n\n/**\n * A reference to one declared input of a node: a value hashed inline, or the\n * key of an upstream node whose result this node consumes.\n *\n * The three variants are tagged, and the tag is hashed, so `Pending{from}` and\n * `Ref{from, path: []}` \u2014 which resolve to the same dependency digest \u2014 can\n * never collide.\n *\n * @since 0.1.0\n * @category schemas\n * @slop\n */\nexport const InputRef = Schema.Union([\n  Schema.TaggedStruct(\"Literal\", { value: Schema.Unknown }),\n  Schema.TaggedStruct(\"Ref\", { from: Schema.NonEmptyString, path: Schema.Array(Schema.String) }),\n  Schema.TaggedStruct(\"Pending\", { from: Schema.NonEmptyString })\n])\n\n/**\n * A reference to one declared input of a node.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport type InputRef = typeof InputRef.Type\n\n/**\n * The material version. Folded into every hashed body so a bump re-keys every\n * node derived from it \u2014 the original's second collision fix, kept.\n *\n * @since 0.1.0\n * @category constants\n * @slop\n */\nexport const version = \"flows/key-material/v2\"\n\n/**\n * Everything that can change a node's result, handed to the digest.\n *\n * `effects` and `placement` are opaque: canonically serialized, never\n * interpreted, which is what keeps the compiler independent of whatever the\n * flow builder decides an effect declaration looks like.\n *\n * @since 0.1.0\n * @category schemas\n * @slop\n */\nexport const KeyMaterial = Schema.Struct({\n  version: Schema.Literal(version),\n  kind: Effects.Tier,\n  // Absence claims determinism; only the explicit declaration changes identity.\n  nondeterministic: Schema.optional(Schema.Literal(true)),\n  body: Schema.Unknown,\n  inputs: Schema.Array(InputRef),\n  layers: Schema.Array(Schema.String),\n  capabilities: Schema.Array(Schema.String),\n  effects: Schema.optional(Schema.Unknown),\n  placement: Schema.optional(Schema.Unknown)\n})\n\n/**\n * Everything that can change a node's result, handed to the digest.\n *\n * @since 0.1.0\n * @category models\n * @slop\n */\nexport type KeyMaterial = typeof KeyMaterial.Type\n\n/**\n * The graph-local dependencies a material names, in declaration order and\n * without duplicates. The compiler resolves exactly these before hashing, and\n * {@link module:Plan} uses them as the edge set \u2014 one derivation, so an edge\n * and a hashed reference can never disagree.\n *\n * @since 0.1.0\n * @category accessors\n * @slop\n */\nexport const dependencies = (material: KeyMaterial): ReadonlyArray<string> => {\n  const seen = new Set<string>()\n  for (const input of material.inputs) {\n    if (input._tag !== \"Literal\") seen.add(input.from)\n  }\n  return [...seen]\n}\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,aAAwB;AACxB,cAAyB;AAclB,MAAM,WAAW,OAAO,MAAM;AAAA,EACnC,OAAO,aAAa,WAAW,EAAE,OAAO,OAAO,QAAQ,CAAC;AAAA,EACxD,OAAO,aAAa,OAAO,EAAE,MAAM,OAAO,gBAAgB,MAAM,OAAO,MAAM,OAAO,MAAM,EAAE,CAAC;AAAA,EAC7F,OAAO,aAAa,WAAW,EAAE,MAAM,OAAO,eAAe,CAAC;AAChE,CAAC;AAmBM,MAAM,UAAU;AAahB,MAAM,cAAc,OAAO,OAAO;AAAA,EACvC,SAAS,OAAO,QAAQ,OAAO;AAAA,EAC/B,MAAM,QAAQ;AAAA;AAAA,EAEd,kBAAkB,OAAO,SAAS,OAAO,QAAQ,IAAI,CAAC;AAAA,EACtD,MAAM,OAAO;AAAA,EACb,QAAQ,OAAO,MAAM,QAAQ;AAAA,EAC7B,QAAQ,OAAO,MAAM,OAAO,MAAM;AAAA,EAClC,cAAc,OAAO,MAAM,OAAO,MAAM;AAAA,EACxC,SAAS,OAAO,SAAS,OAAO,OAAO;AAAA,EACvC,WAAW,OAAO,SAAS,OAAO,OAAO;AAC3C,CAAC;AAqBM,MAAM,eAAe,CAAC,aAAiD;AAC5E,QAAM,OAAO,oBAAI,IAAY;AAC7B,aAAW,SAAS,SAAS,QAAQ;AACnC,QAAI,MAAM,SAAS,UAAW,MAAK,IAAI,MAAM,IAAI;AAAA,EACnD;AACA,SAAO,CAAC,GAAG,IAAI;AACjB;",
+  "sourcesContent": ["/**\n * The key-material contract: what a planner hands the step-key compiler.\n *\n * Revived from the deleted `packages/smithers/flows/keys/src/KeyMaterial.ts`.\n * It does NOT return to `@smthrs/keys`: that package owns generic derivation\n * and stored-key validation, while material is a *plan-shaped* concept. It\n * lives here, above `@smthrs/keys`, so the key package stays a leaf.\n *\n * Governing contract: the step-key rules at\n * https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/plan/docs/concepts/step-keys.md. Material is computed with no I/O,\n * and two hardening rules shape it: the nominal, never shape-sniffed\n * `InputRef` and the hashed `version`.\n *\n * @since 0.1.0\n */\n\nimport * as Schema from \"effect/Schema\"\nimport * as Effects from \"./Effects.ts\"\n\n/**\n * A reference to one declared input of a node: a value hashed inline, or the\n * key of an upstream node whose result this node consumes.\n *\n * The three variants are tagged, and the tag is hashed, so `Pending{from}` and\n * `Ref{from, path: []}` \u2014 which resolve to the same dependency digest \u2014 can\n * never collide.\n *\n * - `Literal` hashes `value` inline.\n * - `Ref` consumes the value at `path` inside node `from`'s result.\n * - `Pending` consumes node `from`'s whole result.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const InputRef = Schema.Union([\n  Schema.TaggedStruct(\"Literal\", { value: Schema.Unknown }),\n  Schema.TaggedStruct(\"Ref\", { from: Schema.NonEmptyString, path: Schema.Array(Schema.String) }),\n  Schema.TaggedStruct(\"Pending\", { from: Schema.NonEmptyString })\n])\n\n/**\n * The value form of {@link InputRef}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type InputRef = typeof InputRef.Type\n\n/**\n * The material version. Folded into every hashed body so a bump re-keys every\n * node derived from it \u2014 the original's second collision fix, kept.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const version = \"flows/key-material/v2\"\n\n/**\n * Everything that can change a node's result, handed to the digest.\n *\n * `effects` and `placement` are opaque: canonically serialized, never\n * interpreted, which is what keeps the compiler independent of whatever the\n * flow builder decides an effect declaration looks like.\n *\n * `version` must equal {@link version}. `kind` is the effect tier. `inputs`\n * are hashed in order; `layers` and `capabilities` name what the node runs\n * with.\n *\n * @since 0.1.0\n * @category schemas\n */\nexport const KeyMaterial = Schema.Struct({\n  version: Schema.Literal(version),\n  kind: Effects.Tier,\n  // Absence claims determinism; only the explicit declaration changes identity.\n  nondeterministic: Schema.optional(Schema.Literal(true)),\n  body: Schema.Unknown,\n  inputs: Schema.Array(InputRef),\n  layers: Schema.Array(Schema.String),\n  capabilities: Schema.Array(Schema.String),\n  effects: Schema.optional(Schema.Unknown),\n  placement: Schema.optional(Schema.Unknown)\n})\n\n/**\n * The value form of {@link KeyMaterial}.\n *\n * @since 0.1.0\n * @category models\n */\nexport type KeyMaterial = typeof KeyMaterial.Type\n\n/**\n * The graph-local dependencies a material names, in declaration order and\n * without duplicates. The compiler resolves exactly these before hashing, and\n * {@link module:Plan} uses them as the edge set \u2014 one derivation, so an edge\n * and a hashed reference can never disagree.\n *\n * @param material - The node's key material.\n * @returns The `from` of every `Ref` and `Pending` input, first occurrence\n * order, deduplicated.\n * @since 0.1.0\n * @category accessors\n */\nexport const dependencies = (material: KeyMaterial): ReadonlyArray<string> => {\n  const seen = new Set<string>()\n  for (const input of material.inputs) {\n    if (input._tag !== \"Literal\") seen.add(input.from)\n  }\n  return [...seen]\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,aAAwB;AACxB,cAAyB;AAiBlB,MAAM,WAAW,OAAO,MAAM;AAAA,EACnC,OAAO,aAAa,WAAW,EAAE,OAAO,OAAO,QAAQ,CAAC;AAAA,EACxD,OAAO,aAAa,OAAO,EAAE,MAAM,OAAO,gBAAgB,MAAM,OAAO,MAAM,OAAO,MAAM,EAAE,CAAC;AAAA,EAC7F,OAAO,aAAa,WAAW,EAAE,MAAM,OAAO,eAAe,CAAC;AAChE,CAAC;AAiBM,MAAM,UAAU;AAgBhB,MAAM,cAAc,OAAO,OAAO;AAAA,EACvC,SAAS,OAAO,QAAQ,OAAO;AAAA,EAC/B,MAAM,QAAQ;AAAA;AAAA,EAEd,kBAAkB,OAAO,SAAS,OAAO,QAAQ,IAAI,CAAC;AAAA,EACtD,MAAM,OAAO;AAAA,EACb,QAAQ,OAAO,MAAM,QAAQ;AAAA,EAC7B,QAAQ,OAAO,MAAM,OAAO,MAAM;AAAA,EAClC,cAAc,OAAO,MAAM,OAAO,MAAM;AAAA,EACxC,SAAS,OAAO,SAAS,OAAO,OAAO;AAAA,EACvC,WAAW,OAAO,SAAS,OAAO,OAAO;AAC3C,CAAC;AAsBM,MAAM,eAAe,CAAC,aAAiD;AAC5E,QAAM,OAAO,oBAAI,IAAY;AAC7B,aAAW,SAAS,SAAS,QAAQ;AACnC,QAAI,MAAM,SAAS,UAAW,MAAK,IAAI,MAAM,IAAI;AAAA,EACnD;AACA,SAAO,CAAC,GAAG,IAAI;AACjB;",
   "names": []
 }

package/dist/cjs/Plan.d.ts

@@ -25,11 +25,15 @@ 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.
  *
+ * Decoding fails with a `SchemaError` when a path is not workspace-relative.
+ * {@link compile} also refuses a node whose `removes` overlaps its `writes`
+ * with an `invalid_effects` {@link PlanError}.
+ *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const NodeEffects: Schema.Struct<{
+    /** Paths the node reads. A read orders the node after every writer of an overlapping path. */
     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>>;
@@ -40,6 +44,7 @@ export declare const NodeEffects: Schema.Struct<{
             readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
         }>]>>;
     }>]>>;
+    /** Paths the node writes. Two writers of an overlapping path form a conflict. */
     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>>;
@@ -60,6 +65,7 @@ export declare const NodeEffects: Schema.Struct<{
      * conflict pass and the reader-after-writer pass see them as one set.
      */
     readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+    /** How strictly the sandbox enforces these declarations. */
     readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
 }>;
 /**
@@ -67,15 +73,17 @@ export declare const NodeEffects: Schema.Struct<{
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type NodeEffects = typeof NodeEffects.Type;
 /**
- * The plan-time write-conflict strategies of the effect taxonomy.
+ * The plan-time verdict for two writers of an overlapping path:
+ * `serialize` gives the later writer an ordering edge, `lane` records a lane
+ * annotation on both writers and adds no edge, and `fail` refuses the plan
+ * with `overlap_forbidden`. For a pair, `fail` dominates `lane`, which
+ * dominates `serialize`. The same schema as `Effects.ConflictStrategy`.
  *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const PairStrategy: Schema.Literals<readonly ["serialize", "lane", "fail"]>;
 /**
@@ -83,17 +91,16 @@ export declare const PairStrategy: Schema.Literals<readonly ["serialize", "lane"
  *
  * @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.
+ * scheduled node's inputs are invalidated under it. For a pair,
+ * `stop-merge` dominates `delay-rebase`.
  *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const RuntimeStrategy: Schema.Literals<readonly ["delay-rebase", "stop-merge"]>;
 /**
@@ -101,16 +108,17 @@ export declare const RuntimeStrategy: Schema.Literals<readonly ["delay-rebase",
  *
  * @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.
  *
+ * `with` names the other node, `paths` lists the overlapping declarations,
+ * and `strategy` and `runtime` are the verdicts resolved for the pair.
+ *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const ConflictAnnotation: Schema.Struct<{
     readonly with: Schema.NonEmptyString;
@@ -123,7 +131,6 @@ export declare const ConflictAnnotation: Schema.Struct<{
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type ConflictAnnotation = typeof ConflictAnnotation.Type;
 /**
@@ -140,9 +147,11 @@ export type ConflictAnnotation = typeof ConflictAnnotation.Type;
  * a later elaboration can resolve a pair against them without re-reading the
  * flow source.
  *
+ * `generation` is 0 for nodes from {@link compile} and grows by one with each
+ * {@link append}.
+ *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const PlanNode: Schema.Struct<{
     readonly id: Schema.NonEmptyString;
@@ -167,6 +176,7 @@ export declare const PlanNode: Schema.Struct<{
         readonly placement: Schema.optional<Schema.Unknown>;
     }>;
     readonly effects: Schema.Struct<{
+        /** Paths the node reads. A read orders the node after every writer of an overlapping path. */
         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>>;
@@ -177,6 +187,7 @@ export declare const PlanNode: Schema.Struct<{
                 readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
             }>]>>;
         }>]>>;
+        /** Paths the node writes. Two writers of an overlapping path form a conflict. */
         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>>;
@@ -197,6 +208,7 @@ export declare const PlanNode: Schema.Struct<{
          * conflict pass and the reader-after-writer pass see them as one set.
          */
         readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+        /** How strictly the sandbox enforces these declarations. */
         readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
     }>;
     readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
@@ -216,7 +228,6 @@ export declare const PlanNode: Schema.Struct<{
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type PlanNode = typeof PlanNode.Type;
 /**
@@ -229,9 +240,11 @@ export type PlanNode = typeof PlanNode.Type;
  * `baseDigest` is the digest at generation 0: what a human approved and what
  * a `RUNNING` run pins. `digest` advances with every appended elaboration.
  *
+ * Decoding checks only the shape. Use {@link verify} to check that keys,
+ * edges, and digests match the declarations.
+ *
  * @since 0.1.0
  * @category schemas
- * @slop
  */
 export declare const Plan: Schema.Struct<{
     readonly planId: Schema.NonEmptyString;
@@ -262,6 +275,7 @@ export declare const Plan: Schema.Struct<{
             readonly placement: Schema.optional<Schema.Unknown>;
         }>;
         readonly effects: Schema.Struct<{
+            /** Paths the node reads. A read orders the node after every writer of an overlapping path. */
             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>>;
@@ -272,6 +286,7 @@ export declare const Plan: Schema.Struct<{
                     readonly exclude: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
                 }>]>>;
             }>]>>;
+            /** Paths the node writes. Two writers of an overlapping path form a conflict. */
             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>>;
@@ -292,6 +307,7 @@ export declare const Plan: Schema.Struct<{
              * conflict pass and the reader-after-writer pass see them as one set.
              */
             readonly removes: Schema.optional<Schema.$Array<Schema.NonEmptyString>>;
+            /** How strictly the sandbox enforces these declarations. */
             readonly boundaryMode: Schema.Literals<readonly ["hard", "expected"]>;
         }>;
         readonly dependsOn: Schema.$Array<Schema.NonEmptyString>;
@@ -312,7 +328,6 @@ export declare const Plan: Schema.Struct<{
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type Plan = typeof Plan.Type;
 /**
@@ -320,13 +335,17 @@ export type Plan = typeof Plan.Type;
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface NodeDraft {
+    /** A non-empty id, unique within the plan. */
     readonly id: string;
+    /** The key inputs. Its `Ref` inputs name the node's material dependencies. */
     readonly material: KeyMaterial.KeyMaterial;
+    /** The declared reads, writes, and removals. They replace `material.effects`. */
     readonly effects: NodeEffects;
+    /** `step`, `agent`, or `merge`. Defaults to `step`. */
     readonly kind?: PlanNode["kind"] | undefined;
+    /** A safe integer scheduling priority. Defaults to 0. */
     readonly priority?: number | undefined;
     /** This declaration's preferred plan-time verdict for a detected overlap. */
     readonly conflictStrategy?: PairStrategy | undefined;
@@ -338,11 +357,22 @@ declare const PlanError_base: Schema.Class<PlanError, Schema.TaggedStruct<"@smth
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * A graph the compiler refuses.
+ * A graph the compiler refuses. `code` names the rule:
+ *
+ * - `cycle`: material or inferred edges form a cycle.
+ * - `unknown_dependency`: a `Ref` names a node that is not in the plan.
+ * - `duplicate_node`: two nodes share an id.
+ * - `overlap_forbidden`: two unordered writers overlap and the pair's
+ *   strategy is `fail`.
+ * - `invalid_effects`: a node both writes and removes one path.
+ * - `invalid_node`: a draft field, the plan id, or the flow name is malformed.
+ * - `invalid_plan`: {@link verify} found a plan that does not match its
+ *   declarations.
+ * - `graph_too_large`: the plan exceeds {@link maximumPlanNodes} or the
+ *   effect-analysis work budget.
  *
  * @since 0.1.0
  * @category errors
- * @slop
  */
 export declare class PlanError extends PlanError_base {
 }
@@ -354,7 +384,6 @@ export declare class PlanError extends PlanError_base {
  *
  * @since 1.0.0
  * @category limits
- * @slop
  */
 export declare const maximumPlanNodes = 10000;
 /**
@@ -367,9 +396,15 @@ export declare const maximumPlanNodes = 10000;
  * {@link maximumPlanNodes} and fail with `graph_too_large` above that limit
  * or the effect-analysis work budget. Analysis yields periodically.
  *
+ * The options and drafts are copied when `compile` is called, so later
+ * caller mutation does not reach the plan. The result is deeply frozen.
+ *
+ * @param options - `planId` and `flow` name the plan; `nodes` are the drafts.
+ * @returns The generation-0 plan, whose `baseDigest` equals its `digest`.
+ * Fails with {@link PlanError} for a refused graph, `KeyMaterialError` or
+ * `SchemaError` when a key cannot be derived.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export declare const compile: (options: {
     readonly planId: string;
@@ -386,9 +421,16 @@ export declare const compile: (options: {
  * Re-ordering after a reconciliation happens by re-keying *future* steps,
  * never by rewriting history.
  *
+ * A plan not produced by this module is checked with {@link verify} first.
+ *
+ * @param plan - The plan to grow.
+ * @param drafts - At least one new node. Ids must not repeat existing ones;
+ *   `Ref` inputs may name existing nodes.
+ * @returns The plan with one more generation and a new `digest`. Fails with
+ * {@link PlanError} (`invalid_node` for an empty `drafts`, `invalid_plan` for a
+ * plan that fails verification), `KeyMaterialError`, or `SchemaError`.
  * @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>;
 /**
@@ -409,9 +451,10 @@ export declare const verify: (input: unknown) => Effect.Effect<Plan, PlanError |
  * The nodes added by the newest generation: what {@link module:PlanStore}
  * appends and what the `subgraph-appended` journal record names.
  *
+ * @param plan - A plan.
+ * @returns The nodes whose generation equals `plan.generation`, in order.
  * @since 0.1.0
  * @category accessors
- * @slop
  */
 export declare const generationNodes: (plan: Plan) => ReadonlyArray<PlanNode>;
 /**
@@ -419,9 +462,11 @@ export declare const generationNodes: (plan: Plan) => ReadonlyArray<PlanNode>;
  * {@link verify}: such values take verify's trusted fast path and need no
  * second schema validation.
  *
+ * @param input - Any value.
+ * @returns `true` only for a plan returned by {@link compile},
+ * {@link append}, or {@link verify}; a structurally equal copy returns `false`.
  * @since 1.0.0
  * @category guards
- * @slop
  */
 export declare const isVerified: (input: unknown) => input is Plan;
 /**
@@ -431,9 +476,13 @@ export declare const isVerified: (input: unknown) => input is Plan;
  * plan's integrity from the already-verified prefix instead of decoding and
  * re-verifying every stored row.
  *
+ * For a generation-0 plan no generation precedes the newest, so this is the
+ * digest of an empty node list.
+ *
+ * @param plan - A plan.
+ * @returns The approval digest of the nodes older than `plan.generation`.
  * @since 1.0.0
  * @category accessors
- * @slop
  */
 export declare const prefixDigest: (plan: Plan) => Effect.Effect<StepKey.StepKey, StepKey.KeyMaterialError | Schema.SchemaError, Crypto.Crypto>;
 export {};

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

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

package/dist/cjs/Plan.js

@@ -56,7 +56,9 @@ var import_JsonMirror = require("./internal/JsonMirror.js");
 var KeyMaterial = __toESM(require("./KeyMaterial.js"), 1);
 var StepKey = __toESM(require("./StepKey.js"), 1);
 const NodeEffects = Schema.Struct({
+  /** Paths the node reads. A read orders the node after every writer of an overlapping path. */
   reads: Schema.Array(FileSet.ReadDeclaration),
+  /** Paths the node writes. Two writers of an overlapping path form a conflict. */
   writes: Schema.Array(FileSet.Declaration),
   /**
    * Paths the node declares it will DELETE. A removal mutates the world exactly
@@ -64,6 +66,7 @@ const NodeEffects = Schema.Struct({
    * conflict pass and the reader-after-writer pass see them as one set.
    */
   removes: Schema.optional(Schema.Array(FileSet.Pattern)),
+  /** How strictly the sandbox enforces these declarations. */
   boundaryMode: FileSet.BoundaryMode
 });
 const PairStrategy = Effects.ConflictStrategy;