canopycms 0.0.56 → 0.0.58

package/dist/branch-registry.js

@@ -1,85 +1,211 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { BranchMetadataFileManager } from './branch-metadata.js';
-import { isNotFoundError } from './utils/error.js';
+import { isNotFoundError, getErrorMessage } from './utils/error.js';
+import { createDebugLogger } from './utils/debug.js';
+import { bumpResourceGeneration, readResourceGeneration, isGenerationCurrent, } from './resource-generation.js';
+const log = createDebugLogger({ prefix: 'BranchRegistry' });
 // Registry files are stored directly in the branches root (not in a subdirectory)
 const REGISTRY_FILE = 'branches.json';
+// Legacy rename-based invalidation scheme's stale marker file. No longer written -
+// invalidate() now bumps the cross-process generation marker instead - but a
+// process upgraded mid-flight may find one left over from before the deploy, so
+// regenerate() opportunistically deletes it. Keep this name only for that cleanup.
 const REGISTRY_STALE_FILE = 'branches.stale.json';
 const REGISTRY_TEMP_FILE = 'branches.tmp.json';
-const REGISTRY_VERSION = 1;
+const REGISTRY_VERSION = 2;
+/** resource-generation.ts resource key for the branch registry's marker. */
+const RESOURCE = 'branch-registry';
+/** Throttle for the get() suspicious-miss backstop; mirrors content-store's FORCED_REFRESH_MIN_INTERVAL_MS. */
+const GET_MISS_REFRESH_MIN_INTERVAL_MS = 5000;
 /**
  * BranchRegistry is a read-only cache for fast branch listing.
  * Individual branch.json files are the source of truth.
  *
+ * ## Cross-process freshness (resource-generation.ts marker protocol)
+ *
+ * Several warm Lambda containers plus the EC2 worker can share one branch-clone
+ * root over EFS, each with its own in-process cache of `branches.json`. There is
+ * no shared memory and no cross-host file watching, so freshness is coordinated
+ * via the generic on-disk generation marker in resource-generation.ts: every
+ * snapshot embeds the marker token it was built against, and every read
+ * cheaply re-checks the live marker before trusting the cached snapshot. See
+ * that module's doc comment for the full protocol and residual staleness
+ * windows (A/B/C/E).
+ *
+ * BranchRegistry is exactly the "durable snapshot consumer" case called out
+ * there: a regeneration whose scan is served from stale NFS dentry/attribute
+ * caches can record a FRESH token over STALE data (window E), and because the
+ * result is written to `branches.json`, that staleness becomes durable and
+ * shared with every other host that reads the marker - not just one process's
+ * memory. Two mitigations close the practical gap:
+ *
+ * - invalidate() eager-regenerates immediately after its own bump. The
+ *   mutating host's own scan is necessarily coherent with the mutation it just
+ *   made (no NFS round trip was needed to observe its own write), so this
+ *   closes window (E) for the common case without waiting for some other host
+ *   to lazily pull the change.
+ * - get() implements a suspicious-miss backstop: a branch that "should" exist
+ *   but is absent from the cached snapshot forces one fresh regeneration
+ *   (throttled), bounding how long a bad snapshot can hide a real branch.
+ *
+ * regenerate() also skips persisting a snapshot when the marker read itself
+ * fails (`{ ok: false }`, e.g. unreadable for a non-ENOENT reason): a snapshot
+ * embedding a token we cannot attribute to "matches this scan" would be
+ * indistinguishable from a correctly-attributed one to every future reader, so
+ * the safer behavior is to serve the fresh scan without writing it durably and
+ * let the next read retry the marker.
+ *
  * Design:
- * - list() returns cached data if fresh, regenerates from branch.json files if stale
- * - invalidate() marks cache as stale (called when branch state changes)
- * - Concurrent regeneration is safe (all processes produce identical output)
+ * - list() returns the cached snapshot if its embedded generation token still
+ *   matches the live marker, regenerates from branch.json files otherwise
+ * - invalidate() bumps the marker (durable, cross-process) and eager-regenerates
+ * - Concurrent regeneration within one process is deduped to a single scan
+ *   (regenInFlight); across processes, regeneration is still safe since all
+ *   processes produce identical output from the same branch.json files
  */
 export class BranchRegistry {
     constructor(root) {
+        /** Shared in-flight scan so concurrent list()/get() callers on one instance await a single regeneration. */
+        this.regenInFlight = null;
+        /** Throttle clock for the get() suspicious-miss backstop. */
+        this.lastForcedRefreshMs = 0;
         this.root = path.resolve(root);
         this.registryPath = path.join(this.root, REGISTRY_FILE);
         this.stalePath = path.join(this.root, REGISTRY_STALE_FILE);
         this.tempPath = path.join(this.root, REGISTRY_TEMP_FILE);
     }
     /**
-     * Returns all branches. Uses cache if fresh, regenerates if stale.
+     * Returns all branches. Uses the cached snapshot if its embedded generation
+     * token matches the live marker, regenerates otherwise.
      */
     async list() {
+        let parsed;
         try {
             const raw = await fs.readFile(this.registryPath, 'utf8');
-            const parsed = JSON.parse(raw);
-            if (!parsed.version || !Array.isArray(parsed.branches)) {
-                // Invalid cache, regenerate
-                return await this.regenerate();
-            }
-            return parsed.branches;
+            parsed = JSON.parse(raw);
         }
         catch (err) {
             if (isNotFoundError(err)) {
-                // Cache missing or stale, regenerate
                 return await this.regenerate();
             }
             throw err;
         }
+        // Strict version check: a truthy-only check would accept a persisted v1
+        // snapshot (no `generation` field) left on EFS after a rolling deploy,
+        // and `parsed.generation` would then be `undefined` rather than a real
+        // token or explicit `null`, breaking the freshness comparison below.
+        if (parsed.version !== REGISTRY_VERSION || !Array.isArray(parsed.branches)) {
+            return await this.regenerate();
+        }
+        const read = await readResourceGeneration(this.root, RESOURCE);
+        if (isGenerationCurrent(parsed.generation, read)) {
+            return parsed.branches;
+        }
+        return await this.regenerate();
     }
     /**
      * Returns a single branch by name. Uses cache if available.
+     *
+     * Suspicious-miss backstop: if `name` isn't in the (possibly cached) list,
+     * that's a signal the snapshot may be stale in the specific direction where
+     * a branch that now exists is missing from it - force one fresh
+     * regeneration and re-search before giving up, throttled per instance so a
+     * genuinely-absent branch costs at most one extra scan per throttle window.
+     * This bounds durable window-E staleness for the "branch exists but
+     * snapshot predates it" direction; see the class doc comment.
      */
     async get(name) {
         const branches = await this.list();
-        return branches.find((b) => b.branch.name === name);
+        const found = branches.find((b) => b.branch.name === name);
+        if (found)
+            return found;
+        if (!this.shouldForceRefresh())
+            return undefined;
+        const refreshed = await this.regenerate();
+        return refreshed.find((b) => b.branch.name === name);
+    }
+    shouldForceRefresh() {
+        const now = Date.now();
+        if (now - this.lastForcedRefreshMs < GET_MISS_REFRESH_MIN_INTERVAL_MS)
+            return false;
+        this.lastForcedRefreshMs = now;
+        return true;
     }
     /**
-     * Marks the cache as stale. Next list() call will regenerate.
-     * Uses atomic rename for safety.
+     * Marks the cache as stale for every process sharing this root by bumping
+     * the cross-process generation marker, then eager-regenerates on this host
+     * (see class doc comment for why). The bump must succeed: a swallowed
+     * failure here would leave the registry stale indefinitely with no
+     * bounding backstop, unlike a failed eager regen below, which only forgoes
+     * closing window (E) early - the bump alone already restored correctness
+     * for every future reader. A failed eager regen therefore must not fail the
+     * caller's save/delete.
      */
     async invalidate() {
+        await bumpResourceGeneration(this.root, RESOURCE, { mustSucceed: true });
         try {
-            await fs.rename(this.registryPath, this.stalePath);
+            // A scan already in flight (a concurrent list() on this shared
+            // instance) captured the PRE-bump token and possibly pre-mutation
+            // state; joining it via regenerate()'s dedup would skip the eager
+            // post-bump scan this method exists for. Let it drain — its snapshot
+            // self-describes as stale either way — then run a fresh scan.
+            if (this.regenInFlight)
+                await this.regenInFlight.catch(() => { });
+            await this.regenerate();
         }
         catch (err) {
-            // ENOENT means already stale or never existed, which is fine
-            if (!isNotFoundError(err)) {
-                throw err;
-            }
+            log.warn('invalidate', 'Eager regeneration after invalidate() failed', {
+                error: getErrorMessage(err),
+            });
         }
     }
     /**
-     * Scans branch directories and rebuilds the cache.
-     * Concurrent calls are safe - all produce identical content.
+     * Scans branch directories and rebuilds the cache, deduping concurrent
+     * callers on this instance to a single underlying scan. Never loops waiting
+     * for the snapshot's embedded token to match the marker - under a bump
+     * storm that could livelock; a caller that wants the very latest state
+     * after a concurrent bump should call list() again after this resolves.
      */
     async regenerate() {
+        if (this.regenInFlight)
+            return this.regenInFlight;
+        const run = this.performRegenerate();
+        this.regenInFlight = run;
+        try {
+            return await run;
+        }
+        finally {
+            this.regenInFlight = null;
+        }
+    }
+    async performRegenerate() {
+        // Capture the marker strictly BEFORE scanning: a bump landing mid-scan
+        // then differs from the token recorded below, forcing a rebuild on the
+        // next probe instead of silently resurrecting stale data.
+        const read = await readResourceGeneration(this.root, RESOURCE);
         const branches = await this.scanBranchDirectories();
-        // Write to unique temp file first, then atomic rename
-        // Use random suffix to avoid conflicts between concurrent regenerations
-        const uniqueTempPath = `${this.tempPath}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
-        await fs.mkdir(this.root, { recursive: true });
+        // Opportunistic cleanup of a stale file left by the old rename-based
+        // invalidation scheme (e.g. a process upgraded mid-flight). Not load-bearing.
+        await fs.unlink(this.stalePath).catch(() => { });
+        if (!read.ok) {
+            // The marker couldn't be read for a reason other than "never bumped" -
+            // we cannot attribute a token to this scan, and stamping the snapshot
+            // with an unattributable token would make it indistinguishable from a
+            // correctly-attributed one to every future reader on any host. Serve
+            // the fresh scan result without persisting it; the next read retries
+            // the marker read and, on success, regenerates and persists normally.
+            return branches;
+        }
         const snapshot = {
             version: REGISTRY_VERSION,
             branches,
+            generation: read.token,
         };
+        // Write to unique temp file first, then atomic rename.
+        // Use random suffix to avoid conflicts between concurrent regenerations.
+        const uniqueTempPath = `${this.tempPath}.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+        await fs.mkdir(this.root, { recursive: true });
         await fs.writeFile(uniqueTempPath, JSON.stringify(snapshot, null, 2) + '\n', 'utf8');
         try {
             await fs.rename(uniqueTempPath, this.registryPath);
@@ -89,12 +215,12 @@ export class BranchRegistry {
             await fs.unlink(uniqueTempPath).catch(() => { });
             throw err;
         }
-        // Clean up stale file (ignore errors)
-        await fs.unlink(this.stalePath).catch(() => { });
         return branches;
     }
     /**
      * Scans the root directory for branch subdirectories with valid branch.json files.
+     * Protected (rather than exported as a test hook) so tests can subclass and
+     * override to simulate cross-process interleavings.
      */
     async scanBranchDirectories() {
         const branches = [];

package/dist/branch-registry.js.map

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

package/dist/branch-schema-cache.d.ts

@@ -1,7 +1,9 @@
 import type { RootCollectionConfig } from './config';
 import type { FlatSchemaItem } from './config/types';
 import type { OperatingMode } from './operating-mode';
-import type { EntrySchemaRegistry } from './schema/types';
+import type { EntrySchemaRegistry, SchemaResolutionResult } from './schema/types';
+/** resource-generation.ts resource key for the schema cache's marker. */
+export declare const SCHEMA_GENERATION_RESOURCE = "schema";
 /**
  * Schema cache structure stored in {branchRoot}/.canopy-meta/schema-cache.json
  */
@@ -10,19 +12,84 @@ export interface BranchSchemaCacheEntry {
     schema: RootCollectionConfig;
     flatSchema: FlatSchemaItem[];
     cachedAt: string;
+    /**
+     * The resource-generation.ts marker token this snapshot was resolved
+     * against, or null if it was built before any bump ever occurred on this
+     * root. Compared against the live marker (via isGenerationCurrent) to
+     * decide freshness. See the class doc comment.
+     */
+    generation: string | null;
 }
 /**
- * Manages per-branch schema caching with lazy loading and automatic invalidation.
+ * Manages per-branch schema caching with lazy loading and automatic
+ * invalidation.
  *
- * Caching Strategy:
- * - File-based cache at {branchRoot}/.canopy-meta/schema-cache.json (no in-memory layer
- *   — intentional: matches prod behavior and keeps cache coherent across Lambda invocations)
- * - Invalidation: Writers create .stale marker, causing cache regeneration on next access
+ * ## Cross-process freshness (resource-generation.ts marker protocol)
+ *
+ * Several warm Lambda containers plus the EC2 worker can share one
+ * branch-clone root over EFS, each with its own copy of
+ * `schema-cache.json`. There is no shared memory and no cross-host file
+ * watching, so freshness is coordinated via the generic on-disk generation
+ * marker in resource-generation.ts: every cached snapshot embeds the marker
+ * token it was resolved against, and every read cheaply re-checks the live
+ * marker before trusting the cache. See that module's doc comment for the
+ * full protocol and residual staleness windows (A/B/C/E).
+ *
+ * BranchSchemaCache is the "durable snapshot consumer" case called out there:
+ * a resolve whose scan is served from stale NFS dentry/attribute caches can
+ * record a FRESH token over STALE data (window E), and because the result is
+ * written to `schema-cache.json`, that staleness becomes durable and shared
+ * with every other host that reads the marker - not just one process's
+ * memory. `loadFromCacheOrResolve` mitigates this the same way
+ * BranchRegistry does:
  *
- * Multi-User Support:
- * - User A modifies schema via SchemaOps → writes .stale marker
- * - User B loads schema later → sees .stale marker → regenerates cache
- * - Atomic file operations prevent corruption during concurrent access
+ * - The marker is captured strictly BEFORE `resolveFresh()` runs, and the
+ *   captured token (not one read after resolving) is what gets embedded in
+ *   the persisted snapshot. A bump landing mid-resolve therefore leaves the
+ *   embedded token older than the live marker, forcing a re-resolve on the
+ *   next read instead of silently resurrecting stale schema.
+ * - A snapshot is only persisted when the marker read itself succeeded
+ *   (`{ ok: true }`). If the read fails for a reason other than "never
+ *   bumped", we cannot attribute a token to this resolve, and stamping the
+ *   snapshot with an unattributable token would make it indistinguishable
+ *   from a correctly-attributed one to every future reader. The fresh result
+ *   is still served to this caller; it just isn't written durably.
+ * - invalidate() bumps the marker with `mustSucceed: true`: an explicit
+ *   invalidation (e.g. after a schema mutation) must not silently fail and
+ *   leave every reader confidently stale with no bounding backstop.
+ *   invalidate() itself does NOT eager-regenerate - it isn't given the
+ *   entrySchemaRegistry/contentRootName that resolveSchema needs. The
+ *   eager re-resolve (window-E mitigation, mirroring BranchRegistry's
+ *   eager regen) lives one level up in SchemaOps.invalidateSchemaCache()
+ *   (schema/schema-store.ts), which has those arguments and calls
+ *   {@link resolveAndPersist} (NOT getSchema()) right after invalidating -
+ *   so every SchemaOps mutation re-resolves on the mutating host via a scan
+ *   that is GUARANTEED to run, not merely likely to run. getSchema() would
+ *   be the wrong call here: its cache-read fast path can short-circuit
+ *   through a snapshot a DIFFERENT concurrent host just wrote (see
+ *   resolveAndPersist()'s doc comment for the exact race), silently
+ *   skipping the one scan this eager re-resolve exists to guarantee. (The
+ *   editor's follow-up schema GET is a separate Lambda invocation with no
+ *   container affinity, so it could not serve this purpose either.)
+ *   Callers of invalidate() that bypass SchemaOps (api/schema.ts's explicit
+ *   invalidate endpoint; the bulk-mutation bump in
+ *   invalidateBranchContentCaches) accept the lazy next-read regen.
+ *
+ * This is also why prod needs no mtime walk: the dev-only mtime check below
+ * exists solely to catch hand edits to .collection.json made outside the CMS
+ * (which bypass SchemaOps and therefore never bump the marker). Every
+ * mutation path that matters in prod - SchemaOps writes, git working-tree
+ * rewrites (checkout/merge/rebase/sync/migrate) - bumps the marker via
+ * SchemaOps.invalidateSchemaCache() or the combined
+ * invalidateBranchContentCaches() helper in content-index-generation.ts, so
+ * the marker alone is a sufficient prod backstop.
+ *
+ * Caching Strategy:
+ * - File-based cache at {branchRoot}/.canopy-meta/schema-cache.json (no
+ *   in-memory layer - intentional: matches prod behavior and keeps cache
+ *   coherent across Lambda invocations)
+ * - Invalidation: invalidate() bumps the cross-process generation marker;
+ *   every reader sharing this branchRoot re-resolves at its next access.
  */
 export declare class BranchSchemaCache {
     /** Tracks when we last checked mtimes per contentRoot, to debounce rapid requests */
@@ -51,12 +118,60 @@ export declare class BranchSchemaCache {
         schema: RootCollectionConfig;
         flatSchema: FlatSchemaItem[];
     }>;
+    /**
+     * Resolve the schema from disk. Wrapped in a protected method (rather than
+     * calling the imported resolveSchema directly) so tests can subclass and
+     * override with a deferred/blocking implementation to simulate cross-process
+     * interleavings — mirrors BranchRegistry's scanBranchDirectories() hook.
+     */
+    protected resolveFresh(contentRoot: string, entrySchemaRegistry: EntrySchemaRegistry): Promise<SchemaResolutionResult>;
     /**
      * Load schema from cache or resolve fresh if cache is missing or stale.
      */
     private loadFromCacheOrResolve;
     /**
-     * Invalidate cache for a branch (creates .stale marker).
+     * Resolve the schema fresh from disk and persist it (subject to the
+     * skip-persist rule below), UNCONDITIONALLY -- never through the cache-read
+     * fast path in {@link loadFromCacheOrResolve}. Shared by that method's
+     * cache-miss fallback and by {@link resolveAndPersist}.
+     */
+    private resolveFreshAndPersist;
+    /**
+     * Resolve the schema fresh from disk and persist it, SKIPPING the cache
+     * read entirely -- unlike {@link getSchema}, which can short-circuit
+     * through a cache HIT. That distinction matters for eager re-resolve after
+     * invalidation (see {@link invalidate}'s doc comment and
+     * `SchemaOps.invalidateSchemaCache()` in schema/schema-store.ts, the sole
+     * intended caller): the whole point of an eager re-resolve is to guarantee
+     * ONE scan that is coherent with the mutation this host just made. A plain
+     * `getSchema()` call right after `invalidate()` is NOT that guarantee --
+     * `getSchema()`'s cache-read fast path (`loadFromCacheOrResolve`) can still
+     * return a snapshot written by a DIFFERENT, concurrent host: if that
+     * foreign host's own eager re-resolve raced this one and embedded the
+     * (now-current) marker token over ITS OWN stale-NFS-cache scan (the
+     * window-E case this class's doc comment describes), this host's
+     * `getSchema()` would happily accept that foreign snapshot as "current"
+     * and skip the one scan this call was specifically trying to guarantee.
+     * `resolveAndPersist()` never reads the cache file at all, so it cannot be
+     * short-circuited that way.
+     */
+    resolveAndPersist(branchRoot: string, entrySchemaRegistry: EntrySchemaRegistry, contentRootName?: string): Promise<{
+        schema: RootCollectionConfig;
+        flatSchema: FlatSchemaItem[];
+    }>;
+    /**
+     * Invalidate cache for a branch by bumping the cross-process generation
+     * marker (resource-generation.ts). Every process sharing this branchRoot
+     * will re-resolve at its next read.
+     *
+     * The bump must succeed: a swallowed failure here would leave the schema
+     * cache stale indefinitely with no bounding backstop (unlike
+     * BranchRegistry, there is no get-miss backstop for a resolved schema).
+     *
+     * No eager regeneration here (unlike BranchRegistry.invalidate()): this
+     * method isn't given the entrySchemaRegistry/contentRootName resolveSchema
+     * needs. See the class doc comment for why the mutating request's own
+     * follow-up schema read closes the same window-E gap instead.
      *
      * @param branchRoot - Root directory of the branch
      */

package/dist/branch-schema-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-schema-cache.d.ts","sourceRoot":"","sources":["../src/branch-schema-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAA;AAWzD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,oBAAoB,CAAA;IAC5B,UAAU,EAAE,cAAc,EAAE,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;CACjB;AA8BD;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAC5B,qFAAqF;IACrF,OAAO,CAAC,cAAc,CAA4B;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,IAAI,GAAE,aAAsB;IAIxC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;;OAOG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,mBAAmB,EAAE,mBAAmB,EACxC,eAAe,GAAE,MAAkB,GAClC,OAAO,CAAC;QAAE,MAAM,EAAE,oBAAoB,CAAC;QAAC,UAAU,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;IAI1E;;OAEG;YACW,sBAAsB;IA+FpC;;;;OAIG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CASpD"}
+{"version":3,"file":"branch-schema-cache.d.ts","sourceRoot":"","sources":["../src/branch-schema-cache.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAiBjF,yEAAyE;AACzE,eAAO,MAAM,0BAA0B,WAAW,CAAA;AAElD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,oBAAoB,CAAA;IAC5B,UAAU,EAAE,cAAc,EAAE,CAAA;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,qBAAa,iBAAiB;IAC5B,qFAAqF;IACrF,OAAO,CAAC,cAAc,CAA4B;IAElD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,IAAI,GAAE,aAAsB;IAIxC;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;;;OAOG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,EAClB,mBAAmB,EAAE,mBAAmB,EACxC,eAAe,GAAE,MAAkB,GAClC,OAAO,CAAC;QAAE,MAAM,EAAE,oBAAoB,CAAC;QAAC,UAAU,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;IAI1E;;;;;OAKG;cACa,YAAY,CAC1B,WAAW,EAAE,MAAM,EACnB,mBAAmB,EAAE,mBAAmB,GACvC,OAAO,CAAC,sBAAsB,CAAC;IAIlC;;OAEG;YACW,sBAAsB;IA+DpC;;;;;OAKG;YACW,sBAAsB;IA0EpC;;;;;;;;;;;;;;;;;;OAkBG;IACG,iBAAiB,CACrB,UAAU,EAAE,MAAM,EAClB,mBAAmB,EAAE,mBAAmB,EACxC,eAAe,GAAE,MAAkB,GAClC,OAAO,CAAC;QAAE,MAAM,EAAE,oBAAoB,CAAC;QAAC,UAAU,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;IAO1E;;;;;;;;;;;;;;;OAeG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAKpD"}