wingfoil 0.2.1

package/dist/memory/commit-message.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reasonDefectMessage = reasonDefectMessage;
+exports.normalizeReason = normalizeReason;
+exports.reasonDefect = reasonDefect;
+exports.parseReasonBlock = parseReasonBlock;
+exports.parseApproverTrailerLine = parseApproverTrailerLine;
+exports.formatMemoryCommitMessage = formatMemoryCommitMessage;
+/** The arrow used in `[from → to]` subject brackets (U+2192), as `./audit.ts`'s `BRACKET_RE` expects. */
+const ARROW = '→';
+// --- The reason grammar (dl-067-reason-trailer-contract) ---------------------------------------
+/**
+ * A git trailer line's shape (`Token: value`), as git itself recognises one. Used ONLY to identify a
+ * message's trailing trailer paragraph — the `Co-Authored-By:` block a hand-written commit ends with —
+ * which is where a `Reason:` block stops.
+ */
+const TRAILER_LINE_RE = /^[A-Za-z][A-Za-z0-9-]*:[ \t]\S/;
+/**
+ * The two trailer keys THIS project's reader acts on. A reason may not contain a line starting with
+ * either, because such a line is indistinguishable from the trailer itself. Deliberately narrow: on
+ * `main`, 8 approve/reject commits carry a generic `Key: value` line inside their reason (ordinary
+ * prose — `Action: amend spec-015 §3`, `A: before the v0.2 …`) and **0** carry a reserved one, so a
+ * broader rule would outlaw the approver's own writing style (dl-067 E5).
+ */
+const RESERVED_TRAILER_LINE_RE = /^(?:Approver|Reason):/;
+/** The `Reason:` key, at the start of a line. */
+const REASON_KEY_RE = /^Reason:[ \t]*/;
+/** The `Approver:` key, at the start of a line. */
+const APPROVER_KEY_RE = /^Approver:/;
+/** The exact refusal message for each defect — `spec-008-cli-grammar` §2's "invalid flag value" class (exit 2). */
+const REASON_DEFECT_MESSAGES = {
+    blank: 'invalid flag value: --reason must not be blank',
+    'reserved-trailer-line': 'invalid flag value: --reason must not contain a line starting with "Approver:" or "Reason:"',
+    'trailing-trailer-paragraph': 'invalid flag value: --reason must not end in a paragraph of "Key: value" lines',
+};
+/**
+ * The refusal message for `defect` — the single source of the wording the CLI prints and
+ * `spec-008-cli-grammar` §2 pins. Deliberately distinct from `missing required argument: --reason`
+ * (`src/core/require-reason.ts`), which answers the *omitted* case that spec-008 §2 and the P1.7/P1.8
+ * BDD features already quote verbatim (dl-067 S1).
+ */
+function reasonDefectMessage(defect) {
+    return REASON_DEFECT_MESSAGES[defect];
+}
+/**
+ * The declared normal form of a reason (`dl-067` clause 3) — two rules, from two different sources,
+ * and it is worth keeping them apart:
+ *
+ *  1. **git's**, which applies whether or not this function exists. `commitPaths`
+ *     (`src/storage/commit.ts`) commits with `-m`, so git's `cleanup=whitespace` strips per-line
+ *     trailing whitespace, collapses runs of blank lines to one, and drops leading and trailing blank
+ *     lines. This is why `spec-008-cli-grammar` §2's original "Recorded verbatim" was already false
+ *     for any multi-line text, independently of bug-042.
+ *  2. **This module's**: the first line's leading whitespace is trimmed. git does NOT do this. It is
+ *     needed because that line sits after `Reason: ` on the same physical line and
+ *     {@link parseReasonBlock} consumes the key together with the whitespace that follows it — so
+ *     without the trim, a reason beginning with spaces would not round-trip equally.
+ *
+ * Applying both HERE, on the way in, is what turns "approximately what you typed" into an assertable
+ * equality: what {@link parseReasonBlock} reads back out of the commit is exactly this function's
+ * output. Interior indentation is preserved by both rules — it carries meaning in real approval prose.
+ *
+ * Idempotent, and a pure function of its input (REQ-SYS-07).
+ */
+function normalizeReason(reason) {
+    return reason
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+$/, ''))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/^\n+/, '')
+        .replace(/\n+$/, '')
+        .replace(/^[ \t]+/, '');
+}
+/** Split a normalized reason into its paragraphs, dropping the blank separators. */
+function paragraphsOf(normalized) {
+    const paragraphs = [[]];
+    for (const line of normalized.split('\n')) {
+        if (line.trim() === '')
+            paragraphs.push([]);
+        else
+            paragraphs[paragraphs.length - 1].push(line);
+    }
+    return paragraphs.filter((paragraph) => paragraph.length > 0);
+}
+/**
+ * Why `reason` cannot be recorded in the `Reason:` trailer, or `null` when it can (`dl-067` clause 4).
+ *
+ * Judged on the NORMALIZED text ({@link normalizeReason}), because that is what would actually be
+ * stored — otherwise a defect could hide behind trailing whitespace git strips on the way in. This is
+ * the ONE place the rule is decided: `src/core/require-reason.ts` turns a non-`null` result into the
+ * `UsageError` (exit 2) the CLI boundary reports, and {@link formatMemoryCommitMessage} refuses the
+ * same values so no caller can route around that boundary.
+ */
+function reasonDefect(reason) {
+    const normalized = normalizeReason(reason);
+    if (normalized === '')
+        return 'blank';
+    const lines = normalized.split('\n');
+    if (lines.some((line) => RESERVED_TRAILER_LINE_RE.test(line)))
+        return 'reserved-trailer-line';
+    const paragraphs = paragraphsOf(normalized);
+    const last = paragraphs[paragraphs.length - 1];
+    if (paragraphs.length > 1 && last && last.every((line) => TRAILER_LINE_RE.test(line))) {
+        return 'trailing-trailer-paragraph';
+    }
+    return null;
+}
+/**
+ * Where a commit body's trailing trailer paragraph begins, or `lines.length` when it has none — the
+ * `Co-Authored-By:` block a hand-written WingFoil commit ends with. Defined the way git defines a
+ * trailer block: the final paragraph of the message, every line of which is trailer-shaped.
+ */
+function trailerParagraphStart(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1].trim() === '')
+        end -= 1;
+    let start = 0;
+    for (let index = end - 1; index >= 0; index -= 1) {
+        if (lines[index].trim() === '') {
+            start = index + 1;
+            break;
+        }
+    }
+    if (start === 0 || start >= end)
+        return lines.length;
+    return lines.slice(start, end).every((line) => TRAILER_LINE_RE.test(line)) ? start : lines.length;
+}
+/**
+ * The `Reason:` a commit body records, read as a BLOCK (`dl-067` clause 2): the remainder of the
+ * `Reason:` line plus every following body line, up to (exclusive) git's trailing trailer paragraph or
+ * the end of the body. `null` when the body records no reason, or records a bare `Reason:` with no
+ * value — the shape git's cleanup leaves behind when an empty reason is written (bug-042 F2), which
+ * `parseApprovalMetadata` degrades around rather than treating as an absent approval.
+ *
+ * This replaces the first-line capture `/^Reason:\s*(.+)$/m` that preceded it, and that is a real
+ * change to how existing history reads: 79 of `main`'s 171 approve/reject commits (46%) carry a reason
+ * continuing past line one, and every one of them was silently halved. It is a recovery, not a
+ * reinterpretation — the text was always in the commit; only the reader dropped it.
+ *
+ * A generic `Key: value` line INSIDE the block is ordinary prose and does not end it; only a trailing
+ * paragraph made entirely of trailer lines does (dl-067 E5).
+ */
+function parseReasonBlock(body) {
+    const lines = body.replace(/\r\n?/g, '\n').split('\n');
+    const start = lines.findIndex((line) => REASON_KEY_RE.test(line));
+    if (start === -1)
+        return null;
+    const end = Math.max(trailerParagraphStart(lines), start + 1);
+    const block = [lines[start].replace(REASON_KEY_RE, ''), ...lines.slice(start + 1, end)].join('\n');
+    const normalized = normalizeReason(block);
+    return normalized === '' ? null : normalized;
+}
+/**
+ * The commit body's `Approver:` trailer line, or `null` when it has none — anchored to the body's
+ * FIRST non-empty line (`dl-067` clause 5). {@link formatMemoryCommitMessage} has always emitted it
+ * there, and it is the first body line in 171 of `main`'s 171 approve/reject commits (dl-067 E4), so
+ * anchoring costs no existing commit its approver while closing bug-042 F3 on the read side: an
+ * `Approver:` line appearing anywhere else is text some reason happens to contain, never an approval
+ * record. `./audit.ts` destructures the returned line into an identity — that shape is its concern;
+ * the line's POSITION is this module's.
+ */
+function parseApproverTrailerLine(body) {
+    const first = body
+        .replace(/\r\n?/g, '\n')
+        .split('\n')
+        .find((line) => line.trim() !== '');
+    return first !== undefined && APPROVER_KEY_RE.test(first) ? first : null;
+}
+/**
+ * Format a Memory transition commit message: the subject, then — only when an approver or reason is
+ * given — a blank line and the `Approver:` / `Reason:` lines in that order.
+ *
+ * The reason is emitted in its declared normal form and, when it carries a defect
+ * ({@link reasonDefect}), refused rather than written. The CLI boundary
+ * (`src/core/require-reason.ts`) already refuses the same values with the same messages at exit 2, so
+ * reaching this throw means a caller bypassed that boundary — it exists so no *future* caller can
+ * (dl-067 clause 5; bug-042 F2/F3).
+ *
+ * @throws `Error` when `ids` is empty: a transition commit always names what it moved.
+ * @throws `Error` when `reason` cannot be recorded in the trailer, carrying that defect's message.
+ */
+function formatMemoryCommitMessage(input) {
+    if (input.ids.length === 0) {
+        throw new Error('a Memory transition commit must name at least one id');
+    }
+    const defect = input.reason === undefined ? null : reasonDefect(input.reason);
+    if (defect !== null) {
+        throw new Error(reasonDefectMessage(defect));
+    }
+    const bracket = input.transition ? ` [${input.transition.from} ${ARROW} ${input.transition.to}]` : '';
+    const subject = `wf(${input.type}): ${input.op} ${input.ids.join(', ')}${bracket}`;
+    const body = [];
+    if (input.approver) {
+        body.push(`Approver: ${input.approver.name} <${input.approver.email}> (${input.approver.role})`);
+    }
+    if (input.reason !== undefined) {
+        body.push(`Reason: ${normalizeReason(input.reason)}`);
+    }
+    return body.length === 0 ? subject : `${subject}\n\n${body.join('\n')}`;
+}
+//# sourceMappingURL=commit-message.js.map

package/dist/memory/commit-message.js.map

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

package/dist/memory/entry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The git-backed Memory-entry store primitive (task-022-implement-memory-entries, P1.11,
+ * REQ-SYS-01/REQ-SYS-03, REQ-SEC-06) — the storage foundation `wingfoil memory add` (task-020) and
+ * `wingfoil memory submit` build their CLI/CoreResult surface on top of.
+ *
+ * This module composes three primitives that already exist and are NOT re-implemented here:
+ *   - `resolveConfinedMemoryPath` (task-017-storage-confinement, `../storage/memory-path` — not
+ *     re-exported by the `../storage` barrel, imported directly per that module's own convention)
+ *     renders a type's `path` pattern against concrete values and refuses — throwing `StorageError`
+ *     `E_PATH_ESCAPES_ROOT` — any resolution that would land outside the project root, BEFORE
+ *     anything is written, judging the rendered string **and** its resolution on the filesystem
+ *     (`task-105`, `bug-117`: a symlinked type directory leaves the project with no traversal
+ *     anywhere in the string). Its message opens with the corrected, canonical REQ-SEC-06
+ *     fit-criterion sentence — `'Memory entries must reside within the project root'` — and then
+ *     names both spellings of the path, what the pattern rendered and where it really lands, because
+ *     on the symlink case the two differing is the finding. The BDD `.feature` file's older "must
+ *     reside under .wingfoil/memory/" wording is stale (see this task's Execution Notes for the
+ *     reconciliation).
+ *   - `writeDocument` (`../storage`) writes bytes only (mkdir-p).
+ *   - `commitPaths` (`../storage`) stages exactly the one resolved path and produces exactly one
+ *     commit — so calling {@link writeMemoryEntry} twice against the SAME `pattern`/`values` (i.e.
+ *     the same target file, modified) yields two DISTINCT commits, with the file's prior content
+ *     retrievable from git history via that file's own commit log — the P1.11 "each Memory entry is
+ *     individually versioned" contract.
+ *
+ * Deliberately a throwing **library** primitive, not a `CoreResult`-wrapped `CORE_MODULES` operation:
+ * this task's scope is the reusable store primitive, not the `wingfoil memory add` CLI command or its
+ * `StorageError` → `CoreError` mapping — both of those are task-020's scope, which wires this
+ * primitive in (see the task's Execution Notes for that scoping decision).
+ */
+import type { CommitOptions } from '../storage';
+/** The result of a single {@link writeMemoryEntry} call. */
+export interface MemoryEntryWrite {
+    /** The absolute, confinement-verified path that was written (see `resolveConfinedMemoryPath`). */
+    readonly path: string;
+    /** The 40-hex sha of the single commit this write produced. */
+    readonly sha: string;
+}
+/**
+ * Render `pattern` against `values` (per `memory.yaml`'s per-type `path` pattern,
+ * spec-001-memory-yaml-schema), confining the result to `root` (REQ-SEC-06), write `content` to that
+ * path, and commit exactly that one path as a single commit with `message` (REQ-SYS-01).
+ *
+ * @throws {@link ../storage/errors.StorageError} `E_PATH_ESCAPES_ROOT` when the resolved path would
+ *   escape `root` — refused before any write, so a rejected call writes and commits nothing.
+ * @throws {@link ../storage/errors.StorageError} `E_TARGET_IS_SYMLINK` when the target itself is a
+ *   symbolic link, dangling or live (`task-106`, `bug-120`): `writeDocument`'s `writeFileSync`
+ *   follows one, so the bytes would land at the link's destination rather than at the path this
+ *   function names — and through a *dangling* link the write used to succeed and commit. Refused in
+ *   the same place, before the same write.
+ * @throws whatever `commitPaths`/git raises (e.g. no configured git identity) — callers that need a
+ *   pre-flight identity check must call `requireGitIdentity` (`../core/git-identity`) themselves
+ *   before invoking this primitive, same as every other mutating core operation.
+ */
+export declare function writeMemoryEntry(root: string, pattern: string, values: Record<string, string>, content: string, message: string, options?: CommitOptions): MemoryEntryWrite;
+//# sourceMappingURL=entry.d.ts.map

package/dist/memory/entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.d.ts","sourceRoot":"","sources":["../../src/memory/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,aAAkB,GAC1B,gBAAgB,CAKlB"}

package/dist/memory/entry.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeMemoryEntry = writeMemoryEntry;
+const storage_1 = require("../storage");
+const memory_path_1 = require("../storage/memory-path");
+/**
+ * Render `pattern` against `values` (per `memory.yaml`'s per-type `path` pattern,
+ * spec-001-memory-yaml-schema), confining the result to `root` (REQ-SEC-06), write `content` to that
+ * path, and commit exactly that one path as a single commit with `message` (REQ-SYS-01).
+ *
+ * @throws {@link ../storage/errors.StorageError} `E_PATH_ESCAPES_ROOT` when the resolved path would
+ *   escape `root` — refused before any write, so a rejected call writes and commits nothing.
+ * @throws {@link ../storage/errors.StorageError} `E_TARGET_IS_SYMLINK` when the target itself is a
+ *   symbolic link, dangling or live (`task-106`, `bug-120`): `writeDocument`'s `writeFileSync`
+ *   follows one, so the bytes would land at the link's destination rather than at the path this
+ *   function names — and through a *dangling* link the write used to succeed and commit. Refused in
+ *   the same place, before the same write.
+ * @throws whatever `commitPaths`/git raises (e.g. no configured git identity) — callers that need a
+ *   pre-flight identity check must call `requireGitIdentity` (`../core/git-identity`) themselves
+ *   before invoking this primitive, same as every other mutating core operation.
+ */
+function writeMemoryEntry(root, pattern, values, content, message, options = {}) {
+    const path = (0, memory_path_1.resolveConfinedMemoryPath)(root, pattern, values);
+    (0, storage_1.writeDocument)(path, content);
+    const sha = (0, storage_1.commitPaths)(root, [path], message, options);
+    return { path, sha };
+}
+//# sourceMappingURL=entry.js.map

package/dist/memory/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../src/memory/entry.ts"],"names":[],"mappings":";;AA0DA,4CAYC;AAvCD,wCAAwD;AACxD,wDAAmE;AAUnE;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,gBAAgB,CAC9B,IAAY,EACZ,OAAe,EACf,MAA8B,EAC9B,OAAe,EACf,OAAe,EACf,UAAyB,EAAE;IAE3B,MAAM,IAAI,GAAG,IAAA,uCAAyB,EAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9D,IAAA,uBAAa,EAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAA,qBAAW,EAAC,IAAI,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IACxD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AACvB,CAAC"}

package/dist/memory/frontmatter-edit.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Set top-level `key` to the string `value`, serialized YAML-safely. An existing entry is replaced as a
+ * whole — continuation lines, block-scalar body or multi-line quoted value included. A `# comment` on
+ * the key line is kept when the old value ended on that line; the line ending of the key line is kept.
+ * An absent key is appended after the last non-blank frontmatter line, with the document's line ending.
+ *
+ * @throws `Error` when the document has no frontmatter block.
+ */
+export declare function setFrontmatterField(content: string, key: string, value: string): string;
+/**
+ * Remove top-level `key` together with every line its value spans (rules in the module doc). Blank
+ * lines and comments that follow the value belong to the parent mapping and are kept. Returns `content`
+ * unchanged when the key is absent.
+ *
+ * @throws `Error` when the document has no frontmatter block.
+ */
+export declare function removeFrontmatterField(content: string, key: string): string;
+/**
+ * The post-condition of a frontmatter edit, checked by re-parsing rather than by trusting the editor.
+ * `expected` maps each field the operation owns to its required value (`undefined` = must be absent).
+ * Returns the problems found, empty when the edit is sound:
+ *
+ * - the rendered document has no frontmatter, or it does not parse;
+ * - an owned field does not have its expected value, or is still present when it should be removed;
+ * - any **other** field's parsed value differs from `before` — an edit leaked into a field it does not own.
+ *
+ * Deterministic (REQ-SYS-07): owned fields in `expected`'s order, then other fields sorted by name.
+ */
+export declare function verifyFrontmatterEdit(before: string, after: string, expected: Readonly<Record<string, string | undefined>>): string[];
+/**
+ * How much of a document an operation is entitled to change (task-088, `bug-076`), per
+ * `spec-010-memory-frontmatter-schema` § "Field-write ownership":
+ *
+ * - `declared-fields-only` — the operation owns `status` (plus `rejection_reason` on `memory.reject`)
+ *   and **nothing else**: no other frontmatter field, and not one byte of the body. This is
+ *   `memory.approve`, `memory.reject` and `memory.deprecate`.
+ * - `carries-content` — the operation is defined as filling content *and* moving state, so the body
+ *   and the type's other frontmatter fields may legitimately change. This is `memory.submit` alone,
+ *   and the asymmetry is deliberate rather than an oversight: an approval that carried a body would
+ *   attest, under an approver's name, to content no commit subject mentions.
+ */
+export type DocumentScope = 'declared-fields-only' | 'carries-content';
+/**
+ * The post-condition of a whole-document edit: {@link verifyFrontmatterEdit}'s frontmatter rules plus
+ * the body, gated by `scope`. Returns the problems found, empty when the edit is within scope.
+ *
+ * Under `carries-content` only the `expected` fields are checked — every other field and the body are
+ * the operation's to write. Under `declared-fields-only` an unowned field or a changed body is a
+ * problem, which is the rule `bug-076` showed nothing was enforcing.
+ *
+ * Deterministic (REQ-SYS-07): owned fields in `expected`'s order, then other fields sorted by name,
+ * then the body.
+ */
+export declare function verifyDocumentEdit(before: string, after: string, expected: Readonly<Record<string, string | undefined>>, scope: DocumentScope): string[];
+/**
+ * Name, in a form a person can act on, every way `after` differs from `before` — the frontmatter
+ * fields whose parsed value moved, and whether the body moved. `before` is `null` when the document
+ * does not exist at the revision being compared against.
+ *
+ * This is the *reporting* half of {@link verifyDocumentEdit}: the verifier answers "is this edit in
+ * scope", this answers "so what exactly is in the way". A difference that changes no parsed value and
+ * no body byte — a reordered comment, a requoted scalar — is still a difference git will commit, so
+ * it is reported as such rather than dropped.
+ *
+ * Deterministic (REQ-SYS-07): fields sorted by name, then the frontmatter-text fallback, then the body.
+ */
+export declare function describeDocumentChanges(before: string | null, after: string): string[];
+//# sourceMappingURL=frontmatter-edit.d.ts.map

package/dist/memory/frontmatter-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter-edit.d.ts","sourceRoot":"","sources":["../../src/memory/frontmatter-edit.ts"],"names":[],"mappings":"AAwKA;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAsBvF;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAK3E;AAeD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,MAAM,EAAE,CAOrI;AAkCD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,sBAAsB,GAAG,iBAAiB,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,EACtD,KAAK,EAAE,aAAa,GACnB,MAAM,EAAE,CAYV;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAqBtF"}