@orkestrel/brief 0.0.7 → 0.0.8

package/dist/src/core/index.js

@@ -3,7 +3,13 @@ import { canonicalize, collapseWhitespace, createInterpret, digestValue, isInter
 import { createAtom, createCompound, createLogicalDefinition, createLogicalReasoner, createReason, createRule, formatField, isLogicalResult } from "@orkestrel/reason";
 import { Emitter } from "@orkestrel/emitter";
 //#region src/core/constants.ts
-/** Lists the `TaskOperation` values, frozen. */
+/**
+* Lists the `TaskOperation` values, frozen.
+*
+* @remarks
+* Compose the tuple rather than restating its members: `literalOf(TASK_OPERATIONS)` builds the
+* guard and `parseEnum(value, TASK_OPERATIONS)` coerces a bare value against it.
+*/
 var TASK_OPERATIONS = Object.freeze([
 	"create",
 	"refactor",
@@ -86,7 +92,7 @@ var GATE_ID = "gate";
 * Matches every line terminator a brief field refuses.
 *
 * @remarks
-* Every ECMAScript line terminator, not just `\n`: a renderer that splits on any of them
+* Every ECMAScript line terminator, not only `\n`: a renderer that splits on any of them
 * would let the others 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
@@ -94,7 +100,7 @@ var GATE_ID = "gate";
 */
 var LINE_BREAK_PATTERN = /\r\n|[\n\r\u2028\u2029]/;
 /**
-* Holds the positive form of {@link LINE_BREAK_PATTERN}, for the shape DSL.
+* Holds the positive form of {@link LINE_BREAK_PATTERN}, for a `stringShape` `pattern`.
 *
 * @remarks
 * `stringShape`'s `pattern` must MATCH an accepted value, so the guard's refusal regex
@@ -120,6 +126,9 @@ var BLANK_PATTERN = /^ +$/;
 * Represents the one error class this package throws.
 *
 * @remarks
+* Extends `Error` with a readonly `code` on the `BriefErrorCode` vocabulary and an optional
+* readonly `context` record carrying whatever the raising site can supply.
+*
 * 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
@@ -168,14 +177,21 @@ function isBriefError(value) {
 }
 //#endregion
 //#region src/core/shapers.ts
-/** Describes a single-line string of any length, including empty. */
+/** Describes a single-line string of any length, including empty — the shape mirror of `isText`. */
 var textShape = stringShape({ pattern: SINGLE_LINE_PATTERN });
 /** Describes a non-empty single-line string — the shape mirror of `isLine`. */
 var lineShape = stringShape({
 	min: 1,
 	pattern: SINGLE_LINE_PATTERN
 });
-/** Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty statement. */
+/**
+* Describes the `Task` shape — closed operation and domain vocabularies plus a non-empty
+* statement.
+*
+* @remarks
+* `literalShape(TASK_OPERATIONS)` and `literalShape(TASK_DOMAINS)` compile the same tuples the
+* guards read, and `statement` carries `min: 1`.
+*/
 var taskShape = objectShape({
 	operation: literalShape(TASK_OPERATIONS),
 	domain: literalShape(TASK_DOMAINS),
@@ -186,14 +202,25 @@ var referenceShape = objectShape({
 	path: lineShape,
 	note: lineShape
 }, { description: "One referenced path and why it is listed." });
-/** Describes the `Manifest` shape — disjoint reference partitions. */
+/**
+* Describes the `Manifest` shape — disjoint reference partitions.
+*
+* @remarks
+* Each partition is an `arrayShape(referenceShape)`; disjointness is `validateBrief`'s pass
+* rather than the shape's.
+*/
 var manifestShape = objectShape({
 	read: arrayShape(referenceShape),
 	edit: arrayShape(referenceShape),
 	locked: arrayShape(referenceShape),
 	forbidden: arrayShape(referenceShape)
 }, { description: "The disjoint file partitions of a brief." });
-/** Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done. */
+/**
+* Describes the `Outcome` shape — a one-based rank, the result text, and whether it gates done.
+*
+* @remarks
+* `rank` is an `integerShape({ min: 1 })`, so a zero or fractional rank is off-contract.
+*/
 var outcomeShape = objectShape({
 	rank: integerShape({ min: 1 }),
 	text: lineShape,
@@ -285,6 +312,10 @@ var isText = (value) => isString(value) && !LINE_BREAK_PATTERN.test(value);
 /**
 * Checks whether the value is a non-empty string holding no line terminator.
 *
+* @remarks
+* The shape of nearly every brief field: a path, a note, a statement, a rule, and a command
+* all narrow through it.
+*
 * @param value - The value to inspect.
 * @returns True if `value` is a non-empty string holding no line terminator; false otherwise.
 */
@@ -623,6 +654,10 @@ function buildTask(operation, domain, statement) {
 /**
 * Assembles a `Reference` from a path and the note that justifies listing it.
 *
+* @remarks
+* The one builder for an authority entry and a manifest entry alike: the container the record
+* lands in is what says whether the path is ranked or permitted.
+*
 * @param path - The referenced path or glob.
 * @param note - Why the path is listed.
 * @returns A fresh `Reference`.
@@ -1009,6 +1044,10 @@ function countSentences(statement) {
 /**
 * Lists the gaps that block emission.
 *
+* @remarks
+* A non-empty result means the gate must fail closed: a blocking gap has no safe default, so
+* the compile yields a visible incomplete `Briefing` carrying the questions instead of a brief.
+*
 * @param source - The brief to inspect.
 * @returns Every gap carrying `blocking: true`, in declaration order.
 *
@@ -1037,7 +1076,7 @@ function findBlockingGaps(source) {
 * are disjoint — `findManifestOverlaps` and the `disjoint` rule enforce it — so a forbidden
 * path is in none of the 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.
+* entirely: the brief 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
@@ -1501,8 +1540,9 @@ function exampleToLines(entry) {
 * Projects 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.
+* Sections render in authority order, so the executor meets what wins a conflict before what
+* it may touch. 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 input - The brief to render.
 * @returns The markdown prompt.
@@ -1631,10 +1671,11 @@ function briefToGoal(input, turns = 16) {
 * Projects 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.
+* `edit` is exactly `manifest.edit` — the owned set — so two dispatches whose `edit` sets do
+* not intersect can run concurrently under the same brief without conflict. `locked` and
+* `forbidden` cross unchanged as the do-not-touch sets.
 *
-* `authority` is exactly `brief.authority` in rank order, and it is a SEPARATE axis from the
+* `authority` is exactly `brief.authority` in rank order, and it is a separate axis from the
 * permission sets rather than a further 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.
@@ -2281,6 +2322,45 @@ var BriefCompiler = class {
 * emitter hooks.
 * @returns A working {@link BriefCompilerInterface}.
 *
+* @example Compile and project a brief
+* ```ts
+* import {
+* 	briefToGoal,
+* 	briefToMarkdown,
+* 	buildOutcome,
+* 	buildProof,
+* 	buildTask,
+* 	createBriefCompiler,
+* } from '@orkestrel/brief'
+*
+* const compiler = createBriefCompiler()
+*
+* const briefing = compiler.compile({
+* 	task: buildTask('refactor', 'code', 'Refactor useForm to native browser form APIs.'),
+* 	authority: [{ path: 'AGENTS.md', note: 'project law; wins every conflict' }],
+* 	manifest: {
+* 		read: [
+* 			{ path: 'AGENTS.md', note: 'project law; wins every conflict' },
+* 			{ path: 'guides/browser.md', note: 'the composable contract' },
+* 		],
+* 		edit: [{ path: 'src/browser/composables/useForm.ts', note: 'the composable being refactored' }],
+* 		locked: [{ path: 'src/browser/types.ts', note: 'the published contract' }],
+* 		forbidden: [{ path: 'app/**', note: 'out of scope' }],
+* 	},
+* 	outcomes: [buildOutcome(1, 'useForm uses native FormData with no behavior change')],
+* 	proofs: [buildProof('type-check and lint pass', 'npm run check')],
+* })
+*
+* briefing.brief !== undefined // true — the brief is present exactly when the gate passed
+* if (briefing.brief !== undefined) {
+* 	briefToMarkdown(briefing.brief) // the copy-ready agent prompt
+* 	briefToGoal(briefing.brief) // the /goal completion condition
+* }
+*
+* compiler.emitter.on('block', (questions) => questions.length)
+* compiler.destroy()
+* ```
+*
 * @example
 * ```ts
 * import { createBriefCompiler } from '@orkestrel/brief'