effect-agent 0.1.0-beta.9 → 0.1.0-beta.90

package/dist/core/SemanticMemoryIndex.mjs

@@ -0,0 +1,185 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { MemoryPassage } from "./MemoryReference.mjs";
+import { equals } from "./MemoryNamespace.mjs";
+import { ActiveMemoryDocument, MemoryKey } from "./MemoryStore.mjs";
+import { Context, Effect, Schema } from "effect";
+//#region src/core/SemanticMemoryIndex.ts
+var SemanticMemoryIndex_exports = /* @__PURE__ */ __exportAll({
+	MemoryIndexCandidate: () => MemoryIndexCandidate,
+	MemoryIndexError: () => MemoryIndexError,
+	MemoryIndexQuery: () => MemoryIndexQuery,
+	MemoryIndexReplacement: () => MemoryIndexReplacement,
+	MemoryIndexSearch: () => MemoryIndexSearch,
+	MemoryIndexSource: () => MemoryIndexSource,
+	SemanticMemoryChunk: () => SemanticMemoryChunk,
+	SemanticMemoryIndex: () => SemanticMemoryIndex,
+	SemanticMemoryProfile: () => SemanticMemoryProfile
+});
+const Identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+const Positive = Schema.Int.check(Schema.isBetween({
+	minimum: 1,
+	maximum: Number.MAX_SAFE_INTEGER
+}));
+const Timestamp = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));
+const Vector = Schema.Array(Schema.Finite).check(Schema.isMinLength(1), Schema.isMaxLength(4096));
+/** A host declaration of the exact embedding space and deterministic chunking policy. */
+var SemanticMemoryProfile = class extends Schema.Class("@effect-agent/core/SemanticMemoryProfile")({
+	version: Schema.Literal(1),
+	provider: Identity,
+	model: Identity,
+	modelRevision: Identity,
+	dimensions: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 4096
+	})),
+	chunker: Schema.Literal("utf8-codepoint@1"),
+	maxChunkBytes: Schema.Int.check(Schema.isBetween({
+		minimum: 4,
+		maximum: 8192
+	})),
+	distance: Schema.Literal("cosine")
+}) {};
+var SemanticMemoryChunk = class extends Schema.Class("@effect-agent/core/SemanticMemoryChunk")({
+	passageId: MemoryPassage.fields.passageId,
+	ordinal: Schema.Int.check(Schema.isBetween({
+		minimum: 0,
+		maximum: 255
+	})),
+	startByte: Schema.Natural,
+	endByte: Schema.Natural,
+	text: Schema.NonEmptyString.check(Schema.isMaxLength(8192)),
+	vector: Vector
+}) {};
+const SourceFields = {
+	key: MemoryKey.Wire,
+	source: ActiveMemoryDocument.Wire.fields.source,
+	sourceGeneration: Positive
+};
+var MemoryIndexSourceWire = class extends Schema.Class("@effect-agent/core/MemoryIndexSource")(SourceFields) {};
+const MemoryIndexSource = {
+	Wire: MemoryIndexSourceWire,
+	make: (fields) => Object.assign(Schema.decodeUnknownSync(MemoryIndexSourceWire)(fields), { key: MemoryKey.make(fields.key) })
+};
+/** A complete replacement, prepared before touching the disposable index. */
+var MemoryIndexReplacementWire = class extends Schema.Class("@effect-agent/core/MemoryIndexReplacement")({
+	source: MemoryIndexSource.Wire,
+	profile: SemanticMemoryProfile,
+	chunks: Schema.Array(SemanticMemoryChunk).check(Schema.isMinLength(1), Schema.isMaxLength(256))
+}) {};
+const MemoryIndexReplacement = {
+	Wire: MemoryIndexReplacementWire,
+	make: (fields) => Object.assign(Schema.decodeUnknownSync(MemoryIndexReplacementWire)(fields), { source: fields.source })
+};
+var MemoryIndexCandidateWire = class extends Schema.Class("@effect-agent/core/MemoryIndexCandidate")({
+	...SourceFields,
+	passageId: SemanticMemoryChunk.fields.passageId,
+	ordinal: SemanticMemoryChunk.fields.ordinal,
+	startByte: SemanticMemoryChunk.fields.startByte,
+	endByte: SemanticMemoryChunk.fields.endByte,
+	text: SemanticMemoryChunk.fields.text,
+	score: Schema.Finite.check(Schema.isBetween({
+		minimum: -1,
+		maximum: 1
+	})),
+	indexedAt: Timestamp
+}) {};
+const MemoryIndexCandidate = {
+	Wire: MemoryIndexCandidateWire,
+	make: (fields) => Object.assign(Schema.decodeUnknownSync(MemoryIndexCandidateWire)(fields), { key: MemoryKey.make(fields.key) })
+};
+var MemoryIndexQueryWire = class extends Schema.Class("@effect-agent/core/MemoryIndexQuery")({
+	namespace: MemoryKey.Wire.fields.namespace,
+	vector: Vector,
+	limit: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 128
+	})),
+	minScore: Schema.Finite.check(Schema.isBetween({
+		minimum: -1,
+		maximum: 1
+	})),
+	maxScannedChunks: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 65536
+	}))
+}) {};
+const MemoryIndexQuery = {
+	Wire: MemoryIndexQueryWire,
+	make: (fields) => Object.assign(Schema.decodeUnknownSync(MemoryIndexQueryWire)(fields), { namespace: fields.namespace })
+};
+var MemoryIndexSearchWire = class extends Schema.Class("@effect-agent/core/MemoryIndexSearch")({
+	candidates: Schema.Array(MemoryIndexCandidate.Wire).check(Schema.isMaxLength(128)),
+	scannedChunks: Schema.Natural
+}) {};
+const MemoryIndexSearch = {
+	Wire: MemoryIndexSearchWire,
+	make: (fields) => Object.assign(Schema.decodeUnknownSync(MemoryIndexSearchWire)(fields), { candidates: fields.candidates })
+};
+var MemoryIndexError = class extends Schema.TaggedError()("MemoryIndexError", {
+	operation: Identity,
+	reason: Schema.Literals([
+		"invalid-input",
+		"unavailable",
+		"corrupt",
+		"incompatible",
+		"fenced",
+		"budget"
+	])
+}) {};
+/**
+* Optional disposable ranking index with one fixed embedding/chunking profile.
+* replace validates a complete replacement before atomically exchanging chunks. Failure leaves
+* the last successful index intact. Older generations and divergent same-generation source
+* identities are fenced; refreshing the same source is allowed. Source IDs must equal key IDs.
+* withdraw retains a terminal tombstone that fences every later replacement for that key.
+*
+* Vectors match the profile dimensions and have positive finite squared norms. Chunks form a
+* nonempty contiguous ordinal/byte sequence starting at zero, with unique passage IDs and exact
+* UTF-8 byte ranges bounded by maxChunkBytes. Implementations snapshot mutable caller values.
+*
+* Bounded adapters count every source key, including tombstones, against capacity. Replacement
+* capacity is measured after removing the old chunks. Search rejects scans over maxScannedChunks
+* instead of ranking a truncated prefix. scannedChunks counts all indexed chunks in the namespace
+* before threshold/limit. Ties sort by source ID, revision, then ordinal in UTF-16 code-unit order.
+* Scope close clears the index and makes captured methods fail unavailable.
+*
+* Search is ranking only: callers MUST recheck authoritative revision, access, and withdrawal.
+* This port tracks no builds, extraction progress, or corpus completeness. The host owns source
+* discovery, refresh scheduling, and required freshness.
+*/
+var SemanticMemoryIndex = class extends Context.Service()("@effect-agent/core/SemanticMemoryIndex") {
+	static fromAdapter(adapter) {
+		return {
+			...adapter,
+			search: Effect.fn("SemanticMemoryIndex.search")(function* (query) {
+				const result = yield* adapter.search(query);
+				const checked = yield* Schema.decodeEffect(MemoryIndexSearch.Wire)(result).pipe(Effect.mapError(() => MemoryIndexError.make({
+					operation: "restore index search",
+					reason: "corrupt"
+				})));
+				const candidates = [];
+				for (const candidate of checked.candidates) {
+					if (!equals(candidate.key.namespace, query.namespace)) return yield* MemoryIndexError.make({
+						operation: "restore index namespace",
+						reason: "corrupt"
+					});
+					candidates.push(MemoryIndexCandidate.make({
+						...candidate,
+						key: MemoryKey.make({
+							...candidate.key,
+							namespace: query.namespace
+						})
+					}));
+				}
+				return MemoryIndexSearch.make({
+					...checked,
+					candidates
+				});
+			})
+		};
+	}
+};
+//#endregion
+export { MemoryIndexCandidate, MemoryIndexError, MemoryIndexQuery, MemoryIndexReplacement, MemoryIndexSearch, MemoryIndexSource, SemanticMemoryChunk, SemanticMemoryIndex, SemanticMemoryProfile, SemanticMemoryIndex_exports as t };
+
+//# sourceMappingURL=SemanticMemoryIndex.mjs.map

package/dist/core/SemanticMemoryIndex.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticMemoryIndex.mjs","names":["MemoryNamespace.equals"],"sources":["../../src/core/SemanticMemoryIndex.ts"],"sourcesContent":["import { Context, Effect, Schema } from \"effect\";\n\nimport * as MemoryNamespace from \"./MemoryNamespace.ts\";\nimport { MemoryPassage } from \"./MemoryReference.ts\";\nimport { ActiveMemoryDocument, MemoryKey } from \"./MemoryStore.ts\";\n\nconst Identity = Schema.NonEmptyString.check(Schema.isMaxLength(256));\n\nconst Positive = Schema.Int.check(\n  Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),\n);\n\nconst Timestamp = Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0));\nconst Vector = Schema.Array(Schema.Finite).check(Schema.isMinLength(1), Schema.isMaxLength(4_096));\n\n/** A host declaration of the exact embedding space and deterministic chunking policy. */\nexport class SemanticMemoryProfile extends Schema.Class<SemanticMemoryProfile>(\n  \"@effect-agent/core/SemanticMemoryProfile\",\n)({\n  version: Schema.Literal(1),\n  provider: Identity,\n  model: Identity,\n  modelRevision: Identity,\n  dimensions: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 4_096 })),\n  chunker: Schema.Literal(\"utf8-codepoint@1\"),\n  maxChunkBytes: Schema.Int.check(Schema.isBetween({ minimum: 4, maximum: 8_192 })),\n  distance: Schema.Literal(\"cosine\"),\n}) {}\n\nexport class SemanticMemoryChunk extends Schema.Class<SemanticMemoryChunk>(\n  \"@effect-agent/core/SemanticMemoryChunk\",\n)({\n  passageId: MemoryPassage.fields.passageId,\n  ordinal: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 255 })),\n  startByte: Schema.Natural,\n  endByte: Schema.Natural,\n  text: Schema.NonEmptyString.check(Schema.isMaxLength(8_192)),\n  vector: Vector,\n}) {}\n\nconst SourceFields = {\n  key: MemoryKey.Wire,\n  source: ActiveMemoryDocument.Wire.fields.source,\n  sourceGeneration: Positive,\n};\n\nclass MemoryIndexSourceWire extends Schema.Class<MemoryIndexSourceWire>(\n  \"@effect-agent/core/MemoryIndexSource\",\n)(SourceFields) {}\n\nexport type MemoryIndexSource<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<\n  MemoryIndexSourceWire,\n  \"key\"\n> & { readonly key: MemoryKey<Namespace> };\n\nexport const MemoryIndexSource = {\n  Wire: MemoryIndexSourceWire,\n  make: <Namespace extends MemoryNamespace.Any>(\n    fields: MemoryIndexSource<Namespace>,\n  ): MemoryIndexSource<Namespace> =>\n    Object.assign(Schema.decodeUnknownSync(MemoryIndexSourceWire)(fields), {\n      key: MemoryKey.make(fields.key),\n    }),\n};\n\n/** A complete replacement, prepared before touching the disposable index. */\nclass MemoryIndexReplacementWire extends Schema.Class<MemoryIndexReplacementWire>(\n  \"@effect-agent/core/MemoryIndexReplacement\",\n)({\n  source: MemoryIndexSource.Wire,\n  profile: SemanticMemoryProfile,\n  chunks: Schema.Array(SemanticMemoryChunk).check(Schema.isMinLength(1), Schema.isMaxLength(256)),\n}) {}\n\nexport type MemoryIndexReplacement<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =\n  Omit<MemoryIndexReplacementWire, \"source\"> & { readonly source: MemoryIndexSource<Namespace> };\n\nexport const MemoryIndexReplacement = {\n  Wire: MemoryIndexReplacementWire,\n  make: <Namespace extends MemoryNamespace.Any>(\n    fields: MemoryIndexReplacement<Namespace>,\n  ): MemoryIndexReplacement<Namespace> =>\n    Object.assign(Schema.decodeUnknownSync(MemoryIndexReplacementWire)(fields), {\n      source: fields.source,\n    }),\n};\n\nclass MemoryIndexCandidateWire extends Schema.Class<MemoryIndexCandidateWire>(\n  \"@effect-agent/core/MemoryIndexCandidate\",\n)({\n  ...SourceFields,\n  passageId: SemanticMemoryChunk.fields.passageId,\n  ordinal: SemanticMemoryChunk.fields.ordinal,\n  startByte: SemanticMemoryChunk.fields.startByte,\n  endByte: SemanticMemoryChunk.fields.endByte,\n  text: SemanticMemoryChunk.fields.text,\n  score: Schema.Finite.check(Schema.isBetween({ minimum: -1, maximum: 1 })),\n  indexedAt: Timestamp,\n}) {}\n\nexport type MemoryIndexCandidate<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> =\n  Omit<MemoryIndexCandidateWire, \"key\"> & { readonly key: MemoryKey<Namespace> };\n\nexport const MemoryIndexCandidate = {\n  Wire: MemoryIndexCandidateWire,\n  make: <Namespace extends MemoryNamespace.Any>(\n    fields: MemoryIndexCandidate<Namespace>,\n  ): MemoryIndexCandidate<Namespace> =>\n    Object.assign(Schema.decodeUnknownSync(MemoryIndexCandidateWire)(fields), {\n      key: MemoryKey.make(fields.key),\n    }),\n};\n\nclass MemoryIndexQueryWire extends Schema.Class<MemoryIndexQueryWire>(\n  \"@effect-agent/core/MemoryIndexQuery\",\n)({\n  namespace: MemoryKey.Wire.fields.namespace,\n  vector: Vector,\n  limit: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 128 })),\n  minScore: Schema.Finite.check(Schema.isBetween({ minimum: -1, maximum: 1 })),\n  maxScannedChunks: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65_536 })),\n}) {}\n\nexport type MemoryIndexQuery<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<\n  MemoryIndexQueryWire,\n  \"namespace\"\n> & { readonly namespace: Namespace };\n\nexport const MemoryIndexQuery = {\n  Wire: MemoryIndexQueryWire,\n  make: <Namespace extends MemoryNamespace.Any>(\n    fields: MemoryIndexQuery<Namespace>,\n  ): MemoryIndexQuery<Namespace> =>\n    Object.assign(Schema.decodeUnknownSync(MemoryIndexQueryWire)(fields), {\n      namespace: fields.namespace,\n    }),\n};\n\nclass MemoryIndexSearchWire extends Schema.Class<MemoryIndexSearchWire>(\n  \"@effect-agent/core/MemoryIndexSearch\",\n)({\n  candidates: Schema.Array(MemoryIndexCandidate.Wire).check(Schema.isMaxLength(128)),\n  scannedChunks: Schema.Natural,\n}) {}\n\nexport type MemoryIndexSearch<Namespace extends MemoryNamespace.Any = MemoryNamespace.Any> = Omit<\n  MemoryIndexSearchWire,\n  \"candidates\"\n> & { readonly candidates: ReadonlyArray<MemoryIndexCandidate<Namespace>> };\n\nexport const MemoryIndexSearch = {\n  Wire: MemoryIndexSearchWire,\n  make: <Namespace extends MemoryNamespace.Any>(\n    fields: MemoryIndexSearch<Namespace>,\n  ): MemoryIndexSearch<Namespace> =>\n    Object.assign(Schema.decodeUnknownSync(MemoryIndexSearchWire)(fields), {\n      candidates: fields.candidates,\n    }),\n};\n\nexport class MemoryIndexError extends Schema.TaggedError<MemoryIndexError>()(\"MemoryIndexError\", {\n  operation: Identity,\n  reason: Schema.Literals([\n    \"invalid-input\",\n    \"unavailable\",\n    \"corrupt\",\n    \"incompatible\",\n    \"fenced\",\n    \"budget\",\n  ]),\n}) {}\n\n/**\n * Optional disposable ranking index with one fixed embedding/chunking profile.\n * replace validates a complete replacement before atomically exchanging chunks. Failure leaves\n * the last successful index intact. Older generations and divergent same-generation source\n * identities are fenced; refreshing the same source is allowed. Source IDs must equal key IDs.\n * withdraw retains a terminal tombstone that fences every later replacement for that key.\n *\n * Vectors match the profile dimensions and have positive finite squared norms. Chunks form a\n * nonempty contiguous ordinal/byte sequence starting at zero, with unique passage IDs and exact\n * UTF-8 byte ranges bounded by maxChunkBytes. Implementations snapshot mutable caller values.\n *\n * Bounded adapters count every source key, including tombstones, against capacity. Replacement\n * capacity is measured after removing the old chunks. Search rejects scans over maxScannedChunks\n * instead of ranking a truncated prefix. scannedChunks counts all indexed chunks in the namespace\n * before threshold/limit. Ties sort by source ID, revision, then ordinal in UTF-16 code-unit order.\n * Scope close clears the index and makes captured methods fail unavailable.\n *\n * Search is ranking only: callers MUST recheck authoritative revision, access, and withdrawal.\n * This port tracks no builds, extraction progress, or corpus completeness. The host owns source\n * discovery, refresh scheduling, and required freshness.\n */\nexport class SemanticMemoryIndex extends Context.Service<\n  SemanticMemoryIndex,\n  {\n    readonly profile: SemanticMemoryProfile;\n    readonly replace: <Namespace extends MemoryNamespace.Any>(\n      request: MemoryIndexReplacement<Namespace>,\n    ) => Effect.Effect<void, MemoryIndexError>;\n    readonly withdraw: <Namespace extends MemoryNamespace.Any>(\n      source: MemoryIndexSource<Namespace>,\n    ) => Effect.Effect<void, MemoryIndexError>;\n    readonly search: <Namespace extends MemoryNamespace.Any>(\n      query: MemoryIndexQuery<Namespace>,\n    ) => Effect.Effect<MemoryIndexSearch<Namespace>, MemoryIndexError>;\n  }\n>()(\"@effect-agent/core/SemanticMemoryIndex\") {\n  static fromAdapter(adapter: {\n    readonly profile: SemanticMemoryProfile;\n    readonly replace: (request: MemoryIndexReplacement) => Effect.Effect<void, MemoryIndexError>;\n    readonly withdraw: (source: MemoryIndexSource) => Effect.Effect<void, MemoryIndexError>;\n    readonly search: (\n      query: MemoryIndexQuery,\n    ) => Effect.Effect<MemoryIndexSearch, MemoryIndexError>;\n  }): SemanticMemoryIndex[\"Service\"] {\n    return {\n      ...adapter,\n      search: Effect.fn(\"SemanticMemoryIndex.search\")(function* <\n        Namespace extends MemoryNamespace.Any,\n      >(query: MemoryIndexQuery<Namespace>) {\n        const result = yield* adapter.search(query);\n\n        const checked = yield* Schema.decodeEffect(MemoryIndexSearch.Wire)(result).pipe(\n          Effect.mapError(() =>\n            MemoryIndexError.make({ operation: \"restore index search\", reason: \"corrupt\" }),\n          ),\n        );\n\n        const candidates: Array<MemoryIndexCandidate<Namespace>> = [];\n\n        for (const candidate of checked.candidates) {\n          if (!MemoryNamespace.equals(candidate.key.namespace, query.namespace))\n            return yield* MemoryIndexError.make({\n              operation: \"restore index namespace\",\n              reason: \"corrupt\",\n            });\n          candidates.push(\n            MemoryIndexCandidate.make({\n              ...candidate,\n              key: MemoryKey.make({ ...candidate.key, namespace: query.namespace }),\n            }),\n          );\n        }\n\n        return MemoryIndexSearch.make({ ...checked, candidates });\n      }),\n    };\n  }\n}\n"],"mappings":"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"}

package/dist/core/SemanticMemoryRevalidation.d.mts

@@ -0,0 +1,45 @@
+import { a as MemoryPassage } from "../MemoryReference-B8Q3UJoJ.mjs";
+import { MemoryReader, MemoryStorageError } from "./MemoryStore.mjs";
+import { MemoryAccess } from "./MemoryRevalidation.mjs";
+import { MemoryIndexError, MemoryIndexSearch, SemanticMemoryProfile } from "./SemanticMemoryIndex.mjs";
+import { Effect, Schema } from "effect";
+declare namespace SemanticMemoryRevalidation_d_exports {
+  export { SemanticCandidateLimits, SemanticCandidateResult, SemanticMemoryError, revalidateSemanticMemoryCandidates };
+}
+declare const SemanticMemoryError_base: Schema.Class<SemanticMemoryError, Schema.TaggedStruct<"SemanticMemoryError", {
+  readonly operation: Schema.NonEmptyString;
+  readonly reason: Schema.Literals<readonly ["invalid-input", "invalid-embedding", "budget", "timeout", "source-changed", "unavailable"]>;
+}>, import("effect/Cause").YieldableError>;
+declare class SemanticMemoryError extends SemanticMemoryError_base {}
+declare const SemanticCandidateLimits_base: Schema.Class<SemanticCandidateLimits, Schema.Struct<{
+  readonly maxCandidates: Schema.Int;
+  readonly maxScannedChunks: Schema.Int;
+  readonly maxSourceBytes: Schema.optionalKey<Schema.Int>;
+  /** Aggregate UTF-8 JSON passage bytes, including repeated provenance; defaults to 16 MiB. */
+  readonly maxOutputBytes: Schema.optionalKey<Schema.Int>;
+  readonly minScore: Schema.Finite;
+}>, {}>;
+declare class SemanticCandidateLimits extends SemanticCandidateLimits_base {}
+declare const SemanticCandidateResult_base: Schema.Class<SemanticCandidateResult, Schema.Struct<{
+  readonly lookup: Schema.Union<readonly [Schema.TaggedStruct<"Found", {
+    readonly passages: Schema.$Array<typeof MemoryPassage>;
+  }>, Schema.TaggedStruct<"NoMatch", {}>, Schema.TaggedStruct<"Unavailable", {
+    readonly message: Schema.String;
+  }>, Schema.TaggedStruct<"InsufficientFreshness", {
+    readonly message: Schema.String;
+  }>]>;
+  readonly scannedChunks: Schema.Natural;
+  readonly staleExcluded: Schema.Natural;
+  readonly unauthorizedExcluded: Schema.Natural;
+}>, {}>;
+declare class SemanticCandidateResult extends SemanticCandidateResult_base {}
+/**
+ * Revalidate one ranked batch locally. No embedding or index access; stale scored text is excluded.
+ * Charge each accepted passage's full JSON encoding before retaining it, including duplicates and
+ * authoritative metadata/attribution. maxOutputBytes bounds their aggregate, not source reads or
+ * a transport envelope. One passage is constructed at a time before this check.
+ */
+declare const revalidateSemanticMemoryCandidates: (found: MemoryIndexSearch, access: MemoryAccess, profile: SemanticMemoryProfile, limits: SemanticCandidateLimits) => Effect.Effect<SemanticCandidateResult, MemoryIndexError | MemoryStorageError | SemanticMemoryError, MemoryReader>;
+//#endregion
+export { SemanticCandidateLimits, SemanticCandidateResult, SemanticMemoryError, revalidateSemanticMemoryCandidates, SemanticMemoryRevalidation_d_exports as t };
+//# sourceMappingURL=SemanticMemoryRevalidation.d.mts.map

package/dist/core/SemanticMemoryRevalidation.mjs

@@ -0,0 +1,191 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { n as utf8ByteLength } from "../utf8-DchGZRBd.mjs";
+import { MemoryLookup, MemoryPassage } from "./MemoryReference.mjs";
+import { MemoryDocument, MemoryReader, MemoryStorageError } from "./MemoryStore.mjs";
+import { MemoryAccess } from "./MemoryRevalidation.mjs";
+import { MemoryIndexError, MemoryIndexSearch, SemanticMemoryProfile } from "./SemanticMemoryIndex.mjs";
+import { Effect, Encoding, Schema } from "effect";
+//#region src/core/SemanticMemoryRevalidation.ts
+var SemanticMemoryRevalidation_exports = /* @__PURE__ */ __exportAll({
+	SemanticCandidateLimits: () => SemanticCandidateLimits,
+	SemanticCandidateResult: () => SemanticCandidateResult,
+	SemanticMemoryError: () => SemanticMemoryError,
+	revalidateSemanticMemoryCandidates: () => revalidateSemanticMemoryCandidates
+});
+var SemanticMemoryError = class extends Schema.TaggedError()("SemanticMemoryError", {
+	operation: Schema.NonEmptyString,
+	reason: Schema.Literals([
+		"invalid-input",
+		"invalid-embedding",
+		"budget",
+		"timeout",
+		"source-changed",
+		"unavailable"
+	])
+}) {};
+var SemanticCandidateLimits = class extends Schema.Class("@effect-agent/core/SemanticCandidateLimits")({
+	maxCandidates: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 128
+	})),
+	maxScannedChunks: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 65536
+	})),
+	maxSourceBytes: Schema.optionalKey(Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 67108864
+	}))),
+	/** Aggregate UTF-8 JSON passage bytes, including repeated provenance; defaults to 16 MiB. */
+	maxOutputBytes: Schema.optionalKey(Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 67108864
+	}))),
+	minScore: Schema.Finite.check(Schema.isBetween({
+		minimum: -1,
+		maximum: 1
+	}))
+}) {};
+var SemanticCandidateResult = class extends Schema.Class("@effect-agent/core/SemanticCandidateResult")({
+	lookup: MemoryLookup,
+	scannedChunks: Schema.Natural,
+	staleExcluded: Schema.Natural,
+	unauthorizedExcluded: Schema.Natural
+}) {};
+const readDocument = Effect.fn("semanticCandidates.readDocument")(function* (key) {
+	const document = yield* (yield* MemoryReader).get(key).pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.NullOr(MemoryDocument.Wire))), Effect.catchTag("SchemaError", () => Effect.fail(MemoryStorageError.make({
+		operation: "validate semantic source",
+		reason: "corrupt"
+	}))));
+	if (document !== null && (document.key.namespace.address !== key.namespace.address || document.key.id !== key.id || document.source.id !== key.id)) return yield* MemoryStorageError.make({
+		operation: "validate semantic source identity",
+		reason: "corrupt"
+	});
+	return document;
+});
+/**
+* Revalidate one ranked batch locally. No embedding or index access; stale scored text is excluded.
+* Charge each accepted passage's full JSON encoding before retaining it, including duplicates and
+* authoritative metadata/attribution. maxOutputBytes bounds their aggregate, not source reads or
+* a transport envelope. One passage is constructed at a time before this check.
+*/
+const revalidateSemanticMemoryCandidates = Effect.fn("revalidateSemanticMemoryCandidates")(function* (found, access, profile, limits) {
+	const input = yield* Schema.decodeEffect(Schema.Struct({
+		found: MemoryIndexSearch.Wire,
+		access: MemoryAccess.Wire,
+		profile: SemanticMemoryProfile,
+		limits: SemanticCandidateLimits
+	}))({
+		found,
+		access,
+		profile,
+		limits
+	}).pipe(Effect.mapError(() => MemoryIndexError.make({
+		operation: "validate candidates",
+		reason: "corrupt"
+	})));
+	found = input.found;
+	access = input.access;
+	profile = input.profile;
+	limits = input.limits;
+	if (found.candidates.length > limits.maxCandidates || found.scannedChunks > limits.maxScannedChunks || found.scannedChunks < found.candidates.length) return yield* MemoryIndexError.make({
+		operation: "validate candidate bounds",
+		reason: "corrupt"
+	});
+	const groups = /* @__PURE__ */ new Map();
+	const rankedPassages = [];
+	let staleExcluded = 0;
+	let unauthorizedExcluded = 0;
+	for (const [rank, candidate] of found.candidates.entries()) {
+		if (candidate.key.namespace.address !== access.namespace.address || candidate.source.id !== candidate.key.id || candidate.score < limits.minScore) return yield* MemoryIndexError.make({
+			operation: "validate candidate identity",
+			reason: "corrupt"
+		});
+		const group = groups.get(candidate.key.id);
+		if (group === void 0) groups.set(candidate.key.id, {
+			key: candidate.key,
+			candidates: [{
+				rank,
+				candidate
+			}]
+		});
+		else group.candidates.push({
+			rank,
+			candidate
+		});
+	}
+	const maxSourceBytes = limits.maxSourceBytes ?? 16777216;
+	const maxOutputBytes = limits.maxOutputBytes ?? 16777216;
+	let sourceBytes = 0;
+	let outputBytes = 0;
+	for (const group of groups.values()) {
+		yield* Effect.yieldNow;
+		const document = yield* readDocument(group.key);
+		if (document === null || document._tag === "WithdrawnMemoryDocument") {
+			staleExcluded += group.candidates.length;
+			continue;
+		}
+		if (!document.scopes.includes(access.scope)) {
+			unauthorizedExcluded += group.candidates.length;
+			continue;
+		}
+		const current = group.candidates.filter(({ candidate }) => document.generation === candidate.sourceGeneration && document.source.revision === candidate.source.revision && document.source.locator === candidate.source.locator);
+		staleExcluded += group.candidates.length - current.length;
+		if (current.length === 0) continue;
+		const encoded = JSON.stringify(document);
+		const remainingSourceBytes = maxSourceBytes - sourceBytes;
+		const encodedBytes = encoded.length <= remainingSourceBytes ? utf8ByteLength(encoded) : void 0;
+		if (encodedBytes === void 0 || encodedBytes > remainingSourceBytes) return yield* SemanticMemoryError.make({
+			operation: "query source bytes",
+			reason: "budget"
+		});
+		sourceBytes += encodedBytes;
+		const encodedDocument = Encoding.encodeHex(document.content.text);
+		for (const { rank, candidate } of current) {
+			if (!sameExcerpt(encodedDocument, candidate, profile.maxChunkBytes)) {
+				staleExcluded += 1;
+				continue;
+			}
+			const passage = MemoryPassage.make({
+				version: 1,
+				authority: access.namespace.address,
+				source: document.source,
+				passageId: candidate.passageId,
+				content: {
+					...document.content,
+					text: candidate.text
+				}
+			});
+			const encodedPassage = JSON.stringify(passage);
+			const remainingOutputBytes = maxOutputBytes - outputBytes;
+			const passageBytes = encodedPassage.length <= remainingOutputBytes ? utf8ByteLength(encodedPassage) : void 0;
+			if (passageBytes === void 0 || passageBytes > remainingOutputBytes) return yield* SemanticMemoryError.make({
+				operation: "query output bytes",
+				reason: "budget"
+			});
+			outputBytes += passageBytes;
+			rankedPassages.push({
+				rank,
+				passage
+			});
+		}
+	}
+	const passages = rankedPassages.sort((left, right) => left.rank - right.rank).map(({ passage }) => passage);
+	return SemanticCandidateResult.make({
+		lookup: passages.length === 0 ? { _tag: "NoMatch" } : {
+			_tag: "Found",
+			passages
+		},
+		scannedChunks: found.scannedChunks,
+		staleExcluded,
+		unauthorizedExcluded
+	});
+});
+const sameExcerpt = (encodedDocument, candidate, maxChunkBytes) => {
+	const hex = Encoding.encodeHex(candidate.text);
+	return candidate.startByte < candidate.endByte && hex.length / 2 === candidate.endByte - candidate.startByte && hex.length / 2 <= maxChunkBytes && encodedDocument.slice(candidate.startByte * 2, candidate.endByte * 2) === hex;
+};
+//#endregion
+export { SemanticCandidateLimits, SemanticCandidateResult, SemanticMemoryError, revalidateSemanticMemoryCandidates, SemanticMemoryRevalidation_exports as t };
+
+//# sourceMappingURL=SemanticMemoryRevalidation.mjs.map

package/dist/core/SemanticMemoryRevalidation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SemanticMemoryRevalidation.mjs","names":["byteLength"],"sources":["../../src/core/SemanticMemoryRevalidation.ts"],"sourcesContent":["import { Effect, Encoding, Schema } from \"effect\";\n\nimport { utf8ByteLength as byteLength } from \"./internal/utf8.ts\";\nimport { MemoryLookup, MemoryPassage } from \"./MemoryReference.ts\";\nimport { MemoryAccess } from \"./MemoryRevalidation.ts\";\nimport type { MemoryKey } from \"./MemoryStore.ts\";\nimport { MemoryDocument, MemoryReader, MemoryStorageError } from \"./MemoryStore.ts\";\nimport type { MemoryIndexCandidate } from \"./SemanticMemoryIndex.ts\";\nimport {\n  MemoryIndexError,\n  MemoryIndexSearch,\n  SemanticMemoryProfile,\n} from \"./SemanticMemoryIndex.ts\";\n\nexport class SemanticMemoryError extends Schema.TaggedError<SemanticMemoryError>()(\n  \"SemanticMemoryError\",\n  {\n    operation: Schema.NonEmptyString,\n    reason: Schema.Literals([\n      \"invalid-input\",\n      \"invalid-embedding\",\n      \"budget\",\n      \"timeout\",\n      \"source-changed\",\n      \"unavailable\",\n    ]),\n  },\n) {}\n\nexport class SemanticCandidateLimits extends Schema.Class<SemanticCandidateLimits>(\n  \"@effect-agent/core/SemanticCandidateLimits\",\n)({\n  maxCandidates: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 128 })),\n  maxScannedChunks: Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 65_536 })),\n  maxSourceBytes: Schema.optionalKey(\n    Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 67_108_864 })),\n  ),\n  /** Aggregate UTF-8 JSON passage bytes, including repeated provenance; defaults to 16 MiB. */\n  maxOutputBytes: Schema.optionalKey(\n    Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: 67_108_864 })),\n  ),\n  minScore: Schema.Finite.check(Schema.isBetween({ minimum: -1, maximum: 1 })),\n}) {}\n\nexport class SemanticCandidateResult extends Schema.Class<SemanticCandidateResult>(\n  \"@effect-agent/core/SemanticCandidateResult\",\n)({\n  lookup: MemoryLookup,\n  scannedChunks: Schema.Natural,\n  staleExcluded: Schema.Natural,\n  unauthorizedExcluded: Schema.Natural,\n}) {}\n\nconst readDocument = Effect.fn(\"semanticCandidates.readDocument\")(function* (key: MemoryKey) {\n  const reader = yield* MemoryReader;\n\n  const document = yield* reader.get(key).pipe(\n    Effect.flatMap(Schema.decodeUnknownEffect(Schema.NullOr(MemoryDocument.Wire))),\n    Effect.catchTag(\"SchemaError\", () =>\n      Effect.fail(\n        MemoryStorageError.make({ operation: \"validate semantic source\", reason: \"corrupt\" }),\n      ),\n    ),\n  );\n\n  if (\n    document !== null &&\n    (document.key.namespace.address !== key.namespace.address ||\n      document.key.id !== key.id ||\n      document.source.id !== key.id)\n  )\n    return yield* MemoryStorageError.make({\n      operation: \"validate semantic source identity\",\n      reason: \"corrupt\",\n    });\n\n  return document;\n});\n\n/**\n * Revalidate one ranked batch locally. No embedding or index access; stale scored text is excluded.\n * Charge each accepted passage's full JSON encoding before retaining it, including duplicates and\n * authoritative metadata/attribution. maxOutputBytes bounds their aggregate, not source reads or\n * a transport envelope. One passage is constructed at a time before this check.\n */\nexport const revalidateSemanticMemoryCandidates = Effect.fn(\"revalidateSemanticMemoryCandidates\")(\n  function* (\n    found: MemoryIndexSearch,\n    access: MemoryAccess,\n    profile: SemanticMemoryProfile,\n    limits: SemanticCandidateLimits,\n  ) {\n    const input = yield* Schema.decodeEffect(\n      Schema.Struct({\n        found: MemoryIndexSearch.Wire,\n        access: MemoryAccess.Wire,\n        profile: SemanticMemoryProfile,\n        limits: SemanticCandidateLimits,\n      }),\n    )({ found, access, profile, limits }).pipe(\n      Effect.mapError(() =>\n        MemoryIndexError.make({ operation: \"validate candidates\", reason: \"corrupt\" }),\n      ),\n    );\n\n    found = input.found;\n    access = input.access;\n    profile = input.profile;\n    limits = input.limits;\n    if (\n      found.candidates.length > limits.maxCandidates ||\n      found.scannedChunks > limits.maxScannedChunks ||\n      found.scannedChunks < found.candidates.length\n    ) {\n      return yield* MemoryIndexError.make({\n        operation: \"validate candidate bounds\",\n        reason: \"corrupt\",\n      });\n    }\n\n    const groups = new Map<\n      string,\n      {\n        readonly key: MemoryKey;\n        readonly candidates: Array<{\n          readonly rank: number;\n          readonly candidate: MemoryIndexCandidate;\n        }>;\n      }\n    >();\n\n    const rankedPassages: Array<{ readonly rank: number; readonly passage: MemoryPassage }> = [];\n    let staleExcluded = 0;\n    let unauthorizedExcluded = 0;\n\n    for (const [rank, candidate] of found.candidates.entries()) {\n      if (\n        candidate.key.namespace.address !== access.namespace.address ||\n        candidate.source.id !== candidate.key.id ||\n        candidate.score < limits.minScore\n      ) {\n        return yield* MemoryIndexError.make({\n          operation: \"validate candidate identity\",\n          reason: \"corrupt\",\n        });\n      }\n      const group = groups.get(candidate.key.id);\n\n      if (group === undefined) {\n        groups.set(candidate.key.id, { key: candidate.key, candidates: [{ rank, candidate }] });\n      } else group.candidates.push({ rank, candidate });\n    }\n    const maxSourceBytes = limits.maxSourceBytes ?? 16_777_216;\n    const maxOutputBytes = limits.maxOutputBytes ?? 16_777_216;\n    let sourceBytes = 0;\n    let outputBytes = 0;\n\n    for (const group of groups.values()) {\n      yield* Effect.yieldNow;\n      const document = yield* readDocument(group.key);\n\n      if (document === null || document._tag === \"WithdrawnMemoryDocument\") {\n        staleExcluded += group.candidates.length;\n        continue;\n      }\n      if (!document.scopes.includes(access.scope)) {\n        unauthorizedExcluded += group.candidates.length;\n        continue;\n      }\n\n      const current = group.candidates.filter(\n        ({ candidate }) =>\n          document.generation === candidate.sourceGeneration &&\n          document.source.revision === candidate.source.revision &&\n          document.source.locator === candidate.source.locator,\n      );\n\n      staleExcluded += group.candidates.length - current.length;\n      if (current.length === 0) continue;\n      const encoded = JSON.stringify(document);\n      const remainingSourceBytes = maxSourceBytes - sourceBytes;\n      const encodedBytes = encoded.length <= remainingSourceBytes ? byteLength(encoded) : undefined;\n\n      if (encodedBytes === undefined || encodedBytes > remainingSourceBytes) {\n        return yield* SemanticMemoryError.make({\n          operation: \"query source bytes\",\n          reason: \"budget\",\n        });\n      }\n      sourceBytes += encodedBytes;\n      const encodedDocument = Encoding.encodeHex(document.content.text);\n\n      for (const { rank, candidate } of current) {\n        if (!sameExcerpt(encodedDocument, candidate, profile.maxChunkBytes)) {\n          staleExcluded += 1;\n          continue;\n        }\n\n        const passage = MemoryPassage.make({\n          version: 1,\n          authority: access.namespace.address,\n          source: document.source,\n          passageId: candidate.passageId,\n          content: { ...document.content, text: candidate.text },\n        });\n\n        const encodedPassage = JSON.stringify(passage);\n        const remainingOutputBytes = maxOutputBytes - outputBytes;\n\n        const passageBytes =\n          encodedPassage.length <= remainingOutputBytes ? byteLength(encodedPassage) : undefined;\n\n        if (passageBytes === undefined || passageBytes > remainingOutputBytes) {\n          return yield* SemanticMemoryError.make({\n            operation: \"query output bytes\",\n            reason: \"budget\",\n          });\n        }\n        outputBytes += passageBytes;\n        rankedPassages.push({ rank, passage });\n      }\n    }\n\n    const passages = rankedPassages\n      .sort((left, right) => left.rank - right.rank)\n      .map(({ passage }) => passage);\n\n    return SemanticCandidateResult.make({\n      lookup: passages.length === 0 ? { _tag: \"NoMatch\" } : { _tag: \"Found\", passages },\n      scannedChunks: found.scannedChunks,\n      staleExcluded,\n      unauthorizedExcluded,\n    });\n  },\n);\n\nconst sameExcerpt = (\n  encodedDocument: string,\n  candidate: {\n    readonly startByte: number;\n    readonly endByte: number;\n    readonly text: string;\n  },\n  maxChunkBytes: number,\n): boolean => {\n  const hex = Encoding.encodeHex(candidate.text);\n\n  return (\n    candidate.startByte < candidate.endByte &&\n    hex.length / 2 === candidate.endByte - candidate.startByte &&\n    hex.length / 2 <= maxChunkBytes &&\n    encodedDocument.slice(candidate.startByte * 2, candidate.endByte * 2) === hex\n  );\n};\n"],"mappings":"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"}

package/dist/core/SubagentContract.d.mts

@@ -0,0 +1,2 @@
+import { _ as isSubagentToolAllowed, c as SubagentExecutionFailureClassification, d as SubagentReservationAmounts, f as ToolExecutionKind, g as isDelegationToolName, h as getToolExecutionKind, i as SubagentBudgetReservation, l as SubagentGrant, m as delegationToolPrefix, n as DelegationDepth, o as SubagentDelegationCaps, p as WorkerOperationTool, r as DelegationTool, s as SubagentExecutionFailure, t as BackgroundSpawnTool, u as SubagentParentLink, v as maxErrorTagLength, y as narrowSubagentGrant } from "../SubagentContract-DdT7Cqe6.mjs";
+export { BackgroundSpawnTool, DelegationDepth, DelegationTool, SubagentBudgetReservation, SubagentDelegationCaps, SubagentExecutionFailure, SubagentExecutionFailureClassification, SubagentGrant, SubagentParentLink, SubagentReservationAmounts, ToolExecutionKind, WorkerOperationTool, delegationToolPrefix, getToolExecutionKind, isDelegationToolName, isSubagentToolAllowed, maxErrorTagLength, narrowSubagentGrant };

package/dist/core/SubagentContract.mjs

@@ -0,0 +1,148 @@
+import { t as __exportAll } from "../rolldown-runtime-D7D4PA-g.mjs";
+import { AgentId, DelegationId, RunId, SubmissionId, ThreadId, ToolCallId } from "./Identifiers.mjs";
+import { Context, Schema } from "effect";
+//#region src/core/SubagentContract.ts
+var SubagentContract_exports = /* @__PURE__ */ __exportAll({
+	BackgroundSpawnTool: () => BackgroundSpawnTool,
+	DelegationDepth: () => DelegationDepth,
+	DelegationTool: () => DelegationTool,
+	SubagentBudgetReservation: () => SubagentBudgetReservation,
+	SubagentDelegationCaps: () => SubagentDelegationCaps,
+	SubagentExecutionFailure: () => SubagentExecutionFailure,
+	SubagentExecutionFailureClassification: () => SubagentExecutionFailureClassification,
+	SubagentGrant: () => SubagentGrant,
+	SubagentParentLink: () => SubagentParentLink,
+	SubagentReservationAmounts: () => SubagentReservationAmounts,
+	ToolExecutionKind: () => ToolExecutionKind,
+	WorkerOperationTool: () => WorkerOperationTool,
+	delegationToolPrefix: () => delegationToolPrefix,
+	getToolExecutionKind: () => getToolExecutionKind,
+	isDelegationToolName: () => isDelegationToolName,
+	isSubagentToolAllowed: () => isSubagentToolAllowed,
+	maxErrorTagLength: () => 256,
+	narrowSubagentGrant: () => narrowSubagentGrant
+});
+const Natural = Schema.Natural;
+/** Tree authority ceiling. Each child exposes only its own Toolkit's permitted names. */
+var SubagentGrant = class extends Schema.Class("@effect-agent/capabilities/SubagentGrant")({
+	allowedToolNames: Schema.Array(Schema.NonEmptyString).check(Schema.isMaxLength(128)),
+	maxDepth: Schema.Int.check(Schema.isBetween({
+		minimum: 1,
+		maximum: 16
+	})),
+	/** Omitted permits either lifetime within the depth and reserved subtree budgets. */
+	childLifetimes: Schema.optionalKey(Schema.Array(Schema.Literals(["attached", "background"])).check(Schema.isMaxLength(2)))
+}) {};
+/** Intersect inherited authority; another delegation can never restore a removed capability. */
+const narrowSubagentGrant = (declared, inherited) => inherited === void 0 ? declared : SubagentGrant.make({
+	allowedToolNames: declared.allowedToolNames.filter((name) => inherited.allowedToolNames.includes(name)),
+	maxDepth: Math.min(declared.maxDepth, inherited.maxDepth),
+	childLifetimes: (declared.childLifetimes ?? ["attached", "background"]).filter((lifetime) => (inherited.childLifetimes ?? ["attached", "background"]).includes(lifetime))
+});
+/** Finite delegable caps for one parent Run. Absent means not configured; present values are finite. */
+var SubagentDelegationCaps = class extends Schema.Class("@effect-agent/capabilities/SubagentDelegationCaps")({
+	maxTotalChildInvocations: Schema.optionalKey(Natural),
+	maxConcurrentChildren: Schema.optionalKey(Natural),
+	maxTurns: Schema.optionalKey(Natural),
+	maxToolCalls: Schema.optionalKey(Natural),
+	maxDurationMillis: Schema.optionalKey(Natural),
+	maxInputTokens: Schema.optionalKey(Natural),
+	maxOutputTokens: Schema.optionalKey(Natural),
+	maxCostMicrousd: Schema.optionalKey(Natural),
+	maxResultBytes: Schema.optionalKey(Natural)
+}) {};
+const AmountFields = {
+	turns: Natural,
+	toolCalls: Natural,
+	durationMillis: Natural,
+	inputTokens: Natural,
+	outputTokens: Natural,
+	costMicrousd: Natural,
+	resultBytes: Natural
+};
+/** Exact amounts across every reservable delegation dimension. */
+var SubagentReservationAmounts = class extends Schema.Class("@effect-agent/capabilities/SubagentReservationAmounts")(AmountFields) {};
+/** One child reservation against the parent Run's shared delegation pool. */
+const SubagentBudgetReservation = Schema.Struct({
+	caps: SubagentDelegationCaps,
+	allocation: SubagentReservationAmounts,
+	/** Slots reserved for every descendant input beneath this input; absent reserves none. */
+	descendantInvocations: Schema.optionalKey(Natural)
+});
+/** Root-relative delegation depth; the direct child of a top-level run has depth 1. */
+const DelegationDepth = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+/** @deprecated Names are application-owned; use DelegationTool metadata for classification. */
+const delegationToolPrefix = "delegate_";
+/** @deprecated Checks a legacy spelling only, never execution, nesting or recovery semantics. */
+const isDelegationToolName = (toolName) => toolName.startsWith(delegationToolPrefix);
+/** Marks a Tool implementing the idempotent Subagent establishment protocol. */
+const DelegationTool = Context.Reference("@effect-agent/core/DelegationTool", { defaultValue: () => false });
+/** Marks a host-managed idempotent worker operation, independently of its Tool name. */
+const WorkerOperationTool = Context.Reference("@effect-agent/core/WorkerOperationTool", { defaultValue: () => false });
+/** Identifies the background launch operation within a generated management Toolkit. */
+const BackgroundSpawnTool = Context.Reference("@effect-agent/core/BackgroundSpawnTool", { defaultValue: () => false });
+/** Declaration metadata and inherited authority determine the effective visible Tool set. */
+const isSubagentToolAllowed = (grant, depth, name, annotations) => grant === void 0 || grant.allowedToolNames.includes(name) && (Context.get(annotations, BackgroundSpawnTool) ? depth < grant.maxDepth && (grant.childLifetimes ?? ["attached", "background"]).includes("background") : Context.get(annotations, DelegationTool) ? depth < grant.maxDepth && (grant.childLifetimes ?? ["attached", "background"]).includes("attached") : true);
+/** Persisted preparation classification, checked against the resolved Tool before replay. */
+const ToolExecutionKind = Schema.Literals([
+	"ordinary",
+	"delegation",
+	"orchestration"
+]);
+/** Resolve only trusted declaration metadata; names never authorize automatic replay. */
+const getToolExecutionKind = (annotations) => Context.get(annotations, WorkerOperationTool) ? "orchestration" : Context.get(annotations, DelegationTool) ? "delegation" : "ordinary";
+/** Immutable lineage from a child Thread to the parent identity that established it. */
+var SubagentParentLink = class extends Schema.Class("SubagentParentLink")({
+	delegationId: DelegationId,
+	parentAgentId: AgentId,
+	parentThreadId: ThreadId,
+	parentRunId: RunId,
+	parentToolCallId: ToolCallId,
+	depth: DelegationDepth
+}) {};
+/**
+* Classification of one bounded durable delegation failure.
+* `"child-failed"` and `"child-aborted"` project the
+* child's canonical failed/aborted Settlement; `"child-compatibility"`
+* projects the framework's `ChildCompatibilityFailure` child Settlement (the
+* stored child Binding digest was unavailable — recovery never substituted
+* current code); `"establishment-denied"` is a fail-closed coordinator
+* refusal (lineage/digest verification, divergent replay); and
+* `"declaration-unavailable"` is retained for decoding failures recorded by
+* versions that required an explicit durable digest declaration.
+*/
+const SubagentExecutionFailureClassification = Schema.Literals([
+	"child-failed",
+	"child-aborted",
+	"child-compatibility",
+	"establishment-denied",
+	"declaration-unavailable"
+]);
+const maxErrorTagLength = 256;
+const BoundedErrorTag = Schema.NonEmptyString.check(Schema.isMaxLength(256));
+/**
+* Bounded framework projection of a durable child failure, shared by attached joins and reports.
+* A failed or aborted durable child
+* joins its parent Tool Call as exactly this typed failure: a classification,
+* the child references, and the coordinator's bounded `{errorTag, message}`
+* projection — never a raw Cause, stack, provider response, secret, or child
+* payload. The typed child failure union does not survive a durable
+* Settlement, so `mapChildFailure` remains the ephemeral-path contract;
+* Schema-declared durable domain-failure mapping is a recorded later
+* extension.
+*/
+var SubagentExecutionFailure = class extends Schema.TaggedError()("SubagentExecutionFailure", {
+	delegationId: DelegationId,
+	targetAgentId: AgentId,
+	classification: SubagentExecutionFailureClassification,
+	/** Child references, present once establishment reached a child identity. */
+	childThreadId: Schema.optionalKey(ThreadId),
+	childSubmissionId: Schema.optionalKey(SubmissionId),
+	childRunId: Schema.optionalKey(RunId),
+	errorTag: BoundedErrorTag,
+	message: Schema.String.check(Schema.isMaxLength(4096))
+}) {};
+//#endregion
+export { BackgroundSpawnTool, DelegationDepth, DelegationTool, SubagentBudgetReservation, SubagentDelegationCaps, SubagentExecutionFailure, SubagentExecutionFailureClassification, SubagentGrant, SubagentParentLink, SubagentReservationAmounts, ToolExecutionKind, WorkerOperationTool, delegationToolPrefix, getToolExecutionKind, isDelegationToolName, isSubagentToolAllowed, maxErrorTagLength, narrowSubagentGrant, SubagentContract_exports as t };
+
+//# sourceMappingURL=SubagentContract.mjs.map