@smthrs/core 0.0.0-stage → 1.0.0-rc.12

package/CHANGELOG.md

@@ -0,0 +1,189 @@
+# Changelog
+
+## [Unreleased]
+
+### Removed
+
+- Removed the object-form `Flow.make(options)` and `Flow.MakeOptions` under
+  [RELEASE_SUPPORT.md (MVP compatibility changes)](../../../../RELEASE_SUPPORT.md#mvp-compatibility-changes).
+  Replace executable declarations with `Flow.make("tag", { payload, success, body })`
+  from `@smthrs/flow`. For host handlers, pass a plain `FlowBinding` record with
+  `name`, `input`, `output`, `capabilities` and `effects`. `Flow.isFlow` and
+  `Flow.TypeId` remain available for retained Markdown metadata signatures.
+
+- Removed `Flow.withCapabilities`, `Flow.sealed` and `Flow.annotateMerge` from
+  core's deprecated object-form flow API. Nothing outside this package called
+  them. Declare capabilities and effects on the flow itself, or use
+  `@smthrs/flow`'s tag-first `Flow.make` with its `annotate` and
+  `annotateMerge` methods.
+
+### Added
+
+- Added `Graph.maximumGraphNodes`, `Graph.maximumGraphEdges`,
+  `Graph.maximumGraphConflicts`, and `Graph.maximumPayloadMembers`, the width
+  bounds `Graph.build` enforces alongside its depth bounds, and the
+  `plan_too_large` and `payload_too_large` diagnostics they throw.
+- Added `Graph.maximumEffectPaths` and `Graph.maximumPlanEffectPaths`, the
+  bounds on the read and write paths one effect declaration may list and on
+  the paths admitted across a plan. `Graph.build` refuses either with
+  `plan_too_large` naming the node before it copies a path and before the
+  write-conflict pass runs.
+- Added `Graph.maximumEffectPathLength` and `Graph.maximumEffectGlobs`, the
+  bounds on the length of one effect path (4096 code units, `PATH_MAX`) and on
+  the patterns one read or write list may carry (128). `Graph.build` refuses
+  either with `plan_too_large` naming the node, or `payload_too_large` for a
+  flow placed inside a plan value, reading only the path's length or last
+  character, so every per-character cost of a build is bounded by the two
+  limits together with `Graph.maximumPlanEffectPaths`.
+- Added `Markdown.validateSkillFrontmatter` and the `Markdown.SkillFrontmatter`
+  shape, so a caller holding already-parsed frontmatter can apply the Agent
+  Skills rules without a document, and the `skill_invalid_name`,
+  `skill_invalid_description`, `skill_invalid_allowed_tools`,
+  `skill_invalid_compatibility`, `skill_invalid_metadata`, and
+  `skill_invalid_license` error codes.
+
+### Fixed
+
+- Fixed `Markdown.parseSkill`, which accepted documents the Agent Skills
+  specification forbids: any non-empty `name`, a `description` of any length,
+  and a sequence-valued `allowed-tools`. It now enforces the specification's
+  name grammar and 64-character limit, the 1024-character description limit
+  counted in code points, a scalar `allowed-tools`, and the optional
+  `license`, `compatibility`, and `metadata` shapes, each with its own stable
+  code. A sequence-valued `allowed-tools` now fails with
+  `skill_invalid_allowed_tools` instead of being lowered.
+- Fixed `Graph.build`, which bounded depth but not width, so a shallow plan of
+  a few thousand siblings, or one plan value holding an enormous array, could
+  exhaust CPU or memory before any documented limit applied. Node, edge,
+  conflict, and reflected-member counts are now refused at fixed limits before
+  allocation, the write-conflict pass indexes literal writers by path instead
+  of comparing every pair, and reachability walks an adjacency index instead
+  of every recorded edge.
+- Fixed `Effects.overlaps` and `Effects.narrow`, which compared every path of
+  one declaration against every path of the other, so two writers naming the
+  same twenty thousand files kept `Graph.build` busy for minutes with no limit
+  reached. Both now index exact paths in a set and find the paths a glob
+  covers by binary search over the sorted declaration, and `Graph.build`
+  bounds the paths it admits. A flow placed inside a plan value now charges
+  its effect paths to the member budget instead of copying them unbounded.
+- Fixed `Effects.overlaps`, `Effects.narrow`, and the write-conflict pass,
+  whose cost inside the limits still grew with the product of two
+  declarations when their patterns nested, because every candidate under a
+  pattern's prefix was compared as a string and rescanned for a dot segment:
+  two writers of 1024 nested patterns took a second to compare and 16 of them
+  minutes to build. Paths are now indexed once per comparison, each scanned
+  once for a dot segment and located by rank, nested patterns collapse into
+  the outermost, and every match is an integer comparison, so the same pair
+  compares in milliseconds and 16 writers of the widest nested declaration
+  the limits admit build in well under a second. An envelope is prepared once
+  for every node it encloses instead of being re-sorted per node, so a wide
+  envelope of long paths narrowed by thousands of nodes builds in under a
+  second instead of several. Reachability in the conflict pass is answered
+  from a transitive closure computed once, and a graph's conflict and
+  diagnostic path lists are frozen in place instead of through allocated
+  property descriptors, so the widest shared-literal conflict set the limits
+  admit builds in about two seconds instead of eight.
+
+## [1.0.0-rc.0] - 2026-08-31
+
+### Added
+
+- Added the Schema-first `Flow` and pipeable `Node` builders, placement and
+  effect annotations, markdown lowering, graph introspection, and digest-free
+  key-material handoff.
+- Added `Node.priority` and the `Annotations.Priority` key, carried onto the
+  graph node and inherited lexically. Priority stays out of key material.
+- Added `Node.catch`, which recovers a node's typed failures with a statically
+  planned arm, and `Node.fail`, which re-raises from one.
+- Added `Node.capture`, which folds the inert values a plan-time function closes
+  over into deterministic, cross-process function identity. Unannotated
+  functions keep process-local identity.
+- Added `Flow.annotate`, which attaches one typed annotation to a flow, and
+  `Flow.withFlows`, which replaces the collaborators a flow declares.
+- Added the `Digest` module: the synchronous, SHA-256-only `Crypto` service,
+  its layer, `runSync`, `digest`, and `canonical`, delegating to
+  `@smthrs/crypto`'s `digestSync` and `syncCrypto` and `@smthrs/canonical`'s
+  `Canonical` after `@smthrs/keys/Digest` was deleted.
+- Added `Graph.maximumGraphDepth` and `Graph.maximumPayloadDepth`, the
+  documented bounds `Graph.build` enforces instead of overflowing the host
+  stack, and `Graph.isFatalDiagnostic`, which reports whether a diagnostic
+  blocks `Graph.keyMaterial`.
+- Added the `capability_outside_grant`, `duplicate_node_id`, `invalid_node`,
+  `plan_too_deep`, and `payload_too_deep` graph diagnostics, and the
+  `unrepresentable_value` node build error.
+- Added `model`, `flows`, and `prompt` to the `Flow` value, so a flow declaring
+  collaborators alongside a body reports them and `Flow.withFlows` can rewrite
+  them.
+- Exported `Flow.MakeOptions` and `Graph.EdgeReason`, so a consumer can name
+  what `Flow.make` and `Flow.agent` accept, and why one node depends on
+  another, without reaching for `Parameters<typeof Flow.make>[0]`.
+- Added `TestRuntime`, a pure evaluator for the deferred callbacks in in-memory
+  Node declarations. It resolves execution leaves explicitly and can inline
+  called flow bodies without pretending to model durable host behavior.
+
+### Fixed
+
+- Replaced the provisional `skill_parser_not_implemented` failure with complete
+  Agent Skills YAML parsing. Callers now receive the stable
+  `skill_missing_frontmatter`, `skill_invalid_frontmatter`,
+  `skill_missing_name`, and `skill_missing_description` error codes.
+- Made the plan-value projection injective. A `Date`, `Map`, `Set`, typed array,
+  `RegExp`, or `Error` used to reflect to `{}`, every function to one constant
+  tag, and two distinct symbols to the same value, so behaviorally different
+  plans shared one content step key. Encoder tags are no longer forgeable from a
+  user literal, own `__proto__` data properties survive, accessors are recorded
+  rather than invoked, and a value the projection cannot represent is refused
+  instead of collapsed.
+- Fixed `Node.capture` of an already-captured function, which discarded the
+  inner source and captures and produced one digest for every nesting.
+- Fixed `Node.all`, which silently dropped a member named `__proto__`, deleting
+  an executable branch with no error.
+- Fixed `Effects.covers` for the universal `**` glob, which matched nothing and
+  therefore turned an "anywhere" envelope into a spurious
+  `effect_outside_envelope` diagnostic on every child step. A path containing a
+  `.` or `..` segment is now never covered, so a declaration can no longer
+  escape its own envelope.
+- Fixed `Node.withEffects` on non-work nodes: the declaration was checked and
+  projected, then dropped from key material, so two nodes with opposite
+  declarations were byte-identical.
+- Fixed `Flow.make`, which discarded `model`, `flows`, and `prompt` whenever
+  `body` was present, making every `flows:` declaration in `@smthrs/patterns`
+  dead configuration and `Flow.withFlows` a no-op on body flows.
+- Fixed `Flow.make` capability normalization, which disagreed with
+  `Flow.withCapabilities`, and the unnamed-flow `name` property, which was an
+  own enumerable `undefined`.
+- Fixed `Graph.keyMaterial`, which compiled step keys for a graph the builder
+  had already recorded as invalid. Fatal diagnostics now block key material and
+  are returned unchanged.
+- Fixed `Node.all` member ordering, which leaked a record literal's insertion
+  order into content step keys, and `schemaIdentity`, which collapsed branded
+  and annotated schemas onto one empty JSON Schema document.
+- Fixed silent capability attenuation: a capability a callee declares and its
+  caller does not grant now records a `capability_outside_grant` diagnostic, and
+  a flow called from a bare-node root keeps the capabilities it declares.
+- Fixed envelope-narrowing diagnostics, which omitted the `nodeId` their own
+  schema provides.
+- Fixed `Markdown.parseSkill`, whose `extra` record could have its prototype
+  replaced by a `__proto__` frontmatter key, and whose invalid-frontmatter
+  message echoed the offending source line into a public error.
+- Fixed `Markdown.lowerMarkdown`, which fabricated an empty hermetic envelope
+  for a markdown flow that declared none, so the lowered flow stopped
+  inheriting its caller's envelope.
+- Replaced raw host `TypeError`s with package-shaped failures for a
+  non-function passed to `Node.capture` and a malformed AST passed to
+  `Graph.build`, and replaced the host stack overflow on a deep plan with coded
+  `plan_too_deep` and `payload_too_deep` diagnostics.
+- Detected colliding structural node ids, which previously dropped a node's key
+  material without a word, as a `duplicate_node_id` diagnostic.
+
+### Changed
+
+- Bumped graph key material to `flows/key-material/v2` and captured-function
+  identity to `sha256-source-captures/v4`, so the hardened reflection and
+  capture encodings can never alias keys produced by their predecessors.
+- Graph identity now has explicit encodings for `Option`, `Result`, `Chunk`,
+  and `URL` values while continuing to reject unsupported class instances.
+
+- A built graph is now deeply frozen, so `Graph.nodes`, `Graph.edges`,
+  `Graph.conflicts`, and `Graph.diagnostics` can no longer be used to edit the
+  plan being observed.

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,110 @@
-# Temporary Holding Version
+# @smthrs/core
 
-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 a `^4.0.4` peer dependency. Install one
+`effect` release in that range so all Smithers packages share one Effect
+runtime.
+
+**Documentation:** https://github.com/smithersai/smithers/tree/main/packages/smithers/flows/core/docs
+
+Metadata and compatibility adapters over `@smthrs/flow`. Author flows with its canonical `Flow.make(tag, { payload, success, body })`. Beside that it publishes the metadata projections the registry and execution layers read: annotations, effects, placement, key material, digests, and Markdown lowering. The node model is `@smthrs/plan`'s and the graph builder is `@smthrs/flow`'s; `Node` and `Graph` here are the names this package's consumers reach them through.
+
+JavaScript and TypeScript declarations and all planning callbacks must be trusted. `Graph.build` executes flow bodies, `Node.andThen` builders, `Node.catch` recovery callbacks, and an optional `resolveLayers` callback in the caller process with ambient process authority. Purity is a caller obligation, not an enforced boundary. Placement, capability, and effect metadata does not sandbox planning, including sandbox placement, empty capability grants, and sealed effects.
+
+For agent-generated declarations, use a constrained data-only ingestion boundary that trusted code validates and translates into nodes, or load and plan untrusted code in an externally isolated environment with restricted permissions and resources. See [Plan time](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/core/docs/concepts/plan-time.md#planning-requires-trusted-declarations).
+
+```bash
+npm install @smthrs/core@next effect
+```
+
+The full API reference lives at [docs/api.md](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/core/docs/api.md).
+
+## Public API
+
+The root entry point exports these namespaces; each is also importable from `@smthrs/core/<Module>`.
+
+| Module        | Public exports                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Description                                                                        |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `Annotations` | `empty`, `add`, `merge`, `getOption`, `Placement`, `Effects`, `Priority`                                                                                                                                                                                                                                                                                                                                                                                              | Builds and reads typed lexical annotations carried by flows and plan nodes.        |
+| `Digest`      | `provideSync`, `digest`, `canonical`                                                                                                                                                                                                                                                                                                                                                                                                                                  | Synchronous SHA-256 and canonical JSON for pure identity constructors.             |
+| `Effects`     | `Declaration`, `NarrowResult`, `make`, `covers`, `narrow`, `overlaps`, `sealed`                                                                                                                                                                                                                                                                                                                                                                                       | Normalizes effect declarations and checks path coverage, narrowing, and conflicts. |
+| `Flow`        | `TypeId`, `Flow`, `Any`, `Payload`, `Reference`, `Seat`, `Input`, `Output`, `Error`, `isFlow`, `within`, `annotate`, `withFlows`                                                                                                                                                                                                                                                                                                                                      | Retains Markdown signatures and their metadata combinators.                        |
+| `Graph`       | `build`, `inspect`, `nodes`, `edges`, `drafts`, `diagnostics`, `evaluatedFrom`, `maximumGraphDepth`, `Graph`, `GraphNode`, `Edge`, `EdgeReason`, `LayerRequest`, `BuildOptions`, `Inspection`                                                                                                                                                                                                                                                                         | `@smthrs/flow`'s plan-time graph builder, re-exported.                             |
+| `KeyMaterial` | `InputRef`, `KeyMaterial`, `Entry`                                                                                                                                                                                                                                                                                                                                                                                                                                    | Defines the stable key projection emitted from a built graph. Types only.          |
+| `Markdown`    | `splitFrontmatter`, `MarkdownFrontmatter`, `SkillFrontmatter`, `SkillDocument`, `MarkdownErrorCode`, `MarkdownError`, `lowerMarkdown`, `isSkillName`, `validateSkillFrontmatter`, `parseSkill`, `lowerSkill`                                                                                                                                                                                                                                                          | Parses and lowers Markdown and Agent Skills declarations to signatures.            |
+| `Node`        | `TypeId`, `Ast`, `Node`, `Any`, `Success`, `Error`, `CallMode`, `isNode`, `succeed`, `fail`, `all`, `race`, `any`, `quorum`, `map`, `andThen`, `branch`, `catch`, `capture`, `priority`, `declaredPriority`, `bindPlanned`, `plannedReference`, `branchSubject`, `catchSubject`, `catchFilter`, `continuation`, `mapper`, `predicate`, `declaration`, `flowCall`, `actionCall`, `functionIdentity`, `schemaIdentity`, `representationIdentity`, `SchemaIdentityError` | `@smthrs/plan`'s inert, pipeable plan AST, re-exported.                            |
+| `Placement`   | `Options`, `Placement`, `local`, `client`, `sandbox`, `remote`                                                                                                                                                                                                                                                                                                                                                                                                        | Creates serializable host-placement declarations.                                  |
+
+```ts
+import { Graph, Node, Placement } from "@smthrs/core"
+import { Flow } from "@smthrs/flow"
+import { Schema } from "effect"
+
+const greeting = Flow.make("greeting", {
+  payload: Schema.Struct({ name: Schema.String }),
+  success: Schema.String,
+  body: ({ name }) => Node.succeed(`Hello, ${name}`)
+}).annotate(Flow.Placement, Placement.sandbox())
+
+const graph = Graph.build(greeting, { name: "world" })
+```
+
+`@smthrs/core/package.json` is also exported. `internal/*` and nested `*/index` subpaths are not public.
+
+## Canonical flows and actions
+
+A flow has a required tag, a struct payload schema, a success schema, and a body returning a node. Work a host implements is an explicit action:
+
+```ts
+import { Action } from "@smthrs/flow"
+import { Effect, Schema } from "effect"
+
+const read = Action.make("std/read", {
+  payload: Schema.Struct({ path: Schema.String }),
+  success: Schema.String,
+  capabilities: ["fs"],
+  tier: "irreversible"
+})
+
+const layer = read.toLayer(({ path }) => Effect.succeed(path))
+```
+
+Struct schemas, including `Schema.Class`, can be the canonical payload schema. Calls accept their constructor input.
+
+## Identity and caching
+
+`@smthrs/plan` compiles a built graph's digest-free key material into step keys, so two declarations with equal key material are the same step.
+
+An unannotated mapper, continuation, or flow body receives a process-local `sha256-source-ephemeral/v4` identity, because JavaScript cannot inspect closure state: two processes give the same function two different digests. Only `Node.capture` produces the cross-process-stable `sha256-source-captures/v5` identity, by folding the canonicalized inert values a function closes over into its digest. A step whose result must survive a restart has to declare its captures.
+
+```ts
+const scaled = Node.capture({ factor: 3 }, (value: number) => value * 3)
+```
+
+An authored captured body retains its identity through core lowering and
+decorators, including the adapter for a non-struct input. An uncaptured body
+remains process-local. Generated action-only wrappers also remain process-local:
+use `Interpreter.layer`, or explicitly select `callbackIdentity: "process-local"`
+when registering them. A stable composition uses authored captured bodies or
+native declarations with explicit capture contracts.
+
+Capture data must be finite, inert, plain data. Accessors, cycles, non-finite numbers, symbols, functions, and non-plain prototypes are rejected rather than hashed incompletely, and accepted capture data is copied and deeply frozen. A function expression reads the copy through its `this` receiver; the returned function keeps its ordinary arguments. Caller objects remain unchanged. Built-in brands and Proxies are refused, and object capture requires `structuredClone`. Captures are compared by structural value: two references to one shared object digest identically to two structurally equal copies, so aliasing is not identity.
+
+## Failure behavior
+
+Construction failures throw; declaration failures are recorded.
+
+| Surface                                                                           | Failure                                                                                                                                                                                                                                                                                                                           |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Node.capture` on a non-function operation or non-inert capture data              | throws `TypeError`; a capture-data failure names the offending path in its `Node.capture:`-prefixed message                                                                                                                                                                                                                       |
+| `Markdown.parseSkill`, `Markdown.lowerSkill`, `Markdown.validateSkillFrontmatter` | returns `Result.fail(MarkdownError)` with code `skill_missing_frontmatter`, `skill_invalid_frontmatter`, `skill_missing_name`, `skill_invalid_name`, `skill_missing_description`, `skill_invalid_description`, `skill_invalid_allowed_tools`, `skill_invalid_compatibility`, `skill_invalid_metadata`, or `skill_invalid_license` |
+| `Graph.build` on an invalid declaration                                           | records a `GraphBuildError` in `Graph.diagnostics`; `@smthrs/flow` documents the codes and which of them are fatal                                                                                                                                                                                                                |
+
+`Markdown.parseSkill` enforces the intrinsic rules of the Agent Skills specification: a `name` of 1 to 64 lowercase ASCII letters, digits, or single hyphens that does not start or end with a hyphen, a `description` of 1 to 1024 characters counted in code points, a scalar `allowed-tools`, a scalar `license`, a `compatibility` of 1 to 500 characters, and `metadata` mapping string keys to scalar values. `Markdown.validateSkillFrontmatter` applies the same rules to already-parsed frontmatter. The rule that `name` equals the skill directory name needs the file system and stays with `@smthrs/registry`.
+
+## Mutability
+
+A compatibility signature is immutable: every combinator returns a fresh one built from the same declaration, and the original keeps the capabilities, annotations, and collaborators it was made with. A collaborator array handed to `Flow.withFlows` is copied, so mutating it afterwards changes nothing.
+
+Plan values are not copied. `Node.succeed`, `Node.fail`, and a call retain the caller's value by reference and read it when the graph is built, so mutating one between construction and `Graph.build` changes the recorded identity.

package/dist/cjs/Annotations.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Typed immutable annotations attached to flow graph values.
+ *
+ * Governing contract: `packages/smithers/flows/core/docs/api.md`, published as
+ * https://smithers.sh/docs/reference/api/core.
+ *
+ * @since 0.0.0
+ */
+import * as PlanEffects from "@smthrs/plan/Effects";
+import { Context, type Option } from "effect";
+/**
+ * The empty annotation bag.
+ *
+ * @category constructors
+ * @since 0.0.0
+ * @slop
+ */
+export declare const empty: Context.Context<never>;
+/**
+ * Adds or replaces one annotation without changing the original context.
+ *
+ * @category adders
+ * @since 0.0.0
+ * @slop
+ */
+export declare const add: {
+    <I, S>(key: Context.Key<I, S>, service: import("effect/Types").NoInfer<S>): <Services>(self: Context.Context<Services>) => Context.Context<Services | I>;
+    <Services, I, S>(self: Context.Context<Services>, key: Context.Key<I, S>, service: import("effect/Types").NoInfer<S>): Context.Context<Services | I>;
+};
+/**
+ * Merges parent and child annotation bags. Child values override parent values
+ * for matching keys.
+ *
+ * @category combining
+ * @since 0.0.0
+ * @slop
+ */
+export declare const merge: (parent: Context.Context<never>, child: Context.Context<never>) => Context.Context<never>;
+/**
+ * Safely retrieves an annotation. An absent service key returns `Option.none()`;
+ * a `Context.Reference` key supplies its declared default.
+ *
+ * @category getters
+ * @since 0.0.0
+ * @slop
+ */
+export declare const getOption: <I, S>(context: Context.Context<never>, key: Context.Key<I, S>) => Option.Option<S>;
+/**
+ * Annotation key for a node's placement directive.
+ *
+ * This is `@smthrs/plan`'s `Placement.Annotation`, the ONE key, which
+ * `@smthrs/flow` also publishes as `Flow.Placement`. While the two packages
+ * each declared a key with its own value type, crossing between them cost a
+ * cast in `@smthrs/registry`.
+ *
+ * @category annotations
+ * @since 0.0.0
+ * @slop
+ */
+export declare const Placement: Context.Service<{
+    readonly _tag: "flows/core/Placement/Local";
+} | {
+    readonly _tag: "flows/core/Placement/Client";
+} | {
+    readonly _tag: "flows/core/Placement/Sandbox";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+} | {
+    readonly _tag: "flows/core/Placement/Remote";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+}, {
+    readonly _tag: "flows/core/Placement/Local";
+} | {
+    readonly _tag: "flows/core/Placement/Client";
+} | {
+    readonly _tag: "flows/core/Placement/Sandbox";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+} | {
+    readonly _tag: "flows/core/Placement/Remote";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+}>;
+/**
+ * Annotation key for a flow or node effect declaration.
+ *
+ * This is `@smthrs/plan`'s `Effects.Envelope`, the ONE key, which
+ * `@smthrs/flow` also publishes as `Flow.EffectEnvelope`. While the two
+ * packages each declared their own key a flow annotated for one graph builder
+ * was invisible to the other.
+ *
+ * @category annotations
+ * @since 0.0.0
+ * @slop
+ */
+export declare const Effects: Context.Service<PlanEffects.Declaration, PlanEffects.Declaration>;
+/**
+ * Annotation key for a node's scheduling priority.
+ *
+ * The value is a signed integer that orders ready work: a scheduler runs a
+ * higher number before a lower one. Priority is a scheduling hint, never part
+ * of step identity, so raising it never invalidates a cached step.
+ *
+ * @category annotations
+ * @since 0.1.0
+ * @slop
+ */
+export declare const Priority: Context.Service<number, number>;
+//# sourceMappingURL=Annotations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Annotations.d.ts","sourceRoot":"","sources":["../../src/Annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,WAAW,MAAM,sBAAsB,CAAA;AAEnD,OAAO,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAmB,CAAA;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,GAAG;;;CAAc,CAAA;AAE9B;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,GAAI,QAAQ,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAC7E,CAAA;AAE9B;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,CAAC,EAAE,CAAC,EAAE,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CACxE,CAAA;AAEjC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA2B,CAAA;AAEjD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,mEAAuB,CAAA;AAE3C;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,iCAA6D,CAAA"}

package/dist/cjs/Annotations.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 Annotations_exports = {};
+__export(Annotations_exports, {
+  Effects: () => Effects,
+  Placement: () => Placement,
+  Priority: () => Priority,
+  add: () => add,
+  empty: () => empty,
+  getOption: () => getOption,
+  merge: () => merge
+});
+module.exports = __toCommonJS(Annotations_exports);
+var PlanEffects = __toESM(require("@smthrs/plan/Effects"), 1);
+var PlanPlacement = __toESM(require("@smthrs/plan/Placement"), 1);
+var import_effect = require("effect");
+const empty = import_effect.Context.empty();
+const add = import_effect.Context.add;
+const merge = (parent, child) => import_effect.Context.merge(parent, child);
+const getOption = (context, key) => import_effect.Context.getOption(context, key);
+const Placement = PlanPlacement.Annotation;
+const Effects = PlanEffects.Envelope;
+const Priority = import_effect.Context.Service("flows/core/Annotations/Priority");
+//# sourceMappingURL=Annotations.js.map

package/dist/cjs/Annotations.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Annotations.ts"],
+  "sourcesContent": ["/**\n * Typed immutable annotations attached to flow graph values.\n *\n * Governing contract: `packages/smithers/flows/core/docs/api.md`, published as\n * https://smithers.sh/docs/reference/api/core.\n *\n * @since 0.0.0\n */\n\nimport * as PlanEffects from \"@smthrs/plan/Effects\"\nimport * as PlanPlacement from \"@smthrs/plan/Placement\"\nimport { Context, type Option } from \"effect\"\n\n/**\n * The empty annotation bag.\n *\n * @category constructors\n * @since 0.0.0\n * @slop\n */\nexport const empty: Context.Context<never> = Context.empty()\n\n/**\n * Adds or replaces one annotation without changing the original context.\n *\n * @category adders\n * @since 0.0.0\n * @slop\n */\nexport const add = Context.add\n\n/**\n * Merges parent and child annotation bags. Child values override parent values\n * for matching keys.\n *\n * @category combining\n * @since 0.0.0\n * @slop\n */\nexport const merge = (parent: Context.Context<never>, child: Context.Context<never>): Context.Context<never> =>\n  Context.merge(parent, child)\n\n/**\n * Safely retrieves an annotation. An absent service key returns `Option.none()`;\n * a `Context.Reference` key supplies its declared default.\n *\n * @category getters\n * @since 0.0.0\n * @slop\n */\nexport const getOption = <I, S>(context: Context.Context<never>, key: Context.Key<I, S>): Option.Option<S> =>\n  Context.getOption(context, key)\n\n/**\n * Annotation key for a node's placement directive.\n *\n * This is `@smthrs/plan`'s `Placement.Annotation`, the ONE key, which\n * `@smthrs/flow` also publishes as `Flow.Placement`. While the two packages\n * each declared a key with its own value type, crossing between them cost a\n * cast in `@smthrs/registry`.\n *\n * @category annotations\n * @since 0.0.0\n * @slop\n */\nexport const Placement = PlanPlacement.Annotation\n\n/**\n * Annotation key for a flow or node effect declaration.\n *\n * This is `@smthrs/plan`'s `Effects.Envelope`, the ONE key, which\n * `@smthrs/flow` also publishes as `Flow.EffectEnvelope`. While the two\n * packages each declared their own key a flow annotated for one graph builder\n * was invisible to the other.\n *\n * @category annotations\n * @since 0.0.0\n * @slop\n */\nexport const Effects = PlanEffects.Envelope\n\n/**\n * Annotation key for a node's scheduling priority.\n *\n * The value is a signed integer that orders ready work: a scheduler runs a\n * higher number before a lower one. Priority is a scheduling hint, never part\n * of step identity, so raising it never invalidates a cached step.\n *\n * @category annotations\n * @since 0.1.0\n * @slop\n */\nexport const Priority = Context.Service<number>(\"flows/core/Annotations/Priority\")\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASA,kBAA6B;AAC7B,oBAA+B;AAC/B,oBAAqC;AAS9B,MAAM,QAAgC,sBAAQ,MAAM;AASpD,MAAM,MAAM,sBAAQ;AAUpB,MAAM,QAAQ,CAAC,QAAgC,UACpD,sBAAQ,MAAM,QAAQ,KAAK;AAUtB,MAAM,YAAY,CAAO,SAAiC,QAC/D,sBAAQ,UAAU,SAAS,GAAG;AAczB,MAAM,YAAY,cAAc;AAchC,MAAM,UAAU,YAAY;AAa5B,MAAM,WAAW,sBAAQ,QAAgB,iCAAiC;",
+  "names": []
+}

package/dist/cjs/Digest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Synchronous identity construction.
+ *
+ * The agent side computes content fingerprints inside *pure, synchronous*
+ * constructors: a prompt section's identity, a context-window segment, a
+ * cell's source digest, a plan card's digest. `@smthrs/crypto` now owns that
+ * policy and its only handwritten implementation. This module delegates to
+ * `digestSync`.
+ *
+ * The digest is therefore the *same digest*: same canonical bytes, same hash,
+ * same hexadecimal encoding, just reached without suspending. `Digest.test.ts`
+ * pins that equivalence against the platform Crypto layer.
+ *
+ * @since 0.1.0
+ */
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+/**
+ * Provides the synchronous SHA-256 service to an Effect-shaped derivation.
+ *
+ * @category hashing
+ * @since 1.0.0
+ */
+export declare const provideSync: <A, E>(effect: Effect.Effect<A, E, Crypto.Crypto>) => Effect.Effect<A, E>;
+/**
+ * Returns the full lowercase SHA-256 digest of UTF-8 string or byte input.
+ *
+ * @category hashing
+ * @since 0.1.0
+ * @slop
+ */
+export declare const digest: (input: string | Uint8Array) => import("@smthrs/crypto").Digest;
+/**
+ * Returns the RFC 8785 canonical JSON serialization of a value.
+ *
+ * A function, symbol, `bigint`, cyclic object, non-finite number, or top-level
+ * `undefined` has no canonical JSON representation. For those values this
+ * throws the `SchemaError` from `effect/Schema` raised through
+ * `Effect.runSync`; the canonical package's failure is not wrapped.
+ *
+ * @category serialization
+ * @since 0.1.0
+ * @slop
+ */
+export declare const canonical: (value: unknown) => string;
+//# sourceMappingURL=Digest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Digest.d.ts","sourceRoot":"","sources":["../../src/Digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CACvC,CAAA;AAM1D;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,iEAAa,CAAA;AAEhC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MAAyC,CAAA"}

package/dist/cjs/Digest.js

@@ -0,0 +1,46 @@
+"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 Digest_exports = {};
+__export(Digest_exports, {
+  canonical: () => canonical,
+  digest: () => digest,
+  provideSync: () => provideSync
+});
+module.exports = __toCommonJS(Digest_exports);
+var import_canonical = require("@smthrs/canonical");
+var import_crypto = require("@smthrs/crypto");
+var Crypto = __toESM(require("effect/Crypto"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+const provideSync = (effect) => Effect.provideService(effect, Crypto.Crypto, import_crypto.syncCrypto);
+const runSync = (effect) => Effect.runSync(provideSync(effect));
+const decodeCanonical = Schema.decodeUnknownEffect(import_canonical.Canonical);
+const digest = import_crypto.digestSync;
+const canonical = (value) => runSync(decodeCanonical(value));
+//# sourceMappingURL=Digest.js.map

package/dist/cjs/Digest.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Digest.ts"],
+  "sourcesContent": ["/**\n * Synchronous identity construction.\n *\n * The agent side computes content fingerprints inside *pure, synchronous*\n * constructors: a prompt section's identity, a context-window segment, a\n * cell's source digest, a plan card's digest. `@smthrs/crypto` now owns that\n * policy and its only handwritten implementation. This module delegates to\n * `digestSync`.\n *\n * The digest is therefore the *same digest*: same canonical bytes, same hash,\n * same hexadecimal encoding, just reached without suspending. `Digest.test.ts`\n * pins that equivalence against the platform Crypto layer.\n *\n * @since 0.1.0\n */\n\nimport { Canonical } from \"@smthrs/canonical\"\nimport { digestSync, syncCrypto } from \"@smthrs/crypto\"\nimport * as Crypto from \"effect/Crypto\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Provides the synchronous SHA-256 service to an Effect-shaped derivation.\n *\n * @category hashing\n * @since 1.0.0\n */\nexport const provideSync = <A, E>(effect: Effect.Effect<A, E, Crypto.Crypto>): Effect.Effect<A, E> =>\n  Effect.provideService(effect, Crypto.Crypto, syncCrypto)\n\nconst runSync = <A, E>(effect: Effect.Effect<A, E, Crypto.Crypto>): A => Effect.runSync(provideSync(effect))\n\nconst decodeCanonical = Schema.decodeUnknownEffect(Canonical)\n\n/**\n * Returns the full lowercase SHA-256 digest of UTF-8 string or byte input.\n *\n * @category hashing\n * @since 0.1.0\n * @slop\n */\nexport const digest = digestSync\n\n/**\n * Returns the RFC 8785 canonical JSON serialization of a value.\n *\n * A function, symbol, `bigint`, cyclic object, non-finite number, or top-level\n * `undefined` has no canonical JSON representation. For those values this\n * throws the `SchemaError` from `effect/Schema` raised through\n * `Effect.runSync`; the canonical package's failure is not wrapped.\n *\n * @category serialization\n * @since 0.1.0\n * @slop\n */\nexport const canonical = (value: unknown): string => runSync(decodeCanonical(value))\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,uBAA0B;AAC1B,oBAAuC;AACvC,aAAwB;AACxB,aAAwB;AACxB,aAAwB;AAQjB,MAAM,cAAc,CAAO,WAChC,OAAO,eAAe,QAAQ,OAAO,QAAQ,wBAAU;AAEzD,MAAM,UAAU,CAAO,WAAkD,OAAO,QAAQ,YAAY,MAAM,CAAC;AAE3G,MAAM,kBAAkB,OAAO,oBAAoB,0BAAS;AASrD,MAAM,SAAS;AAcf,MAAM,YAAY,CAAC,UAA2B,QAAQ,gBAAgB,KAAK,CAAC;",
+  "names": []
+}