@telora/daemon 0.22.187 → 0.22.208

package/dist/migrations/migration-held-set.js

@@ -0,0 +1,295 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: packages/daemon/src/migrations/claim-end-to-end.test.ts,
+//   packages/daemon/src/migrations/concurrent-claim-regression.test.ts,
+//   packages/daemon/src/migrations/held-set-grant-effect.test.ts,
+//   packages/daemon/src/migrations/migration-held-set.test.ts,
+//   packages/daemon/src/shell/migration-held-set-publish.test.ts
+// PINNED-BY-END
+/**
+ * What a product's migration numbers are CURRENTLY held by, across every ref
+ * that matters -- integration and every live focus branch.
+ *
+ * WHY THIS LIVES IN THE DAEMON AND THE GRANT DOES NOT
+ * ---------------------------------------------------
+ * The two halves of claiming a number sit on opposite sides of a boundary, and
+ * neither half can move:
+ *
+ *   - Seeing what is held needs the REPO. It is a git-tree read across several
+ *     refs, and only the daemon has the repository on disk. The product-api
+ *     edge function has no git (`sessionStateHandler` says as much: "the server
+ *     has no git access").
+ *   - Granting a number needs the DATABASE, atomically. Two teams claiming at
+ *     once must be separated by a constraint, not by timing, and the constraint
+ *     is the partial unique index on `product_migration_claims`.
+ *
+ * So the held set has to cross the gap. The daemon PUBLISHES it -- per product,
+ * on the heartbeat, the way `metadata.verificationPostures` is published for
+ * the same reason ("posture is workstation-local config the API cannot itself
+ * derive; the daemon is the single source") -- and the edge handler grants
+ * against the published set plus the live claims it can see itself.
+ *
+ * THE OTHER SHAPE, AND WHY NOT IT. Serving the whole claim from the daemon was
+ * the alternative. It collapses: either the daemon reads-then-inserts, which is
+ * the two-worktrees race reborn one altitude up, or it still calls an edge
+ * handler to do the atomic insert -- in which case that handler exists anyway
+ * and the daemon is an extra hop in front of it. The decision is recorded on
+ * the delivery.
+ *
+ * WHY A STALE SNAPSHOT IS SAFE, AND WHERE IT IS NOT
+ * -------------------------------------------------
+ * The published set is only ever an INPUT TO THE CANDIDATE. It never decides
+ * anything: the unique index decides. A snapshot read a minute ago can make the
+ * handler propose a number that a concurrent claim just took -- and the insert
+ * fails, and the handler recomputes. A stale snapshot costs a retry; it cannot
+ * cost a collision.
+ *
+ * What it CAN cost is a number granted against branch tips that have since
+ * moved -- a migration landed on a sibling branch after the snapshot was taken,
+ * and no claim was recorded for it (a team that skipped the rule). That is why
+ * every reading carries `tips`: the exact sha each ref was at when it was read.
+ * The confirm pass re-checks a claim whose snapshot predates the tips its branch
+ * actually had. A snapshot with no recorded staleness is a silent read-then-write
+ * race wearing a different hat, so the tips are not optional decoration.
+ *
+ * WHAT AN UNREADABLE REF DOES
+ * ---------------------------
+ * It makes the whole reading INCOMPLETE, and the reading says so. A ref that
+ * could not be read proves nothing about what it holds, and a held set quietly
+ * missing one branch's numbers tells the allocator those numbers are free --
+ * failing open on exactly the question being asked. An incomplete reading is
+ * published as incomplete and the handler refuses to grant against it.
+ *
+ * A ref that does not EXIST is different and is not incompleteness: a deleted
+ * branch holds nothing. That distinction is the reader's (`migration-inventory`)
+ * and is simply carried through here.
+ *
+ * @module migration-held-set
+ */
+import { readMigrationInventory, defaultMigrationInventoryDeps, } from './migration-inventory.js';
+import { declaredOrdinalWidth } from './migration-manifest.js';
+/** Real git, real declaration reader, real clock. */
+export function defaultMigrationHeldSetDeps() {
+    return { ...defaultMigrationInventoryDeps(), now: () => Date.now() };
+}
+/**
+ * The ordinals a ref's JOURNAL registers, normalised to the product's width.
+ *
+ * WHY THE JOURNAL COUNTS AT ALL. On a hand-registered product the journal is
+ * half the record: a migration is its numbered filename AND its `idx` entry. A
+ * ref can register an idx whose file is not visible -- mid-rename, a file
+ * removed but the entry left, a journal edited ahead of the file -- and a held
+ * set built from filenames alone reports that number free. The allocator then
+ * grants it, and the product ends with two migrations at one position, which is
+ * the failure this whole mechanism exists to remove.
+ *
+ * WHY NORMALISATION IS REQUIRED, NOT COSMETIC. The journal records `idx` as a
+ * NUMBER (352) while the filename carries it zero-padded (`0352`). Unioning the
+ * two raw would put both `352` and `0352` in the held set -- two widths -- and
+ * the candidate rule refuses a product whose ordinals are not one fixed width.
+ * A naive union would therefore break every claim on exactly the products this
+ * fixes. So a journal idx is padded to the width the product uses.
+ *
+ * WHEN IT CANNOT BE NORMALISED, THE READING IS INCOMPLETE. An idx wider than
+ * the width, one that is not a plain number, and -- the case this argument was
+ * missing -- ANY idx at all when no width is established. Dropping such an
+ * entry silently is the fail-open; guessing a placement is worse; and using the
+ * raw value is worst, because it is neither dropped nor refused but published
+ * as though it were a number on this product. It is reported instead, and the
+ * caller refuses to grant against the reading rather than granting around the
+ * part it could not read.
+ *
+ * @param width The product's ordinal width, or null when none is established.
+ *              See `resolveOrdinalWidth`.
+ */
+export function journalOrdinals(journal, width) {
+    if (journal === undefined || journal.length === 0) {
+        return { ordinals: [], unnormalisable: [] };
+    }
+    const ordinals = [];
+    const unnormalisable = [];
+    for (const entry of journal) {
+        const idx = entry.idx.trim();
+        if (!/^\d+$/.test(idx) || width === null || idx.length > width) {
+            unnormalisable.push(entry.idx);
+            continue;
+        }
+        ordinals.push(idx.padStart(width, '0'));
+    }
+    return { ordinals, unnormalisable };
+}
+/**
+ * The width this product's ordinals are padded to, across the WHOLE reading.
+ *
+ * A PROPERTY OF THE PRODUCT, NOT OF ONE REF. It used to be derived per ref,
+ * from that ref's own filenames -- so a ref holding only a journal entry had no
+ * width, and a ref holding files a moment before the reading had one. The width
+ * a number is padded to cannot depend on which branch you happen to be looking
+ * at; it is the product's numbering convention, and it is read once for the
+ * whole reading.
+ *
+ * Declaration first (it fixes the width authoritatively -- no inventoried file
+ * can disagree with a pattern it had to match), then the files, which must all
+ * agree. Null when neither establishes one: a product with no declared width
+ * and no files. Every journal entry is then unnormalisable and the reading is
+ * incomplete, which is the honest answer -- the alternative was publishing a
+ * bare `351` and granting `352` into a four-digit namespace.
+ */
+export function resolveOrdinalWidth(declaredWidth, fileOrdinals) {
+    if (declaredWidth !== null)
+        return declaredWidth;
+    const widths = [...new Set(fileOrdinals.map((o) => o.length))];
+    return widths.length === 1 ? (widths[0] ?? null) : null;
+}
+/** The commit `ref` points at, or null when it cannot be resolved. */
+function resolveTip(repoPath, ref, deps) {
+    const result = deps.runGit(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], repoPath);
+    if (!result.success)
+        return null;
+    const tip = result.output.trim();
+    return tip === '' ? null : tip;
+}
+/** Ask one ref what it holds, or abort the whole reading. */
+function readRefRaw(repoPath, ref, deps) {
+    // RESOLVE FIRST, THEN READ AT THE SHA. A branch is a MUTABLE pointer: read
+    // through the name and resolve afterwards, and the tip can name a commit
+    // the inventory never saw -- a reading that claims a provenance it does not
+    // have, which is worse than no provenance at all, because it looks sound.
+    // Reading at the resolved sha makes the two agree by construction: a sha is
+    // immutable, so nothing the branch does afterwards can move what was read.
+    const tip = resolveTip(repoPath, ref, deps);
+    if (tip === null) {
+        // No immutable point to read at. Not an absence -- `readMigrationInventory`
+        // distinguishes that -- so ask it, and let it say which.
+        const unresolved = readMigrationInventory(repoPath, ref, deps);
+        if (unresolved.kind === 'refAbsent') {
+            return { ok: { ref, tip: null, outcome: 'absent' } };
+        }
+        if (unresolved.kind === 'undeclared')
+            return { abort: { kind: 'undeclared' } };
+        if (unresolved.kind === 'declarationUnreadable') {
+            return { abort: { kind: 'declarationUnreadable', reason: unresolved.reason } };
+        }
+        // It read through the mutable name but has no sha: an anchorless reading.
+        // Its ordinals still count as TAKEN -- dropping them would be the
+        // fail-open this module exists to avoid -- but the reading is incomplete,
+        // because a claim granted against it could never be re-checked.
+        return {
+            ok: {
+                ref,
+                tip: null,
+                outcome: 'unreadable',
+                ...(unresolved.kind === 'read' ? { inventory: unresolved.inventory } : {}),
+                reason: `${ref} carries no resolvable sha, so the reading has no point to `
+                    + 're-check a claim against',
+            },
+        };
+    }
+    // Everything below is read AT `tip`, never through `ref`.
+    const result = readMigrationInventory(repoPath, tip, deps);
+    switch (result.kind) {
+        case 'read':
+            return { ok: { ref, tip, outcome: 'read', inventory: result.inventory } };
+        case 'refAbsent':
+            // The sha resolved a moment ago and is gone now (a prune between the
+            // two calls). That is not an established absence of the BRANCH, so it
+            // is treated as unreadable rather than as "holds nothing".
+            return {
+                ok: {
+                    ref,
+                    tip,
+                    outcome: 'unreadable',
+                    reason: `${ref} resolved to ${tip}, which was then unreadable`,
+                },
+            };
+        case 'refUnreadable':
+            return { ok: { ref, tip: null, outcome: 'unreadable', reason: result.reason } };
+        case 'undeclared':
+        case 'declarationUnreadable':
+            // The declaration was read once above; a mid-walk change means the
+            // reading can no longer be trusted as a whole.
+            return {
+                abort: result.kind === 'undeclared'
+                    ? { kind: 'undeclared' }
+                    : { kind: 'declarationUnreadable', reason: result.reason },
+            };
+    }
+}
+/** Pass two: normalise one raw reading against the product's width. */
+function foldRefReading(raw, width) {
+    const files = raw.inventory?.migrations.map((m) => m.ordinal) ?? [];
+    const journal = journalOrdinals(raw.inventory?.journal, width);
+    const ordinals = [...new Set([...files, ...journal.ordinals])].sort();
+    // An unnormalisable entry is a registered position this reader cannot place
+    // in the sequence. Granting around it would be granting against a partial
+    // view, so it makes the reading incomplete exactly as an unreadable ref does.
+    const unplaceable = journal.unnormalisable.length > 0
+        ? (width === null
+            ? `${raw.ref} registers journal entries (${journal.unnormalisable.join(', ')}) but this `
+                + 'product establishes no ordinal width -- no file to read one from and no fixed '
+                + 'width in its declaration -- so they cannot be placed in the sequence'
+            : `${raw.ref} registers journal entries whose idx cannot be placed in `
+                + `this product's numbering (${journal.unnormalisable.join(', ')})`)
+        : null;
+    const reason = raw.reason ?? unplaceable ?? undefined;
+    return {
+        reading: {
+            ref: raw.ref,
+            tip: raw.tip,
+            outcome: raw.outcome,
+            ordinals,
+            ...(reason !== undefined ? { reason } : {}),
+        },
+        complete: raw.outcome !== 'unreadable' && unplaceable === null,
+    };
+}
+/**
+ * Read every ref and fold what they hold into one set.
+ *
+ * @param repoPath The product's repo root.
+ * @param refs     Integration plus every live focus branch. Duplicates are fine
+ *                 (a focus whose branch IS integration reads once).
+ */
+export function computeMigrationHeldSet(repoPath, refs, deps = defaultMigrationHeldSetDeps()) {
+    let scheme;
+    let declaredWidth;
+    try {
+        const manifest = deps.readManifest(repoPath);
+        if (manifest === undefined)
+            return { kind: 'undeclared' };
+        scheme = manifest.scheme;
+        declaredWidth = declaredOrdinalWidth(manifest.filePattern);
+    }
+    catch (err) {
+        return { kind: 'declarationUnreadable', reason: String(err?.message ?? err) };
+    }
+    const raws = [];
+    for (const ref of [...new Set(refs)]) {
+        const outcome = readRefRaw(repoPath, ref, deps);
+        if ('abort' in outcome)
+            return outcome.abort;
+        raws.push(outcome.ok);
+    }
+    const width = resolveOrdinalWidth(declaredWidth, raws.flatMap((raw) => raw.inventory?.migrations.map((m) => m.ordinal) ?? []));
+    const readings = [];
+    const held = new Set();
+    let complete = true;
+    for (const raw of raws) {
+        const folded = foldRefReading(raw, width);
+        if (!folded.complete)
+            complete = false;
+        for (const ordinal of folded.reading.ordinals)
+            held.add(ordinal);
+        readings.push(folded.reading);
+    }
+    return {
+        kind: 'held',
+        heldSet: {
+            scheme,
+            held: [...held].sort(),
+            readings,
+            complete,
+            readAt: deps.now(),
+        },
+    };
+}
+//# sourceMappingURL=migration-held-set.js.map

package/dist/migrations/migration-held-set.js.map

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

package/dist/migrations/migration-inventory.d.ts

@@ -0,0 +1,187 @@
+/**
+ * What a git REF holds in a product's declared migration namespace.
+ *
+ * WHY IT READS THE GIT TREE AND NEVER A WORKING TREE
+ * --------------------------------------------------
+ * The whole point of this module is to answer the question for a branch that is
+ * NOT checked out. Two focuses are armed concurrently on one product, each in
+ * its own worktree; the allocator that grants a migration number has to know
+ * what the OTHER focus's branch already holds, and the daemon never checks that
+ * branch out. So every read here is `git ls-tree` / `git show` against a ref.
+ *
+ * A reader that looked at a working tree could only ever see the branch it is
+ * standing on -- which is exactly the blind spot that lets two teams take the
+ * same number.
+ *
+ * WHY THE OUTCOMES ARE KEPT DISTINCT
+ * ----------------------------------
+ * This reader answers with one of five things, and collapsing any pair of them
+ * breaks a consumer:
+ *
+ *   - `undeclared`          -- the product ships no `telora.migrations.json`.
+ *                              It opted out. Its teams keep numbering as they
+ *                              do today; nothing should hold or refuse.
+ *   - `declarationUnreadable` -- a declaration EXISTS and is broken. A claim
+ *                              against this product must be REFUSED with the
+ *                              reason, not granted a guessed number.
+ *   - `refAbsent`           -- the ref does not exist (a deleted branch, a stale
+ *                              `branch_name`). It CLAIMS NOTHING. Holding here
+ *                              would let one stale row block every future claim
+ *                              on the product.
+ *   - `refUnreadable`       -- the ref exists and could not be read. It PROVES
+ *                              NOTHING. This is the one that must hold: read as
+ *                              an empty inventory it would say "every number is
+ *                              free", failing open on precisely the question
+ *                              this reader exists to answer.
+ *   - `read`                -- the ordinals, tags and journal entries the ref
+ *                              holds. Possibly EMPTY, which is a real answer:
+ *                              "this ref holds no migrations".
+ *
+ * The last two are the load-bearing pair. `refAbsent` and `refUnreadable` are
+ * both "git said no", and a reader that returned one kind for both would force
+ * its caller either to hold on a deleted branch forever or to treat an I/O
+ * failure as proof of absence. So absence is POSITIVELY ESTABLISHED rather than
+ * inferred from a non-zero exit: `probeRefExists` is three-valued, and only a
+ * healthy repository that still cannot resolve the ref yields `refAbsent`.
+ * Everything else -- including a probe that itself failed -- is `refUnreadable`.
+ * Both probes run only on the failure path, so the happy path pays nothing.
+ *
+ * SCOPE: THIS IS A READER
+ * -----------------------
+ * It answers "what does this ref hold?" for ONE ref. It does not compare two
+ * refs, judge a merge, or render a notice -- a comparison at the merge is the
+ * shape this focus abandoned (two teams told to renumber from the same union at
+ * the same moment collide again). The allocator consumes this to compute a
+ * candidate; nothing here decides anything.
+ *
+ * WHY THE GIT PRIMITIVE COMES FROM daemon-core
+ * --------------------------------------------
+ * `runGit` is taken from `@telora/daemon-core` rather than the daemon's own
+ * `git/types.ts` wrapper: this area is a rank-0 leaf in
+ * `scripts/daemon-layer-ranks.json` and `git/` sits above it, so importing the
+ * wrapper would be an upward import. The wrapper adds only a default timeout,
+ * which is passed explicitly here.
+ *
+ * @module migration-inventory
+ */
+import { type GitResult } from '@telora/daemon-core';
+import { type MigrationManifest, type MigrationManifestFs } from './migration-manifest.js';
+/** One migration file a ref holds. */
+export interface MigrationEntry {
+    /**
+     * The migration's number, captured as a STRING by the declared pattern.
+     *
+     * Never parsed to a number: both live schemes are zero-padded fixed width
+     * (`0352`, `20260614172757`), so string comparison IS ordinal comparison, and
+     * a parse could only lose the padding that makes that true.
+     */
+    ordinal: string;
+    /** The migration's name, recorded alongside the number on a claim. */
+    tag: string;
+    /** Repo-relative path of the file at the ref. */
+    path: string;
+}
+/** One entry the journal registers, when the product keeps a journal. */
+export interface JournalEntry {
+    /** The registered index, kept as a string for the same reason as `ordinal`. */
+    idx: string;
+    /** The tag the journal registers at that index. */
+    tag: string;
+}
+/** Everything one ref holds in the declared migration namespace. */
+export interface MigrationInventory {
+    /** The ref this was read from, as given (a branch name or a sha). */
+    ref: string;
+    /** Migrations at the ref, in the order git listed them. May be empty. */
+    migrations: MigrationEntry[];
+    /** Journal entries at the ref; undefined when the product declares no journal. */
+    journal: JournalEntry[] | undefined;
+}
+/** The five distinguishable outcomes of asking a ref what it holds. */
+export type MigrationInventoryResult = {
+    kind: 'undeclared';
+} | {
+    kind: 'declarationUnreadable';
+    reason: string;
+} | {
+    kind: 'refAbsent';
+    ref: string;
+} | {
+    kind: 'refUnreadable';
+    ref: string;
+    reason: string;
+} | {
+    kind: 'read';
+    inventory: MigrationInventory;
+};
+/** Injected seams: git and the declaration reader. Tests pass fakes. */
+export interface MigrationInventoryDeps {
+    /** Run git in `repoPath`. Must not throw; a failure is reported on the result. */
+    runGit: (args: string[], repoPath: string) => GitResult;
+    /** Read the product's declaration. Throws when the declaration is malformed. */
+    readManifest: (repoPath: string, fs?: MigrationManifestFs) => MigrationManifest | undefined;
+}
+/** Real git + real declaration reader. */
+export declare function defaultMigrationInventoryDeps(): MigrationInventoryDeps;
+/**
+ * Parse a journal document into its entries.
+ *
+ * Accepts the two shapes the hand-written products ship: a bare array of
+ * entries, or an object carrying an `entries` array. Anything else -- including
+ * an entry missing `idx` or `tag` -- is a parse FAILURE, because a journal we
+ * cannot read is the unreadable state, never an empty registration.
+ */
+export declare function parseJournal(text: string): {
+    entries: JournalEntry[];
+} | {
+    error: string;
+};
+/**
+ * Which of a ref's listed files are migrations, read through the declared
+ * pattern. Pure.
+ *
+ * A file in the migration dir that does NOT match the pattern is not a
+ * migration (a README, a .gitkeep, a `meta/` subdirectory) -- not a failure.
+ */
+export declare function readMigrationsFromPaths(paths: readonly string[], manifest: MigrationManifest): MigrationEntry[];
+/** What a ref-existence probe could establish. */
+export type RefProbe = 'present' | 'absent' | 'indeterminate';
+/**
+ * Does `ref` name a commit in this repo -- and could we even tell?
+ *
+ * THREE-VALUED ON PURPOSE. `git rev-parse --verify --quiet` exits non-zero for
+ * BOTH a missing ref and an operational failure (a corrupt object store, a
+ * timeout, a repo that is not there). Collapsing those to a boolean is a
+ * fail-OPEN: an unreadable branch is reported as holding nothing, the held set
+ * still reads complete, and the allocator grants a number that branch already
+ * holds -- which is the exact failure the reader exists to prevent.
+ *
+ * ABSENCE MUST BE POSITIVELY ESTABLISHED, and that takes two facts: the
+ * REPOSITORY answers, and the REF does not. So a failed ref probe is followed
+ * by a repo-health probe; only a healthy repo that still cannot resolve the ref
+ * proves the ref is gone. Anything else is `indeterminate`, and the caller
+ * treats that as unreadable.
+ *
+ * `--quiet` suppresses git's missing-ref message, so a genuine absence writes
+ * NOTHING to stderr. Output on stderr is therefore a second, independent signal
+ * that something operational went wrong, and is honoured even if the health
+ * probe happens to pass.
+ *
+ * Called ONLY after a read of the ref has already failed, so the happy path
+ * pays nothing for the distinction.
+ */
+export declare function probeRefExists(repoPath: string, ref: string, deps: MigrationInventoryDeps): RefProbe;
+/**
+ * What `ref` holds in `repoPath`'s declared migration namespace.
+ *
+ * Never throws. A malformed declaration, a missing ref, a failed git call and an
+ * unparseable journal each come back as their OWN kind, so a caller can refuse
+ * on a broken declaration, ignore an absent ref, and hold on an unreadable one
+ * without having to guess which it got.
+ *
+ * @param repoPath The product's repo root (`config.products[].repoPath`).
+ * @param ref      Any git ref -- a branch name or a sha. Need not be checked out.
+ * @param deps     Injectable git + declaration seams; defaults to the real ones.
+ */
+export declare function readMigrationInventory(repoPath: string, ref: string, deps?: MigrationInventoryDeps): MigrationInventoryResult;
+//# sourceMappingURL=migration-inventory.d.ts.map

package/dist/migrations/migration-inventory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-inventory.d.ts","sourceRoot":"","sources":["../../src/migrations/migration-inventory.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AAEH,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AAEjC,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC;IACZ,yEAAyE;IACzE,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,kFAAkF;IAClF,OAAO,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC;CACrC;AAED,uEAAuE;AACvE,MAAM,MAAM,wBAAwB,GAChC;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GACtB;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEpD,wEAAwE;AACxE,MAAM,WAAW,sBAAsB;IACrC,kFAAkF;IAClF,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,SAAS,CAAC;IACxD,gFAAgF;IAChF,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,mBAAmB,KAAK,iBAAiB,GAAG,SAAS,CAAC;CAC7F;AAED,0CAA0C;AAC1C,wBAAgB,6BAA6B,IAAI,sBAAsB,CAKtE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAiC1F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,QAAQ,EAAE,iBAAiB,GAC1B,cAAc,EAAE,CAYlB;AAED,kDAAkD;AAClD,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,sBAAsB,GAC3B,QAAQ,CAQV;AA6BD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,sBAAwD,GAC7D,wBAAwB,CAwC1B"}