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

package/dist/esm/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/esm/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/esm/Plan.js

@@ -31,12 +31,17 @@ import * as StepKey from "./StepKey.js";
  * 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 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
@@ -44,24 +49,28 @@ export 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
 });
 /**
- * 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 const PairStrategy = Effects.ConflictStrategy;
 /**
  * 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 const RuntimeStrategy = Schema.Literals(["delay-rebase", "stop-merge"]);
 /** @private */
@@ -70,9 +79,11 @@ const NodeKind = Schema.Literals(["step", "agent", "merge"]);
  * 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 const ConflictAnnotation = Schema.Struct({
     with: Schema.NonEmptyString,
@@ -94,9 +105,11 @@ export const ConflictAnnotation = Schema.Struct({
  * 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 const PlanNode = Schema.Struct({
     id: Schema.NonEmptyString,
@@ -121,9 +134,11 @@ export const PlanNode = Schema.Struct({
  * `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 const Plan = Schema.Struct({
     planId: Schema.NonEmptyString,
@@ -134,11 +149,22 @@ export const Plan = Schema.Struct({
     nodes: Schema.Array(PlanNode)
 });
 /**
- * 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 class PlanError extends Schema.TaggedError()("@smthrs/plan/PlanError", {
     code: Schema.Literals([
@@ -162,7 +188,6 @@ export class PlanError extends Schema.TaggedError()("@smthrs/plan/PlanError", {
  *
  * @since 1.0.0
  * @category limits
- * @slop
  */
 export const maximumPlanNodes = 10_000;
 /** @private */
@@ -502,9 +527,15 @@ const keyNodes = (drafts, existing, generation) => Effect.gen(function* () {
  * {@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 const compile = (options) => {
     const captured = snapshot(options);
@@ -538,9 +569,16 @@ export 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 const append = (plan, drafts) => {
     const candidate = frozenPlans.has(plan) ? plan : snapshot(plan);
@@ -643,9 +681,10 @@ export const verify = (input) => Effect.gen(function* () {
  * 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 const generationNodes = (plan) => plan.nodes.filter((node) => node.generation === plan.generation);
 /**
@@ -653,9 +692,11 @@ export const generationNodes = (plan) => plan.nodes.filter((node) => node.genera
  * {@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 const isVerified = (input) => typeof input === "object" && input !== null && frozenPlans.has(input);
 /**
@@ -665,9 +706,13 @@ export const isVerified = (input) => typeof input === "object" && input !== null
  * 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 const prefixDigest = (plan) => digestOf(plan.planId, plan.flow, plan.nodes.filter((node) => node.generation < plan.generation));
 //# sourceMappingURL=Plan.js.map