@orkestrel/brief 0.0.4 → 0.0.5

package/dist/src/core/index.cjs

@@ -370,6 +370,84 @@ var isBrief = (0, _orkestrel_contract.recordOf)({
 //#endregion
 //#region src/core/cloners.ts
 /**
+* Captures one stable, frozen view of a foreign contract value.
+*
+* @remarks
+* Rebuilds the root and every reachable plain container from its own enumerable members.
+* Unknown own members survive. Each published member absent from that copied own set is read
+* once and materialized, which admits a class that supplies its contract through prototype
+* accessors without leaving later reads attached to the live instance. Non-container leaves
+* retain their identity, including functions that `structuredClone` cannot carry.
+*
+* @param source - The foreign value to capture.
+* @param members - The published root member names to materialize when absent from its own set.
+* @returns A deeply frozen plain view, or `source` itself when it is a primitive.
+*
+* @example
+* ```ts
+* import { captureValue } from '@orkestrel/brief'
+*
+* const leaf = () => 'ready'
+* const owned = captureValue({ leaf }, ['leaf'])
+* Reflect.get(owned, 'leaf') === leaf // true — an uncloneable leaf keeps its identity
+* Object.isFrozen(owned) // true
+* ```
+*/
+function captureValue(source, members) {
+	if (source === null || typeof source !== "object" && typeof source !== "function") return source;
+	const target = Array.isArray(source) ? [] : Object.create(null);
+	const seen = new WeakMap([[source, target]]);
+	const captured = [target];
+	const pending = [[
+		source,
+		target,
+		members
+	]];
+	while (pending.length > 0) {
+		const frame = pending.pop();
+		if (frame === void 0) continue;
+		const [current, view, expected] = frame;
+		const entries = [];
+		const copied = /* @__PURE__ */ new Set();
+		for (const key of Reflect.ownKeys(current)) {
+			const descriptor = Reflect.getOwnPropertyDescriptor(current, key);
+			if (descriptor === void 0 || !descriptor.enumerable) continue;
+			copied.add(key);
+			entries.push([key, "value" in descriptor ? descriptor.value : Reflect.get(current, key)]);
+		}
+		for (const key of expected ?? []) if (!copied.has(key)) entries.push([key, Reflect.get(current, key)]);
+		for (const [key, value] of entries) {
+			let owned = value;
+			if (value !== null && typeof value === "object") {
+				const existing = seen.get(value);
+				if (existing !== void 0) owned = existing;
+				else {
+					const prototype = Reflect.getPrototypeOf(value);
+					if (Array.isArray(value) || prototype === null || prototype === Object.prototype) {
+						const branch = Array.isArray(value) ? [] : Object.create(null);
+						seen.set(value, branch);
+						captured.push(branch);
+						pending.push([
+							value,
+							branch,
+							void 0
+						]);
+						owned = branch;
+					}
+				}
+			}
+			Reflect.defineProperty(view, key, {
+				value: owned,
+				enumerable: true,
+				configurable: false,
+				writable: false
+			});
+		}
+	}
+	for (const view of captured) Object.freeze(view);
+	return target;
+}
+/**
 * Return a deeply owned, deeply frozen copy of a brief, refusing anything off-contract.
 *
 * @remarks
@@ -1164,6 +1242,15 @@ function errorToMessage(error) {
 * nothing, so it is an assertion rather than a factory. Reserve it for programmer-error
 * contexts where invalidity is a bug.
 *
+* Intake NARROWS, and transfers no ownership. What comes back is the caller's own object,
+* so a member carried on an accessor can answer this guard one way and a later reader
+* another. The division is deliberate: the borrowed-engine law governs values this package
+* pulls across a seam it called, and a value handed in at the door stays the caller's.
+* `snapshotBrief` is the ownership door, and `pinBrief`, `BriefManager`, `briefToMarkdown`,
+* `briefToGoal`, and `briefToDispatch` take it. `briefToSubject`, `briefToContent`, and
+* `briefToTrace` read the value they are handed instead, so a caller reaching one of those
+* directly owns that reading. Pass `assertBrief` a value you already own.
+*
 * @param data - The candidate brief data.
 * @returns The same value, now known to satisfy {@link Brief}.
 * @throws {@link BriefError} `INVALID` when `data` fails `isBrief`.
@@ -1503,8 +1590,10 @@ function deriveStatement(text) {
 * ```
 */
 function deriveTask(intent, text, actions, domains) {
-	const operation = Object.hasOwn(actions, intent.action) ? actions[intent.action] : void 0;
-	const domain = Object.hasOwn(domains, intent.domain) ? domains[intent.domain] : void 0;
+	const operationDescriptor = Object.getOwnPropertyDescriptor(actions, intent.action);
+	const domainDescriptor = Object.getOwnPropertyDescriptor(domains, intent.domain);
+	const operation = operationDescriptor === void 0 ? void 0 : "value" in operationDescriptor ? operationDescriptor.value : operationDescriptor.get === void 0 ? void 0 : Reflect.apply(operationDescriptor.get, actions, []);
+	const domain = domainDescriptor === void 0 ? void 0 : "value" in domainDescriptor ? domainDescriptor.value : domainDescriptor.get === void 0 ? void 0 : Reflect.apply(domainDescriptor.get, domains, []);
 	if (!isTaskOperation(operation) || !isTaskDomain(domain)) return void 0;
 	const statement = deriveStatement(text);
 	return statement.length === 0 ? void 0 : task(operation, domain, statement);
@@ -1570,6 +1659,15 @@ function deriveGaps(ambiguities) {
 * all fail the same way — `undefined`, never a throw. Coerce a bare vocabulary value with
 * `parseEnum` from `@orkestrel/contract` against the exported tuple instead.
 *
+* The half of the intake pair that is OWNED BY CONSTRUCTION, which is what separates it from
+* `assertBrief`. The argument is text, so the graph the guard reads is one `JSON.parse` built
+* inside this call: it carries no caller identity, no accessor, and no alias back into anything
+* the caller still holds, and the parse-and-guard primitive this file imports from
+* `@orkestrel/contract` returns that same parsed graph rather than a second reading of it.
+* Every member `isBrief` checked therefore answers a later reader identically. The value is
+* fresh rather than frozen, so the caller owns it outright — reach for `snapshotBrief` when the
+* value came from code instead of from text.
+*
 * @param value - The JSON text to parse.
 * @returns The `Brief` when the parsed value satisfies `isBrief`, otherwise `undefined`.
 *
@@ -1880,7 +1978,15 @@ var BriefCompiler = class {
 	}
 	gate(source) {
 		this.#refuseDestroyed();
-		const ruled = (0, _orkestrel_contract.attempt)(() => this.#own(this.#reason.reason(briefToSubject(source), gateDefinition())));
+		const ruled = (0, _orkestrel_contract.attempt)(() => this.#own(this.#reason.reason(briefToSubject(source), gateDefinition()), [
+			"reasoning",
+			"conclusion",
+			"rules",
+			"count",
+			"success",
+			"trace",
+			"errors"
+		]));
 		if (!ruled.success) throw new BriefError("GATE_FAILED", errorToMessage(ruled.error), {
 			stage: "gate",
 			field: "reason"
@@ -1903,14 +2009,30 @@ var BriefCompiler = class {
 	#snapshot(input) {
 		return freezeDeep(structuredClone(input));
 	}
-	#own(value) {
+	#own(value, members) {
 		const cloned = (0, _orkestrel_contract.attempt)(() => structuredClone(value));
-		return freezeDeep(cloned.success ? cloned.value : value);
+		return cloned.success ? freezeDeep(cloned.value) : captureValue(value, members);
 	}
 	#read(input, raw, stages, failures) {
+		const members = [
+			"text",
+			"normalized",
+			"intent",
+			"entities",
+			"subject",
+			"definition",
+			"mappings",
+			"ambiguities",
+			"prompt",
+			"stages",
+			"failures",
+			"complete",
+			"confidence",
+			"digest"
+		];
 		const text = input.text;
 		if (text !== void 0) {
-			const read = (0, _orkestrel_contract.attempt)(() => this.#own(this.#interpret.interpret(text)));
+			const read = (0, _orkestrel_contract.attempt)(() => this.#own(this.#interpret.interpret(text), members));
 			if (read.success && (0, _orkestrel_interpret.isInterpretation)(read.value)) {
 				stages.push(Object.freeze({
 					stage: "interpret",
@@ -1935,7 +2057,8 @@ var BriefCompiler = class {
 		const supplied = input.interpretation;
 		if (supplied === void 0 || (0, _orkestrel_interpret.isInterpretation)(supplied)) return supplied;
 		const live = raw.interpretation;
-		if (live !== void 0 && (0, _orkestrel_interpret.isInterpretation)(live)) return freezeDeep(live);
+		const captured = (0, _orkestrel_contract.attempt)(() => captureValue(live, members));
+		if (captured.success && (0, _orkestrel_interpret.isInterpretation)(captured.value)) return captured.value;
 		const message = "The supplied interpretation does not satisfy the published shape";
 		stages.push(Object.freeze({
 			stage: "interpret",
@@ -1959,7 +2082,7 @@ var BriefCompiler = class {
 			code: "BLOCKED",
 			message: `Gate refused: ${unready.join(", ")}`
 		};
-		if (!(0, _orkestrel_reason.isLogicalResult)(verdict)) return void 0;
+		if (verdict === void 0) return void 0;
 		const refused = verdict.rules.filter((entry) => !entry.conclusion).map((entry) => entry.id).join(", ");
 		if (refused.length === 0) return {
 			stage: "gate",
@@ -2115,6 +2238,7 @@ exports.briefToHash = briefToHash;
 exports.briefToMarkdown = briefToMarkdown;
 exports.briefToSubject = briefToSubject;
 exports.briefToTrace = briefToTrace;
+exports.captureValue = captureValue;
 exports.citation = citation;
 exports.citationShape = citationShape;
 exports.countSentences = countSentences;