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

package/dist/esm/test/PlanFixtures.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Graph fixtures shared by every suite that needs a compiled plan.
+ *
+ * These live outside a `*.test.ts` file on purpose. `PlanStore.test.ts` used to
+ * import `compile` and `draft` from `Plan.test.ts`, and importing a test module
+ * REGISTERS ITS SUITES in the importer: every case in `Plan.test.ts` ran a
+ * second time under `PlanStore.test.ts`, including the 10,000-node chain, which
+ * is the most expensive case in the package. CI reported it as
+ * `PlanStore.test.ts > Plan.compile > compiles a 10,000-node Ref chain` and it
+ * timed out there, on a slower runner, for work `PlanStore` never asked for.
+ *
+ * They ship from `src/test` rather than `test/` because `@smthrs/plan-store`
+ * drives the same fixtures against the persisted form, the way
+ * `@smthrs/database` ships `test/TestDatabase` and `@smthrs/engine-store`
+ * ships `test/TestStores`. One definition, two packages.
+ *
+ * @since 0.1.0
+ */
+import * as KeyMaterial from "../KeyMaterial.ts";
+import * as Plan from "../Plan.ts";
+/**
+ * A hard-boundary effect declaration over plain path lists.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export declare const effects: (reads: ReadonlyArray<string>, writes: ReadonlyArray<string>) => Plan.NodeEffects;
+/**
+ * A sealed node draft whose body defaults to `{ action: id }`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const draft: (id: string, options?: {
+    readonly body?: unknown;
+    readonly inputs?: ReadonlyArray<KeyMaterial.InputRef>;
+    readonly reads?: ReadonlyArray<string>;
+    readonly writes?: ReadonlyArray<string>;
+    readonly removes?: ReadonlyArray<string>;
+} & Omit<Plan.NodeDraft, "id" | "material" | "effects">) => Plan.NodeDraft;
+/**
+ * Compiles drafts into a plan under the `example/Build` flow.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const compile: (nodes: ReadonlyArray<Plan.NodeDraft>, planId?: string) => import("effect/Effect").Effect<{
+    readonly planId: string;
+    readonly flow: string;
+    readonly generation: number;
+    readonly baseDigest: string & import("effect/Brand").Brand<"@smthrs/keys/Key">;
+    readonly digest: string & import("effect/Brand").Brand<"@smthrs/keys/Key">;
+    readonly nodes: readonly {
+        readonly id: string;
+        readonly kind: "step" | "agent" | "merge";
+        readonly key: string & import("effect/Brand").Brand<"@smthrs/keys/Key">;
+        readonly material: {
+            readonly version: "flows/key-material/v2";
+            readonly inputs: readonly ({
+                readonly _tag: "Literal";
+                readonly value: unknown;
+            } | {
+                readonly _tag: "Ref";
+                readonly from: string;
+                readonly path: readonly string[];
+            } | {
+                readonly _tag: "Pending";
+                readonly from: string;
+            })[];
+            readonly layers: readonly string[];
+            readonly capabilities: readonly string[];
+            readonly kind: "sealed" | "compensable" | "irreversible";
+            readonly body: unknown;
+            readonly nondeterministic?: true | undefined;
+            readonly effects?: unknown;
+            readonly placement?: unknown;
+        };
+        readonly effects: {
+            readonly reads: readonly (string | {
+                readonly include: readonly [string, ...string[]];
+                readonly _tag: "Glob";
+                readonly exclude?: readonly string[] | undefined;
+            } | {
+                readonly _tag: "Filegroup";
+                readonly name: string;
+                readonly entries: readonly (string | {
+                    readonly include: readonly [string, ...string[]];
+                    readonly _tag: "Glob";
+                    readonly exclude?: readonly string[] | undefined;
+                })[];
+            })[];
+            readonly writes: readonly (string | {
+                readonly include: readonly [string, ...string[]];
+                readonly _tag: "Glob";
+                readonly exclude?: readonly string[] | undefined;
+            } | {
+                readonly _tag: "TreeArtifact";
+                readonly path: string;
+            } | {
+                readonly _tag: "Filegroup";
+                readonly name: string;
+                readonly entries: readonly (string | {
+                    readonly include: readonly [string, ...string[]];
+                    readonly _tag: "Glob";
+                    readonly exclude?: readonly string[] | undefined;
+                } | {
+                    readonly _tag: "TreeArtifact";
+                    readonly path: string;
+                })[];
+            })[];
+            readonly boundaryMode: "expected" | "hard";
+            readonly removes?: readonly string[] | undefined;
+        };
+        readonly dependsOn: readonly string[];
+        readonly conflicts: readonly {
+            readonly with: string;
+            readonly paths: readonly string[];
+            readonly strategy: "serialize" | "lane" | "fail";
+            readonly runtime: "delay-rebase" | "stop-merge";
+        }[];
+        readonly strategy: "serialize" | "lane" | "fail";
+        readonly runtime: "delay-rebase" | "stop-merge";
+        readonly priority: number;
+        readonly generation: number;
+    }[];
+}, import("effect/Schema").SchemaError | import("../StepKey.ts").KeyMaterialError | Plan.PlanError, import("effect/Crypto").Crypto>;
+//# sourceMappingURL=PlanFixtures.d.ts.map

package/dist/esm/test/PlanFixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlanFixtures.d.ts","sourceRoot":"","sources":["../../../src/test/PlanFixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAElC;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAClB,OAAO,aAAa,CAAC,MAAM,CAAC,EAC5B,QAAQ,aAAa,CAAC,MAAM,CAAC,KAC5B,IAAI,CAAC,WAAwD,CAAA;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,KAAK,GAChB,IAAI,MAAM,EACV,UAAS;IACP,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAA;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CACzC,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,GAAG,UAAU,GAAG,SAAS,CAAM,KAC3D,IAAI,CAAC,SAkBN,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,eAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mIACvB,CAAA"}

package/dist/esm/test/PlanFixtures.js

@@ -0,0 +1,60 @@
+/**
+ * Graph fixtures shared by every suite that needs a compiled plan.
+ *
+ * These live outside a `*.test.ts` file on purpose. `PlanStore.test.ts` used to
+ * import `compile` and `draft` from `Plan.test.ts`, and importing a test module
+ * REGISTERS ITS SUITES in the importer: every case in `Plan.test.ts` ran a
+ * second time under `PlanStore.test.ts`, including the 10,000-node chain, which
+ * is the most expensive case in the package. CI reported it as
+ * `PlanStore.test.ts > Plan.compile > compiles a 10,000-node Ref chain` and it
+ * timed out there, on a slower runner, for work `PlanStore` never asked for.
+ *
+ * They ship from `src/test` rather than `test/` because `@smthrs/plan-store`
+ * drives the same fixtures against the persisted form, the way
+ * `@smthrs/database` ships `test/TestDatabase` and `@smthrs/engine-store`
+ * ships `test/TestStores`. One definition, two packages.
+ *
+ * @since 0.1.0
+ */
+import * as KeyMaterial from "../KeyMaterial.js";
+import * as Plan from "../Plan.js";
+/**
+ * A hard-boundary effect declaration over plain path lists.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export const effects = (reads, writes) => ({ reads, writes, boundaryMode: "hard" });
+/**
+ * A sealed node draft whose body defaults to `{ action: id }`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const draft = (id, options = {}) => ({
+    id,
+    material: {
+        version: KeyMaterial.version,
+        kind: "sealed",
+        body: options.body ?? { action: id },
+        inputs: options.inputs ?? [],
+        layers: [],
+        capabilities: []
+    },
+    effects: {
+        ...effects(options.reads ?? [], options.writes ?? []),
+        ...(options.removes === undefined ? {} : { removes: options.removes })
+    },
+    ...(options.kind === undefined ? {} : { kind: options.kind }),
+    ...(options.priority === undefined ? {} : { priority: options.priority }),
+    ...(options.conflictStrategy === undefined ? {} : { conflictStrategy: options.conflictStrategy }),
+    ...(options.runtimeStrategy === undefined ? {} : { runtimeStrategy: options.runtimeStrategy })
+});
+/**
+ * Compiles drafts into a plan under the `example/Build` flow.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const compile = (nodes, planId = "plan-1") => Plan.compile({ planId, flow: "example/Build", nodes });
+//# sourceMappingURL=PlanFixtures.js.map

package/dist/esm/test/PlanFixtures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlanFixtures.js","sourceRoot":"","sources":["../../../src/test/PlanFixtures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,WAAW,MAAM,mBAAmB,CAAA;AAChD,OAAO,KAAK,IAAI,MAAM,YAAY,CAAA;AAElC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CACrB,KAA4B,EAC5B,MAA6B,EACX,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAA;AAEhE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,EAAU,EACV,UAM0D,EAAE,EAC5C,EAAE,CAAC,CAAC;IACpB,EAAE;IACF,QAAQ,EAAE;QACR,OAAO,EAAE,WAAW,CAAC,OAAO;QAC5B,IAAI,EAAE,QAAQ;QACd,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;QAC5B,MAAM,EAAE,EAAE;QACV,YAAY,EAAE,EAAE;KACjB;IACD,OAAO,EAAE;QACP,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QACrD,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;KACvE;IACD,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;IAC7D,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;IACzE,GAAG,CAAC,OAAO,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE,CAAC;IACjG,GAAG,CAAC,OAAO,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE,CAAC;CAC/F,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAoC,EAAE,MAAM,GAAG,QAAQ,EAAE,EAAE,CACjF,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,CAAC,CAAA","sourcesContent":["/**\n * Graph fixtures shared by every suite that needs a compiled plan.\n *\n * These live outside a `*.test.ts` file on purpose. `PlanStore.test.ts` used to\n * import `compile` and `draft` from `Plan.test.ts`, and importing a test module\n * REGISTERS ITS SUITES in the importer: every case in `Plan.test.ts` ran a\n * second time under `PlanStore.test.ts`, including the 10,000-node chain, which\n * is the most expensive case in the package. CI reported it as\n * `PlanStore.test.ts > Plan.compile > compiles a 10,000-node Ref chain` and it\n * timed out there, on a slower runner, for work `PlanStore` never asked for.\n *\n * They ship from `src/test` rather than `test/` because `@smthrs/plan-store`\n * drives the same fixtures against the persisted form, the way\n * `@smthrs/database` ships `test/TestDatabase` and `@smthrs/engine-store`\n * ships `test/TestStores`. One definition, two packages.\n *\n * @since 0.1.0\n */\n\nimport * as KeyMaterial from \"../KeyMaterial.ts\"\nimport * as Plan from \"../Plan.ts\"\n\n/**\n * A hard-boundary effect declaration over plain path lists.\n *\n * @category models\n * @since 0.1.0\n */\nexport const effects = (\n  reads: ReadonlyArray<string>,\n  writes: ReadonlyArray<string>\n): Plan.NodeEffects => ({ reads, writes, boundaryMode: \"hard\" })\n\n/**\n * A sealed node draft whose body defaults to `{ action: id }`.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const draft = (\n  id: string,\n  options: {\n    readonly body?: unknown\n    readonly inputs?: ReadonlyArray<KeyMaterial.InputRef>\n    readonly reads?: ReadonlyArray<string>\n    readonly writes?: ReadonlyArray<string>\n    readonly removes?: ReadonlyArray<string>\n  } & Omit<Plan.NodeDraft, \"id\" | \"material\" | \"effects\"> = {}\n): Plan.NodeDraft => ({\n  id,\n  material: {\n    version: KeyMaterial.version,\n    kind: \"sealed\",\n    body: options.body ?? { action: id },\n    inputs: options.inputs ?? [],\n    layers: [],\n    capabilities: []\n  },\n  effects: {\n    ...effects(options.reads ?? [], options.writes ?? []),\n    ...(options.removes === undefined ? {} : { removes: options.removes })\n  },\n  ...(options.kind === undefined ? {} : { kind: options.kind }),\n  ...(options.priority === undefined ? {} : { priority: options.priority }),\n  ...(options.conflictStrategy === undefined ? {} : { conflictStrategy: options.conflictStrategy }),\n  ...(options.runtimeStrategy === undefined ? {} : { runtimeStrategy: options.runtimeStrategy })\n})\n\n/**\n * Compiles drafts into a plan under the `example/Build` flow.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const compile = (nodes: ReadonlyArray<Plan.NodeDraft>, planId = \"plan-1\") =>\n  Plan.compile({ planId, flow: \"example/Build\", nodes })\n"]}

package/docs/README.md

@@ -0,0 +1,165 @@
+---
+title: "@smthrs/plan"
+description: "Compile what a run intends to do into one keyed, content-addressed graph, grow it later without rewriting a node, and diff two graphs to say exactly what changed."
+---
+
+`@smthrs/plan` turns a description of work into one durable value. It compiles a
+list of declared steps into a graph in which every node carries a content key
+derived from what that node declares, grows that graph a generation at a time
+without rewriting a node, and compares two graphs to say exactly what changed.
+It runs nothing itself and performs no I/O at all.
+
+## What it solves
+
+A long run that calls models, builds code, and touches files has to answer two
+questions that are awkward to answer after the fact.
+
+The first is which work is the same work as last time. If identity is a name or
+a position in a list, a harmless edit invalidates everything downstream and a
+meaningful edit sometimes invalidates nothing. This package makes identity
+computable: a node's key is a hash of its payload, its declared dependencies,
+its layers, and its capabilities, so an edit re-keys that node and the nodes
+that depend on it, and leaves every other key untouched. Renaming a node changes
+no key at all, because ids are lookup addresses rather than identity.
+
+The second is whether what executed is what somebody approved. A plan carries
+two digests: `digest`, which moves as the plan elaborates, and `baseDigest`,
+which still names the shape a reviewer signed off on. `Plan.append` is the only
+way a plan changes, and it leaves every earlier node byte for byte.
+[`@smthrs/plan-store`](/api/plan-store) keeps that honest in SQL rather than by
+convention, with triggers that refuse a rewritten node.
+
+Reach for this package when you are building a scheduler, a cache, or an
+approval flow over declared work and you need step identity, declared file
+effects, and an auditable history as values you can hold, hash, and store.
+
+## Install
+
+Not on npm yet; see [Installation](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/flow/docs/installation.md#use-the-libraries).
+
+Compiling asks Effect for its `Crypto` service, which a platform package
+supplies:
+
+```bash
+pnpm add @effect/platform-node@4.0.0-rc.115 @effect/platform-node-shared@4.0.0-rc.115
+```
+
+[Installation](./installation.md) covers the import forms, the package
+persistence lives in, and browser support.
+
+## Compile a plan
+
+Two steps, where the second consumes the first's result and reads the file the
+first writes:
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as KeyMaterial from "@smthrs/plan/KeyMaterial"
+import * as Plan from "@smthrs/plan/Plan"
+import * as Effect from "effect/Effect"
+
+/** Everything hashed about one node. `sealed` is work whose result may be reused across runs. */
+const sealed = (body: unknown, inputs: ReadonlyArray<KeyMaterial.InputRef> = []): KeyMaterial.KeyMaterial => ({
+  version: KeyMaterial.version,
+  kind: "sealed",
+  body,
+  inputs,
+  layers: [],
+  capabilities: []
+})
+
+const drafts: ReadonlyArray<Plan.NodeDraft> = [
+  {
+    id: "run-tests",
+    material: sealed({ action: "run-tests" }, [{ _tag: "Ref", from: "read-pr", path: [] }]),
+    effects: { reads: ["pr.json"], writes: ["report.json"], boundaryMode: "hard" }
+  },
+  {
+    id: "read-pr",
+    material: sealed({ action: "read-pr", pr: 4821 }),
+    effects: { reads: [], writes: ["pr.json"], boundaryMode: "hard" }
+  }
+]
+
+const plan = await Effect.runPromise(
+  Plan.compile({ planId: "review-4821", flow: "example/Review", nodes: drafts }).pipe(
+    Effect.provide(NodeCrypto.layer),
+    Effect.orDie
+  )
+)
+
+console.log(plan.digest)
+for (const node of plan.nodes) console.log(node.id, node.key, node.dependsOn)
+```
+
+`layers` and `capabilities` are empty here. They name the composition a node
+runs under and the authority it claims, and both are hashed into the node's
+key. `boundaryMode` is `hard` or `expected`: the plan carries it through to
+whatever measures the boundary at run time and never interprets it itself.
+[Step keys](./concepts/step-keys.md) tables every field.
+
+The digests on your machine match these, because a plan is a pure function of
+its declarations. Compiling reads no file, no clock, and no network:
+
+```text
+key1_61edccc875ff69b798e0c3874d167f65ff0a250b9fe67d27558b854fa2832302
+read-pr key1_6353326ab2a03804d6acfe916debc4f04f09f9deb8f0e93c1ebea3cdd983db18 []
+run-tests key1_e58229e3be2f6abf6f818baf8577fe7045edba6f5e88097b633898478da93985 [ 'read-pr' ]
+```
+
+The drafts went in out of order and came back topologically sorted.
+`run-tests` names `read-pr` once, in its key material, and that single
+declaration became both the hashed dependency and the graph edge, so an edge and
+a key can never disagree about what a node consumes. Change `pr: 4821` to
+another number and both keys move; rename `read-pr` to `fetch-pr` and neither
+does.
+
+## What is in the package
+
+| Module        | Role                                                                            |
+| ------------- | ------------------------------------------------------------------------------- |
+| `Node`        | The pure authoring AST: `succeed`, `all`, `map`, `andThen`, `branch`, `catch`.  |
+| `Planned`     | The placeholder a body sees where a step result will be.                        |
+| `KeyMaterial` | What a planner declares about a node: body, inputs, layers, capabilities.       |
+| `StepKey`     | The compiler that turns material and resolved dependencies into a key.          |
+| `FileSet`     | Patterns, globs, tree artifacts, and filegroups: the vocabulary `effects` uses. |
+| `Plan`        | `compile`, `append`, the node schemas, and the digest an approval binds to.     |
+| `PlanDiff`    | A comparison of two plans as a value, with each re-key attributed to a field.   |
+| `Placement`   | Where a node runs: four directives, their host detail, and the annotation key.  |
+
+The [API reference](./api.md) documents every export.
+
+## Where this sits
+
+`@smthrs/plan` is one package of the Smithers durable flow engine, and it owns
+the plan phase: step identity, graph compilation, and declared file effects.
+Storing a plan is [`@smthrs/plan-store`](/api/plan-store), which is a separate
+package so that compiling does not drag a database in.
+[`@smthrs/flows`](/api/flows) is the whole engine as a single dependency, and it
+re-exports this package as its `Plan` namespace, so `Plan.compile` there is
+`Plan.Plan.compile`. If you are writing an application rather than a scheduler,
+install `@smthrs/flows` and reach for this package's names through it; install
+`@smthrs/plan` on its own when you want the plan value without the engine that
+executes it.
+
+Nothing here executes a node. A compiled plan is inert until a scheduler drives
+it, which is [`@smthrs/engine-store`](/api/engine-store)'s `PlanScheduler`.
+Above this layer, [`@smthrs/flow`](/api/flow) is the authoring API most flow
+authors write against, and it produces the drafts that arrive here. Above all of
+it, [`@smthrs/cli`](/api/cli) is the `smthrs` command line that plans, approves,
+runs, and inspects flows for someone who never imports a package at all.
+
+## Next
+
+- [Quickstart](./quickstart.md): compile a plan, append a generation, and diff
+  the two graphs.
+- [The plan value](./concepts/plan-value.md): generations, the two digests, and
+  why a plan grows instead of being rewritten.
+- [Step keys](./concepts/step-keys.md): what goes into a key, what deliberately
+  stays out, and why invalidation is re-keying.
+- [Declared effects and conflicts](./concepts/effects-and-conflicts.md): how
+  reads and writes become ordering edges.
+- [Persist a plan](https://plan-store.smithers.sh/guides/persist-a-plan/): the
+  store composition and every outcome `record` can answer with.
+- [Troubleshooting](./troubleshooting.md): every refusal this package raises and
+  what to change.