@tokenfactory/acc-runner 0.41.7 → 0.43.0

package/dist/machine-capabilities/report.js

@@ -0,0 +1,211 @@
+/**
+ * AX-H1 (MACHINE-CAPABILITIES): the reporter — decide WHETHER to probe on this
+ * AS-1 cadence tick, and record the result.
+ *
+ * WHY A GATE AND NOT JUST "PROBE EVERY TICK". AX-H1 rides the AS-1 cadence
+ * (account-probe.ts) rather than adding a loop of its own, and that cadence ticks
+ * every ~60s while the runner is capacity-paused. An account probe is a config
+ * read; a capability probe shells out to gh, git and every engine — four to six
+ * subprocesses. Firing that every minute forever would make a cheap loop
+ * expensive and would rewrite an unchanged row all day.
+ *
+ * So the gate has three rules, in priority order:
+ *
+ *   1. FIRST TICK always probes. A machine that never reports is a machine ACC
+ *      cannot describe, which is the whole gap.
+ *   2. AN ACCOUNT CHANGE always probes. A login swap is precisely when the engine
+ *      rows went stale, and it is the AS-1 signal that already exists.
+ *   3. Otherwise probe at most once per `probeMinIntervalMs` (default 15 min).
+ *
+ * …and the WRITE has one more: an unchanged snapshot is only re-recorded once per
+ * `refreshMinIntervalMs` (default 6 h), so `probed_at` still proves liveness
+ * without an unchanged row being written 96 times a day. `snapshotFingerprint`
+ * decides "unchanged" over the whole sanitized document, so a version bump or a
+ * lost gh login is a change and a reordered scope list is not.
+ *
+ * FULLY injectable (probe / rpc / clock) so both gates are asserted with a fake
+ * clock and zero subprocesses.
+ */
+import { sanitizeSnapshot } from "./redact.js";
+/** Minimum gap between host probes on the shared AS-1 cadence. */
+export const DEFAULT_PROBE_MIN_INTERVAL_MS = 15 * 60_000;
+/** Minimum gap between re-recording an UNCHANGED snapshot (liveness refresh). */
+export const DEFAULT_REFRESH_MIN_INTERVAL_MS = 6 * 60 * 60_000;
+/**
+ * A stable content fingerprint of a snapshot. Deliberately excludes nothing:
+ * every field that reaches the server is in it, so "unchanged" means the recorded
+ * row would be byte-identical. Sorted keys, so JSON key order cannot make an
+ * unchanged machine look changed.
+ */
+export function snapshotFingerprint(snapshot) {
+    return JSON.stringify(snapshot, (_key, value) => {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const obj = value;
+            return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]));
+        }
+        return value;
+    });
+}
+/**
+ * Drives the capability probe on somebody else's cadence. Holds only the last
+ * fingerprint + two timestamps, so it is cheap to keep for the process lifetime
+ * and has no timer of its own — which is what makes "there is exactly one probe
+ * loop on this host" structurally true rather than a claim in a comment.
+ */
+export class MachineCapabilityReporter {
+    deps;
+    probeMinIntervalMs;
+    refreshMinIntervalMs;
+    now;
+    lastProbeAt = null;
+    lastRecordAt = null;
+    lastFingerprint = null;
+    lastAccountKey = null;
+    seq = 0;
+    /** Serial chain so two triggers never probe concurrently or record out of order. */
+    tail = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+        this.probeMinIntervalMs = Math.max(0, deps.probeMinIntervalMs ?? DEFAULT_PROBE_MIN_INTERVAL_MS);
+        this.refreshMinIntervalMs = Math.max(0, deps.refreshMinIntervalMs ?? DEFAULT_REFRESH_MIN_INTERVAL_MS);
+        this.now = deps.now ?? Date.now;
+    }
+    /** The last recorded fingerprint (null before the first successful probe). */
+    fingerprint() {
+        return this.lastFingerprint;
+    }
+    /** Resolve once every queued tick has settled (test seam). */
+    async settle() {
+        await this.tail;
+    }
+    /**
+     * Note one AS-1 cadence tick. `accountKey` is the AS-1 `synthetic_account` of
+     * the identity that tick resolved: when it moves, the engine rows are stale by
+     * definition and the throttle is bypassed.
+     *
+     * Returns the outcome and never rejects — a capability report is
+     * best-effort telemetry and must never be able to fail a cadence tick.
+     */
+    onProbeTick(args) {
+        const run = this.tail.then(() => this.tick(args));
+        // Keep the chain alive even if a tick rejects (it should not — tick catches).
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    shouldProbe(accountKey) {
+        if (this.lastProbeAt === null)
+            return { probe: true, reason: "first-probe" };
+        if (accountKey !== null && accountKey !== this.lastAccountKey) {
+            return { probe: true, reason: "account-changed" };
+        }
+        const age = this.now() - this.lastProbeAt;
+        if (age >= this.probeMinIntervalMs)
+            return { probe: true, reason: "interval-elapsed" };
+        return { probe: false, reason: "throttled" };
+    }
+    async tick(args) {
+        const accountKey = args.accountKey ?? null;
+        const decision = this.shouldProbe(accountKey);
+        // A skip is only ever reached when the account is UNCHANGED (rule 2 above
+        // outranks the throttle), so nothing is lost by not tracking the key here.
+        if (!decision.probe) {
+            return { action: "skipped", reason: "throttled" };
+        }
+        let snapshot;
+        try {
+            // Sanitized again here even though probe.ts already sanitizes: this class
+            // accepts an INJECTED probe, and the redaction boundary must not depend on
+            // which probe was injected.
+            snapshot = sanitizeSnapshot(await this.deps.probe());
+        }
+        catch (err) {
+            this.deps.onLog?.(`[acc-runner] machine-capability probe (${args.trigger}) failed: ${err?.message ?? String(err)}`);
+            return { action: "failed", reason: "probe-threw" };
+        }
+        const at = this.now();
+        this.lastProbeAt = at;
+        if (accountKey !== null)
+            this.lastAccountKey = accountKey;
+        const fingerprint = snapshotFingerprint(snapshot);
+        const changed = fingerprint !== this.lastFingerprint;
+        const refreshDue = this.lastRecordAt === null || at - this.lastRecordAt >= this.refreshMinIntervalMs;
+        if (!changed && !refreshDue) {
+            return {
+                action: "probed",
+                recorded: false,
+                changed: false,
+                reason: "unchanged",
+                probeReason: decision.reason,
+            };
+        }
+        if (!this.deps.transport) {
+            this.lastFingerprint = fingerprint;
+            return {
+                action: "probed",
+                recorded: false,
+                changed,
+                reason: "no-transport",
+                probeReason: decision.reason,
+            };
+        }
+        const report = {
+            snapshot,
+            trigger: args.trigger,
+            seq: ++this.seq,
+        };
+        const recorded = await recordMachineCapabilities(this.deps.transport, report, {
+            runnerId: this.deps.runnerId ?? null,
+            onLog: this.deps.onLog,
+        });
+        if (recorded) {
+            this.lastRecordAt = at;
+            this.lastFingerprint = fingerprint;
+        }
+        return {
+            action: "probed",
+            recorded,
+            changed,
+            reason: changed ? "changed" : "liveness-refresh",
+            probeReason: decision.reason,
+        };
+    }
+}
+/**
+ * Send one report to `acc.record_machine_capabilities`. Returns false (and logs)
+ * on any failure rather than throwing: a pre-0310 server 404s this RPC, and an
+ * operator on an older deploy must not have their runner wedged by a telemetry
+ * write — the same non-fatal contract `set_runner_capabilities` uses in watch.ts.
+ *
+ * The snapshot is sanitized ONE more time on the way out. That is not paranoia
+ * theatre: this function is exported and callable with an arbitrary snapshot, and
+ * the invariant it has to hold is "nothing that leaves this process carries
+ * credential material", not "nothing that leaves this class does".
+ */
+export async function recordMachineCapabilities(transport, report, opts = {}) {
+    const snapshot = sanitizeSnapshot(report.snapshot);
+    try {
+        const { error } = await transport.rpc("record_machine_capabilities", {
+            p_machine: snapshot.machine,
+            p_runner_id: opts.runnerId ?? null,
+            p_platform: snapshot.platform,
+            p_arch: snapshot.arch,
+            p_runner_version: snapshot.runner_version || null,
+            p_tools: snapshot.tools,
+            p_engines: snapshot.engines,
+            p_probe_trigger: report.trigger,
+            p_probe_seq: report.seq,
+            // No timestamp argument by design: probed_at is server time (0310 §4), so a
+            // host with a wrong clock cannot win last-writer-wins forever.
+        });
+        if (error) {
+            opts.onLog?.(`[acc-runner] record_machine_capabilities failed (continuing): ${error.message}`);
+            return false;
+        }
+        return true;
+    }
+    catch (err) {
+        opts.onLog?.(`[acc-runner] record_machine_capabilities threw (continuing): ${err?.message ?? String(err)}`);
+        return false;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/machine-capabilities/report.js.map

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

package/dist/machine-capabilities/types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * AX-H1 (MACHINE-CAPABILITIES): the shapes a host reports about ITSELF.
+ *
+ * The one rule these types exist to encode (AUTH_APPROVAL_BRIEF.md §7.1 + the
+ * MLSA plan): NO CREDENTIAL EVER TRANSITS ACC. Every field below is either
+ *
+ *   - PRESENCE   — is the tool installed, does it authenticate, which version;
+ *   - IDENTITY   — which login / email / plan / scope-set it resolves to;
+ *   - PROVENANCE — which host, which runner, which AS-1 probe trigger.
+ *
+ * There is deliberately no field that could hold a token, and the field set is
+ * CLOSED on three sides: `sanitizeSnapshot` (redact.ts) rebuilds every record
+ * from these fields before it leaves the host,
+ * `acc._normalize_machine_capability_{tools,engines}` (migration 0310) rebuilds
+ * it again from the same whitelist server-side, and two CHECK constraints reject
+ * anything shaped like a credential at rest. Adding a field here without adding
+ * it to BOTH whitelists means the field is silently dropped, which is the
+ * intended failure direction.
+ *
+ * DECLARATIONS ONLY — no behaviour, no I/O, so the contract can be asserted
+ * against the SQL mirror in a unit test.
+ */
+import type { EngineAuthMode, EnginePlanHint } from "../engines/types.js";
+/**
+ * The host tools ACC probes. Mirrors `acc.machine_capability_tools()` (0310 §1)
+ * and `HOST_TOOLS` in api/_lib/machine-capabilities.ts — the unit suite asserts
+ * all three agree, so a tool added on one side cannot silently be dropped by
+ * the writer's whitelist on another.
+ *
+ * Deliberately NOT the `acc.runners.capabilities` vocabulary (0114/0115): those
+ * are routing tags an operator DECLARES; these are tools ACC PROBES.
+ */
+export declare const HOST_TOOLS: readonly ["gh", "git"];
+export type HostTool = (typeof HOST_TOOLS)[number];
+/** What one host tool offers. Presence + identity only. */
+export interface ToolCapability {
+    /** Which tool this row describes. */
+    tool: HostTool;
+    /** The binary resolved on the (launchd-augmented) PATH. */
+    present: boolean;
+    /** Reported version, e.g. "2.62.0". Null when absent or unparseable. */
+    version: string | null;
+    /**
+     * The tool holds a working credential. For `gh` this is `gh auth status`
+     * exiting 0; `git` has no host-level login of its own, so it reports false.
+     */
+    authenticated: boolean;
+    /**
+     * WHO the tool acts as: the gh account login, or git's `user.email`. An
+     * identity, never a credential — and null rather than guessed when unknown.
+     */
+    identity: string | null;
+    /** The host the credential is for (gh: github.com / a GHES hostname). */
+    host: string | null;
+    /**
+     * The AUTHORITY LABELS a gh token carries ("repo", "read:org"). These are what
+     * make "can this machine open a PR" answerable. The token itself is never
+     * read: `gh auth status --show-token` is never invoked anywhere in this
+     * package, and the unit suite asserts that.
+     */
+    scopes: string[];
+    /** Masked, credential-safe one-line summary — safe to log, store and display. */
+    detail: string;
+}
+/** What one coding engine offers on this host. */
+export interface EngineCapability {
+    /** Engine registry id (claude-code | codex | gemini). */
+    engine_id: string;
+    /** The engine's binary resolved on PATH. */
+    present: boolean;
+    /** Reported version. Null when absent or unparseable. */
+    version: string | null;
+    /** The engine resolved a real, named account (not the honest-unknown identity). */
+    logged_in: boolean;
+    /** Which auth channel the identity resolved through (AS-1 `channel`). */
+    channel: EngineAuthMode;
+    /** The account the engine is logged in as, or null when unintrospectable. */
+    account_email: string | null;
+    /** Coarse plan hint; "unknown" when the engine cannot detect one. */
+    plan_hint: EnginePlanHint;
+    /** The AS-1 stable synthetic account id. Always set. */
+    synthetic_account: string;
+    /** Masked, credential-safe one-line summary. */
+    detail: string;
+}
+/** Everything one host reports about itself in a single probe. */
+export interface MachineCapabilitySnapshot {
+    /** os.hostname() — the operator-facing name of the machine. */
+    machine: string;
+    /** process.platform. */
+    platform: string;
+    /** process.arch. */
+    arch: string;
+    /** The acc-runner version that produced this snapshot. */
+    runner_version: string;
+    /** One row per probed host tool, in HOST_TOOLS order. */
+    tools: ToolCapability[];
+    /** One row per registered chat engine. */
+    engines: EngineCapability[];
+}
+/**
+ * A snapshot plus the AS-1 provenance of the probe that produced it. This is
+ * what `recordMachineCapabilities` sends to
+ * `acc.record_machine_capabilities` — note there is no timestamp: `probed_at` is
+ * server time, because a host with a wrong clock would otherwise win every
+ * last-writer-wins comparison forever (0310 §4).
+ */
+export interface MachineCapabilityReport {
+    snapshot: MachineCapabilitySnapshot;
+    /** Which AS-1 cadence trigger fired this probe. */
+    trigger: string;
+    /** The probing process's monotonic probe sequence. */
+    seq: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/machine-capabilities/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/machine-capabilities/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1E;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,wBAAyB,CAAC;AAEjD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,IAAI,EAAE,QAAQ,CAAC;IACf,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,yDAAyD;IACzD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,cAAc,CAAC;IACxB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,qEAAqE;IACrE,SAAS,EAAE,cAAc,CAAC;IAC1B,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kEAAkE;AAClE,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,wBAAwB;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,0CAA0C;IAC1C,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,yBAAyB,CAAC;IACpC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/machine-capabilities/types.js

@@ -0,0 +1,11 @@
+/**
+ * The host tools ACC probes. Mirrors `acc.machine_capability_tools()` (0310 §1)
+ * and `HOST_TOOLS` in api/_lib/machine-capabilities.ts — the unit suite asserts
+ * all three agree, so a tool added on one side cannot silently be dropped by
+ * the writer's whitelist on another.
+ *
+ * Deliberately NOT the `acc.runners.capabilities` vocabulary (0114/0115): those
+ * are routing tags an operator DECLARES; these are tools ACC PROBES.
+ */
+export const HOST_TOOLS = ["gh", "git"];
+//# sourceMappingURL=types.js.map

package/dist/machine-capabilities/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/machine-capabilities/types.ts"],"names":[],"mappings":"AAwBA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,KAAK,CAAU,CAAC"}

package/dist/migration-seq-guard.d.ts

@@ -0,0 +1,78 @@
+/** Kill switch. Set to `0`/`false` to skip the pre-push re-validation entirely. */
+export declare const SEQ_GUARD_ENV = "ACC_MIGRATION_SEQ_GUARD";
+/** Every reason the guard can decline to renumber, for the runner log. */
+export type SeqGuardSkipReason = "disabled" | "no-base-ref" | "no-new-migrations" | "no-remote-seqs" | "seq-free" | "renumber-noop" | "renumber-failed";
+export interface SeqGuardRenumber {
+    /** Repo-relative path the migration had before the guard ran. */
+    file: string;
+    /** Repo-relative path it now has. */
+    newFile: string;
+    /** Numeric seq before → after. */
+    fromSeq: number;
+    toSeq: number;
+    /** Tail of the renumber tool's own log (which refs it rewrote). */
+    output: string;
+}
+export interface SeqGuardResult {
+    /** True iff a migration was renumbered AND the rename was committed. */
+    renumbered: boolean;
+    /** Why nothing happened. Unset when `renumbered` is true. */
+    skipped?: SeqGuardSkipReason;
+    /** Human-readable one-liner for the runner log — always set. */
+    detail: string;
+    /** Highest seq seen on the freshly-fetched integration head (null if unread). */
+    remoteMaxSeq?: number | null;
+    /** The move, when one happened. */
+    move?: SeqGuardRenumber;
+}
+export interface SeqGuardOptions {
+    /** Integration branch this task will target, e.g. `acc/integration`. */
+    integrationBranch: string;
+    /** Merge-base ref the new-migration diff is taken against. */
+    baseRef?: string;
+    /** Remote to re-fetch. Defaults to `origin`. */
+    remote?: string;
+    /**
+     * Live `acc.applied_migrations` seqs, when the caller can read them. Unioned
+     * with the fresh remote head so a migration applied out-of-band still counts
+     * as claimed. Omitted → the remote head alone is the baseline.
+     */
+    appliedSeqs?: number[] | null;
+}
+export interface SeqGuardDeps {
+    env?: NodeJS.ProcessEnv;
+    /** `git fetch <remote> <branch>`. Rejects → treated as "no fresh head". */
+    fetchRef?: (workdir: string, remote: string, branch: string) => Promise<void>;
+    /**
+     * Migration paths present on the freshly-fetched head, repo-relative. Returns
+     * `null` when the ref could not be read (the guard then stands down).
+     */
+    listRemoteMigrations?: (workdir: string, ref: string) => Promise<string[] | null>;
+    /** Migration files this branch ADDED vs `baseRef`, repo-relative. */
+    listAddedMigrations?: (workdir: string, baseRef?: string) => Promise<string[]>;
+    /** Run the renumber pass with an out-of-tree baseline roster. */
+    runRenumber?: (workdir: string, files: string[], baselineSeqs: number[]) => Promise<{
+        output: string;
+    }>;
+    /** True when the working tree has uncommitted changes (did the renumber act?). */
+    isDirty?: (workdir: string) => Promise<boolean>;
+    /** Commit the rename so the push carries it. */
+    commit?: (workdir: string, message: string) => Promise<void>;
+}
+/**
+ * The numeric sequence prefix of a migration path (`…/0315_acc_x.sql` → 315),
+ * or null when the filename does not carry one. Mirrors `parseSeq` in
+ * scripts/ci/migration-lint.mjs — the two must agree on what counts as a
+ * migration, so both accept `_` and `-` after the digits.
+ */
+export declare function migrationSeq(file: string): number | null;
+/** Whether the guard is enabled. ON by default; `0`/`false`/`no` turns it off. */
+export declare function seqGuardEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Re-validate this branch's NEW migration seq against a freshly-fetched
+ * integration head and auto-renumber it when a sibling has since taken the
+ * number. Returns what happened; NEVER throws (a crash inside the guard is
+ * reported as `renumber-failed` and the push proceeds).
+ */
+export declare function revalidateMigrationSeq(workdir: string, opts: SeqGuardOptions, deps?: SeqGuardDeps): Promise<SeqGuardResult>;
+//# sourceMappingURL=migration-seq-guard.d.ts.map

package/dist/migration-seq-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-seq-guard.d.ts","sourceRoot":"","sources":["../src/migration-seq-guard.ts"],"names":[],"mappings":"AAkDA,mFAAmF;AACnF,eAAO,MAAM,aAAa,4BAA4B,CAAC;AAIvD,0EAA0E;AAC1E,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,aAAa,GACb,mBAAmB,GACnB,gBAAgB,GAChB,UAAU,GACV,eAAe,GACf,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;IACpB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,mCAAmC;IACnC,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAClF,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/E,iEAAiE;IACjE,WAAW,CAAC,EAAE,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,YAAY,EAAE,MAAM,EAAE,KACnB,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjC,kFAAkF;IAClF,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,gDAAgD;IAChD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxD;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAI7E;AAwGD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,EACrB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,cAAc,CAAC,CAgKzB"}