@namzu/sdk 42.0.2 → 44.0.0

package/dist/store/memory/markdown-format.d.ts

@@ -0,0 +1,88 @@
+/**
+ * One memory as one Markdown file: YAML frontmatter, a blank line, the body.
+ *
+ * ```markdown
+ * ---
+ * name: tests-need-a-built-sdk
+ * description: The CLI's tests import the SDK's dist, so build it first
+ * type: feedback
+ * status: active
+ * createdAt: 2026-09-21T09:30:00.000Z
+ * updatedAt: 2026-09-21T09:30:00.000Z
+ * tags: ["testing"]
+ * id: 0b6c2a4e-…
+ * ---
+ *
+ * Run `pnpm -r build` before `pnpm --filter @namzu/cli test`.
+ *
+ * Why: the CLI resolves `@namzu/sdk` through its package exports.
+ * How to apply: after any SDK change, before trusting a CLI failure.
+ * ```
+ *
+ * **Deliberately not a YAML parser**, for the reason `utils/frontmatter.ts`
+ * gives: a reader that half-understands YAML produces a value that passes
+ * validation and means nothing. That reader cannot be reused here because it
+ * refuses lists and mappings by design, and a memory has tags and metadata.
+ * This one reads exactly three value spellings — a plain scalar, a
+ * double-quoted JSON value (string, array or object; JSON is YAML's flow
+ * syntax), a single-quoted YAML string — and a block list of those under a
+ * key with no value. A value opening with `[` or `{` that is not JSON is read
+ * as the plain string it was written as, so a field that needs a list or an
+ * object refuses it by type and a description like `[WIP] notes` just works.
+ * Everything else is refused with the file and line, as is an unknown or
+ * repeated key: a key this build does not know is a field it
+ * would silently drop on the next write.
+ *
+ * The writer only emits what the reader reads, so every file this store
+ * writes parses back to the same record, body byte for byte.
+ */
+import type { MemoryStatus, MemoryType } from '../../types/memory/index.js';
+/** Keys this build reads and writes, in the order it writes them. */
+export declare const MEMORY_FRONTMATTER_KEYS: readonly ["name", "description", "type", "status", "createdAt", "updatedAt", "tags", "id", "title", "summary", "format", "metadata", "schemaVersion"];
+export type MemoryFrontmatterKey = (typeof MEMORY_FRONTMATTER_KEYS)[number];
+export type FrontmatterScalar = string | number | boolean | null;
+export type FrontmatterJson = FrontmatterScalar | readonly FrontmatterJson[] | {
+    readonly [key: string]: FrontmatterJson;
+};
+export interface ParsedMemoryFile {
+    /** Plain scalars arrive as strings; the caller decides what each key's string means. */
+    readonly values: ReadonlyMap<MemoryFrontmatterKey, FrontmatterJson>;
+    readonly body: string;
+}
+export declare class MemoryFileFormatError extends Error {
+    readonly file: string;
+    readonly reason: string;
+    readonly line?: number | undefined;
+    constructor(file: string, reason: string, line?: number | undefined);
+}
+/**
+ * Split a memory file into frontmatter values and body.
+ *
+ * The body is everything after the closing fence, less ONE leading newline
+ * (the blank line the writer puts there) and ONE trailing newline, `\n` or
+ * `\r\n` (the one the writer adds; it writes `\r\n` after a body ending in
+ * `\r`). Removing exactly one of each, not trimming, is what makes a body
+ * that itself begins or ends with blank lines, or with a `\r`, round-trip.
+ */
+export declare function parseMemoryFile(raw: string, file: string): ParsedMemoryFile;
+export interface MemoryFileFields {
+    readonly name: string;
+    readonly description: string;
+    readonly type: MemoryType;
+    readonly status: MemoryStatus;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly tags: readonly string[];
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly format: 'text' | 'markdown' | 'json';
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * The file for one memory. Fields that repeat another are left out — a title
+ * equal to the name, a summary equal to the description, the default format —
+ * so an ordinary file carries the reference shape and nothing else.
+ */
+export declare function formatMemoryFile(fields: MemoryFileFields, body: string): string;
+//# sourceMappingURL=markdown-format.d.ts.map

package/dist/store/memory/markdown-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-format.d.ts","sourceRoot":"","sources":["../../../src/store/memory/markdown-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAE3E,qEAAqE;AACrE,eAAO,MAAM,uBAAuB,uJAc1B,CAAA;AAEV,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3E,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;AAChE,MAAM,MAAM,eAAe,GACxB,iBAAiB,GACjB,SAAS,eAAe,EAAE,GAC1B;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAAA;CAAE,CAAA;AAE9C,MAAM,WAAW,gBAAgB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,oBAAoB,EAAE,eAAe,CAAC,CAAA;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACrB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;gBAFb,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,MAAM,YAAA;CAKvB;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAgF3E;AAsBD,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAA;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAsB/E"}

package/dist/store/memory/markdown-format.js

@@ -0,0 +1,222 @@
+/**
+ * One memory as one Markdown file: YAML frontmatter, a blank line, the body.
+ *
+ * ```markdown
+ * ---
+ * name: tests-need-a-built-sdk
+ * description: The CLI's tests import the SDK's dist, so build it first
+ * type: feedback
+ * status: active
+ * createdAt: 2026-09-21T09:30:00.000Z
+ * updatedAt: 2026-09-21T09:30:00.000Z
+ * tags: ["testing"]
+ * id: 0b6c2a4e-…
+ * ---
+ *
+ * Run `pnpm -r build` before `pnpm --filter @namzu/cli test`.
+ *
+ * Why: the CLI resolves `@namzu/sdk` through its package exports.
+ * How to apply: after any SDK change, before trusting a CLI failure.
+ * ```
+ *
+ * **Deliberately not a YAML parser**, for the reason `utils/frontmatter.ts`
+ * gives: a reader that half-understands YAML produces a value that passes
+ * validation and means nothing. That reader cannot be reused here because it
+ * refuses lists and mappings by design, and a memory has tags and metadata.
+ * This one reads exactly three value spellings — a plain scalar, a
+ * double-quoted JSON value (string, array or object; JSON is YAML's flow
+ * syntax), a single-quoted YAML string — and a block list of those under a
+ * key with no value. A value opening with `[` or `{` that is not JSON is read
+ * as the plain string it was written as, so a field that needs a list or an
+ * object refuses it by type and a description like `[WIP] notes` just works.
+ * Everything else is refused with the file and line, as is an unknown or
+ * repeated key: a key this build does not know is a field it
+ * would silently drop on the next write.
+ *
+ * The writer only emits what the reader reads, so every file this store
+ * writes parses back to the same record, body byte for byte.
+ */
+/** Keys this build reads and writes, in the order it writes them. */
+export const MEMORY_FRONTMATTER_KEYS = [
+    'name',
+    'description',
+    'type',
+    'status',
+    'createdAt',
+    'updatedAt',
+    'tags',
+    'id',
+    'title',
+    'summary',
+    'format',
+    'metadata',
+    'schemaVersion',
+];
+export class MemoryFileFormatError extends Error {
+    file;
+    reason;
+    line;
+    constructor(file, reason, line) {
+        super(`${file}${line === undefined ? '' : `:${line}`}: ${reason}`);
+        this.file = file;
+        this.reason = reason;
+        this.line = line;
+        this.name = 'MemoryFileFormatError';
+    }
+}
+const KEYS = new Set(MEMORY_FRONTMATTER_KEYS);
+const FENCE = /^---[ \t]*$/;
+const KEY_LINE = /^([A-Za-z][A-Za-z0-9_]*):(?:[ \t]+(.*))?$/;
+const ITEM_LINE = /^[ \t]+-(?:[ \t]+(.*))?$/;
+function parseValue(raw, file, line) {
+    const value = raw.trim();
+    if (value.startsWith('"') || value.startsWith('[') || value.startsWith('{')) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            // `description: [WIP] deploy notes` is a plain string to the person
+            // who wrote it. A `[` or `{` value that is not JSON is read as that
+            // string; a field that needs a list or an object (tags, metadata)
+            // still refuses it by type. An unterminated `"` has no such reading.
+            if (!value.startsWith('"'))
+                return value;
+            throw new MemoryFileFormatError(file, 'a value starting with " must be a valid JSON string', line);
+        }
+    }
+    if (value.startsWith("'")) {
+        if (value.length < 2 || !value.endsWith("'") || /(^|[^'])'(?!')/.test(value.slice(1, -1))) {
+            throw new MemoryFileFormatError(file, 'an unterminated single-quoted string', line);
+        }
+        return value.slice(1, -1).replace(/''/g, "'");
+    }
+    if (/^[>|][-+]?$/.test(value) || value.startsWith('&') || value.startsWith('*')) {
+        throw new MemoryFileFormatError(file, 'block scalars, anchors and aliases are not supported; write a single-line value', line);
+    }
+    return value;
+}
+/**
+ * Split a memory file into frontmatter values and body.
+ *
+ * The body is everything after the closing fence, less ONE leading newline
+ * (the blank line the writer puts there) and ONE trailing newline, `\n` or
+ * `\r\n` (the one the writer adds; it writes `\r\n` after a body ending in
+ * `\r`). Removing exactly one of each, not trimming, is what makes a body
+ * that itself begins or ends with blank lines, or with a `\r`, round-trip.
+ */
+export function parseMemoryFile(raw, file) {
+    const text = raw.startsWith('\uFEFF') ? raw.slice(1) : raw;
+    const lines = text.split('\n');
+    if (!FENCE.test((lines[0] ?? '').replace(/\r$/, ''))) {
+        throw new MemoryFileFormatError(file, 'a memory file must start with a --- frontmatter fence', 1);
+    }
+    let closing = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (FENCE.test((lines[i] ?? '').replace(/\r$/, ''))) {
+            closing = i;
+            break;
+        }
+    }
+    if (closing < 0)
+        throw new MemoryFileFormatError(file, 'the frontmatter is never closed');
+    const values = new Map();
+    let listKey;
+    let list;
+    // A key with no value holds the empty string until a list item under it
+    // makes it a list, which a caller then validates like any other value.
+    const closeList = () => {
+        if (listKey && list && list.length > 0)
+            values.set(listKey, list);
+        listKey = undefined;
+        list = undefined;
+    };
+    for (let i = 1; i < closing; i++) {
+        const lineNumber = i + 1;
+        const line = (lines[i] ?? '').replace(/\r$/, '');
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        const item = ITEM_LINE.exec(line);
+        if (item) {
+            if (!list) {
+                throw new MemoryFileFormatError(file, 'a list item must follow a key with no value', lineNumber);
+            }
+            list.push(parseValue(item[1] ?? '', file, lineNumber));
+            continue;
+        }
+        const pair = KEY_LINE.exec(line);
+        if (!pair) {
+            throw new MemoryFileFormatError(file, 'expected "key: value" at the start of the line', lineNumber);
+        }
+        closeList();
+        const key = pair[1] ?? '';
+        if (!KEYS.has(key)) {
+            throw new MemoryFileFormatError(file, `unknown key "${key}"; this build reads ${MEMORY_FRONTMATTER_KEYS.join(', ')}`, lineNumber);
+        }
+        const typedKey = key;
+        if (values.has(typedKey)) {
+            throw new MemoryFileFormatError(file, `"${key}" appears twice`, lineNumber);
+        }
+        const rawValue = pair[2]?.trim() ?? '';
+        if (rawValue === '') {
+            listKey = typedKey;
+            list = [];
+            values.set(typedKey, '');
+            continue;
+        }
+        values.set(typedKey, parseValue(rawValue, file, lineNumber));
+    }
+    closeList();
+    let body = lines.slice(closing + 1).join('\n');
+    body = body.replace(/^\r?\n/, '').replace(/\r?\n$/, '');
+    return { values, body };
+}
+const RESERVED_PLAIN = /^(?:true|false|null|yes|no|on|off|~|[-+]?(?:\d[\d_]*)?\.?\d.*)$/i;
+/** A string the reader gets back unchanged without quotes, and YAML reads as the same string. */
+function isPlainSafe(value) {
+    return (value.length > 0 &&
+        value === value.trim() &&
+        !/^[-?:,[\]{}#&*!|>'"%@`]/.test(value) &&
+        !/: |\s#|:$/.test(value) &&
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: refusing control characters is the point
+        !/[\u0000-\u001f\u007f]/.test(value) &&
+        !RESERVED_PLAIN.test(value));
+}
+function formatValue(value) {
+    if (typeof value === 'string')
+        return isPlainSafe(value) ? value : JSON.stringify(value);
+    return JSON.stringify(value);
+}
+/**
+ * The file for one memory. Fields that repeat another are left out — a title
+ * equal to the name, a summary equal to the description, the default format —
+ * so an ordinary file carries the reference shape and nothing else.
+ */
+export function formatMemoryFile(fields, body) {
+    const lines = ['---'];
+    const put = (key, value) => {
+        lines.push(`${key}: ${formatValue(value)}`);
+    };
+    put('name', fields.name);
+    put('description', fields.description);
+    put('type', fields.type);
+    put('status', fields.status);
+    put('createdAt', new Date(fields.createdAt).toISOString());
+    put('updatedAt', new Date(fields.updatedAt).toISOString());
+    if (fields.tags.length > 0)
+        lines.push(`tags: ${JSON.stringify(fields.tags)}`);
+    put('id', fields.id);
+    if (fields.title !== fields.name)
+        put('title', fields.title);
+    if (fields.summary !== fields.description)
+        put('summary', fields.summary);
+    if (fields.format !== 'markdown')
+        put('format', fields.format);
+    if (fields.metadata !== undefined)
+        lines.push(`metadata: ${JSON.stringify(fields.metadata)}`);
+    lines.push('---', '', body);
+    // The reader removes one trailing `\n` or `\r\n`, the second so a
+    // hand-written CRLF file reads cleanly. A body that itself ends in `\r`
+    // would lose it to that `\r\n`, so it is closed with one of its own.
+    return `${lines.join('\n')}${body.endsWith('\r') ? '\r\n' : '\n'}`;
+}
+//# sourceMappingURL=markdown-format.js.map

package/dist/store/memory/markdown-format.js.map

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

package/dist/store/memory/markdown.d.ts

@@ -0,0 +1,109 @@
+import type { MemoryId } from '../../types/ids/index.js';
+import type { CreateMemoryParams, MemoryContent, MemoryIndexEntry, MemoryRecord, MemorySearchParams, MemorySearchResult, MemoryStore, MemoryType, UpdateMemoryParams } from '../../types/memory/index.js';
+import { type Logger } from '../../utils/logger.js';
+import { type RenderedMemoryIndex } from './index-file.js';
+/** The generated index. Never a memory, never read back as one. */
+export declare const MEMORY_INDEX_FILE = "MEMORY.md";
+/** Largest memory file this store will read. A memory is a paragraph, not a document. */
+export declare const MEMORY_FILE_MAX_BYTES: number;
+export interface MarkdownMemoryStoreConfig {
+    /**
+     * The exact directory holding one `<name>.md` per memory and the generated
+     * `MEMORY.md`. Created private (0700) when absent. The host owns isolation:
+     * bind it to the project or tenant the memories belong to.
+     */
+    readonly directory: string;
+    readonly logger?: Logger;
+    /** Maximum wait for another process's operation; default 10 seconds. Never breaks stale locks. */
+    readonly lockTimeoutMs?: number;
+}
+/** What {@link MarkdownMemoryStore.importRecord} did with one record. */
+export type MemoryImportOutcome = 'imported' | 'present';
+/**
+ * One Markdown file per memory, in a directory the operator can read, grep
+ * and edit by hand, with a generated `MEMORY.md` index beside them.
+ *
+ * Implements the same {@link MemoryStore} contract as `DiskMemoryStore` and
+ * keeps its guarantees: every operation — reads included — runs under the
+ * directory's exclusive operation lock and reloads what is on disk, so no
+ * process acts on another's stale snapshot; writes are atomic renames of
+ * private (0600) files; a file that does not parse, a name that does not match
+ * its file, a symlink, two files claiming one id with the same `updatedAt`, or
+ * a record stamped by a newer build is refused with the file named, never
+ * skipped. Two files claiming one id are what an interrupted rename leaves
+ * when both state their own, different `updatedAt`, or when one is a
+ * hand-written file with neither an `id` nor an `updatedAt` — its id derived
+ * from its name, its time its mtime — and the other states that id and a
+ * different `updatedAt`: only a rename of the hand-written file writes its
+ * derived id under another name. The newer is read, and the next write moves
+ * the older aside to `<name>.md.superseded`. Any other pair — an undated file
+ * that states its id, or equal times — is refused like a copy. Content the loader
+ * would refuse — a NUL character in the body, title, summary, description or
+ * tags, a file over {@link MEMORY_FILE_MAX_BYTES} — is refused with
+ * {@link MemoryContentRejectedError} before it is written. A store that
+ * quietly dropped the one file it could not read would present the model an
+ * incomplete memory as a complete one.
+ *
+ * Names are unique. {@link create} refuses an explicit name another memory
+ * holds with {@link MemoryNameConflictError}, and derives a free one from the
+ * title when none is given.
+ */
+export declare class MarkdownMemoryStore implements MemoryStore {
+    private readonly directory;
+    private readonly log;
+    private readonly lockTimeoutMs;
+    private canonical?;
+    constructor(config: MarkdownMemoryStoreConfig);
+    /** The directory this store reads and writes, as configured. */
+    get path(): string;
+    private location;
+    private memoryPath;
+    private load;
+    private withLoaded;
+    /** {@link withLoaded} for an operation that writes. */
+    private mutate;
+    private setAside;
+    private writeMemory;
+    /** Rewrite `MEMORY.md` from `records` when its text would change. */
+    private writeIndex;
+    private entries;
+    /** Every loaded record, with `changed` put in place of (or beside) its id's. */
+    private records;
+    create(params: CreateMemoryParams): Promise<{
+        entry: MemoryIndexEntry;
+        content: MemoryContent;
+    }>;
+    get(id: MemoryId): Promise<MemoryContent | undefined>;
+    getRecord(id: MemoryId): Promise<MemoryRecord | undefined>;
+    /** The current record held under `name`, archived included, or `undefined`. */
+    getByName(name: string): Promise<MemoryRecord | undefined>;
+    update(id: MemoryId, updates: UpdateMemoryParams): Promise<MemoryIndexEntry | undefined>;
+    delete(id: MemoryId): Promise<boolean>;
+    list(params?: MemorySearchParams): Promise<MemorySearchResult>;
+    /**
+     * The index a prompt carries: one line per active memory someone chose to
+     * keep — never a record the runtime derived from a turn — operator
+     * `feedback` and `user` memories first, capped at `maxLines` (default 200)
+     * with a note pointing to search for the rest. Rendered from the memory
+     * files under the lock, so it is current even when a file was edited by
+     * hand since the last write. See {@link renderMemoryIndex}. `derived: true`
+     * lists the records the runtime derived instead, newest first — for an
+     * operator's inspection, never for a prompt.
+     */
+    readIndex(options?: {
+        readonly maxLines?: number;
+        readonly derived?: boolean;
+    }): Promise<RenderedMemoryIndex>;
+    /**
+     * Bring in a record from another store, keeping its id, timestamps,
+     * status and metadata. Idempotent by id: a record already here is left
+     * alone and reported `present`, so a migration interrupted halfway can
+     * simply run again. A name another memory holds is suffixed rather than
+     * refused, because an import that stopped on a clash would strand the
+     * records after it.
+     */
+    importRecord(record: MemoryRecord, defaults?: {
+        readonly type?: MemoryType;
+    }): Promise<MemoryImportOutcome>;
+}
+//# sourceMappingURL=markdown.d.ts.map

package/dist/store/memory/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../../src/store/memory/markdown.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAA;AACxD,OAAO,KAAK,EACX,kBAAkB,EAClB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,MAAM,6BAA6B,CAAA;AAKpC,OAAO,EAAE,KAAK,MAAM,EAAiB,MAAM,uBAAuB,CAAA;AAElE,OAAO,EAEN,KAAK,mBAAmB,EAExB,MAAM,iBAAiB,CAAA;AAsCxB,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,cAAc,CAAA;AAC5C,yFAAyF;AACzF,eAAO,MAAM,qBAAqB,QAAa,CAAA;AAI/C,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,kGAAkG;IAClG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,SAAS,CAAA;AAwLxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,SAAS,CAAC,CAAQ;gBAEd,MAAM,EAAE,yBAAyB;IAS7C,gEAAgE;IAChE,IAAI,IAAI,IAAI,MAAM,CAEjB;YAEa,QAAQ;IAOtB,OAAO,CAAC,UAAU;YAOJ,IAAI;YA6EJ,UAAU;IAoBxB,uDAAuD;IACvD,OAAO,CAAC,MAAM;YAOA,QAAQ;YAWR,WAAW;IA+CzB,qEAAqE;YACvD,UAAU;IAUxB,OAAO,CAAC,OAAO;IAIf,gFAAgF;IAChF,OAAO,CAAC,OAAO;IAWT,MAAM,CACX,MAAM,EAAE,kBAAkB,GACxB,OAAO,CAAC;QAAE,KAAK,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,aAAa,CAAA;KAAE,CAAC;IAsDzD,GAAG,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAIrD,SAAS,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAOhE,+EAA+E;IACzE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC;IAc1D,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IA0CxF,MAAM,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAkBtC,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAYpE;;;;;;;;;OASG;IACG,SAAS,CACd,OAAO,GAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GACtE,OAAO,CAAC,mBAAmB,CAAC;IAI/B;;;;;;;OAOG;IACG,YAAY,CACjB,MAAM,EAAE,YAAY,EACpB,QAAQ,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAO,GAC3C,OAAO,CAAC,mBAAmB,CAAC;CAqC/B"}