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

package/src/Plan.ts

@@ -34,12 +34,17 @@ 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 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
@@ -47,6 +52,7 @@ 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
 })
 
@@ -55,16 +61,18 @@ export 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 const PairStrategy = Effects.ConflictStrategy
 
@@ -73,18 +81,17 @@ export const PairStrategy = Effects.ConflictStrategy
  *
  * @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 const RuntimeStrategy = Schema.Literals(["delay-rebase", "stop-merge"])
 
@@ -93,7 +100,6 @@ export const RuntimeStrategy = Schema.Literals(["delay-rebase", "stop-merge"])
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type RuntimeStrategy = typeof RuntimeStrategy.Type
 
@@ -104,9 +110,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,
@@ -120,7 +128,6 @@ export const ConflictAnnotation = Schema.Struct({
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type ConflictAnnotation = typeof ConflictAnnotation.Type
 
@@ -138,9 +145,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 const PlanNode = Schema.Struct({
   id: Schema.NonEmptyString,
@@ -161,7 +170,6 @@ export const PlanNode = Schema.Struct({
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type PlanNode = typeof PlanNode.Type
 
@@ -175,9 +183,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 const Plan = Schema.Struct({
   planId: Schema.NonEmptyString,
@@ -193,7 +203,6 @@ export const Plan = Schema.Struct({
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type Plan = typeof Plan.Type
 
@@ -202,13 +211,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
@@ -217,11 +230,22 @@ export interface NodeDraft {
 }
 
 /**
- * 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<PlanError>()("@smthrs/plan/PlanError", {
   code: Schema.Literals([
@@ -245,7 +269,6 @@ export class PlanError extends Schema.TaggedError<PlanError>()("@smthrs/plan/Pla
  *
  * @since 1.0.0
  * @category limits
- * @slop
  */
 export const maximumPlanNodes = 10_000
 
@@ -671,9 +694,15 @@ const keyNodes = (
  * {@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: {
   readonly planId: string
@@ -710,9 +739,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: Plan,
@@ -832,9 +868,10 @@ export const verify = (
  * 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): ReadonlyArray<PlanNode> =>
   plan.nodes.filter((node) => node.generation === plan.generation)
@@ -844,9 +881,11 @@ export 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 const isVerified = (input: unknown): input is Plan =>
   typeof input === "object" && input !== null && frozenPlans.has(input as Plan)
@@ -858,9 +897,13 @@ export 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 const prefixDigest = (
   plan: Plan

package/src/PlanDiff.ts

@@ -6,10 +6,10 @@
  * 'what is different about this run' is a set comparison, not archaeology."
  * This module is the set comparison.
  *
- * The **verdict** is the key: two nodes with the same id and the same key are
- * the same step and nothing else needs saying. The **attribution** —
- * `changed: ["input[1]"]` — is a report for a human, derived by comparing the
- * declarations field by field. It is deliberately not part of any digest.
+ * The **verdict** is the key: two nodes with the same key are the same step,
+ * under the same id or a moved one, and nothing else needs saying. The
+ * **attribution** — `changed: ["input[1]"]` — is a report for a human, derived
+ * by comparing the declarations field by field. It is deliberately not part of any digest.
  *
  * @since 0.1.0
  */
@@ -23,11 +23,13 @@ import type * as Planned from "./Planned.ts"
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface Rekeyed {
+  /** The node's id in the newer plan. */
   readonly id: string
+  /** The step key the paired node carried in the older plan. */
   readonly from: string
+  /** The step key the node carries in the newer plan. */
   readonly to: string
   /**
    * Field labels such as `"kind"`, `"body"`, `"layers"`, `"capabilities"`,
@@ -44,12 +46,15 @@ export interface Rekeyed {
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface PlanDiff {
+  /** Ids, in the newer plan, of nodes with no counterpart in the older plan. */
   readonly added: ReadonlyArray<string>
+  /** Ids, in the older plan, of nodes with no counterpart in the newer plan. */
   readonly removed: ReadonlyArray<string>
+  /** Nodes paired by id whose step key changed, with the fields that changed it. */
   readonly rekeyed: ReadonlyArray<Rekeyed>
+  /** Ids, in the newer plan, of nodes whose step key is unchanged, including nodes whose id moved. */
   readonly unchanged: ReadonlyArray<string>
 }
 
@@ -157,24 +162,64 @@ const changedFields = (
 /**
  * Compares a plan against the last plan for the same flow.
  *
+ * Nodes pair in three passes, each over the nodes no earlier pass paired:
+ * the same id with the same key, then the same key under any id, then the
+ * same id with a different key. The second pass exists because flow node ids
+ * can be positional: inserting a step shifts the ids after it while their
+ * keys stay equal, and that is one added step, not a re-key of every later
+ * one (#3905).
+ *
+ * `added`, `rekeyed`, and `unchanged` name nodes by their id in `next`;
+ * `removed` names nodes by their id in `previous`. A moved id can therefore
+ * appear once in `removed` or `added` and once in `unchanged`.
+ *
+ * @param previous - The last plan recorded for the flow.
+ * @param next - The plan to compare against it.
+ * @returns The added, removed, re-keyed, and unchanged node ids, each in its
+ * plan's node order.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const diff = (previous: Plan.Plan, next: Plan.Plan): PlanDiff => {
+  // pairs maps a next node to the previous node it is the same step as.
+  const pairs = new Map<Plan.PlanNode, Plan.PlanNode>()
+  const paired = new Set<Plan.PlanNode>()
+  const pair = (node: Plan.PlanNode, original: Plan.PlanNode) => {
+    pairs.set(node, original)
+    paired.add(original)
+  }
   const before = new Map(previous.nodes.map((node) => [node.id, node]))
-  const after = new Map(next.nodes.map((node) => [node.id, node]))
+  for (const node of next.nodes) {
+    const original = before.get(node.id)
+    if (original !== undefined && original.key === node.key) pair(node, original)
+  }
+  const byKey = new Map<string, Array<Plan.PlanNode>>()
+  for (const node of previous.nodes) {
+    if (paired.has(node)) continue
+    const same = byKey.get(node.key)
+    if (same === undefined) byKey.set(node.key, [node])
+    else same.push(node)
+  }
+  for (const node of next.nodes) {
+    if (pairs.has(node)) continue
+    const original = byKey.get(node.key)?.shift()
+    if (original !== undefined) pair(node, original)
+  }
   const rekeyedIds = new Set<string>()
   for (const node of next.nodes) {
+    if (pairs.has(node)) continue
     const original = before.get(node.id)
-    if (original !== undefined && original.key !== node.key) rekeyedIds.add(node.id)
+    if (original !== undefined && !paired.has(original)) {
+      pair(node, original)
+      rekeyedIds.add(node.id)
+    }
   }
   const added: Array<string> = []
   const rekeyed: Array<Rekeyed> = []
   const unchanged: Array<string> = []
   const sameField = fieldComparison()
   for (const node of next.nodes) {
-    const original = before.get(node.id)
+    const original = pairs.get(node)
     if (original === undefined) {
       added.push(node.id)
       continue
@@ -192,7 +237,7 @@ export const diff = (previous: Plan.Plan, next: Plan.Plan): PlanDiff => {
   }
   return {
     added,
-    removed: previous.nodes.filter((node) => !after.has(node.id)).map((node) => node.id),
+    removed: previous.nodes.filter((node) => !paired.has(node)).map((node) => node.id),
     rekeyed,
     unchanged
   }

package/src/StepKey.ts

@@ -43,7 +43,6 @@ import type * as KeyMaterial from "./KeyMaterial.ts"
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type StepKey = StoredKey
 
@@ -72,7 +71,6 @@ type GraphReference = "ref" | "pending" | "ref-projected"
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface DigestInput {
   readonly [DigestInputTypeId]: typeof DigestInputTypeId
@@ -94,9 +92,12 @@ export interface DigestInput {
  * Nominally tags a precomputed digest so it is hashed as a digest reference
  * rather than a literal value.
  *
+ * @param digest - The precomputed digest.
+ * @param reference - Which graph reference resolved to the digest, and the
+ *   projection path for `ref-projected`. Omit for a plain digest.
+ * @returns The tagged digest input.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const digestInput = (
   digest: string,
@@ -112,11 +113,13 @@ export const digestInput = (
 })
 
 /**
- * Type guard for values produced by {@link digestInput}.
+ * Type guard for values produced by {@link digestInput}. A plain object
+ * shaped like `{ digest: "..." }` is not one.
  *
+ * @param value - Any value.
+ * @returns `true` only for a value carrying the private digest-input brand.
  * @since 0.1.0
  * @category guards
- * @slop
  */
 export const isDigestInput = (value: unknown): value is DigestInput =>
   typeof value === "object" && value !== null && DigestInputTypeId in value &&
@@ -146,7 +149,6 @@ export const isDigestInput = (value: unknown): value is DigestInput =>
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export type EnvironmentIdentity = typeof EnvironmentIdentity.Type
 
@@ -180,9 +182,13 @@ export const EnvironmentIdentity = Schema.Union([
  * digest. Entries are sound only while each settled `from` value is immutable;
  * callers must create a fresh memo when those values can change.
  *
+ * `digest(from, path, compute)` runs `compute` once per address and shares its
+ * result with concurrent callers. A failed or interrupted computation is not
+ * kept: the next caller recomputes, and a waiter whose leader was interrupted
+ * becomes the new leader instead of inheriting the interrupt.
+ *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface DigestMemo {
   readonly digest: (
@@ -196,37 +202,42 @@ export interface DigestMemo {
  * Creates an empty projected-value digest memo. Projection addresses are
  * JSON-encoded `[from, path]` tuples so segment boundaries are unambiguous.
  *
+ * @returns A memo with no entries.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const makeDigestMemo = (): DigestMemo => {
   const entries = new Map<string, Deferred.Deferred<StepKey, Schema.SchemaError>>()
+  // Registering the entry and installing its exit handler run uninterruptibly,
+  // so an interrupt can never land between them and strand a Deferred that no
+  // fiber will complete. The wait and the computation stay interruptible.
   const digest: DigestMemo["digest"] = (from, path, compute) =>
-    Effect.suspend(() => {
-      const address = JSON.stringify([from, path])
-      const existing = entries.get(address)
-      if (existing !== undefined) {
-        return Effect.flatMap(Effect.exit(Deferred.await(existing)), (exit) => {
-          if (Exit.isSuccess(exit)) return Effect.succeed(exit.value)
-          // A waiter did not request the leader's cancellation. It competes to
-          // become the replacement leader instead of inheriting that interrupt.
-          return Cause.hasInterrupts(exit.cause) ? digest(from, path, compute) : Effect.failCause(exit.cause)
-        })
-      }
-      const pending = Deferred.makeUnsafe<StepKey, Schema.SchemaError>()
-      entries.set(address, pending)
-      return compute.pipe(
-        Effect.onExit((exit) =>
-          Effect.gen(function*() {
-            if (Exit.isFailure(exit) && entries.get(address) === pending) {
-              entries.delete(address)
-            }
-            yield* Deferred.done(pending, exit)
-          })
+    Effect.uninterruptibleMask((restore) =>
+      Effect.suspend(() => {
+        const address = JSON.stringify([from, path])
+        const existing = entries.get(address)
+        if (existing !== undefined) {
+          return restore(Effect.flatMap(Effect.exit(Deferred.await(existing)), (exit) => {
+            if (Exit.isSuccess(exit)) return Effect.succeed(exit.value)
+            // A waiter did not request the leader's cancellation. It competes to
+            // become the replacement leader instead of inheriting that interrupt.
+            return Cause.hasInterrupts(exit.cause) ? digest(from, path, compute) : Effect.failCause(exit.cause)
+          }))
+        }
+        const pending = Deferred.makeUnsafe<StepKey, Schema.SchemaError>()
+        entries.set(address, pending)
+        return restore(compute).pipe(
+          Effect.onExit((exit) =>
+            Effect.gen(function*() {
+              if (Exit.isFailure(exit) && entries.get(address) === pending) {
+                entries.delete(address)
+              }
+              yield* Deferred.done(pending, exit)
+            })
+          )
         )
-      )
-    })
+      })
+    )
   return { digest }
 }
 
@@ -235,7 +246,6 @@ export const makeDigestMemo = (): DigestMemo => {
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface ContentIdentity {
   readonly body: unknown
@@ -256,7 +266,6 @@ export interface ContentIdentity {
  *
  * @since 0.1.0
  * @category models
- * @slop
  */
 export interface OrdinalIdentity {
   readonly runId: string
@@ -266,11 +275,18 @@ export interface OrdinalIdentity {
 }
 
 /**
- * Stable failures while resolving graph-local dependency references.
+ * Stable failures while deriving a key. `code` names the rule:
+ *
+ * - `invalid_environment`: an {@link EnvironmentIdentity} that is neither
+ *   declared nor run-scoped.
+ * - `missing_dependency`: a `Ref` or `Pending` input names a node with no
+ *   recorded digest, or, at dispatch, a `Ref` names one with no settled
+ *   result.
+ * - `non_content_material`: a content-key constructor received material whose
+ *   tier is not `sealed`.
  *
  * @since 0.1.0
  * @category errors
- * @slop
  */
 export class KeyMaterialError extends Schema.TaggedError<KeyMaterialError>()("@smthrs/plan/KeyMaterialError", {
   code: Schema.Literals(["invalid_environment", "missing_dependency", "non_content_material"]),
@@ -418,9 +434,11 @@ export const environmentIdentity = (
  * declarations are normalized before serialization; write declarations remain
  * part of the identity even when the step writes nothing.
  *
+ * @param identity - The step's content material.
+ * @returns The content key. Fails with `invalid_environment` for a malformed
+ * environment, or `SchemaError` when the material cannot be serialized.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const content = (
   identity: ContentIdentity
@@ -442,9 +460,10 @@ export const content = (
  * Produces a run-local ordinal key for compensable, irreversible, or unsealed
  * work. These keys intentionally cannot be reused across runs.
  *
+ * @param identity - The run id, optional parent scope, ordinal, and tier.
+ * @returns The ordinal key.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const ordinal = (
   identity: OrdinalIdentity
@@ -461,9 +480,13 @@ export const ordinal = (
  * and never enter the hashed value — rename a node and nothing re-keys; change
  * what a node consumes and everything downstream of it does.
  *
+ * @param material - The node's key material; its tier must be `sealed`.
+ * @param dependencyDigests - The key of every node the material references,
+ *   by node id.
+ * @returns The content key. Fails with `non_content_material` for a
+ * non-sealed tier and `missing_dependency` for an unresolved reference.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const fromKeyMaterial = (
   material: KeyMaterial.KeyMaterial,
@@ -632,7 +655,6 @@ const orderingOnly = "ordering-only"
  *
  * @since 0.1.0
  * @category utilities
- * @slop
  */
 export const project = (value: unknown, path: ReadonlyArray<string>): unknown => {
   let current = value
@@ -667,9 +689,13 @@ export const project = (value: unknown, path: ReadonlyArray<string>): unknown =>
  * halt rule guarantees it: a dependent of failed or skipped work never
  * dispatches, so a `Ref` always resolves against a success.
  *
+ * @param options - The material, the dependencies' settled results, the
+ *   measured hermetic boundary, and an optional environment and memo.
+ * @returns The dispatch key. Fails with `non_content_material` for a
+ * non-sealed tier, `missing_dependency` for a `Ref` absent from `results`,
+ * or `invalid_environment` for a malformed environment.
  * @since 0.1.0
  * @category constructors
- * @slop
  */
 export const dispatchIdentity = (options: {
   readonly material: KeyMaterial.KeyMaterial