@substrat-run/kernel 0.139.0 → 0.140.0

package/dist/migration-digest.js

@@ -0,0 +1,237 @@
+import { substratError, tokenizeSql } from '@substrat-run/contracts';
+import { moduleMigrations } from './module-migrations.js';
+import { assertNoSpineReference, assertNoSpineWrite } from './spine-guard.js';
+import { attachmentSha256 } from './scope-host.js';
+/**
+ * What a scope's migration journal records beside each version, and the check that reads it
+ * (#2066). Shared by both adapters, so the rule and the sentence an operator reads are one.
+ *
+ * A scope used to record an applied migration by `(module_id, version)` alone, so a later
+ * `0025` whose SQL differed from the `0025` it ran was skipped as already applied: a dev
+ * database that ran one branch's `0025` and then `main`'s, or a preview that ran an unmerged
+ * branch, kept whichever schema it got first, and the first sign was a query failing against
+ * a column that was not there. `_substrat_migrations.sql_digest` closes that.
+ *
+ * - **The digest is SHA-256 over the exact SQL text**, lowercase hex, with no normalisation:
+ *   not whitespace, not comments, not line endings. Any change is a different migration. A
+ *   shipped migration's text never changes on `main` (`lint:migrations --check` refuses the
+ *   edit upstream), so a difference at a scope means the scope ran something else.
+ * - **Only a module's AUTHORED migrations are held to it.** The kernel-derived DDL
+ *   (`search/…`, `state/…`, `list/…`, see `moduleMigrations`) is versioned by its
+ *   declaration on purpose: the version names what decides the DDL, so the kernel may change
+ *   how it spells the same declaration between releases. Holding those rows to a digest would
+ *   fail every scope with a searchable entity closed on the kernel upgrade that respelled a
+ *   trigger. Their digest is still recorded, as the fact of what ran.
+ * - **A row applied before the column carries `'legacy'`, and is accepted.** Nobody measured
+ *   what it ran, so it gets no digest: backfilling the registered one would write a value
+ *   nobody measured, and bless the one row this exists to catch if that scope did run
+ *   something else. The mark is explicit rather than a NULL, because a NULL cannot say where it
+ *   came from: the rows present when the column arrives are marked (`MIGRATION_DIGEST_MARK_LEGACY`),
+ *   a dump taken before the column restores as `'legacy'` (the restore derives it), and from
+ *   then on the fence below refuses a NULL however it is written. So `'legacy'` is provenance,
+ *   and a NULL — say a dump edited to clear a digest — is refused rather than trusted. Such a
+ *   row is unprotected for good, which is the price of not lying in the journal.
+ */
+export function migrationDigest(sql) {
+    return attachmentSha256(new TextEncoder().encode(sql));
+}
+/** What a journal row applied before digests were recorded carries in `sql_digest` (#2066). */
+export const MIGRATION_DIGEST_LEGACY = 'legacy';
+/**
+ * Marks the rows present when the column arrived. Run right after the column's ALTER on every
+ * wake: once the fence is in place it can only ever find those rows, since nothing else can
+ * leave a NULL. Literal text, like the fence, so `lint:spine-ddl` and a reviewer read one spelling.
+ */
+export const MIGRATION_DIGEST_MARK_LEGACY = "UPDATE _substrat_migrations SET sql_digest = 'legacy' WHERE sql_digest IS NULL";
+/**
+ * The fence: no journal row is written, or rewritten, without a digest or the legacy mark — in
+ * both adapters' KERNEL_DDL, after the journal table, so `lint:spine-ddl` holds it like any
+ * spine trigger.
+ *
+ * Without it an older writer (an instance still on the previous release during a rollout or a
+ * rollback, or a second process over the same SQLite file) inserts a row that omits the
+ * column, and SQLite records NULL. With it that INSERT aborts, so the older writer's migration
+ * fails and its scope fails closed until code that records the digest serves it, which then
+ * applies the migration properly. KERNEL_DDL runs before the column is ALTERed onto a legacy
+ * journal, and on a table without the column the INSERT trigger makes any INSERT fail with
+ * `no such column`: there is no window in which a NULL can be written. A restore loads its
+ * rows under the fence too, so a dump that carries a NULL is refused (`spineRowsInsert` gives a
+ * dump from before the column the legacy mark instead).
+ *
+ * Migration SQL cannot drop it: `assertNoJournalSql` refuses any migration naming the journal.
+ * Literal text, no interpolation: `lint:spine-ddl` inlines a kernel fragment one level deep.
+ */
+export const MIGRATION_DIGEST_FENCE_DDL = `
+  CREATE TRIGGER IF NOT EXISTS _substrat_migrations_digest_required
+  BEFORE INSERT ON _substrat_migrations WHEN NEW.sql_digest IS NULL
+  BEGIN
+    SELECT RAISE(ABORT, 'a migration journal row must carry its sql_digest (#2066)');
+  END;
+  CREATE TRIGGER IF NOT EXISTS _substrat_migrations_digest_kept
+  BEFORE UPDATE OF sql_digest ON _substrat_migrations WHEN NEW.sql_digest IS NULL
+  BEGIN
+    SELECT RAISE(ABORT, 'a migration journal row must carry its sql_digest (#2066)');
+  END;
+`;
+/**
+ * Refuse migration SQL that names the migration journal (`_substrat_migration…`: the table, its
+ * fence, the DO's bookmarks), in any spelling the grammar allows — quoted, any case, schema-
+ * qualified — before any of it runs.
+ *
+ * A migration runs on the kernel's own handle, not `ctx.sql`, so the spine write guard never
+ * sees it, and an authored migration that repairs `_substrat_tuples` is a reviewed, linted path
+ * (`boundary-lint-allow R4 migration`). The journal is different: a migration that drops the
+ * fence, or writes its own journal rows, makes the digest check say whatever it wrote. Nothing
+ * legitimate in a module's migration names it, reads included.
+ */
+export function assertNoJournalSql(sql, what) {
+    for (const token of tokenizeSql(sql)) {
+        if (!token.text.split('.').some((part) => part.toLowerCase().startsWith('_substrat_migration')))
+            continue;
+        throw substratError('forbidden', `${what} cannot name the migration journal ('${token.text}'): the journal and its digest fence are the kernel's (#2066)`, { reason: 'spine_write' });
+    }
+}
+/**
+ * The authored migrations allowed to write the spine: four shipped ticket0 repairs of its own
+ * `_substrat_tuples` edges and its hand-recreated derived list indexes, each reviewed under
+ * `boundary-lint-allow R4 migration`. Keyed by module, version AND the digest of the exact text,
+ * so only those texts pass: a new migration, or any edit to one of these, gets the full guard.
+ * Shipped migrations are append-only, so this list only ever shrinks — a new spine repair goes
+ * through the platform, not a migration.
+ */
+const REVIEWED_SPINE_MIGRATIONS = new Set([
+    '@substrat-run/demo-ticket0@0020#d29122b68f3cc5d07a70fb87874085e0e6805e2e19612984160488c59789d75c',
+    '@substrat-run/demo-ticket0@0022#9de9088207fa914e9eb8c8344924708655cbecb11e5b64f76e1d2ec7d0bd0ea2',
+    '@substrat-run/demo-ticket0@0024#ba60103ae91108bfce21fd5b24818cec18aefe4ee3b03b49ca8013fd2634aae3',
+    '@substrat-run/demo-ticket0@0026#da0bb4e3c8b13f5febd8b2202e7267c30e9ee91a19d202181b99ccdeb71ec3a4',
+]);
+/**
+ * Refuse a migration's SQL before any of it runs, if it reaches where a migration must not.
+ *
+ * A migration runs on the kernel's own handle, not `ctx.sql`, so `ctx.sql`'s guard never sees it.
+ * Every migration is held to: no foreign key to the spine (#1898), and nothing that names the
+ * journal (`assertNoJournalSql`). An AUTHORED one is also held to the full spine write guard —
+ * no write, DDL or same-named TEMP object on any `_substrat_*` table — unless it is one of the
+ * exact reviewed texts above. Kernel-derived DDL is exempt from that last rule: creating
+ * `_substrat_*` indexes and triggers is what it is for.
+ */
+export function assertMigrationSql(sql, step) {
+    const what = `migration ${step.key}`;
+    assertNoSpineReference(sql, what);
+    assertNoJournalSql(sql, what);
+    if (!step.authored || REVIEWED_SPINE_MIGRATIONS.has(`${step.key}#${step.digest}`))
+        return;
+    try {
+        assertNoSpineWrite(sql);
+    }
+    catch (err) {
+        throw substratError('forbidden', `${what} cannot write the platform spine: ${err.message.replace(/^ctx\.sql cannot write the platform spine: /, '')}`, {
+            reason: 'spine_write',
+        });
+    }
+}
+/**
+ * Refuse a dump whose journal is not consistent with its own shape (#2066 r3): a table whose
+ * recorded DDL declares `sql_digest` while its columns omit it, or the other way round.
+ *
+ * A dump exported before digests were recorded restores as `'legacy'` (`spineRowsInsert`), so
+ * the shape of the journal is what says which kind of dump this is — and a current dump with
+ * the column stripped would otherwise pass as legacy and unprotect every row. The dump's DDL is
+ * `sqlite_master`'s text, which an ALTER rewrites, so a real pre-#2066 journal carries neither.
+ * Nothing else a dump carries changed with #2066 to cross-check against (the fence is a trigger,
+ * and a dump holds tables). A dump is freely editable data: a consistent edit of both is not
+ * detectable, and restore is privileged, audited staff work that could forge any digest anyway.
+ * This catches corruption and partial edits, not an author set on lying.
+ */
+export function assertJournalDumpCoherent(tables) {
+    for (const t of tables) {
+        if (t.name.toLowerCase() !== '_substrat_migrations')
+            continue;
+        const declared = tokenizeSql(t.ddl).some((tok) => tok.text.toLowerCase() === 'sql_digest');
+        const carried = t.columns.some((c) => c.toLowerCase() === 'sql_digest');
+        if (declared === carried)
+            continue;
+        throw substratError('validation_failed', `restore refused: the dump's _substrat_migrations ${declared ? 'declares sql_digest in its DDL but carries no such column' : 'carries sql_digest but its DDL does not declare it'} — ` +
+            `it is neither a dump from before digests were recorded nor a whole one from after. Nothing was changed (#2066).`);
+    }
+}
+/**
+ * Digests by SQL text. Keyed on the content, not on the registration object: a registration
+ * mutated or rebuilt with other SQL under the same version gets that SQL's digest, never a
+ * stale one. Bounded by the distinct migration texts the isolate has registered.
+ */
+const digestOf = new Map();
+const cachedDigest = (sql) => {
+    let digest = digestOf.get(sql);
+    if (!digest)
+        digestOf.set(sql, (digest = migrationDigest(sql)));
+    return digest;
+};
+/**
+ * A module's migrations in the order the host applies them (`moduleMigrations`), each with its
+ * digest and whether it is authored — read from the registration as it is now. The digest of a
+ * text is computed once per isolate, so a Durable Object that wakes with the same code hashes
+ * nothing again.
+ */
+export function migrationSteps(registration) {
+    const authored = new Set((registration.migrations ?? []).map((m) => m.version));
+    return Promise.all(moduleMigrations(registration).map(async (migration) => ({
+        migration,
+        digest: await cachedDigest(migration.sql),
+        authored: authored.has(migration.version),
+    })));
+}
+/**
+ * Plan a scope's migration pass against its journal (`module@version` → recorded digest): the
+ * registered steps it has not applied, or the first applied one whose SQL differs, which fails
+ * the scope closed before anything else runs. Both adapters plan through this.
+ */
+export async function planMigrations(modules, applied) {
+    const pending = [];
+    for (const mod of modules) {
+        for (const step of await mod.steps) {
+            const key = `${mod.id}@${step.migration.version}`;
+            if (!applied.has(key)) {
+                pending.push({ moduleId: mod.id, ...step });
+                continue;
+            }
+            const error = migrationDivergence(applied.get(key), step.digest, step.authored);
+            if (error)
+                return { pending: [], diverged: { version: key, error } };
+        }
+    }
+    return { pending };
+}
+/** The error a scope fails closed with when `module@version` cannot be applied or trusted. */
+export function migrationFailedError(key, cause) {
+    return new Error(`migration failed for ${key} — scope fails closed: ${cause}`);
+}
+/**
+ * Why a registered migration the scope has already applied cannot be trusted, or null when it
+ * can: on an authored migration, a recorded digest that differs from the registered one, or
+ * no digest and no legacy mark at all.
+ *
+ * The caller fails the scope closed with this as the cause, the way a migration that threw
+ * does — the same `migration failed for <module>@<version> — scope fails closed:` record, so
+ * the directory, the sweep and the dashboard read it with nothing new. The scope recovers
+ * when its journal and its schema agree with the deployment again: a scope that ran another
+ * branch's migration is rebuilt (a dev database, a preview) or restored to a dump taken before
+ * it ran; a deployment carrying the wrong SQL is redeployed with the SQL the scope ran. A
+ * migration is never edited or renumbered once a scope has it, so re-numbering is not a
+ * recovery: the scope would still hold the other SQL under this version.
+ */
+export function migrationDivergence(recorded, registered, authored) {
+    if (!authored || recorded === undefined || recorded === registered || recorded === MIGRATION_DIGEST_LEGACY)
+        return null;
+    if (recorded === null) {
+        // The fence makes this unreachable through the kernel; a row that has it anyway was not
+        // written by the kernel, and says nothing about what ran.
+        return (`this scope's journal records neither a digest nor the legacy mark for this version, so ` +
+            `what it ran is unknown (registered sha256 ${registered}). Rebuild the scope, or restore it ` +
+            `to a dump the kernel wrote (#2066)`);
+    }
+    return (`this scope applied different SQL under this version (applied sha256 ${recorded}, ` +
+        `registered sha256 ${registered}). Rebuild the scope, or restore it to a dump taken before ` +
+        `it ran the other SQL; a migration is never edited or renumbered once a scope has applied it (#2066)`);
+}
+//# sourceMappingURL=migration-digest.js.map

package/dist/migration-digest.js.map

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

package/dist/module-erasure.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Subject erasure inside a module's OWN tables (#2068) — the half of open question 17 that
+ * K-37 left named and unbuilt.
+ *
+ * `shredSubject` redacts the spine and destroys the key that seals the platform's copies. A
+ * module's rows were outside that, and §13.1 said so (limit 2). This file brings them in, two
+ * ways, both run by the kernel in the SAME transaction as the spine redaction and before the
+ * key is destroyed:
+ *
+ * - **Declared.** An entity names its subject columns beside its `erasable` fields
+ *   (`erasure: { subjects }`, `subject-erasure.ts` in contracts), and the kernel blanks those
+ *   fields — or deletes the row — wherever a subject column equals the id. No module code
+ *   runs, so a vertical gets the right behaviour by declaring, and a declaration cannot forget
+ *   a column the way a hand-written UPDATE can.
+ * - **A hook.** `onSubjectErased(ctx, { subjectId })` on the registration, for a link the row
+ *   does not hold itself (a rating reached through its conversation). It is narrow on purpose:
+ *   a `sql` that reaches the module's own tables and nothing else, and `now()`. No emit — an
+ *   event about the erasure would be a new immutable copy of what is being erased — no
+ *   check, grant, link or platform request, and no await: it is synchronous, so it runs inside
+ *   the erasure's one transaction and nothing interleaves with it.
+ *
+ * **Failure is all or nothing.** A hook that throws rolls the whole scope-side unit back, the
+ * spine redaction with it, and the erasure throws before the key is touched or a receipt is
+ * written. Nothing claims an erasure that did not happen, and a re-run converges: a declared
+ * blank skips rows already blank, and a hook is idempotent by contract.
+ *
+ * **Derived stores.** A search index over an erased column is kept in step by its own triggers,
+ * but FTS5 keeps a deleted row's terms in older index segments until they merge — the words
+ * are still in the database file, findable by anyone reading the shadow tables. So the erasure
+ * runs with FTS5's `secure-delete` on for the indexes over the erasing modules' tables, which
+ * removes each entry where it sits rather than recording its deletion. A list index is an ordinary b-tree and loses the old value with the
+ * UPDATE. What neither reaches — free pages SQLite has not reused, and attachment text — is
+ * written down in kernel-design.md §13.1 rather than implied.
+ */
+import { type ErasedEntityCount, type ErasureHookCount, type SubjectErasureDeclaration, type UnreachedEntity } from '@substrat-run/contracts';
+import type { ModuleRegistration, ScopedSql } from './scope-host.js';
+import type { SearchIndexPlan } from './search-index.js';
+/** What a module's `onSubjectErased` hook is handed — and all it is handed. */
+export interface SubjectErasureContext {
+    /**
+     * The module's own tables, and only those — the ones its migrations create: a statement
+     * naming any other table in the scope (another module's, a view, a TEMP object, the spine)
+     * is refused before it runs, reads included. Only `SELECT`, `UPDATE`, `DELETE`, `INSERT` and
+     * `REPLACE`; no `WITH`, no DDL, no `PRAGMA`. Revoked when the hook returns: a call after that
+     * throws and writes nothing.
+     */
+    readonly sql: ScopedSql;
+    /** The erasure's instant, the same one the spine's tombstones carry. Revoked with `sql`. */
+    now(): string;
+}
+/**
+ * A module's own erasure step (#2068). Synchronous and returning nothing — a promise, an
+ * iterator or any other returned value refuses the whole erasure — and
+ * idempotent: an erasure is re-run after any failure, so a second call for the same subject
+ * must find nothing left to do.
+ */
+export type OnSubjectErased = (ctx: SubjectErasureContext, subject: {
+    readonly subjectId: string;
+}) => void;
+/** One registered module's erasure, validated once at registration. */
+export interface ModuleErasurePlan {
+    readonly moduleId: string;
+    readonly declaration: SubjectErasureDeclaration;
+    readonly hook?: OnSubjectErased;
+    /**
+     * The tables this module's erasure may touch, lowercased: the declaration's, each one VERIFIED
+     * at registration to be created by the module's own migrations. The hook's whole reach.
+     */
+    readonly ownTables: ReadonlySet<string>;
+}
+/** What the module half of one erasure did — the receipt's three new lines. */
+export interface ModuleErasureCounts {
+    verticalRows: ErasedEntityCount[];
+    hookRows: ErasureHookCount[];
+    unreachedEntities: UnreachedEntity[];
+}
+/**
+ * The tables a module's own migration TEXT creates, lowercased — read at registration, where no
+ * scope exists yet, as early feedback only: it can refuse a module whose erasure names a table it
+ * plainly never creates, and it never grants anything. `CREATE TABLE IF NOT EXISTS` on another
+ * module's table reads as a creation here and creates nothing in a scope, which is why the
+ * authority is the ownership each scope RECORDS as its migrations run (`table-ownership.ts`),
+ * checked by the erasure itself before it writes.
+ */
+export declare function tablesCreatedBy(migrations: readonly {
+    readonly sql: string;
+}[]): Set<string>;
+/**
+ * The erasure plan for one registration, or undefined when it has nothing to erase. Throws,
+ * at registration, for every way a module can claim an erasure it cannot deliver, or one that
+ * would reach past itself:
+ *
+ * - a hook with no `manifest.erasure` — the hook's reach IS that block's `tables`, and a hook
+ *   with no reach declared is refused rather than handed the whole scope;
+ * - an entity declared `custom` with no hook to reach it;
+ * - an entity the erasure would write (`blank`, `delete`, `custom`) on a table the module's own
+ *   migrations do not create, and — when there is a hook — any table in its reach that they do
+ *   not create. The declaration is a claim; the migrations are what the kernel ran. A misdeclared
+ *   entity naming another module's table would otherwise have that table erased through the
+ *   kernel's own handle. An `unreached` entity writes nothing and is not held to it.
+ */
+export declare function moduleErasurePlan(registration: ModuleRegistration): ModuleErasurePlan | undefined;
+/**
+ * Refuse a hook statement that reaches past the module's own tables (#2068).
+ *
+ * An ALLOWLIST, judged where a table can stand: every name in a table position — after `FROM`,
+ * `JOIN`, `INTO` and `UPDATE`, and each further name in a comma-joined `FROM` list, at any
+ * nesting depth — must be one of `own`, unqualified. Whatever else the scope holds — another
+ * module's table, a view, a TEMP object, the spine — is refused without having to be listed,
+ * so nothing the schema grows later widens the reach. Also refused: a qualified name
+ * (`main.x`, `temp.x`), a table-valued function other than `json_each`/`json_tree`, `WITH`
+ * (a CTE could shadow an own table's name), and any spine- or `sqlite_`-prefixed name
+ * anywhere. Every statement chained after a `;` starts with an allowed verb.
+ *
+ * It errs toward refusing: a name in a table position that is not a table at all
+ * (`a IS DISTINCT FROM b`) is held to the allowlist too, and fails closed with a message.
+ */
+export declare function assertWithinErasureReach(moduleId: string, sql: string, own: ReadonlySet<string>): void;
+/**
+ * The oldest SQLite that may run an erasure over a search index (#2068): FTS5 `secure-delete`
+ * arrived in 3.42.0, and an index deleted from under it is recorded at FTS5 format version 5,
+ * which no older SQLite can read. A dump never carries a search index (it is rebuilt on load),
+ * so the reader that matters is the runtime holding the scope's own file.
+ */
+export declare const SECURE_DELETE_MIN_SQLITE = "3.42.0";
+/**
+ * Run the module half of one erasure: every declared entity, then every hook, with FTS5's
+ * `secure-delete` on for the search indexes over those modules' tables. `sql` is the kernel's
+ * own handle on the scope — never module code's — and the caller holds it inside the
+ * transaction the spine redaction runs in, so a throw from here rolls both back.
+ *
+ * Order between the two halves: declared first, hooks after, so a hook reading a declared
+ * entity sees it already blank and a hook that deletes cannot strand a declared blank. Order
+ * between modules is registration order, which nothing here depends on: each touches its own
+ * tables only.
+ */
+export declare function eraseSubjectFromModules(input: {
+    readonly sql: ScopedSql;
+    readonly plans: readonly ModuleErasurePlan[];
+    readonly searchPlans: Iterable<SearchIndexPlan>;
+    /** The module tables carrying archive/trash columns (#119), lowercased — `guardSpine`'s. */
+    readonly statefulTables?: ReadonlySet<string>;
+    readonly subjectId: string;
+    readonly at: string;
+    /** A registered module's migration text, for backfilling a scope migrated before ownership was recorded. */
+    readonly migrationSqlOf: (moduleId: string, version: string) => string | undefined;
+}): ModuleErasureCounts;
+/** Every row the module half changed — what the access log adds to "how much evidence this destroyed". */
+export declare function moduleRowsErased(counts: ModuleErasureCounts): number;
+/**
+ * Whether a host's reply carries the module half (#2068) in the shape this kernel wrote — what a
+ * coordinator checks before destroying the key, so a host built before the half existed is
+ * refused rather than read as having reached nothing.
+ */
+export declare function isModuleErasureCounts(value: unknown): value is ModuleErasureCounts;
+//# sourceMappingURL=module-erasure.d.ts.map

package/dist/module-erasure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-erasure.d.ts","sourceRoot":"","sources":["../src/module-erasure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAY,MAAM,iBAAiB,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAKzD,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,4FAA4F;IAC5F,GAAG,IAAI,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,qBAAqB,EAAE,OAAO,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAE5G,uEAAuE;AACvE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,yBAAyB,CAAC;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACzC;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,iBAAiB,EAAE,eAAe,EAAE,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,SAAS;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAW5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,SAAS,CAyCjG;AAkBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAqEtG;AAoCD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC;AA0BjD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAChD,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4GAA4G;IAC5G,QAAQ,CAAC,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACpF,GAAG,mBAAmB,CAgJtB;AAED,0GAA0G;AAC1G,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,mBAAmB,CAIlF"}