@tenphi/akno-core 0.1.0

package/dist/write/edit.js

@@ -0,0 +1,231 @@
+import { AknoError } from '@tenphi/akno-protocol';
+import { declaredFrontmatter, parseFrontmatter, withId } from "../kb/frontmatter.js";
+export function applyEdit(original, edit) {
+    const frontmatter = parseFrontmatter(original);
+    const head = original.slice(0, frontmatter.bodyOffset);
+    const body = original.slice(frontmatter.bodyOffset);
+    if (edit.kind === 'content') {
+        const declared = declaredFrontmatter(edit.content);
+        if (declared) {
+            // `id` is Akno's own key and the caller has no reason to be carrying it. Losing it
+            // detaches the page from its row, so it survives a rewrite that omits it.
+            const id = frontmatter.data.id;
+            const nextHead = typeof id === 'string' && id.length > 0 ? withId(declared.head, id) : declared.head;
+            // A blank line between the closing fence and the body, matching how every page Akno
+            // composes is laid out. `bodyOffset` has already eaten the fence's own newline.
+            const separated = declared.body.startsWith('\n') ? declared.body : `\n${declared.body}`;
+            const content = nextHead + endWithNewline(separated);
+            const dropped = Object.keys(frontmatter.data).filter((key) => key !== 'id' && !Object.hasOwn(declared.data, key));
+            return {
+                content,
+                firstChangedLine: firstDifference(original, content),
+                frontmatter: { adopted: true, dropped },
+            };
+        }
+    }
+    const nextBody = editBody(body, edit);
+    const content = head + nextBody;
+    return { content, firstChangedLine: firstDifference(original, content) };
+}
+function editBody(body, edit) {
+    switch (edit.kind) {
+        case 'content':
+            return endWithNewline(edit.content);
+        case 'append': {
+            if (edit.section !== undefined)
+                return appendUnderHeading(body, edit.section, edit.text);
+            // A blank line before the appended text, unless the body already ends in
+            // one. Appending flush against the previous line silently joins two list
+            // items or two paragraphs into one.
+            const trimmed = body.replace(/\s+$/, '');
+            const separator = trimmed.length === 0 ? '' : '\n\n';
+            return endWithNewline(`${trimmed}${separator}${edit.text.trim()}`);
+        }
+        case 'replace': {
+            const occurrences = countOccurrences(body, edit.find);
+            if (occurrences === 0) {
+                throw new AknoError('invalid', `nothing to replace: the page does not contain that text`, {
+                    find: edit.find.slice(0, 120),
+                });
+            }
+            if (occurrences > 1) {
+                // Replacing the first of several is a coin flip about which line the
+                // caller meant, and the wrong guess edits a line nobody was looking at.
+                throw new AknoError('invalid', `that text appears ${occurrences} times — include enough context to identify one`, { find: edit.find.slice(0, 120), occurrences });
+            }
+            return endWithNewline(body.replace(edit.find, edit.with));
+        }
+        case 'patch':
+            return endWithNewline(applyUnifiedDiff(body, edit.patch));
+    }
+}
+const LIST_ITEM = /^\s*(?:[-*+]\s|\d+[.)]\s)/;
+/**
+ * Appends at the end of a heading's section — after its last line, before the next heading at
+ * the same level or above.
+ *
+ * A page has structure and its author put it there. A claim about rent belongs under `## Rent`,
+ * and appending it to the end of the file instead puts it under whatever heading happens to be
+ * last, where a reader will attribute it to the wrong subject. That is not hypothetical: the
+ * host's tool advertised this and the schema silently dropped it, so every heading-scoped
+ * append had been landing at the bottom of the page.
+ *
+ * Absent or ambiguous is an error, matching `replace`. A caller that named a heading had one in
+ * mind, and the alternative to saying so is picking one of several and being quietly wrong.
+ */
+function appendUnderHeading(body, section, text) {
+    const wanted = section
+        .trim()
+        .replace(/^#+\s*/, '')
+        .toLowerCase();
+    const lines = body.split('\n');
+    const matches = [];
+    lines.forEach((line, index) => {
+        const heading = /^(#{1,6})\s+(.*?)\s*$/.exec(line);
+        if (heading && heading[2].toLowerCase() === wanted) {
+            matches.push({ index, level: heading[1].length });
+        }
+    });
+    if (matches.length === 0) {
+        throw new AknoError('invalid', `the page has no heading called "${section}"`, { section });
+    }
+    if (matches.length > 1) {
+        throw new AknoError('invalid', `"${section}" appears ${matches.length} times on this page — append without a section, or patch`, { section, occurrences: matches.length });
+    }
+    const { index, level } = matches[0];
+    // The section runs to the next heading at the same level or shallower. A deeper one is part
+    // of this section, and stopping at it would insert above content that belongs above.
+    let end = lines.length;
+    for (let i = index + 1; i < lines.length; i++) {
+        const heading = /^(#{1,6})\s/.exec(lines[i]);
+        if (heading && heading[1].length <= level) {
+            end = i;
+            break;
+        }
+    }
+    // Back over the blank lines that separate this section from the next, so the insertion lands
+    // against the section's own content rather than against the following heading.
+    let at = end;
+    while (at > index + 1 && lines[at - 1].trim() === '')
+        at--;
+    // A blank line separates two paragraphs and *breaks* a list — Markdown reads a gap between
+    // items as a loose list and renders every item wrapped in a paragraph. Appending a bullet
+    // under a heading is the common case here, so the two are distinguished rather than always
+    // getting a gap.
+    const previous = lines[at - 1];
+    const bothListItems = LIST_ITEM.test(previous) && LIST_ITEM.test(text.trim());
+    const separator = previous.trim() === '' || bothListItems ? [] : [''];
+    lines.splice(at, 0, ...separator, text.trim());
+    return endWithNewline(lines.join('\n'));
+}
+function endWithNewline(text) {
+    return text.endsWith('\n') ? text : `${text}\n`;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count++;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function firstDifference(before, after) {
+    if (before === after)
+        return null;
+    const a = before.split('\n');
+    const b = after.split('\n');
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if (a[i] !== b[i])
+            return i + 1;
+    }
+    return null;
+}
+// ─── Unified diff ───────────────────────────────────────────────────────────
+/**
+ * A strict unified-diff applier: every context and removal line must match the
+ * file exactly, or the whole patch is refused.
+ *
+ * Strictness is the feature. A fuzzy applier that "finds the nearest match" will
+ * eventually apply a hunk to the wrong place, and in a knowledge base that means a
+ * value silently attached to the wrong subject — the exact failure Akno exists
+ * to prevent. Refusing costs the caller a re-read; guessing costs correctness.
+ *
+ * The `@@` line numbers are treated as a hint, not as truth: agents get them wrong
+ * constantly, and the context lines identify the location unambiguously anyway.
+ */
+export function applyUnifiedDiff(body, patch) {
+    const hunks = parseHunks(patch);
+    if (hunks.length === 0) {
+        throw new AknoError('invalid', 'the patch contains no @@ hunks');
+    }
+    const lines = body.split('\n');
+    // Apply back to front so earlier hunks' line numbers stay valid.
+    const located = hunks.map((hunk) => ({ hunk, at: locate(lines, hunk) }));
+    located.sort((a, b) => b.at - a.at);
+    for (const { hunk, at } of located) {
+        const removals = hunk.lines.filter((line) => line.sign !== '+').length;
+        const replacement = hunk.lines.filter((line) => line.sign !== '-').map((line) => line.text);
+        lines.splice(at, removals, ...replacement);
+    }
+    return lines.join('\n');
+}
+function parseHunks(patch) {
+    const hunks = [];
+    let current = null;
+    for (const raw of patch.split('\n')) {
+        const header = /^@@\s+-(\d+)(?:,\d+)?\s+\+\d+(?:,\d+)?\s+@@/.exec(raw);
+        if (header) {
+            current = { hint: Number(header[1]), lines: [] };
+            hunks.push(current);
+            continue;
+        }
+        if (!current)
+            continue;
+        // `---`/`+++` file headers, and the "\ No newline" marker, are not content.
+        if (raw.startsWith('---') || raw.startsWith('+++') || raw.startsWith('\\'))
+            continue;
+        const sign = raw[0];
+        if (sign === ' ' || sign === '+' || sign === '-') {
+            current.lines.push({ sign, text: raw.slice(1) });
+        }
+        else if (raw.length === 0) {
+            // A truly empty line in a diff is a context line for an empty line.
+            current.lines.push({ sign: ' ', text: '' });
+        }
+    }
+    return hunks.filter((hunk) => hunk.lines.length > 0);
+}
+/** Finds the one place a hunk's context matches, searching outward from the hint. */
+function locate(lines, hunk) {
+    const expected = hunk.lines.filter((line) => line.sign !== '+').map((line) => line.text);
+    if (expected.length === 0) {
+        // Pure insertion: the hint is all there is to go on.
+        const at = Math.min(Math.max(hunk.hint - 1, 0), lines.length);
+        return at;
+    }
+    const matchesAt = (start) => start >= 0 &&
+        start + expected.length <= lines.length &&
+        expected.every((text, offset) => lines[start + offset] === text);
+    const hinted = hunk.hint - 1;
+    if (matchesAt(hinted))
+        return hinted;
+    // Search outward, and require the match to be unique so an ambiguous hunk is
+    // refused rather than applied to whichever copy came first.
+    const found = [];
+    for (let start = 0; start + expected.length <= lines.length; start++) {
+        if (matchesAt(start))
+            found.push(start);
+    }
+    if (found.length === 1)
+        return found[0];
+    if (found.length === 0) {
+        throw new AknoError('invalid', 'patch context does not match the page — re-read it and patch again', {
+            expected: expected.slice(0, 3),
+        });
+    }
+    throw new AknoError('invalid', `patch context matches ${found.length} places — include more context to identify one`, { expected: expected.slice(0, 3) });
+}
+//# sourceMappingURL=edit.js.map

package/dist/write/edit.js.map

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

package/dist/write/gate.d.ts

@@ -0,0 +1,59 @@
+import type { FolderRequired } from '@tenphi/akno-protocol';
+import type { Store } from '../store/db.ts';
+import type { AknoConfig } from '../config/schema.ts';
+/**
+ * **A page may not appear in a folder nobody has described.**
+ *
+ * This used to be an approval: a new top-level folder became a proposal, an approval card, and
+ * a decision the owner had to make from a phone. That was the wrong question put to the wrong
+ * person. An owner cannot usefully rule on whether a research note needs a `research/` folder,
+ * and while the question waited the finding was lost. The second-order damage was worse — an
+ * agent that learns a folder request can be declined learns to append to whatever page already
+ * exists, and claims start landing on the pages of unrelated subjects.
+ *
+ * So nothing here waits on a human any more. What is refused is not the folder but the
+ * *silence*: the write comes back `requires_folder`, the caller declares the folder with the
+ * `folder` op — ungated, one call, saying what belongs there — and repeats the write. The user
+ * is never asked, and no folder appears that nothing can explain.
+ *
+ * `gate: "top-level"` (the default) requires a declaration for a new top-level folder and lets
+ * subfolders of a described one through. The asymmetry is the same as it always was:
+ * `medical/` appearing is a statement about how the knowledge base is organised;
+ * `work/projects/atlas/` under an existing `work/projects/` is not.
+ *
+ * If the user makes a folder themselves, that folder exists and nothing is asked. This module
+ * never sees a hand edit.
+ */
+export type GateDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    requiresFolder: FolderRequired;
+};
+export interface ProposalRow {
+    id: string;
+    at: string;
+    kind: string;
+    reason: string;
+    subject: string;
+    payload: string;
+    nearest: string;
+    status: 'pending' | 'approved' | 'declined';
+}
+export declare class Gate {
+    #private;
+    constructor(store: Store, config: AknoConfig);
+    /**
+     * Checks a slug an agent wants to create.
+     *
+     * Nothing is recorded when this refuses. A proposal row existed to hold a question for the
+     * user; there is no question now, so writing one would leave `akno proposals` full of
+     * things nobody will ever answer — and an agent that re-asks after declaring the folder
+     * would collect one per attempt.
+     */
+    check(slug: string, actor: string): GateDecision;
+    pending(): ProposalRow[];
+    get(id: string): ProposalRow | null;
+    resolve(id: string, status: 'approved' | 'declined', changeId?: string): void;
+}
+//# sourceMappingURL=gate.d.ts.map

package/dist/write/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/write/gate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,YAAY,GAAG;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,cAAc,EAAE,cAAc,CAAA;CAAE,CAAC;AAElG,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;CAC7C;AAED,qBAAa,IAAI;;gBAIH,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU;IAK5C;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY;IAuEhD,OAAO,IAAI,WAAW,EAAE;IAMxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAInC,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,UAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;CAK9E"}

package/dist/write/gate.js

@@ -0,0 +1,99 @@
+import { physicalFolderExists } from "../kb/folders.js";
+export class Gate {
+    #store;
+    #config;
+    constructor(store, config) {
+        this.#store = store;
+        this.#config = config;
+    }
+    /**
+     * Checks a slug an agent wants to create.
+     *
+     * Nothing is recorded when this refuses. A proposal row existed to hold a question for the
+     * user; there is no question now, so writing one would leave `akno proposals` full of
+     * things nobody will ever answer — and an agent that re-asks after declaring the folder
+     * would collect one per attempt.
+     */
+    check(slug, actor) {
+        if (actor === 'user' || this.#config.gate === 'none')
+            return { allowed: true };
+        const newFolder = this.#firstUndeclaredFolder(slug);
+        if (!newFolder)
+            return { allowed: true };
+        if (this.#config.gate === 'top-level' && newFolder.includes('/'))
+            return { allowed: true };
+        return { allowed: false, requiresFolder: { folder: newFolder, nearest: this.#nearest(slug) } };
+    }
+    /**
+     * The shallowest folder on the slug's path that holds no page **and** has no rule
+     * describing it. Null when every folder on the way is one or the other.
+     *
+     * The rule half is what makes declare-then-write work in a single turn: a folder that was
+     * described a moment ago holds nothing yet, and asking the `pages` table alone would refuse
+     * the very write the declaration was made for.
+     */
+    #firstUndeclaredFolder(slug) {
+        const segments = slug.split('/');
+        segments.pop(); // The page's own basename is not a folder.
+        if (segments.length === 0)
+            return null;
+        const exists = this.#store.db.prepare("SELECT 1 AS ok FROM pages WHERE slug LIKE ? || '/%' LIMIT 1");
+        for (let depth = 1; depth <= segments.length; depth++) {
+            const folder = segments.slice(0, depth).join('/');
+            if (exists.get(folder))
+                continue;
+            // The page index cannot represent an empty directory. A folder the user created on disk is
+            // nevertheless an explicit taxonomy decision and must not be reported as nonexistent.
+            if (physicalFolderExists(this.#config, folder))
+                continue;
+            if (this.#described(folder))
+                continue;
+            return folder;
+        }
+        return null;
+    }
+    /** True when some rule names this exact folder — `research` for a `research/**` rule. */
+    #described(folder) {
+        return this.#config.rules.some((rule) => rule.glob.replace(/\/\*+$/, '') === folder);
+    }
+    /**
+     * Where this could go instead, so a new folder is a choice rather than a reflex. Existing
+     * folders whose name shares a word with the slug, then the busiest top-level folders.
+     */
+    #nearest(slug) {
+        const words = slug
+            .split(/[/\-_\s]+/)
+            .filter((word) => word.length > 3)
+            .map((word) => word.toLowerCase());
+        const out = new Set();
+        if (words.length > 0) {
+            const like = this.#store.db.prepare('SELECT DISTINCT slug FROM pages WHERE lower(slug) LIKE ? LIMIT 3');
+            for (const word of words) {
+                for (const row of like.all(`%${word}%`))
+                    out.add(row.slug);
+            }
+        }
+        const folders = this.#store.db
+            .prepare(`SELECT substr(slug, 1, instr(slug, '/') - 1) AS folder, count(*) AS n
+           FROM pages WHERE instr(slug, '/') > 0
+          GROUP BY folder ORDER BY n DESC LIMIT 4`)
+            .all();
+        for (const row of folders)
+            out.add(row.folder);
+        return [...out].slice(0, 6);
+    }
+    pending() {
+        return this.#store.db
+            .prepare("SELECT * FROM proposals WHERE status = 'pending' ORDER BY at DESC")
+            .all();
+    }
+    get(id) {
+        return this.#store.db.prepare('SELECT * FROM proposals WHERE id = ?').get(id) ?? null;
+    }
+    resolve(id, status, changeId) {
+        this.#store.db
+            .prepare('UPDATE proposals SET status = ?, resolved_at = ?, change_id = ? WHERE id = ?')
+            .run(status, new Date().toISOString(), changeId ?? null, id);
+    }
+}
+//# sourceMappingURL=gate.js.map

package/dist/write/gate.js.map

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

package/dist/write/journal.d.ts

@@ -0,0 +1,90 @@
+import type { Store } from '../store/db.ts';
+import { type WriteResult } from './atomic.ts';
+/**
+ * **The journal is the only irreplaceable table.** Everything else is
+ * derived from the Markdown and rebuilt by `akno index`; this holds the previous
+ * bytes, and there is nowhere else to get them.
+ *
+ * It records content, not pointers — so `undo` still works after
+ * `rm akno.db && akno index` has thrown away every fact id the change might
+ * otherwise have referenced — which is why a fact id is never stored here.
+ *
+ * The unit is a **change**, not a file. One `write` can touch a page, the event
+ * ledger and an attachment; `undo` reverses all of them or none, because a page
+ * whose ledger line survived it is a knowledge base that now lies.
+ */
+export type FileAction = 'created' | 'modified' | 'deleted' | 'moved';
+export interface ChangeFile {
+    relPath: string;
+    action: FileAction;
+    before: string | null;
+    after: string | null;
+    /** Set instead of `before` for a binary held in trash. */
+    snapshot?: string;
+    /**
+     * Where a `moved` file went, when its bytes are nowhere else.
+     *
+     * A page carries its old text in `before`, so undo recreates it and deletes the copy at the
+     * new path. An attachment has no text to carry, and reversing it that way deleted the file
+     * and restored nothing. With this, the reversal is the rename it should always have been.
+     */
+    movedTo?: string;
+}
+export interface ChangeSummary {
+    id: string;
+    at: string;
+    actor: string;
+    op: string;
+    summary: string;
+    status: 'applied' | 'undone';
+    files: {
+        relPath: string;
+        action: FileAction;
+    }[];
+}
+export declare class Journal {
+    #private;
+    constructor(store: Store, aknoPath: string, trashDir: string);
+    /**
+     * Records a change that has already been applied to disk. Deliberately after
+     * the fact: a journal entry for a write that then failed is a lie in the one
+     * table that has to be trustworthy, and the failure mode of recording late (a
+     * crash between write and journal leaves an un-undoable change) is both rarer
+     * and far less confusing than the reverse.
+     */
+    record(input: {
+        actor: string;
+        op: string;
+        summary: string;
+        files: ChangeFile[];
+    }): string;
+    /**
+     * Reverses a change: every file back to its previous bytes, in reverse order.
+     *
+     * Reverse order matters for a move — the change created the destination and
+     * deleted the source, so undoing destination-first leaves the source free to be
+     * recreated. Forward order would try to recreate the source while the
+     * destination still holds it.
+     */
+    undo(changeId: string): Promise<{
+        restored: string[];
+        removed: string[];
+        summary: string;
+    }>;
+    list(limit?: number): ChangeSummary[];
+    /**
+     * Moves a file into `trash/<change>/` and returns the snapshot path:
+     * `forget({slug})` moves a whole page to trash and stays undoable for the
+     * retention window — deleting outright would make "reversible" a lie.
+     */
+    trash(relPath: string, changeToken: string): Promise<string>;
+    /**
+     * Drops trashed files past the retention window. Called from the maintenance
+     * path, never from a write — a delete that also expires somebody else's older
+     * delete is a surprise nobody asked for.
+     */
+    expireTrash(retentionDays: number): Promise<number>;
+}
+/** Convenience: turn an atomic write result into the journal's shape. */
+export declare function fileEntry(result: WriteResult): ChangeFile;
+//# sourceMappingURL=journal.d.ts.map

package/dist/write/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../../src/write/journal.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAEtE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;CAClD;AAED,qBAAa,OAAO;;gBAKN,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAM5D;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,EAAE,CAAA;KAAE,GAAG,MAAM;IA8B1F;;;;;;;OAOG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAkFjG,IAAI,CAAC,KAAK,SAAK,GAAG,aAAa,EAAE;IAyBjC;;;;OAIG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAalE;;;;OAIG;IACG,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAmB1D;AAED,yEAAyE;AACzE,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,CAOzD"}