@davidorex/pi-context 0.26.0 → 0.28.0

package/dist/migration-registry-loader.js

@@ -0,0 +1,309 @@
+/**
+ * migration-registry-loader — builds a populated MigrationRegistry from the
+ * substrate-persisted migrations.json declarations.
+ *
+ * Layering:
+ *   - schema-migrations.ts owns the in-memory registry abstraction
+ *     (MigrationFn, MigrationRegistry, createRegistry, runMigrations). It
+ *     knows nothing of persistence — that boundary is intentional so the
+ *     registry can be exercised by tests with ad-hoc functions.
+ *   - migrations-store.ts owns the on-disk read/write surface (MigrationDecl,
+ *     TransformOp shapes; AJV-validated load/write; op-correct mutation
+ *     helpers).
+ *   - This module is the bridge: it consumes MigrationDecl values from the
+ *     store and produces MigrationFn closures that the registry registers.
+ *     Caching (keyed on the resolved substrate dir) + invalidation hooks live
+ *     here so the substrate writers can punch a single function call to mark
+ *     the cached registry stale.
+ *
+ * Path-walker semantics (TransformSpec dotted paths):
+ *   - All paths are anchored on '$' and use simple dotted notation:
+ *     '$' → the data root, '$.field' → root.field, '$.nested.field' →
+ *     root.nested.field. Bracket-indexed array access ('$.arr[0]') is OUT
+ *     of initial scope; the schema does not constrain the string form
+ *     beyond a free-form `type: "string"`, but the walker rejects '[' in
+ *     a path segment so a future array-extension is not accidentally
+ *     bypassed at the runtime layer.
+ *   - 'set' creates intermediate object parents as needed (a 'set' at
+ *     '$.a.b.c' on `{}` produces `{ a: { b: { c: value } } }`). 'rename'
+ *     is read + delete + set: a no-op when the source field is absent.
+ *     'delete' is a no-op when the field is absent. 'coerce' is a no-op
+ *     when the field is absent; when present it casts via the explicit
+ *     primitive constructors String(v) / Number(v) / Boolean(v); for
+ *     'array' coercion uses [].concat(v) so a non-array value becomes a
+ *     single-element array (and an existing array passes through
+ *     unchanged); for 'object' coercion uses Object(v).
+ *
+ * Identity migrations are the pass-through case the operator declares when
+ * the bumped schema is shape-compatible with the prior version; the closure
+ * returned by migrationFnFor for kind='identity' is byte-cheap (returns the
+ * input reference unchanged).
+ */
+import path from "node:path";
+import { resolveContextDir, tryResolveContextDir } from "./context-dir.js";
+import { loadMigrationsFileForDir } from "./migrations-store.js";
+import { createRegistry } from "./schema-migrations.js";
+/**
+ * Cache of populated MigrationRegistry instances. ONE cache, keyed by the
+ * RESOLVED SUBSTRATE DIR (`path.resolve(substrateDir)`) — not by cwd. The cwd
+ * and dir forms converge on this single key: the cwd forms first resolve
+ * `cwd → substrateDir` via the bootstrap pointer, then read/invalidate the
+ * dir-keyed entry. Invalidated by `invalidateMigrationRegistry(cwd)` /
+ * `invalidateMigrationRegistryForDir(substrateDir)` after a successful
+ * migrations.json mutation so the next consumer sees the new declarations
+ * without restarting the process.
+ *
+ * Keying on the resolved dir (rather than cwd) is load-bearing for coherence:
+ * the block writers read the registry via `getProjectMigrationRegistryForDir`
+ * (dir-keyed); a migration declaration invalidates via the cwd form. If the
+ * read key (resolved dir) and the invalidate key (raw cwd) diverged — which
+ * they do whenever cwd ≠ substrateDir, e.g. `<root>` vs `<root>/.project` —
+ * the post-declaration read would serve a stale pre-declaration registry. The
+ * single resolved-dir key keeps read and invalidate coherent.
+ */
+const registryCache = new Map();
+/**
+ * Apply a single dotted path traversal, returning {parent, key} where parent
+ * is the object containing the addressed leaf and key is the final segment.
+ * When `createParents` is true, intermediate missing parents are created as
+ * empty objects (used by 'set' / 'rename' write side). When false, missing
+ * intermediates yield `null` parent (used by 'delete' / 'coerce' / 'rename'
+ * read side to no-op silently on absent paths).
+ *
+ * Rejects '[' / ']' in any segment — array-element addressing is explicitly
+ * out of scope so a future extension cannot be accidentally bypassed.
+ */
+function walkPath(root, dottedPath, createParents) {
+    if (!dottedPath.startsWith("$")) {
+        throw new Error(`migration path must start with '$' (got '${dottedPath}')`);
+    }
+    const tail = dottedPath.slice(1); // strip leading '$'
+    const segments = tail.length === 0 ? [] : tail.split(".").slice(1); // first split element is '' from leading '.'
+    if (segments.length === 0) {
+        throw new Error(`migration path '${dottedPath}' has no segments; cannot address the root for write/delete`);
+    }
+    for (const seg of segments) {
+        if (seg.length === 0) {
+            throw new Error(`migration path '${dottedPath}' contains an empty segment`);
+        }
+        if (seg.includes("[") || seg.includes("]")) {
+            throw new Error(`migration path '${dottedPath}' contains array-element addressing ('[...]'); not supported in v1`);
+        }
+    }
+    if (typeof root !== "object" || root === null || Array.isArray(root)) {
+        if (!createParents)
+            return { parent: null, key: segments[segments.length - 1] };
+        throw new Error(`migration path '${dottedPath}' cannot create parents on a non-object root`);
+    }
+    let cursor = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+        const seg = segments[i];
+        const next = cursor[seg];
+        if (typeof next === "object" && next !== null && !Array.isArray(next)) {
+            cursor = next;
+        }
+        else if (createParents) {
+            const fresh = {};
+            cursor[seg] = fresh;
+            cursor = fresh;
+        }
+        else {
+            return { parent: null, key: segments[segments.length - 1] };
+        }
+    }
+    return { parent: cursor, key: segments[segments.length - 1] };
+}
+/**
+ * Apply one TransformOp to `data` in place. Returns the (possibly same) data
+ * reference so chained ops compose cleanly. The mutation is intentionally
+ * in-place because the migrationFnFor closure deep-clones at the entry of
+ * the composed function — chaining sees a private copy throughout.
+ */
+function applyOp(data, op) {
+    switch (op.op) {
+        case "rename": {
+            const read = walkPath(data, op.from, false);
+            if (read.parent === null || !(read.key in read.parent))
+                return data; // no-op on absent source
+            const value = read.parent[read.key];
+            delete read.parent[read.key];
+            const write = walkPath(data, op.to, true);
+            if (write.parent === null)
+                return data;
+            write.parent[write.key] = value;
+            return data;
+        }
+        case "set": {
+            const write = walkPath(data, op.path, true);
+            if (write.parent === null)
+                return data;
+            write.parent[write.key] = op.value;
+            return data;
+        }
+        case "delete": {
+            const read = walkPath(data, op.path, false);
+            if (read.parent === null)
+                return data;
+            delete read.parent[read.key];
+            return data;
+        }
+        case "coerce": {
+            const read = walkPath(data, op.path, false);
+            if (read.parent === null || !(read.key in read.parent))
+                return data;
+            const current = read.parent[read.key];
+            let next;
+            switch (op.type) {
+                case "string":
+                    next = String(current);
+                    break;
+                case "number":
+                    next = Number(current);
+                    break;
+                case "boolean":
+                    next = Boolean(current);
+                    break;
+                case "array":
+                    next = Array.isArray(current) ? current : [].concat(current);
+                    break;
+                case "object":
+                    next = Object(current);
+                    break;
+            }
+            read.parent[read.key] = next;
+            return data;
+        }
+    }
+}
+/**
+ * Convert one MigrationDecl into a MigrationFn closure. kind='identity'
+ * returns the input unchanged; kind='declarative-transform' deep-clones
+ * the input then applies each TransformOp in declaration order to the
+ * private copy, returning it.
+ *
+ * The kind='declarative-transform' branch throws when `transform` is
+ * missing — the schema declares the field optional only because the
+ * identity branch never carries one; runtime-time the loader trusts the
+ * write-schema-migration tool's presence/absence guard, but a hand-edited
+ * malformed file would surface here rather than silently no-op.
+ */
+export function migrationFnFor(decl) {
+    if (decl.kind === "identity") {
+        return (data) => data;
+    }
+    if (decl.kind === "declarative-transform") {
+        const ops = decl.transform?.operations;
+        if (!ops) {
+            throw new Error(`migrationFnFor: declarative-transform decl for schema '${decl.schemaName}' ${decl.fromVersion}→${decl.toVersion} is missing transform.operations`);
+        }
+        return (data) => {
+            let cursor = JSON.parse(JSON.stringify(data));
+            for (const op of ops) {
+                cursor = applyOp(cursor, op);
+            }
+            return cursor;
+        };
+    }
+    // Unreachable per the TS discriminated union — present as a defensive
+    // throw so a future schema-shape additive change surfaces here.
+    throw new Error(`migrationFnFor: unknown decl.kind '${decl.kind}'`);
+}
+/**
+ * Build a fresh MigrationRegistry populated from migrations.json. When the
+ * file is absent or empty (no declarations), returns an empty registry that
+ * `runMigrations` exercises happy-path-only (currentVersion === targetVersion
+ * cases pass through without registry consultation).
+ *
+ * Throws when a declaration is malformed in a way the loader catches at
+ * MigrationFn-construction time (e.g. declarative-transform with no
+ * transform.operations), preserving the fail-fast aim. The store's AJV
+ * validation at load time catches schema-shape failures upstream.
+ */
+export function buildRegistryFromSubstrateForDir(substrateDir) {
+    const reg = createRegistry();
+    const file = loadMigrationsFileForDir(substrateDir);
+    if (file === null)
+        return reg;
+    for (const decl of file.migrations) {
+        const migrate = migrationFnFor(decl);
+        reg.register({
+            schemaName: decl.schemaName,
+            fromVersion: decl.fromVersion,
+            toVersion: decl.toVersion,
+            migrate,
+        });
+    }
+    return reg;
+}
+export function buildRegistryFromSubstrate(cwd) {
+    return buildRegistryFromSubstrateForDir(resolveContextDir(cwd));
+}
+/**
+ * Return a cached MigrationRegistry for `cwd`, building it on first call (or
+ * after invalidation). Resolves the cwd to its substrate dir via the bootstrap
+ * pointer, then delegates to `getProjectMigrationRegistryForDir` so the cwd
+ * read path and the dir read path share ONE cache entry (keyed by the resolved
+ * substrate dir). This convergence is what keeps reads coherent with the
+ * cwd-form invalidation.
+ */
+export function getProjectMigrationRegistry(cwd) {
+    return getProjectMigrationRegistryForDir(resolveContextDir(cwd));
+}
+/**
+ * Dir-targeted form of `getProjectMigrationRegistry` and the SINGLE registry
+ * builder/cacher: return a cached MigrationRegistry for an explicit substrate
+ * directory, building it on first call. Keyed on `path.resolve(substrateDir)`
+ * — the one cache key both read forms and both invalidate forms agree on. Used
+ * by `writeBlockForDir` so a write into a non-active substrate
+ * validates/migrates against THAT substrate's `migrations.json`, never the
+ * active dir's.
+ *
+ * The cwd form (`getProjectMigrationRegistry`) resolves `cwd → substrateDir`
+ * and delegates here, so when `substrateDir === resolveContextDir(cwd)` both
+ * forms hit the SAME entry. The migrations-store mutation helpers invalidate
+ * via `invalidateMigrationRegistry(cwd)`, which resolves the same dir key and
+ * deletes the entry this builder populates — so a declare-then-read sequence
+ * (mutate migrations.json, then `writeBlockForDir` re-reads) rebuilds against
+ * the fresh declarations rather than serving a stale registry.
+ */
+export function getProjectMigrationRegistryForDir(substrateDir) {
+    const key = path.resolve(substrateDir);
+    const cached = registryCache.get(key);
+    if (cached)
+        return cached;
+    const reg = buildRegistryFromSubstrateForDir(substrateDir);
+    registryCache.set(key, reg);
+    return reg;
+}
+/**
+ * Drop the cached MigrationRegistry for an explicit substrate directory (if
+ * any). Deletes `path.resolve(substrateDir)` — the SAME key the read forms
+ * populate, so an invalidation here is observed by the next read.
+ *
+ * No-op when no entry is cached — invalidation is cheap and write-after-no-
+ * cache is a normal pre-warming state.
+ */
+export function invalidateMigrationRegistryForDir(substrateDir) {
+    registryCache.delete(path.resolve(substrateDir));
+}
+/**
+ * Drop the cached MigrationRegistry for `cwd` (if any). Called by each
+ * migrations-store mutation helper after a successful write so the next
+ * consumer reads the fresh declarations without process restart.
+ *
+ * Resolves `cwd → substrateDir` and delegates to the ForDir form so the
+ * deleted key MATCHES the resolved-substrate-dir key the read path uses (the
+ * Regression-B fix: pre-fix this deleted `path.resolve(cwd)`, a different key
+ * from the dir-keyed read entry, leaving the post-declaration read stale). The
+ * mutation helpers always call this after a successful `writeMigrationsFile`,
+ * which itself required the pointer to resolve — so resolution is normally
+ * safe; `tryResolveContextDir` guards the absent-pointer edge with a no-op
+ * rather than throwing during invalidation.
+ */
+export function invalidateMigrationRegistry(cwd) {
+    const substrateDir = tryResolveContextDir(cwd);
+    if (substrateDir === null)
+        return;
+    invalidateMigrationRegistryForDir(substrateDir);
+}
+//# sourceMappingURL=migration-registry-loader.js.map

package/dist/migration-registry-loader.js.map

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

package/dist/migrations-store.d.ts

@@ -0,0 +1,141 @@
+/**
+ * migrations-store — substrate-managed read / write surface for
+ * `<resolveContextDir(cwd)>/migrations.json`.
+ *
+ * Mirrors the config / relations precedent in context.ts: load + AJV-validate
+ * via `validateFromFile` against the bundled migrations.schema.json; whole-file
+ * writes delegate to block-api's atomic `writeTypedFile` (tmp + rename) so a
+ * failed write leaves the prior file byte-identical.
+ *
+ * Three op-correct mutation helpers — append / replace / remove — wrap a
+ * load → JSON deep-clone → mutate → write pattern. Identity of a MigrationDecl
+ * is the (schemaName, fromVersion) pair, mirroring the registry's
+ * one-outgoing-edge-per-(schemaName, fromVersion) discipline from
+ * `schema-migrations.ts`:
+ *   - appendMigrationDecl requires the (schemaName, fromVersion) pair to be
+ *     ABSENT; collision throws with a descriptive message so an unintended
+ *     double-declaration surfaces at the write site rather than as silent
+ *     registry duplicate-registration at load time.
+ *   - replaceMigrationDecl requires the pair to be PRESENT; a missing target
+ *     throws (use append to introduce a new declaration).
+ *   - removeMigrationDecl requires the pair to be PRESENT; a missing target
+ *     throws.
+ *
+ * After each successful mutation the helper invokes
+ * `invalidateMigrationRegistry(cwd)` (migration-registry-loader.ts) so the
+ * next `getProjectMigrationRegistry(cwd)` consumer reads the fresh
+ * declarations without process restart. The store↔loader edge is mutually
+ * cyclic (loader reads from store; store writes invalidate loader cache);
+ * ESM tolerates the cycle because both imports are function-level uses, not
+ * top-level evaluations.
+ *
+ * MigrationDecl + TransformSpec + TransformOp types mirror the on-disk schema
+ * shape one-for-one. They live here (rather than schema-migrations.ts) because
+ * schema-migrations.ts is the in-memory registry abstraction (knows nothing of
+ * persistence); the persisted-shape vocabulary belongs at the substrate-store
+ * boundary.
+ */
+import type { DispatchContext } from "./dispatch-context.js";
+/**
+ * One TransformOp variant — discriminated by the `op` field. Mirrors the
+ * `definitions/TransformOp` `oneOf` in migrations.schema.json. Keeping the
+ * variants in TypeScript lets the loader's `migrationFnFor` switch on the
+ * discriminator with type-narrowing rather than blind property access.
+ */
+export type TransformOp = {
+    op: "rename";
+    from: string;
+    to: string;
+} | {
+    op: "set";
+    path: string;
+    value?: unknown;
+} | {
+    op: "delete";
+    path: string;
+} | {
+    op: "coerce";
+    path: string;
+    type: "string" | "number" | "boolean" | "array" | "object";
+};
+export interface TransformSpec {
+    operations: TransformOp[];
+}
+export interface MigrationDecl {
+    schemaName: string;
+    fromVersion: string;
+    toVersion: string;
+    kind: "identity" | "declarative-transform";
+    transform?: TransformSpec;
+    created_by: string;
+    created_at: string;
+}
+export interface MigrationsFile {
+    schema_version: string;
+    migrations: MigrationDecl[];
+}
+/**
+ * Current schema_version emitted into newly-created migrations.json files.
+ * Tracks the `version` field of migrations.schema.json itself.
+ */
+export declare const MIGRATIONS_FILE_VERSION = "1.0.0";
+/**
+ * Load + AJV-validate migrations.json. Returns null when the file is absent
+ * (pre-write state is a normal condition, NOT an error — empty/missing yields
+ * an empty registry in the loader). Throws on read / parse / schema failure.
+ */
+export declare function loadMigrationsFileForDir(substrateDir: string): MigrationsFile | null;
+export declare function loadMigrationsFile(cwd: string): MigrationsFile | null;
+/**
+ * Atomic, AJV-validated whole-file write of migrations.json. Delegates to
+ * block-api's writeTypedFile against the bundled migrations schema. `ctx` is
+ * accepted for call-site parity with the rest of the substrate write surface;
+ * the migrations schema declares no envelope author fields so stamping is a
+ * structural no-op today (the loader-cache invalidation upstream of this call
+ * is the side-effect that matters for read-after-write parity).
+ */
+export declare function writeMigrationsFile(cwd: string, file: MigrationsFile, ctx?: DispatchContext): void;
+/**
+ * Dir-targeted twin of {@link writeMigrationsFile} (Cycle-1 `*ForDir` pattern).
+ * Atomic, AJV-validated whole-file write of `<substrateDir>/migrations.json`
+ * against the bundled migrations schema — takes the ALREADY-RESOLVED substrate
+ * dir directly (no `.pi-context.json` pointer resolution). The cwd form is a
+ * thin wrapper resolving the active dir; behaviour is byte-identical when called
+ * via cwd. Same attestation-parity no-op semantics as the cwd form (the
+ * migrations schema declares no envelope author fields). Does NOT invalidate any
+ * loader cache — the cache-invalidation side-effect lives on the
+ * appendMigrationDecl mutation helpers, not the raw whole-file write.
+ */
+export declare function writeMigrationsFileForDir(substrateDir: string, file: MigrationsFile, ctx?: DispatchContext): void;
+/**
+ * Append a new MigrationDecl to the substrate. Op-correctness: the
+ * (schemaName, fromVersion) pair must be ABSENT on-disk; collision throws.
+ * Invalidates the loader cache for `cwd` after a successful write so the
+ * next registry consumer reads the fresh declaration.
+ */
+export declare function appendMigrationDecl(cwd: string, decl: MigrationDecl, ctx?: DispatchContext): void;
+/**
+ * Dir-targeted twin of {@link appendMigrationDecl} (Cycle-1 `*ForDir` pattern).
+ * Append a new MigrationDecl to the substrate at `substrateDir`. Op-correctness:
+ * the (schemaName, fromVersion) pair must be ABSENT on-disk; collision throws.
+ * Invalidates the loader cache for `substrateDir` after a successful write so
+ * the next registry consumer reads the fresh declaration. The cwd form is a thin
+ * wrapper resolving the active dir; behaviour is byte-identical when called via
+ * cwd (resolveContextDir(cwd) → invalidateMigrationRegistry(cwd) routes through
+ * invalidateMigrationRegistryForDir on the same dir).
+ */
+export declare function appendMigrationDeclForDir(substrateDir: string, decl: MigrationDecl, ctx?: DispatchContext): void;
+/**
+ * Replace an existing MigrationDecl identified by (schemaName, fromVersion).
+ * Op-correctness: target must be PRESENT; missing target throws. The whole
+ * decl is replaced (no per-field merge). Invalidates the loader cache after a
+ * successful write.
+ */
+export declare function replaceMigrationDecl(cwd: string, decl: MigrationDecl, ctx?: DispatchContext): void;
+/**
+ * Remove an existing MigrationDecl identified by (schemaName, fromVersion).
+ * Op-correctness: target must be PRESENT; missing target throws. Invalidates
+ * the loader cache after a successful write.
+ */
+export declare function removeMigrationDecl(cwd: string, schemaName: string, fromVersion: string, ctx?: DispatchContext): void;
+//# sourceMappingURL=migrations-store.d.ts.map

package/dist/migrations-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations-store.d.ts","sourceRoot":"","sources":["../src/migrations-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAc7D;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACpB;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,EAAE,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;CAAE,CAAC;AAE9F,MAAM,WAAW,aAAa;IAC7B,UAAU,EAAE,WAAW,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,UAAU,GAAG,uBAAuB,CAAC;IAC3C,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAiBpF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAElG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAEjH;AA6BD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAEjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAYhH;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAiBlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAerH"}