wingfoil 0.2.2 → 0.3.0

package/dist/core/context.js

@@ -1,35 +1,71 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrittenTimestamp = exports.CONTEXT_PAYLOAD_FORMAT = void 0;
 exports.selectDirectivesById = selectDirectivesById;
 exports.resolveRoleDirectives = resolveRoleDirectives;
+exports.validateExecutionContext = validateExecutionContext;
+exports.serializeExecutionContext = serializeExecutionContext;
 exports.assembleExecutionContext = assembleExecutionContext;
 /**
- * Agent execution context assembly (task-037-role-task-scoped-context, REQ-STATE-05) — the
- * `directive-loader` + a minimal `context-builder` slice of
- * `spec-012-context-loader-relevance-filtering` (§1 "placement & responsibilities", §5 "Directive
- * resolution"). Satisfies REQ-STATE-05's Fit Criterion, verbatim: "The assembled context object
- * exposes separate `dna`, `memory`, `directives` sections; it contains 100% of the role's assigned
- * directives and 0 directives of other roles."
+ * The `spec-012-context-loader-relevance-filtering` context builder: the `directive-loader`
+ * ({@link resolveRoleDirectives}, §5), the `dna-loader` (§4), the call into the `relevance-filter`
+ * (`./relevance.ts`, §6), the validator (P5.4.4 sc. 3) and the canonical serializer (§7), behind one
+ * public entry, {@link assembleExecutionContext} (task-176; task-037 built the directive half,
+ * REQ-STATE-05).
  *
- * **Archived elements are excluded** (REQ-STATE-06, the `{deprecated, superseded}` set ratified by
- * `dl-028-archived-states-excluded-from-context`): {@link assembleExecutionContext} drops a resolved
- * element whose `status` is archived, through the shared `isArchivedStatus` primitive rather than any
- * local notion of "archived". This closed `bug-010-deprecated-reaches-agent-context` — which this
- * header previously recorded as an open gap — together with the `wingfoil://memory/{type}` collection
- * Resource, the other surface that bug covered (`task-069-fix-archived-excluded-from-agent-context`).
+ * Every read is pinned to `spec-012` §2's `stateRef`: the entry resolves it once to a commit sha
+ * (`resolveRevision`) and reads every pillar and every Memory document at that sha through task-137's
+ * `…AtRev` readers. The working tree is never read, so the same `(role, element, stateRef, limits)`
+ * yields the same bytes (§8, REQ-SYS-07).
  *
- * Still deliberately NOT the full spec-012 pipeline: no `ContextRequest`/`stateRef` pinning, no tiered
- * (T1–T4) Memory relevance ranking, no bounding caps, and no canonical byte-for-byte Markdown
- * serialization (§7). Those are split across sibling Wave-1 v0.2 tasks
- * (task-035-bounded-context-relevance REQ-PERF-05, task-038-deprecated-excluded-from-context
- * REQ-STATE-06) and v0.3 (`REQ-SYS-07`, `REQ-PERF-01`, `REQ-STATE-09`, the real `agent execute`
- * CLI/MCP surface) — see this task's Execution Notes for the full scope decision. This module wraps
- * only existing, already-shipped primitives: `loadDirectives`/`loadRolesYaml` (`./loaders`),
- * `findMemoryDocumentByTypeAndId` and `isArchivedStatus` (`../memory`, task-011/task-035) — no
- * scan/parse logic and no second status predicate is reimplemented here.
+ * **Archived elements never reach a context** (REQ-STATE-06, the `{deprecated, superseded}` set
+ * ratified by `dl-028-archived-states-excluded-from-context`): an archived subject element is refused,
+ * and archived candidates are dropped by the relevance filter — both through the shared
+ * `isArchivedStatus`.
  */
+const jsYaml = __importStar(require("js-yaml"));
+const js_yaml_1 = require("js-yaml");
 const memory_1 = require("../memory");
+const storage_1 = require("../storage");
+const validation_1 = require("../validation");
 const builtin_asset_1 = require("./builtin-asset");
+const loaders_1 = require("./loaders");
+const relevance_1 = require("./relevance");
+const revision_1 = require("./revision");
+const types_1 = require("./types");
 /** `assignments` is a plain object parsed from YAML, so a role named `toString`, `constructor`,
  * `valueOf`, `hasOwnProperty` or `__proto__` would otherwise resolve to an inherited
  * `Object.prototype` member instead of `undefined`. Read own properties only. */
@@ -138,55 +174,555 @@ function resolveRoleDirectives(directiveFiles, rolesYaml, role) {
     return { directives: [...selection.byId.values()], warnings };
 }
 /**
- * Assemble a role- and task-scoped {@link ExecutionContext} (REQ-STATE-05) from already-loaded pillar
- * config. Given the same inputs and unchanged on-disk Memory content, the output is deep-equal across
- * calls: the function itself introduces no wall-clock, randomness, or unordered iteration
- * (REQ-SYS-07's discipline, applied to this narrower slice per REQ-STATE-05's own rationale "crisp,
- * low-noise context; determinism"), and `directives` is totally ordered by
- * {@link resolveRoleDirectives}.
+ * The sections {@link validateExecutionContext} checks, in §7 order, with the shape each must have.
+ * The name is the {@link ExecutionContext} property, so the refusal names what to address.
+ */
+const REQUIRED_SECTIONS = [
+    ['element', (value) => isRecord(value)],
+    ['dna', (value) => isRecord(value) && Array.isArray(value.modules)],
+    ['directives', (value) => Array.isArray(value)],
+    ['memory', (value) => Array.isArray(value)],
+];
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function missingSection(name) {
+    return `invalid execution context: missing '${name}' section`;
+}
+/**
+ * Validate an assembled context before anything uses it (P5.4.4 sc. 3). The first section that is
+ * absent, or not of its section's shape, refuses the context with `VALIDATION` and the scenario's
+ * message, verbatim: `invalid execution context: missing '<section>' section`. Sections are checked in
+ * §7 order — `element`, `dna`, `directives`, `memory` — so the refusal is deterministic.
+ */
+function validateExecutionContext(candidate) {
+    const value = isRecord(candidate) ? candidate : {};
+    for (const [name, hasShape] of REQUIRED_SECTIONS) {
+        if (!hasShape(value[name]))
+            return (0, types_1.coreErr)({ code: 'VALIDATION', message: missingSection(name) });
+    }
+    return (0, types_1.coreOk)(candidate);
+}
+/**
+ * The payload's format version (`dl-150` option B, the `dl-149` format key): the first field of the
+ * header comment. A change to the bytes §7 pins is a new format.
+ */
+exports.CONTEXT_PAYLOAD_FORMAT = 1;
+/**
+ * A YAML timestamp scalar exactly as its document wrote it (`bug-232`, review F1 of task-255): the
+ * frontmatter the payload carries holds one of these where js-yaml's default schema would hold a
+ * `Date`, so `2026-10-05`, `2026-10-05T00:00:00Z` and `2026-10-05 10:00:00 +02:00` are re-emitted
+ * unchanged rather than normalized to an instant.
+ */
+class WrittenTimestamp {
+    text;
+    constructor(
+    /** The scalar's text, as written. */
+    text) {
+        this.text = text;
+    }
+    /** The text as written, so `JSON.stringify` of a context renders the timestamp as the document did. */
+    toJSON() {
+        return this.text;
+    }
+}
+exports.WrittenTimestamp = WrittenTimestamp;
+// js-yaml 4 exports its built-in types as `types`; `@types/js-yaml` does not declare that export.
+const types = jsYaml.types;
+/** js-yaml's timestamp tag and resolution, constructing a {@link WrittenTimestamp} instead of a `Date`. */
+const WRITTEN_TIMESTAMP_TYPE = new js_yaml_1.Type('tag:yaml.org,2002:timestamp', {
+    kind: 'scalar',
+    resolve: (data) => types.timestamp.resolve(data),
+    construct: (data) => new WrittenTimestamp(data),
+    instanceOf: WrittenTimestamp,
+    represent: (value) => value.text,
+});
+/**
+ * The schema the payload's frontmatter is read and dumped with: js-yaml's default schema (same implicit
+ * and explicit types, so it accepts what the scan accepted) with {@link WRITTEN_TIMESTAMP_TYPE} in place
+ * of the timestamp type. A timestamp is written back as written; a quoted date is a string that a reader
+ * could take for a timestamp, so the dump keeps it quoted.
+ */
+const PAYLOAD_YAML_SCHEMA = js_yaml_1.CORE_SCHEMA.extend({
+    implicit: [WRITTEN_TIMESTAMP_TYPE, types.merge],
+    explicit: [types.binary, types.omap, types.pairs, types.set],
+});
+/** `value` with every `Date` — a value a caller built itself, never one the builder read — as its
+ * ISO-8601 UTC text, at any depth, so {@link serializeExecutionContext} accepts it. */
+function withDatesAsWritten(value) {
+    if (value instanceof WrittenTimestamp)
+        return value;
+    if (value instanceof Date)
+        return new WrittenTimestamp(value.toISOString());
+    if (Array.isArray(value))
+        return value.map(withDatesAsWritten);
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, withDatesAsWritten(entry)]));
+    return value;
+}
+/**
+ * The frontmatter of each document at `paths`, as commit `sha` holds it, read with
+ * {@link PAYLOAD_YAML_SCHEMA} so its timestamps keep their text (`bug-232`). Every path was read and
+ * parsed at `sha` by the scan already, with a schema that accepts the same documents, and each one
+ * has a frontmatter block: the element is found, and a document carried, by its frontmatter's `type`
+ * and `id`.
+ */
+function writtenFrontmatter(root, sha, paths) {
+    return (0, storage_1.readPathsAtRev)(root, sha, [...paths]).map((raw) => (0, js_yaml_1.load)((0, storage_1.splitFrontmatter)(raw).frontmatter, { schema: PAYLOAD_YAML_SCHEMA }));
+}
+/** YAML for the payload: keys sorted ascending (§7), no line folding and no anchors, dates as written
+ * (`bug-232`), so the text is a function of the value alone. */
+function canonicalYaml(value) {
+    return (0, js_yaml_1.dump)(withDatesAsWritten(value), { schema: PAYLOAD_YAML_SCHEMA, sortKeys: true, lineWidth: -1, noRefs: true });
+}
+function yamlBlock(value) {
+    return '```yaml\n' + canonicalYaml(value) + '```';
+}
+/** A body as §7 carries it: verbatim, without the blank lines before it or the whitespace after it. */
+function trimBody(body) {
+    return body.replace(/^(?:[ \t]*\r?\n)+/, '').trimEnd();
+}
+/** The line that closes the body keyed `key` (`dl-150` B). */
+function endMarker(key) {
+    return `<!-- end:${key} -->`;
+}
+/**
+ * A body between its markers: `<!-- begin:<key> -->`, the trimmed body, `<!-- end:<key> -->`, each on
+ * its own line; an empty body leaves the two markers adjacent.
+ */
+function markedBody(key, body) {
+    const trimmed = trimBody(body);
+    return [`<!-- begin:${key} -->`, ...(trimmed.length > 0 ? [trimmed] : []), endMarker(key)].join('\n');
+}
+/**
+ * Whether `body`, once canonicalized (§7), holds the line that closes it — the one body a reader could
+ * not split by `dl-150` B's rule, so it never enters a payload.
+ */
+function closesItself(key, body) {
+    const marker = endMarker(key);
+    return canonicalize(body).split('\n').includes(marker);
+}
+function selfClosingProblem(what, key) {
+    return `${what} cannot enter an execution context: its body holds the line ${JSON.stringify(endMarker(key))} that closes it`;
+}
+/** The marker key of a directive body. */
+function directiveKey(id) {
+    return `directive:${id}`;
+}
+/** Whether a Memory document can be named in the payload: a string `type` and `id`, each fit for a
+ * heading and a marker (no control character, no `-->`). */
+function isNameable(type, id) {
+    return (typeof type === 'string' &&
+        typeof id === 'string' &&
+        type.length > 0 &&
+        id.length > 0 &&
+        headerFieldProblem('type', type) === undefined &&
+        headerFieldProblem('id', id) === undefined);
+}
+/** §7's canonicalization: LF only, no trailing whitespace on any line, exactly one trailing `\n`. */
+function canonicalize(text) {
+    return (text
+        .replace(/\r\n?/g, '\n')
+        .replace(/[ \t]+$/gm, '')
+        .replace(/\n+$/, '') + '\n');
+}
+/**
+ * Why `value` cannot sit in the payload's header comment, or `undefined` when it can. The header is one
+ * line inside `<!-- … -->`: a line break would split it, and `-->` would close the comment early and
+ * let the rest of the value pass for payload content. Control characters are refused with them.
+ */
+function headerFieldProblem(name, value) {
+    // eslint-disable-next-line no-control-regex
+    if (/[\u0000-\u001f\u007f]/.test(value) || value.includes('-->')) {
+        return `invalid ${name} ${JSON.stringify(value)}: it may hold no control character and no '-->'`;
+    }
+    return undefined;
+}
+/** The first body in `context` that {@link closesItself}, as its refusal; `undefined` when none does.
+ * The element first, then directives in payload order. */
+function selfClosingBody(context) {
+    const { element } = context;
+    const elementKey = `${element.type}:${element.id}`;
+    if (closesItself(elementKey, element.body))
+        return selfClosingProblem(`element '${elementKey}'`, elementKey);
+    for (const directive of context.directives) {
+        const key = directiveKey(directive.frontmatter.id);
+        if (closesItself(key, directive.body))
+            return selfClosingProblem(`directive '${directive.frontmatter.id}'`, key);
+    }
+    return undefined;
+}
+/**
+ * Render a context as `spec-012` §7's canonical Markdown payload, format {@link CONTEXT_PAYLOAD_FORMAT}
+ * (`dl-150` option B) — the bytes §8 holds identical across builds. Fixed headings in a fixed order,
+ * one blank line between blocks; frontmatter and DNA sections as fenced YAML with sorted keys; every
+ * directive and document body verbatim between `<!-- begin:<key> -->`/`<!-- end:<key> -->` markers
+ * (`<type>:<id>` for the element and Memory, `directive:<id>` for a directive), so a body's own
+ * headings never pass for §7's; ids rather than paths; the header names only the format, role, element
+ * and the resolved sha. `warnings` are not rendered.
+ *
+ * @throws Error `invalid execution context: missing '<section>' section` when `context` does not
+ *   validate ({@link validateExecutionContext}): a partial payload is never rendered. Error `invalid
+ *   role …` (or `element type`/`element id`/`directive id`) when a header field or a directive id holds
+ *   a control character or `-->`; `invalid Memory document <path>: …` for a document it cannot name;
+ *   `… cannot enter an execution context: its body holds the line … that closes it` for a body that
+ *   holds its own end marker.
+ */
+function serializeExecutionContext(context) {
+    const valid = validateExecutionContext(context);
+    if (!valid.ok)
+        throw new Error(valid.error.message);
+    const unsafe = headerFieldProblem('role', context.role) ??
+        headerFieldProblem('element type', context.element.type) ??
+        headerFieldProblem('element id', context.element.id) ??
+        context.directives.map((directive) => headerFieldProblem('directive id', directive.frontmatter.id)).find((problem) => problem !== undefined) ??
+        selfClosingBody(context);
+    if (unsafe !== undefined)
+        throw new Error(unsafe);
+    const { role, stateRef, element, dna, directives, memory } = context;
+    // The header comment sits on the title's next line, as §7's template shows.
+    const blocks = [
+        `# WingFoil Agent Context\n<!-- format: ${exports.CONTEXT_PAYLOAD_FORMAT} | role: ${role} | element: ${element.type}:${element.id} | state: ${stateRef} -->`,
+    ];
+    blocks.push('## 1. Task', yamlBlock(element.frontmatter), markedBody(`${element.type}:${element.id}`, element.body));
+    blocks.push('## 2. Project DNA');
+    for (const [name, value] of Object.entries(dna))
+        blocks.push(`### ${name}`, yamlBlock(value));
+    blocks.push(`## 3. Directives (${role} + global)`);
+    for (const directive of directives) {
+        blocks.push(`### ${directive.frontmatter.id}`, markedBody(directiveKey(directive.frontmatter.id), directive.body));
+    }
+    blocks.push(`## 4. Relevant Memory (${memory.length} documents)`);
+    for (const doc of memory) {
+        if (!isNameable(doc.type, doc.id)) {
+            throw new Error(`invalid Memory document ${doc.path}: an execution context names a document by a type and an id that hold no control character and no '-->'`);
+        }
+        const key = `${doc.type}:${doc.id}`;
+        if (closesItself(key, doc.body))
+            throw new Error(selfClosingProblem(`Memory document '${key}'`, key));
+        blocks.push(`### ${key}`, yamlBlock(doc.frontmatter), markedBody(key, doc.body));
+    }
+    return canonicalize(blocks.join('\n\n'));
+}
+function asNames(value) {
+    const entries = typeof value === 'string' ? [value] : Array.isArray(value) ? value : [];
+    return entries.filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+}
+/** A path with `\` read as `/` and no trailing `/`, so `src/core/` and `src/core` compare equal. */
+function normalizePath(path) {
+    return path.replace(/\\/g, '/').replace(/\/+$/, '');
+}
+/** Leading characters an entry's token never starts with: quotes and backticks. */
+const TOKEN_LEAD = /^[`'"]+/;
+/** Trailing characters an entry's token never ends with: list and sentence punctuation, quotes and
+ * backticks (`bug-233`). */
+const TOKEN_TRAIL = /[`'".,;:!?]+$/;
+/**
+ * The tokens one `modules:`/`scope:` value names (`spec-012` §4, `bug-233`): parenthesised text is
+ * set aside, the rest is split on commas into entries, and each entry is read by its leading token
+ * with surrounding quotes, backticks and trailing punctuation stripped — `src/mcp/server.ts, src/cli
+ * (the \`wingfoil mcp\` command)` names `src/mcp/server.ts` and `src/cli`.
+ */
+function entryTokens(entry) {
+    let text = entry;
+    for (let previous = ''; previous !== text;) {
+        previous = text;
+        text = text.replace(/\([^()]*\)/g, ' ');
+    }
+    return text
+        .split(',')
+        .map((part) => part.trim().split(/\s+/)[0].replace(TOKEN_LEAD, '').replace(TOKEN_TRAIL, ''))
+        .filter((token) => token.length > 0);
+}
+/** Whether `inner` equals `outer` or lies under it at a segment boundary. */
+function isAtOrUnder(inner, outer) {
+    return outer.length > 0 && (inner === outer || inner.startsWith(`${outer}/`));
+}
+/**
+ * Whether one token of a `modules:`/`scope:` entry selects `module` (`spec-012` §4, approver ruling D3
+ * and `bug-233`): it equals the module's `name`, or — as a path, compared at segment boundaries — the
+ * module's `path` equals it, lies under it (`src` selects `src/core`), or holds it (`src/mcp/server.ts`
+ * selects `src/mcp`). `src/co` selects nothing.
+ */
+function tokenSelectsModule(token, module) {
+    if (token === module.name)
+        return true;
+    if (module.path === undefined)
+        return false;
+    const named = normalizePath(token);
+    const path = normalizePath(module.path);
+    return isAtOrUnder(path, named) || isAtOrUnder(named, path);
+}
+/** The note recorded when the element names modules and none of them matches (ruling D3). */
+function noModuleMatchNote(entries) {
+    return `no module matches the element's modules:/scope: (${entries.map((entry) => JSON.stringify(entry)).join(', ')}); all modules included`;
+}
+/** The top-level keys of a `dna.yaml` text that has already validated, in the order the file
+ * declares them. */
+function declaredKeyOrder(raw, label) {
+    return Object.keys((0, validation_1.parseYaml)(raw, label));
+}
+/**
+ * `spec-012` §4, the `dna-loader`: `project`, `stacks` (`dl-151` A) and `team` always, `paths` whole
+ * (every category), and the `modules` the tokens of the element's `modules:`/`scope:` entries select
+ * ({@link entryTokens}, {@link tokenSelectsModule}), in
+ * `dna.yaml` order. Every module when it names none — and also when it names some and none matches,
+ * which then returns a note (ruling D3) for the caller's diagnostics. Sections are inserted in
+ * `declaredOrder`, the file's own key order.
+ */
+function selectDnaSections(dna, declaredOrder, frontmatter) {
+    const entries = [...asNames(frontmatter.modules), ...asNames(frontmatter.scope)];
+    const tokens = entries.flatMap(entryTokens);
+    const matched = dna.modules.filter((module) => tokens.some((token) => tokenSelectsModule(token, module)));
+    const unmatched = entries.length > 0 && matched.length === 0;
+    const sections = {
+        project: dna.project,
+        modules: matched.length === 0 ? dna.modules : matched,
+        stacks: dna.stacks,
+        team: dna.team,
+        paths: dna.paths,
+    };
+    const selection = {};
+    for (const key of declaredOrder)
+        if (sections[key] !== undefined)
+            selection[key] = sections[key];
+    return unmatched
+        ? { selection: selection, note: noModuleMatchNote(entries) }
+        : { selection: selection };
+}
+/** The Markdown body of each resolved directive, read at `sha` (`DirectiveFile.path` is relative to
+ * `.wingfoil/`). */
+function withBodies(root, sha, directives) {
+    return directives.map((directive) => {
+        const raw = (0, storage_1.readPathAtRev)(root, sha, `.wingfoil/${directive.path.split(/[\\/]/).join('/')}`) ?? '';
+        return { ...directive, body: (0, storage_1.splitFrontmatter)(raw).body };
+    });
+}
+function stringField(frontmatter, key) {
+    const value = frontmatter[key];
+    return typeof value === 'string' ? value : undefined;
+}
+/** The pillar file whose absence at `stateRef` leaves each section unset, keyed by the refusal. */
+const ABSENT_PILLAR_FILE = {
+    [missingSection('element')]: loaders_1.MEMORY_YAML_PATH,
+    [missingSection('dna')]: loaders_1.DNA_YAML_PATH,
+    [missingSection('directives')]: loaders_1.ROLES_YAML_PATH,
+};
+function isPositiveInteger(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * A request the builder refuses before reading anything (`VALIDATION`): a role or element field that
+ * cannot sit in the payload header (`headerFieldProblem`), or limits that are not positive integers —
+ * `NaN`, a fraction, zero or a negative number would make §6's bounding meaningless.
+ */
+function requestProblem(request) {
+    const header = headerFieldProblem('role', request.role) ??
+        headerFieldProblem('element type', request.element.type) ??
+        headerFieldProblem('element id', request.element.id);
+    if (header !== undefined)
+        return { code: 'VALIDATION', message: header };
+    const { limits } = request;
+    if (limits !== undefined && !(isPositiveInteger(limits.maxDocs) && isPositiveInteger(limits.maxBytes))) {
+        return {
+            code: 'VALIDATION',
+            message: `invalid context limits: maxDocs and maxBytes must be positive integers (got ${String(limits.maxDocs)}, ${String(limits.maxBytes)})`,
+        };
+    }
+    return undefined;
+}
+/** Ranks with no bound: used only to learn which unnameable documents would have been relevant. */
+const UNBOUNDED = { maxDocs: Number.MAX_SAFE_INTEGER, maxBytes: Number.MAX_SAFE_INTEGER };
+/**
+ * The Memory documents §7 can carry (`dl-150` B), before §6 ranks them: a document needs a nameable
+ * `type` and `id` ({@link isNameable}) for its heading and markers, and a body that does not hold its
+ * own end marker ({@link closesItself}). An unnameable document is reported only when §6 would have
+ * found it relevant — a repository's frontmatter-less files (grandfathered plans) would otherwise be
+ * reported in every context; a self-closing one is always reported. Neither takes a slot in the
+ * bounds, so the documents carried are what §6 selects among the rest.
+ */
+function payloadCandidates(documents, element) {
+    const carried = [];
+    const unnamed = [];
+    const left = [];
+    for (const doc of documents) {
+        const { type, id } = doc.frontmatter;
+        if (!isNameable(type, id)) {
+            unnamed.push(doc);
+            continue;
+        }
+        const key = `${type}:${id}`;
+        if (closesItself(key, doc.body)) {
+            const reason = `its body holds the line ${JSON.stringify(endMarker(key))} that closes it in an execution context`;
+            left.push({ path: doc.path, diagnostic: (0, memory_1.memoryUnreadableDiagnostic)(doc.path, reason) });
+        }
+        else
+            carried.push(doc);
+    }
+    for (const doc of (0, relevance_1.selectRelevantMemoryDocuments)(unnamed, element, UNBOUNDED).documents) {
+        const reason = 'no string type and id, so an execution context cannot name it';
+        left.push({ path: doc.path, diagnostic: (0, memory_1.memoryUnreadableDiagnostic)(doc.path, reason) });
+    }
+    // A path is reported at most once, so no two compare equal.
+    left.sort((a, b) => (a.path < b.path ? -1 : 1));
+    return { carried, left: left.map((entry) => entry.diagnostic) };
+}
+/**
+ * The refusal of a subject that commit `sha` holds in a `format:` newer than this build reads (task-195,
+ * `bug-263`), or `undefined`. The tolerant scan leaves such a document out as `W_MEMORY_UNREADABLE`, so
+ * the subject looks absent; the lookup by (`type`, `id`) refuses exactly that case with the `dl-149`
+ * `ValidationError` (`E_INVALID_FORMAT`), which becomes `VALIDATION` here, as every verb that names the
+ * element refuses it. Called only when the scan did not find the subject, so a context that builds pays
+ * nothing for it.
+ */
+function newerFormatSubject(root, sha, memoryYaml, wanted, label) {
+    try {
+        (0, memory_1.findMemoryDocumentByTypeAndIdAtRev)(root, sha, memoryYaml, wanted.type, wanted.id, { includeArchived: true });
+    }
+    catch (error) {
+        if (!(0, validation_1.isNewerFormatError)(error))
+            throw error;
+        return {
+            code: 'VALIDATION',
+            message: `element '${label}' at ${sha} is written in a newer format: ${error.message}`,
+            details: { issues: error.issues },
+        };
+    }
+    return undefined;
+}
+/**
+ * Build the execution context for `request` — `spec-012`'s single public entry (§1), the context
+ * `agent execute` (task-218) and the `{role}-session` Prompt (task-195) hand an agent.
+ *
+ * The §3 pipeline, every read at the one commit `request.stateRef` resolves to:
  *
- * `memory` resolves `element` via `findMemoryDocumentByTypeAndId`
- * (`task-011-mcp-resources-read-only`). Two properties of that primitive are inherited here and are
- * worth stating plainly:
+ * 1. **resolve-element**: every Memory document at that commit is read once
+ *    (`loadMemoryDocumentsAtRev`); the element is found in that snapshot. Absent → `NOT_FOUND`;
+ *    archived (`isArchivedStatus`) → `VALIDATION`, since an archived document never enters a context
+ *    (REQ-STATE-06). A `draft` element assembles.
+ * 2. **load-dna** (§4): see `selectDnaSections`; modules match by name or path (ruling D3, `bug-233`).
+ * 3. **load-directives** (§5): {@link resolveRoleDirectives} over the directives and `roles.yaml` at the
+ *    commit; its warnings become `context.warnings`.
+ * 4. **filter-memory** (§6): `selectRelevantMemoryDocuments` over the same snapshot, within
+ *    `request.limits`, among the documents §7 can carry (`dl-150` B, `payloadCandidates`): one with
+ *    no nameable `type` and `id` is left out, and reported only when it would have been relevant; one
+ *    whose body holds its own end marker is left out and reported. Both reports are
+ *    `W_MEMORY_UNREADABLE` lines on the success warnings, after the scan's own, in path order.
+ * 5. **validate** (P5.4.4 sc. 3) and **serialize** (§7).
  *
- * - It is **not** a single addressed read. It walks the Memory document paths derived from
- *   `memoryYaml` in sorted order and YAML-parses each document's frontmatter until one matches
- *   `element.type`/`element.id`, so cost grows with the size of the Memory tree (bounding that is
- *   `task-035-bounded-context-relevance`'s REQ-PERF-05 scope, not this task's).
- * - It therefore **can throw**. An `element` that matches nothing yields an empty `memory` array
- *   rather than an error — an unresolvable element is the caller's concern to surface — but a
- *   `ValidationError` (`E_YAML_PARSE_ERROR`) propagates out of assembly if any document visited
- *   during that walk has unparseable frontmatter. This function adds no `try`/`catch` of its own.
+ * A pillar file the commit does not hold leaves its section unset, and step 5 refuses the context:
+ * no `roles.yaml` → `missing 'directives'`, no `dna.yaml` → `missing 'dna'`, no `memory.yaml` →
+ * `missing 'element'`; the refusal's `details.cause` names the file (`no .wingfoil/roles.yaml at <sha>`).
+ * Before any read, a role or element field holding a control character or `-->`, or limits that are
+ * not positive integers, are refused as `VALIDATION`. After the reads, an element or directive body
+ * that holds its own end marker, or a directive id holding a control character or `-->`, refuses the
+ * context as `VALIDATION`: neither may be dropped (§5 never truncates a directive).
  *
- * `memory` **is** filtered by document status, in one direction only: a resolved element whose
- * `status` is archived — `{deprecated, superseded}`, per the shared {@link isArchivedStatus}
- * (`../memory`, the set ratified by `dl-028-archived-states-excluded-from-context`) — is dropped,
- * leaving `memory` empty. That is REQ-STATE-06's Fit Criterion as amended: "a `deprecated` or
- * `superseded` document never appears in an assembled agent context". The filter is applied to the
- * lookup's *result* rather than pushed into `findMemoryDocumentByTypeAndId`, because that same
- * primitive also serves `wingfoil://memory/{type}/{id}`, where explicit retrieval of archived content
- * must keep working.
+ * A subject the commit holds in a `format:` newer than this build reads is refused as `VALIDATION` with
+ * the `dl-149` `E_INVALID_FORMAT` text (task-195, `bug-263`), not reported as absent.
  *
- * `draft` is deliberately **not** excluded here, unlike in `./relevance.ts`. That module filters
- * *candidate* documents for relevance (spec-012 §6, which does bar `draft` from a context); this
- * function resolves the **subject** element the context is being assembled for (spec-012 §3's
- * `resolve-element` stage), and blanking the context for a task still in `draft` would defeat the
- * point of assembling it. dl-028 ratified the archived set as `{deprecated, superseded}` and did not
- * put `draft` in it.
+ * A Memory document that does not parse is left out and reported (task-171): as a `W_MEMORY_UNREADABLE`
+ * line in the result's `warnings` on success, and in `details.unreadable` of a `NOT_FOUND` refusal, so
+ * a subject that does not parse is not reported as merely absent. Neither reaches the payload.
  *
- * An archived element produces no warning: {@link ExecutionContext.warnings} carries
- * directive-resolution diagnostics only (dl-029, dl-037, dl-042), and adding an unratified entry would change a payload
- * REQ-SYS-07 governs. An archived element is therefore indistinguishable here from an unresolvable
- * one — both yield `memory: []`.
- */
-function assembleExecutionContext(inputs) {
-    const { directives, warnings } = resolveRoleDirectives(inputs.directiveFiles, inputs.rolesYaml, inputs.role);
-    const doc = (0, memory_1.findMemoryDocumentByTypeAndId)(inputs.root, inputs.memoryYaml, inputs.element.type, inputs.element.id);
-    // `frontmatter` is untyped (`Record<string, unknown>`), so project `status` to the
-    // `string | undefined` shape `isArchivedStatus` takes — a non-string `status` is never archived,
-    // exactly as that predicate's contract states.
-    const status = typeof doc?.frontmatter.status === 'string' ? doc.frontmatter.status : undefined;
-    const memory = doc !== undefined && !(0, memory_1.isArchivedStatus)(status) ? [doc] : [];
-    return { dna: inputs.dna, directives, memory, warnings };
+ * Expected failures are returned, never thrown: a `stateRef` that is malformed or names no commit is
+ * the `RevisionError`'s own `CoreError`. A pillar file (`dna.yaml`, `roles.yaml`, a directive) that
+ * does not parse still throws `ValidationError`, as its loader does.
+ */
+function assembleExecutionContext(root, request) {
+    const refused = requestProblem(request);
+    if (refused !== undefined)
+        return (0, types_1.coreErr)(refused);
+    let sha;
+    try {
+        sha = (0, revision_1.resolveRevision)(root, request.stateRef);
+    }
+    catch (error) {
+        if (error instanceof revision_1.RevisionError)
+            return (0, types_1.coreErr)(error.toCoreError());
+        throw error;
+    }
+    const { role, element: wanted } = request;
+    const label = `${wanted.type}:${wanted.id}`;
+    // The scan is tolerant (task-171, `bug-031`): a document it cannot read is left out and reported as
+    // `W_MEMORY_UNREADABLE`, so one malformed sibling no longer fails every context. It reads archived
+    // documents too — the archived subject is refused below, and §6 drops archived candidates itself.
+    const diagnostics = [];
+    const memoryYaml = (0, loaders_1.loadMemoryYamlAtRev)(root, sha);
+    const documents = memoryYaml === null
+        ? null
+        : (0, memory_1.loadMemoryDocumentsAtRev)(root, sha, memoryYaml, { onDiagnostic: (diagnostic) => diagnostics.push(diagnostic) });
+    const unreadable = diagnostics.map(validation_1.formatDiagnostic);
+    const found = documents?.find((doc) => stringField(doc.frontmatter, 'type') === wanted.type && stringField(doc.frontmatter, 'id') === wanted.id);
+    if (documents !== null && found === undefined) {
+        // A subject written in a newer format exists: it is refused for its format (`bug-263`).
+        const newer = newerFormatSubject(root, sha, memoryYaml, wanted, label);
+        if (newer !== undefined)
+            return (0, types_1.coreErr)(newer);
+        // A subject whose own frontmatter does not parse is among the unreadable files: name them, so the
+        // refusal does not read as a bare "not found".
+        return (0, types_1.coreErr)({
+            code: 'NOT_FOUND',
+            message: `element '${label}' not found at ${sha}`,
+            ...(unreadable.length > 0 ? { details: { unreadable } } : {}),
+        });
+    }
+    const status = found === undefined ? undefined : stringField(found.frontmatter, 'status');
+    if ((0, memory_1.isArchivedStatus)(status)) {
+        return (0, types_1.coreErr)({
+            code: 'VALIDATION',
+            message: `element '${label}' is ${status}: an archived element never enters an execution context`,
+        });
+    }
+    const element = found === undefined ? undefined : { ...found, type: wanted.type, id: wanted.id };
+    const frontmatter = element?.frontmatter ?? {};
+    // `loadDnaYamlAtRev` validates; the raw text gives the declared section order, which the
+    // Zod-parsed object loses (schema keys come first there). `loadDnaYamlAtRev` is non-null whenever
+    // the raw read is: both read the same path at the same sha.
+    const dnaRaw = (0, storage_1.readPathAtRev)(root, sha, loaders_1.DNA_YAML_PATH);
+    const dnaSelected = dnaRaw === null
+        ? undefined
+        : selectDnaSections((0, loaders_1.loadDnaYamlAtRev)(root, sha), declaredKeyOrder(dnaRaw, `${sha}:${loaders_1.DNA_YAML_PATH}`), frontmatter);
+    const dna = dnaSelected?.selection;
+    const rolesYaml = (0, loaders_1.loadRolesYamlAtRev)(root, sha);
+    const resolution = rolesYaml === null ? undefined : resolveRoleDirectives((0, loaders_1.loadDirectivesAtRev)(root, sha), rolesYaml, role);
+    const directives = resolution === undefined ? undefined : withBodies(root, sha, resolution.directives);
+    const candidates = documents === null ? undefined : payloadCandidates(documents, { ...wanted, frontmatter });
+    const relevant = candidates === undefined
+        ? undefined
+        : (0, relevance_1.selectRelevantMemoryDocuments)(candidates.carried, { ...wanted, frontmatter }, request.limits ?? relevance_1.DEFAULT_CONTEXT_LIMITS);
+    // The payload carries the frontmatter as written (`bug-232`): the element and the selected documents
+    // are re-read at the commit with the payload's schema. Selection above used the scan's parse.
+    const carried = [...(element === undefined ? [] : [element]), ...(relevant?.documents ?? [])];
+    const written = writtenFrontmatter(root, sha, carried.map((doc) => doc.path));
+    const offset = carried.length - (relevant?.documents.length ?? 0);
+    const validated = validateExecutionContext({
+        role,
+        stateRef: sha,
+        element: element === undefined ? undefined : { ...element, frontmatter: written[0] },
+        dna,
+        directives,
+        memory: relevant?.documents.map((doc, index) => ({ ...doc, frontmatter: written[offset + index] })),
+        warnings: resolution?.warnings ?? [],
+    });
+    if (!validated.ok) {
+        // Every section the builder can leave unset is unset by an absent pillar file (an absent
+        // `memory.yaml` unsets `element` before `memory`), so the refusal always names one. The message
+        // stays P5.4.4's, verbatim.
+        const cause = `no ${ABSENT_PILLAR_FILE[validated.error.message]} at ${sha}`;
+        return (0, types_1.coreErr)({ ...validated.error, details: { cause } });
+    }
+    const context = validated.value;
+    const unfit = context.directives.map((directive) => headerFieldProblem('directive id', directive.frontmatter.id)).find((problem) => problem !== undefined) ??
+        selfClosingBody(context);
+    if (unfit !== undefined)
+        return (0, types_1.coreErr)({ code: 'VALIDATION', message: unfit });
+    // In §3 stage order: the DNA note (ruling D3), then the relevance note (P5.3.3 sc. 3).
+    const notes = [dnaSelected?.note, relevant?.note].filter((note) => note !== undefined);
+    // Unreadable files are about the repository, not the context: they ride the success-warning channel
+    // (task-169), as `memory search` carries them (task-171), and never enter the payload.
+    // `candidates` is set whenever `memory.yaml` is, and without it the context was refused above.
+    const warnings = [...unreadable, ...candidates.left.map(validation_1.formatDiagnostic)];
+    return (0, types_1.coreOk)({ context, payload: serializeExecutionContext(context), notes }, undefined, warnings);
 }
 //# sourceMappingURL=context.js.map