wingfoil 0.2.1 → 0.3.0

package/dist/core/relevance.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NO_RELEVANT_MEMORY_NOTE = exports.DEFAULT_CONTEXT_LIMITS = void 0;
 exports.filterRelevantMemoryDocuments = filterRelevantMemoryDocuments;
+exports.selectRelevantMemoryDocuments = selectRelevantMemoryDocuments;
 /**
  * `relevance-filter` (task-035-bounded-context-relevance, REQ-PERF-05) —
  * spec-012-context-loader-relevance-filtering §6's deterministic Memory-document selection unit:
@@ -12,8 +13,8 @@ exports.filterRelevantMemoryDocuments = filterRelevantMemoryDocuments;
  *
  * This module implements ONLY spec-012 §6 (`relevance-filter`), one of the four cooperating units
  * spec-012 defines (`dna-loader`, `directive-loader`, `relevance-filter`, `context-builder`) — the
- * other three, and the canonical serialized envelope (§7), belong to
- * task-037-role-task-scoped-context (REQ-STATE-05, the `context-builder`/envelope task). For the
+ * other three, and the canonical serialized envelope (§7), live in `./context.ts`
+ * (`assembleExecutionContext`, task-176), which calls this unit at its `stateRef`. For the
  * document scan itself it wraps, not reimplements, `src/memory/query.ts`'s scan primitives
  * (task-008) — no second directory walk or frontmatter parser — and is placed in `src/core` per
  * spec-012 §1 ("folded into the `core` module"). It is re-exported from `src/core`'s barrel, so
@@ -30,12 +31,13 @@ exports.filterRelevantMemoryDocuments = filterRelevantMemoryDocuments;
  * `spec-001-memory-yaml-schema` removed from every type's machine.
  *
  * Determinism (REQ-SYS-07): no wall-clock, no randomness, no unordered map/set iteration in any
- * output-affecting path. This function READS the live working tree under `root` — it is not pinned to
- * a git revision, and `root`'s content is therefore part of its input, not a constant. What is
- * guaranteed is *referential transparency over that observed state*: for one unchanged working tree,
- * the selection and its order are a pure function of `(the Memory documents under root, memoryYaml,
- * element, limits)`, so repeated calls return the identical array. See
- * {@link filterRelevantMemoryDocuments}'s own doc comment for the exact ordering/bounding contract.
+ * output-affecting path. The ranking itself, {@link selectRelevantMemoryDocuments}, is a pure function
+ * of `(documents, element, limits)` and reads nothing. Where the documents come from is the caller's
+ * choice: the execution-context builder (`./context.ts`, task-176) feeds it the snapshot
+ * `loadMemoryDocumentsAtRev` reads at `spec-012` §2's `stateRef`, so a context is pinned to one commit;
+ * {@link filterRelevantMemoryDocuments} feeds it the live working tree under `root`, whose content is
+ * then part of its input. See {@link selectRelevantMemoryDocuments} for the exact ordering/bounding
+ * contract.
  */
 const query_1 = require("../memory/query");
 const state_machine_1 = require("../memory/state-machine");
@@ -176,40 +178,56 @@ function isSameReleaseScope(elementRelease, documentPath, documentFrontmatter) {
     return documentPath.includes(`/${elementRelease}/`) || asString(documentFrontmatter.release) === elementRelease;
 }
 /**
- * Rank and bound the Memory documents relevant to `element` (spec-012 §6, REQ-PERF-05). Deterministic
- * end to end (REQ-SYS-07):
+ * Rank and bound the Memory documents relevant to `element` (spec-012 §6, REQ-PERF-05), scanning the
+ * **working tree** under `root`: every document `memoryYaml` declares, in sorted path order
+ * (`loadMemoryDocuments`, task-008), handed to {@link selectRelevantMemoryDocuments}. An execution
+ * context does not use this reader: it ranks the snapshot read at its `stateRef` (`./context.ts`).
  *
- * 1. **Scan** every document `memoryYaml` declares under `root` ({@link listMemoryDocumentPaths}'s
- *    already-sorted order, task-008) — no second directory walk.
- * 2. **Exclude** the element's own document (never relevant to itself) and any document
+ * The read is tolerant like every other Memory scan (task-171; task-253, `bug-230`; `spec-017` §1.4):
+ * a document whose frontmatter does not parse, and a symbolic link, are left out of the ranking and
+ * reported in the result's `diagnostics` as `W_MEMORY_UNREADABLE`, so one malformed document never
+ * fails the filter for every element.
+ */
+function filterRelevantMemoryDocuments(root, memoryYaml, element, limits = exports.DEFAULT_CONTEXT_LIMITS) {
+    const diagnostics = [];
+    const documents = (0, query_1.loadMemoryDocuments)(root, memoryYaml, { onDiagnostic: (diagnostic) => diagnostics.push(diagnostic) });
+    return { ...selectRelevantMemoryDocuments(documents, element, limits), diagnostics };
+}
+/**
+ * Rank and bound `documents` by their relevance to `element` (spec-012 §6, REQ-PERF-05). A pure
+ * function of its arguments: it reads nothing, so the caller decides which state is ranked — the
+ * working tree ({@link filterRelevantMemoryDocuments}) or one commit (`./context.ts`, `stateRef`).
+ * Deterministic end to end (REQ-SYS-07):
+ *
+ * 1. **Exclude** the element's own document (never relevant to itself) and any document
  *    {@link isExcludedFromContext} bars — `draft` plus the shared archived set `{deprecated,
  *    superseded}` (`dl-028`; the archived half is the same predicate REQ-STATE-06 applies to default
  *    `memory search`, the `draft` half is context-only).
- * 3. **Score** each remaining document: `1000*T1 + 100*T2 + 10*T3 + overlapCount(T4)` — T1 explicit
+ * 2. **Score** each remaining document: `1000*T1 + 100*T2 + 10*T3 + overlapCount(T4)` — T1 explicit
  *    link, T2 same release scope, T3 shared traceability key, T4 keyword/tag overlap count
  *    (spec-012 §6's exact formula). A document scoring `0` (no tier hit at all) is **not relevant**
  *    and is dropped — this is the relevance threshold P5.3.3-relevance-filtering.feature's "Edge - no
  *    documents pass the relevance threshold" scenario exercises.
- * 4. **Order**: score DESC, then `type` ASC, then `id` ASC (falling back to `path` when a document has
- *    no `id`) — a total, deterministic tie-break (spec-012 §6/REQ-SYS-07).
- * 5. **Bound**: walk in that order, including documents until either `limits.maxDocs` or
+ * 3. **Order**: score DESC, then `type` ASC, then `id` ASC (falling back to `path` when a document has
+ *    no `id`) — a total, deterministic tie-break (spec-012 §6/REQ-SYS-07). The input order therefore
+ *    never reaches the output.
+ * 4. **Bound**: walk in that order, including documents until either `limits.maxDocs` or
  *    `limits.maxBytes` (summed UTF-8 body bytes) would be exceeded, then **stop** — never skip a
  *    lower-ranked document to fit under a cap while a higher-ranked one was excluded, and never
  *    partially include a document (spec-012 §6's "deterministic truncation").
  *
- * Returns {@link NO_RELEVANT_MEMORY_NOTE} in `note` only when **step 3 left nothing** — i.e. no
+ * Returns {@link NO_RELEVANT_MEMORY_NOTE} in `note` only when **step 2 left nothing** — i.e. no
  * document passed the relevance threshold at all (P5.3.3's edge-case scenario, verbatim wording).
- * When documents scored as relevant but step 5's caps admitted none of them, `documents` is empty and
+ * When documents scored as relevant but step 4's caps admitted none of them, `documents` is empty and
  * `note` is omitted: relevant Memory *was* found, so the note would assert something false.
  */
-function filterRelevantMemoryDocuments(root, memoryYaml, element, limits = exports.DEFAULT_CONTEXT_LIMITS) {
+function selectRelevantMemoryDocuments(documents, element, limits) {
     const linkedIds = collectLinkedIds(element.frontmatter);
     const elementRelease = asString(element.frontmatter.release);
     const elementTraceability = collectTraceabilityKeys(element.frontmatter);
     const elementKeywords = collectKeywords(element.frontmatter);
     const scored = [];
-    for (const path of (0, query_1.listMemoryDocumentPaths)(root, memoryYaml)) {
-        const { frontmatter, body } = (0, query_1.loadMemoryDocumentSummary)(root, path);
+    for (const { path, frontmatter, body } of documents) {
         const type = asString(frontmatter.type);
         const id = asString(frontmatter.id);
         const status = asString(frontmatter.status);
@@ -240,19 +258,19 @@ function filterRelevantMemoryDocuments(root, memoryYaml, element, limits = expor
         const idB = b.id ?? b.path;
         return idA < idB ? -1 : idA > idB ? 1 : 0;
     });
-    const documents = [];
+    const included = [];
     let totalBytes = 0;
     for (const doc of scored) {
-        if (documents.length >= limits.maxDocs)
+        if (included.length >= limits.maxDocs)
             break;
         const docBytes = Buffer.byteLength(doc.body, 'utf-8');
         if (totalBytes + docBytes > limits.maxBytes)
             break;
-        documents.push(doc);
+        included.push(doc);
         totalBytes += docBytes;
     }
-    // The note is keyed to `scored`, NOT to `documents`: an empty `documents` with a non-empty `scored`
+    // The note is keyed to `scored`, NOT to `included`: an empty `included` with a non-empty `scored`
     // means relevant Memory existed and was bounded out, which the note must not claim away.
-    return scored.length === 0 ? { documents, note: exports.NO_RELEVANT_MEMORY_NOTE } : { documents };
+    return scored.length === 0 ? { documents: included, note: exports.NO_RELEVANT_MEMORY_NOTE } : { documents: included };
 }
 //# sourceMappingURL=relevance.js.map

package/dist/core/relevance.js.map

@@ -1 +1 @@
-{"version":3,"file":"relevance.js","sourceRoot":"","sources":["../../src/core/relevance.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relevance.js","sourceRoot":"","sources":["../../src/core/relevance.ts"],"names":[],"mappings":"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"}

package/dist/core/require-reason.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"require-reason.d.ts","sourceRoot":"","sources":["../../src/core/require-reason.ts"],"names":[],"mappings":"AA2DA;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAM3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxG"}
+{"version":3,"file":"require-reason.d.ts","sourceRoot":"","sources":["../../src/core/require-reason.ts"],"names":[],"mappings":"AA4DA;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAM3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxG"}

package/dist/core/require-reason.js

@@ -42,8 +42,9 @@ const usage_error_1 = require("./usage-error");
 const MISSING_REASON_ERROR = 'missing required argument: --reason';
 /**
  * The given reason in its declared normal form, or a `UsageError` (exit 2) naming the defect that
- * makes it unrecordable — blank, carrying a reserved trailer line, or ending in one
- * (`reasonDefect`, `src/memory/commit-message.ts`).
+ * makes it unrecordable — blank, carrying a control character other than tab or newline, carrying a
+ * reserved trailer line, or ending in a paragraph shaped like one (`reasonRefusalMessage`,
+ * `src/memory/commit-message.ts`).
  *
  * The message is deliberately NOT {@link MISSING_REASON_ERROR}: that string answers the *omitted*
  * case, and `spec-008-cli-grammar` §2 plus the `P1.7`/`P1.8` BDD features quote it verbatim for that
@@ -51,9 +52,9 @@ const MISSING_REASON_ERROR = 'missing required argument: --reason';
  * (dl-067 S1).
  */
 function recordableReason(reason) {
-    const defect = (0, commit_message_1.reasonDefect)(reason);
-    if (defect !== null) {
-        throw new usage_error_1.UsageError((0, commit_message_1.reasonDefectMessage)(defect));
+    const refusal = (0, commit_message_1.reasonRefusalMessage)(reason);
+    if (refusal !== null) {
+        throw new usage_error_1.UsageError(refusal);
     }
     return (0, commit_message_1.normalizeReason)(reason);
 }

package/dist/core/require-reason.js.map

@@ -1 +1 @@
-{"version":3,"file":"require-reason.js","sourceRoot":"","sources":["../../src/core/require-reason.ts"],"names":[],"mappings":";;AAuEA,sCAMC;AAcD,wCAGC;AA9FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,6DAA8F;AAE9F,+CAA2C;AAE3C,qIAAqI;AACrI,MAAM,oBAAoB,GAAG,qCAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,MAAM,GAAG,IAAA,6BAAY,EAAC,MAAM,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,wBAAU,CAAC,IAAA,oCAAmB,EAAC,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAA,gCAAe,EAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAC,OAAqD;IACjF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,wBAAU,CAAC,oBAAoB,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,cAAc,CAAC,OAAqD;IAClF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACrE,CAAC"}
+{"version":3,"file":"require-reason.js","sourceRoot":"","sources":["../../src/core/require-reason.ts"],"names":[],"mappings":";;AAwEA,sCAMC;AAcD,wCAGC;AA/FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,6DAAiF;AAEjF,+CAA2C;AAE3C,qIAAqI;AACrI,MAAM,oBAAoB,GAAG,qCAAqC,CAAC;AAEnE;;;;;;;;;;GAUG;AACH,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,OAAO,GAAG,IAAA,qCAAoB,EAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,wBAAU,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAA,gCAAe,EAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAC,OAAqD;IACjF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,wBAAU,CAAC,oBAAoB,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,cAAc,CAAC,OAAqD;IAClF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACrE,CAAC"}

package/dist/core/required-fields.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The required-field check two verbs share (`spec-010` § Validation rules): `memory submit` before
+ * leaving the initial state, and `memory amend` on a document already past it (task-127 review F1).
+ * One function, so the two can never disagree about what "filled" means.
+ *
+ * A field is refused when it is missing — absent, `null`, blank, a mapping, or a list on a field the
+ * type does not declare in `template.frontmatter.lists` (`bug-147`, task-168 re-review rulings) — or
+ * when it holds a
+ * not-applicable value that may not stand (`dl-124`, task-168): the type does not list the field in
+ * `template.frontmatter.not_applicable_allowed`, or the value is not `"n/a — <reason>"`. A required
+ * field the type does not list — `task.kind` in this repository — therefore cannot be skipped by
+ * writing `n/a` in it.
+ *
+ * A field the type's `template.frontmatter.exempt` lists for this document's `id` is not required of
+ * it at all (`bug-342`, task-279): neither checked nor named in the refusal. The declaration in
+ * `memory.yaml` is the only source of the exemption — this repository's releases added before
+ * `dl-092` carry no `kind`; no id is written here.
+ */
+import { type MemoryYaml } from '../memory';
+import { type CoreResult } from './types';
+/**
+ * `VALIDATION` (exit 1) naming every refused field, or `ok`. A list is a value only on the fields the
+ * type declares in `template.frontmatter.lists`. The message is
+ * `missing required field on <verb>: a, b`, then — joined by `; ` when both apply —
+ * `not-applicable value on <verb>: <field> …`, each clause in declared field order.
+ */
+export declare function requireRequiredFields(memoryYaml: MemoryYaml, type: string, frontmatter: Readonly<Record<string, unknown>>, verb: 'submit' | 'amend'): CoreResult<undefined>;
+//# sourceMappingURL=required-fields.d.ts.map

package/dist/core/required-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fields.d.ts","sourceRoot":"","sources":["../../src/core/required-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAgD,KAAK,UAAU,EAA6B,MAAM,WAAW,CAAC;AAErH,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAa3D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,IAAI,EAAE,QAAQ,GAAG,OAAO,GACvB,UAAU,CAAC,SAAS,CAAC,CAiBvB"}

package/dist/core/required-fields.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireRequiredFields = requireRequiredFields;
+/**
+ * The required-field check two verbs share (`spec-010` § Validation rules): `memory submit` before
+ * leaving the initial state, and `memory amend` on a document already past it (task-127 review F1).
+ * One function, so the two can never disagree about what "filled" means.
+ *
+ * A field is refused when it is missing — absent, `null`, blank, a mapping, or a list on a field the
+ * type does not declare in `template.frontmatter.lists` (`bug-147`, task-168 re-review rulings) — or
+ * when it holds a
+ * not-applicable value that may not stand (`dl-124`, task-168): the type does not list the field in
+ * `template.frontmatter.not_applicable_allowed`, or the value is not `"n/a — <reason>"`. A required
+ * field the type does not list — `task.kind` in this repository — therefore cannot be skipped by
+ * writing `n/a` in it.
+ *
+ * A field the type's `template.frontmatter.exempt` lists for this document's `id` is not required of
+ * it at all (`bug-342`, task-279): neither checked nor named in the refusal. The declaration in
+ * `memory.yaml` is the only source of the exemption — this repository's releases added before
+ * `dl-092` carry no `kind`; no id is written here.
+ */
+const memory_1 = require("../memory");
+const types_1 = require("./types");
+function describeRefusal(type, refusal) {
+    switch (refusal.problem) {
+        case 'no-reason':
+            return `${refusal.field} needs a reason, written "n/a — <reason>"`;
+        case 'bad-form':
+            return `${refusal.field} must be written "n/a — <reason>", with an em dash before the reason`;
+        default:
+            return `${refusal.field} does not accept one (type '${type}' does not list it in template.frontmatter.not_applicable_allowed)`;
+    }
+}
+/**
+ * `VALIDATION` (exit 1) naming every refused field, or `ok`. A list is a value only on the fields the
+ * type declares in `template.frontmatter.lists`. The message is
+ * `missing required field on <verb>: a, b`, then — joined by `; ` when both apply —
+ * `not-applicable value on <verb>: <field> …`, each clause in declared field order.
+ */
+function requireRequiredFields(memoryYaml, type, frontmatter, verb) {
+    const template = memoryYaml.types[type]?.template?.frontmatter;
+    const id = frontmatter['id'];
+    const exempt = template?.exempt ?? {};
+    // Own properties only: a field named like an Object.prototype member (`constructor`, `toString`) is
+    // an ordinary required field, never the prototype's function (task-279 review F1).
+    const exemptIds = (field) => (Object.hasOwn(exempt, field) ? (exempt[field] ?? []) : []);
+    const required = (template?.required ?? []).filter((field) => !(typeof id === 'string' && exemptIds(field).includes(id)));
+    const missing = (0, memory_1.missingRequiredFields)(frontmatter, required, template?.lists ?? []);
+    const refused = (0, memory_1.notApplicableRefusals)(frontmatter, required, template?.not_applicable_allowed ?? []);
+    const clauses = [];
+    if (missing.length > 0)
+        clauses.push(`missing required field on ${verb}: ${missing.join(', ')}`);
+    if (refused.length > 0) {
+        clauses.push(`not-applicable value on ${verb}: ${refused.map((refusal) => describeRefusal(type, refusal)).join(', ')}`);
+    }
+    if (clauses.length === 0)
+        return (0, types_1.coreOk)(undefined);
+    return (0, types_1.coreErr)({ code: 'VALIDATION', message: clauses.join('; ') });
+}
+//# sourceMappingURL=required-fields.js.map

package/dist/core/required-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fields.js","sourceRoot":"","sources":["../../src/core/required-fields.ts"],"names":[],"mappings":";;AAuCA,sDAsBC;AA7DD;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAAqH;AAErH,mCAA2D;AAE3D,SAAS,eAAe,CAAC,IAAY,EAAE,OAA6B;IAClE,QAAQ,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,KAAK,WAAW;YACd,OAAO,GAAG,OAAO,CAAC,KAAK,2CAA2C,CAAC;QACrE,KAAK,UAAU;YACb,OAAO,GAAG,OAAO,CAAC,KAAK,sEAAsE,CAAC;QAChG;YACE,OAAO,GAAG,OAAO,CAAC,KAAK,+BAA+B,IAAI,oEAAoE,CAAC;IACnI,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CACnC,UAAsB,EACtB,IAAY,EACZ,WAA8C,EAC9C,IAAwB;IAExB,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC/D,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IACtC,oGAAoG;IACpG,mFAAmF;IACnF,MAAM,SAAS,GAAG,CAAC,KAAa,EAAqB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpH,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1H,MAAM,OAAO,GAAG,IAAA,8BAAqB,EAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACpF,MAAM,OAAO,GAAG,IAAA,8BAAqB,EAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,sBAAsB,IAAI,EAAE,CAAC,CAAC;IACrG,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,6BAA6B,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjG,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,2BAA2B,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1H,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAA,cAAM,EAAC,SAAS,CAAC,CAAC;IACnD,OAAO,IAAA,eAAO,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/core/revision.d.ts

@@ -0,0 +1,82 @@
+import { type BlobEntry } from '../storage';
+import type { CoreError, CoreErrorCode } from './types';
+/**
+ * A revision a `…AtRev` reader cannot read at. It is thrown, like the loaders' `ValidationError`, and
+ * it **is** a {@link CoreError} — `code`, `message`, `details: { rev }` — so a core function hands it
+ * on with `coreErr(error.toCoreError())`.
+ *
+ * - `VALIDATION`: the rev is malformed ({@link isWellFormedRevision}) and was never shown to git.
+ * - `NOT_FOUND`: the rev is well formed and names no commit — an unknown name, an unborn `HEAD`, a
+ *   tree or a blob.
+ *
+ * Both messages name the rev JSON-quoted, so an empty or whitespace rev is visible.
+ */
+export declare class RevisionError extends Error implements CoreError {
+    readonly code: CoreErrorCode;
+    readonly details: {
+        readonly rev: string;
+    };
+    constructor(code: 'VALIDATION' | 'NOT_FOUND', rev: string);
+    /** The plain {@link CoreError} value, for a `CoreResult` (spec-006 §2). */
+    toCoreError(): CoreError;
+}
+/**
+ * Whether `rev` has the shape a single-commit revision may have here. Refused: the empty string; a
+ * leading `-` (git would read it as an option); whitespace and control bytes (no ref name holds them,
+ * and a newline would split a batch request); `:` (that is `<rev>:<path>`, a blob, never a commit);
+ * `..` (a range, two commits). Everything else — `HEAD`, `HEAD~2`, a sha or its prefix, a branch, a tag,
+ * `main@{1}` — is left for git to resolve.
+ *
+ * The whitespace rule also refuses the revision forms that spell a phrase with spaces —
+ * `master@{1 day ago}`, `HEAD^{/fix bug}` — as `VALIDATION`. git's dotted spelling of an approxidate
+ * (`HEAD@{1.day.ago}`) has no space and resolves.
+ */
+export declare function isWellFormedRevision(rev: string): boolean;
+/**
+ * Resolve `rev` to the full sha of the commit it names (task-137).
+ *
+ * @param root - Project root (the git repository).
+ * @param rev - A revision naming one commit: `HEAD`, a sha, a branch, a tag.
+ * @returns The commit's full sha.
+ * @throws {@link RevisionError} `VALIDATION` for a malformed rev, `NOT_FOUND` for one naming no commit;
+ *   `StorageError` `E_GIT_READ_FAILED` when git cannot answer at all (a `root` that is not a
+ *   repository, a `git` that cannot run) — a broken environment is not a missing revision.
+ */
+export declare function resolveRevision(root: string, rev: string): string;
+/**
+ * Every file commit `sha` holds under `prefix` (`storage.listPathsAtRev`), for a sha
+ * {@link resolveRevision} has just resolved. `listPathsAtRev` answers `null` only for a revision that
+ * does not resolve, so a `null` here means git could not list a commit it had just resolved; that is a
+ * failed read, and it throws rather than passing for "the commit holds nothing" (the empty answer this
+ * module exists to keep away from an agent's context).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+export declare function listPathsAtCommit(root: string, sha: string, prefix: string): string[];
+/**
+ * {@link listPathsAtCommit} with each blob's kind (`storage.listBlobEntriesAtRev`): the Memory scan
+ * reads at a commit through this, so that a symbolic link is known as one rather than read as a
+ * document whose text is the link's target (task-171, `bug-189`).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+export declare function listBlobEntriesAtCommit(root: string, sha: string, prefix: string): BlobEntry[];
+/**
+ * Run a `…AtRev(root, 'HEAD')` read with the answer the `…AtHead` readers have always given when there
+ * is no `HEAD` to read — `fallback` (`null`, or `[]` for a directory) — rather than an error. Two
+ * conditions mean that, and only two (task-171, `bug-201`):
+ *
+ * - {@link RevisionError} `NOT_FOUND`: a repository with no commit yet (`HEAD` is a constant, so
+ *   `VALIDATION` cannot occur);
+ * - `StorageError` `E_GIT_READ_FAILED` when `root` holds no `.git`: it is not a repository, so nothing
+ *   is committed there.
+ *
+ * Their callers treat the fallback as "nothing committed" (task-090, task-091, task-096). Any other
+ * failure is thrown, and the caller refuses it by name: a `git` that cannot be spawned, an answer past
+ * the read buffer, a tree git cannot read. Until task-171 every `E_GIT_READ_FAILED` gave the fallback,
+ * so a failed read inside a repository passed for an empty baseline.
+ *
+ * @param root - The project root the read is against; asked only whether it holds `.git`.
+ */
+export declare function atHeadOr<T, F>(root: string, read: () => T, fallback: F): T | F;
+//# sourceMappingURL=revision.d.ts.map

package/dist/core/revision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.d.ts","sourceRoot":"","sources":["../../src/core/revision.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,SAAS,EAA6F,MAAM,YAAY,CAAC;AAEvI,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,KAAM,YAAW,SAAS;IAC3D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;gBAE/B,IAAI,EAAE,YAAY,GAAG,WAAW,EAAE,GAAG,EAAE,MAAM;IAazD,2EAA2E;IAC3E,WAAW,IAAI,SAAS;CAGzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAMrF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CAM9F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAQ9E"}

package/dist/core/revision.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RevisionError = void 0;
+exports.isWellFormedRevision = isWellFormedRevision;
+exports.resolveRevision = resolveRevision;
+exports.listPathsAtCommit = listPathsAtCommit;
+exports.listBlobEntriesAtCommit = listBlobEntriesAtCommit;
+exports.atHeadOr = atHeadOr;
+/**
+ * Resolving the revision a read is pinned to (task-137, `spec-012` §2 `stateRef`, `spec-016` §3.3
+ * step 7, `spec-017` §1.1).
+ *
+ * Every `…AtRev(root, rev)` reader — the pillar loaders (`./loaders.ts`) and the Memory scan
+ * (`../memory/query.ts`) — resolves its `rev` here, once, to the full sha of a commit, and reads every
+ * byte at that sha. A rev that resolves to nothing is a refusal, never an empty answer: an empty
+ * directive list or Memory scan is a legitimate answer for a commit that holds nothing, so handing it
+ * back for a mistyped rev would build an agent a wrong context that looks right.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const storage_1 = require("../storage");
+/**
+ * A revision a `…AtRev` reader cannot read at. It is thrown, like the loaders' `ValidationError`, and
+ * it **is** a {@link CoreError} — `code`, `message`, `details: { rev }` — so a core function hands it
+ * on with `coreErr(error.toCoreError())`.
+ *
+ * - `VALIDATION`: the rev is malformed ({@link isWellFormedRevision}) and was never shown to git.
+ * - `NOT_FOUND`: the rev is well formed and names no commit — an unknown name, an unborn `HEAD`, a
+ *   tree or a blob.
+ *
+ * Both messages name the rev JSON-quoted, so an empty or whitespace rev is visible.
+ */
+class RevisionError extends Error {
+    code;
+    details;
+    constructor(code, rev) {
+        super(code === 'VALIDATION'
+            ? `malformed revision ${JSON.stringify(rev)}: a revision is a non-empty name with no leading '-', no whitespace or control character, no ':' and no '..'`
+            : `revision ${JSON.stringify(rev)} does not name a commit`);
+        this.name = 'RevisionError';
+        this.code = code;
+        this.details = { rev };
+        // Restore the prototype chain so `instanceof RevisionError` holds after transpilation.
+        Object.setPrototypeOf(this, RevisionError.prototype);
+    }
+    /** The plain {@link CoreError} value, for a `CoreResult` (spec-006 §2). */
+    toCoreError() {
+        return { code: this.code, message: this.message, details: { rev: this.details.rev } };
+    }
+}
+exports.RevisionError = RevisionError;
+/**
+ * Whether `rev` has the shape a single-commit revision may have here. Refused: the empty string; a
+ * leading `-` (git would read it as an option); whitespace and control bytes (no ref name holds them,
+ * and a newline would split a batch request); `:` (that is `<rev>:<path>`, a blob, never a commit);
+ * `..` (a range, two commits). Everything else — `HEAD`, `HEAD~2`, a sha or its prefix, a branch, a tag,
+ * `main@{1}` — is left for git to resolve.
+ *
+ * The whitespace rule also refuses the revision forms that spell a phrase with spaces —
+ * `master@{1 day ago}`, `HEAD^{/fix bug}` — as `VALIDATION`. git's dotted spelling of an approxidate
+ * (`HEAD@{1.day.ago}`) has no space and resolves.
+ */
+function isWellFormedRevision(rev) {
+    // eslint-disable-next-line no-control-regex
+    return rev.length > 0 && !rev.startsWith('-') && !/[\s\u0000-\u001f\u007f:]/.test(rev) && !rev.includes('..');
+}
+/**
+ * Resolve `rev` to the full sha of the commit it names (task-137).
+ *
+ * @param root - Project root (the git repository).
+ * @param rev - A revision naming one commit: `HEAD`, a sha, a branch, a tag.
+ * @returns The commit's full sha.
+ * @throws {@link RevisionError} `VALIDATION` for a malformed rev, `NOT_FOUND` for one naming no commit;
+ *   `StorageError` `E_GIT_READ_FAILED` when git cannot answer at all (a `root` that is not a
+ *   repository, a `git` that cannot run) — a broken environment is not a missing revision.
+ */
+function resolveRevision(root, rev) {
+    if (!isWellFormedRevision(rev))
+        throw new RevisionError('VALIDATION', rev);
+    const sha = (0, storage_1.resolveCommitAtRev)(root, rev);
+    if (sha === null)
+        throw new RevisionError('NOT_FOUND', rev);
+    return sha;
+}
+/**
+ * Every file commit `sha` holds under `prefix` (`storage.listPathsAtRev`), for a sha
+ * {@link resolveRevision} has just resolved. `listPathsAtRev` answers `null` only for a revision that
+ * does not resolve, so a `null` here means git could not list a commit it had just resolved; that is a
+ * failed read, and it throws rather than passing for "the commit holds nothing" (the empty answer this
+ * module exists to keep away from an agent's context).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+function listPathsAtCommit(root, sha, prefix) {
+    const listed = (0, storage_1.listPathsAtRev)(root, sha, prefix);
+    if (listed === null) {
+        throw new storage_1.StorageError(storage_1.E_GIT_READ_FAILED, `git ls-tree ${sha} -- ${prefix} failed in ${root}: the commit could not be listed`);
+    }
+    return listed;
+}
+/**
+ * {@link listPathsAtCommit} with each blob's kind (`storage.listBlobEntriesAtRev`): the Memory scan
+ * reads at a commit through this, so that a symbolic link is known as one rather than read as a
+ * document whose text is the link's target (task-171, `bug-189`).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+function listBlobEntriesAtCommit(root, sha, prefix) {
+    const listed = (0, storage_1.listBlobEntriesAtRev)(root, sha, prefix);
+    if (listed === null) {
+        throw new storage_1.StorageError(storage_1.E_GIT_READ_FAILED, `git ls-tree ${sha} -- ${prefix} failed in ${root}: the commit could not be listed`);
+    }
+    return listed;
+}
+/**
+ * Run a `…AtRev(root, 'HEAD')` read with the answer the `…AtHead` readers have always given when there
+ * is no `HEAD` to read — `fallback` (`null`, or `[]` for a directory) — rather than an error. Two
+ * conditions mean that, and only two (task-171, `bug-201`):
+ *
+ * - {@link RevisionError} `NOT_FOUND`: a repository with no commit yet (`HEAD` is a constant, so
+ *   `VALIDATION` cannot occur);
+ * - `StorageError` `E_GIT_READ_FAILED` when `root` holds no `.git`: it is not a repository, so nothing
+ *   is committed there.
+ *
+ * Their callers treat the fallback as "nothing committed" (task-090, task-091, task-096). Any other
+ * failure is thrown, and the caller refuses it by name: a `git` that cannot be spawned, an answer past
+ * the read buffer, a tree git cannot read. Until task-171 every `E_GIT_READ_FAILED` gave the fallback,
+ * so a failed read inside a repository passed for an empty baseline.
+ *
+ * @param root - The project root the read is against; asked only whether it holds `.git`.
+ */
+function atHeadOr(root, read, fallback) {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (error instanceof RevisionError && error.code === 'NOT_FOUND')
+            return fallback;
+        if (error instanceof storage_1.StorageError && error.code === storage_1.E_GIT_READ_FAILED && !(0, fs_1.existsSync)((0, path_1.join)(root, '.git')))
+            return fallback;
+        throw error;
+    }
+}
+//# sourceMappingURL=revision.js.map

package/dist/core/revision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"revision.js","sourceRoot":"","sources":["../../src/core/revision.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -18,28 +18,54 @@ export interface CoreError {
     readonly code: CoreErrorCode;
     readonly message: string;
     readonly details?: Record<string, unknown>;
+    /**
+     * One sentence suggesting what to do next, which the CLI prints as `spec-005` §3.1's `hint:` line
+     * (the `hint` field under `json`/`yaml`). It never changes the refusal or its code: `agent show`
+     * says through it that only the working tree holds the run it refused (task-220, `spec-016` §6,
+     * the `command-baseline` directive: the working tree may explain a refusal, never decide it).
+     * Absent when there is nothing to suggest.
+     */
+    readonly hint?: string;
 }
 /**
  * The discriminated-union return of every {@link CoreFn} (spec-006 §2): `ok: true` with the operation's
  * `value` (and, for a mutation, the `commit` it produced), or `ok: false` with a {@link CoreError}.
  * Expected domain failures travel here, never as a thrown exception.
+ *
+ * `warnings` (task-169, `dl-062` Q1 option 3) is the **success-warning channel**: what a successful
+ * operation wants the operator told — e.g. that `directive assign --force` rewrote `roles.yaml` as a
+ * whole file and what that normalized — kept apart from `value` so it never becomes part of the
+ * payload a script parses. Each entry is one operator-facing sentence, in the order core recorded it
+ * (REQ-SYS-07). The key is absent when there is nothing to say, never an empty list. Each surface
+ * renders it in one place: the CLI on stderr (`src/cli/warning.ts`), the MCP Tool result in
+ * `structuredContent` (`src/mcp/registrar.ts`).
  */
 export type CoreResult<T> = {
     readonly ok: true;
     readonly value: T;
+    /**
+     * The commit the operation produced. `message` is the operation's message, not the stored body:
+     * `commitPaths` appends the `WingFoil-Version:` trailer paragraph to what it records (task-192,
+     * `dl-111`), and `git log --format=%B <sha>` reads the stored body.
+     */
     readonly commit?: {
         readonly sha: string;
         readonly message: string;
     };
+    readonly warnings?: readonly string[];
 } | {
     readonly ok: false;
     readonly error: CoreError;
 };
-/** Build a success {@link CoreResult}, optionally carrying the git commit the operation produced. */
+/**
+ * Build a success {@link CoreResult}, optionally carrying the git commit the operation produced and
+ * the warnings to show the operator (task-169). An empty `warnings` list is the same as none: the
+ * result then has no `warnings` key, the shape every success had before the channel existed.
+ */
 export declare function coreOk<T>(value: T, commit?: {
     sha: string;
     message: string;
-}): CoreResult<T>;
+}, warnings?: readonly string[]): CoreResult<T>;
 /** Build a failure {@link CoreResult} from a {@link CoreError}. */
 export declare function coreErr<T = never>(error: CoreError): CoreResult<T>;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,IAAI,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtD,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAE5F;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,IAAI,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,KAAK,EAAE,CAAC,EACR,MAAM,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACzC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAC3B,UAAU,CAAC,CAAC,CAAC,CAOf;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}