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

package/CHANGELOG.md

@@ -0,0 +1,183 @@
+# @smthrs/plan
+
+## Unreleased
+
+### Fixed
+
+- Keep live executable bindings and planned-reference ownership across compatible package copies; serialized ASTs remain inert. ([#1991](https://github.com/smithersai/smithers/issues/1991)).
+
+## [Unreleased]
+
+### Added
+
+- `Scheduling.make` exposes the pure ready-work priority, aging and capacity
+  policy used by the durable plan scheduler. Its exact integer comparison does
+  not round away priority differences after aging. Conditional readiness and
+  effect execution remain the coordinator's responsibilities.
+
+### Fixed
+
+- `StepKey.EnvironmentIdentity` now also supplies the runtime schema. Identity
+  constructors reject malformed/unknown environment fields with typed errors.
+  `StepKey.environmentIdentity` fingerprints a runtime environment for durable
+  recovery binding, using content-key normalization in a separate namespace.
+  Existing valid content and dispatch keys are unchanged.
+
+- Explicit `Ref`/`Pending` read-before-write sequences compile and verify,
+  including transitive paths and appended generations. Conflicting inferred
+  producer/serialize orders still fail with `cycle`.
+
+- `Plan.compile`, `append`, and `verify` accept compensable and irreversible
+  declarations. New `StepKey.planIdentity` separates their approval fingerprints
+  from cache eligibility. Existing sealed keys are unchanged;
+  `fromKeyMaterial` and `dispatchIdentity` remain sealed-only.
+
+## [1.0.0-rc.0] - 2026-08-31
+
+### Added
+
+- The persisted plan: `Plan` (compile, append, conflict annotation),
+  `PlanStore` (append-only SQL, migration block `4000`), `PlanDiff`, and the
+  `KeyMaterial` to `StepKey` compiler revived from the deleted
+  `packages/smithers/flows/keys` modules, now producing `@smthrs/keys` `Key`
+  values rather than a second digest format.
+- Added `Node.priority`, which attaches a scheduling priority to a node, and
+  `Node.declaredPriority`, which reads one back. The value is a plain JSON
+  field on the AST rather than a `Context` annotation, so a stored plan keeps
+  it. `Plan.compile` copies it from `NodeDraft.priority` onto the plan node and
+  folds it into the plan digest a human approves; it never enters a node's key
+  material, so raising a priority reorders work without re-keying a step. A
+  priority that is not a safe integer is a `GraphBuildError` with the new
+  `invalid_priority` code.
+- Added package-owned documentation. `packages/plan/docs` and the public JSDoc
+  in `src` are the single source for the published API page.
+
+### Breaking Changes
+
+- Bumped key material to `flows/key-material/v2` and captured-function
+  identity to `sha256-source-captures/v4`. Existing persisted step keys are
+  intentionally invalidated rather than being reused across changed identity
+  semantics.
+
+- Plan approval digests now include each node's conflict and runtime
+  strategies. This moves plan digests without moving step keys. A running run
+  pinned to the old digest needs a new approval before it can use the changed
+  plan.
+- A node payload is now cloned as its JSON mirror, so a payload carrying a
+  `toJSON`, such as a `Date` or a `URL`, keys as the value it serializes to
+  rather than as an empty object. Payloads of that shape re-key once.
+- A flow call's `KeyMaterial.body` no longer has a body-less shape. `Flow.make`
+  requires `body`, so `@smthrs/flow` never records `declaration.body:
+  undefined` for a call whose declaration survived beside its AST.
+  `StepKey.content` therefore folds a body digest into every such node, and the
+  keys `Plan.compile` derives for the flow calls that previously carried none
+  move with it.
+- The raw migration steps moved beneath `src/internal/migrations`, so
+  `@smthrs/plan/migrations/0001_initial` and its siblings no longer resolve.
+  `Migrations.set` is the supported surface; a step imported on its own ran
+  outside the namespaced ordering `Migrator` relies on.
+- `Node.isNode` no longer accepts the public `TypeId` marker on its own. It
+  recognizes a node this package built by registration at construction, and a
+  rehydrated node, an object sharing the node prototype whose own `ast` is a
+  well-formed AST, by that shape, which is what `@smthrs/flow` hands back for
+  an AST that crossed a serialization boundary. `Node.all`, `andThen`,
+  `branch`, and `catch` therefore refuse a forged object carrying the marker,
+  one inheriting it from a node, and one whose `ast` is missing, malformed, or
+  cyclic with their usual `GraphBuildError` instead of storing an `ast` the
+  package never built.
+- `StepKey.EnvironmentIdentity` is now a discriminated union. A declared
+  environment may not carry a `runScope` and an undeclared one must, which
+  `StepKey.dispatchIdentity` also enforces at run time with the new
+  `invalid_environment` code.
+- A plan may no longer contain an unbounded number of nodes. `Plan.compile` and
+  `Plan.append` refuse a plan above `Plan.maximumPlanNodes` with the new
+  `graph_too_large` code, before any pair comparison runs. The conflict pass
+  compares node pairs and adds a reachability walk per overlapping pair, so an
+  unbounded plan had an unbounded planning cost; a graph larger than the bound
+  now has to be split.
+- `NodeDraft.effects` is now the single derivation point for effect identity.
+  `Plan.compile` and `Plan.append` fold the decoded declaration into the hashed
+  material, replacing any `material.effects` a caller supplied. Every plan
+  re-keys once, and editing `reads`, `writes`, `removes`, or `boundaryMode`
+  now re-keys the node and is attributed by `PlanDiff` as `effects`. Before
+  this, the two channels were independent: a draft could change what a node
+  writes without moving its key, and `PlanDiff` reported it `unchanged`.
+- Compiled material is stored as its deeply frozen JSON mirror. A `Date`, a
+  `URL`, or any value with a data-valued callable `toJSON` is stored as the
+  value it serializes to, which is what its key already covered. A material
+  accessor or a prototype with no JSON representation is now refused with
+  `invalid_node` rather than passed through by reference; the message names the
+  node and the payload path and never the value.
+- A payload whose `toJSON` returns its own receiver now fails with the
+  `cyclic_payload` `GraphBuildError` instead of being silently omitted from the
+  clone. The clone and the input now agree: canonical serialization refused
+  that shape all along, while the clone quietly keyed as `{}`.
+
+### Fixed
+
+- The migration steps under `internal/migrations` are named exports, and
+  `Migrations` imports them by name. The CommonJS build compiled each
+  `export default` step to `exports.default`, and Node's default-import interop
+  then handed the importer the whole exports object instead of the Effect, so
+  `require("@smthrs/plan/Migrations")` produced a set whose entries had no
+  `pipe`.
+- Plan payload capture now refuses accessors and unsupported prototypes with
+  `invalid_payload` instead of executing getters or collapsing `Map`, `Set`,
+  `RegExp`, and class instances onto the same `{}` identity.
+- `StepKey.content` and `dispatchIdentity` now share one environment validator;
+  undeclared environments require a non-empty run scope on both paths.
+
+- `PlanStore.append` now advances the stored plan row with a compare-and-swap
+  on the previous generation, so appending a skipped generation is refused
+  instead of persisting node rows whose dependencies are missing and which the
+  append-only triggers then forbid removing. Node ordinals are derived from the
+  store rather than from the caller's array, `PlanStore.record` refuses
+  anything that is not generation 0, and an append with no new nodes is
+  refused rather than advancing the generation for nothing.
+- A node payload no longer keeps live functions, and different `Date`, `URL`
+  or other `toJSON` payloads no longer share one step key.
+- `StepKey.fromKeyMaterial` resolves dependency digests as own properties, so a
+  dependency named `toString` or `constructor` is a `missing_dependency`
+  refusal rather than a colliding key.
+- A `StepKey.DigestMemo` waiter no longer inherits the leader's interruption;
+  it recomputes its own digest instead.
+- `StepKey.project` resolves only own data properties, so a projection path
+  through `toString`, `constructor` or `__proto__` yields `undefined` as
+  documented and no getter runs during key derivation.
+- The conflict pass now decides orderedness against the live edge set, so a
+  writer pair a dependency path already orders is neither annotated, nor given
+  a redundant edge, nor refused with `overlap_forbidden`.
+- `Plan.compile` now fails with `cycle` when a reader-after-writer edge would
+  close a cycle, because a declared dependency or a `serialize` edge already
+  orders the producer behind its reader. The edge was dropped before, which
+  left the reader ahead of its producer to measure and cache pre-producer
+  bytes as a legitimate execution. The message names the reader, the producer,
+  the overlapping paths, and the dependency chain.
+- `Plan.compile` no longer recurses per dependency edge and no longer
+  materializes a transitive closure, so a large graph compiles in bounded
+  memory instead of raising an untyped `RangeError`.
+- `Plan.compile` and `Plan.append` validate drafts before keying, with the new
+  `invalid_node` code, so an empty plan id, an unsafe-integer priority, or a
+  key material version this release does not know is refused at the plan rather
+  than at the store.
+- `PlanDiff` attributes a key move caused by `nondeterministic` or `placement`,
+  and `Node.capture` refuses a capture nested past its documented limit with a
+  path-bearing error rather than overflowing the stack.
+- `Plan.compile` and `Plan.append` decode `NodeDraft.effects` through
+  `NodeEffects` before keying, so a malformed declaration is a typed
+  `invalid_node` naming the node and the failing path instead of an untyped
+  defect. A filesystem declaration containing C0 controls or DEL, or one that is
+  not workspace-relative, is refused there rather than reaching a host
+  filesystem, and path comparison is Unicode NFC normalized, so two spellings of
+  one name are detected as an overlap. `invalid_effects` is now reserved for the
+  cross-field rule that one path cannot be both a write and a removal.
+- `Planned.reference` validates the reference shape, so a forged carrier can no
+  longer inject a fabricated projection path into a payload.
+- Compiled and appended plans now keep the exact material and filesystem
+  authority that their keys and approval digest cover, even if caller-owned
+  draft objects are later mutated.
+- Persisted plans can no longer be deleted or have their plan id, flow, or
+  creation time rewritten, and node order is now unique and deterministic within
+  each plan. Migration `4003` adds the plan-id pin the forward-only trigger was
+  missing, which a rename could otherwise use to strand a plan's immortal node
+  rows under an id nothing can record again.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Cory and the Smithers Flows contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,229 @@
-# Temporary Holding Version
+# @smthrs/plan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Release candidate scope, host requirements and compatibility review are defined in the [library support policy](https://github.com/smithersai/smithers/blob/main/RELEASE_SUPPORT.md).
+
+This package declares `effect` as an exact
+`4.0.0-rc.115` peer dependency. Keep the application on that version so
+all Smithers packages share one Effect runtime.
+
+**Documentation:** https://plan.smithers.sh
+
+The persisted plan: a keyed action graph, its append-only store, its diff, and
+the step-key compiler that gives every node its identity.
+
+`@smthrs/plan` turns a description of work into one durable value. It compiles
+declared steps into a graph in which every node carries a content key derived
+from what that node declares, records that graph in a SQLite store that only
+ever grows, and compares two graphs to say exactly what changed. It runs
+nothing itself: it performs no I/O beyond the database, and driving a compiled
+plan is a scheduler's job, such as
+[`@smthrs/engine-store`](https://engine-store.smithers.sh)'s `PlanScheduler`.
+
+Reach for it 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
+```
+
+Node.js 26.4.0 or later, and `effect` 4.0.0-rc.115 as a peer. Recording a plan
+is [`@smthrs/plan-store`](https://plan-store.smithers.sh), which owns the SQL
+and brings [`@smthrs/database`](https://database.smithers.sh) with it.
+
+## 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)
+```
+
+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.
+
+Recording that plan is
+[`@smthrs/plan-store`](https://plan-store.smithers.sh), whose
+[quickstart](https://plan-store.smithers.sh/quickstart/) builds the whole
+composition against an in-memory database.
+
+## What is in here
+
+| Module            | Role                                                                                                |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `Node`            | The pure, pipeable authoring AST: `succeed`, `all`, `map`, `andThen`, `branch`, `catch`, `priority` |
+| `Planned`         | The strict placeholder a body sees where a step result will be, and the reference it records        |
+| `GraphBuildError` | The refusals a plan-time build raises instead of producing a wrong plan                             |
+| `FileSet`         | The static filesystem declaration vocabulary: patterns, globs, tree artifacts, filegroups, overlap  |
+| `KeyMaterial`     | What a planner declares about a node: body, tagged input references, layers, capabilities, effects  |
+| `StepKey`         | The compiler that turns material plus resolved dependency digests into a `@smthrs/keys` `Key`       |
+| `Plan`            | `compile`, `append`, the node/edge/conflict schemas, and the digest an approval binds to            |
+| `PlanDiff`        | A comparison of two plans as a value: added, removed, re-keyed with attribution, unchanged          |
+| `Placement`       | Where a node runs: the four directives, their host-selection detail, and the annotation key         |
+
+Every module is its own entry point, so
+`import * as Plan from "@smthrs/plan/Plan"` keeps a bundle to what you reach
+for. The root entry re-exports all of them as namespaces.
+
+## The four rules this package exists to keep
+
+**Planning demands nothing.** A `Node` carries Effect's requirement channel,
+`R`, and carries it as a phantom: no combinator here reads it, and the AST, the
+graph, the key material, and every digest are identical whatever it says.
+Building a plan therefore asks for no service at all. What fills the channel is
+a call to something whose code lives elsewhere, an action, so a plan's type
+states which implementations running it will need, and the place that runs it
+is where the compiler asks for them. Each combinator unions its parts: `all`
+over its members, `map` and `andThen` along the chain, `branch` over BOTH arms
+and `catch` over its failure arm, because both arms of a decision are topology
+the plan carries and a run has to be able to take either.
+
+**Planning performs no I/O.** Nothing here reads a file, a clock, or a network.
+A node's declared `effects` carry read and write _paths_, never digests, since
+measuring them is the scheduler's run-time job.
+
+**Invalidation is re-keying.** A node's key is a function of what it consumes,
+so an edited declaration re-keys that node and its dependent cone and nothing
+else. There is deliberately **no reverse-dependency index and no invalidating
+node visitor**: content addressing subsumes both.
+
+**A plan grows; it is never rewritten.** `append` adds a pre-keyed subgraph at
+the next generation. Recorded nodes keep their id, key, edges, and generation
+byte for byte, and the SQL raises rather than letting a caller update or delete
+one. Re-ordering after a reconciliation happens by re-keying _future_ steps.
+Appending to a plan that was never recorded, or over a skipped generation, is a
+`constraint` refusal, because the alternative is node rows for a plan that does
+not exist and that the append-only triggers then forbid removing.
+
+## Conflict annotations
+
+Declared write sets make overlap detectable at plan time. `compile` annotates
+both members of every overlapping pair that no dependency path already orders:
+`serialize` is the default and gives the later writer an ordering edge that is
+deliberately not key material, so a serialized node keeps its cache hit; `lane`
+gives both writers lane annotations and no edge; `fail` refuses the compile,
+for flows that promise disjointness. Each annotation also carries the runtime
+strategy, `delay-rebase` or `stop-merge`, and both strategies are folded into
+the plan digest a human approves.
+
+A node that reads a path another node writes is not a conflict but a missing
+edge: `compile` puts the reader behind its producer by growing `dependsOn`, and
+fails with `cycle` when no edge set can satisfy both that and the declared
+order.
+
+[Declared effects and conflicts](https://plan.smithers.sh/concepts/effects-and-conflicts/)
+covers both passes in full.
+
+## When it refuses
+
+`Plan.compile` and `Plan.append` fail with a `PlanError` carrying one of seven
+stable codes: `cycle`, `unknown_dependency`, `duplicate_node`,
+`overlap_forbidden`, `invalid_effects`, `invalid_node`, and `graph_too_large`.
+`Plan.verify`, which every store read and write runs, adds an eighth,
+`invalid_plan`: the plan decoded but its generations, approval digest, keys,
+effects, or ordering do not match its content. A plan-time build refuses
+through `GraphBuildError`, whose closed code set names the site and the fix;
+`unstable_callback` in that set is raised by `@smthrs/flow` when a stable build
+meets a callback without a `Node.capture` declaration. Persistence has its own
+refusals, all of them
+[`@smthrs/plan-store`](https://plan-store.smithers.sh)'s.
+
+[Troubleshooting](https://plan.smithers.sh/troubleshooting/) lists every code
+with the change that clears it.
+
+## Paths, payloads, and immutability
+
+Declared paths are workspace-relative and compared in one spelling:
+`FileSet.canonical` rewrites every separator to `/` and normalizes to Unicode
+NFC, and `FileSet.workspaceRelative` refuses absolute paths, drive letters,
+`..` and `.` segments, empty segments, the C0 control range, and DEL.
+
+A node payload is stored as its inert JSON mirror, so a data-valued `toJSON` is
+honoured while an accessor or an unsupported prototype fails with
+`invalid_payload` rather than executing author code or collapsing distinct
+values onto `{}`. That mirror is identity material: it is hashed into the step
+key and persisted verbatim as plaintext in `node_json` and in the approval card,
+and this package never redacts it. Keep credentials out of payloads. A secret
+belongs in a layer, a capability, or the environment, resolved at dispatch. `Node.succeed(input)` returns `Node<Succeed<typeof input>>`:
+the success type describes that projection. Dates become `string | null`, URLs
+become strings, and callable object members disappear. Planned references
+resolve to their result types. Reconstruct domain objects explicitly in
+`Node.map` when needed. A compiled plan is deep-frozen: mutating the draft objects
+you passed in cannot change the plan, its keys, or its digest.
+
+`Plan.maximumPlanNodes` bounds compilation. The conflict and
+reader-after-writer passes compare node pairs, so a plan above that bound is
+refused with `graph_too_large` before any pair is compared.
+
+## Browser support
+
+Browser-safe: the package resolves no `node:` built-in and binds no database,
+so compiling, diffing, and building node graphs all work in a browser.
+Persistence is a separate package, which is where a platform choice enters.
+
+## Links
+
+- [Documentation](https://plan.smithers.sh)
+- [API reference](https://plan.smithers.sh/reference/api/)
+- [`@smthrs/plan-store`](https://plan-store.smithers.sh), the append-only store
+  a compiled plan is recorded in
+- [`@smthrs/flows`](https://flows.smithers.sh), the whole engine as a single
+  dependency, which re-exports this package as its `Plan` namespace
+- [License: MIT](./LICENSE)

package/dist/cjs/CachePolicy.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The caller-declared cache policy: how far a recorded sealed result may
+ * travel, and how long it stays servable.
+ *
+ * This is the ONE cache-policy model. `@smthrs/flow` publishes it as
+ * `CacheEnvironment.CachePolicy` and the engine reads it off a dispatched
+ * action; `@smthrs/patterns` declares it over a flow as `WithCache.Policy`. It
+ * used to be two declarations in those two packages, tied together by nothing
+ * but a re-typed identifier string, so a field added on one side was invisible
+ * to the other. It lives here because `@smthrs/plan` is the package both
+ * already depend on.
+ *
+ * The annotation key still reads `"@smthrs/flow/Action/CachePolicy"`.
+ * `@smthrs/engine-store`'s `ActionPersistence` reads the policy off stored and
+ * dispatched actions by that identifier, so retagging it would make every
+ * policy already written invisible at dispatch. The identifier is a wire
+ * value, not a location.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+/**
+ * How far a recorded sealed result may travel.
+ *
+ * `shared` is the content-addressed default: the key names the inputs and the
+ * environment, so any run on any host that would have produced the same bytes
+ * may reuse the row. `run` and `flow` narrow that on purpose — a step whose
+ * result is only meaningful inside one execution, or inside one flow, folds
+ * that identity into its key so a sibling never reads it.
+ *
+ * The old scope vocabulary was `run | workflow | global`; `flow` and `shared`
+ * are the same three levels named after the current concepts.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const CacheScope: Schema.Literals<readonly ["run", "flow", "shared"]>;
+/**
+ * The value form of {@link CacheScope}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type CacheScope = typeof CacheScope.Type;
+/**
+ * The caller's declaration about the decay and the reach of a sealed result.
+ *
+ * `ttlMs` bounds the age of a row the engine may serve: past it the dispatch
+ * executes again and journals `cache-expired`, so the refusal is durable
+ * evidence a replay reads rather than a fresh clock reading. `scope` decides
+ * what the key names besides the inputs.
+ *
+ * Both fields are optional and both defaults are the pre-policy behavior: no
+ * age bound, and the reach the composition's cache environment already
+ * granted.
+ *
+ * @category schemas
+ * @since 1.0.0-rc.0
+ */
+export declare const CachePolicy: Schema.Struct<{
+    readonly ttlMs: Schema.optionalKey<Schema.Int>;
+    readonly scope: Schema.optionalKey<Schema.Literals<readonly ["run", "flow", "shared"]>>;
+}>;
+/**
+ * The value form of {@link CachePolicy}.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type CachePolicy = typeof CachePolicy.Type;
+/**
+ * Annotation key carrying a declaration's {@link CachePolicy}.
+ *
+ * It is an annotation, not a field on the declaration, for the same reason
+ * placement and effects are: the policy is data that travels with the
+ * declaration and is read by whoever executes it, and adding it changes no
+ * existing call site.
+ *
+ * @category annotations
+ * @since 1.0.0-rc.0
+ */
+export declare const CachePolicyAnnotation: Context.Service<{
+    readonly ttlMs?: number;
+    readonly scope?: "run" | "flow" | "shared";
+}, {
+    readonly ttlMs?: number;
+    readonly scope?: "run" | "flow" | "shared";
+}>;
+/**
+ * Reads the cache policy an annotation bag carries, or `undefined` when it
+ * carries none.
+ *
+ * @category getters
+ * @since 1.0.0-rc.0
+ */
+export declare const cachePolicyOf: (annotations: Context.Context<never>) => CachePolicy | undefined;
+/**
+ * Attaches a cache policy to a declaration that can carry annotations.
+ *
+ * The declaration is not mutated: `annotate` answers a new one carrying the
+ * policy, which is what a plan captures. It is written against the `annotate`
+ * method rather than against an action or a flow type so the one declaration
+ * serves both, which is what `@smthrs/flow` publishes as
+ * `CacheEnvironment.withCache`.
+ *
+ * @example
+ * ```ts
+ * import { CachePolicy } from "@smthrs/plan"
+ * import { Action } from "@smthrs/flow"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ *
+ * const compile = CachePolicy.annotate(
+ *   Action.make({
+ *     name: "build/compile",
+ *     success: Schema.String,
+ *     tier: "sealed",
+ *     execute: Effect.succeed("dist/server.js")
+ *   }),
+ *   { ttlMs: 60_000, scope: "shared" }
+ * )
+ * ```
+ *
+ * @category combinators
+ * @since 1.0.0-rc.0
+ */
+export declare const annotate: <A extends {
+    annotate: (key: typeof CachePolicyAnnotation, value: CachePolicy) => A;
+}>(declaration: A, policy: CachePolicy) => A;
+//# sourceMappingURL=CachePolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CachePolicy.d.ts","sourceRoot":"","sources":["../../src/CachePolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAEzC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,qDAA6C,CAAA;AAEpE;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAU/C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;EAGtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB;;;;;;EAAkE,CAAA;AAEpG;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,aAAa,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,WAAW,GAAG,SACJ,CAAA;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS;IAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,qBAAqB,EAAE,KAAK,EAAE,WAAW,KAAK,CAAC,CAAA;CAAE,EAC3G,aAAa,CAAC,EACd,QAAQ,WAAW,KAClB,CAAwD,CAAA"}

package/dist/cjs/CachePolicy.js

@@ -0,0 +1,50 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var CachePolicy_exports = {};
+__export(CachePolicy_exports, {
+  CachePolicy: () => CachePolicy,
+  CachePolicyAnnotation: () => CachePolicyAnnotation,
+  CacheScope: () => CacheScope,
+  annotate: () => annotate,
+  cachePolicyOf: () => cachePolicyOf
+});
+module.exports = __toCommonJS(CachePolicy_exports);
+var Context = __toESM(require("effect/Context"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const CacheScope = Schema.Literals(["run", "flow", "shared"]);
+const PositiveMillis = Schema.Int.check(Schema.isGreaterThan(0));
+const CachePolicy = Schema.Struct({
+  ttlMs: Schema.optionalKey(PositiveMillis),
+  scope: Schema.optionalKey(CacheScope)
+});
+const CachePolicyAnnotation = Context.Service("@smthrs/flow/Action/CachePolicy");
+const cachePolicyOf = (annotations) => Option.getOrUndefined(Context.getOption(annotations, CachePolicyAnnotation));
+const annotate = (declaration, policy) => declaration.annotate(CachePolicyAnnotation, policy);
+//# sourceMappingURL=CachePolicy.js.map

package/dist/cjs/CachePolicy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/CachePolicy.ts"],
+  "sourcesContent": ["/**\n * The caller-declared cache policy: how far a recorded sealed result may\n * travel, and how long it stays servable.\n *\n * This is the ONE cache-policy model. `@smthrs/flow` publishes it as\n * `CacheEnvironment.CachePolicy` and the engine reads it off a dispatched\n * action; `@smthrs/patterns` declares it over a flow as `WithCache.Policy`. It\n * used to be two declarations in those two packages, tied together by nothing\n * but a re-typed identifier string, so a field added on one side was invisible\n * to the other. It lives here because `@smthrs/plan` is the package both\n * already depend on.\n *\n * The annotation key still reads `\"@smthrs/flow/Action/CachePolicy\"`.\n * `@smthrs/engine-store`'s `ActionPersistence` reads the policy off stored and\n * dispatched actions by that identifier, so retagging it would make every\n * policy already written invisible at dispatch. The identifier is a wire\n * value, not a location.\n *\n * @since 1.0.0-rc.0\n */\n\nimport * as Context from \"effect/Context\"\nimport * as Option from \"effect/Option\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * How far a recorded sealed result may travel.\n *\n * `shared` is the content-addressed default: the key names the inputs and the\n * environment, so any run on any host that would have produced the same bytes\n * may reuse the row. `run` and `flow` narrow that on purpose \u2014 a step whose\n * result is only meaningful inside one execution, or inside one flow, folds\n * that identity into its key so a sibling never reads it.\n *\n * The old scope vocabulary was `run | workflow | global`; `flow` and `shared`\n * are the same three levels named after the current concepts.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport const CacheScope = Schema.Literals([\"run\", \"flow\", \"shared\"])\n\n/**\n * The value form of {@link CacheScope}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type CacheScope = typeof CacheScope.Type\n\n/**\n * A positive whole number of milliseconds.\n *\n * @private\n * @since 1.0.0-rc.0\n */\nconst PositiveMillis = Schema.Int.check(Schema.isGreaterThan(0))\n\n/**\n * The caller's declaration about the decay and the reach of a sealed result.\n *\n * `ttlMs` bounds the age of a row the engine may serve: past it the dispatch\n * executes again and journals `cache-expired`, so the refusal is durable\n * evidence a replay reads rather than a fresh clock reading. `scope` decides\n * what the key names besides the inputs.\n *\n * Both fields are optional and both defaults are the pre-policy behavior: no\n * age bound, and the reach the composition's cache environment already\n * granted.\n *\n * @category schemas\n * @since 1.0.0-rc.0\n */\nexport const CachePolicy = Schema.Struct({\n  ttlMs: Schema.optionalKey(PositiveMillis),\n  scope: Schema.optionalKey(CacheScope)\n})\n\n/**\n * The value form of {@link CachePolicy}.\n *\n * @category models\n * @since 1.0.0-rc.0\n */\nexport type CachePolicy = typeof CachePolicy.Type\n\n/**\n * Annotation key carrying a declaration's {@link CachePolicy}.\n *\n * It is an annotation, not a field on the declaration, for the same reason\n * placement and effects are: the policy is data that travels with the\n * declaration and is read by whoever executes it, and adding it changes no\n * existing call site.\n *\n * @category annotations\n * @since 1.0.0-rc.0\n */\nexport const CachePolicyAnnotation = Context.Service<CachePolicy>(\"@smthrs/flow/Action/CachePolicy\")\n\n/**\n * Reads the cache policy an annotation bag carries, or `undefined` when it\n * carries none.\n *\n * @category getters\n * @since 1.0.0-rc.0\n */\nexport const cachePolicyOf = (annotations: Context.Context<never>): CachePolicy | undefined =>\n  Option.getOrUndefined(Context.getOption(annotations, CachePolicyAnnotation))\n\n/**\n * Attaches a cache policy to a declaration that can carry annotations.\n *\n * The declaration is not mutated: `annotate` answers a new one carrying the\n * policy, which is what a plan captures. It is written against the `annotate`\n * method rather than against an action or a flow type so the one declaration\n * serves both, which is what `@smthrs/flow` publishes as\n * `CacheEnvironment.withCache`.\n *\n * @example\n * ```ts\n * import { CachePolicy } from \"@smthrs/plan\"\n * import { Action } from \"@smthrs/flow\"\n * import * as Effect from \"effect/Effect\"\n * import * as Schema from \"effect/Schema\"\n *\n * const compile = CachePolicy.annotate(\n *   Action.make({\n *     name: \"build/compile\",\n *     success: Schema.String,\n *     tier: \"sealed\",\n *     execute: Effect.succeed(\"dist/server.js\")\n *   }),\n *   { ttlMs: 60_000, scope: \"shared\" }\n * )\n * ```\n *\n * @category combinators\n * @since 1.0.0-rc.0\n */\nexport const annotate = <A extends { annotate: (key: typeof CachePolicyAnnotation, value: CachePolicy) => A }>(\n  declaration: A,\n  policy: CachePolicy\n): A => declaration.annotate(CachePolicyAnnotation, policy)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,cAAyB;AACzB,aAAwB;AACxB,aAAwB;AAiBjB,MAAM,aAAa,OAAO,SAAS,CAAC,OAAO,QAAQ,QAAQ,CAAC;AAgBnE,MAAM,iBAAiB,OAAO,IAAI,MAAM,OAAO,cAAc,CAAC,CAAC;AAiBxD,MAAM,cAAc,OAAO,OAAO;AAAA,EACvC,OAAO,OAAO,YAAY,cAAc;AAAA,EACxC,OAAO,OAAO,YAAY,UAAU;AACtC,CAAC;AAqBM,MAAM,wBAAwB,QAAQ,QAAqB,iCAAiC;AAS5F,MAAM,gBAAgB,CAAC,gBAC5B,OAAO,eAAe,QAAQ,UAAU,aAAa,qBAAqB,CAAC;AAgCtE,MAAM,WAAW,CACtB,aACA,WACM,YAAY,SAAS,uBAAuB,MAAM;",
+  "names": []
+}