@orkestrel/brief 0.0.1 → 0.0.2

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

@@ -19,7 +19,6 @@ import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { ReasonInterface } from '@orkestrel/reason';
 import { ReasonValidationResult } from '@orkestrel/reason';
-import { RuleResult } from '@orkestrel/reason';
 import { StringShape } from '@orkestrel/contract';
 import { Subject } from '@orkestrel/reason';
 
@@ -180,11 +179,11 @@ import { Subject } from '@orkestrel/reason';
   * - 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`.
-  * - Only the VERDICT is shape-checked, because `ReasonInterface.reason` publishes a union
-  *   this package must narrow. The `Interpretation` is owned and not validated: it is a
-  *   14-member foreign interface with no published guard, and only four of its members are
-  *   read, inside contained code. That asymmetry is deliberate — guarding it would trade a
-  *   contained failure for a wrong refusal against a valid engine.
+  * - 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.
   * - 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.
@@ -1371,31 +1370,6 @@ import { Subject } from '@orkestrel/reason';
  /** `true` when the value is a non-empty string holding no line terminator. */
  export declare const isLine: Guard<string>;
 
- /**
-  * `true` when the value is a well-formed reasons `LogicalResult`.
-  *
-  * @remarks
-  * The gate's reasoner is supplied by the caller through `BriefCompilerOptions.reason`, so its
-  * return value is FOREIGN data no matter how well-typed the interface is. `BriefCompiler`
-  * dereferences `reasoning`, `conclusion`, and `rules`; checking one field left a malformed
-  * result to throw a raw `TypeError` out of `compile`, from the very code that contains stage
-  * failures. Total: returns `false` for `undefined`, `null`, and every off-shape value.
-  *
-  * Checks the WHOLE published shape rather than only the three members read today, because a
-  * guard that narrows to `LogicalResult` while ignoring four of its members is unsound.
-  *
-  * OPEN on unknown keys, deliberately. The exact-record combinator this file uses elsewhere
-  * refuses a value a FOREIGN interface permits: `LogicalResult` is a TypeScript interface,
-  * so a conforming reasoner returning a richer result is still returning a `LogicalResult`. An
-  * exact check refused it and failed the gate closed on a valid engine — trading a loud crash
-  * for a wrong refusal, which is the worse of the two. Exactness belongs on records this
-  * package OWNS, where an extra key means the caller misunderstood the contract.
-  *
-  * `count` is checked as a number rather than an integer for the same reason: the published
-  * type says `number`, and narrowing past a foreign contract is the same mistake.
-  */
- export declare const isLogicalVerdict: Guard<LogicalResult>;
-
  /**
   * `true` when the value is a well-formed `Manifest`.
   *
@@ -1404,22 +1378,6 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare const isManifest: Guard<Manifest>;
 
- /**
-  * `true` when the value is a non-null object whose named members can be read.
-  *
-  * @remarks
-  * Wider than the contract package's plain-record guard, which refuses any object carrying its
-  * own prototype — a class instance among them. The verdict guards below narrow FOREIGN
-  * interfaces, and an
-  * interface is satisfied by a class instance as readily as by a literal — refusing one is the
-  * same narrowing-past-the-contract mistake that made an exact-record verdict guard fail the
-  * gate closed on a valid engine.
-  *
-  * Arrays are excluded because no interface this narrows is an array, and admitting one would
-  * let index access stand in for member access.
-  */
- export declare const isObject: Guard<Record<string, unknown>>;
-
  /** `true` when the value is a well-formed `Outcome` — `rank` a positive integer. */
  export declare const isOutcome: Guard<Outcome>;
 
@@ -1441,15 +1399,6 @@ import { Subject } from '@orkestrel/reason';
  /** `true` when the value is one of the three `RiskSeverity` literals. */
  export declare const isRiskSeverity: Guard<RiskSeverity>;
 
- /**
-  * `true` when the value is a well-formed reasons `RuleResult`.
-  *
-  * @remarks
-  * `@orkestrel/reason` publishes the type but no guard for it, and `BriefCompiler` reads these
-  * off a BORROWED engine's return value, so the shape has to be checked rather than trusted.
-  */
- export declare const isRuleVerdict: Guard<RuleResult>;
-
  /** `true` when the value is a well-formed `Task` — both vocabularies closed, statement one line. */
  export declare const isTask: Guard<Task>;
 

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

@@ -19,7 +19,6 @@ import { ObjectShape } from '@orkestrel/contract';
 import { OptionalShape } from '@orkestrel/contract';
 import { ReasonInterface } from '@orkestrel/reason';
 import { ReasonValidationResult } from '@orkestrel/reason';
-import { RuleResult } from '@orkestrel/reason';
 import { StringShape } from '@orkestrel/contract';
 import { Subject } from '@orkestrel/reason';
 
@@ -180,11 +179,11 @@ import { Subject } from '@orkestrel/reason';
   * - 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`.
-  * - Only the VERDICT is shape-checked, because `ReasonInterface.reason` publishes a union
-  *   this package must narrow. The `Interpretation` is owned and not validated: it is a
-  *   14-member foreign interface with no published guard, and only four of its members are
-  *   read, inside contained code. That asymmetry is deliberate — guarding it would trade a
-  *   contained failure for a wrong refusal against a valid engine.
+  * - 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.
   * - 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.
@@ -1371,31 +1370,6 @@ import { Subject } from '@orkestrel/reason';
  /** `true` when the value is a non-empty string holding no line terminator. */
  export declare const isLine: Guard<string>;
 
- /**
-  * `true` when the value is a well-formed reasons `LogicalResult`.
-  *
-  * @remarks
-  * The gate's reasoner is supplied by the caller through `BriefCompilerOptions.reason`, so its
-  * return value is FOREIGN data no matter how well-typed the interface is. `BriefCompiler`
-  * dereferences `reasoning`, `conclusion`, and `rules`; checking one field left a malformed
-  * result to throw a raw `TypeError` out of `compile`, from the very code that contains stage
-  * failures. Total: returns `false` for `undefined`, `null`, and every off-shape value.
-  *
-  * Checks the WHOLE published shape rather than only the three members read today, because a
-  * guard that narrows to `LogicalResult` while ignoring four of its members is unsound.
-  *
-  * OPEN on unknown keys, deliberately. The exact-record combinator this file uses elsewhere
-  * refuses a value a FOREIGN interface permits: `LogicalResult` is a TypeScript interface,
-  * so a conforming reasoner returning a richer result is still returning a `LogicalResult`. An
-  * exact check refused it and failed the gate closed on a valid engine — trading a loud crash
-  * for a wrong refusal, which is the worse of the two. Exactness belongs on records this
-  * package OWNS, where an extra key means the caller misunderstood the contract.
-  *
-  * `count` is checked as a number rather than an integer for the same reason: the published
-  * type says `number`, and narrowing past a foreign contract is the same mistake.
-  */
- export declare const isLogicalVerdict: Guard<LogicalResult>;
-
  /**
   * `true` when the value is a well-formed `Manifest`.
   *
@@ -1404,22 +1378,6 @@ import { Subject } from '@orkestrel/reason';
   */
  export declare const isManifest: Guard<Manifest>;
 
- /**
-  * `true` when the value is a non-null object whose named members can be read.
-  *
-  * @remarks
-  * Wider than the contract package's plain-record guard, which refuses any object carrying its
-  * own prototype — a class instance among them. The verdict guards below narrow FOREIGN
-  * interfaces, and an
-  * interface is satisfied by a class instance as readily as by a literal — refusing one is the
-  * same narrowing-past-the-contract mistake that made an exact-record verdict guard fail the
-  * gate closed on a valid engine.
-  *
-  * Arrays are excluded because no interface this narrows is an array, and admitting one would
-  * let index access stand in for member access.
-  */
- export declare const isObject: Guard<Record<string, unknown>>;
-
  /** `true` when the value is a well-formed `Outcome` — `rank` a positive integer. */
  export declare const isOutcome: Guard<Outcome>;
 
@@ -1441,15 +1399,6 @@ import { Subject } from '@orkestrel/reason';
  /** `true` when the value is one of the three `RiskSeverity` literals. */
  export declare const isRiskSeverity: Guard<RiskSeverity>;
 
- /**
-  * `true` when the value is a well-formed reasons `RuleResult`.
-  *
-  * @remarks
-  * `@orkestrel/reason` publishes the type but no guard for it, and `BriefCompiler` reads these
-  * off a BORROWED engine's return value, so the shape has to be checked rather than trusted.
-  */
- export declare const isRuleVerdict: Guard<RuleResult>;
-
  /** `true` when the value is a well-formed `Task` — both vocabularies closed, statement one line. */
  export declare const isTask: Guard<Task>;
 

package/dist/src/core/index.js

@@ -1,6 +1,6 @@
-import { andOf, arrayOf, arrayShape, attempt, booleanShape, boundsOf, cloneJSONRecord, createContract, integerShape, isBoolean, isInteger, isNonEmptyString, isNumber, isString, literalOf, literalShape, objectShape, optionalShape, parseJSONAs, recordOf, stringShape } from "@orkestrel/contract";
-import { canonicalize, collapseWhitespace, createInterpret, digestValue } from "@orkestrel/interpret";
-import { atom, compound, createLogicalReasoner, createReason, formatField, logicalDefinition, rule } from "@orkestrel/reason";
+import { andOf, arrayOf, arrayShape, attempt, booleanShape, boundsOf, cloneJSONRecord, createContract, integerShape, isBoolean, isInteger, isNonEmptyString, isString, literalOf, literalShape, objectShape, optionalShape, parseJSONAs, recordOf, stringShape } from "@orkestrel/contract";
+import { canonicalize, collapseWhitespace, createInterpret, digestValue, isInterpretation } from "@orkestrel/interpret";
+import { atom, compound, createLogicalReasoner, createReason, formatField, isLogicalResult, logicalDefinition, rule } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
 /** The twelve `TaskOperation` values, frozen. */
@@ -259,53 +259,6 @@ var isTaskDomain = literalOf(TASK_DOMAINS);
 var isOutputFormat = literalOf(OUTPUT_FORMATS);
 /** `true` when the value is one of the three `RiskSeverity` literals. */
 var isRiskSeverity = literalOf(RISK_SEVERITIES);
-/**
-* `true` when the value is a non-null object whose named members can be read.
-*
-* @remarks
-* Wider than the contract package's plain-record guard, which refuses any object carrying its
-* own prototype — a class instance among them. The verdict guards below narrow FOREIGN
-* interfaces, and an
-* interface is satisfied by a class instance as readily as by a literal — refusing one is the
-* same narrowing-past-the-contract mistake that made an exact-record verdict guard fail the
-* gate closed on a valid engine.
-*
-* Arrays are excluded because no interface this narrows is an array, and admitting one would
-* let index access stand in for member access.
-*/
-var isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/**
-* `true` when the value is a well-formed reasons `RuleResult`.
-*
-* @remarks
-* `@orkestrel/reason` publishes the type but no guard for it, and `BriefCompiler` reads these
-* off a BORROWED engine's return value, so the shape has to be checked rather than trusted.
-*/
-var isRuleVerdict = (value) => isObject(value) && isNonEmptyString(value["id"]) && isBoolean(value["applied"]) && arrayOf(isBoolean)(value["premises"]) && isBoolean(value["conclusion"]);
-/**
-* `true` when the value is a well-formed reasons `LogicalResult`.
-*
-* @remarks
-* The gate's reasoner is supplied by the caller through `BriefCompilerOptions.reason`, so its
-* return value is FOREIGN data no matter how well-typed the interface is. `BriefCompiler`
-* dereferences `reasoning`, `conclusion`, and `rules`; checking one field left a malformed
-* result to throw a raw `TypeError` out of `compile`, from the very code that contains stage
-* failures. Total: returns `false` for `undefined`, `null`, and every off-shape value.
-*
-* Checks the WHOLE published shape rather than only the three members read today, because a
-* guard that narrows to `LogicalResult` while ignoring four of its members is unsound.
-*
-* OPEN on unknown keys, deliberately. The exact-record combinator this file uses elsewhere
-* refuses a value a FOREIGN interface permits: `LogicalResult` is a TypeScript interface,
-* so a conforming reasoner returning a richer result is still returning a `LogicalResult`. An
-* exact check refused it and failed the gate closed on a valid engine — trading a loud crash
-* for a wrong refusal, which is the worse of the two. Exactness belongs on records this
-* package OWNS, where an extra key means the caller misunderstood the contract.
-*
-* `count` is checked as a number rather than an integer for the same reason: the published
-* type says `number`, and narrowing past a foreign contract is the same mistake.
-*/
-var isLogicalVerdict = (value) => isObject(value) && value["reasoning"] === "logical" && isBoolean(value["conclusion"]) && arrayOf(isRuleVerdict)(value["rules"]) && isNumber(value["count"]) && isBoolean(value["success"]) && arrayOf(isString)(value["trace"]) && arrayOf(isString)(value["errors"]);
 /** `true` when the value is a well-formed `Task` — both vocabularies closed, statement one line. */
 var isTask = recordOf({
 	operation: isTaskOperation,
@@ -1834,7 +1787,7 @@ var BriefCompiler = class {
 			return this.#refuse(void 0, void 0, [], void 0, stages, failures);
 		}
 		const owned = taken.value;
-		const interpretation = this.#read(owned, stages, failures);
+		const interpretation = this.#read(owned, input, stages, failures);
 		const drafted = attempt(() => this.#draft(owned, interpretation, this.#unresolved(interpretation, failures)));
 		if (!drafted.success) {
 			const message = errorToMessage(drafted.error);
@@ -1932,7 +1885,7 @@ var BriefCompiler = class {
 			field: "reason"
 		});
 		const verdict = ruled.value;
-		if (!isLogicalVerdict(verdict)) throw new BriefError("GATE_FAILED", "The gate reasoner returned a non-logical result", {
+		if (!isLogicalResult(verdict)) throw new BriefError("GATE_FAILED", "The gate reasoner returned a non-logical result", {
 			stage: "gate",
 			field: "reasoning"
 		});
@@ -1953,22 +1906,39 @@ var BriefCompiler = class {
 		const cloned = attempt(() => structuredClone(value));
 		return freezeDeep(cloned.success ? cloned.value : value);
 	}
-	#read(input, stages, failures) {
+	#read(input, raw, stages, failures) {
 		const text = input.text;
-		if (text === void 0) return input.interpretation;
-		const read = attempt(() => this.#own(this.#interpret.interpret(text)));
-		if (read.success) {
+		if (text !== void 0) {
+			const read = attempt(() => this.#own(this.#interpret.interpret(text)));
+			if (read.success && isInterpretation(read.value)) {
+				stages.push(Object.freeze({
+					stage: "interpret",
+					input: text,
+					output: read.value
+				}));
+				return read.value;
+			}
+			const message = read.success ? "The interpret engine returned a non-interpretation result" : errorToMessage(read.error);
 			stages.push(Object.freeze({
 				stage: "interpret",
 				input: text,
-				output: read.value
+				error: message
+			}));
+			failures.push(Object.freeze({
+				stage: "interpret",
+				code: "INTERPRET_FAILED",
+				message
 			}));
-			return read.value;
+			this.#emitter.emit("error", read.success ? new BriefError("INTERPRET_FAILED", message, { stage: "interpret" }) : read.error);
 		}
-		const message = errorToMessage(read.error);
+		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 message = "The supplied interpretation does not satisfy the published shape";
 		stages.push(Object.freeze({
 			stage: "interpret",
-			input: text,
+			input: "interpretation",
 			error: message
 		}));
 		failures.push(Object.freeze({
@@ -1976,8 +1946,6 @@ var BriefCompiler = class {
 			code: "INTERPRET_FAILED",
 			message
 		}));
-		this.#emitter.emit("error", read.error);
-		return input.interpretation;
 	}
 	#blockage(questions, unready, verdict) {
 		if (questions.length > 0) return {
@@ -1990,7 +1958,7 @@ var BriefCompiler = class {
 			code: "BLOCKED",
 			message: `Gate refused: ${unready.join(", ")}`
 		};
-		if (!isLogicalVerdict(verdict)) return void 0;
+		if (!isLogicalResult(verdict)) return void 0;
 		const refused = verdict.rules.filter((entry) => !entry.conclusion).map((entry) => entry.id).join(", ");
 		if (refused.length === 0) return {
 			stage: "gate",
@@ -2124,6 +2092,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, isLogicalVerdict, isManifest, isObject, isOutcome, isOutput, isOutputFormat, isProof, isReference, isRisk, isRiskSeverity, isRuleVerdict, 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, 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