@orkestrel/brief 0.0.3 → 0.0.5

package/dist/src/core/index.d.cts

@@ -31,6 +31,15 @@ import { Subject } from '@orkestrel/reason';
  * 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`.
@@ -173,22 +182,31 @@ import { Subject } from '@orkestrel/reason';
   * is FIXED: readiness is this package's contract, not a caller setting.
   *
   * A borrowed engine is the caller's own code, not an attacker, and this package does not
-  * treat it as one. The line is OWNERSHIP, and it produces four obligations worth stating
-  * because none of them is enforced in code:
-  *
-  * - Every value a borrowed engine returns is OWNED AT ARRIVAL — copied where the value
-  *   permits it, sealed in place where it does not — and then read exactly once. What the
-  *   engine does with its own object afterwards cannot reach a `Briefing`.
+  * treat it as one. The line is OWNERSHIP, and it produces obligations worth stating because
+  * none of them is enforced in code:
+  *
+  * - Every value a borrowed engine returns is OWNED AT ARRIVAL — copied where a structured
+  *   clone can carry it, captured into a frozen plain view where it cannot — and read once,
+  *   where that copy or capture takes the reading. The captured view is what the `Briefing`
+  *   replays, exactly as the clone arm always produced: a member the caller's prototype
+  *   carries, outside the published contract, does not survive capture, and it never survived
+  *   a structured clone either. What the engine does with its own object afterwards cannot
+  *   reach a `Briefing`.
   * - Both returns are shape-checked with their packages' published guards — reasons' logical
   *   result guard for the verdict, interprets' interpretation guard at both of the interpret
   *   stage's doors. A malformed value at either door records `INTERPRET_FAILED` instead of
   *   escaping `compile` as a raw throw, and a supplied interpretation whose snapshot copy
-  *   loses prototype-carried members is sealed live rather than refused.
+  *   loses prototype-carried members is captured rather than refused.
   * - Neither engine is narrowed past its published contract. `Entity.value` is `unknown` and
   *   `LogicalResult` is an interface a class instance satisfies, so a value JSON cannot
-  *   express is on-contract and is sealed rather than refused.
-  * - `actions` and `domains` are read LIVE on every `compile`, not snapshotted at
-  *   construction. Mutating them between calls changes what the next call derives.
+  *   express is on-contract: its uncloneable leaves keep their identity inside the captured
+  *   view rather than being refused.
+  * - `actions` and `domains` are read as option slots ONCE, at construction, so replacing
+  *   either property on the options object afterwards changes nothing. The map each slot
+  *   names is dereferenced on every `compile`, and each lookup captures its mapping once
+  *   through the own descriptor. Mutating a map between calls therefore changes what the next
+  *   call derives, while a mapping that answers differently on a second read cannot change
+  *   what one call already derived.
   *
   * Whether the engine is correct, and whether it answers the same way twice, remain the
   * caller's own problem.
@@ -638,6 +656,32 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function briefToTrace(source: Brief): string;
 
+ /**
+  * 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
+  * ```
+  */
+ export declare function captureValue(source: unknown, members: readonly string[]): unknown;
+
  /**
   * One external source — what it is called, where it lives, and why it is cited.
   *
@@ -1572,6 +1616,15 @@ import { Subject } from '@orkestrel/reason';
   * 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`.
   *

package/dist/src/core/index.d.ts

@@ -31,6 +31,15 @@ import { Subject } from '@orkestrel/reason';
  * 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`.
@@ -173,22 +182,31 @@ import { Subject } from '@orkestrel/reason';
   * is FIXED: readiness is this package's contract, not a caller setting.
   *
   * A borrowed engine is the caller's own code, not an attacker, and this package does not
-  * treat it as one. The line is OWNERSHIP, and it produces four obligations worth stating
-  * because none of them is enforced in code:
-  *
-  * - Every value a borrowed engine returns is OWNED AT ARRIVAL — copied where the value
-  *   permits it, sealed in place where it does not — and then read exactly once. What the
-  *   engine does with its own object afterwards cannot reach a `Briefing`.
+  * treat it as one. The line is OWNERSHIP, and it produces obligations worth stating because
+  * none of them is enforced in code:
+  *
+  * - Every value a borrowed engine returns is OWNED AT ARRIVAL — copied where a structured
+  *   clone can carry it, captured into a frozen plain view where it cannot — and read once,
+  *   where that copy or capture takes the reading. The captured view is what the `Briefing`
+  *   replays, exactly as the clone arm always produced: a member the caller's prototype
+  *   carries, outside the published contract, does not survive capture, and it never survived
+  *   a structured clone either. What the engine does with its own object afterwards cannot
+  *   reach a `Briefing`.
   * - Both returns are shape-checked with their packages' published guards — reasons' logical
   *   result guard for the verdict, interprets' interpretation guard at both of the interpret
   *   stage's doors. A malformed value at either door records `INTERPRET_FAILED` instead of
   *   escaping `compile` as a raw throw, and a supplied interpretation whose snapshot copy
-  *   loses prototype-carried members is sealed live rather than refused.
+  *   loses prototype-carried members is captured rather than refused.
   * - Neither engine is narrowed past its published contract. `Entity.value` is `unknown` and
   *   `LogicalResult` is an interface a class instance satisfies, so a value JSON cannot
-  *   express is on-contract and is sealed rather than refused.
-  * - `actions` and `domains` are read LIVE on every `compile`, not snapshotted at
-  *   construction. Mutating them between calls changes what the next call derives.
+  *   express is on-contract: its uncloneable leaves keep their identity inside the captured
+  *   view rather than being refused.
+  * - `actions` and `domains` are read as option slots ONCE, at construction, so replacing
+  *   either property on the options object afterwards changes nothing. The map each slot
+  *   names is dereferenced on every `compile`, and each lookup captures its mapping once
+  *   through the own descriptor. Mutating a map between calls therefore changes what the next
+  *   call derives, while a mapping that answers differently on a second read cannot change
+  *   what one call already derived.
   *
   * Whether the engine is correct, and whether it answers the same way twice, remain the
   * caller's own problem.
@@ -638,6 +656,32 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare function briefToTrace(source: Brief): string;
 
+ /**
+  * 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
+  * ```
+  */
+ export declare function captureValue(source: unknown, members: readonly string[]): unknown;
+
  /**
   * One external source — what it is called, where it lives, and why it is cited.
   *
@@ -1572,6 +1616,15 @@ import { Subject } from '@orkestrel/reason';
   * 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`.
   *

package/dist/src/core/index.js

@@ -369,6 +369,84 @@ var isBrief = 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
@@ -1163,6 +1241,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`.
@@ -1502,8 +1589,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);
@@ -1569,6 +1658,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`.
 *
@@ -1879,7 +1977,15 @@ var BriefCompiler = class {
 	}
 	gate(source) {
 		this.#refuseDestroyed();
-		const ruled = attempt(() => this.#own(this.#reason.reason(briefToSubject(source), gateDefinition())));
+		const ruled = 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"
@@ -1902,14 +2008,30 @@ var BriefCompiler = class {
 	#snapshot(input) {
 		return freezeDeep(structuredClone(input));
 	}
-	#own(value) {
+	#own(value, members) {
 		const cloned = 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 = attempt(() => this.#own(this.#interpret.interpret(text)));
+			const read = attempt(() => this.#own(this.#interpret.interpret(text), members));
 			if (read.success && isInterpretation(read.value)) {
 				stages.push(Object.freeze({
 					stage: "interpret",
@@ -1934,7 +2056,8 @@ var BriefCompiler = class {
 		const supplied = input.interpretation;
 		if (supplied === void 0 || isInterpretation(supplied)) return supplied;
 		const live = raw.interpretation;
-		if (live !== void 0 && isInterpretation(live)) return freezeDeep(live);
+		const captured = attempt(() => captureValue(live, members));
+		if (captured.success && isInterpretation(captured.value)) return captured.value;
 		const message = "The supplied interpretation does not satisfy the published shape";
 		stages.push(Object.freeze({
 			stage: "interpret",
@@ -1958,7 +2081,7 @@ var BriefCompiler = class {
 			code: "BLOCKED",
 			message: `Gate refused: ${unready.join(", ")}`
 		};
-		if (!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",
@@ -2092,6 +2215,6 @@ function createBriefContract() {
 	return createContract(briefShape);
 }
 //#endregion
-export { BLANK_PATTERN, BriefCompiler, BriefError, BriefManager, DEFAULT_BRIEF_TURNS, GATE_ID, LINE_BREAK_PATTERN, OUTPUT_FORMATS, RISK_SEVERITIES, SINGLE_LINE_PATTERN, TASK_DOMAINS, TASK_OPERATIONS, assertBrief, brief, briefShape, briefToContent, briefToDispatch, briefToGoal, briefToHash, briefToMarkdown, briefToSubject, briefToTrace, citation, citationShape, countSentences, createBriefCompiler, createBriefContract, createBriefManager, deriveGaps, deriveGivens, deriveStatement, deriveTask, errorToMessage, example, exampleShape, exampleToLines, findBlockingGaps, findManifestOverlaps, findUngrantedAuthority, findUnmetRules, findUnpairedGaps, freezeBranch, freezeDeep, gap, gapShape, gateDefinition, given, givenShape, isBrief, isBriefError, isCitation, isExample, isGap, isGiven, isLine, isManifest, isOutcome, isOutput, isOutputFormat, isProof, isReference, isRisk, isRiskSeverity, isTask, isTaskDomain, isTaskOperation, isText, lineShape, manifest, manifestShape, outcome, outcomeShape, output, outputShape, parseBrief, pinBrief, proof, proofShape, reference, referenceShape, risk, riskShape, snapshotBrief, task, taskShape, textShape, validateBrief };
+export { BLANK_PATTERN, BriefCompiler, BriefError, BriefManager, DEFAULT_BRIEF_TURNS, GATE_ID, LINE_BREAK_PATTERN, OUTPUT_FORMATS, RISK_SEVERITIES, SINGLE_LINE_PATTERN, TASK_DOMAINS, TASK_OPERATIONS, assertBrief, brief, briefShape, briefToContent, briefToDispatch, briefToGoal, briefToHash, briefToMarkdown, briefToSubject, briefToTrace, captureValue, citation, citationShape, countSentences, createBriefCompiler, createBriefContract, createBriefManager, deriveGaps, deriveGivens, deriveStatement, deriveTask, errorToMessage, example, exampleShape, exampleToLines, findBlockingGaps, findManifestOverlaps, findUngrantedAuthority, findUnmetRules, findUnpairedGaps, freezeBranch, freezeDeep, gap, gapShape, gateDefinition, given, givenShape, isBrief, isBriefError, isCitation, isExample, isGap, isGiven, isLine, isManifest, isOutcome, isOutput, isOutputFormat, isProof, isReference, isRisk, isRiskSeverity, isTask, isTaskDomain, isTaskOperation, isText, lineShape, manifest, manifestShape, outcome, outcomeShape, output, outputShape, parseBrief, pinBrief, proof, proofShape, reference, referenceShape, risk, riskShape, snapshotBrief, task, taskShape, textShape, validateBrief };
 
 //# sourceMappingURL=index.js.map