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

package/src/PlanDiff.ts

@@ -0,0 +1,199 @@
+/**
+ * A plan comparison, as a value.
+ *
+ * A plan diff answers "which steps changed key (and _which input_
+ * changed them), what entered the envelope, what joined the release set —
+ * '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.
+ *
+ * @since 0.1.0
+ */
+
+import { jsonMirror } from "./internal/JsonMirror.ts"
+import type * as Plan from "./Plan.ts"
+import type * as Planned from "./Planned.ts"
+
+/**
+ * A node whose key moved, with the fields that moved it.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface Rekeyed {
+  readonly id: string
+  readonly from: string
+  readonly to: string
+  /**
+   * Field labels such as `"kind"`, `"body"`, `"layers"`, `"capabilities"`,
+   * `"effects"`, and `"input[0]"` whose declaration differs. `"kind"` is the
+   * effect tier (`sealed`, `compensable`, or `irreversible`). A
+   * `Pending`-referenced upstream re-key is attributed to that input position
+   * too. `changed` is empty only when none of the compared fields moved.
+   */
+  readonly changed: ReadonlyArray<string>
+}
+
+/**
+ * What changed between two plans of the same flow.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface PlanDiff {
+  readonly added: ReadonlyArray<string>
+  readonly removed: ReadonlyArray<string>
+  readonly rekeyed: ReadonlyArray<Rekeyed>
+  readonly unchanged: ReadonlyArray<string>
+}
+
+/**
+ * Order-insensitive structural comparison for the attribution report only.
+ * Digests go through RFC 8785 canonical JSON; this does not have to, and
+ * saying so keeps the two from being confused.
+ *
+ * @private
+ */
+const stable = (value: unknown): string => {
+  if (typeof value === "bigint") return `${value}n`
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined"
+  if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`
+  const entries = Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left < right ? -1 : 1)
+  return `{${entries.map(([name, entry]) => `${JSON.stringify(name)}:${stable(entry)}`).join(",")}}`
+}
+
+/**
+ * A planned value compares as the reference an AST stores for it, so the same
+ * reference at the same place is unchanged.
+ *
+ * @private
+ */
+const plannedReference = (_value: unknown, reference: Planned.Reference) => ({
+  _tag: "PlannedReference",
+  node: reference.node,
+  path: reference.path
+})
+
+/** @private */
+type ComparisonToken = string | symbol
+
+/**
+ * Projects compared fields through the key's JSON semantics. A refused value
+ * receives an identity token scoped to its node and field, so the same value
+ * remains equal to itself without equating two distinct refused values.
+ *
+ * @private
+ */
+const fieldComparison = () => {
+  const refused = new Map<unknown, Map<string, symbol>>()
+  const token = (input: unknown, nodeId: string, field: string): ComparisonToken => {
+    try {
+      return stable(jsonMirror(input, plannedReference))
+    } catch {
+      const address = JSON.stringify([nodeId, field])
+      let fields = refused.get(input)
+      if (fields === undefined) {
+        fields = new Map()
+        refused.set(input, fields)
+      }
+      let sentinel = fields.get(address)
+      if (sentinel === undefined) {
+        sentinel = Symbol(address)
+        fields.set(address, sentinel)
+      }
+      return sentinel
+    }
+  }
+  return (previous: unknown, next: unknown, nodeId: string, field: string): boolean =>
+    token(previous, nodeId, field) === token(next, nodeId, field)
+}
+
+/** @private */
+const changedFields = (
+  previous: Plan.PlanNode,
+  next: Plan.PlanNode,
+  rekeyedDependencies: ReadonlySet<string>,
+  sameField: ReturnType<typeof fieldComparison>
+): ReadonlyArray<string> => {
+  const changed: Array<string> = []
+  // StepKey.materialBody is the identity list this attribution must mirror.
+  // Inputs, layers, and capabilities complete fromKeyMaterial's hashed value,
+  // and material.kind selects the key namespace (content versus tier-bearing
+  // plan declaration), so a tier-only move still re-keys and is blamed here.
+  if (!sameField(previous.material.version, next.material.version, next.id, "version")) changed.push("version")
+  if (previous.material.kind !== next.material.kind) changed.push("kind")
+  if (!sameField(previous.material.body, next.material.body, next.id, "body")) changed.push("body")
+  if (!sameField(previous.material.nondeterministic, next.material.nondeterministic, next.id, "nondeterministic")) {
+    changed.push("nondeterministic")
+  }
+  if (!sameField(previous.material.effects, next.material.effects, next.id, "effects")) changed.push("effects")
+  if (!sameField(previous.material.placement, next.material.placement, next.id, "placement")) {
+    changed.push("placement")
+  }
+  const width = Math.max(previous.material.inputs.length, next.material.inputs.length)
+  for (let index = 0; index < width; index++) {
+    const before = previous.material.inputs[index]
+    const after = next.material.inputs[index]
+    const field = `input[${index}]`
+    if (before === undefined || after === undefined || !sameField(before, after, next.id, field)) {
+      changed.push(field)
+      continue
+    }
+    if (after._tag !== "Literal" && rekeyedDependencies.has(after.from)) changed.push(field)
+  }
+  if (!sameField(previous.material.layers, next.material.layers, next.id, "layers")) changed.push("layers")
+  if (!sameField(previous.material.capabilities, next.material.capabilities, next.id, "capabilities")) {
+    changed.push("capabilities")
+  }
+  return changed
+}
+
+/**
+ * Compares a plan against the last plan for the same flow.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export const diff = (previous: Plan.Plan, next: Plan.Plan): PlanDiff => {
+  const before = new Map(previous.nodes.map((node) => [node.id, node]))
+  const after = new Map(next.nodes.map((node) => [node.id, node]))
+  const rekeyedIds = new Set<string>()
+  for (const node of next.nodes) {
+    const original = before.get(node.id)
+    if (original !== undefined && original.key !== node.key) 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)
+    if (original === undefined) {
+      added.push(node.id)
+      continue
+    }
+    if (original.key === node.key) {
+      unchanged.push(node.id)
+      continue
+    }
+    rekeyed.push({
+      id: node.id,
+      from: original.key,
+      to: node.key,
+      changed: changedFields(original, node, rekeyedIds, sameField)
+    })
+  }
+  return {
+    added,
+    removed: previous.nodes.filter((node) => !after.has(node.id)).map((node) => node.id),
+    rekeyed,
+    unchanged
+  }
+}

package/src/Planned.ts

@@ -0,0 +1,208 @@
+/**
+ * The placeholder a body sees where a step result will be.
+ *
+ * A flow body runs at PLAN time, so its
+ * own payload is real data while every step result is a value that does not
+ * exist yet. That value has a name and one rule: a planned value may be **passed** — into a payload field,
+ * into a branch, into a map — and field access is allowed, because it records a
+ * reference path. It may never be **computed on**.
+ *
+ * {@link Planned} is branded, so arithmetic is a compile error.
+ * {@link make} returns a strict proxy
+ * whose `Symbol.toPrimitive`, `valueOf`, `toString`, `toJSON`, and call traps
+ * throw {@link module:GraphBuildError.GraphBuildError} rather than let a plan be
+ * built around `NaN` or `"[object Object]"`. The lenient proxy this adapts
+ * (`@smthrs/core`'s `Graph.plannedValue`) answered `toPrimitive` with a
+ * readable string, which is exactly the silent-wrong-plan path this module
+ * exists to close.
+ *
+ * JavaScript does not expose traps for `Boolean(value)` or strict identity
+ * (`value === other`), so those operations cannot be refused at run time.
+ * They reveal only proxy truthiness or identity and never the planned result;
+ * authors must use {@link module:Node.branch} for decisions on real values.
+ * Type-aware ESLint `@typescript-eslint/strict-boolean-expressions` rejects
+ * planned conditions, but does not reject explicit Boolean coercion or all
+ * reference comparisons. Those still require review.
+ *
+ * @since 0.1.0
+ */
+
+import type * as Types from "effect/Types"
+import { GraphBuildError } from "./GraphBuildError.ts"
+
+/**
+ * The brand carried by every planned value, and the key its reference is read
+ * from. Interned with `Symbol.for` so a value that crossed a module boundary is
+ * still recognised. The interned symbol is a recognition aid, not a
+ * capability, so {@link reference} validates the value stored under it.
+ *
+ * @since 0.1.0
+ * @category symbols
+ * @slop
+ */
+export const TypeId: unique symbol = Symbol.for("@smthrs/plan/Planned")
+
+/**
+ * The type-level form of {@link TypeId}.
+ *
+ * @since 0.1.0
+ * @category symbols
+ * @slop
+ */
+export type TypeId = typeof TypeId
+
+/**
+ * What a planned value points at: the node that will produce the result, and
+ * the property path read from it. `path` is empty for the result itself.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface Reference {
+  readonly node: string
+  readonly path: ReadonlyArray<string>
+}
+
+/**
+ * A {@link Reference} plus the phantom type of the value it stands for, so
+ * `Planned<string>` and `Planned<number>` are not interchangeable.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export interface Identity<out T> extends Reference {
+  readonly _T: Types.Covariant<T>
+}
+
+/**
+ * A step result that has not been produced yet.
+ *
+ * The brand rejects arithmetic and ordinary value arguments. The mapped half keeps field
+ * access typed — `result.files` is a `Planned` of the field, which is what
+ * makes "pass it on, never compute on it" expressible rather than merely
+ * documented.
+ *
+ * @since 0.1.0
+ * @category models
+ * @slop
+ */
+export type Planned<T> =
+  & { readonly [TypeId]: Identity<T> }
+  & ([T] extends [object] ? { readonly [K in keyof T]: Planned<T[K]> } : unknown)
+
+/**
+ * The operations that are computation rather than reference, keyed by the
+ * property that performs them. `toJSON` is here because `JSON.stringify` reads
+ * it, and a plan that serialized a placeholder would look correct.
+ *
+ * @private
+ */
+const refusals = new Map<PropertyKey, string>([
+  [Symbol.toPrimitive, "Symbol.toPrimitive"],
+  ["valueOf", "valueOf"],
+  ["toString", "toString"],
+  ["toJSON", "toJSON"]
+])
+
+/** @private */
+const describe = (reference: Reference): string =>
+  reference.path.length === 0 ? reference.node : `${reference.node}.${reference.path.join(".")}`
+
+/**
+ * The one refusal this module raises. The guidance is spelled out rather than
+ * linked because the author reading it is inside a body and needs the
+ * correction on the spot.
+ *
+ * @private
+ */
+const refuse = (reference: Reference, operation: string): GraphBuildError =>
+  new GraphBuildError({
+    code: "planned_value_computed",
+    node: reference.node,
+    path: reference.path,
+    message: `Planned value ${describe(reference)} was computed at plan time by ${operation}. ` +
+      "Use Node.map to compute, Node.branch to decide, or pass the value into a payload."
+  })
+
+/**
+ * The proxy itself. `_T` of {@link Identity} is a phantom and never exists at
+ * run time, so the trap carries the plain {@link Reference}.
+ *
+ * @private
+ */
+const placeholder = (reference: Reference): unknown => {
+  /* v8 ignore next -- a Proxy application always enters the `apply` trap below, so the callable target is unreachable by construction */
+  const target = (): undefined => undefined
+  return new Proxy(target, {
+    get: (_target, key) => {
+      if (key === TypeId) return reference
+      const refusal = refusals.get(key)
+      if (refusal !== undefined) throw refuse(reference, refusal)
+      // Not a thenable: a body that returns a planned value inside a promise
+      // must resolve to the placeholder, not hang awaiting a proxy.
+      if (key === "then") return undefined
+      return placeholder({ node: reference.node, path: [...reference.path, String(key)] })
+    },
+    apply: () => {
+      throw refuse(reference, "function application")
+    },
+    has: () => {
+      throw refuse(reference, "property existence (`in`)")
+    },
+    ownKeys: () => {
+      throw refuse(reference, "property enumeration")
+    }
+  })
+}
+
+/**
+ * Creates the strict placeholder standing for a node's result.
+ *
+ * Planning hands one of these to every builder that consumes an upstream
+ * value — a branch arm, a continuation — and reads the {@link Reference} back
+ * off whatever the builder passed it into.
+ *
+ * @since 0.1.0
+ * @category constructors
+ * @slop
+ */
+export const make = <T>(node: string): Planned<T> => placeholder({ node, path: [] }) as Planned<T>
+
+/** @private */
+const carrier = (value: unknown): value is { readonly [TypeId]?: Reference } =>
+  (typeof value === "object" && value !== null) || typeof value === "function"
+
+/** @private */
+const validReference = (value: unknown): value is Reference =>
+  typeof value === "object" && value !== null &&
+  typeof (value as Reference).node === "string" && (value as Reference).node.length > 0 &&
+  Array.isArray((value as Reference).path) &&
+  Array.from((value as Reference).path).every((segment) => typeof segment === "string")
+
+/**
+ * Reads the reference a planned value records, or `undefined` for anything
+ * else. An interned symbol is a recognition aid rather than a capability, so a
+ * forged carrier is accepted only when its node and path have the complete
+ * reference shape. This is how a payload is scanned for the upstream results
+ * it consumes.
+ *
+ * @since 0.1.0
+ * @category accessors
+ * @slop
+ */
+export const reference = (value: unknown): Reference | undefined => {
+  if (!carrier(value)) return undefined
+  const candidate = value[TypeId]
+  return validReference(candidate) ? candidate : undefined
+}
+
+/**
+ * Checks whether a value is a planned placeholder.
+ *
+ * @since 0.1.0
+ * @category guards
+ * @slop
+ */
+export const isPlanned = (value: unknown): value is Planned<unknown> => reference(value) !== undefined

package/src/Repetition.ts

@@ -0,0 +1,33 @@
+/**
+ * What a bounded repetition does when it reaches its ceiling.
+ *
+ * This is the ONE ceiling vocabulary. `@smthrs/flow`'s `Poll.make` takes it as
+ * `onTimeout`, for the attempt a poll gives up on, and `@smthrs/patterns`'
+ * `Loop` takes it as `onMaxReached`, for the iteration a loop gives up on. It
+ * was the same two words written out in both packages, with no edge between
+ * them, so a third member added on one side would have been invisible to the
+ * other. It lives here because `@smthrs/plan` is the package both already
+ * depend on.
+ *
+ * @since 1.0.0-rc.0
+ */
+
+import * as Schema from "effect/Schema"
+
+/**
+ * What a bounded repetition answers with at its ceiling: `fail` raises the
+ * repetition's own typed failure, and `return-last` settles with the last
+ * value it produced.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export const AtCeiling = Schema.Literals(["fail", "return-last"])
+
+/**
+ * The value form of {@link AtCeiling}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type AtCeiling = typeof AtCeiling.Type

package/src/Scheduling.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared ready-work admission policy. This module decides priority, aging,
+ * deterministic ties, and step/agent capacity. It does not decide which nodes
+ * are ready, evaluate branches, launch effects, or own execution lifetimes.
+ * Those decisions must use the compiled graph and the caller's activation
+ * state before presenting candidates here.
+ *
+ * @since 1.0.0
+ */
+
+import type * as Plan from "./Plan.ts"
+
+/**
+ * Admission limits, independent of graph width and provider capacity.
+ * Omitted limits are unbounded within JavaScript's safe-integer range.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Concurrency {
+  readonly steps?: number | undefined
+  readonly agents?: number | undefined
+}
+
+/**
+ * Currently held permits. Every agent also holds a step permit.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Usage {
+  readonly steps: number
+  readonly agents: number
+}
+
+/**
+ * The part of a plan node admission reads. Declared once here so the three
+ * places that name it, {@link Candidate}, {@link Admission} and
+ * {@link Policy.admit}, cannot drift apart.
+ */
+type Schedulable = Pick<Plan.PlanNode, "id" | "kind" | "priority">
+
+/**
+ * A ready node's scheduling state. `order` is its position in the compiled
+ * plan, not arrival order. `waited` counts capacity-constrained admission
+ * passes, not wall-clock time.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Candidate<N extends Schedulable = Plan.PlanNode> {
+  readonly node: N
+  readonly order: number
+  readonly waited: number
+}
+
+/**
+ * One admission decision. Deferred candidates carry their incremented age;
+ * admitted candidates retain their age for dispatch diagnostics. No input is
+ * mutated and neither array owns or freezes the caller's node values.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Admission<N extends Schedulable = Plan.PlanNode> {
+  readonly admitted: ReadonlyArray<Candidate<N>>
+  readonly deferred: ReadonlyArray<Candidate<N>>
+  readonly agents: number
+}
+
+/**
+ * Pure policy shared by execution coordinators.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Policy {
+  readonly limits: Usage
+  readonly admit: <N extends Schedulable>(
+    ready: ReadonlyArray<Candidate<N>>,
+    active: Usage
+  ) => Admission<N>
+}
+
+const integer = (name: string, value: number, minimum: number): number => {
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    throw new RangeError(`${name} must be a ${minimum === 1 ? "positive" : "non-negative"} safe integer`)
+  }
+  return value
+}
+
+/**
+ * Snapshots validated limits. Admission orders by declared priority plus age,
+ * using exact integer arithmetic even when their sum exceeds MAX_SAFE_INTEGER.
+ * Ties preserve compiled plan order. An agent blocked by its subset cap does
+ * not prevent ordinary ready work from using spare step capacity.
+ *
+ * Invalid candidate/permit state is refused before any decision is returned.
+ * At MAX_SAFE_INTEGER the age saturates; a bounded plan cannot require that
+ * many capacity-constrained passes to drain finite work.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = (concurrency: Concurrency = {}): Policy => {
+  const limits = Object.freeze({
+    steps: integer("concurrency.steps", concurrency.steps ?? Number.MAX_SAFE_INTEGER, 1),
+    agents: integer("concurrency.agents", concurrency.agents ?? Number.MAX_SAFE_INTEGER, 1)
+  })
+  const admit: Policy["admit"] = (ready, active) => {
+    integer("active.steps", active.steps, 0)
+    integer("active.agents", active.agents, 0)
+    if (active.agents > active.steps) throw new RangeError("active.agents cannot exceed active.steps")
+    const ids = new Set<string>()
+    const positions = new Set<number>()
+    const ranked = ready.map((candidate) => {
+      const { node, order, waited } = candidate
+      integer("candidate.order", order, 0)
+      integer("candidate.waited", waited, 0)
+      if (!Number.isSafeInteger(node.priority)) throw new RangeError("candidate.priority must be a safe integer")
+      if (node.kind !== "step" && node.kind !== "agent" && node.kind !== "merge") {
+        throw new RangeError("invalid candidate kind")
+      }
+      if (typeof node.id !== "string" || node.id === "" || ids.has(node.id)) {
+        throw new RangeError("candidate ids must be non-empty and unique")
+      }
+      if (positions.has(order)) throw new RangeError("candidate plan positions must be unique")
+      ids.add(node.id)
+      positions.add(order)
+      return { candidate, priority: BigInt(node.priority) + BigInt(waited) }
+    })
+    ranked.sort((left, right) =>
+      left.priority === right.priority
+        ? left.candidate.order - right.candidate.order
+        : left.priority > right.priority
+        ? -1
+        : 1
+    )
+    const admitted: Array<typeof ready[number]> = []
+    const deferred: Array<typeof ready[number]> = []
+    let agents = 0
+    for (const { candidate } of ranked) {
+      const isAgent = candidate.node.kind === "agent"
+      if (admitted.length >= limits.steps - active.steps || (isAgent && agents >= limits.agents - active.agents)) {
+        deferred.push(Object.freeze({ ...candidate, waited: Math.min(Number.MAX_SAFE_INTEGER, candidate.waited + 1) }))
+      } else {
+        admitted.push(Object.freeze({ ...candidate }))
+        if (isAgent) agents++
+      }
+    }
+    return Object.freeze({ admitted: Object.freeze(admitted), deferred: Object.freeze(deferred), agents })
+  }
+  return Object.freeze({ limits, admit })
+}