@tenphi/akno-core 0.1.0

package/dist/ingest/store.d.ts

@@ -0,0 +1,66 @@
+import type { AknoContext } from '../context.ts';
+import type { Extraction } from './extract.ts';
+import type { ChangeFile } from '../write/journal.ts';
+/**
+ * Where a stored document actually goes, and how it gets recorded.
+ *
+ * **Stored files are content-addressed**: `<page-basename>-<sha8>.<ext>`. That is worth
+ * more than it looks — naming a file after its page forces a whole family of rules
+ * ("a document must get its own page", "two files on one page each need a label to tell
+ * them apart", "never park a document on a person's page"). Content addressing makes
+ * all of them unnecessary: files are unique by construction, several can sit on one
+ * page without ambiguity, and `label` goes back to being a description rather than a
+ * disambiguator.
+ *
+ * One implementation, used by `ingest` and by `write`'s `documents` field. Two would
+ * eventually disagree about the naming scheme, and the scheme is the whole point.
+ */
+export interface StoredDocument {
+    /** Path inside the knowledge base, content-addressed. */
+    relPath: string;
+    sha256: string;
+    bytes: number;
+    /** For the journal. A moved file records its origin so undo can put it back. */
+    file: ChangeFile;
+}
+export interface StoreOptions {
+    ctx: AknoContext;
+    /** Absolute path to read from. */
+    source: string;
+    /** The page this attachment belongs to. Supplies the basename. */
+    pageSlug: string;
+    /**
+     * Move rather than copy.
+     *
+     * **The inbox is the only place Akno moves files.** A file dropped straight
+     * into `documents/` was put there on purpose; Akno will name it, page it and index
+     * it, but never relocate it. An external file handed to `ingest` is copied, so the
+     * caller still has what they passed.
+     */
+    move: boolean;
+}
+export declare function storeDocument(options: StoreOptions): Promise<StoredDocument>;
+/**
+ * Writes the extraction into the `documents` row the indexer created.
+ *
+ * The full text lives here rather than in the page body, which is what makes a stored PDF
+ * searchable by its own content without turning a 40-page contract into a 40-page Markdown
+ * file.
+ */
+export declare function recordDocument(options: {
+    ctx: AknoContext;
+    relPath: string;
+    extraction: Extraction;
+    summary?: string | null;
+    label?: string | null;
+}): string | null;
+/**
+ * Where a document's provenance is stated in the page itself.
+ *
+ * A reader deciding whether to trust a number should know whether it was typed, read
+ * off a scan, or *described by a model that looked at a picture*. The last is not the
+ * document's own text at all, and presenting the three identically would be a false
+ * claim about where the words came from: cite or stay quiet, applied to files.
+ */
+export declare function provenanceLines(extraction: Extraction): string[];
+//# sourceMappingURL=store.d.ts.map

package/dist/ingest/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/ingest/store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,WAAW,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CA6BlF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE;IACtC,GAAG,EAAE,WAAW,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,GAAG,MAAM,GAAG,IAAI,CA0BhB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,EAAE,CAWhE"}

package/dist/ingest/store.js

@@ -0,0 +1,92 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+export async function storeDocument(options) {
+    const { ctx, source, pageSlug } = options;
+    const extension = path.extname(source).toLowerCase();
+    const sha = await sha256File(source);
+    const relPath = `${pageSlug}-${sha.slice(0, 8)}${extension}`;
+    const target = path.join(ctx.config.aknoPath, relPath);
+    await fsp.mkdir(path.dirname(target), { recursive: true });
+    const stat = await fsp.stat(source);
+    if (options.move) {
+        await fsp.rename(source, target).catch(async (err) => {
+            // A rename across devices fails; an inbox can sit on a different volume.
+            if (err.code !== 'EXDEV')
+                throw err;
+            await fsp.copyFile(source, target);
+            await fsp.rm(source);
+        });
+    }
+    else {
+        await fsp.copyFile(source, target);
+    }
+    return {
+        relPath,
+        sha256: sha,
+        bytes: stat.size,
+        // Binary bytes never go in the journal — `before: null` with the file recorded as
+        // created is enough for undo, which removes it.
+        file: { relPath, action: 'created', before: null, after: null },
+    };
+}
+/**
+ * Writes the extraction into the `documents` row the indexer created.
+ *
+ * The full text lives here rather than in the page body, which is what makes a stored PDF
+ * searchable by its own content without turning a 40-page contract into a 40-page Markdown
+ * file.
+ */
+export function recordDocument(options) {
+    const { ctx, relPath, extraction } = options;
+    ctx.store.db
+        .prepare(`UPDATE documents
+          SET text = ?, summary = ?, page_count = ?, ocr = ?, label = coalesce(?, label),
+              -- The only extraction with a vision client behind it, so this is the one
+              -- writer that can record via = vision, and the one whose provenance the
+              -- indexer must not overwrite with a guess.
+              extract_via = ?, confidence = ?, rendition_sha = NULL
+        WHERE rel_path = ?`)
+        .run(extraction.text.length > 0 ? extraction.text : null, options.summary ?? null, extraction.pageCount, extraction.ocr ? 1 : 0, options.label ?? null, extraction.via, extraction.confidence, relPath);
+    const row = ctx.store.db.prepare('SELECT id FROM documents WHERE rel_path = ?').get(relPath);
+    return row?.id ?? null;
+}
+/**
+ * Where a document's provenance is stated in the page itself.
+ *
+ * A reader deciding whether to trust a number should know whether it was typed, read
+ * off a scan, or *described by a model that looked at a picture*. The last is not the
+ * document's own text at all, and presenting the three identically would be a false
+ * claim about where the words came from: cite or stay quiet, applied to files.
+ */
+export function provenanceLines(extraction) {
+    const out = [];
+    if (extraction.pageCount !== null)
+        out.push(`- Pages: ${extraction.pageCount}`);
+    if (extraction.via === 'ocr') {
+        const confidence = extraction.confidence !== null ? ` (confidence ${extraction.confidence.toFixed(2)})` : '';
+        out.push(`- Text below: recognised by OCR${confidence}`);
+    }
+    else if (extraction.via === 'vision') {
+        out.push("- Text below: a model's description of the image, not text found in it");
+    }
+    return out;
+}
+async function sha256File(absPath) {
+    const { createHash } = await import('node:crypto');
+    const hash = createHash('sha256');
+    const handle = await fsp.open(absPath, 'r');
+    try {
+        const buffer = Buffer.allocUnsafe(64 * 1024);
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                break;
+            hash.update(buffer.subarray(0, bytesRead));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return hash.digest('hex');
+}
+//# sourceMappingURL=store.js.map

package/dist/ingest/store.js.map

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

package/dist/kb/folders.d.ts

@@ -0,0 +1,37 @@
+import type { PageRole, RememberManagement } from '@tenphi/akno-protocol';
+import type { AknoConfig } from '../config/schema.ts';
+import type { Store } from '../store/db.ts';
+export interface FolderCatalogEntry {
+    path: string;
+    role: PageRole;
+    remember: RememberManagement;
+    /** A new Akno-managed page may be created here. */
+    creatable: boolean;
+    /** Explicitly admitted existing pages when the folder itself is read-only. */
+    admittedPages: string[];
+    eligible: boolean;
+    description?: string;
+}
+/**
+ * Physical folders in the knowledge base, including ones that contain no pages.
+ *
+ * Pages cannot represent an empty directory in the index. Structure callers still need to see
+ * directories the user created themselves, both to honour that taxonomy and to avoid inventing a
+ * parallel folder. This walk reads names only: it never opens or indexes the files inside them.
+ */
+export declare function physicalFolders(config: AknoConfig, options?: {
+    under?: string;
+    depth?: number;
+}): string[];
+/** True when the user has already made this folder on disk, even if it is empty. */
+export declare function physicalFolderExists(config: AknoConfig, folder: string): boolean;
+/**
+ * Every visible folder a curator may choose as a page's parent.
+ *
+ * The catalog deliberately combines three sources. The page index supplies folders with content,
+ * the filesystem supplies empty folders the user made by hand, and rules supply declared folders
+ * that have not received their first page yet. Leaving out any one of them teaches a curator to
+ * invent a parallel taxonomy for exactly the folders whose purpose was stated most explicitly.
+ */
+export declare function folderCatalog(config: AknoConfig, store: Store): FolderCatalogEntry[];
+//# sourceMappingURL=folders.d.ts.map

package/dist/kb/folders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folders.d.ts","sourceRoot":"","sources":["../../src/kb/folders.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAI5C,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,mDAAmD;IACnD,SAAS,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/C,MAAM,EAAE,CA6BV;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQhF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,kBAAkB,EAAE,CAuDpF"}

package/dist/kb/folders.js

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { effectiveRule } from "../rules/compile.js";
+import { isReserved } from "../reserved.js";
+/**
+ * Physical folders in the knowledge base, including ones that contain no pages.
+ *
+ * Pages cannot represent an empty directory in the index. Structure callers still need to see
+ * directories the user created themselves, both to honour that taxonomy and to avoid inventing a
+ * parallel folder. This walk reads names only: it never opens or indexes the files inside them.
+ */
+export function physicalFolders(config, options = {}) {
+    const under = (options.under ?? '').replace(/^\/+|\/+$/g, '');
+    const maxDepth = Math.max(1, options.depth ?? 8);
+    const ignored = new Set(config.ignore.map((entry) => entry.replace(/^\/+|\/+$/g, '')));
+    const out = [];
+    walk(under, 0);
+    return out.sort();
+    function walk(relDir, depth) {
+        if (depth >= maxDepth)
+            return;
+        const absDir = path.join(config.aknoPath, relDir);
+        let entries;
+        try {
+            entries = fs.readdirSync(absDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+            if (ignored.has(entry.name) || ignored.has(rel))
+                continue;
+            if (isReserved(rel, config))
+                continue;
+            if (effectiveRule(`${rel}/x`, config.rules).role === 'ignored')
+                continue;
+            out.push(rel);
+            walk(rel, depth + 1);
+        }
+    }
+}
+/** True when the user has already made this folder on disk, even if it is empty. */
+export function physicalFolderExists(config, folder) {
+    if (isReserved(folder, config))
+        return false;
+    if (effectiveRule(`${folder}/x`, config.rules).role === 'ignored')
+        return false;
+    try {
+        return fs.statSync(path.join(config.aknoPath, folder)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Every visible folder a curator may choose as a page's parent.
+ *
+ * The catalog deliberately combines three sources. The page index supplies folders with content,
+ * the filesystem supplies empty folders the user made by hand, and rules supply declared folders
+ * that have not received their first page yet. Leaving out any one of them teaches a curator to
+ * invent a parallel taxonomy for exactly the folders whose purpose was stated most explicitly.
+ */
+export function folderCatalog(config, store) {
+    const paths = new Set(physicalFolders(config, { depth: Number.MAX_SAFE_INTEGER }));
+    const rows = store.db
+        .prepare("SELECT slug, role, frontmatter FROM pages WHERE role != 'ignored' ORDER BY slug")
+        .all();
+    for (const { slug } of rows) {
+        const segments = slug.split('/');
+        for (let depth = 1; depth < segments.length; depth++) {
+            paths.add(segments.slice(0, depth).join('/'));
+        }
+    }
+    for (const rule of config.rules) {
+        const folderPath = rule.glob.replace(/\/\*+$/, '');
+        if (folderPath.length > 0 && !folderPath.includes('*'))
+            paths.add(folderPath);
+    }
+    return [...paths]
+        .filter((folderPath) => {
+        if (isReserved(folderPath, config))
+            return false;
+        return effectiveRule(`${folderPath}/x`, config.rules).role !== 'ignored';
+    })
+        .sort()
+        .map((folderPath) => {
+        const rule = effectiveRule(`${folderPath}/x`, config.rules);
+        const role = rule.role ?? 'knowledge';
+        // A physical folder is taxonomy, not permission to inject facts into every page in it.
+        // `akno folder` writes an explicit value; handwritten rules that omit it stay read-only.
+        const remember = rule.remember ?? 'deny';
+        const creatable = role === 'knowledge' && remember === 'integrate';
+        const admittedPages = creatable
+            ? []
+            : rows
+                .filter((row) => row.role === 'knowledge' &&
+                parentFolder(row.slug) === folderPath &&
+                declaresRememberIntegration(row.frontmatter))
+                .map((row) => row.slug);
+        return {
+            path: folderPath,
+            role,
+            remember,
+            creatable,
+            admittedPages,
+            eligible: creatable || admittedPages.length > 0,
+            ...(rule.description ? { description: rule.description } : {}),
+        };
+    });
+}
+function parentFolder(slug) {
+    return slug.slice(0, slug.lastIndexOf('/'));
+}
+function declaresRememberIntegration(frontmatter) {
+    try {
+        const parsed = JSON.parse(frontmatter);
+        const akno = record(parsed.akno);
+        const management = record(akno.management);
+        return management.remember === 'integrate';
+    }
+    catch {
+        return false;
+    }
+}
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+//# sourceMappingURL=folders.js.map

package/dist/kb/folders.js.map

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

package/dist/kb/frontmatter.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Akno reads several frontmatter keys. Ordinary writes add only `id`; a qualified maintenance
+ * plan may replace one existing top-level scalar through `replaceTopLevelString`. Every other
+ * key is preserved byte for byte and ignored.
+ *
+ * That guarantee is why this module never round-trips through the YAML
+ * serializer on a write. A parse-and-re-emit reflows quotes, reorders nothing
+ * reliably, drops comments, and turns `date: '2026-05-26T00:00:00.000Z'` into an
+ * unquoted timestamp. Instead we keep the raw frontmatter text and splice into
+ * it, so a page Akno touched still diffs as one added line.
+ */
+export interface Frontmatter {
+    /** Parsed values. Empty object when the page has no frontmatter block. */
+    data: Record<string, unknown>;
+    /** The raw YAML between the `---` fences, without the fences. */
+    raw: string;
+    /** Whether a frontmatter block was present at all. */
+    present: boolean;
+    /** Byte offset in the original file where the body begins. */
+    bodyOffset: number;
+    /** 1-based line number of the first body line. Line addressing hangs off this. */
+    bodyLine: number;
+}
+export declare function parseFrontmatter(content: string): Frontmatter;
+/** `tags: [a, b]`, `tags:\n  - a`, and `tags: a` all mean the same thing here. */
+export declare function readTags(data: Record<string, unknown>): string[];
+export declare function readString(data: Record<string, unknown>, key: string): string | null;
+/**
+ * Replace one existing top-level YAML string without serializing any neighboring frontmatter.
+ * The parser supplies the exact scalar byte range, so quoted `#` characters, comments, ordering,
+ * line endings, and unknown keys survive untouched. Missing, duplicate, malformed, nested, or
+ * non-string keys are refused rather than guessed.
+ */
+export declare function replaceTopLevelString(content: string, key: string, value: string): string | null;
+/**
+ * Replace every exact string in one existing nested YAML sequence while preserving all other bytes.
+ * Used for identity references such as `akno.about`; malformed paths, aliases, non-string members,
+ * and absent values are refused rather than round-tripped through a serializer.
+ */
+export declare function replaceNestedStringArrayValue(content: string, keys: string[], from: string, to: string): string | null;
+/**
+ * Splices `id: <value>` into an existing frontmatter block, or creates a
+ * minimal one. Only ever called when `write_ids` is on. Everything else in the
+ * file — including the byte-for-byte frontmatter of keys Akno does not know —
+ * is untouched.
+ */
+export declare function withId(content: string, id: string): string;
+/**
+ * Inserts lines immediately after the opening fence of an existing block, leaving
+ * every other byte alone. Immediately after, because that is where a human scanning
+ * frontmatter expects an identifier or a title to be.
+ *
+ * Splicing rather than parse-and-re-emit for the reason at the top of this file: the
+ * keys already there keep their exact quoting, ordering and comments.
+ */
+export declare function spliceAfterFence(content: string, lines: string[]): string;
+/**
+ * Adds identity aliases without round-tripping the rest of the frontmatter through YAML.
+ *
+ * Merge is allowed to retire one page identity, but the old title and slug must remain
+ * discoverable on the canonical page. Complex inline `akno` mappings are refused: silently
+ * reformatting an owner's unknown keys and comments would make a structural cleanup broader
+ * than the plan says it is.
+ */
+export declare function withAknoAliases(content: string, aliases: string[]): string | null;
+/** A frontmatter block a caller supplied, split from the body it came with. */
+export interface DeclaredFrontmatter {
+    /** The block verbatim, fences and trailing newline included. */
+    head: string;
+    /** Everything after the closing fence. */
+    body: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Reads a frontmatter block off the front of text a *caller* supplied, rather than off a
+ * file on disk.
+ *
+ * This exists because `read` hands back the whole file, frontmatter included. A caller that
+ * read a page, revised it and sent the result back therefore carries a block with it, and
+ * treating that block as body text is how a page grows a second one — the head is preserved,
+ * the block lands underneath it, and nothing that reads frontmatter can see it. Rewriting the
+ * declaration is a legitimate thing for a caller to want: `role`, `management` and `temporal`
+ * live nowhere else in the write API.
+ *
+ * Returns `null` when there is nothing to adopt — no fence, an unterminated fence, or a fence
+ * pair whose contents are not a mapping. That last case is the guard that matters: a body
+ * opening with a `---` horizontal rule and containing another one looks exactly like a
+ * frontmatter block until you try to parse it, and a horizontal rule is not a declaration.
+ */
+export declare function declaredFrontmatter(text: string): DeclaredFrontmatter | null;
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/kb/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../../src/kb/frontmatter.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAoC7D;AAQD,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAUhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGpF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBhG;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,MAAM,GAAG,IAAI,CA0Cf;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAO1D;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAYzE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CA0DjF;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAU5E"}