@smthrs/flow 1.0.0-rc.12 → 1.0.0-rc.14

package/dist/esm/internal/RecordedPlan.js

@@ -0,0 +1,45 @@
+/**
+ * Resume compatibility is weaker than result reuse: unchanged callback source
+ * may rebuild a recorded plan, but an opaque closure still cannot earn a cache
+ * hit. Only the interpreter's PlanRecorded guard uses this projection. Approval
+ * digests and dispatch keys keep the original entropy-bearing material.
+ *
+ * @since 1.0.0
+ * @internal
+ */
+import { isRecord } from "@smthrs/canonical/Record";
+import * as Graph from "../Graph.js";
+/** Missing source metadata retains the old identity and fails closed. */
+const callback = (value) => isRecord(value) && value._tag === "FunctionIdentity" && value.algorithm === "sha256-source-ephemeral/v4" &&
+    typeof value.sourceDigest === "string"
+    ? { _tag: value._tag, algorithm: value.algorithm, digest: value.sourceDigest }
+    : value;
+/** Project only callback slots, never identity-shaped application data. */
+const body = (value) => {
+    if (!isRecord(value))
+        return value;
+    switch (value._tag) {
+        case "FlowCall":
+            return isRecord(value.declaration)
+                ? { ...value, declaration: { ...value.declaration, body: callback(value.declaration.body) } }
+                : value;
+        case "Map":
+            return { ...value, mapper: callback(value.mapper) };
+        case "AndThen":
+            return { ...value, continuation: callback(value.continuation) };
+        case "Branch":
+            return { ...value, predicate: callback(value.predicate) };
+        case "Catch":
+            return { ...value, filterIdentity: callback(value.filterIdentity) };
+        default:
+            return value;
+    }
+};
+/**
+ * The same drafts, with only callback identities made restart-comparable.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const recordedPlanDrafts = (graph) => Graph.drafts(graph).map((draft) => ({ ...draft, material: { ...draft.material, body: body(draft.material.body) } }));
+//# sourceMappingURL=RecordedPlan.js.map

package/dist/esm/internal/RecordedPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordedPlan.js","sourceRoot":"","sources":["../../../src/internal/RecordedPlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AAEnD,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AAEpC,yEAAyE;AACzE,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAW,EAAE,CAC3C,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,KAAK,kBAAkB,IAAI,KAAK,CAAC,SAAS,KAAK,4BAA4B;IACtG,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ;IACtC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,YAAY,EAAE;IAC9E,CAAC,CAAC,KAAK,CAAA;AAEX,2EAA2E;AAC3E,MAAM,IAAI,GAAG,CAAC,KAAc,EAAW,EAAE;IACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IAClC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,UAAU;YACb,OAAO,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC;gBAChC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,EAAE,GAAG,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,EAAE;gBAC7F,CAAC,CAAC,KAAK,CAAA;QACX,KAAK,KAAK;YACR,OAAO,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAA;QACrD,KAAK,SAAS;YACZ,OAAO,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,EAAE,CAAA;QACjE,KAAK,QAAQ;YACX,OAAO,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAA;QAC3D,KAAK,OAAO;YACV,OAAO,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAA;QACrE;YACE,OAAO,KAAK,CAAA;IAChB,CAAC;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,KAAkB,EAAiC,EAAE,CACtF,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA","sourcesContent":["/**\n * Resume compatibility is weaker than result reuse: unchanged callback source\n * may rebuild a recorded plan, but an opaque closure still cannot earn a cache\n * hit. Only the interpreter's PlanRecorded guard uses this projection. Approval\n * digests and dispatch keys keep the original entropy-bearing material.\n *\n * @since 1.0.0\n * @internal\n */\n\nimport { isRecord } from \"@smthrs/canonical/Record\"\nimport type * as Plan from \"@smthrs/plan/Plan\"\nimport * as Graph from \"../Graph.ts\"\n\n/** Missing source metadata retains the old identity and fails closed. */\nconst callback = (value: unknown): unknown =>\n  isRecord(value) && value._tag === \"FunctionIdentity\" && value.algorithm === \"sha256-source-ephemeral/v4\" &&\n    typeof value.sourceDigest === \"string\"\n    ? { _tag: value._tag, algorithm: value.algorithm, digest: value.sourceDigest }\n    : value\n\n/** Project only callback slots, never identity-shaped application data. */\nconst body = (value: unknown): unknown => {\n  if (!isRecord(value)) return value\n  switch (value._tag) {\n    case \"FlowCall\":\n      return isRecord(value.declaration)\n        ? { ...value, declaration: { ...value.declaration, body: callback(value.declaration.body) } }\n        : value\n    case \"Map\":\n      return { ...value, mapper: callback(value.mapper) }\n    case \"AndThen\":\n      return { ...value, continuation: callback(value.continuation) }\n    case \"Branch\":\n      return { ...value, predicate: callback(value.predicate) }\n    case \"Catch\":\n      return { ...value, filterIdentity: callback(value.filterIdentity) }\n    default:\n      return value\n  }\n}\n\n/**\n * The same drafts, with only callback identities made restart-comparable.\n *\n * @since 1.0.0\n * @private\n */\nexport const recordedPlanDrafts = (graph: Graph.Graph): ReadonlyArray<Plan.NodeDraft> =>\n  Graph.drafts(graph).map((draft) => ({ ...draft, material: { ...draft.material, body: body(draft.material.body) } }))\n"]}

package/docs/guides/inspect-the-plan.md

@@ -19,7 +19,7 @@ engine, database, or jj: planning reads declarations only. They import
 add both at the version of `@smthrs/flows` you have:
 
 ```bash
-npm install @smthrs/flow@1.0.0-rc.12 @smthrs/plan@1.0.0-rc.12
+npm install @smthrs/flow@1.0.0-rc.14 @smthrs/plan@1.0.0-rc.14
 ```
 
 `@smthrs/flows` re-exports the same modules, so `import { Graph } from "@smthrs/flows"`

package/docs/installation.md

@@ -13,8 +13,8 @@ npm install @smthrs/flow@next effect
 
 The `next` tag carries the 1.0 release candidates.
 
-`effect` is a peer dependency of this package, in the range `^4.0.4`. Add one
-`effect` in that range to your own dependencies: your declarations import
+`effect` is a peer dependency of this package, at exactly `4.0.5`. Add one
+`effect` at that version to your own dependencies: your declarations import
 `effect/Schema` and your implementations import `effect/Effect` directly, and two
 copies of `effect` in one program are two sets of service tags.
 
@@ -28,7 +28,7 @@ from, and the canonical JSON checks applied to values.
 ## Use the libraries
 
 Every `@smthrs` library installs from npm the same way. Name each package your
-code imports with the `next` tag, and add one `effect` in the `^4.0.4` range
+code imports with the `next` tag, and add one `effect` in the `4.0.5` range
 the libraries peer. The [Quickstart](./quickstart.md) program needs these:
 
 ```bash

package/docs/quickstart.md

@@ -10,7 +10,7 @@ touches a database or the network, and the result arrives as a typed value
 decoded by the schema you declared.
 
 A runnable copy of this program is published in the Smithers examples,
-[`01-define-and-run.ts`](https://github.com/smithersai/smithers/blob/main/examples/src/01-define-and-run.ts).
+[`01-define-and-run.ts`](https://github.com/smithersai/smithers/blob/main/packages/smithers/flows/engine/examples/01-define-and-run.ts).
 
 ## Prerequisites
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@smthrs/flow",
   "type": "module",
-  "version": "1.0.0-rc.12",
+  "version": "1.0.0-rc.14",
   "license": "MIT",
   "smthrs": {
     "group": "engine"
@@ -289,21 +289,21 @@
     "tag": "next"
   },
   "dependencies": {
-    "@smthrs/crypto": "1.0.0-rc.12",
-    "@smthrs/keys": "1.0.0-rc.12",
-    "@smthrs/plan": "1.0.0-rc.12",
-    "@smthrs/canonical": "1.0.0-rc.12",
-    "@smthrs/capability": "1.0.0-rc.12"
+    "@smthrs/crypto": "1.0.0-rc.14",
+    "@smthrs/keys": "1.0.0-rc.14",
+    "@smthrs/plan": "1.0.0-rc.14",
+    "@smthrs/canonical": "1.0.0-rc.14",
+    "@smthrs/capability": "1.0.0-rc.14"
   },
   "devDependencies": {
     "@effect/language-service": "0.87.2",
-    "@effect/platform-node": "4.0.4",
-    "@effect/vitest": "4.0.4",
+    "@effect/platform-node": "4.0.5",
+    "@effect/vitest": "4.0.5",
     "@eslint/js": "9.39.5",
     "@types/node": "26.4.1",
     "@vitest/coverage-v8": "5.0.0",
     "dprint": "0.57.1",
-    "effect": "4.0.4",
+    "effect": "4.0.5",
     "esbuild": "0.28.2",
     "eslint": "9.39.5",
     "eslint-import-resolver-typescript": "4.4.5",
@@ -316,7 +316,7 @@
     "vitest": "5.0.0"
   },
   "peerDependencies": {
-    "effect": "^4.0.4"
+    "effect": "4.0.5"
   },
   "scripts": {
     "lint": "eslint src examples --max-warnings=0 && dprint check",

package/src/Flow/make.ts

@@ -84,6 +84,20 @@ interface MakeOptions<
    * reach.
    */
   readonly modelInvocable?: boolean | undefined
+  /**
+   * The tokens, milliseconds and dollars one run asks a control plane to
+   * approve, and what exceeding them does, as a literal.
+   *
+   * Discovery reads it from the source text onto the descriptor's budget,
+   * exactly as Markdown frontmatter's `budget` is read; the control plane, not
+   * this flow, enforces it.
+   */
+  readonly budget?: {
+    readonly tokens?: number | undefined
+    readonly milliseconds?: number | undefined
+    readonly usd?: number | undefined
+    readonly onExceeded?: "fail" | "warn" | "skip-remaining" | "park" | undefined
+  } | undefined
   readonly idempotencyKey?:
     | ((
       payload: Payload extends Schema.Struct.Fields ? Schema.Struct.Type<Payload>

package/src/HumanTask.ts

@@ -1004,4 +1004,18 @@ export const answer = (options: {
 export const decode =
   <S extends Schema.ConstraintDecoder<unknown>>(schema: S) =>
   <E, R>(self: Node.Node<typeof Schema.Json.Type, E, R>): Node.Node<S["Type"], E, R> =>
-    Node.map(self, Schema.decodeUnknownSync(schema))
+    Node.map(self, answerDecoder(schema))
+
+// Schema decoders are opaque callbacks. Reuse one per immutable schema so a
+// same-process rebuild preserves its identity without claiming portable
+// identity for arbitrary schema transformations or checks.
+const answerDecoders = new WeakMap<object, (input: unknown) => unknown>()
+
+const answerDecoder = <S extends Schema.ConstraintDecoder<unknown>>(schema: S): (input: unknown) => S["Type"] => {
+  let decoder = answerDecoders.get(schema)
+  if (decoder === undefined) {
+    decoder = Schema.decodeUnknownSync(schema)
+    answerDecoders.set(schema, decoder)
+  }
+  return decoder
+}

package/src/Interpreter.ts

@@ -80,6 +80,7 @@ import * as HumanTask from "./HumanTask.ts"
 import * as BoundedJson from "./internal/BoundedJson.ts"
 import { ExecutionMiddleware } from "./internal/ExecutionMiddleware.ts"
 import { OutcomeValueTypeId } from "./internal/OutcomeMarker.ts"
+import { recordedPlanDrafts } from "./internal/RecordedPlan.ts"
 import * as Sleep from "./Sleep.ts"
 import * as WaitFor from "./WaitFor.ts"
 
@@ -272,7 +273,7 @@ const planPages = (
 > =>
   Effect.gen(function*() {
     const identity = yield* StepKey.content({
-      body: { flow, nodes: Graph.drafts(graph), edges: Graph.edges(graph) },
+      body: { flow, nodes: recordedPlanDrafts(graph), edges: Graph.edges(graph) },
       inputs: {},
       layers: [],
       capabilities: {}
@@ -1486,12 +1487,27 @@ export const layer = <
 
 // These layers only register handlers at construction. Crypto is supplied by
 // the executing interpreter (Services), not required to register a flow.
-const systemActions = Layer.mergeAll(HumanTask.layer, Sleep.layer, WaitFor.layer) as Layer.Layer<
+const systemHandlers = Layer.mergeAll(HumanTask.layer, Sleep.layer, WaitFor.layer) as Layer.Layer<
   never,
   never,
   FlowRuntime
 >
 
+// Independent module/refresh layer builds can share one implementation table.
+// Memoize the built-ins by that owner, with Layer retaining each live scope's
+// reference, rather than registering a second handler or overriding the first.
+const systemMemoMaps = new WeakMap<Implementations["Service"], Layer.MemoMap>()
+const systemActions = Layer.fromBuild((currentMemoMap, scope) =>
+  Effect.flatMap(Implementations, (table) => {
+    let memoMap = systemMemoMaps.get(table)
+    if (memoMap === undefined) {
+      memoMap = currentMemoMap
+      systemMemoMaps.set(table, memoMap)
+    }
+    return Layer.buildWithMemoMap(systemHandlers, memoMap, scope)
+  })
+)
+
 /** Registers the interpreter and reachable child flows under one policy. @private */
 const makeLayer = <
   Tag extends string,

package/src/internal/RecordedPlan.ts

@@ -0,0 +1,50 @@
+/**
+ * Resume compatibility is weaker than result reuse: unchanged callback source
+ * may rebuild a recorded plan, but an opaque closure still cannot earn a cache
+ * hit. Only the interpreter's PlanRecorded guard uses this projection. Approval
+ * digests and dispatch keys keep the original entropy-bearing material.
+ *
+ * @since 1.0.0
+ * @internal
+ */
+
+import { isRecord } from "@smthrs/canonical/Record"
+import type * as Plan from "@smthrs/plan/Plan"
+import * as Graph from "../Graph.ts"
+
+/** Missing source metadata retains the old identity and fails closed. */
+const callback = (value: unknown): unknown =>
+  isRecord(value) && value._tag === "FunctionIdentity" && value.algorithm === "sha256-source-ephemeral/v4" &&
+    typeof value.sourceDigest === "string"
+    ? { _tag: value._tag, algorithm: value.algorithm, digest: value.sourceDigest }
+    : value
+
+/** Project only callback slots, never identity-shaped application data. */
+const body = (value: unknown): unknown => {
+  if (!isRecord(value)) return value
+  switch (value._tag) {
+    case "FlowCall":
+      return isRecord(value.declaration)
+        ? { ...value, declaration: { ...value.declaration, body: callback(value.declaration.body) } }
+        : value
+    case "Map":
+      return { ...value, mapper: callback(value.mapper) }
+    case "AndThen":
+      return { ...value, continuation: callback(value.continuation) }
+    case "Branch":
+      return { ...value, predicate: callback(value.predicate) }
+    case "Catch":
+      return { ...value, filterIdentity: callback(value.filterIdentity) }
+    default:
+      return value
+  }
+}
+
+/**
+ * The same drafts, with only callback identities made restart-comparable.
+ *
+ * @since 1.0.0
+ * @private
+ */
+export const recordedPlanDrafts = (graph: Graph.Graph): ReadonlyArray<Plan.NodeDraft> =>
+  Graph.drafts(graph).map((draft) => ({ ...draft, material: { ...draft.material, body: body(draft.material.body) } }))