@orkestrel/brief 0.0.1

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

@@ -0,0 +1,1911 @@
+import { Ambiguity } from '@orkestrel/interpret';
+import { ArrayShape } from '@orkestrel/contract';
+import { BooleanShape } from '@orkestrel/contract';
+import { ContractInterface } from '@orkestrel/contract';
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { Entity } from '@orkestrel/interpret';
+import { Guard } from '@orkestrel/contract';
+import { Intent } from '@orkestrel/interpret';
+import { Interpretation } from '@orkestrel/interpret';
+import { InterpretInterface } from '@orkestrel/interpret';
+import { LiteralShape } from '@orkestrel/contract';
+import { LogicalDefinition } from '@orkestrel/reason';
+import { LogicalResult } from '@orkestrel/reason';
+import { ManagerAddOptions } from '@orkestrel/interpret';
+import { NumberShape } from '@orkestrel/contract';
+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';
+
+/**
+ * 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
+     * ```
+     */
+ export declare function assertBrief(data: unknown): Brief;
+
+ /**
+  * 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.
+  */
+ export declare const BLANK_PATTERN: RegExp;
+
+ /**
+  * The closed execution contract — a rough request with every implicit decision resolved.
+  *
+  * @remarks
+  * `trace` and `hash` are DERIVED by `pinBrief`. The `brief` builder cannot set them, so
+  * nothing this package produces authors them.
+  *
+  * They are still SHAPE-checked rather than verified on the way in: `isBrief` and `parseBrief`
+  * accept any single-line string, because that is what lets a pinned brief round-trip through
+  * JSON and back. So an inbound brief's `hash` is not proof of its content — re-derive it with
+  * `briefToHash` if the source is untrusted. `BriefManager` does exactly that, and refuses a
+  * record whose stored hash contradicts its content.
+  */
+ export declare interface Brief {
+     readonly task: Task;
+     readonly authority: readonly Reference[];
+     readonly manifest: Manifest;
+     readonly outcomes: readonly Outcome[];
+     readonly rules: readonly string[];
+     readonly invariants: readonly string[];
+     readonly givens: readonly Given[];
+     readonly examples: readonly Example[];
+     readonly assumptions: readonly string[];
+     readonly citations: readonly Citation[];
+     readonly gaps: readonly Gap[];
+     readonly risks: readonly Risk[];
+     readonly output: Output;
+     readonly proofs: readonly Proof[];
+     readonly trace?: string;
+     readonly hash?: string;
+ }
+
+ /**
+  * 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')],
+  * })
+  * ```
+  */
+ export declare function brief(subject: Task, overrides?: Partial<Omit<Brief, 'task' | 'trace' | 'hash'>>): Brief;
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare class BriefCompiler implements BriefCompilerInterface {
+     #private;
+     constructor(options?: BriefCompilerOptions);
+     get emitter(): EmitterInterface<BriefCompilerEventMap>;
+     get interpret(): InterpretInterface;
+     get reason(): ReasonInterface;
+     compile(input: BriefInput): Briefing;
+     gate(source: Brief): LogicalResult;
+     destroy(): void;
+ }
+
+ /** The `BriefCompiler`'s push observation surface. */
+ export declare type BriefCompilerEventMap = {
+     compile: readonly [briefing: Briefing];
+     block: readonly [questions: readonly Gap[]];
+     error: readonly [error: unknown];
+     destroy: readonly [];
+ };
+
+ /** The compilation orchestrator contract. */
+ export declare interface BriefCompilerInterface {
+     readonly emitter: EmitterInterface<BriefCompilerEventMap>;
+     readonly interpret: InterpretInterface;
+     readonly reason: ReasonInterface;
+     compile(input: BriefInput): Briefing;
+     gate(brief: Brief): LogicalResult;
+     destroy(): void;
+ }
+
+ /**
+  * Input to `createBriefCompiler`.
+  *
+  * @remarks
+  * `interpret` and `reason` are BORROWED when supplied — the compiler destroys only
+  * engines it created itself. `actions` and `domains` map an interpret `Intent`'s free
+  * strings onto the closed task vocabularies; an unmapped value drafts no task. The gate
+  * is FIXED: readiness is this package's contract, not a caller setting.
+  *
+  * A borrowed engine is the caller's own code, not an attacker, and this package does not
+  * treat it as one. The line is OWNERSHIP, and it produces four obligations worth stating
+  * because none of them is enforced in code:
+  *
+  * - Every value a borrowed engine returns is OWNED AT ARRIVAL — copied where the value
+  *   permits it, sealed in place where it does not — and then read exactly once. What the
+  *   engine does with its own object afterwards cannot reach a `Briefing`.
+  * - 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.
+  * - Neither engine is narrowed past its published contract. `Entity.value` is `unknown` and
+  *   `LogicalResult` is an interface a class instance satisfies, so a value JSON cannot
+  *   express is on-contract and is sealed rather than refused.
+  * - `actions` and `domains` are read LIVE on every `compile`, not snapshotted at
+  *   construction. Mutating them between calls changes what the next call derives.
+  *
+  * Whether the engine is correct, and whether it answers the same way twice, remain the
+  * caller's own problem.
+  */
+ export declare interface BriefCompilerOptions {
+     readonly interpret?: InterpretInterface;
+     readonly reason?: ReasonInterface;
+     readonly actions?: Readonly<Record<string, TaskOperation>>;
+     readonly domains?: Readonly<Record<string, TaskDomain>>;
+     readonly on?: EmitterHooks<BriefCompilerEventMap>;
+     readonly error?: EmitterErrorHandler;
+ }
+
+ /**
+  * 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' }
+  * ```
+  */
+ export declare class BriefError extends Error {
+     readonly code: BriefErrorCode;
+     readonly context?: Readonly<Record<string, unknown>>;
+     constructor(code: BriefErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+ }
+
+ /**
+  * The machine-readable reasons a {@link BriefError} carries.
+  *
+  * @remarks
+  * Inside `compile` every stage failure is CONTAINED: the four `*_FAILED` codes and
+  * `BLOCKED` mark it on the {@link Briefing} rather than throwing.
+  *
+  * `INTERPRET_FAILED` needs a FOREIGN `InterpretInterface`. `@orkestrel/interpret` contains
+  * its own stage failures and returns a degraded `Interpretation` rather than throwing, so
+  * the default engine never raises it; `BriefCompilerOptions.interpret` is the seam a caller
+  * reaches it through. Three codes also reach a
+  * throw, from methods outside that containment — `INVALID` from `assertBrief`,
+  * `snapshotBrief`, and `pinBrief`; `DESTROYED` from any method after
+  * `destroy()`; and `GATE_FAILED` from `BriefCompiler.gate` when a borrowed reasoner returns a
+  * non-logical result OR throws its own error, which is translated rather than leaked so that
+  * every throw out of this module stays a `BriefError` an `isBriefError` catch can narrow.
+  */
+ export declare type BriefErrorCode = 'INTERPRET_FAILED' | 'DRAFT_FAILED' | 'GATE_FAILED' | 'PIN_FAILED' | 'BLOCKED' | 'INVALID' | 'DESTROYED';
+
+ /**
+  * The full, replayable outcome of one `compile()` call.
+  *
+  * @remarks
+  * `brief` is present exactly when the compile completed, so it is ALSO the completeness
+  * test — there is no `complete` flag, because a second stored fact is free to disagree
+  * with the first. `questions` carries what the caller must answer when it is absent.
+  *
+  * Nor is the caller's `text` echoed back. It is the caller's own value on the direct
+  * path, and `interpretation.text` on the interpret path, so storing it here would be one
+  * fact in two places. `interpretation` and `verdict` are the originating packages' own
+  * types — import them from `@orkestrel/interpret` and `@orkestrel/reason`.
+  *
+  * `digest` identifies this OUTCOME — the brief, the questions, and the failures together — so
+  * two identical compiles share it and a refused compile has one just as a complete one does.
+  * It is not `Brief.hash`, which identifies the brief's content alone and exists only on an
+  * emitted brief. Key a cache of compile results by `digest`; key a registry of briefs by
+  * `hash`.
+  */
+ export declare interface Briefing {
+     readonly interpretation?: Interpretation;
+     readonly brief?: Brief;
+     readonly questions: readonly Gap[];
+     readonly verdict?: LogicalResult;
+     readonly stages: readonly BriefStageRecord[];
+     readonly failures: readonly BriefStageFailure[];
+     readonly digest: string;
+ }
+
+ /**
+  * One `compile()` input.
+  *
+  * @remarks
+  * THREE classes of input, not two. `text` selects the interpret stage. `interpretation`
+  * supplies that stage's result directly: with no `text` it drives `deriveTask`,
+  * `deriveGivens`, and `deriveGaps` without running the language pipeline at all, and with
+  * `text` present it is also the FALLBACK the draft uses when the interpret engine throws.
+  * Every remaining key is a caller-authored section merged OVER whatever the draft derived.
+  *
+  * Supplying both `text` and `interpretation` is therefore meaningful: the engine's result
+  * wins when it succeeds, and the supplied one carries the compile when it does not.
+  */
+ export declare interface BriefInput {
+     readonly text?: string;
+     readonly interpretation?: Interpretation;
+     readonly task?: Task;
+     readonly authority?: readonly Reference[];
+     readonly manifest?: Manifest;
+     readonly outcomes?: readonly Outcome[];
+     readonly rules?: readonly string[];
+     readonly invariants?: readonly string[];
+     readonly givens?: readonly Given[];
+     readonly examples?: readonly Example[];
+     readonly assumptions?: readonly string[];
+     readonly citations?: readonly Citation[];
+     readonly gaps?: readonly Gap[];
+     readonly risks?: readonly Risk[];
+     readonly output?: Output;
+     readonly proofs?: readonly Proof[];
+ }
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare class BriefManager implements BriefManagerInterface {
+     #private;
+     constructor(options?: BriefManagerOptions);
+     get emitter(): EmitterInterface<BriefManagerEventMap>;
+     get size(): number;
+     has(id: string): boolean;
+     brief(id: string): BriefRecord | undefined;
+     briefs(): readonly BriefRecord[];
+     add(source: Brief, options?: ManagerAddOptions): BriefRecord;
+     remove(ids: readonly string[]): boolean;
+     remove(id: string): boolean;
+     remove(): void;
+     destroy(): void;
+ }
+
+ /** The `BriefManager`'s push observation surface. */
+ export declare type BriefManagerEventMap = {
+     add: readonly [id: string];
+     remove: readonly [id: string];
+     destroy: readonly [];
+ };
+
+ /**
+  * The brief registry contract.
+  *
+  * @remarks
+  * The array overload of `remove` is declared FIRST so an id list resolves to the batch
+  * form. `add` takes the fleet's own `ManagerAddOptions` from `@orkestrel/interpret`;
+  * omit its `id` and the record is keyed by the brief's own content hash, so re-adding
+  * unchanged content is a version no-op.
+  */
+ export declare interface BriefManagerInterface {
+     readonly emitter: EmitterInterface<BriefManagerEventMap>;
+     readonly size: number;
+     has(id: string): boolean;
+     brief(id: string): BriefRecord | undefined;
+     briefs(): readonly BriefRecord[];
+     add(brief: Brief, options?: ManagerAddOptions): BriefRecord;
+     remove(ids: readonly string[]): boolean;
+     remove(id: string): boolean;
+     remove(): void;
+     destroy(): void;
+ }
+
+ /** Input to `createBriefManager`. */
+ export declare interface BriefManagerOptions {
+     readonly briefs?: readonly Brief[];
+     readonly on?: EmitterHooks<BriefManagerEventMap>;
+     readonly error?: EmitterErrorHandler;
+ }
+
+ /** A versioned, content-hashed `Brief` inside a {@link BriefManagerInterface}. */
+ export declare interface BriefRecord {
+     readonly id: string;
+     readonly brief: Brief;
+     readonly version: number;
+     readonly hash: string;
+ }
+
+ /**
+  * 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.
+  */
+ export declare const briefShape: ObjectShape<{
+     task: ObjectShape<{
+         operation: LiteralShape<readonly TaskOperation[]>;
+         domain: LiteralShape<readonly TaskDomain[]>;
+         statement: StringShape;
+     }, false>;
+     authority: ArrayShape<ObjectShape<{
+         path: StringShape;
+         note: StringShape;
+     }, false>>;
+     manifest: ObjectShape<{
+         read: ArrayShape<ObjectShape<{
+             path: StringShape;
+             note: StringShape;
+         }, false>>;
+         edit: ArrayShape<ObjectShape<{
+             path: StringShape;
+             note: StringShape;
+         }, false>>;
+         locked: ArrayShape<ObjectShape<{
+             path: StringShape;
+             note: StringShape;
+         }, false>>;
+         forbidden: ArrayShape<ObjectShape<{
+             path: StringShape;
+             note: StringShape;
+         }, false>>;
+     }, false>;
+     outcomes: ArrayShape<ObjectShape<{
+         rank: NumberShape;
+         text: StringShape;
+         required: BooleanShape;
+     }, false>>;
+     rules: ArrayShape<StringShape>;
+     invariants: ArrayShape<StringShape>;
+     givens: ArrayShape<ObjectShape<{
+         category: StringShape;
+         name: StringShape;
+         value: StringShape;
+     }, false>>;
+     examples: ArrayShape<ObjectShape<{
+         input: StringShape;
+         output: StringShape;
+         note: OptionalShape<StringShape>;
+     }, false>>;
+     assumptions: ArrayShape<StringShape>;
+     citations: ArrayShape<ObjectShape<{
+         name: StringShape;
+         url: StringShape;
+         note: StringShape;
+     }, false>>;
+     gaps: ArrayShape<ObjectShape<{
+         field: StringShape;
+         question: StringShape;
+         blocking: BooleanShape;
+         candidates: OptionalShape<ArrayShape<StringShape>>;
+     }, false>>;
+     risks: ArrayShape<ObjectShape<{
+         severity: LiteralShape<readonly RiskSeverity[]>;
+         text: StringShape;
+         mitigation: StringShape;
+     }, false>>;
+     output: ObjectShape<{
+         format: LiteralShape<readonly OutputFormat[]>;
+         sections: OptionalShape<ArrayShape<StringShape>>;
+         include: OptionalShape<ArrayShape<StringShape>>;
+         exclude: OptionalShape<ArrayShape<StringShape>>;
+     }, false>;
+     proofs: ArrayShape<ObjectShape<{
+         text: StringShape;
+         command: StringShape;
+     }, false>>;
+     trace: OptionalShape<StringShape>;
+     hash: OptionalShape<StringShape>;
+ }, false>;
+
+ /** The four fixed compilation phases, in pipeline order. */
+ export declare type BriefStage = 'interpret' | 'draft' | 'gate' | 'pin';
+
+ /** A visible marker for a phase that failed. */
+ export declare interface BriefStageFailure {
+     readonly stage: BriefStage;
+     readonly code: BriefErrorCode;
+     readonly message: string;
+ }
+
+ /**
+  * One pipeline phase, discriminated by `stage`.
+  *
+  * @remarks
+  * Narrowing on `stage` types both payloads exactly, so a consumer reads a replay without
+  * a type assertion. A phase failed exactly when `error` is present.
+  */
+ export declare type BriefStageRecord = InterpretStageRecord | DraftStageRecord | GateStageRecord | PinStageRecord;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function briefToContent(source: Brief): string;
+
+ /**
+  * 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']
+  * ```
+  */
+ export declare function briefToDispatch(input: Brief): Dispatch;
+
+ /**
+  * 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.'
+  * ```
+  */
+ export declare function briefToGoal(input: Brief, turns?: number): string;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function briefToHash(source: Brief): string;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function briefToMarkdown(input: Brief): string;
+
+ /**
+  * 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, … }
+  * ```
+  */
+ export declare function briefToSubject(source: Brief): Subject;
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function briefToTrace(source: Brief): string;
+
+ /**
+  * One external source — what it is called, where it lives, and why it is cited.
+  *
+  * @remarks
+  * List ORDER is the trust order; there is no per-entry weight.
+  *
+  * The off-repository twin of {@link Reference}: `note` says why the entry is listed, in both.
+  * It carries `name` where a reference does not because a path is already readable and a URL
+  * is not, so the name is the citation's readable half rather than a classifier in disguise.
+  *
+  * It carries no classifier for a different reason than a reference does. A reference has none
+  * because its container already fixes what it is; a citation has none because the closed
+  * vocabulary this once held — `docs`, `spec`, `api`, `standard` — was a document taxonomy no
+  * mechanism read, and its members were not disjoint, so a page documenting an API or a
+  * specification that is also a standard forced an arbitrary choice.
+  *
+  * `url` is validated as a single line and NOT as a URL, so `url: 'docs'` is on-contract. That
+  * is a limit rather than an oversight: constraining it needs a `pattern` on `citationShape`,
+  * and the shape DSL's seeded generator builds a random alphanumeric string and throws when it
+  * fails the pattern — so any pattern requiring a scheme's colon makes `createBriefContract()`
+  * ungeneratable for the whole brief. Constraining only the guard would leave the guard and the
+  * compiled shape disagreeing, which is the parity this package holds in lockstep. Four working
+  * mechanisms beat one stricter member.
+  *
+  * The cost lands on one migration: `citation` takes `(name, url, note)` where it once took
+  * `(name, role, url)` — three strings either way, so a stale call still compiles and still
+  * passes the guard, and only renders wrong. Nothing is published, so a version bump carries it.
+  */
+ export declare interface Citation {
+     readonly name: string;
+     readonly url: string;
+     readonly note: string;
+ }
+
+ /**
+  * 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',
+  * )
+  * ```
+  */
+ export declare function citation(name: string, url: string, note: string): Citation;
+
+ /** The `Citation` shape — a name, a locator, and why the source is cited. */
+ export declare const citationShape: ObjectShape<{
+     name: StringShape;
+     url: StringShape;
+     note: StringShape;
+ }, false>;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function countSentences(statement: string): number;
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare function createBriefCompiler(options?: BriefCompilerOptions): BriefCompilerInterface;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function createBriefContract(): ContractInterface<Brief>;
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare function createBriefManager(options?: BriefManagerOptions): BriefManagerInterface;
+
+ /**
+  * `16` — the default turn cap `briefToGoal` renders.
+  *
+  * @remarks
+  * Domain-qualified so the barrel stays collision-free as sibling modules add their own
+  * turn defaults.
+  */
+ export declare const DEFAULT_BRIEF_TURNS = 16;
+
+ /**
+  * 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 }]
+  * ```
+  */
+ export declare function deriveGaps(ambiguities: readonly Ambiguity[]): readonly Gap[];
+
+ /**
+  * 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' }]
+  * ```
+  */
+ export declare function deriveGivens(entities: readonly Entity[]): readonly Given[];
+
+ /**
+  * 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('') // ''
+  * ```
+  */
+ export declare function deriveStatement(text: string): string;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function deriveTask(intent: Intent, text: string, actions: Readonly<Record<string, TaskOperation>>, domains: Readonly<Record<string, TaskDomain>>): Task | undefined;
+
+ /**
+  * The subagent projection of a brief.
+  *
+  * @remarks
+  * Two orthogonal axes, not five partitions. PERMISSION is `read`, `edit`, `locked`, and
+  * `forbidden`, with `edit` the owned set two concurrent dispatches must not intersect on and
+  * `locked` and `forbidden` do-not-touch. PRECEDENCE is `authority`, in ranked order, index 0
+  * winning every conflict.
+  *
+  * `authority` therefore OVERLAPS the permission arrays by design: a ranked path ALWAYS also
+  * sits in `read`, `edit`, or `locked`, because the executor has to open what it obeys, and
+  * the `granted` gate rule refuses a brief where it does not. Read the four to decide what may
+  * be touched and `authority` to decide what wins. Never union all five — that was already
+  * wrong before `authority` existed, because `forbidden` is an exclusion rather than a grant.
+  * `authority` is a path list rather than a rendered section because a machine consumer must
+  * reach mandatory authority without parsing `prompt`, which is written for a model.
+  *
+  * The four permission arrays are mutually disjoint in a GATED brief — `findManifestOverlaps`
+  * measures it and the `disjoint` rule refuses on it. `briefToDispatch` is a pure projection
+  * and runs no gate, so projecting an unvetted draft can produce arrays that intersect. Gate
+  * before you dispatch, or treat disjointness as unproven.
+  */
+ export declare interface Dispatch {
+     readonly prompt: string;
+     readonly authority: readonly string[];
+     readonly read: readonly string[];
+     readonly edit: readonly string[];
+     readonly locked: readonly string[];
+     readonly forbidden: readonly string[];
+ }
+
+ /** The `draft` phase snapshot — the caller's input in, an unpinned `Brief` out. */
+ export declare interface DraftStageRecord {
+     readonly stage: 'draft';
+     readonly input: BriefInput;
+     readonly output?: Brief;
+     readonly error?: string;
+ }
+
+ /**
+  * 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'
+  * ```
+  */
+ export declare function errorToMessage(error: unknown): string;
+
+ /** One input to output exemplar — the highest-leverage ambiguity remover. */
+ export declare interface Example {
+     readonly input: string;
+     readonly output: string;
+     readonly note?: string;
+ }
+
+ /**
+  * 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')
+  * ```
+  */
+ export declare function example(input: string, result: string, note?: string): Example;
+
+ /** The `Example` shape — one input to output exemplar. */
+ export declare const exampleShape: ObjectShape<{
+     input: StringShape;
+     output: StringShape;
+     note: OptionalShape<StringShape>;
+ }, false>;
+
+ /**
+  * 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 `']
+  * ```
+  */
+ export declare function exampleToLines(entry: Example): readonly string[];
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function findBlockingGaps(source: Brief): readonly Gap[];
+
+ /**
+  * 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']
+  * ```
+  */
+ export declare function findManifestOverlaps(source: Brief): readonly string[];
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function findUngrantedAuthority(source: Brief): readonly string[];
+
+ /**
+  * 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')],
+  * 	}),
+  * ) // []
+  * ```
+  */
+ export declare function findUnmetRules(source: Brief): readonly string[];
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function findUnpairedGaps(source: Brief): readonly Gap[];
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function freezeBranch<T>(value: T, seen: WeakSet<object>): T;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function freezeDeep<T>(value: T): T;
+
+ /**
+  * One unknown the brief has not resolved.
+  *
+  * @remarks
+  * `blocking: true` means no safe default exists and the gate must fail closed. An
+  * open gap proceeds on a narrow recorded assumption instead.
+  */
+ export declare interface Gap {
+     readonly field: string;
+     readonly question: string;
+     readonly blocking: boolean;
+     readonly candidates?: readonly string[];
+ }
+
+ /**
+  * 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'] })
+  * ```
+  */
+ export declare function gap(field: string, question: string, overrides?: Partial<Omit<Gap, 'field' | 'question'>>): Gap;
+
+ /** The `Gap` shape — an unknown, whether it blocks, and the candidates that would close it. */
+ export declare const gapShape: ObjectShape<{
+     field: StringShape;
+     question: StringShape;
+     blocking: BooleanShape;
+     candidates: OptionalShape<ArrayShape<StringShape>>;
+ }, false>;
+
+ /** `'gate'` — the id of the `gateDefinition()` logical definition. */
+ export declare const GATE_ID = "gate";
+
+ /**
+  * 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()
+  * ```
+  */
+ export declare function gateDefinition(): LogicalDefinition;
+
+ /** The `gate` phase snapshot — the readiness `Subject` in, the reasoner's verdict out. */
+ export declare interface GateStageRecord {
+     readonly stage: 'gate';
+     readonly input: Subject;
+     readonly output?: LogicalResult;
+     readonly error?: string;
+ }
+
+ /** One context fact handed to the executor — a convention, a version, a constraint value. */
+ export declare interface Given {
+     readonly category: string;
+     readonly name: string;
+     readonly value: string;
+ }
+
+ /**
+  * 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')
+  * ```
+  */
+ export declare function given(category: string, name: string, value: string): Given;
+
+ /** The `Given` shape — one categorized context fact. */
+ export declare const givenShape: ObjectShape<{
+     category: StringShape;
+     name: StringShape;
+     value: StringShape;
+ }, false>;
+
+ /**
+  * The `interpret` phase snapshot — raw text in, an `Interpretation` out.
+  *
+  * @remarks
+  * `output` is absent exactly when `error` is present, which is what makes the phase
+  * failure derivable rather than stored twice.
+  */
+ export declare interface InterpretStageRecord {
+     readonly stage: 'interpret';
+     readonly input: string;
+     readonly output?: Interpretation;
+     readonly error?: string;
+ }
+
+ /**
+  * `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.
+  */
+ export declare const isBrief: Guard<Brief>;
+
+ /**
+  * 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'
+  * }
+  * ```
+  */
+ export declare function isBriefError(value: unknown): value is BriefError;
+
+ /** `true` when the value is a well-formed `Citation` — all three members single-line. */
+ export declare const isCitation: Guard<Citation>;
+
+ /**
+  * `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.
+  */
+ export declare const isExample: Guard<Example>;
+
+ /** `true` when the value is a well-formed `Gap`. */
+ export declare const isGap: Guard<Gap>;
+
+ /** `true` when the value is a well-formed `Given` — `value` may be empty but stays one line. */
+ export declare const isGiven: Guard<Given>;
+
+ /** `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`.
+  *
+  * @remarks
+  * Partition presence only — disjointness is `validateBrief`'s semantic pass.
+  */
+ 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>;
+
+ /** `true` when the value is a well-formed `Output` — `format` on the closed vocabulary. */
+ export declare const isOutput: Guard<Output>;
+
+ /** `true` when the value is one of the five `OutputFormat` literals. */
+ export declare const isOutputFormat: Guard<OutputFormat>;
+
+ /** `true` when the value is a well-formed `Proof`. */
+ export declare const isProof: Guard<Proof>;
+
+ /** `true` when the value is a well-formed `Reference` — both members required, both single-line. */
+ export declare const isReference: Guard<Reference>;
+
+ /** `true` when the value is a well-formed `Risk` — `severity` on the closed vocabulary. */
+ export declare const isRisk: Guard<Risk>;
+
+ /** `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>;
+
+ /** `true` when the value is one of the eight `TaskDomain` literals. */
+ export declare const isTaskDomain: Guard<TaskDomain>;
+
+ /** `true` when the value is one of the twelve `TaskOperation` literals. */
+ export declare const isTaskOperation: Guard<TaskOperation>;
+
+ /**
+  * `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.
+  */
+ export declare const isText: Guard<string>;
+
+ /**
+  * 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.
+  */
+ export declare const LINE_BREAK_PATTERN: RegExp;
+
+ /** A non-empty single-line string — the shape mirror of `isLine`. */
+ export declare const lineShape: StringShape;
+
+ /**
+  * The four disjoint file partitions of a brief.
+  *
+  * @remarks
+  * `read` order is the reading order. A path in more than one partition is a
+  * `validateBrief` error, found by `findManifestOverlaps`.
+  */
+ export declare interface Manifest {
+     readonly read: readonly Reference[];
+     readonly edit: readonly Reference[];
+     readonly locked: readonly Reference[];
+     readonly forbidden: readonly Reference[];
+ }
+
+ /**
+  * 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')] })
+  * ```
+  */
+ export declare function manifest(partitions?: Partial<Manifest>): Manifest;
+
+ /** The `Manifest` shape — four disjoint reference partitions. */
+ export declare const manifestShape: ObjectShape<{
+     read: ArrayShape<ObjectShape<{
+         path: StringShape;
+         note: StringShape;
+     }, false>>;
+     edit: ArrayShape<ObjectShape<{
+         path: StringShape;
+         note: StringShape;
+     }, false>>;
+     locked: ArrayShape<ObjectShape<{
+         path: StringShape;
+         note: StringShape;
+     }, false>>;
+     forbidden: ArrayShape<ObjectShape<{
+         path: StringShape;
+         note: StringShape;
+     }, false>>;
+ }, false>;
+
+ /**
+  * One ranked outcome — a result, never a step.
+  *
+  * @remarks
+  * `required: true` gates "done"; a demoted outcome is desirable but not blocking.
+  */
+ export declare interface Outcome {
+     readonly rank: number;
+     readonly text: string;
+     readonly required: boolean;
+ }
+
+ /**
+  * 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)
+  * ```
+  */
+ export declare function outcome(rank: number, text: string, required?: boolean): Outcome;
+
+ /** The `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
+ export declare const outcomeShape: ObjectShape<{
+     rank: NumberShape;
+     text: StringShape;
+     required: BooleanShape;
+ }, false>;
+
+ /**
+  * The closed shape of the deliverable.
+  *
+  * @remarks
+  * `format` is required; `sections` / `include` / `exclude` refine it.
+  */
+ export declare interface Output {
+     readonly format: OutputFormat;
+     readonly sections?: readonly string[];
+     readonly include?: readonly string[];
+     readonly exclude?: readonly string[];
+ }
+
+ /**
+  * 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'] })
+  * ```
+  */
+ export declare function output(format: OutputFormat, overrides?: Partial<Omit<Output, 'format'>>): Output;
+
+ /** The five `OutputFormat` values, frozen. */
+ export declare const OUTPUT_FORMATS: readonly OutputFormat[];
+
+ /** The closed vocabulary of deliverable shapes. */
+ export declare type OutputFormat = 'markdown' | 'json' | 'code' | 'diff' | 'prose';
+
+ /** The `Output` shape — a closed format plus its optional refinements. */
+ export declare const outputShape: ObjectShape<{
+     format: LiteralShape<readonly OutputFormat[]>;
+     sections: OptionalShape<ArrayShape<StringShape>>;
+     include: OptionalShape<ArrayShape<StringShape>>;
+     exclude: OptionalShape<ArrayShape<StringShape>>;
+ }, false>;
+
+ /**
+  * 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
+  * ```
+  */
+ export declare function parseBrief(value: string): Brief | undefined;
+
+ /**
+  * 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'
+      * ```
+      */
+  export declare function pinBrief(source: Brief): Brief;
+
+  /** The `pin` phase snapshot — the drafted `Brief` in, the pinned `Brief` out. */
+  export declare interface PinStageRecord {
+      readonly stage: 'pin';
+      readonly input: Brief;
+      readonly output?: Brief;
+      readonly error?: string;
+  }
+
+  /**
+   * One mechanical, transcript-provable check.
+   *
+   * @remarks
+   * `command` should carry a clear exit signal — it becomes the `/goal` condition verbatim.
+   */
+  export declare interface Proof {
+      readonly text: string;
+      readonly command: string;
+  }
+
+  /**
+   * 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')
+   * ```
+   */
+  export declare function proof(text: string, command: string): Proof;
+
+  /** The `Proof` shape — the claim and the command that settles it. */
+  export declare const proofShape: ObjectShape<{
+      text: StringShape;
+      command: StringShape;
+  }, false>;
+
+  /**
+   * One referenced path and why it is listed.
+   *
+   * @remarks
+   * The ONE path record. A reference means different things in different containers, and the
+   * container is what says which: `Brief.authority` ranks its entries so index 0 wins every
+   * conflict, and each `Manifest` partition states a permission. The record itself carries no
+   * classifier, because a second label on the row would restate what the container already
+   * fixed — and the label this package used to carry was one repository's document taxonomy
+   * rather than a domain.
+   *
+   * `note` is required. A path with no rationale is interpretation left to do, which is the
+   * one thing a brief exists to remove.
+   */
+  export declare interface Reference {
+      readonly path: string;
+      readonly note: string;
+  }
+
+  /**
+   * 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' }
+   * ```
+   */
+  export declare function reference(path: string, note: string): Reference;
+
+  /** The `Reference` shape — a path and the note that justifies listing it. */
+  export declare const referenceShape: ObjectShape<{
+      path: StringShape;
+      note: StringShape;
+  }, false>;
+
+  /** One pre-empted risk and the mitigation that answers it. */
+  export declare interface Risk {
+      readonly severity: RiskSeverity;
+      readonly text: string;
+      readonly mitigation: string;
+  }
+
+  /**
+   * 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')
+   * ```
+   */
+  export declare function risk(severity: RiskSeverity, text: string, mitigation: string): Risk;
+
+  /** The three `RiskSeverity` values, frozen. */
+  export declare const RISK_SEVERITIES: readonly RiskSeverity[];
+
+  /** The closed vocabulary of risk severities. */
+  export declare type RiskSeverity = 'low' | 'medium' | 'high';
+
+  /** The `Risk` shape — a closed severity, the risk, and its mitigation. */
+  export declare const riskShape: ObjectShape<{
+      severity: LiteralShape<readonly RiskSeverity[]>;
+      text: StringShape;
+      mitigation: StringShape;
+  }, false>;
+
+  /**
+   * 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.
+   */
+  export declare const SINGLE_LINE_PATTERN: RegExp;
+
+  /**
+   * 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
+       * ```
+       */
+   export declare function snapshotBrief(source: Brief): Brief;
+
+   /**
+    * What the brief asks for, in one imperative sentence.
+    *
+    * @remarks
+    * A compound `statement` is two briefs — `validateBrief` errors on more than one sentence.
+    */
+   export declare interface Task {
+       readonly operation: TaskOperation;
+       readonly domain: TaskDomain;
+       readonly statement: string;
+   }
+
+   /**
+    * 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.')
+    * ```
+    */
+   export declare function task(operation: TaskOperation, domain: TaskDomain, statement: string): Task;
+
+   /** The eight `TaskDomain` values, frozen. */
+   export declare const TASK_DOMAINS: readonly TaskDomain[];
+
+   /** The twelve `TaskOperation` values, frozen. */
+   export declare const TASK_OPERATIONS: readonly TaskOperation[];
+
+   /** The closed vocabulary of the subject matter a brief operates on. */
+   export declare type TaskDomain = 'code' | 'writing' | 'research' | 'analysis' | 'design' | 'data' | 'ops' | 'other';
+
+   /**
+    * The closed vocabulary of what a brief asks for.
+    *
+    * @remarks
+    * A request that fits none of these twelve is mis-scoped rather than a missing
+    * literal. Compose with `literalOf(TASK_OPERATIONS)` or `parseEnum(value, TASK_OPERATIONS)`.
+    */
+   export declare type TaskOperation = 'create' | 'refactor' | 'debug' | 'extract' | 'migrate' | 'explain' | 'review' | 'optimize' | 'audit' | 'test' | 'document' | 'plan';
+
+   /** The `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
+   export declare const taskShape: ObjectShape<{
+       operation: LiteralShape<readonly TaskOperation[]>;
+       domain: LiteralShape<readonly TaskDomain[]>;
+       statement: StringShape;
+   }, false>;
+
+   /** A single-line string of any length, including empty. */
+   export declare const textShape: StringShape;
+
+   /**
+    * 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
+    * ```
+    */
+   export declare function validateBrief(source: Brief): ReasonValidationResult;
+
+   export { }