effect-agent 0.1.0-beta.85 → 0.1.0-beta.87

package/dist/capabilities/Remembering.mjs

@@ -0,0 +1,290 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { n as utf8ByteLength } from "../utf8-DchGZRBd.mjs";
+import { MemoryContent, MemorySourceReference } from "../core/MemoryReference.mjs";
+import { MemoryDocument, MemoryKey, MemoryReader, MemoryScope, MemoryWrite, MemoryWriter } from "../core/MemoryStore.mjs";
+import { AdmissionError, Checkpoint, CheckpointError, Intent, Invalidation, MutationFailpoint, ProcessingError, Proposal, Source } from "../core/RememberingStore.mjs";
+import { Effect, Encoding, Schema } from "effect";
+//#region src/capabilities/Remembering.ts
+var Remembering_exports = /* @__PURE__ */ __exportAll({
+	Decision: () => Decision,
+	Limits: () => Limits,
+	SourceSnapshot: () => SourceSnapshot,
+	admit: () => admit,
+	invalidate: () => invalidate,
+	make: () => make
+});
+var Limits = class extends Schema.Class("@effect-agent/remembering/Limits")({
+	maxSourceBytes: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 4194304
+	})),
+	maxProposalBytes: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 1048576
+	})),
+	timeoutMillis: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 3e5
+	}))
+}) {};
+var SourceSnapshot = class extends Schema.Class("@effect-agent/remembering/SourceSnapshot")({
+	source: Source,
+	text: Schema.String.check(Schema.isMaxLength(4194304))
+}) {};
+const SourceResult = Schema.NullOr(Schema.Union([SourceSnapshot, Invalidation]));
+/** Application-authorized output. The coordinator binds key, operation ID and expected revision.
+* Fact acceptance, sharing scopes, profile schema and source-aware merging remain application code.
+*/
+const Decision = Schema.Union([
+	Schema.TaggedStruct("Put", {
+		locator: MemorySourceReference.fields.locator,
+		content: MemoryContent,
+		scopes: Schema.Array(MemoryScope).check(Schema.isMaxLength(128))
+	}),
+	Schema.TaggedStruct("Withdraw", { reason: Schema.String.check(Schema.isMaxLength(4096)) }),
+	Schema.TaggedStruct("NoChange", {}),
+	Schema.TaggedStruct("Reject", {})
+]);
+const equal = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const sameKey = (left, right) => left.id === right.id && left.namespace.address === right.namespace.address;
+const encodeIntent = Schema.encodeSync(Intent.Wire);
+const validateSource = Effect.fn("Remembering.validateSource")(function* (intent, snapshot, limits) {
+	const source = yield* Schema.decodeEffect(SourceSnapshot)(snapshot).pipe(Effect.mapError(() => ProcessingError.make({ reason: "invalid-input" })));
+	const actual = yield* Schema.encodeEffect(Source)(source.source);
+	const expected = yield* Schema.encodeEffect(Source)(intent.source);
+	if (!equal(actual, expected)) return yield* ProcessingError.make({ reason: "source-changed" });
+	if (utf8ByteLength(source.text) > limits.maxSourceBytes) return yield* ProcessingError.make({ reason: "budget" });
+	return source;
+});
+const validateEvidence = Effect.fn("Remembering.validateEvidence")(function* (source, proposal) {
+	const bytes = Encoding.encodeHex(source.text);
+	for (const evidence of proposal.evidence) {
+		const quote = Encoding.encodeHex(evidence.quote);
+		if (evidence.source.id !== source.source.key.id || evidence.source.revision !== source.source.revision || evidence.source.locator !== source.source.locator || evidence.endByte <= evidence.startByte || evidence.endByte > bytes.length / 2 || quote.length / 2 !== evidence.endByte - evidence.startByte || quote !== bytes.slice(evidence.startByte * 2, evidence.endByte * 2)) return yield* ProcessingError.make({ reason: "invalid-evidence" });
+	}
+});
+const validateCheckpoint = Effect.fn("Remembering.validateCheckpoint")(function* (intent, input) {
+	const checkpoint = yield* Schema.decodeEffect(Checkpoint)(input).pipe(Effect.mapError(() => CheckpointError.make({ reason: "corrupt" })));
+	if (!equal(encodeIntent(intent), encodeIntent(checkpoint.intent)) || checkpoint.suppression !== null && !sameKey(checkpoint.suppression.source, intent.source.key)) return yield* CheckpointError.make({ reason: "corrupt" });
+	const progress = checkpoint.progress;
+	if (progress._tag !== "Pending" && progress.applied !== null && !sameKey(progress.applied.key, intent.target)) return yield* CheckpointError.make({ reason: "corrupt" });
+	if (progress._tag === "Prepared" && (!sameKey(progress.command.key, intent.target) || progress.command.operationId !== operationId(intent, progress.purpose, progress.attempt))) return yield* CheckpointError.make({ reason: "corrupt" });
+	const applied = progress._tag === "Pending" || progress.applied === null ? null : yield* MemoryDocument.restore(intent.target.namespace, progress.applied).pipe(Effect.mapError(() => CheckpointError.make({ reason: "corrupt" })));
+	const boundProgress = progress._tag === "Pending" ? progress : progress._tag === "Prepared" ? {
+		...progress,
+		applied,
+		command: MemoryWrite.make({
+			...progress.command,
+			key: intent.target
+		})
+	} : {
+		...progress,
+		applied
+	};
+	const suppression = checkpoint.suppression === null ? null : Object.assign(checkpoint.suppression, { source: MemoryKey.make({
+		...checkpoint.suppression.source,
+		namespace: intent.source.key.namespace
+	}) });
+	return Object.assign(checkpoint, {
+		intent,
+		progress: boundProgress,
+		suppression
+	});
+});
+const operationId = (intent, purpose, attempt) => `remembering/${intent.id}/${purpose}/${attempt}`;
+const completed = (progress, outcome, cleaned, applied) => ({
+	_tag: "Completed",
+	proposal: progress._tag === "Pending" ? null : progress.proposal,
+	attempt: progress._tag === "Pending" ? 0 : progress.attempt,
+	applied: applied ?? (progress._tag === "Pending" ? null : progress.applied),
+	outcome,
+	cleaned
+});
+/** Foreground admission performs only one durable port call. Bind authority and idempotency
+* from the trusted invocation before calling; a queued receipt is returned only after commit.
+*/
+const admit = Effect.fn("Remembering.admit")(function* (store, intent) {
+	const checked = yield* Schema.decodeEffect(Intent.Wire)(intent).pipe(Effect.mapError(() => AdmissionError.make({ reason: "invalid-input" })));
+	const failpoint = yield* MutationFailpoint;
+	yield* failpoint.hit("admission:before");
+	const receipt = yield* store.admit(checked);
+	yield* failpoint.hit("admission:after");
+	return receipt;
+});
+/** Source owners await this durable suppression receipt before acknowledging edit/deletion/Forget.
+* Scheduling all affected retained references and conditional cleanup is the host's obligation.
+*/
+const invalidate = Effect.fn("Remembering.invalidate")(function* (store, event) {
+	const checked = yield* Schema.decodeEffect(Invalidation)(event).pipe(Effect.mapError(() => AdmissionError.make({ reason: "invalid-input" })));
+	const failpoint = yield* MutationFailpoint;
+	yield* failpoint.hit("suppression:before");
+	const receipt = yield* store.invalidate(checked);
+	yield* failpoint.hit("suppression:after");
+	return receipt;
+});
+/** Define one application learner. Extraction may call native Effect AI LanguageModel directly;
+* callback/model/schema requirements and errors remain in the returned Effect. No model owns
+* authority, source loading, fact acceptance, profile representation or sharing policy.
+* These are Effect-composition callbacks: they can yield application Context services, and advance
+* retains every callback's E/R. The framework neither acquires nor provides application policy.
+*
+* advance is finite: it extracts, prepares, dispatches, or rebases at most once. The host calls it
+* again when ready. A proposal is persisted before any target read; a complete command is saved
+* before dispatch. Unknown outcomes leave that command untouched. Only MemoryConflict rebases.
+* Cleanup receives the immutable proposal, original applied document and latest target so it can
+* remove that contribution without overwriting intervening human corrections.
+*
+* loadSource returns an explicit Invalidation when source authority changed or was revoked; its
+* suppression is committed before processing returns. null means absent on an initial load. A
+* later null or a changed snapshot without an authority event fails source-changed and retains
+* the obligation. Sources must keep revision content immutable. Evidence is checked again before
+* preparing a new command. A saved Prepared command may already have executed, so it never calls
+* loadSource and must reconcile even during a source outage. Source owners durably invalidate
+* before acknowledging edits, and authoritative recall filters suppression while cleanup runs.
+* No source text, proposal, authority identity, or extracted values are added to tracing spans.
+*/
+const make = (options) => {
+	return { advance: Effect.fn("Remembering.advance")(function* (input) {
+		const limits = yield* Schema.decodeEffect(Limits)(input.limits).pipe(Effect.mapError(() => ProcessingError.make({ reason: "invalid-input" })));
+		const decodedIntent = yield* Schema.decodeUnknownEffect(Intent.Wire)(input.intent).pipe(Effect.mapError(() => ProcessingError.make({ reason: "invalid-input" })));
+		const intent = Object.assign(decodedIntent, {
+			source: {
+				...decodedIntent.source,
+				key: MemoryKey.make({
+					...decodedIntent.source.key,
+					namespace: input.intent.source.key.namespace
+				})
+			},
+			target: MemoryKey.make({
+				...decodedIntent.target,
+				namespace: input.intent.target.namespace
+			})
+		});
+		return yield* Effect.gen(function* () {
+			const checkpoint = yield* input.store.read(intent).pipe(Effect.flatMap((value) => validateCheckpoint(intent, value)));
+			const progress = checkpoint.progress;
+			const suppression = checkpoint.suppression;
+			if (progress._tag === "Proposed" && suppression === null && utf8ByteLength(JSON.stringify(progress.proposal)) > limits.maxProposalBytes) return yield* ProcessingError.make({ reason: "budget" });
+			const failpoint = yield* MutationFailpoint;
+			const save = Effect.fn("Remembering.save")(function* (next, before, after) {
+				yield* failpoint.hit(before);
+				const stored = yield* input.store.save({
+					intent,
+					expectedVersion: checkpoint.version,
+					progress: next
+				});
+				yield* failpoint.hit(after);
+				return yield* validateCheckpoint(intent, stored);
+			});
+			const suppress = Effect.fn("Remembering.suppress")(function* (event) {
+				if (!sameKey(event.source, intent.source.key)) return yield* ProcessingError.make({ reason: "invalid-input" });
+				yield* invalidate(input.store, event);
+				return yield* input.store.read(intent).pipe(Effect.flatMap((value) => validateCheckpoint(intent, value)));
+			});
+			if (progress._tag === "Completed" && (suppression === null || progress.cleaned)) return checkpoint;
+			if (suppression !== null && progress._tag !== "Prepared" && (progress._tag === "Pending" || progress.applied === null)) return yield* save(completed(progress, "suppressed", true), "completion:before", "completion:after");
+			if (progress._tag === "Pending") {
+				if (!input.extractionEnabled) return yield* ProcessingError.make({ reason: "disabled" });
+				const snapshot = yield* options.loadSource(intent).pipe(Effect.flatMap(Schema.decodeUnknownEffect(SourceResult)));
+				if (snapshot === null) return yield* save(completed(progress, "rejected", false), "completion:before", "completion:after");
+				if (Schema.is(Invalidation)(snapshot)) return yield* suppress(snapshot);
+				const source = yield* validateSource(intent, snapshot, limits);
+				const extracted = yield* options.extract(source, intent);
+				if (extracted === null) return yield* save(completed(progress, "no-change", false), "completion:before", "completion:after");
+				const value = yield* Schema.encodeEffect(options.proposal)(extracted.value);
+				const proposal = yield* Schema.decodeUnknownEffect(Proposal)({
+					version: 1,
+					value,
+					evidence: extracted.evidence
+				});
+				if (utf8ByteLength(JSON.stringify(proposal)) > limits.maxProposalBytes) return yield* ProcessingError.make({ reason: "budget" });
+				yield* validateEvidence(source, proposal);
+				const latest = yield* options.loadSource(intent).pipe(Effect.flatMap(Schema.decodeUnknownEffect(SourceResult)));
+				if (latest === null) return yield* ProcessingError.make({ reason: "source-changed" });
+				if (Schema.is(Invalidation)(latest)) return yield* suppress(latest);
+				yield* validateSource(intent, latest, limits);
+				if (latest.text !== source.text) return yield* ProcessingError.make({ reason: "source-changed" });
+				return yield* save({
+					_tag: "Proposed",
+					proposal,
+					attempt: 0,
+					purpose: "remember",
+					applied: null
+				}, "proposal:before", "proposal:after");
+			}
+			if (progress._tag === "Prepared") {
+				const writer = yield* MemoryWriter;
+				const command = MemoryWrite.make({
+					...progress.command,
+					key: intent.target
+				});
+				const outcome = yield* writer.change(command).pipe(Effect.map((document) => ({
+					_tag: "Written",
+					document
+				})), Effect.catchTag("MemoryConflict", () => Effect.succeed({ _tag: "Conflict" })), Effect.catchTag("MemoryWithdrawn", () => Effect.succeed({ _tag: "Withdrawn" })));
+				if (outcome._tag === "Written") return yield* save(completed(progress, progress.purpose === "cleanup" ? "suppressed" : "applied", progress.purpose === "cleanup", progress.purpose === "remember" ? outcome.document : void 0), "completion:before", "completion:after");
+				if (outcome._tag === "Withdrawn" || suppression !== null && progress.purpose === "remember") return yield* save(completed(progress, suppression !== null ? "suppressed" : "rejected", suppression !== null), "completion:before", "completion:after");
+				return yield* save({
+					_tag: "Proposed",
+					proposal: progress.proposal,
+					attempt: progress.attempt,
+					purpose: progress.purpose,
+					applied: progress.applied
+				}, "rebase:before", "rebase:after");
+			}
+			const proposal = progress.proposal;
+			if (proposal === null) return yield* CheckpointError.make({ reason: "corrupt" });
+			if (suppression === null) {
+				const latest = yield* options.loadSource(intent).pipe(Effect.flatMap(Schema.decodeUnknownEffect(SourceResult)));
+				if (latest === null) return yield* ProcessingError.make({ reason: "source-changed" });
+				if (Schema.is(Invalidation)(latest)) return yield* suppress(latest);
+				yield* validateSource(intent, latest, limits);
+				yield* validateEvidence(latest, proposal);
+			}
+			const value = yield* Schema.decodeUnknownEffect(options.proposal)(proposal.value);
+			const current = yield* (yield* MemoryReader).get(intent.target);
+			const applied = progress.applied === null ? null : yield* MemoryDocument.restore(intent.target.namespace, progress.applied);
+			const cleanup = suppression !== null && applied !== null;
+			const mergeInput = {
+				intent,
+				proposal: {
+					value,
+					evidence: proposal.evidence
+				},
+				current
+			};
+			const candidate = cleanup ? yield* options.cleanup({
+				...mergeInput,
+				suppression,
+				applied
+			}) : yield* options.merge(mergeInput);
+			const decision = yield* Schema.decodeEffect(Decision)(candidate);
+			if (cleanup && decision._tag === "Reject") return yield* ProcessingError.make({ reason: "cleanup-rejected" });
+			if (decision._tag === "NoChange" || decision._tag === "Reject") return yield* save(completed(progress, cleanup ? "suppressed" : decision._tag === "Reject" ? "rejected" : "no-change", cleanup, !cleanup && decision._tag === "NoChange" && current !== null ? current : void 0), cleanup ? "cleanup:before" : "completion:before", cleanup ? "cleanup:after" : "completion:after");
+			if (decision._tag === "Withdraw" && current === null) return yield* save(completed(progress, cleanup ? "suppressed" : "no-change", cleanup), "completion:before", "completion:after");
+			const purpose = cleanup ? "cleanup" : "remember";
+			const attempt = progress.attempt + 1;
+			const key = intent.target;
+			return yield* save({
+				_tag: "Prepared",
+				proposal,
+				applied,
+				attempt,
+				purpose,
+				command: yield* Schema.decodeUnknownEffect(MemoryWrite.Wire)({
+					...decision,
+					key,
+					operationId: operationId(intent, purpose, attempt),
+					expectedRevision: current?.source.revision ?? null
+				})
+			}, cleanup ? "cleanup:before" : "command:before", cleanup ? "cleanup:after" : "command:after");
+		}).pipe(Effect.timeoutOrElse({
+			duration: limits.timeoutMillis,
+			orElse: () => ProcessingError.make({ reason: "timeout" })
+		}));
+	}) };
+};
+//#endregion
+export { Decision, Limits, SourceSnapshot, admit, invalidate, make, Remembering_exports as t };
+
+//# sourceMappingURL=Remembering.mjs.map

package/dist/capabilities/Remembering.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Remembering.mjs","names":["Protocol.Source","Protocol.Invalidation","Protocol.Checkpoint","Protocol.MutationFailpoint","Protocol.Proposal"],"sources":["../../src/capabilities/Remembering.ts"],"sourcesContent":["import { Effect, Encoding, Schema } from \"effect\";\n\nimport { utf8ByteLength } from \"../core/internal/utf8.ts\";\nimport type * as MemoryNamespace from \"../core/MemoryNamespace.ts\";\nimport { MemoryContent, MemorySourceReference } from \"../core/MemoryReference.ts\";\nimport {\n  MemoryDocument,\n  MemoryKey,\n  MemoryReader,\n  MemoryScope,\n  MemoryWrite,\n  MemoryWriter,\n} from \"../core/MemoryStore.ts\";\nimport * as Protocol from \"../core/RememberingStore.ts\";\n\nexport class Limits extends Schema.Class<Limits>(\"@effect-agent/remembering/Limits\")({\n  maxSourceBytes: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 4_194_304 })),\n  maxProposalBytes: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 1_048_576 })),\n  timeoutMillis: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 300_000 })),\n}) {}\n\nexport class SourceSnapshot extends Schema.Class<SourceSnapshot>(\n  \"@effect-agent/remembering/SourceSnapshot\",\n)({\n  source: Protocol.Source,\n  text: Schema.String.check(Schema.isMaxLength(4_194_304)),\n}) {}\n\nconst SourceResult = Schema.NullOr(Schema.Union([SourceSnapshot, Protocol.Invalidation]));\n\n/** Application-authorized output. The coordinator binds key, operation ID and expected revision.\n * Fact acceptance, sharing scopes, profile schema and source-aware merging remain application code.\n */\nexport const Decision = Schema.Union([\n  Schema.TaggedStruct(\"Put\", {\n    locator: MemorySourceReference.fields.locator,\n    content: MemoryContent,\n    scopes: Schema.Array(MemoryScope).check(Schema.isMaxLength(128)),\n  }),\n  Schema.TaggedStruct(\"Withdraw\", { reason: Schema.String.check(Schema.isMaxLength(4_096)) }),\n  Schema.TaggedStruct(\"NoChange\", {}),\n  Schema.TaggedStruct(\"Reject\", {}),\n]);\n\nexport type Decision = typeof Decision.Type;\n\nexport interface MergeInput<Value, S extends MemoryNamespace.Any, T extends MemoryNamespace.Any> {\n  readonly intent: Protocol.Intent<S, T>;\n  readonly proposal: Protocol.Extracted<Value>;\n  readonly current: MemoryDocument<T> | null;\n}\n\nexport interface CleanupInput<\n  Value,\n  S extends MemoryNamespace.Any,\n  T extends MemoryNamespace.Any,\n> extends MergeInput<Value, S, T> {\n  readonly suppression: Protocol.Invalidation;\n  readonly applied: MemoryDocument<T>;\n}\n\nconst equal = (left: unknown, right: unknown): boolean =>\n  JSON.stringify(left) === JSON.stringify(right);\n\nconst sameKey = (left: MemoryKey, right: MemoryKey): boolean =>\n  left.id === right.id && left.namespace.address === right.namespace.address;\n\nconst encodeIntent = Schema.encodeSync(Protocol.Intent.Wire);\n\nconst validateSource = Effect.fn(\"Remembering.validateSource\")(function* (\n  intent: Protocol.Intent,\n  snapshot: SourceSnapshot,\n  limits: Limits,\n) {\n  const source = yield* Schema.decodeEffect(SourceSnapshot)(snapshot).pipe(\n    Effect.mapError(() => Protocol.ProcessingError.make({ reason: \"invalid-input\" })),\n  );\n\n  const actual = yield* Schema.encodeEffect(Protocol.Source)(source.source);\n  const expected = yield* Schema.encodeEffect(Protocol.Source)(intent.source);\n\n  if (!equal(actual, expected))\n    return yield* Protocol.ProcessingError.make({ reason: \"source-changed\" });\n  if (utf8ByteLength(source.text) > limits.maxSourceBytes)\n    return yield* Protocol.ProcessingError.make({ reason: \"budget\" });\n\n  return source;\n});\n\nconst validateEvidence = Effect.fn(\"Remembering.validateEvidence\")(function* (\n  source: SourceSnapshot,\n  proposal: Protocol.Proposal,\n) {\n  const bytes = Encoding.encodeHex(source.text);\n\n  for (const evidence of proposal.evidence) {\n    const quote = Encoding.encodeHex(evidence.quote);\n\n    if (\n      evidence.source.id !== source.source.key.id ||\n      evidence.source.revision !== source.source.revision ||\n      evidence.source.locator !== source.source.locator ||\n      evidence.endByte <= evidence.startByte ||\n      evidence.endByte > bytes.length / 2 ||\n      quote.length / 2 !== evidence.endByte - evidence.startByte ||\n      quote !== bytes.slice(evidence.startByte * 2, evidence.endByte * 2)\n    )\n      return yield* Protocol.ProcessingError.make({ reason: \"invalid-evidence\" });\n  }\n});\n\nconst validateCheckpoint = Effect.fn(\"Remembering.validateCheckpoint\")(function* <\n  S extends MemoryNamespace.Any,\n  T extends MemoryNamespace.Any,\n>(\n  intent: Protocol.Intent<S, T>,\n  input: Protocol.Checkpoint,\n): Effect.fn.Return<Protocol.BoundCheckpoint<S, T>, Protocol.CheckpointError> {\n  const checkpoint = yield* Schema.decodeEffect(Protocol.Checkpoint)(input).pipe(\n    Effect.mapError(() => Protocol.CheckpointError.make({ reason: \"corrupt\" })),\n  );\n\n  if (\n    !equal(encodeIntent(intent), encodeIntent(checkpoint.intent)) ||\n    (checkpoint.suppression !== null && !sameKey(checkpoint.suppression.source, intent.source.key))\n  )\n    return yield* Protocol.CheckpointError.make({ reason: \"corrupt\" });\n  const progress = checkpoint.progress;\n\n  if (\n    progress._tag !== \"Pending\" &&\n    progress.applied !== null &&\n    !sameKey(progress.applied.key, intent.target)\n  )\n    return yield* Protocol.CheckpointError.make({ reason: \"corrupt\" });\n  if (\n    progress._tag === \"Prepared\" &&\n    (!sameKey(progress.command.key, intent.target) ||\n      progress.command.operationId !== operationId(intent, progress.purpose, progress.attempt))\n  )\n    return yield* Protocol.CheckpointError.make({ reason: \"corrupt\" });\n\n  const applied =\n    progress._tag === \"Pending\" || progress.applied === null\n      ? null\n      : yield* MemoryDocument.restore(intent.target.namespace, progress.applied).pipe(\n          Effect.mapError(() => Protocol.CheckpointError.make({ reason: \"corrupt\" })),\n        );\n\n  const boundProgress: Protocol.Progress<T> =\n    progress._tag === \"Pending\"\n      ? progress\n      : progress._tag === \"Prepared\"\n        ? {\n            ...progress,\n            applied,\n            command: MemoryWrite.make({ ...progress.command, key: intent.target }),\n          }\n        : { ...progress, applied };\n\n  const suppression: Protocol.BoundInvalidation<S> | null =\n    checkpoint.suppression === null\n      ? null\n      : Object.assign(checkpoint.suppression, {\n          source: MemoryKey.make({\n            ...checkpoint.suppression.source,\n            namespace: intent.source.key.namespace,\n          }),\n        });\n\n  return Object.assign(checkpoint, { intent, progress: boundProgress, suppression });\n});\n\nconst operationId = (\n  intent: Protocol.Intent,\n  purpose: \"remember\" | \"cleanup\",\n  attempt: number,\n): string => `remembering/${intent.id}/${purpose}/${attempt}`;\n\nconst completed = (\n  progress: Protocol.Progress,\n  outcome: \"applied\" | \"no-change\" | \"rejected\" | \"suppressed\",\n  cleaned: boolean,\n  applied?: MemoryDocument,\n): Protocol.Progress => ({\n  _tag: \"Completed\",\n  proposal: progress._tag === \"Pending\" ? null : progress.proposal,\n  attempt: progress._tag === \"Pending\" ? 0 : progress.attempt,\n  applied: applied ?? (progress._tag === \"Pending\" ? null : progress.applied),\n  outcome,\n  cleaned,\n});\n\n/** Foreground admission performs only one durable port call. Bind authority and idempotency\n * from the trusted invocation before calling; a queued receipt is returned only after commit.\n */\nexport const admit = Effect.fn(\"Remembering.admit\")(function* <E, R>(\n  store: Protocol.Store<E, R>,\n  intent: Protocol.Intent,\n) {\n  const checked = yield* Schema.decodeEffect(Protocol.Intent.Wire)(intent).pipe(\n    Effect.mapError(() => Protocol.AdmissionError.make({ reason: \"invalid-input\" })),\n  );\n\n  const failpoint = yield* Protocol.MutationFailpoint;\n\n  yield* failpoint.hit(\"admission:before\");\n  const receipt = yield* store.admit(checked);\n\n  yield* failpoint.hit(\"admission:after\");\n\n  return receipt;\n});\n\n/** Source owners await this durable suppression receipt before acknowledging edit/deletion/Forget.\n * Scheduling all affected retained references and conditional cleanup is the host's obligation.\n */\nexport const invalidate = Effect.fn(\"Remembering.invalidate\")(function* <E, R>(\n  store: Protocol.Store<E, R>,\n  event: Protocol.Invalidation,\n) {\n  const checked = yield* Schema.decodeEffect(Protocol.Invalidation)(event).pipe(\n    Effect.mapError(() => Protocol.AdmissionError.make({ reason: \"invalid-input\" })),\n  );\n\n  const failpoint = yield* Protocol.MutationFailpoint;\n\n  yield* failpoint.hit(\"suppression:before\");\n  const receipt = yield* store.invalidate(checked);\n\n  yield* failpoint.hit(\"suppression:after\");\n\n  return receipt;\n});\n\n/** Define one application learner. Extraction may call native Effect AI LanguageModel directly;\n * callback/model/schema requirements and errors remain in the returned Effect. No model owns\n * authority, source loading, fact acceptance, profile representation or sharing policy.\n * These are Effect-composition callbacks: they can yield application Context services, and advance\n * retains every callback's E/R. The framework neither acquires nor provides application policy.\n *\n * advance is finite: it extracts, prepares, dispatches, or rebases at most once. The host calls it\n * again when ready. A proposal is persisted before any target read; a complete command is saved\n * before dispatch. Unknown outcomes leave that command untouched. Only MemoryConflict rebases.\n * Cleanup receives the immutable proposal, original applied document and latest target so it can\n * remove that contribution without overwriting intervening human corrections.\n *\n * loadSource returns an explicit Invalidation when source authority changed or was revoked; its\n * suppression is committed before processing returns. null means absent on an initial load. A\n * later null or a changed snapshot without an authority event fails source-changed and retains\n * the obligation. Sources must keep revision content immutable. Evidence is checked again before\n * preparing a new command. A saved Prepared command may already have executed, so it never calls\n * loadSource and must reconcile even during a source outage. Source owners durably invalidate\n * before acknowledging edits, and authoritative recall filters suppression while cleanup runs.\n * No source text, proposal, authority identity, or extracted values are added to tracing spans.\n */\nexport const make = <\n  S extends MemoryNamespace.Any,\n  T extends MemoryNamespace.Any,\n  Value,\n  Encoded extends Schema.Json,\n  DecodeR,\n  EncodeR,\n  SourceE,\n  SourceR,\n  ExtractE,\n  ExtractR,\n  MergeE,\n  MergeR,\n  CleanupE,\n  CleanupR,\n>(options: {\n  readonly proposal: Schema.Codec<Value, Encoded, DecodeR, EncodeR>;\n  readonly loadSource: (\n    intent: Protocol.Intent<S, T>,\n  ) => Effect.Effect<SourceSnapshot | Protocol.Invalidation | null, SourceE, SourceR>;\n  readonly extract: (\n    source: SourceSnapshot,\n    intent: Protocol.Intent<S, T>,\n  ) => Effect.Effect<Protocol.Extracted<Value> | null, ExtractE, ExtractR>;\n  readonly merge: (input: MergeInput<Value, S, T>) => Effect.Effect<Decision, MergeE, MergeR>;\n  readonly cleanup: (\n    input: CleanupInput<Value, S, T>,\n  ) => Effect.Effect<Decision, CleanupE, CleanupR>;\n}) => {\n  const advance = Effect.fn(\"Remembering.advance\")(function* <StoreE, StoreR>(input: {\n    readonly intent: Protocol.Intent<S, T>;\n    readonly store: Protocol.Store<StoreE, StoreR>;\n    readonly limits: Limits;\n    /** Stops new extraction only. Saved commands, rebase and suppression cleanup still run. */\n    readonly extractionEnabled: boolean;\n  }) {\n    const limits = yield* Schema.decodeEffect(Limits)(input.limits).pipe(\n      Effect.mapError(() => Protocol.ProcessingError.make({ reason: \"invalid-input\" })),\n    );\n\n    const decodedIntent = yield* Schema.decodeUnknownEffect(Protocol.Intent.Wire)(\n      input.intent,\n    ).pipe(Effect.mapError(() => Protocol.ProcessingError.make({ reason: \"invalid-input\" })));\n\n    const intent: Protocol.Intent<S, T> = Object.assign(decodedIntent, {\n      source: {\n        ...decodedIntent.source,\n        key: MemoryKey.make({\n          ...decodedIntent.source.key,\n          namespace: input.intent.source.key.namespace,\n        }),\n      },\n      target: MemoryKey.make({ ...decodedIntent.target, namespace: input.intent.target.namespace }),\n    });\n\n    const run = Effect.gen(function* () {\n      const checkpoint = yield* input.store\n        .read(intent)\n        .pipe(Effect.flatMap((value) => validateCheckpoint(intent, value)));\n\n      const progress = checkpoint.progress;\n      const suppression = checkpoint.suppression;\n\n      if (\n        progress._tag === \"Proposed\" &&\n        suppression === null &&\n        utf8ByteLength(JSON.stringify(progress.proposal)) > limits.maxProposalBytes\n      )\n        return yield* Protocol.ProcessingError.make({ reason: \"budget\" });\n      const failpoint = yield* Protocol.MutationFailpoint;\n\n      const save = Effect.fn(\"Remembering.save\")(function* (\n        next: Protocol.Progress,\n        before: Protocol.MutationPoint,\n        after: Protocol.MutationPoint,\n      ) {\n        yield* failpoint.hit(before);\n\n        const stored = yield* input.store.save({\n          intent,\n          expectedVersion: checkpoint.version,\n          progress: next,\n        });\n\n        yield* failpoint.hit(after);\n\n        return yield* validateCheckpoint(intent, stored);\n      });\n\n      const suppress = Effect.fn(\"Remembering.suppress\")(function* (event: Protocol.Invalidation) {\n        if (!sameKey(event.source, intent.source.key))\n          return yield* Protocol.ProcessingError.make({ reason: \"invalid-input\" });\n        yield* invalidate(input.store, event);\n\n        return yield* input.store\n          .read(intent)\n          .pipe(Effect.flatMap((value) => validateCheckpoint(intent, value)));\n      });\n\n      if (progress._tag === \"Completed\" && (suppression === null || progress.cleaned))\n        return checkpoint;\n      if (\n        suppression !== null &&\n        progress._tag !== \"Prepared\" &&\n        (progress._tag === \"Pending\" || progress.applied === null)\n      )\n        return yield* save(\n          completed(progress, \"suppressed\", true),\n          \"completion:before\",\n          \"completion:after\",\n        );\n\n      if (progress._tag === \"Pending\") {\n        if (!input.extractionEnabled)\n          return yield* Protocol.ProcessingError.make({ reason: \"disabled\" });\n\n        const snapshot = yield* options\n          .loadSource(intent)\n          .pipe(Effect.flatMap(Schema.decodeUnknownEffect(SourceResult)));\n\n        if (snapshot === null)\n          return yield* save(\n            completed(progress, \"rejected\", false),\n            \"completion:before\",\n            \"completion:after\",\n          );\n        if (Schema.is(Protocol.Invalidation)(snapshot)) return yield* suppress(snapshot);\n        const source = yield* validateSource(intent, snapshot, limits);\n        const extracted = yield* options.extract(source, intent);\n\n        if (extracted === null)\n          return yield* save(\n            completed(progress, \"no-change\", false),\n            \"completion:before\",\n            \"completion:after\",\n          );\n        const value = yield* Schema.encodeEffect(options.proposal)(extracted.value);\n\n        const proposal = yield* Schema.decodeUnknownEffect(Protocol.Proposal)({\n          version: 1,\n          value,\n          evidence: extracted.evidence,\n        });\n\n        if (utf8ByteLength(JSON.stringify(proposal)) > limits.maxProposalBytes)\n          return yield* Protocol.ProcessingError.make({ reason: \"budget\" });\n        yield* validateEvidence(source, proposal);\n\n        const latest = yield* options\n          .loadSource(intent)\n          .pipe(Effect.flatMap(Schema.decodeUnknownEffect(SourceResult)));\n\n        if (latest === null)\n          return yield* Protocol.ProcessingError.make({ reason: \"source-changed\" });\n        if (Schema.is(Protocol.Invalidation)(latest)) return yield* suppress(latest);\n        yield* validateSource(intent, latest, limits);\n        if (latest.text !== source.text)\n          return yield* Protocol.ProcessingError.make({ reason: \"source-changed\" });\n\n        return yield* save(\n          { _tag: \"Proposed\", proposal, attempt: 0, purpose: \"remember\", applied: null },\n          \"proposal:before\",\n          \"proposal:after\",\n        );\n      }\n\n      if (progress._tag === \"Prepared\") {\n        const writer = yield* MemoryWriter;\n        const command = MemoryWrite.make({ ...progress.command, key: intent.target });\n\n        const outcome = yield* writer.change(command).pipe(\n          Effect.map((document) => ({ _tag: \"Written\" as const, document })),\n          Effect.catchTag(\"MemoryConflict\", () => Effect.succeed({ _tag: \"Conflict\" as const })),\n          Effect.catchTag(\"MemoryWithdrawn\", () => Effect.succeed({ _tag: \"Withdrawn\" as const })),\n        );\n\n        if (outcome._tag === \"Written\") {\n          return yield* save(\n            completed(\n              progress,\n              progress.purpose === \"cleanup\" ? \"suppressed\" : \"applied\",\n              progress.purpose === \"cleanup\",\n              progress.purpose === \"remember\" ? outcome.document : undefined,\n            ),\n            \"completion:before\",\n            \"completion:after\",\n          );\n        }\n        if (\n          outcome._tag === \"Withdrawn\" ||\n          (suppression !== null && progress.purpose === \"remember\")\n        )\n          return yield* save(\n            completed(\n              progress,\n              suppression !== null ? \"suppressed\" : \"rejected\",\n              suppression !== null,\n            ),\n            \"completion:before\",\n            \"completion:after\",\n          );\n\n        return yield* save(\n          {\n            _tag: \"Proposed\",\n            proposal: progress.proposal,\n            attempt: progress.attempt,\n            purpose: progress.purpose,\n            applied: progress.applied,\n          },\n          \"rebase:before\",\n          \"rebase:after\",\n        );\n      }\n\n      const proposal = progress.proposal;\n\n      if (proposal === null) return yield* Protocol.CheckpointError.make({ reason: \"corrupt\" });\n      if (suppression === null) {\n        const latest = yield* options\n          .loadSource(intent)\n          .pipe(Effect.flatMap(Schema.decodeUnknownEffect(SourceResult)));\n\n        if (latest === null)\n          return yield* Protocol.ProcessingError.make({ reason: \"source-changed\" });\n        if (Schema.is(Protocol.Invalidation)(latest)) return yield* suppress(latest);\n        yield* validateSource(intent, latest, limits);\n        yield* validateEvidence(latest, proposal);\n      }\n      const value = yield* Schema.decodeUnknownEffect(options.proposal)(proposal.value);\n      const reader = yield* MemoryReader;\n      const current = yield* reader.get(intent.target);\n\n      const applied =\n        progress.applied === null\n          ? null\n          : yield* MemoryDocument.restore(intent.target.namespace, progress.applied);\n\n      const cleanup = suppression !== null && applied !== null;\n      const mergeInput = { intent, proposal: { value, evidence: proposal.evidence }, current };\n\n      const candidate = cleanup\n        ? yield* options.cleanup({ ...mergeInput, suppression, applied })\n        : yield* options.merge(mergeInput);\n\n      const decision = yield* Schema.decodeEffect(Decision)(candidate);\n\n      if (cleanup && decision._tag === \"Reject\")\n        return yield* Protocol.ProcessingError.make({ reason: \"cleanup-rejected\" });\n      if (decision._tag === \"NoChange\" || decision._tag === \"Reject\")\n        return yield* save(\n          completed(\n            progress,\n            cleanup ? \"suppressed\" : decision._tag === \"Reject\" ? \"rejected\" : \"no-change\",\n            cleanup,\n            !cleanup && decision._tag === \"NoChange\" && current !== null ? current : undefined,\n          ),\n          cleanup ? \"cleanup:before\" : \"completion:before\",\n          cleanup ? \"cleanup:after\" : \"completion:after\",\n        );\n      if (decision._tag === \"Withdraw\" && current === null)\n        return yield* save(\n          completed(progress, cleanup ? \"suppressed\" : \"no-change\", cleanup),\n          \"completion:before\",\n          \"completion:after\",\n        );\n      const purpose = cleanup ? \"cleanup\" : \"remember\";\n      const attempt = progress.attempt + 1;\n      const key = intent.target;\n\n      const write = yield* Schema.decodeUnknownEffect(MemoryWrite.Wire)({\n        ...decision,\n        key,\n        operationId: operationId(intent, purpose, attempt),\n        expectedRevision: current?.source.revision ?? null,\n      });\n\n      return yield* save(\n        { _tag: \"Prepared\", proposal, applied, attempt, purpose, command: write },\n        cleanup ? \"cleanup:before\" : \"command:before\",\n        cleanup ? \"cleanup:after\" : \"command:after\",\n      );\n    });\n\n    return yield* run.pipe(\n      Effect.timeoutOrElse({\n        duration: limits.timeoutMillis,\n        orElse: () => Protocol.ProcessingError.make({ reason: \"timeout\" }),\n      }),\n    );\n  });\n\n  return { advance };\n};\n"],"mappings":";;;;;;;;;;;;;;;AAeA,IAAa,SAAb,cAA4B,OAAO,MAAc,kCAAkC,CAAC,CAAC;CACnF,gBAAgB,OAAO,IAAI,MAAM,OAAO,UAAU;EAAE,SAAS;EAAG,SAAS;CAAU,CAAC,CAAC;CACrF,kBAAkB,OAAO,IAAI,MAAM,OAAO,UAAU;EAAE,SAAS;EAAG,SAAS;CAAU,CAAC,CAAC;CACvF,eAAe,OAAO,IAAI,MAAM,OAAO,UAAU;EAAE,SAAS;EAAG,SAAS;CAAQ,CAAC,CAAC;AACpF,CAAC,CAAC,CAAC,CAAC;AAEJ,IAAa,iBAAb,cAAoC,OAAO,MACzC,0CACF,CAAC,CAAC;CACA,QAAQA;CACR,MAAM,OAAO,OAAO,MAAM,OAAO,YAAY,OAAS,CAAC;AACzD,CAAC,CAAC,CAAC,CAAC;AAEJ,MAAM,eAAe,OAAO,OAAO,OAAO,MAAM,CAAC,gBAAgBC,YAAqB,CAAC,CAAC;;;;AAKxF,MAAa,WAAW,OAAO,MAAM;CACnC,OAAO,aAAa,OAAO;EACzB,SAAS,sBAAsB,OAAO;EACtC,SAAS;EACT,QAAQ,OAAO,MAAM,WAAW,CAAC,CAAC,MAAM,OAAO,YAAY,GAAG,CAAC;CACjE,CAAC;CACD,OAAO,aAAa,YAAY,EAAE,QAAQ,OAAO,OAAO,MAAM,OAAO,YAAY,IAAK,CAAC,EAAE,CAAC;CAC1F,OAAO,aAAa,YAAY,CAAC,CAAC;CAClC,OAAO,aAAa,UAAU,CAAC,CAAC;AAClC,CAAC;AAmBD,MAAM,SAAS,MAAe,UAC5B,KAAK,UAAU,IAAI,MAAM,KAAK,UAAU,KAAK;AAE/C,MAAM,WAAW,MAAiB,UAChC,KAAK,OAAO,MAAM,MAAM,KAAK,UAAU,YAAY,MAAM,UAAU;AAErE,MAAM,eAAe,OAAO,WAAA,OAA2B,IAAI;AAE3D,MAAM,iBAAiB,OAAO,GAAG,4BAA4B,CAAC,CAAC,WAC7D,QACA,UACA,QACA;CACA,MAAM,SAAS,OAAO,OAAO,aAAa,cAAc,CAAC,CAAC,QAAQ,CAAC,CAAC,KAClE,OAAO,eAAA,gBAAwC,KAAK,EAAE,QAAQ,gBAAgB,CAAC,CAAC,CAClF;CAEA,MAAM,SAAS,OAAO,OAAO,aAAaD,MAAe,CAAC,CAAC,OAAO,MAAM;CACxE,MAAM,WAAW,OAAO,OAAO,aAAaA,MAAe,CAAC,CAAC,OAAO,MAAM;CAE1E,IAAI,CAAC,MAAM,QAAQ,QAAQ,GACzB,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,iBAAiB,CAAC;CAC1E,IAAI,eAAe,OAAO,IAAI,IAAI,OAAO,gBACvC,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,SAAS,CAAC;CAElE,OAAO;AACT,CAAC;AAED,MAAM,mBAAmB,OAAO,GAAG,8BAA8B,CAAC,CAAC,WACjE,QACA,UACA;CACA,MAAM,QAAQ,SAAS,UAAU,OAAO,IAAI;CAE5C,KAAK,MAAM,YAAY,SAAS,UAAU;EACxC,MAAM,QAAQ,SAAS,UAAU,SAAS,KAAK;EAE/C,IACE,SAAS,OAAO,OAAO,OAAO,OAAO,IAAI,MACzC,SAAS,OAAO,aAAa,OAAO,OAAO,YAC3C,SAAS,OAAO,YAAY,OAAO,OAAO,WAC1C,SAAS,WAAW,SAAS,aAC7B,SAAS,UAAU,MAAM,SAAS,KAClC,MAAM,SAAS,MAAM,SAAS,UAAU,SAAS,aACjD,UAAU,MAAM,MAAM,SAAS,YAAY,GAAG,SAAS,UAAU,CAAC,GAElE,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,mBAAmB,CAAC;CAC9E;AACF,CAAC;AAED,MAAM,qBAAqB,OAAO,GAAG,gCAAgC,CAAC,CAAC,WAIrE,QACA,OAC4E;CAC5E,MAAM,aAAa,OAAO,OAAO,aAAaE,UAAmB,CAAC,CAAC,KAAK,CAAC,CAAC,KACxE,OAAO,eAAA,gBAAwC,KAAK,EAAE,QAAQ,UAAU,CAAC,CAAC,CAC5E;CAEA,IACE,CAAC,MAAM,aAAa,MAAM,GAAG,aAAa,WAAW,MAAM,CAAC,KAC3D,WAAW,gBAAgB,QAAQ,CAAC,QAAQ,WAAW,YAAY,QAAQ,OAAO,OAAO,GAAG,GAE7F,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,UAAU,CAAC;CACnE,MAAM,WAAW,WAAW;CAE5B,IACE,SAAS,SAAS,aAClB,SAAS,YAAY,QACrB,CAAC,QAAQ,SAAS,QAAQ,KAAK,OAAO,MAAM,GAE5C,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,UAAU,CAAC;CACnE,IACE,SAAS,SAAS,eACjB,CAAC,QAAQ,SAAS,QAAQ,KAAK,OAAO,MAAM,KAC3C,SAAS,QAAQ,gBAAgB,YAAY,QAAQ,SAAS,SAAS,SAAS,OAAO,IAEzF,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,UAAU,CAAC;CAEnE,MAAM,UACJ,SAAS,SAAS,aAAa,SAAS,YAAY,OAChD,OACA,OAAO,eAAe,QAAQ,OAAO,OAAO,WAAW,SAAS,OAAO,CAAC,CAAC,KACvE,OAAO,eAAA,gBAAwC,KAAK,EAAE,QAAQ,UAAU,CAAC,CAAC,CAC5E;CAEN,MAAM,gBACJ,SAAS,SAAS,YACd,WACA,SAAS,SAAS,aAChB;EACE,GAAG;EACH;EACA,SAAS,YAAY,KAAK;GAAE,GAAG,SAAS;GAAS,KAAK,OAAO;EAAO,CAAC;CACvE,IACA;EAAE,GAAG;EAAU;CAAQ;CAE/B,MAAM,cACJ,WAAW,gBAAgB,OACvB,OACA,OAAO,OAAO,WAAW,aAAa,EACpC,QAAQ,UAAU,KAAK;EACrB,GAAG,WAAW,YAAY;EAC1B,WAAW,OAAO,OAAO,IAAI;CAC/B,CAAC,EACH,CAAC;CAEP,OAAO,OAAO,OAAO,YAAY;EAAE;EAAQ,UAAU;EAAe;CAAY,CAAC;AACnF,CAAC;AAED,MAAM,eACJ,QACA,SACA,YACW,eAAe,OAAO,GAAG,GAAG,QAAQ,GAAG;AAEpD,MAAM,aACJ,UACA,SACA,SACA,aACuB;CACvB,MAAM;CACN,UAAU,SAAS,SAAS,YAAY,OAAO,SAAS;CACxD,SAAS,SAAS,SAAS,YAAY,IAAI,SAAS;CACpD,SAAS,YAAY,SAAS,SAAS,YAAY,OAAO,SAAS;CACnE;CACA;AACF;;;;AAKA,MAAa,QAAQ,OAAO,GAAG,mBAAmB,CAAC,CAAC,WAClD,OACA,QACA;CACA,MAAM,UAAU,OAAO,OAAO,aAAA,OAA6B,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,KACvE,OAAO,eAAA,eAAuC,KAAK,EAAE,QAAQ,gBAAgB,CAAC,CAAC,CACjF;CAEA,MAAM,YAAY,OAAOC;CAEzB,OAAO,UAAU,IAAI,kBAAkB;CACvC,MAAM,UAAU,OAAO,MAAM,MAAM,OAAO;CAE1C,OAAO,UAAU,IAAI,iBAAiB;CAEtC,OAAO;AACT,CAAC;;;;AAKD,MAAa,aAAa,OAAO,GAAG,wBAAwB,CAAC,CAAC,WAC5D,OACA,OACA;CACA,MAAM,UAAU,OAAO,OAAO,aAAaF,YAAqB,CAAC,CAAC,KAAK,CAAC,CAAC,KACvE,OAAO,eAAA,eAAuC,KAAK,EAAE,QAAQ,gBAAgB,CAAC,CAAC,CACjF;CAEA,MAAM,YAAY,OAAOE;CAEzB,OAAO,UAAU,IAAI,oBAAoB;CACzC,MAAM,UAAU,OAAO,MAAM,WAAW,OAAO;CAE/C,OAAO,UAAU,IAAI,mBAAmB;CAExC,OAAO;AACT,CAAC;;;;;;;;;;;;;;;;;;;;;;AAuBD,MAAa,QAeX,YAaI;CAwQJ,OAAO,EAAE,SAvQO,OAAO,GAAG,qBAAqB,CAAC,CAAC,WAA2B,OAMzE;EACD,MAAM,SAAS,OAAO,OAAO,aAAa,MAAM,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,KAC9D,OAAO,eAAA,gBAAwC,KAAK,EAAE,QAAQ,gBAAgB,CAAC,CAAC,CAClF;EAEA,MAAM,gBAAgB,OAAO,OAAO,oBAAA,OAAoC,IAAI,CAAC,CAC3E,MAAM,MACR,CAAC,CAAC,KAAK,OAAO,eAAA,gBAAwC,KAAK,EAAE,QAAQ,gBAAgB,CAAC,CAAC,CAAC;EAExF,MAAM,SAAgC,OAAO,OAAO,eAAe;GACjE,QAAQ;IACN,GAAG,cAAc;IACjB,KAAK,UAAU,KAAK;KAClB,GAAG,cAAc,OAAO;KACxB,WAAW,MAAM,OAAO,OAAO,IAAI;IACrC,CAAC;GACH;GACA,QAAQ,UAAU,KAAK;IAAE,GAAG,cAAc;IAAQ,WAAW,MAAM,OAAO,OAAO;GAAU,CAAC;EAC9F,CAAC;EAuOD,OAAO,OArOK,OAAO,IAAI,aAAa;GAClC,MAAM,aAAa,OAAO,MAAM,MAC7B,KAAK,MAAM,CAAC,CACZ,KAAK,OAAO,SAAS,UAAU,mBAAmB,QAAQ,KAAK,CAAC,CAAC;GAEpE,MAAM,WAAW,WAAW;GAC5B,MAAM,cAAc,WAAW;GAE/B,IACE,SAAS,SAAS,cAClB,gBAAgB,QAChB,eAAe,KAAK,UAAU,SAAS,QAAQ,CAAC,IAAI,OAAO,kBAE3D,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,SAAS,CAAC;GAClE,MAAM,YAAY,OAAOA;GAEzB,MAAM,OAAO,OAAO,GAAG,kBAAkB,CAAC,CAAC,WACzC,MACA,QACA,OACA;IACA,OAAO,UAAU,IAAI,MAAM;IAE3B,MAAM,SAAS,OAAO,MAAM,MAAM,KAAK;KACrC;KACA,iBAAiB,WAAW;KAC5B,UAAU;IACZ,CAAC;IAED,OAAO,UAAU,IAAI,KAAK;IAE1B,OAAO,OAAO,mBAAmB,QAAQ,MAAM;GACjD,CAAC;GAED,MAAM,WAAW,OAAO,GAAG,sBAAsB,CAAC,CAAC,WAAW,OAA8B;IAC1F,IAAI,CAAC,QAAQ,MAAM,QAAQ,OAAO,OAAO,GAAG,GAC1C,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,gBAAgB,CAAC;IACzE,OAAO,WAAW,MAAM,OAAO,KAAK;IAEpC,OAAO,OAAO,MAAM,MACjB,KAAK,MAAM,CAAC,CACZ,KAAK,OAAO,SAAS,UAAU,mBAAmB,QAAQ,KAAK,CAAC,CAAC;GACtE,CAAC;GAED,IAAI,SAAS,SAAS,gBAAgB,gBAAgB,QAAQ,SAAS,UACrE,OAAO;GACT,IACE,gBAAgB,QAChB,SAAS,SAAS,eACjB,SAAS,SAAS,aAAa,SAAS,YAAY,OAErD,OAAO,OAAO,KACZ,UAAU,UAAU,cAAc,IAAI,GACtC,qBACA,kBACF;GAEF,IAAI,SAAS,SAAS,WAAW;IAC/B,IAAI,CAAC,MAAM,mBACT,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,WAAW,CAAC;IAEpE,MAAM,WAAW,OAAO,QACrB,WAAW,MAAM,CAAC,CAClB,KAAK,OAAO,QAAQ,OAAO,oBAAoB,YAAY,CAAC,CAAC;IAEhE,IAAI,aAAa,MACf,OAAO,OAAO,KACZ,UAAU,UAAU,YAAY,KAAK,GACrC,qBACA,kBACF;IACF,IAAI,OAAO,GAAGF,YAAqB,CAAC,CAAC,QAAQ,GAAG,OAAO,OAAO,SAAS,QAAQ;IAC/E,MAAM,SAAS,OAAO,eAAe,QAAQ,UAAU,MAAM;IAC7D,MAAM,YAAY,OAAO,QAAQ,QAAQ,QAAQ,MAAM;IAEvD,IAAI,cAAc,MAChB,OAAO,OAAO,KACZ,UAAU,UAAU,aAAa,KAAK,GACtC,qBACA,kBACF;IACF,MAAM,QAAQ,OAAO,OAAO,aAAa,QAAQ,QAAQ,CAAC,CAAC,UAAU,KAAK;IAE1E,MAAM,WAAW,OAAO,OAAO,oBAAoBG,QAAiB,CAAC,CAAC;KACpE,SAAS;KACT;KACA,UAAU,UAAU;IACtB,CAAC;IAED,IAAI,eAAe,KAAK,UAAU,QAAQ,CAAC,IAAI,OAAO,kBACpD,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,SAAS,CAAC;IAClE,OAAO,iBAAiB,QAAQ,QAAQ;IAExC,MAAM,SAAS,OAAO,QACnB,WAAW,MAAM,CAAC,CAClB,KAAK,OAAO,QAAQ,OAAO,oBAAoB,YAAY,CAAC,CAAC;IAEhE,IAAI,WAAW,MACb,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,iBAAiB,CAAC;IAC1E,IAAI,OAAO,GAAGH,YAAqB,CAAC,CAAC,MAAM,GAAG,OAAO,OAAO,SAAS,MAAM;IAC3E,OAAO,eAAe,QAAQ,QAAQ,MAAM;IAC5C,IAAI,OAAO,SAAS,OAAO,MACzB,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,iBAAiB,CAAC;IAE1E,OAAO,OAAO,KACZ;KAAE,MAAM;KAAY;KAAU,SAAS;KAAG,SAAS;KAAY,SAAS;IAAK,GAC7E,mBACA,gBACF;GACF;GAEA,IAAI,SAAS,SAAS,YAAY;IAChC,MAAM,SAAS,OAAO;IACtB,MAAM,UAAU,YAAY,KAAK;KAAE,GAAG,SAAS;KAAS,KAAK,OAAO;IAAO,CAAC;IAE5E,MAAM,UAAU,OAAO,OAAO,OAAO,OAAO,CAAC,CAAC,KAC5C,OAAO,KAAK,cAAc;KAAE,MAAM;KAAoB;IAAS,EAAE,GACjE,OAAO,SAAS,wBAAwB,OAAO,QAAQ,EAAE,MAAM,WAAoB,CAAC,CAAC,GACrF,OAAO,SAAS,yBAAyB,OAAO,QAAQ,EAAE,MAAM,YAAqB,CAAC,CAAC,CACzF;IAEA,IAAI,QAAQ,SAAS,WACnB,OAAO,OAAO,KACZ,UACE,UACA,SAAS,YAAY,YAAY,eAAe,WAChD,SAAS,YAAY,WACrB,SAAS,YAAY,aAAa,QAAQ,WAAW,KAAA,CACvD,GACA,qBACA,kBACF;IAEF,IACE,QAAQ,SAAS,eAChB,gBAAgB,QAAQ,SAAS,YAAY,YAE9C,OAAO,OAAO,KACZ,UACE,UACA,gBAAgB,OAAO,eAAe,YACtC,gBAAgB,IAClB,GACA,qBACA,kBACF;IAEF,OAAO,OAAO,KACZ;KACE,MAAM;KACN,UAAU,SAAS;KACnB,SAAS,SAAS;KAClB,SAAS,SAAS;KAClB,SAAS,SAAS;IACpB,GACA,iBACA,cACF;GACF;GAEA,MAAM,WAAW,SAAS;GAE1B,IAAI,aAAa,MAAM,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,UAAU,CAAC;GACxF,IAAI,gBAAgB,MAAM;IACxB,MAAM,SAAS,OAAO,QACnB,WAAW,MAAM,CAAC,CAClB,KAAK,OAAO,QAAQ,OAAO,oBAAoB,YAAY,CAAC,CAAC;IAEhE,IAAI,WAAW,MACb,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,iBAAiB,CAAC;IAC1E,IAAI,OAAO,GAAGA,YAAqB,CAAC,CAAC,MAAM,GAAG,OAAO,OAAO,SAAS,MAAM;IAC3E,OAAO,eAAe,QAAQ,QAAQ,MAAM;IAC5C,OAAO,iBAAiB,QAAQ,QAAQ;GAC1C;GACA,MAAM,QAAQ,OAAO,OAAO,oBAAoB,QAAQ,QAAQ,CAAC,CAAC,SAAS,KAAK;GAEhF,MAAM,UAAU,QAAO,OADD,aAAA,CACQ,IAAI,OAAO,MAAM;GAE/C,MAAM,UACJ,SAAS,YAAY,OACjB,OACA,OAAO,eAAe,QAAQ,OAAO,OAAO,WAAW,SAAS,OAAO;GAE7E,MAAM,UAAU,gBAAgB,QAAQ,YAAY;GACpD,MAAM,aAAa;IAAE;IAAQ,UAAU;KAAE;KAAO,UAAU,SAAS;IAAS;IAAG;GAAQ;GAEvF,MAAM,YAAY,UACd,OAAO,QAAQ,QAAQ;IAAE,GAAG;IAAY;IAAa;GAAQ,CAAC,IAC9D,OAAO,QAAQ,MAAM,UAAU;GAEnC,MAAM,WAAW,OAAO,OAAO,aAAa,QAAQ,CAAC,CAAC,SAAS;GAE/D,IAAI,WAAW,SAAS,SAAS,UAC/B,OAAO,OAAA,gBAAgC,KAAK,EAAE,QAAQ,mBAAmB,CAAC;GAC5E,IAAI,SAAS,SAAS,cAAc,SAAS,SAAS,UACpD,OAAO,OAAO,KACZ,UACE,UACA,UAAU,eAAe,SAAS,SAAS,WAAW,aAAa,aACnE,SACA,CAAC,WAAW,SAAS,SAAS,cAAc,YAAY,OAAO,UAAU,KAAA,CAC3E,GACA,UAAU,mBAAmB,qBAC7B,UAAU,kBAAkB,kBAC9B;GACF,IAAI,SAAS,SAAS,cAAc,YAAY,MAC9C,OAAO,OAAO,KACZ,UAAU,UAAU,UAAU,eAAe,aAAa,OAAO,GACjE,qBACA,kBACF;GACF,MAAM,UAAU,UAAU,YAAY;GACtC,MAAM,UAAU,SAAS,UAAU;GACnC,MAAM,MAAM,OAAO;GASnB,OAAO,OAAO,KACZ;IAAE,MAAM;IAAY;IAAU;IAAS;IAAS;IAAS,SAAS,OAR/C,OAAO,oBAAoB,YAAY,IAAI,CAAC,CAAC;KAChE,GAAG;KACH;KACA,aAAa,YAAY,QAAQ,SAAS,OAAO;KACjD,kBAAkB,SAAS,OAAO,YAAY;IAChD,CAAC;GAGyE,GACxE,UAAU,mBAAmB,kBAC7B,UAAU,kBAAkB,eAC9B;EACF,CAEgB,CAAC,CAAC,KAChB,OAAO,cAAc;GACnB,UAAU,OAAO;GACjB,cAAA,gBAAuC,KAAK,EAAE,QAAQ,UAAU,CAAC;EACnE,CAAC,CACH;CACF,CAEe,EAAE;AACnB"}

package/dist/capabilities/RunHooks.d.mts

@@ -0,0 +1,82 @@
+import { c as ThreadLimitExceeded, i as ThreadEncodingError, s as ThreadHistoryDiverged, t as Store, u as ThreadNotFound } from "../Thread-DOBQ0QUY.mjs";
+import { RedactionError, Redactor } from "./Redaction.mjs";
+import { ApprovalAudit, ApprovalAuditLimitExceeded, ApprovalDecisionMismatch, ApprovalRequestDraft, ApprovalResolver, ApprovalResolverError } from "./Approval.mjs";
+import { BudgetExceeded, UsageBudgetNode } from "./Budget.mjs";
+import { M as RunOptions, R as RunSchedulingHook, _ as RunBudgetHook, b as RunContextHook, g as RunApprovalRequest, h as RunApprovalHook, j as RunInputHook, w as RunContextRequest } from "../RunOptions-g1aigcKI.mjs";
+import { RunCommandQueue } from "./Commands.mjs";
+import { Prompt } from "effect/unstable/ai";
+import { Effect, Schema } from "effect";
+declare namespace RunHooks_d_exports {
+  export { ApprovalAdapterError, BudgetAdapterError, EnginePromptTransform, RunApprovalAdapterPolicy, RunApprovalAdapterPolicySchema, ThreadAdapterError, toDurableRunApprovalHook, toRunApprovalHook, toRunBudgetHook, toRunContextHook, toRunInputHook, toRunSchedulingHook, toRunThreadOptions };
+}
+declare const ApprovalAdapterError_base: Schema.Class<ApprovalAdapterError, Schema.TaggedStruct<"ApprovalAdapterError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Capability policy could not be normalized into the bounded approval request Schema. */
+declare class ApprovalAdapterError extends ApprovalAdapterError_base {}
+declare const BudgetAdapterError_base: Schema.Class<BudgetAdapterError, Schema.TaggedStruct<"BudgetAdapterError", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Engine usage data did not satisfy the non-negative budget delta Schema. */
+declare class BudgetAdapterError extends BudgetAdapterError_base {}
+/** Adapt the richer audited FIFO commands to the engine's safe-seam input hook. */
+declare const toRunInputHook: (queue: RunCommandQueue) => RunInputHook<never, never>;
+/** Explicit policy needed to turn a native Effect AI approval request into an audit request. */
+interface RunApprovalAdapterPolicy {
+  readonly expiresInMillis: number;
+  readonly risk: ApprovalRequestDraft["risk"];
+  readonly denial: ApprovalRequestDraft["denial"];
+  readonly actionSummary: (request: RunApprovalRequest) => string;
+  readonly resourceTargets: (request: RunApprovalRequest) => ReadonlyArray<string>;
+}
+/** Adapt native Effect AI approval parts through structural redaction, audit, and timeout policy. */
+declare const toRunApprovalHook: (policy: RunApprovalAdapterPolicy) => RunApprovalHook<ApprovalResolverError | ApprovalAuditLimitExceeded | ApprovalDecisionMismatch | ApprovalAdapterError | RedactionError, ApprovalResolver | ApprovalAudit | Redactor>;
+/**
+ * Durable variant of `toRunApprovalHook` (P5 plan §2.6): the durable coordinator consults this
+ * delegate for policy-AUTO decisions only, after its recorded-decision lookup misses. It reuses
+ * the exact P2 approval stack — `ApprovalRequestDraft` policy metadata, structural redaction,
+ * audit sink, expiry/timeout policy — but differs in two durable-specific ways:
+ *
+ * 1. The capability services (`ApprovalResolver | ApprovalAudit | Redactor`) are captured up
+ *    front, so the returned hook is `RunApprovalHook<never, never>` — the shape the
+ *    coordinator's `DurableApprovalResolver` reference accepts without leaking capability
+ *    requirements into the durable runtime Layer.
+ * 2. It FAILS CLOSED into `unresolved`: any adapter, audit, redaction, or resolver failure
+ *    defers the decision to the durable suspension + `resolveApproval` path instead of
+ *    approving, denying, or crashing the Attempt on a transient policy fault. Explicit
+ *    policy denials (including the P2 timeout-denial for `denial: "terminal"`) still deny.
+ */
+declare const toDurableRunApprovalHook: (policy: RunApprovalAdapterPolicy) => Effect.Effect<RunApprovalHook<never, never>, never, ApprovalAudit | ApprovalResolver | Redactor>;
+/** Adapt one hierarchical budget node to the engine's usage accounting seam. */
+declare const toRunBudgetHook: (budget: UsageBudgetNode) => RunBudgetHook<BudgetExceeded | BudgetAdapterError, never>;
+type ThreadAdapterError = ThreadNotFound | ThreadLimitExceeded | ThreadEncodingError | ThreadHistoryDiverged;
+/**
+ * Advanced integration for an existing Thread.Store snapshot. Ordinary Runs automatically
+ * retain history through ThreadHistory.layer; use this helper only for explicit snapshot hooks.
+ * Share that Layer's Thread.Store owner. PersistentHistory rejects these competing hooks.
+ * The snapshot is explicit initial Prompt data. Each inline onHistory call immediately records
+ * its append-only suffix, including updates from Runs that later fail or are interrupted. Writes
+ * already made remain in the snapshot. Callback errors stop the Run as ThreadAdapterError;
+ * snapshot lookup can fail with ThreadNotFound before execution.
+ * Native Effect AI parts and provider options are preserved without a role/text projection.
+ * For retaining only successful Runs, provide ThreadHistory through PersistentHistory.layer
+ * with a memory or SQLite store instead. This adapter does not provide durable recovery.
+ */
+declare const toRunThreadOptions: (threadId: string & import("effect/Brand").Brand<"@effect-agent/core/ThreadId">, runId: string & import("effect/Brand").Brand<"@effect-agent/core/RunId">) => Effect.Effect<Pick<RunOptions<ThreadAdapterError, never>, "history" | "onHistory" | "threadId">, ThreadNotFound, Store>;
+/** Prompt transform used by the adapter; the engine retains the authoritative source separately. */
+interface EnginePromptTransform<Error = never, Requirements = never> {
+  readonly prepare: (source: Prompt.Prompt, request: RunContextRequest) => Effect.Effect<Prompt.Prompt, Error, Requirements>;
+}
+/** Adapt a prompt-only context transform without granting it authority over engine source history. */
+declare const toRunContextHook: <Error, Requirements>(transform: EnginePromptTransform<Error, Requirements>) => RunContextHook<Error, Requirements>;
+/** Scheduling values are structurally aligned and only reduce finite concurrency. */
+declare const toRunSchedulingHook: (runOverride: RunSchedulingHook["runOverride"], toolRequiresSequential?: (toolName: string) => boolean) => RunSchedulingHook;
+/** Validate policy configuration at adapter construction boundaries. */
+declare const RunApprovalAdapterPolicySchema: Schema.Struct<{
+  readonly expiresInMillis: Schema.Int;
+  readonly risk: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
+  readonly denial: Schema.Literals<readonly ["terminal", "recoverable"]>;
+}>;
+//#endregion
+export { ApprovalAdapterError, BudgetAdapterError, EnginePromptTransform, RunApprovalAdapterPolicy, RunApprovalAdapterPolicySchema, ThreadAdapterError, RunHooks_d_exports as t, toDurableRunApprovalHook, toRunApprovalHook, toRunBudgetHook, toRunContextHook, toRunInputHook, toRunSchedulingHook, toRunThreadOptions };
+//# sourceMappingURL=RunHooks.d.mts.map

package/dist/capabilities/RunHooks.mjs

@@ -0,0 +1,144 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { Store, toPrompt } from "../core/Thread.mjs";
+import { ApprovalRequestDraft, makeApprovalRequest, requestApproval } from "./Approval.mjs";
+import { UsageDelta } from "./Budget.mjs";
+import { Clock, DateTime, Effect, Schema } from "effect";
+//#region src/capabilities/RunHooks.ts
+var RunHooks_exports = /* @__PURE__ */ __exportAll({
+	ApprovalAdapterError: () => ApprovalAdapterError,
+	BudgetAdapterError: () => BudgetAdapterError,
+	RunApprovalAdapterPolicySchema: () => RunApprovalAdapterPolicySchema,
+	toDurableRunApprovalHook: () => toDurableRunApprovalHook,
+	toRunApprovalHook: () => toRunApprovalHook,
+	toRunBudgetHook: () => toRunBudgetHook,
+	toRunContextHook: () => toRunContextHook,
+	toRunInputHook: () => toRunInputHook,
+	toRunSchedulingHook: () => toRunSchedulingHook,
+	toRunThreadOptions: () => toRunThreadOptions
+});
+/** Capability policy could not be normalized into the bounded approval request Schema. */
+var ApprovalAdapterError = class extends Schema.TaggedError()("ApprovalAdapterError", { message: Schema.String }) {};
+/** Engine usage data did not satisfy the non-negative budget delta Schema. */
+var BudgetAdapterError = class extends Schema.TaggedError()("BudgetAdapterError", { message: Schema.String }) {};
+/** Adapt the richer audited FIFO commands to the engine's safe-seam input hook. */
+const toRunInputHook = (queue) => ({
+	drain: (policy) => queue.drain(policy).pipe(Effect.map((commands) => commands.map((command) => ({
+		kind: command._tag === "SteeringCommand" ? "steering" : "follow-up",
+		input: command.content
+	})))),
+	end: () => queue.shutdown
+});
+/** Adapt native Effect AI approval parts through structural redaction, audit, and timeout policy. */
+const toRunApprovalHook = (policy) => ({ request: (engineRequest) => Effect.gen(function* () {
+	const validatedPolicy = yield* Schema.decodeEffect(RunApprovalAdapterPolicySchema)(policy).pipe(Effect.mapError((error) => ApprovalAdapterError.make({ message: `Approval adapter policy is invalid: ${error.message}` })));
+	const now = yield* Clock.currentTimeMillis;
+	const metadata = yield* Effect.try({
+		try: () => ({
+			actionSummary: policy.actionSummary(engineRequest),
+			resourceTargets: policy.resourceTargets(engineRequest)
+		}),
+		catch: () => ApprovalAdapterError.make({ message: "Approval policy failed while describing the native Tool request" })
+	});
+	const draft = yield* Schema.decodeEffect(ApprovalRequestDraft)({
+		requestId: engineRequest.request.approvalId,
+		runId: engineRequest.runId,
+		threadId: engineRequest.threadId,
+		toolCallId: engineRequest.toolCallId,
+		toolName: engineRequest.toolName,
+		actionSummary: metadata.actionSummary,
+		resourceTargets: metadata.resourceTargets,
+		risk: validatedPolicy.risk,
+		expiresAt: DateTime.formatIso(DateTime.toUtc(DateTime.makeUnsafe(now + validatedPolicy.expiresInMillis))),
+		denial: validatedPolicy.denial
+	}).pipe(Effect.mapError((error) => ApprovalAdapterError.make({ message: `Approval adapter policy is invalid: ${error.message}` })));
+	const request = yield* makeApprovalRequest(draft, engineRequest.parameters);
+	const decision = yield* requestApproval(request);
+	if (decision._tag === "ApprovalApproved") return { _tag: "approved" };
+	if (decision.timedOut && request.denial === "recoverable") return {
+		_tag: "unresolved",
+		reason: decision.reason
+	};
+	return {
+		_tag: "denied",
+		reason: decision.reason
+	};
+}) });
+/**
+* Durable variant of `toRunApprovalHook` (P5 plan §2.6): the durable coordinator consults this
+* delegate for policy-AUTO decisions only, after its recorded-decision lookup misses. It reuses
+* the exact P2 approval stack — `ApprovalRequestDraft` policy metadata, structural redaction,
+* audit sink, expiry/timeout policy — but differs in two durable-specific ways:
+*
+* 1. The capability services (`ApprovalResolver | ApprovalAudit | Redactor`) are captured up
+*    front, so the returned hook is `RunApprovalHook<never, never>` — the shape the
+*    coordinator's `DurableApprovalResolver` reference accepts without leaking capability
+*    requirements into the durable runtime Layer.
+* 2. It FAILS CLOSED into `unresolved`: any adapter, audit, redaction, or resolver failure
+*    defers the decision to the durable suspension + `resolveApproval` path instead of
+*    approving, denying, or crashing the Attempt on a transient policy fault. Explicit
+*    policy denials (including the P2 timeout-denial for `denial: "terminal"`) still deny.
+*/
+const toDurableRunApprovalHook = Effect.fn("toDurableRunApprovalHook")(function* (policy) {
+	const services = yield* Effect.context();
+	const hook = toRunApprovalHook(policy);
+	return { request: (request) => hook.request(request).pipe(Effect.provideContext(services), Effect.catch((error) => Effect.succeed({
+		_tag: "unresolved",
+		reason: `Approval delegation failed (${error._tag}); the decision defers to the durable resolveApproval path`
+	}))) };
+});
+/** Adapt one hierarchical budget node to the engine's usage accounting seam. */
+const toRunBudgetHook = (budget) => ({
+	guard: budget.guard,
+	consume: (delta) => Schema.decodeEffect(UsageDelta)({
+		modelCalls: delta.modelCalls,
+		inputTokens: delta.inputTokens,
+		outputTokens: delta.outputTokens,
+		cacheReadInputTokens: Math.max(0, delta.usage.inputTokens.cacheRead ?? 0),
+		cacheWriteInputTokens: Math.max(0, delta.usage.inputTokens.cacheWrite ?? 0),
+		toolCalls: delta.toolCalls,
+		costMicrousd: delta.costMicrousd
+	}).pipe(Effect.mapError((error) => BudgetAdapterError.make({ message: `Engine usage delta is invalid: ${error.message}` })), Effect.flatMap((usage) => budget.consume(usage)), Effect.asVoid)
+});
+/**
+* Advanced integration for an existing Thread.Store snapshot. Ordinary Runs automatically
+* retain history through ThreadHistory.layer; use this helper only for explicit snapshot hooks.
+* Share that Layer's Thread.Store owner. PersistentHistory rejects these competing hooks.
+* The snapshot is explicit initial Prompt data. Each inline onHistory call immediately records
+* its append-only suffix, including updates from Runs that later fail or are interrupted. Writes
+* already made remain in the snapshot. Callback errors stop the Run as ThreadAdapterError;
+* snapshot lookup can fail with ThreadNotFound before execution.
+* Native Effect AI parts and provider options are preserved without a role/text projection.
+* For retaining only successful Runs, provide ThreadHistory through PersistentHistory.layer
+* with a memory or SQLite store instead. This adapter does not provide durable recovery.
+*/
+const toRunThreadOptions = Effect.fn("toRunThreadOptions")(function* (threadId, runId) {
+	const threads = yield* Store;
+	const snapshot = yield* threads.snapshot(threadId);
+	return {
+		threadId,
+		history: toPrompt(snapshot),
+		onHistory: (history) => threads.recordHistory(threadId, runId, history).pipe(Effect.asVoid)
+	};
+});
+/** Adapt a prompt-only context transform without granting it authority over engine source history. */
+const toRunContextHook = (transform) => ({ prepare: (request) => transform.prepare(request.source, request).pipe(Effect.map((prompt) => ({ prompt }))) });
+/** Scheduling values are structurally aligned and only reduce finite concurrency. */
+const toRunSchedulingHook = (runOverride, toolRequiresSequential) => ({
+	runOverride,
+	...toolRequiresSequential === void 0 ? {} : { toolRequiresSequential }
+});
+/** Validate policy configuration at adapter construction boundaries. */
+const RunApprovalAdapterPolicySchema = Schema.Struct({
+	expiresInMillis: Schema.Int.check(Schema.isGreaterThan(0)),
+	risk: Schema.Literals([
+		"low",
+		"medium",
+		"high",
+		"critical"
+	]),
+	denial: Schema.Literals(["terminal", "recoverable"])
+});
+//#endregion
+export { ApprovalAdapterError, BudgetAdapterError, RunApprovalAdapterPolicySchema, RunHooks_exports as t, toDurableRunApprovalHook, toRunApprovalHook, toRunBudgetHook, toRunContextHook, toRunInputHook, toRunSchedulingHook, toRunThreadOptions };
+
+//# sourceMappingURL=RunHooks.mjs.map

package/dist/capabilities/RunHooks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunHooks.mjs","names":["ConversationStore"],"sources":["../../src/capabilities/RunHooks.ts"],"sourcesContent":["import { Clock, DateTime, Effect, Schema } from \"effect\";\nimport type { Prompt } from \"effect/unstable/ai\";\n\nimport {\n  type ThreadEncodingError,\n  type ThreadHistoryDiverged,\n  type ThreadLimitExceeded,\n  type ThreadNotFound,\n  toPrompt,\n  Store as ConversationStore,\n} from \"../core/Thread.ts\";\nimport {\n  type PreparedRunContext,\n  type RunApprovalDecision,\n  type RunApprovalHook,\n  type RunApprovalRequest,\n  type RunBudgetHook,\n  type RunContextHook,\n  type RunContextRequest,\n  type RunInputHook,\n  type RunOptions,\n  type RunSchedulingHook,\n} from \"../engine/RunOptions.ts\";\nimport {\n  type ApprovalAudit,\n  type ApprovalAuditLimitExceeded,\n  type ApprovalDecisionMismatch,\n  ApprovalRequestDraft,\n  type ApprovalResolver,\n  type ApprovalResolverError,\n  makeApprovalRequest,\n  requestApproval,\n} from \"./Approval.ts\";\nimport { type BudgetExceeded, UsageDelta, type UsageBudgetNode } from \"./Budget.ts\";\nimport type { RunCommandQueue } from \"./Commands.ts\";\nimport type { RedactionError, Redactor } from \"./Redaction.ts\";\n\n/** Capability policy could not be normalized into the bounded approval request Schema. */\nexport class ApprovalAdapterError extends Schema.TaggedError<ApprovalAdapterError>()(\n  \"ApprovalAdapterError\",\n  { message: Schema.String },\n) {}\n\n/** Engine usage data did not satisfy the non-negative budget delta Schema. */\nexport class BudgetAdapterError extends Schema.TaggedError<BudgetAdapterError>()(\n  \"BudgetAdapterError\",\n  { message: Schema.String },\n) {}\n\n/** Adapt the richer audited FIFO commands to the engine's safe-seam input hook. */\nexport const toRunInputHook = (queue: RunCommandQueue): RunInputHook<never, never> => ({\n  drain: (policy) =>\n    queue.drain(policy).pipe(\n      Effect.map((commands) =>\n        commands.map((command) => ({\n          kind: command._tag === \"SteeringCommand\" ? (\"steering\" as const) : (\"follow-up\" as const),\n          input: command.content,\n        })),\n      ),\n    ),\n  end: () => queue.shutdown,\n});\n\n/** Explicit policy needed to turn a native Effect AI approval request into an audit request. */\nexport interface RunApprovalAdapterPolicy {\n  readonly expiresInMillis: number;\n  readonly risk: ApprovalRequestDraft[\"risk\"];\n  readonly denial: ApprovalRequestDraft[\"denial\"];\n  readonly actionSummary: (request: RunApprovalRequest) => string;\n  readonly resourceTargets: (request: RunApprovalRequest) => ReadonlyArray<string>;\n}\n\n/** Adapt native Effect AI approval parts through structural redaction, audit, and timeout policy. */\nexport const toRunApprovalHook = (\n  policy: RunApprovalAdapterPolicy,\n): RunApprovalHook<\n  | ApprovalResolverError\n  | ApprovalAuditLimitExceeded\n  | ApprovalDecisionMismatch\n  | ApprovalAdapterError\n  | RedactionError,\n  ApprovalResolver | ApprovalAudit | Redactor\n> => ({\n  request: (engineRequest) =>\n    Effect.gen(function* () {\n      const validatedPolicy = yield* Schema.decodeEffect(RunApprovalAdapterPolicySchema)(\n        policy,\n      ).pipe(\n        Effect.mapError((error) =>\n          ApprovalAdapterError.make({\n            message: `Approval adapter policy is invalid: ${error.message}`,\n          }),\n        ),\n      );\n\n      const now = yield* Clock.currentTimeMillis;\n\n      const metadata = yield* Effect.try({\n        try: () => ({\n          actionSummary: policy.actionSummary(engineRequest),\n          resourceTargets: policy.resourceTargets(engineRequest),\n        }),\n        catch: () =>\n          ApprovalAdapterError.make({\n            message: \"Approval policy failed while describing the native Tool request\",\n          }),\n      });\n\n      const draft = yield* Schema.decodeEffect(ApprovalRequestDraft)({\n        requestId: engineRequest.request.approvalId,\n        runId: engineRequest.runId,\n        threadId: engineRequest.threadId,\n        toolCallId: engineRequest.toolCallId,\n        toolName: engineRequest.toolName,\n        actionSummary: metadata.actionSummary,\n        resourceTargets: metadata.resourceTargets,\n        risk: validatedPolicy.risk,\n        expiresAt: DateTime.formatIso(\n          DateTime.toUtc(DateTime.makeUnsafe(now + validatedPolicy.expiresInMillis)),\n        ),\n        denial: validatedPolicy.denial,\n      }).pipe(\n        Effect.mapError((error) =>\n          ApprovalAdapterError.make({\n            message: `Approval adapter policy is invalid: ${error.message}`,\n          }),\n        ),\n      );\n\n      const request = yield* makeApprovalRequest(draft, engineRequest.parameters);\n      const decision = yield* requestApproval(request);\n\n      if (decision._tag === \"ApprovalApproved\") {\n        return { _tag: \"approved\" as const };\n      }\n      if (decision.timedOut && request.denial === \"recoverable\") {\n        return {\n          _tag: \"unresolved\" as const,\n          reason: decision.reason,\n        };\n      }\n\n      return {\n        _tag: \"denied\" as const,\n        reason: decision.reason,\n      };\n    }),\n});\n\n/**\n * Durable variant of `toRunApprovalHook` (P5 plan §2.6): the durable coordinator consults this\n * delegate for policy-AUTO decisions only, after its recorded-decision lookup misses. It reuses\n * the exact P2 approval stack — `ApprovalRequestDraft` policy metadata, structural redaction,\n * audit sink, expiry/timeout policy — but differs in two durable-specific ways:\n *\n * 1. The capability services (`ApprovalResolver | ApprovalAudit | Redactor`) are captured up\n *    front, so the returned hook is `RunApprovalHook<never, never>` — the shape the\n *    coordinator's `DurableApprovalResolver` reference accepts without leaking capability\n *    requirements into the durable runtime Layer.\n * 2. It FAILS CLOSED into `unresolved`: any adapter, audit, redaction, or resolver failure\n *    defers the decision to the durable suspension + `resolveApproval` path instead of\n *    approving, denying, or crashing the Attempt on a transient policy fault. Explicit\n *    policy denials (including the P2 timeout-denial for `denial: \"terminal\"`) still deny.\n */\nexport const toDurableRunApprovalHook = Effect.fn(\"toDurableRunApprovalHook\")(function* (\n  policy: RunApprovalAdapterPolicy,\n): Effect.fn.Return<\n  RunApprovalHook<never, never>,\n  never,\n  ApprovalResolver | ApprovalAudit | Redactor\n> {\n  const services = yield* Effect.context<ApprovalResolver | ApprovalAudit | Redactor>();\n  const hook = toRunApprovalHook(policy);\n\n  return {\n    request: (request) =>\n      hook.request(request).pipe(\n        Effect.provideContext(services),\n        Effect.catch((error) =>\n          Effect.succeed<RunApprovalDecision>({\n            _tag: \"unresolved\",\n            reason: `Approval delegation failed (${error._tag}); the decision defers to the durable resolveApproval path`,\n          }),\n        ),\n      ),\n  };\n});\n\n/** Adapt one hierarchical budget node to the engine's usage accounting seam. */\nexport const toRunBudgetHook = (\n  budget: UsageBudgetNode,\n): RunBudgetHook<BudgetExceeded | BudgetAdapterError, never> => ({\n  guard: budget.guard,\n  consume: (delta) =>\n    Schema.decodeEffect(UsageDelta)({\n      modelCalls: delta.modelCalls,\n      inputTokens: delta.inputTokens,\n      outputTokens: delta.outputTokens,\n      cacheReadInputTokens: Math.max(0, delta.usage.inputTokens.cacheRead ?? 0),\n      cacheWriteInputTokens: Math.max(0, delta.usage.inputTokens.cacheWrite ?? 0),\n      toolCalls: delta.toolCalls,\n      costMicrousd: delta.costMicrousd,\n    }).pipe(\n      Effect.mapError((error) =>\n        BudgetAdapterError.make({\n          message: `Engine usage delta is invalid: ${error.message}`,\n        }),\n      ),\n      Effect.flatMap((usage) => budget.consume(usage)),\n      Effect.asVoid,\n    ),\n});\n\nexport type ThreadAdapterError =\n  | ThreadNotFound\n  | ThreadLimitExceeded\n  | ThreadEncodingError\n  | ThreadHistoryDiverged;\n\n/**\n * Advanced integration for an existing Thread.Store snapshot. Ordinary Runs automatically\n * retain history through ThreadHistory.layer; use this helper only for explicit snapshot hooks.\n * Share that Layer's Thread.Store owner. PersistentHistory rejects these competing hooks.\n * The snapshot is explicit initial Prompt data. Each inline onHistory call immediately records\n * its append-only suffix, including updates from Runs that later fail or are interrupted. Writes\n * already made remain in the snapshot. Callback errors stop the Run as ThreadAdapterError;\n * snapshot lookup can fail with ThreadNotFound before execution.\n * Native Effect AI parts and provider options are preserved without a role/text projection.\n * For retaining only successful Runs, provide ThreadHistory through PersistentHistory.layer\n * with a memory or SQLite store instead. This adapter does not provide durable recovery.\n */\nexport const toRunThreadOptions = Effect.fn(\"toRunThreadOptions\")(function* (\n  threadId: import(\"../core/Identifiers.ts\").ThreadId,\n  runId: import(\"../core/Identifiers.ts\").RunId,\n): Effect.fn.Return<\n  Pick<RunOptions<ThreadAdapterError>, \"threadId\" | \"history\" | \"onHistory\">,\n  ThreadNotFound,\n  ConversationStore\n> {\n  const threads = yield* ConversationStore;\n  const snapshot = yield* threads.snapshot(threadId);\n\n  return {\n    threadId,\n    history: toPrompt(snapshot),\n    onHistory: (history) => threads.recordHistory(threadId, runId, history).pipe(Effect.asVoid),\n  };\n});\n\n/** Prompt transform used by the adapter; the engine retains the authoritative source separately. */\nexport interface EnginePromptTransform<Error = never, Requirements = never> {\n  readonly prepare: (\n    source: Prompt.Prompt,\n    request: RunContextRequest,\n  ) => Effect.Effect<Prompt.Prompt, Error, Requirements>;\n}\n\n/** Adapt a prompt-only context transform without granting it authority over engine source history. */\nexport const toRunContextHook = <Error, Requirements>(\n  transform: EnginePromptTransform<Error, Requirements>,\n): RunContextHook<Error, Requirements> => ({\n  prepare: (request): Effect.Effect<PreparedRunContext, Error, Requirements> =>\n    transform.prepare(request.source, request).pipe(Effect.map((prompt) => ({ prompt }))),\n});\n\n/** Scheduling values are structurally aligned and only reduce finite concurrency. */\nexport const toRunSchedulingHook = (\n  runOverride: RunSchedulingHook[\"runOverride\"],\n  toolRequiresSequential?: (toolName: string) => boolean,\n): RunSchedulingHook => ({\n  runOverride,\n  ...(toolRequiresSequential === undefined ? {} : { toolRequiresSequential }),\n});\n\n/** Validate policy configuration at adapter construction boundaries. */\nexport const RunApprovalAdapterPolicySchema = Schema.Struct({\n  expiresInMillis: Schema.Int.check(Schema.isGreaterThan(0)),\n  risk: Schema.Literals([\"low\", \"medium\", \"high\", \"critical\"]),\n  denial: Schema.Literals([\"terminal\", \"recoverable\"]),\n});\n"],"mappings":"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"}