@orkestrel/brief 0.0.1

package/dist/src/core/index.cjs

@@ -0,0 +1,2219 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _orkestrel_contract = require("@orkestrel/contract");
+let _orkestrel_interpret = require("@orkestrel/interpret");
+let _orkestrel_reason = require("@orkestrel/reason");
+let _orkestrel_emitter = require("@orkestrel/emitter");
+//#region src/core/constants.ts
+/** The twelve `TaskOperation` values, frozen. */
+var TASK_OPERATIONS = Object.freeze([
+	"create",
+	"refactor",
+	"debug",
+	"extract",
+	"migrate",
+	"explain",
+	"review",
+	"optimize",
+	"audit",
+	"test",
+	"document",
+	"plan"
+]);
+/** The eight `TaskDomain` values, frozen. */
+var TASK_DOMAINS = Object.freeze([
+	"code",
+	"writing",
+	"research",
+	"analysis",
+	"design",
+	"data",
+	"ops",
+	"other"
+]);
+/** The five `OutputFormat` values, frozen. */
+var OUTPUT_FORMATS = Object.freeze([
+	"markdown",
+	"json",
+	"code",
+	"diff",
+	"prose"
+]);
+/** The three `RiskSeverity` values, frozen. */
+var RISK_SEVERITIES = Object.freeze([
+	"low",
+	"medium",
+	"high"
+]);
+/**
+* `16` — the default turn cap `briefToGoal` renders.
+*
+* @remarks
+* Domain-qualified so the barrel stays collision-free as sibling modules add their own
+* turn defaults.
+*/
+var DEFAULT_BRIEF_TURNS = 16;
+/** `'gate'` — the id of the `gateDefinition()` logical definition. */
+var GATE_ID = "gate";
+/**
+* Every line terminator a brief field refuses.
+*
+* @remarks
+* The four ECMAScript line terminators, not just `\n`: a renderer that splits on any of
+* them would let the other three forge a markdown row. CRLF leads the alternation so a
+* Windows exemplar splits as ONE break rather than two, which would insert a blank line the
+* caller never wrote. Kept unanchored and stateless — no `g` flag — so `test` never carries
+* `lastIndex` between calls.
+*/
+var LINE_BREAK_PATTERN = /\r\n|[\n\r\u2028\u2029]/;
+/**
+* The positive form of {@link LINE_BREAK_PATTERN}, for the shape DSL.
+*
+* @remarks
+* `stringShape`'s `pattern` must MATCH an accepted value, so the guard's refusal regex
+* cannot be reused directly. Both are derived from one character class, which is what
+* keeps the hand-composed guards and the compiled shapes refusing the same strings.
+*/
+var SINGLE_LINE_PATTERN = /^[^\n\r\u2028\u2029]*$/;
+/**
+* A string of one or more spaces and nothing else.
+*
+* @remarks
+* The one exemplar side `exampleToLines` must NOT pad. CommonMark strips a fully-blank code
+* span to nothing rather than one space from each end, so padding inflates an all-space value
+* while every other value needs the pad to keep its own boundary spaces.
+*
+* `+` rather than `*`, because the EMPTY string is not that case: it has no spaces to
+* preserve, and withholding the pad emitted an empty backtick run that does not close.
+*/
+var BLANK_PATTERN = /^ +$/;
+//#endregion
+//#region src/core/errors.ts
+/**
+* The one error class this package throws.
+*
+* @remarks
+* Throws are reserved for caller misuse: `assertBrief`, `snapshotBrief`, and `pinBrief` on
+* off-contract data throw `INVALID`; any method after `destroy()` throws `DESTROYED`; and `BriefCompiler.gate` throws
+* `GATE_FAILED` when a borrowed reasoner returns a non-logical result. A stage that fails
+* inside `compile` is CONTAINED as a `BriefStageFailure` on the `Briefing` instead.
+*
+* @example
+* ```ts
+* import { BriefError } from '@orkestrel/brief'
+*
+* const error = new BriefError('INVALID', 'Brief failed the exact-record contract', {
+* 	field: 'proofs',
+* })
+* error.code // 'INVALID'
+* error.context // { field: 'proofs' }
+* ```
+*/
+var BriefError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "BriefError";
+		this.code = code;
+		if (context !== void 0) this.context = context;
+	}
+};
+/**
+* Narrow a caught value to a {@link BriefError}.
+*
+* @param value - The caught value to inspect.
+* @returns `true` when `value` is a `BriefError`.
+*
+* @example
+* ```ts
+* import { BriefError, isBriefError } from '@orkestrel/brief'
+*
+* try {
+* 	throw new BriefError('DESTROYED', 'BriefCompiler has been destroyed')
+* } catch (error) {
+* 	if (isBriefError(error)) error.code // 'DESTROYED'
+* }
+* ```
+*/
+function isBriefError(value) {
+	return value instanceof BriefError;
+}
+//#endregion
+//#region src/core/shapers.ts
+/** A single-line string of any length, including empty. */
+var textShape = (0, _orkestrel_contract.stringShape)({ pattern: SINGLE_LINE_PATTERN });
+/** A non-empty single-line string — the shape mirror of `isLine`. */
+var lineShape = (0, _orkestrel_contract.stringShape)({
+	min: 1,
+	pattern: SINGLE_LINE_PATTERN
+});
+/** The `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
+var taskShape = (0, _orkestrel_contract.objectShape)({
+	operation: (0, _orkestrel_contract.literalShape)(TASK_OPERATIONS),
+	domain: (0, _orkestrel_contract.literalShape)(TASK_DOMAINS),
+	statement: lineShape
+}, { description: "What the brief asks for, in one imperative sentence." });
+/** The `Reference` shape — a path and the note that justifies listing it. */
+var referenceShape = (0, _orkestrel_contract.objectShape)({
+	path: lineShape,
+	note: lineShape
+}, { description: "One referenced path and why it is listed." });
+/** The `Manifest` shape — four disjoint reference partitions. */
+var manifestShape = (0, _orkestrel_contract.objectShape)({
+	read: (0, _orkestrel_contract.arrayShape)(referenceShape),
+	edit: (0, _orkestrel_contract.arrayShape)(referenceShape),
+	locked: (0, _orkestrel_contract.arrayShape)(referenceShape),
+	forbidden: (0, _orkestrel_contract.arrayShape)(referenceShape)
+}, { description: "The four disjoint file partitions of a brief." });
+/** The `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
+var outcomeShape = (0, _orkestrel_contract.objectShape)({
+	rank: (0, _orkestrel_contract.integerShape)({ min: 1 }),
+	text: lineShape,
+	required: (0, _orkestrel_contract.booleanShape)()
+}, { description: "One ranked outcome — a result, never a step." });
+/** The `Given` shape — one categorized context fact. */
+var givenShape = (0, _orkestrel_contract.objectShape)({
+	category: lineShape,
+	name: lineShape,
+	value: textShape
+}, { description: "One context fact handed to the executor." });
+/** The `Example` shape — one input to output exemplar. */
+var exampleShape = (0, _orkestrel_contract.objectShape)({
+	input: (0, _orkestrel_contract.stringShape)({ min: 1 }),
+	output: (0, _orkestrel_contract.stringShape)({ min: 1 }),
+	note: (0, _orkestrel_contract.optionalShape)(lineShape)
+}, { description: "One input to output exemplar." });
+/** The `Citation` shape — a name, a locator, and why the source is cited. */
+var citationShape = (0, _orkestrel_contract.objectShape)({
+	name: lineShape,
+	url: lineShape,
+	note: lineShape
+}, { description: "One external source; list order is the trust order." });
+/** The `Gap` shape — an unknown, whether it blocks, and the candidates that would close it. */
+var gapShape = (0, _orkestrel_contract.objectShape)({
+	field: lineShape,
+	question: lineShape,
+	blocking: (0, _orkestrel_contract.booleanShape)(),
+	candidates: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(lineShape))
+}, { description: "One unresolved decision; blocking means the gate fails closed." });
+/** The `Risk` shape — a closed severity, the risk, and its mitigation. */
+var riskShape = (0, _orkestrel_contract.objectShape)({
+	severity: (0, _orkestrel_contract.literalShape)(RISK_SEVERITIES),
+	text: lineShape,
+	mitigation: lineShape
+}, { description: "One pre-empted risk and the mitigation that answers it." });
+/** The `Output` shape — a closed format plus its optional refinements. */
+var outputShape = (0, _orkestrel_contract.objectShape)({
+	format: (0, _orkestrel_contract.literalShape)(OUTPUT_FORMATS),
+	sections: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(lineShape)),
+	include: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(lineShape)),
+	exclude: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)(lineShape))
+}, { description: "The closed shape of the deliverable." });
+/** The `Proof` shape — the claim and the command that settles it. */
+var proofShape = (0, _orkestrel_contract.objectShape)({
+	text: lineShape,
+	command: lineShape
+}, { description: "One mechanical, transcript-provable check." });
+/**
+* The whole `Brief` shape, section shapes composed.
+*
+* @remarks
+* `trace` and `hash` are optional because `pinBrief` fills them; an unpinned draft is
+* on-contract without them.
+*/
+var briefShape = (0, _orkestrel_contract.objectShape)({
+	task: taskShape,
+	authority: (0, _orkestrel_contract.arrayShape)(referenceShape),
+	manifest: manifestShape,
+	outcomes: (0, _orkestrel_contract.arrayShape)(outcomeShape),
+	rules: (0, _orkestrel_contract.arrayShape)(lineShape),
+	invariants: (0, _orkestrel_contract.arrayShape)(lineShape),
+	givens: (0, _orkestrel_contract.arrayShape)(givenShape),
+	examples: (0, _orkestrel_contract.arrayShape)(exampleShape),
+	assumptions: (0, _orkestrel_contract.arrayShape)(lineShape),
+	citations: (0, _orkestrel_contract.arrayShape)(citationShape),
+	gaps: (0, _orkestrel_contract.arrayShape)(gapShape),
+	risks: (0, _orkestrel_contract.arrayShape)(riskShape),
+	output: outputShape,
+	proofs: (0, _orkestrel_contract.arrayShape)(proofShape),
+	trace: (0, _orkestrel_contract.optionalShape)(lineShape),
+	hash: (0, _orkestrel_contract.optionalShape)(lineShape)
+}, { description: "The closed execution contract one agent can run with no interpretation left." });
+//#endregion
+//#region src/core/validators.ts
+/**
+* `true` when the value is a string holding no line terminator, empty included.
+*
+* @remarks
+* `briefToMarkdown` renders each brief field as ONE markdown row, so a field carrying a
+* line break would forge a heading or an extra manifest row — which is how a rendered
+* prompt and `briefToDispatch`'s path sets could disagree about the same brief.
+*/
+var isText = (value) => (0, _orkestrel_contract.isString)(value) && !LINE_BREAK_PATTERN.test(value);
+/** `true` when the value is a non-empty string holding no line terminator. */
+var isLine = (0, _orkestrel_contract.andOf)(_orkestrel_contract.isNonEmptyString, isText);
+/** `true` when the value is one of the twelve `TaskOperation` literals. */
+var isTaskOperation = (0, _orkestrel_contract.literalOf)(TASK_OPERATIONS);
+/** `true` when the value is one of the eight `TaskDomain` literals. */
+var isTaskDomain = (0, _orkestrel_contract.literalOf)(TASK_DOMAINS);
+/** `true` when the value is one of the five `OutputFormat` literals. */
+var isOutputFormat = (0, _orkestrel_contract.literalOf)(OUTPUT_FORMATS);
+/** `true` when the value is one of the three `RiskSeverity` literals. */
+var isRiskSeverity = (0, _orkestrel_contract.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) && (0, _orkestrel_contract.isNonEmptyString)(value["id"]) && (0, _orkestrel_contract.isBoolean)(value["applied"]) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isBoolean)(value["premises"]) && (0, _orkestrel_contract.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" && (0, _orkestrel_contract.isBoolean)(value["conclusion"]) && (0, _orkestrel_contract.arrayOf)(isRuleVerdict)(value["rules"]) && (0, _orkestrel_contract.isNumber)(value["count"]) && (0, _orkestrel_contract.isBoolean)(value["success"]) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(value["trace"]) && (0, _orkestrel_contract.arrayOf)(_orkestrel_contract.isString)(value["errors"]);
+/** `true` when the value is a well-formed `Task` — both vocabularies closed, statement one line. */
+var isTask = (0, _orkestrel_contract.recordOf)({
+	operation: isTaskOperation,
+	domain: isTaskDomain,
+	statement: isLine
+});
+/** `true` when the value is a well-formed `Reference` — both members required, both single-line. */
+var isReference = (0, _orkestrel_contract.recordOf)({
+	path: isLine,
+	note: isLine
+});
+/**
+* `true` when the value is a well-formed `Manifest`.
+*
+* @remarks
+* Partition presence only — disjointness is `validateBrief`'s semantic pass.
+*/
+var isManifest = (0, _orkestrel_contract.recordOf)({
+	read: (0, _orkestrel_contract.arrayOf)(isReference),
+	edit: (0, _orkestrel_contract.arrayOf)(isReference),
+	locked: (0, _orkestrel_contract.arrayOf)(isReference),
+	forbidden: (0, _orkestrel_contract.arrayOf)(isReference)
+});
+/** `true` when the value is a well-formed `Outcome` — `rank` a positive integer. */
+var isOutcome = (0, _orkestrel_contract.recordOf)({
+	rank: (0, _orkestrel_contract.andOf)(_orkestrel_contract.isInteger, (0, _orkestrel_contract.boundsOf)(1)),
+	text: isLine,
+	required: _orkestrel_contract.isBoolean
+});
+/** `true` when the value is a well-formed `Given` — `value` may be empty but stays one line. */
+var isGiven = (0, _orkestrel_contract.recordOf)({
+	category: isLine,
+	name: isLine,
+	value: isText
+});
+/**
+* `true` when the value is a well-formed `Example`.
+*
+* @remarks
+* An exemplar's two sides are the ONLY members a brief lets span lines, because they
+* carry code. `briefToMarkdown` fences them rather than rendering them as a row.
+*/
+var isExample = (0, _orkestrel_contract.recordOf)({
+	input: _orkestrel_contract.isNonEmptyString,
+	output: _orkestrel_contract.isNonEmptyString,
+	note: isLine
+}, ["note"]);
+/** `true` when the value is a well-formed `Citation` — all three members single-line. */
+var isCitation = (0, _orkestrel_contract.recordOf)({
+	name: isLine,
+	url: isLine,
+	note: isLine
+});
+/** `true` when the value is a well-formed `Gap`. */
+var isGap = (0, _orkestrel_contract.recordOf)({
+	field: isLine,
+	question: isLine,
+	blocking: _orkestrel_contract.isBoolean,
+	candidates: (0, _orkestrel_contract.arrayOf)(isLine)
+}, ["candidates"]);
+/** `true` when the value is a well-formed `Risk` — `severity` on the closed vocabulary. */
+var isRisk = (0, _orkestrel_contract.recordOf)({
+	severity: isRiskSeverity,
+	text: isLine,
+	mitigation: isLine
+});
+/** `true` when the value is a well-formed `Output` — `format` on the closed vocabulary. */
+var isOutput = (0, _orkestrel_contract.recordOf)({
+	format: isOutputFormat,
+	sections: (0, _orkestrel_contract.arrayOf)(isLine),
+	include: (0, _orkestrel_contract.arrayOf)(isLine),
+	exclude: (0, _orkestrel_contract.arrayOf)(isLine)
+}, [
+	"sections",
+	"include",
+	"exclude"
+]);
+/** `true` when the value is a well-formed `Proof`. */
+var isProof = (0, _orkestrel_contract.recordOf)({
+	text: isLine,
+	command: isLine
+});
+/**
+* `true` when the value satisfies the whole exact-record `Brief` contract.
+*
+* @remarks
+* Every section must be present; an extra key fails. `trace` and `hash` are the only
+* optional members, because `pinBrief` rather than the author fills them.
+*/
+var isBrief = (0, _orkestrel_contract.recordOf)({
+	task: isTask,
+	authority: (0, _orkestrel_contract.arrayOf)(isReference),
+	manifest: isManifest,
+	outcomes: (0, _orkestrel_contract.arrayOf)(isOutcome),
+	rules: (0, _orkestrel_contract.arrayOf)(isLine),
+	invariants: (0, _orkestrel_contract.arrayOf)(isLine),
+	givens: (0, _orkestrel_contract.arrayOf)(isGiven),
+	examples: (0, _orkestrel_contract.arrayOf)(isExample),
+	assumptions: (0, _orkestrel_contract.arrayOf)(isLine),
+	citations: (0, _orkestrel_contract.arrayOf)(isCitation),
+	gaps: (0, _orkestrel_contract.arrayOf)(isGap),
+	risks: (0, _orkestrel_contract.arrayOf)(isRisk),
+	output: isOutput,
+	proofs: (0, _orkestrel_contract.arrayOf)(isProof),
+	trace: isLine,
+	hash: isLine
+}, ["trace", "hash"]);
+//#endregion
+//#region src/core/cloners.ts
+/**
+* Return a deeply owned, deeply frozen copy of a brief, refusing anything off-contract.
+*
+* @remarks
+* The one reading boundary this package has, used by the pin, the registry, and every
+* projection. It matters twice over. A brief built from caller collections ADOPTS those
+* arrays, so a later `outcomes.push` would change content a hash already described. And a
+* caller's object may answer differently on each read, so validating one reading and
+* rendering from a second let a brief that passed the contract render a row it does not
+* contain — this takes ONE reading, validates that, and freezes it.
+*
+* `cloneJSONRecord` is `@orkestrel/contract`'s primitive rather than the ambient
+* `structuredClone`: it deep-freezes, it refuses a value JSON cannot express, and it is a
+* captured import rather than a mutable global. The result is a null-prototype record, so
+* compare it structurally rather than by prototype.
+*
+* This file imports no sibling helper, which is what lets `helpers.ts` consume it without a
+* module cycle.
+*
+* @param source - The brief to snapshot.
+* @returns A deeply frozen `Brief` sharing no reference with `source`.
+* @throws {@link BriefError} `INVALID` when the value is off-contract or JSON cannot express it.
+*
+* @example
+* ```ts
+* import { brief, outcome, snapshotBrief, task } from '@orkestrel/brief'
+*
+* const outcomes = [outcome(1, 'shipped')]
+* const owned = snapshotBrief(brief(task('plan', 'ops', 'Plan the release.'), { outcomes }))
+* owned.outcomes === outcomes // false — the alias is broken
+* Object.isFrozen(owned.outcomes) // true
+* ```
+*/
+function snapshotBrief(source) {
+	const owned = (0, _orkestrel_contract.attempt)(() => (0, _orkestrel_contract.cloneJSONRecord)(source));
+	if (!owned.success || !isBrief(owned.value)) throw new BriefError("INVALID", "Brief carries data that cannot be read as one value", { field: "brief" });
+	return owned.value;
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Build a `Task`.
+*
+* @param operation - What the brief asks for, from the closed operation vocabulary.
+* @param domain - The subject matter, from the closed domain vocabulary.
+* @param statement - One imperative sentence naming the object of the work.
+* @returns A fresh `Task`.
+*
+* @example
+* ```ts
+* import { task } from '@orkestrel/brief'
+*
+* task('refactor', 'code', 'Refactor useForm to native browser form APIs.')
+* ```
+*/
+function task(operation, domain, statement) {
+	return {
+		operation,
+		domain,
+		statement
+	};
+}
+/**
+* Build a `Reference`.
+*
+* @param path - The referenced path or glob.
+* @param note - Why the path is listed.
+* @returns A fresh `Reference`.
+*
+* @example
+* ```ts
+* import { reference } from '@orkestrel/brief'
+*
+* reference('AGENTS.md', 'project law') // { path: 'AGENTS.md', note: 'project law' }
+* ```
+*/
+function reference(path, note) {
+	return {
+		path,
+		note
+	};
+}
+/**
+* Build a `Manifest`, defaulting every absent partition to an empty list.
+*
+* @param partitions - The partitions to fill; a partial literal is enough.
+* @returns A fresh `Manifest` with all four partitions present.
+*
+* @example
+* ```ts
+* import { manifest, reference } from '@orkestrel/brief'
+*
+* manifest({ edit: [reference('src/core/helpers.ts', 'implementation')] })
+* ```
+*/
+function manifest(partitions) {
+	return {
+		read: partitions?.read ?? [],
+		edit: partitions?.edit ?? [],
+		locked: partitions?.locked ?? [],
+		forbidden: partitions?.forbidden ?? []
+	};
+}
+/**
+* Build an `Outcome`.
+*
+* @param rank - The one-based rank; lower ranks matter more.
+* @param text - The result, never a step.
+* @param required - Whether the outcome gates "done"; defaults to `true`.
+* @returns A fresh `Outcome`.
+*
+* @example
+* ```ts
+* import { outcome } from '@orkestrel/brief'
+*
+* outcome(1, 'useForm uses native FormData with no behavior change') // required: true
+* outcome(2, 'the diff stays under 200 lines', false)
+* ```
+*/
+function outcome(rank, text, required = true) {
+	return {
+		rank,
+		text,
+		required
+	};
+}
+/**
+* Build a `Given`.
+*
+* @param category - The kind of fact — a convention, a version, a constraint.
+* @param name - The fact's name.
+* @param value - The fact's value, already rendered as text.
+* @returns A fresh `Given`.
+*
+* @example
+* ```ts
+* import { given } from '@orkestrel/brief'
+*
+* given('convention', 'indentation', 'tabs')
+* ```
+*/
+function given(category, name, value) {
+	return {
+		category,
+		name,
+		value
+	};
+}
+/**
+* Build an `Example`.
+*
+* @param input - The exemplar input.
+* @param result - The expected output for that input.
+* @param note - Optional detail; the key is OMITTED when absent.
+* @returns A fresh `Example`.
+*
+* @example
+* ```ts
+* import { example } from '@orkestrel/brief'
+*
+* example('<input required>', 'validity read from el.validity')
+* ```
+*/
+function example(input, result, note) {
+	return note === void 0 ? {
+		input,
+		output: result
+	} : {
+		input,
+		output: result,
+		note
+	};
+}
+/**
+* Build a `Citation`.
+*
+* @param name - The source's display name.
+* @param url - Where the source lives.
+* @param note - Why the source is cited.
+* @returns A fresh `Citation`.
+*
+* @example
+* ```ts
+* import { citation } from '@orkestrel/brief'
+*
+* citation(
+* 	'MDN Constraint Validation',
+* 	'https://developer.mozilla.org/',
+* 	'the native validity behavior being adopted',
+* )
+* ```
+*/
+function citation(name, url, note) {
+	return {
+		name,
+		url,
+		note
+	};
+}
+/**
+* Build a `Gap`.
+*
+* @param field - The brief section the unknown belongs to.
+* @param question - The question that would close it.
+* @param overrides - Optional `blocking` (defaults `false`) and `candidates`; an absent
+*   `candidates` key is OMITTED entirely.
+* @returns A fresh `Gap`.
+*
+* @example
+* ```ts
+* import { gap } from '@orkestrel/brief'
+*
+* gap('rules', 'Should validation message wording change?') // blocking: false
+* gap('output', 'Diff or full files?', { blocking: true, candidates: ['diff', 'code'] })
+* ```
+*/
+function gap(field, question, overrides) {
+	const blocking = overrides?.blocking ?? false;
+	return overrides?.candidates === void 0 ? {
+		field,
+		question,
+		blocking
+	} : {
+		field,
+		question,
+		blocking,
+		candidates: overrides.candidates
+	};
+}
+/**
+* Build a `Risk`.
+*
+* @param severity - The closed severity.
+* @param text - What could go wrong.
+* @param mitigation - What answers it.
+* @returns A fresh `Risk`.
+*
+* @example
+* ```ts
+* import { risk } from '@orkestrel/brief'
+*
+* risk('medium', 'native validation differs subtly', 'assert message and state in tests')
+* ```
+*/
+function risk(severity, text, mitigation) {
+	return {
+		severity,
+		text,
+		mitigation
+	};
+}
+/**
+* Build an `Output`.
+*
+* @param format - The closed deliverable format.
+* @param overrides - Optional `sections` / `include` / `exclude`; absent keys are OMITTED.
+* @returns A fresh `Output`.
+*
+* @example
+* ```ts
+* import { output } from '@orkestrel/brief'
+*
+* output('markdown') // { format: 'markdown' }
+* output('diff', { include: ['updated useForm.ts'] })
+* ```
+*/
+function output(format, overrides) {
+	return {
+		format,
+		...overrides?.sections === void 0 ? {} : { sections: overrides.sections },
+		...overrides?.include === void 0 ? {} : { include: overrides.include },
+		...overrides?.exclude === void 0 ? {} : { exclude: overrides.exclude }
+	};
+}
+/**
+* Build a `Proof`.
+*
+* @param text - What the check settles.
+* @param command - The command whose exit signal settles it.
+* @returns A fresh `Proof`.
+*
+* @example
+* ```ts
+* import { proof } from '@orkestrel/brief'
+*
+* proof('type-check and lint pass', 'npm run check')
+* ```
+*/
+function proof(text, command) {
+	return {
+		text,
+		command
+	};
+}
+/**
+* Build a `Brief` from a `Task` plus section overrides.
+*
+* @param subject - The task the brief is about.
+* @param overrides - Any sections to fill; every absent collection defaults to `[]`,
+*   `output` defaults to `output('markdown')`, and `trace` / `hash` stay OMITTED so
+*   `pinBrief` can fill them.
+* @returns A fresh, unpinned `Brief`.
+*
+* @example
+* ```ts
+* import { brief, outcome, proof, task } from '@orkestrel/brief'
+*
+* brief(task('audit', 'code', 'Audit the barrel for undocumented exports.'), {
+* 	outcomes: [outcome(1, 'every export appears in the guide')],
+* 	proofs: [proof('parity passes', 'npm run test:guides')],
+* })
+* ```
+*/
+function brief(subject, overrides) {
+	return {
+		task: subject,
+		authority: overrides?.authority ?? [],
+		manifest: overrides?.manifest ?? manifest(),
+		outcomes: overrides?.outcomes ?? [],
+		rules: overrides?.rules ?? [],
+		invariants: overrides?.invariants ?? [],
+		givens: overrides?.givens ?? [],
+		examples: overrides?.examples ?? [],
+		assumptions: overrides?.assumptions ?? [],
+		citations: overrides?.citations ?? [],
+		gaps: overrides?.gaps ?? [],
+		risks: overrides?.risks ?? [],
+		output: overrides?.output ?? output("markdown"),
+		proofs: overrides?.proofs ?? []
+	};
+}
+/**
+* Build the fail-closed readiness gate as a reasons `LogicalDefinition`.
+*
+* @remarks
+* Six readiness rules each derive one named fact from `briefToSubject`'s measures, and a
+* final `ready` rule conjoins all six. Forward chaining reports the LAST rule's
+* conclusion, so `LogicalResult.conclusion` is exactly `ready`.
+*
+* The gate takes NO parameters, and that is deliberate rather than unfinished. The
+* reasoner overlays every derived fact into one flat namespace, so a caller rule named
+* for a readiness fact overwrites it and `ready` then conjoins a fact no base rule
+* proved — a refusal silently becomes a pass. Readiness is this package's contract, not
+* a caller setting. A caller who needs different readiness composes their own
+* `LogicalDefinition` over `briefToSubject` and evaluates it on their own reasoner; both
+* are exported for exactly that, and neither can reach this definition.
+*
+* @returns A fresh `LogicalDefinition` with id `GATE_ID`.
+*
+* @example
+* ```ts
+* import { briefToSubject, gateDefinition } from '@orkestrel/brief'
+* import { createLogicalReasoner, createReason } from '@orkestrel/reason'
+*
+* const reason = createReason({ reasoners: [createLogicalReasoner()] })
+* const verdict = reason.reason(briefToSubject(pinned), gateDefinition())
+* reason.destroy()
+* ```
+*/
+function gateDefinition() {
+	const readiness = [
+		(0, _orkestrel_reason.rule)("specified", [(0, _orkestrel_reason.atom)("blocking", "equals", 0)], (0, _orkestrel_reason.atom)("specified", "equals", true)),
+		(0, _orkestrel_reason.rule)("aimed", [(0, _orkestrel_reason.compound)("and", [(0, _orkestrel_reason.atom)("outcomes", "above", 0), (0, _orkestrel_reason.atom)("required", "above", 0)])], (0, _orkestrel_reason.atom)("aimed", "equals", true)),
+		(0, _orkestrel_reason.rule)("proven", [(0, _orkestrel_reason.atom)("proofs", "above", 0)], (0, _orkestrel_reason.atom)("proven", "equals", true)),
+		(0, _orkestrel_reason.rule)("disjoint", [(0, _orkestrel_reason.atom)("overlaps", "equals", 0)], (0, _orkestrel_reason.atom)("disjoint", "equals", true)),
+		(0, _orkestrel_reason.rule)("granted", [(0, _orkestrel_reason.atom)("ungranted", "equals", 0)], (0, _orkestrel_reason.atom)("granted", "equals", true)),
+		(0, _orkestrel_reason.rule)("single", [(0, _orkestrel_reason.atom)("sentences", "equals", 1)], (0, _orkestrel_reason.atom)("single", "equals", true))
+	];
+	return (0, _orkestrel_reason.logicalDefinition)(GATE_ID, "Brief readiness", [...readiness, (0, _orkestrel_reason.rule)("ready", [(0, _orkestrel_reason.compound)("and", readiness.map((entry) => (0, _orkestrel_reason.atom)(entry.id, "equals", true)))], (0, _orkestrel_reason.atom)("ready", "equals", true))]);
+}
+/**
+* The readiness rules a brief fails, computed directly from its own measures.
+*
+* @remarks
+* The gate's decision, in code. `gateDefinition()` states the same six rules as data for a
+* reasoner to narrate, and a narration is not a decision: `BriefCompilerOptions.reason` lets a
+* caller supply the engine, and an engine that answers "met" to everything would otherwise
+* emit a brief with no proofs. `compile` refuses on THIS and keeps the verdict for its
+* trace, so a supplied engine can add detail and never remove a refusal.
+*
+* The two must agree. `tests/src/core/helpers.test.ts` drives both over one value set, which
+* is what stops the data and the code from drifting apart.
+*
+* @param source - The brief to measure.
+* @returns The unmet rule ids, in gate order; empty when the brief is ready.
+*
+* @example
+* ```ts
+* import { brief, findUnmetRules, outcome, proof, task } from '@orkestrel/brief'
+*
+* findUnmetRules(brief(task('plan', 'ops', 'Plan the release.'))) // ['aimed', 'proven']
+* findUnmetRules(
+* 	brief(task('plan', 'ops', 'Plan the release.'), {
+* 		outcomes: [outcome(1, 'shipped')],
+* 		proofs: [proof('x', 'npm test')],
+* 	}),
+* ) // []
+* ```
+*/
+function findUnmetRules(source) {
+	const unready = [];
+	if (findBlockingGaps(source).length !== 0) unready.push("specified");
+	if (source.outcomes.length === 0 || source.outcomes.filter((entry) => entry.required).length === 0) unready.push("aimed");
+	if (source.proofs.length === 0) unready.push("proven");
+	if (findManifestOverlaps(source).length !== 0) unready.push("disjoint");
+	if (findUngrantedAuthority(source).length !== 0) unready.push("granted");
+	if (countSentences(source.task.statement) !== 1) unready.push("single");
+	return unready;
+}
+/**
+* Count the sentences a statement holds.
+*
+* @remarks
+* A terminator run (`.`, `!`, `?`) followed by whitespace or the end of the text closes one
+* sentence, and a trailing run with no terminator closes one more.
+*
+* LIMIT, stated because it decides a gate: an embedded abbreviation reads as a boundary, so
+* `'Ask Dr. Smith'` and `'Compare React vs. Vue'` count TWO and the `single` rule refuses
+* them. Rewrite the statement without the abbreviation — a brief's statement is one
+* imperative sentence naming the object of the work, and it rarely needs one.
+*
+* This is inherent rather than unfinished. Separating `'Dr.'` from a real boundary needs a
+* lexicon or a heuristic over capitalisation and word length, and a heuristic gets a
+* different set of statements wrong — quietly, in the direction of letting a genuinely
+* compound statement through, which is the failure this rule exists to prevent. `validateBrief`
+* therefore reports the count and lets the author judge, rather than guessing at intent.
+*
+* @param statement - The statement to measure.
+* @returns The sentence count; `0` for empty or whitespace-only text.
+*
+* @example
+* ```ts
+* import { countSentences } from '@orkestrel/brief'
+*
+* countSentences('Refactor useForm to native APIs.') // 1
+* countSentences('Refactor useForm. Then update the tests') // 2 — the tail counts
+* countSentences('Ask Dr. Smith') // 2 — an abbreviation reads as a boundary
+* countSentences('') // 0
+* ```
+*/
+function countSentences(statement) {
+	const text = (0, _orkestrel_interpret.collapseWhitespace)(statement);
+	if (text.length === 0) return 0;
+	const matches = text.match(/[.!?]+(?=\s|$)/gu);
+	if (matches === null) return 1;
+	return /[.!?]$/u.test(text) ? matches.length : matches.length + 1;
+}
+/**
+* The gaps that block emission.
+*
+* @param source - The brief to inspect.
+* @returns Every gap carrying `blocking: true`, in declaration order.
+*
+* @example
+* ```ts
+* import { brief, findBlockingGaps, gap, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('plan', 'ops', 'Plan the release.'), {
+* 	gaps: [gap('output', 'Diff or files?', { blocking: true })],
+* })
+* findBlockingGaps(draft).length // 1
+* ```
+*/
+function findBlockingGaps(source) {
+	return source.gaps.filter((entry) => entry.blocking);
+}
+/**
+* The authority paths the manifest never grants access to.
+*
+* @remarks
+* An authority the executor cannot open is an instruction it cannot follow, so every ranked
+* path must appear in `read`, `edit`, or `locked`. Those three are the grants: `locked` is a
+* grant, because read-only is exactly what obeying a file requires.
+*
+* This subsumes the narrower question of an authority sitting in `forbidden`. The four
+* partitions are disjoint — `findManifestOverlaps` and the `disjoint` rule enforce it — so a
+* forbidden path is in none of the three grants and is reported here. An authority named in
+* NO partition at all is reported for the same reason, and that is the case a forbidden-only
+* check misses entirely: the brief simply never says the executor may open what it must obey.
+*
+* Paths are compared as EXACT strings, matching `findManifestOverlaps`. A glob is never
+* expanded, so `read: 'guides/**'` does not grant `authority: 'guides/brief.md'`. State a
+* grant as the same literal path the authority carries.
+*
+* @param source - The brief to inspect.
+* @returns Each ungranted authority path once, in authority order; empty when all are granted.
+*
+* @example
+* ```ts
+* import { brief, findUngrantedAuthority, manifest, reference, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('debug', 'code', 'Fix the leak.'), {
+* 	authority: [reference('AGENTS.md', 'project law')],
+* 	manifest: manifest(),
+* })
+* findUngrantedAuthority(draft) // ['AGENTS.md'] — ranked, but no partition opens it
+* ```
+*/
+function findUngrantedAuthority(source) {
+	const granted = new Set([
+		...source.manifest.read,
+		...source.manifest.edit,
+		...source.manifest.locked
+	].map((entry) => entry.path));
+	const ungranted = [];
+	for (const path of new Set(source.authority.map((entry) => entry.path))) if (!granted.has(path)) ungranted.push(path);
+	return ungranted;
+}
+/**
+* The paths appearing in more than one manifest partition.
+*
+* @remarks
+* Duplicates WITHIN one partition are not an overlap; the four partitions must be
+* mutually disjoint, which is what `validateBrief` errors on.
+*
+* Paths are compared as EXACT strings. A glob is never expanded, so `edit: 'app/file.ts'`
+* and `forbidden: 'app/**'` are not reported as an overlap even though a walker would place
+* one inside the other. Disjointness here is a property of the written paths.
+*
+* @param source - The brief to inspect.
+* @returns Each overlapping path once, in first-seen partition order.
+*
+* @example
+* ```ts
+* import { brief, findManifestOverlaps, manifest, reference, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('debug', 'code', 'Fix the leak.'), {
+* 	manifest: manifest({
+* 		edit: [reference('src/core/BriefCompiler.ts', 'the leaking pipeline')],
+* 		locked: [reference('src/core/BriefCompiler.ts', 'the published contract')],
+* 	}),
+* })
+* findManifestOverlaps(draft) // ['src/core/BriefCompiler.ts']
+* ```
+*/
+function findManifestOverlaps(source) {
+	const counts = /* @__PURE__ */ new Map();
+	const partitions = [
+		source.manifest.read,
+		source.manifest.edit,
+		source.manifest.locked,
+		source.manifest.forbidden
+	];
+	for (const partition of partitions) for (const path of new Set(partition.map((entry) => entry.path))) counts.set(path, (counts.get(path) ?? 0) + 1);
+	const overlaps = [];
+	for (const [path, count] of counts) if (count > 1) overlaps.push(path);
+	return overlaps;
+}
+/**
+* The open gaps with no assumption to stand on.
+*
+* @remarks
+* The discipline is exactly one recorded assumption per open gap, so the open gaps past
+* the assumption count are the unpaired ones. A blocking gap is never unpaired — it is
+* a question, not something to assume around.
+*
+* @param source - The brief to inspect.
+* @returns The surplus open gaps, in declaration order.
+*
+* @example
+* ```ts
+* import { brief, findUnpairedGaps, gap, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('plan', 'ops', 'Plan the release.'), {
+* 	gaps: [gap('rules', 'Keep the wording?'), gap('output', 'Diff or files?')],
+* 	assumptions: ['Wording is preserved.'],
+* })
+* findUnpairedGaps(draft).length // 1
+* ```
+*/
+function findUnpairedGaps(source) {
+	return source.gaps.filter((entry) => !entry.blocking).slice(source.assumptions.length);
+}
+/**
+* Project a brief into the reasons `Subject` of readiness measures the gate reads.
+*
+* @param source - The brief to measure.
+* @returns A flat record of counts plus the task's two vocabulary values.
+*
+* @example
+* ```ts
+* import { brief, briefToSubject, proof, task } from '@orkestrel/brief'
+*
+* briefToSubject(brief(task('test', 'code', 'Cover the gate.'), { proofs: [proof('x', 'y')] }))
+* // { operation: 'test', domain: 'code', sentences: 1, proofs: 1, … }
+* ```
+*/
+function briefToSubject(source) {
+	return {
+		operation: source.task.operation,
+		domain: source.task.domain,
+		sentences: countSentences(source.task.statement),
+		authority: source.authority.length,
+		gaps: source.gaps.length,
+		blocking: findBlockingGaps(source).length,
+		unpaired: findUnpairedGaps(source).length,
+		outcomes: source.outcomes.length,
+		required: source.outcomes.filter((entry) => entry.required).length,
+		proofs: source.proofs.length,
+		reads: source.manifest.read.length,
+		edits: source.manifest.edit.length,
+		locks: source.manifest.locked.length,
+		bans: source.manifest.forbidden.length,
+		overlaps: findManifestOverlaps(source).length,
+		ungranted: findUngrantedAuthority(source).length,
+		risks: source.risks.length,
+		examples: source.examples.length
+	};
+}
+/**
+* The semantic pass over an already-shape-valid brief.
+*
+* @remarks
+* ERRORS are the structural violations no assumption can paper over: a manifest
+* overlap, an authority no partition grants access to, an empty `proofs` list, and a
+* statement that is not exactly one sentence.
+* WARNINGS are runnable but suspicious: duplicate outcome ranks, an unpaired open gap,
+* and an optional outcome ranked above a required one. Never throws.
+*
+* @param source - The brief to inspect.
+* @returns A reasons `ReasonValidationResult`; `valid` exactly when `errors` is empty.
+*
+* @example
+* ```ts
+* import { brief, proof, task, validateBrief } from '@orkestrel/brief'
+*
+* validateBrief(brief(task('plan', 'ops', 'Plan the release.'))) // valid: false — no proofs
+* validateBrief(
+* 	brief(task('plan', 'ops', 'Plan the release.'), { proofs: [proof('ok', 'npm test')] }),
+* ) // valid: true
+* ```
+*/
+function validateBrief(source) {
+	const errors = [];
+	const warnings = [];
+	for (const path of findManifestOverlaps(source)) errors.push(`Path "${path}" appears in more than one manifest partition`);
+	for (const path of findUngrantedAuthority(source)) errors.push(`Authority "${path}" is in no manifest partition that grants access — the executor cannot obey what it cannot open`);
+	if (source.proofs.length === 0) errors.push("Brief records no proof — nothing can settle \"done\"");
+	const sentences = countSentences(source.task.statement);
+	if (sentences !== 1) errors.push(`Statement holds ${String(sentences)} sentences — a compound statement is two briefs`);
+	const ranks = /* @__PURE__ */ new Map();
+	for (const entry of source.outcomes) ranks.set(entry.rank, (ranks.get(entry.rank) ?? 0) + 1);
+	for (const [rank, count] of ranks) if (count > 1) warnings.push(`Outcome rank ${String(rank)} is used ${String(count)} times`);
+	for (const entry of findUnpairedGaps(source)) warnings.push(`Open gap "${entry.field}" has no paired assumption`);
+	const required = source.outcomes.filter((entry) => entry.required).map((entry) => entry.rank);
+	if (required.length > 0) {
+		const floor = Math.min(...required);
+		for (const entry of source.outcomes) if (!entry.required && entry.rank < floor) warnings.push(`Outcome ${String(entry.rank)} is optional but outranks every required outcome`);
+	}
+	return {
+		valid: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+/**
+* The canonical structural digest of a brief's content.
+*
+* @remarks
+* `trace` and `hash` are stripped before digesting, so the value is the identity of what
+* the brief SAYS rather than of a particular pinning. Deterministic across runs — the
+* same interprets `digestValue` the fleet uses everywhere else.
+*
+* @param source - The brief to digest.
+* @returns An eight-hex-digit digest.
+*
+* @example
+* ```ts
+* import { brief, briefToHash, pinBrief, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('plan', 'ops', 'Plan the release.'))
+* briefToHash(draft) === briefToHash(pinBrief(draft)) // true — pinning does not move it
+* ```
+*/
+function briefToHash(source) {
+	return (0, _orkestrel_interpret.digestValue)(briefToContent(source));
+}
+/**
+* The canonical text of exactly what a brief's hash describes.
+*
+* @remarks
+* `trace` and `hash` are stripped, then interprets `canonicalize` renders the rest in a
+* key-order-stable form. Two briefs with the same hash are the same brief only when this
+* text matches — the digest is eight hex digits, so hash equality alone is not identity.
+*
+* @param source - The brief to render.
+* @returns The canonical content text.
+*
+* @example
+* ```ts
+* import { brief, briefToContent, pinBrief, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('plan', 'ops', 'Plan the release.'))
+* briefToContent(draft) === briefToContent(pinBrief(draft)) // true — pinning adds no content
+* ```
+*/
+function briefToContent(source) {
+	const { trace: _trace, hash: _hash, ...content } = source;
+	return (0, _orkestrel_interpret.canonicalize)(content);
+}
+/**
+* Freeze a value and everything reachable from it.
+*
+* @remarks
+* `Object.freeze` is SHALLOW, so freezing a record leaves every nested array and object
+* writable. A `Briefing` is documented as a replayable record, and a shallow freeze let a
+* consumer rewrite the recorded stage input after the digest describing it was already
+* sealed — the replay and its hash could disagree.
+*
+* Cycles terminate: `structuredClone` preserves them, so a naive walk would not return.
+* Delegates each branch to `freezeBranch` with the shared visited set.
+*
+* Reaches PLAIN objects and arrays, which is the whole of a `Brief` — it is JSON-serializable
+* by contract. A `Map`, `Set`, or typed array is frozen as an object and its CONTENTS are left
+* writable, and `Object.isFrozen` reports `true` for it either way. Nothing this package
+* produces contains one; a caller freezing their own value should know the limit.
+*
+* @param value - The value to freeze in place; returned for convenience.
+* @returns The same value, now deeply frozen.
+*
+* @example
+* ```ts
+* import { freezeDeep } from '@orkestrel/brief'
+*
+* const owned = freezeDeep({ outcomes: [{ rank: 1 }] })
+* Object.isFrozen(owned.outcomes) // true — the nested array too
+* ```
+*/
+function freezeDeep(value) {
+	return freezeBranch(value, /* @__PURE__ */ new WeakSet());
+}
+/**
+* Freeze one branch of a value graph, skipping what the visited set already holds.
+*
+* @param value - The branch to freeze.
+* @param seen - The objects already frozen on this walk; what makes a cycle terminate.
+* @returns The same branch, now frozen.
+*
+* @example
+* ```ts
+* import { freezeBranch } from '@orkestrel/brief'
+*
+* freezeBranch({ a: [1] }, new WeakSet()) // frozen, one level of nesting included
+* ```
+*/
+function freezeBranch(value, seen) {
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return value;
+	seen.add(value);
+	Object.freeze(value);
+	for (const nested of Object.values(value)) freezeBranch(nested, seen);
+	return value;
+}
+/**
+* Render a value thrown by a stage into a message.
+*
+* @remarks
+* TOTAL: it never throws, for any input. That is load-bearing rather than tidy, because this
+* is the containment code itself — `compile` calls it inside the `catch` that turns a thrown
+* stage into a recorded `BriefStageFailure`. A throw here escapes `compile` uncontained and
+* falsifies the package's central promise that a failing stage yields an incomplete
+* `Briefing` rather than an exception.
+*
+* Three real inputs used to throw: an `Error` subclass whose `message` getter throws, a value
+* whose string conversion throws, and a null-prototype object, which has no inherited
+* conversion for String() to reach. Each is wrapped, and an unreadable value degrades to its
+* type rather than propagating.
+*
+* @param error - The caught value, of any shape.
+* @returns The `Error` message when there is one, otherwise the value stringified; a fixed
+*   description when the value cannot be read at all.
+*
+* @example
+* ```ts
+* import { errorToMessage } from '@orkestrel/brief'
+*
+* errorToMessage(new Error('boom')) // 'boom'
+* errorToMessage('boom') // 'boom'
+* errorToMessage(Object.create(null)) // 'an unreadable object was thrown'
+* ```
+*/
+function errorToMessage(error) {
+	const read = (0, _orkestrel_contract.attempt)(() => error instanceof Error ? error.message : String(error));
+	if (read.success && typeof read.value === "string") return read.value;
+	return `an unreadable ${typeof error} was thrown`;
+}
+/**
+* Narrow unknown data to a `Brief`, throwing when it is off-contract.
+*
+* @remarks
+* The throwing half of the intake pair: this returns its argument by IDENTITY once the
+* guard passes, while `parseBrief` returns `undefined` for bad input. It constructs
+* nothing, so it is an assertion rather than a factory. Reserve it for programmer-error
+* contexts where invalidity is a bug.
+*
+* @param data - The candidate brief data.
+* @returns The same value, now known to satisfy {@link Brief}.
+* @throws {@link BriefError} `INVALID` when `data` fails `isBrief`.
+*
+* @example
+* ```ts
+* import { assertBrief, brief, proof, task } from '@orkestrel/brief'
+*
+* assertBrief(brief(task('plan', 'ops', 'Plan the release.'), { proofs: [proof('x', 'y')] }))
+* assertBrief({ task: { operation: 'plan', domain: 'ops', statement: 'x.' } }) // throws INVALID
+* ```
+*/
+function assertBrief(data) {
+	if (!isBrief(data)) throw new BriefError("INVALID", "Brief failed the exact-record contract", { field: "brief" });
+	return data;
+}
+/**
+* Return a fresh brief with `trace` and `hash` derived from its own content.
+*
+* @remarks
+* Deterministic: no clock, no randomness, no run-specific data. Any existing `trace` /
+* `hash` is stripped before the digest, so pinning is idempotent and a re-pin of unchanged
+* content produces the same hash.
+*
+* The snapshot is taken FIRST, before any member is read, so a hostile input whose getters
+* throw surfaces as this package's coded error rather than as whatever it threw.
+*
+* @param source - The brief to pin.
+* @returns A fresh, pinned, deeply frozen `Brief`.
+* @throws {@link BriefError} `INVALID` when the brief carries data JSON cannot express.
+*
+* @example
+* ```ts
+* import { brief, pinBrief, task } from '@orkestrel/brief'
+*
+* const pinned = pinBrief(brief(task('document', 'writing', 'Write the brief guide.')))
+* pinned.hash // an 8-hex-digit structural digest
+* pinned.trace // 'document/writing · outcomes:0 · gaps:0/0 · proofs:0'
+* ```
+*/
+function pinBrief(source) {
+	const owned = snapshotBrief(source);
+	const { trace: _trace, hash: _hash, ...content } = owned;
+	return snapshotBrief({
+		...content,
+		trace: briefToTrace(owned),
+		hash: briefToHash(owned)
+	});
+}
+/**
+* The one-line census `pinBrief` stamps onto a brief.
+*
+* @remarks
+* Extracted so it has ONE implementation. `pinBrief` derives it and `BriefManager` re-derives
+* it to reconcile an inbound brief's own `trace` against its content — an inbound `trace` is
+* shape-checked rather than verified, and it is the line `briefToMarkdown` prints at the top
+* of the executor's prompt, so a stale one misdescribes the brief where it is most read.
+*
+* @param source - The brief to describe.
+* @returns The census line: operation/domain, outcomes, blocking-over-total gaps, proofs.
+*
+* @example
+* ```ts
+* import { brief, briefToTrace, task } from '@orkestrel/brief'
+*
+* briefToTrace(brief(task('document', 'writing', 'Write the guide.')))
+* // 'document/writing · outcomes:0 · gaps:0/0 · proofs:0'
+* ```
+*/
+function briefToTrace(source) {
+	return [
+		`${source.task.operation}/${source.task.domain}`,
+		`outcomes:${String(source.outcomes.length)}`,
+		`gaps:${String(findBlockingGaps(source).length)}/${String(source.gaps.length)}`,
+		`proofs:${String(source.proofs.length)}`
+	].join(" · ");
+}
+/**
+* Render one exemplar as markdown lines.
+*
+* @remarks
+* An `Example`'s two sides are the only brief members permitted to span lines, so a
+* single-line pair renders as one row and a multi-line pair renders as a fenced block.
+* Fencing is what stops the one permissive field from forging a heading.
+*
+* @param entry - The exemplar to render.
+* @returns The markdown lines, without a trailing blank.
+*
+* @example
+* ```ts
+* import { example, exampleToLines } from '@orkestrel/brief'
+*
+* exampleToLines(example('<input required>', 'el.validity')) // ['- ` <input required> ` → ` el.validity `']
+* ```
+*/
+function exampleToLines(entry) {
+	const note = entry.note === void 0 ? "" : ` (${entry.note})`;
+	let runs = 0;
+	let current = 0;
+	for (const character of `${entry.input} ${entry.output}`) {
+		current = character === "`" ? current + 1 : 0;
+		if (current > runs) runs = current;
+	}
+	if (!LINE_BREAK_PATTERN.test(entry.input) && !LINE_BREAK_PATTERN.test(entry.output)) {
+		const tick = "`".repeat(runs + 1);
+		const inputPad = BLANK_PATTERN.test(entry.input) ? "" : " ";
+		const outputPad = BLANK_PATTERN.test(entry.output) ? "" : " ";
+		return [`- ${tick}${inputPad}${entry.input}${inputPad}${tick} → ${tick}${outputPad}${entry.output}${outputPad}${tick}${note}`];
+	}
+	const fence = "`".repeat(Math.max(3, runs) + 1);
+	return [
+		`- exemplar${note}`,
+		"",
+		`  ${fence}text`,
+		...entry.input.split(LINE_BREAK_PATTERN).map((line) => `  ${line}`),
+		`  ${fence}`,
+		"",
+		`  ${fence}text`,
+		...entry.output.split(LINE_BREAK_PATTERN).map((line) => `  ${line}`),
+		`  ${fence}`
+	];
+}
+/**
+* Project a brief into the copy-ready agent prompt.
+*
+* @remarks
+* Paths are REFERENCED, never inlined — the executor retrieves them. An empty section is
+* omitted entirely, so the rendering carries no filler an executor must read past.
+*
+* @param source - The brief to render.
+* @returns The markdown prompt.
+*
+* @example
+* ```ts
+* import { brief, briefToMarkdown, task } from '@orkestrel/brief'
+*
+* briefToMarkdown(brief(task('review', 'code', 'Review the gate rules.')))
+* // '# Brief: Review the gate rules.\n\nreview · code\n\n## Output\n\n- format: markdown\n'
+* ```
+*/
+function briefToMarkdown(input) {
+	const source = snapshotBrief(input);
+	const lines = [`# Brief: ${source.task.statement}`, ""];
+	lines.push(`${source.task.operation} · ${source.task.domain}`, "");
+	if (source.trace !== void 0) lines.push(`Trace: ${source.trace}`, "");
+	if (source.hash !== void 0) lines.push(`Hash: ${source.hash}`, "");
+	if (source.authority.length > 0) {
+		lines.push("## Authority (ranked)", "");
+		lines.push(...source.authority.map((entry, index) => `${String(index + 1)}. ${entry.path} — ${entry.note}`));
+		lines.push("");
+	}
+	const partitions = [
+		["Read", source.manifest.read],
+		["Edit", source.manifest.edit],
+		["Locked", source.manifest.locked],
+		["Forbidden", source.manifest.forbidden]
+	];
+	if (partitions.some((partition) => partition[1].length > 0)) {
+		lines.push("## Manifest", "");
+		for (const [heading, entries] of partitions) {
+			if (entries.length === 0) continue;
+			lines.push(`### ${heading}`, "");
+			lines.push(...entries.map((entry) => `- ${entry.path} — ${entry.note}`));
+			lines.push("");
+		}
+	}
+	if (source.outcomes.length > 0) {
+		lines.push("## Outcomes", "");
+		lines.push(...source.outcomes.map((entry) => `${String(entry.rank)}. ${entry.text}${entry.required ? " (required)" : " (optional)"}`));
+		lines.push("");
+	}
+	const prose = [
+		["Rules", source.rules],
+		["Invariants", source.invariants],
+		["Assumptions", source.assumptions]
+	];
+	for (const [heading, entries] of prose) {
+		if (entries.length === 0) continue;
+		lines.push(`## ${heading}`, "");
+		lines.push(...entries.map((entry) => `- ${entry}`));
+		lines.push("");
+	}
+	if (source.givens.length > 0) {
+		lines.push("## Givens", "");
+		lines.push(...source.givens.map((entry) => `- ${entry.category} · ${entry.name}: ${entry.value}`));
+		lines.push("");
+	}
+	if (source.examples.length > 0) {
+		lines.push("## Examples", "");
+		for (const entry of source.examples) lines.push(...exampleToLines(entry));
+		lines.push("");
+	}
+	if (source.citations.length > 0) {
+		lines.push("## Citations (trust order)", "");
+		lines.push(...source.citations.map((entry, index) => `${String(index + 1)}. ${entry.name} — ${entry.note} — ${entry.url}`));
+		lines.push("");
+	}
+	if (source.gaps.length > 0) {
+		lines.push("## Gaps", "");
+		lines.push(...source.gaps.map((entry) => {
+			const mark = entry.blocking ? "blocking" : "open";
+			const candidates = entry.candidates === void 0 ? "" : ` (candidates: ${entry.candidates.join(", ")})`;
+			return `- [${mark}] ${entry.field}: ${entry.question}${candidates}`;
+		}));
+		lines.push("");
+	}
+	if (source.risks.length > 0) {
+		lines.push("## Risks", "");
+		lines.push(...source.risks.map((entry) => `- ${entry.severity}: ${entry.text} — ${entry.mitigation}`));
+		lines.push("");
+	}
+	lines.push("## Output", "", `- format: ${source.output.format}`);
+	const refinements = [
+		["sections", source.output.sections],
+		["include", source.output.include],
+		["exclude", source.output.exclude]
+	];
+	for (const [label, entries] of refinements) {
+		if (entries === void 0 || entries.length === 0) continue;
+		lines.push(`- ${label}: ${entries.join(", ")}`);
+	}
+	lines.push("");
+	if (source.proofs.length > 0) {
+		lines.push("## Proofs", "");
+		lines.push(...source.proofs.map((entry) => `- ${entry.text} — \`${entry.command}\``));
+		lines.push("");
+	}
+	return lines.join("\n");
+}
+/**
+* Project a brief into a `/goal` completion condition.
+*
+* @remarks
+* The proofs' commands VERBATIM plus a turn cap — the goal never adds a condition the
+* brief does not carry.
+*
+* @param source - The brief to render.
+* @param turns - The turn cap; defaults to `DEFAULT_BRIEF_TURNS`.
+* @returns The one-line completion condition.
+*
+* @example
+* ```ts
+* import { brief, briefToGoal, proof, task } from '@orkestrel/brief'
+*
+* briefToGoal(brief(task('test', 'code', 'Cover the gate.'), { proofs: [proof('x', 'npm test')] }))
+* // 'Done when every proof passes: npm test exits 0. Cap: 16 turns.'
+* ```
+*/
+function briefToGoal(input, turns = 16) {
+	const source = snapshotBrief(input);
+	return `Done when every proof passes: ${source.proofs.length === 0 ? "no proofs recorded" : source.proofs.map((entry) => `${entry.command} exits 0`).join("; ")}. Cap: ${String(turns)} turns.`;
+}
+/**
+* Project a brief into a subagent `Dispatch`.
+*
+* @remarks
+* `edit` is exactly `manifest.edit`, so two dispatches whose `edit` sets do not intersect
+* can run concurrently under the same brief without conflict.
+*
+* `authority` is exactly `brief.authority` in rank order, and it is a SEPARATE axis from the
+* four permission sets rather than a fifth partition — a ranked path normally also appears in
+* `read` or `locked`, because the executor has to open what it obeys. It is projected as
+* paths so a machine consumer never has to parse `prompt`, which is written for a model.
+*
+* @param source - The brief to project.
+* @returns The dispatch — the rendered prompt, the ranked authority, and the four path sets.
+*
+* @example
+* ```ts
+* import { brief, briefToDispatch, manifest, reference, task } from '@orkestrel/brief'
+*
+* const draft = brief(task('migrate', 'code', 'Migrate the stores.'), {
+* 	authority: [reference('AGENTS.md', 'project law')],
+* 	manifest: manifest({ edit: [reference('src/core/stores/**', 'the legacy stores')] }),
+* })
+* briefToDispatch(draft).edit // ['src/core/stores/**']
+* briefToDispatch(draft).authority // ['AGENTS.md']
+* ```
+*/
+function briefToDispatch(input) {
+	const source = snapshotBrief(input);
+	return {
+		prompt: briefToMarkdown(source),
+		authority: source.authority.map((entry) => entry.path),
+		read: source.manifest.read.map((entry) => entry.path),
+		edit: source.manifest.edit.map((entry) => entry.path),
+		locked: source.manifest.locked.map((entry) => entry.path),
+		forbidden: source.manifest.forbidden.map((entry) => entry.path)
+	};
+}
+/**
+* Derive one imperative statement from free text.
+*
+* @remarks
+* Whitespace collapses, the first character uppercases, and a terminator is appended
+* when the text carries none. Nothing else is invented.
+*
+* @param text - The raw request text.
+* @returns The statement, or `''` for empty or whitespace-only text.
+*
+* @example
+* ```ts
+* import { deriveStatement } from '@orkestrel/brief'
+*
+* deriveStatement('  clean up   useForm ') // 'Clean up useForm.'
+* deriveStatement('') // ''
+* ```
+*/
+function deriveStatement(text) {
+	const collapsed = (0, _orkestrel_interpret.collapseWhitespace)(text);
+	if (collapsed.length === 0) return "";
+	const capitalized = collapsed.charAt(0).toUpperCase() + collapsed.slice(1);
+	return /[.!?]$/u.test(capitalized) ? capitalized : `${capitalized}.`;
+}
+/**
+* Derive a `Task` from an interprets `Intent` through the caller's vocabularies.
+*
+* @remarks
+* The vocabularies are the CALLER's policy: this maps and never guesses. An action or
+* domain the caller did not map — or mapped to an off-vocabulary value — yields
+* `undefined` rather than an invented task. Inherited keys never resolve.
+*
+* @param intent - The classified intent from an interpret pipeline.
+* @param text - The text the statement derives from.
+* @param actions - Maps an intent action onto a closed `TaskOperation`.
+* @param domains - Maps an intent domain onto a closed `TaskDomain`.
+* @returns The derived `Task`, or `undefined` when either side is unmapped.
+*
+* @example
+* ```ts
+* import { deriveTask } from '@orkestrel/brief'
+*
+* const intent = { action: 'migrate', domain: 'code', confidence: 1 }
+* deriveTask(intent, 'migrate the stores', { migrate: 'migrate' }, { code: 'code' })
+* // { operation: 'migrate', domain: 'code', statement: 'Migrate the stores.' }
+* deriveTask(intent, 'migrate the stores', {}, { code: 'code' }) // undefined
+* ```
+*/
+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;
+	if (!isTaskOperation(operation) || !isTaskDomain(domain)) return void 0;
+	const statement = deriveStatement(text);
+	return statement.length === 0 ? void 0 : task(operation, domain, statement);
+}
+/**
+* Derive `Given[]` from an interprets `Entity[]`.
+*
+* @remarks
+* Every extracted entity becomes one `extracted` fact. A nameless entity is dropped; an
+* object value renders through interprets `canonicalize`, so the text is key-order stable.
+*
+* @param entities - The entities an interpret pipeline extracted.
+* @returns One `Given` per named entity, in extraction order.
+*
+* @example
+* ```ts
+* import { deriveGivens } from '@orkestrel/brief'
+*
+* deriveGivens([
+* 	{ name: 'value', value: 3, provenance: { category: 'extracted' }, confidence: 1 },
+* ]) // [{ category: 'extracted', name: 'value', value: '3' }]
+* ```
+*/
+function deriveGivens(entities) {
+	return entities.filter((entity) => entity.name.length > 0).map((entity) => given("extracted", entity.name, typeof entity.value === "string" ? entity.value : typeof entity.value === "object" && entity.value !== null ? (0, _orkestrel_interpret.canonicalize)(entity.value) : String(entity.value)));
+}
+/**
+* Derive `Gap[]` from an interprets `Ambiguity[]`.
+*
+* @remarks
+* A REQUIRED ambiguity becomes a BLOCKING gap — the gate must fail closed on it. The
+* rest stay open, to be answered with a recorded assumption. An array field path flattens
+* through reasons `formatField`.
+*
+* @param ambiguities - The ambiguities an interpret pipeline surfaced.
+* @returns One `Gap` per ambiguity, in surfacing order.
+*
+* @example
+* ```ts
+* import { deriveGaps } from '@orkestrel/brief'
+*
+* deriveGaps([{ field: 'output', question: 'Diff or files?', candidates: [], required: true }])
+* // [{ field: 'output', question: 'Diff or files?', blocking: true }]
+* ```
+*/
+function deriveGaps(ambiguities) {
+	return ambiguities.map((ambiguity) => {
+		const candidates = ambiguity.candidates.filter((candidate) => candidate.length > 0);
+		return gap((0, _orkestrel_reason.formatField)(ambiguity.field), ambiguity.question, {
+			blocking: ambiguity.required,
+			...candidates.length === 0 ? {} : { candidates }
+		});
+	});
+}
+//#endregion
+//#region src/core/parsers.ts
+/**
+* Parse a JSON string into a `Brief`.
+*
+* @remarks
+* The parse-then-trust boundary for a stored brief, a tool argument, or an agent's
+* emission. Invalid JSON, an extra key, an off-vocabulary literal, and a missing section
+* all fail the same way — `undefined`, never a throw. Coerce a bare vocabulary value with
+* `parseEnum` from `@orkestrel/contract` against the exported tuple instead.
+*
+* @param value - The JSON text to parse.
+* @returns The `Brief` when the parsed value satisfies `isBrief`, otherwise `undefined`.
+*
+* @example
+* ```ts
+* import { parseBrief } from '@orkestrel/brief'
+*
+* parseBrief('not json') // undefined
+* parseBrief('{"task":{"operation":"plan","domain":"ops","statement":"x."}}') // undefined
+* ```
+*/
+function parseBrief(value) {
+	return (0, _orkestrel_contract.parseJSONAs)(value, isBrief);
+}
+//#endregion
+//#region src/core/BriefManager.ts
+/**
+* The self-owning, versioned and content-hashed brief registry.
+*
+* @remarks
+* Record ids are MINTED from each brief's own content hash unless the caller names one,
+* so registering unchanged content twice is a version no-op and two callers who compiled
+* the same request land on the same id with no coordination. A call after `destroy()`
+* throws `BriefError('DESTROYED', …)`.
+*
+* @example
+* ```ts
+* import { BriefManager, brief, task } from '@orkestrel/brief'
+*
+* const briefs = new BriefManager()
+* const record = briefs.add(brief(task('document', 'writing', 'Write the brief guide.')))
+* record.id === record.hash // true
+* briefs.destroy()
+* ```
+*/
+var BriefManager = class {
+	#emitter;
+	#records = /* @__PURE__ */ new Map();
+	#destroyed = false;
+	constructor(options) {
+		const hooks = options?.on;
+		const failed = options?.error;
+		const seeds = options?.briefs ?? [];
+		const staged = /* @__PURE__ */ new Map();
+		for (const entry of seeds) {
+			const record = this.#stage(entry, staged);
+			staged.set(record.id, record);
+		}
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			...hooks === void 0 ? {} : { on: hooks },
+			...failed === void 0 ? {} : { error: failed }
+		});
+		for (const record of staged.values()) this.#commit(record);
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get size() {
+		return this.#records.size;
+	}
+	has(id) {
+		this.#refuseDestroyed();
+		return this.#records.has(id);
+	}
+	brief(id) {
+		this.#refuseDestroyed();
+		return this.#records.get(id);
+	}
+	briefs() {
+		this.#refuseDestroyed();
+		return [...this.#records.values()];
+	}
+	add(source, options) {
+		this.#refuseDestroyed();
+		const record = this.#stage(source, this.#records, options);
+		this.#commit(record);
+		return record;
+	}
+	remove(target) {
+		this.#refuseDestroyed();
+		if (target === void 0) {
+			for (const id of [...this.#records.keys()]) this.#discard(id);
+			return;
+		}
+		if (typeof target === "string") return this.#discard(target);
+		let removed = true;
+		for (const id of new Set(target)) if (!this.#discard(id)) removed = false;
+		return removed;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		this.#records.clear();
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#stage(source, against, options) {
+		const owned = snapshotBrief(source);
+		const hash = briefToHash(owned);
+		if (owned.hash !== void 0 && owned.hash !== hash) throw new BriefError("INVALID", "Brief carries a hash that does not describe it", {
+			field: "hash",
+			hash: owned.hash
+		});
+		const trace = briefToTrace(owned);
+		if (owned.trace !== void 0 && owned.trace !== trace) throw new BriefError("INVALID", "Brief carries a trace that does not describe it", {
+			field: "trace",
+			trace: owned.trace
+		});
+		const id = options?.id ?? hash;
+		const previous = against.get(id);
+		return Object.freeze({
+			id,
+			brief: owned,
+			version: previous === void 0 ? 1 : this.#version(previous, owned, hash),
+			hash
+		});
+	}
+	#commit(record) {
+		this.#records.set(record.id, record);
+		this.#emitter.emit("add", record.id);
+	}
+	#version(previous, incoming, hash) {
+		if (previous.hash !== hash) return previous.version + 1;
+		if (briefToContent(previous.brief) === briefToContent(incoming)) return previous.version;
+		throw new BriefError("INVALID", "Two different briefs share one content hash — name them with distinct ids", {
+			field: "hash",
+			hash
+		});
+	}
+	#discard(id) {
+		if (!this.#records.delete(id)) return false;
+		this.#emitter.emit("remove", id);
+		return true;
+	}
+	#refuseDestroyed() {
+		if (this.#destroyed) throw new BriefError("DESTROYED", "BriefManager has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/BriefCompiler.ts
+/**
+* The compilation orchestrator — the four-stage `[interpret, draft, gate, pin]` pipeline.
+*
+* @remarks
+* `compile` is genuinely SYNCHRONOUS and never throws for a brief it cannot emit: a
+* blocking gap, a refused gate, and a thrown stage all yield a visible INCOMPLETE
+* `Briefing`. It owns the engines it created and BORROWS the ones passed in, so
+* `destroy()` releases only what it made.
+*
+* @example
+* ```ts
+* import { BriefCompiler, proof, task } from '@orkestrel/brief'
+*
+* const compiler = new BriefCompiler()
+* const briefing = compiler.compile({
+* 	task: task('audit', 'code', 'Audit the barrel for undocumented exports.'),
+* 	outcomes: [{ rank: 1, text: 'every export appears in the guide', required: true }],
+* 	proofs: [proof('parity passes', 'npm run test:guides')],
+* })
+* briefing.brief !== undefined // true — the presence of the brief IS the completeness test
+* compiler.destroy()
+* ```
+*/
+var BriefCompiler = class {
+	#emitter;
+	#interpret;
+	#reason;
+	#ownInterpret;
+	#ownReason;
+	#actions;
+	#domains;
+	#destroyed = false;
+	constructor(options) {
+		const hooks = options?.on;
+		const failed = options?.error;
+		const borrowedInterpret = options?.interpret;
+		const borrowedReason = options?.reason;
+		this.#emitter = new _orkestrel_emitter.Emitter({
+			...hooks === void 0 ? {} : { on: hooks },
+			...failed === void 0 ? {} : { error: failed }
+		});
+		this.#ownInterpret = borrowedInterpret === void 0;
+		this.#ownReason = borrowedReason === void 0;
+		this.#interpret = borrowedInterpret ?? (0, _orkestrel_interpret.createInterpret)();
+		this.#reason = borrowedReason ?? (0, _orkestrel_reason.createReason)({ reasoners: [(0, _orkestrel_reason.createLogicalReasoner)()] });
+		this.#actions = options?.actions ?? {};
+		this.#domains = options?.domains ?? {};
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get interpret() {
+		return this.#interpret;
+	}
+	get reason() {
+		return this.#reason;
+	}
+	compile(input) {
+		this.#refuseDestroyed();
+		const stages = [];
+		const failures = [];
+		const taken = (0, _orkestrel_contract.attempt)(() => this.#snapshot(input));
+		if (!taken.success) {
+			const message = errorToMessage(taken.error);
+			stages.push(Object.freeze({
+				stage: "draft",
+				input: {},
+				error: message
+			}));
+			failures.push(Object.freeze({
+				stage: "draft",
+				code: "DRAFT_FAILED",
+				message
+			}));
+			this.#emitter.emit("error", taken.error);
+			return this.#refuse(void 0, void 0, [], void 0, stages, failures);
+		}
+		const owned = taken.value;
+		const interpretation = this.#read(owned, stages, failures);
+		const drafted = (0, _orkestrel_contract.attempt)(() => this.#draft(owned, interpretation, this.#unresolved(interpretation, failures)));
+		if (!drafted.success) {
+			const message = errorToMessage(drafted.error);
+			stages.push(Object.freeze({
+				stage: "draft",
+				input: owned,
+				error: message
+			}));
+			failures.push(Object.freeze({
+				stage: "draft",
+				code: "DRAFT_FAILED",
+				message
+			}));
+			this.#emitter.emit("error", drafted.error);
+			return this.#refuse(interpretation, void 0, [], void 0, stages, failures);
+		}
+		const draft = drafted.value;
+		stages.push(Object.freeze({
+			stage: "draft",
+			input: owned,
+			output: draft
+		}));
+		const questions = findBlockingGaps(draft);
+		const subject = Object.freeze(briefToSubject(draft));
+		const ruled = (0, _orkestrel_contract.attempt)(() => this.gate(draft));
+		if (ruled.success) stages.push(Object.freeze({
+			stage: "gate",
+			input: subject,
+			output: ruled.value
+		}));
+		else {
+			const message = errorToMessage(ruled.error);
+			stages.push(Object.freeze({
+				stage: "gate",
+				input: subject,
+				error: message
+			}));
+			failures.push(Object.freeze({
+				stage: "gate",
+				code: "GATE_FAILED",
+				message
+			}));
+			this.#emitter.emit("error", ruled.error);
+		}
+		const verdict = ruled.success ? ruled.value : void 0;
+		const unready = findUnmetRules(draft);
+		if (unready.length > 0 || verdict === void 0 || !verdict.conclusion) {
+			const refusal = this.#blockage(questions, unready, verdict);
+			if (refusal !== void 0) failures.push(Object.freeze(refusal));
+			return this.#refuse(interpretation, draft, questions, verdict, stages, failures);
+		}
+		const stamped = (0, _orkestrel_contract.attempt)(() => pinBrief(draft));
+		if (!stamped.success) {
+			const message = errorToMessage(stamped.error);
+			stages.push(Object.freeze({
+				stage: "pin",
+				input: draft,
+				error: message
+			}));
+			failures.push(Object.freeze({
+				stage: "pin",
+				code: "PIN_FAILED",
+				message
+			}));
+			this.#emitter.emit("error", stamped.error);
+			return this.#refuse(interpretation, draft, questions, verdict, stages, failures);
+		}
+		const pinned = stamped.value;
+		stages.push(Object.freeze({
+			stage: "pin",
+			input: draft,
+			output: pinned
+		}));
+		const briefing = Object.freeze({
+			...interpretation === void 0 ? {} : { interpretation },
+			brief: pinned,
+			questions: Object.freeze([]),
+			verdict,
+			stages: Object.freeze([...stages]),
+			failures: Object.freeze([...failures]),
+			digest: (0, _orkestrel_interpret.digestValue)({
+				brief: pinned,
+				questions: [],
+				failures
+			})
+		});
+		this.#emitter.emit("compile", briefing);
+		return briefing;
+	}
+	gate(source) {
+		this.#refuseDestroyed();
+		const ruled = (0, _orkestrel_contract.attempt)(() => this.#own(this.#reason.reason(briefToSubject(source), gateDefinition())));
+		if (!ruled.success) throw new BriefError("GATE_FAILED", errorToMessage(ruled.error), {
+			stage: "gate",
+			field: "reason"
+		});
+		const verdict = ruled.value;
+		if (!isLogicalVerdict(verdict)) throw new BriefError("GATE_FAILED", "The gate reasoner returned a non-logical result", {
+			stage: "gate",
+			field: "reasoning"
+		});
+		return verdict;
+	}
+	destroy() {
+		if (this.#destroyed) return;
+		this.#destroyed = true;
+		if (this.#ownInterpret) this.#interpret.destroy();
+		if (this.#ownReason) this.#reason.destroy();
+		this.#emitter.emit("destroy");
+		this.#emitter.destroy();
+	}
+	#snapshot(input) {
+		return freezeDeep(structuredClone(input));
+	}
+	#own(value) {
+		const cloned = (0, _orkestrel_contract.attempt)(() => structuredClone(value));
+		return freezeDeep(cloned.success ? cloned.value : value);
+	}
+	#read(input, stages, failures) {
+		const text = input.text;
+		if (text === void 0) return input.interpretation;
+		const read = (0, _orkestrel_contract.attempt)(() => this.#own(this.#interpret.interpret(text)));
+		if (read.success) {
+			stages.push(Object.freeze({
+				stage: "interpret",
+				input: text,
+				output: read.value
+			}));
+			return read.value;
+		}
+		const message = errorToMessage(read.error);
+		stages.push(Object.freeze({
+			stage: "interpret",
+			input: text,
+			error: message
+		}));
+		failures.push(Object.freeze({
+			stage: "interpret",
+			code: "INTERPRET_FAILED",
+			message
+		}));
+		this.#emitter.emit("error", read.error);
+		return input.interpretation;
+	}
+	#blockage(questions, unready, verdict) {
+		if (questions.length > 0) return {
+			stage: "gate",
+			code: "BLOCKED",
+			message: `${String(questions.length)} blocking gap(s)`
+		};
+		if (unready.length > 0) return {
+			stage: "gate",
+			code: "BLOCKED",
+			message: `Gate refused: ${unready.join(", ")}`
+		};
+		if (!isLogicalVerdict(verdict)) return void 0;
+		const refused = verdict.rules.filter((entry) => !entry.conclusion).map((entry) => entry.id).join(", ");
+		if (refused.length === 0) return {
+			stage: "gate",
+			code: "BLOCKED",
+			message: "Gate refused: the supplied reasoner named no failing rule"
+		};
+		return {
+			stage: "gate",
+			code: "BLOCKED",
+			message: `Gate refused: ${refused}`
+		};
+	}
+	#unresolved(interpretation, failures) {
+		if (interpretation !== void 0) return [];
+		if (!failures.some((entry) => entry.stage === "interpret")) return [];
+		return [gap("gaps", "The interpret stage failed, so the request is unread and its unknowns are unknown", { blocking: true })];
+	}
+	#draft(input, interpretation, unresolved) {
+		const derived = interpretation === void 0 ? void 0 : deriveTask(interpretation.intent, interpretation.text, this.#actions, this.#domains);
+		const subject = input.task ?? derived;
+		if (subject === void 0) throw new BriefError("DRAFT_FAILED", "No task: supply BriefInput.task, or map the intent through the actions and domains vocabularies", {
+			stage: "draft",
+			field: "task"
+		});
+		return snapshotBrief(brief(subject, {
+			authority: input.authority ?? [],
+			manifest: input.manifest ?? manifest(),
+			outcomes: input.outcomes ?? [],
+			rules: input.rules ?? [],
+			invariants: input.invariants ?? [],
+			givens: [...interpretation === void 0 ? [] : deriveGivens(interpretation.entities), ...input.givens ?? []],
+			examples: input.examples ?? [],
+			assumptions: input.assumptions ?? [],
+			citations: input.citations ?? [],
+			gaps: [
+				...interpretation === void 0 ? [] : deriveGaps(interpretation.ambiguities),
+				...unresolved,
+				...input.gaps ?? []
+			],
+			risks: input.risks ?? [],
+			output: input.output ?? output("markdown"),
+			proofs: input.proofs ?? []
+		}));
+	}
+	#refuse(interpretation, draft, questions, verdict, stages, failures) {
+		const asked = Object.freeze([...questions]);
+		const briefing = Object.freeze({
+			...interpretation === void 0 ? {} : { interpretation },
+			questions: asked,
+			...verdict === void 0 ? {} : { verdict },
+			stages: Object.freeze([...stages]),
+			failures: Object.freeze([...failures]),
+			digest: (0, _orkestrel_interpret.digestValue)({
+				...draft === void 0 ? {} : { brief: draft },
+				questions,
+				failures
+			})
+		});
+		this.#emitter.emit("block", asked);
+		return briefing;
+	}
+	#refuseDestroyed() {
+		if (this.#destroyed) throw new BriefError("DESTROYED", "BriefCompiler has been destroyed");
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a compilation orchestrator.
+*
+* @remarks
+* With no engines supplied the compiler wires its own: a default `createInterpret()`
+* (empty vocabularies, so `options.actions` / `options.domains` drive `deriveTask`) and a
+* `createReason` carrying one `LogicalReasoner` for the gate. Pass your own to share
+* instances or observe their emitters — the compiler destroys ONLY what it created.
+*
+* @param options - Engines to borrow, the two intent vocabularies, and emitter hooks.
+* @returns A working {@link BriefCompilerInterface}.
+*
+* @example
+* ```ts
+* import { createBriefCompiler } from '@orkestrel/brief'
+*
+* const compiler = createBriefCompiler({ actions: { refactor: 'refactor' }, domains: { code: 'code' } })
+* compiler.destroy()
+* ```
+*/
+function createBriefCompiler(options) {
+	return new BriefCompiler(options);
+}
+/**
+* Create a brief registry.
+*
+* @param options - An optional seed collection plus emitter hooks.
+* @returns A working {@link BriefManagerInterface}.
+*
+* @example
+* ```ts
+* import { createBriefManager } from '@orkestrel/brief'
+*
+* const briefs = createBriefManager()
+* briefs.size // 0
+* briefs.destroy()
+* ```
+*/
+function createBriefManager(options) {
+	return new BriefManager(options);
+}
+/**
+* Compile `briefShape` into a guard, parser, JSON Schema, and seeded generator bundle.
+*
+* @remarks
+* The schema is what a tool boundary needs — hand it to `schemaToParameters` — and
+* `generate(seededRandom(n))` yields a reproducible on-contract brief for tests. This
+* bundle and the hand-composed `isBrief` are two independent mechanisms over one
+* vocabulary; `tests/src/core/shapers.test.ts` is what holds them in lockstep.
+*
+* @returns A `ContractInterface` over `Brief`.
+*
+* @example
+* ```ts
+* import { createBriefContract } from '@orkestrel/brief'
+* import { schemaToParameters, seededRandom } from '@orkestrel/contract'
+*
+* const contract = createBriefContract()
+* schemaToParameters(contract.schema) // the open tool-parameters record, no `as` anywhere
+* contract.generate(seededRandom(42)) // a reproducible on-contract brief
+* ```
+*/
+function createBriefContract() {
+	return (0, _orkestrel_contract.createContract)(briefShape);
+}
+//#endregion
+exports.BLANK_PATTERN = BLANK_PATTERN;
+exports.BriefCompiler = BriefCompiler;
+exports.BriefError = BriefError;
+exports.BriefManager = BriefManager;
+exports.DEFAULT_BRIEF_TURNS = DEFAULT_BRIEF_TURNS;
+exports.GATE_ID = GATE_ID;
+exports.LINE_BREAK_PATTERN = LINE_BREAK_PATTERN;
+exports.OUTPUT_FORMATS = OUTPUT_FORMATS;
+exports.RISK_SEVERITIES = RISK_SEVERITIES;
+exports.SINGLE_LINE_PATTERN = SINGLE_LINE_PATTERN;
+exports.TASK_DOMAINS = TASK_DOMAINS;
+exports.TASK_OPERATIONS = TASK_OPERATIONS;
+exports.assertBrief = assertBrief;
+exports.brief = brief;
+exports.briefShape = briefShape;
+exports.briefToContent = briefToContent;
+exports.briefToDispatch = briefToDispatch;
+exports.briefToGoal = briefToGoal;
+exports.briefToHash = briefToHash;
+exports.briefToMarkdown = briefToMarkdown;
+exports.briefToSubject = briefToSubject;
+exports.briefToTrace = briefToTrace;
+exports.citation = citation;
+exports.citationShape = citationShape;
+exports.countSentences = countSentences;
+exports.createBriefCompiler = createBriefCompiler;
+exports.createBriefContract = createBriefContract;
+exports.createBriefManager = createBriefManager;
+exports.deriveGaps = deriveGaps;
+exports.deriveGivens = deriveGivens;
+exports.deriveStatement = deriveStatement;
+exports.deriveTask = deriveTask;
+exports.errorToMessage = errorToMessage;
+exports.example = example;
+exports.exampleShape = exampleShape;
+exports.exampleToLines = exampleToLines;
+exports.findBlockingGaps = findBlockingGaps;
+exports.findManifestOverlaps = findManifestOverlaps;
+exports.findUngrantedAuthority = findUngrantedAuthority;
+exports.findUnmetRules = findUnmetRules;
+exports.findUnpairedGaps = findUnpairedGaps;
+exports.freezeBranch = freezeBranch;
+exports.freezeDeep = freezeDeep;
+exports.gap = gap;
+exports.gapShape = gapShape;
+exports.gateDefinition = gateDefinition;
+exports.given = given;
+exports.givenShape = givenShape;
+exports.isBrief = isBrief;
+exports.isBriefError = isBriefError;
+exports.isCitation = isCitation;
+exports.isExample = isExample;
+exports.isGap = isGap;
+exports.isGiven = isGiven;
+exports.isLine = isLine;
+exports.isLogicalVerdict = isLogicalVerdict;
+exports.isManifest = isManifest;
+exports.isObject = isObject;
+exports.isOutcome = isOutcome;
+exports.isOutput = isOutput;
+exports.isOutputFormat = isOutputFormat;
+exports.isProof = isProof;
+exports.isReference = isReference;
+exports.isRisk = isRisk;
+exports.isRiskSeverity = isRiskSeverity;
+exports.isRuleVerdict = isRuleVerdict;
+exports.isTask = isTask;
+exports.isTaskDomain = isTaskDomain;
+exports.isTaskOperation = isTaskOperation;
+exports.isText = isText;
+exports.lineShape = lineShape;
+exports.manifest = manifest;
+exports.manifestShape = manifestShape;
+exports.outcome = outcome;
+exports.outcomeShape = outcomeShape;
+exports.output = output;
+exports.outputShape = outputShape;
+exports.parseBrief = parseBrief;
+exports.pinBrief = pinBrief;
+exports.proof = proof;
+exports.proofShape = proofShape;
+exports.reference = reference;
+exports.referenceShape = referenceShape;
+exports.risk = risk;
+exports.riskShape = riskShape;
+exports.snapshotBrief = snapshotBrief;
+exports.task = task;
+exports.taskShape = taskShape;
+exports.textShape = textShape;
+exports.validateBrief = validateBrief;
+
+//# sourceMappingURL=index.cjs.map