dorfl 0.0.0 → 0.1.0

package/dist/ledger-write.js

@@ -0,0 +1,411 @@
+import { randomUUID } from 'node:crypto';
+import { runAsync } from './git.js';
+import { Integrator, } from './integrator.js';
+import { routeToNeedsAttention, returnToBacklog, } from './needs-attention.js';
+import { markStuckItemLock, resumeItemLock, } from './item-lock.js';
+// --- The sole strategy: exactly today's behaviour -------------------------
+/** Run git, returning the raw result (no throw) — for soft checks. */
+function gitSoft(args, cwd, env) {
+    return runAsync('git', args, cwd, { env });
+}
+/** Run git; throw on non-zero (genuinely unexpected plumbing failures). */
+async function gitHard(args, cwd, env) {
+    const result = await runAsync('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+/** The git trailer key the per-attempt CAS nonce rides in (greppable, round-trips). */
+export const CAS_NONCE_TRAILER = 'CAS-Nonce';
+/**
+ * Rebuild the transition tip ({@link localBranch}'s commit, whose sha is {@link
+ * head}) into a NEW commit object that is byte-for-byte identical EXCEPT for a
+ * freshly-appended `CAS-Nonce: <uuid>` trailer, and return the new sha. This is
+ * the ONE chokepoint that makes EVERY {@link
+ * LedgerWriteStrategy.applyTransition} caller's CAS commit unique — create,
+ * claim, tasking-lock, advancing-lock, and the needs-attention/requeue surface
+ * all route their publish through `applyTransition`, so stamping HERE (the seam
+ * AMENDING the tip's message just before the push) covers all of them WITHOUT a
+ * shared commit-building helper and WITHOUT touching each commit site.
+ *
+ * It is built with `commit-tree` plumbing on the same tree + parent + ambient
+ * env identity as the tip, so it NEVER mutates the caller's working tree, index,
+ * or HEAD (safe from a job worktree mid-flight), and it preserves WHO/WHAT — it
+ * ONLY appends the trailer to the original message. The author/committer
+ * identity is pinned from the original commit so the stamp does not silently
+ * re-attribute the transition.
+ *
+ * A FRESH nonce is generated on EACH call — and `applyTransition` calls this once
+ * per ATTEMPT (each retry of a caller's outer refetch loop re-enters
+ * `applyTransition`), so two concurrent same-identity racers, and any single
+ * racer across its own retries, ALWAYS get distinct shas.
+ */
+async function stampNonce(params) {
+    const { localBranch, head, cwd, env } = params;
+    const nonce = randomUUID();
+    // Read the tip's tree + parents + author/committer identity + original message
+    // in ONE `git log` (one git subprocess, not four) — the body (%B, multi-line)
+    // MUST be last. Fields are NUL-separated (%x00); the trailing field is the raw
+    // body so its embedded newlines do not confuse the split.
+    const FIELD_SEP = '\u0000';
+    const raw = (await gitHard([
+        'log',
+        '-1',
+        `--format=%T%x00%P%x00%an%x00%ae%x00%aI%x00%cn%x00%ce%x00%B`,
+        head,
+    ], cwd, env)).stdout;
+    const fields = raw.split(FIELD_SEP);
+    const tree = (fields[0] ?? '').trim();
+    const parents = (fields[1] ?? '')
+        .trim()
+        .split(/\s+/)
+        .filter((p) => p.length > 0); // the tip's parents (usually exactly one)
+    const authorName = fields[2] ?? '';
+    const authorEmail = fields[3] ?? '';
+    const authorDate = fields[4] ?? '';
+    const committerName = fields[5] ?? '';
+    const committerEmail = fields[6] ?? '';
+    // The body is the last field; strip trailing whitespace before we append.
+    const message = (fields[7] ?? '').replace(/\s+$/, '');
+    // Pin the original author/committer so the stamp re-attributes nothing; we are
+    // only appending a trailer to the message.
+    const stampEnv = {
+        ...(env ?? process.env),
+        GIT_AUTHOR_NAME: authorName,
+        GIT_AUTHOR_EMAIL: authorEmail,
+        GIT_AUTHOR_DATE: authorDate,
+        GIT_COMMITTER_NAME: committerName,
+        GIT_COMMITTER_EMAIL: committerEmail,
+        // Deliberately do NOT pin GIT_COMMITTER_DATE: even two stamps with identical
+        // everything-else would still differ by the nonce, but leaving the committer
+        // date current is the honest "when this attempt was published".
+    };
+    // Append the trailer as its own block so it round-trips as a real git trailer.
+    const noncedMessage = `${message}\n\n${CAS_NONCE_TRAILER}: ${nonce}\n`;
+    const parentArgs = parents.flatMap((p) => ['-p', p]);
+    const result = await runAsync('git', ['commit-tree', tree, ...parentArgs, '-m', noncedMessage], cwd, { env: stampEnv });
+    if (result.status !== 0) {
+        throw new Error(`git commit-tree (CAS nonce stamp) failed (exit ${result.status}): ${result.stderr.trim()} — localBranch=${localBranch}`);
+    }
+    return result.stdout.trim();
+}
+/**
+ * The ONLY ledger-write strategy: current behaviour. It CAS-publishes the
+ * prepared transition commit to the arbiter's `main` — the `main` push and the
+ * `--force-with-lease=main:<base>` lease live HERE, not in the public input — and
+ * verifies the arbiter's `main` is now that commit (guarding against an
+ * "Everything up-to-date" push masquerading as a successful transition). A future
+ * strategy would be a different object implementing the same interface — chosen
+ * NOWHERE today (no mode/config selects it).
+ */
+export const currentLedgerWrite = {
+    async applyTransition({ arbiter, localBranch, expectedBase, head, cwd, dryRun, env, note, }) {
+        const emit = note ?? (() => { });
+        if (dryRun) {
+            const message = `[dry-run] would: git push ${arbiter} ${localBranch}:main --force-with-lease=main:${expectedBase}`;
+            emit(message);
+            return { kind: 'published', message };
+        }
+        // Stamp this ATTEMPT's transition commit with a FRESH random nonce (a real
+        // `CAS-Nonce: <uuid>` git trailer) so the pushed sha is UNIQUE per attempt.
+        // This is what makes the lease authoritative even for SAME-IDENTITY,
+        // SAME-CONTENT racers: without it, two racers who build an identical tree +
+        // message off the same base within git's 1-second timestamp resolution
+        // produce an IDENTICAL sha X. The first push ff's main to X; the second
+        // push of the SAME X degrades to "Everything up-to-date" (git exits 0, the
+        // lease has nothing to reject), and the post-push verify X === X passes — so
+        // BOTH would return `published`. The nonce gives each attempt a DISTINCT sha,
+        // so the loser's push finds main moved past <base> and is GENUINELY rejected
+        // by the lease, and the verify below correctly fails for it. The stamp is
+        // built with `commit-tree` plumbing (no checkout/HEAD mutation), reusing the
+        // tip's tree + parent + author/committer identity — it ONLY appends the
+        // trailer, leaving WHO/WHAT/the original message intact. Called per ATTEMPT
+        // (each retry of the caller's outer refetch loop re-enters here), so every
+        // attempt gets a fresh nonce, not one per process.
+        const nonced = await stampNonce({ localBranch, head, cwd, env });
+        // The atomic compare-and-swap. --force-with-lease=main:<base> asserts the
+        // arbiter's main is STILL <base> (unchanged since our fetch); the push then
+        // fast-forwards main to our (nonce'd, thus unique) commit. If main moved, the
+        // lease fails → rejected.
+        const push = await gitSoft([
+            'push',
+            arbiter,
+            `${nonced}:main`,
+            `--force-with-lease=main:${expectedBase}`,
+        ], cwd, env);
+        if (push.status === 0) {
+            // Verify the arbiter main now points at OUR (nonce'd) commit. INVARIANT:
+            // because the nonce makes our sha unique, a successful push can ONLY mean
+            // either (a) we genuinely ff'd main to our nonce'd commit (published), or
+            // (b) someone else's commit (a DIFFERENT nonce ⇒ a DIFFERENT sha) is already
+            // there and ours did NOT land — i.e. an "up-to-date / no change of our
+            // making" no-op, which is a LOSS. The nonce makes the two naturally
+            // distinguishable: `arbiterHead === nonced` iff WE won. So an up-to-date
+            // no-op can never satisfy this and is classified REJECTED, never published.
+            await gitHard(['fetch', '--quiet', arbiter], cwd, env);
+            const arbiterHead = (await gitHard(['rev-parse', `${arbiter}/main`], cwd, env)).stdout.trim();
+            if (arbiterHead === nonced) {
+                return {
+                    kind: 'published',
+                    message: 'transition published',
+                    publishedHead: nonced,
+                };
+            }
+            emit(`push reported up-to-date / no change of our making — ${arbiter}/main is not our commit — treating as rejected.`);
+        }
+        return { kind: 'rejected', message: 'push rejected / lease failed' };
+    },
+    /**
+     * The complete transition under the SAME strategy: integrate the prepared work
+     * branch back to the arbiter exactly as `complete.ts` did before — it builds
+     * the {@link Integrator} with the chosen provider and calls `integrate` (the
+     * branch was already rebased onto the latest arbiter ledger by the caller, so
+     * this is the non-rebasing `integrate`, never `--force`). `merge` ff's the
+     * branch to the arbiter's `main`; `propose` pushes the branch + asks the
+     * provider to request review. That `merge` targets `main` is an implementation
+     * detail of THIS strategy — the public input never names it.
+     */
+    async applyCompleteTransition({ arbiter, branch, mode, provider, noPR, title, body, deleteMergedHead, cwd, env, }) {
+        const integrator = new Integrator({ provider });
+        return integrator.integrate({
+            cwd,
+            arbiter,
+            branch,
+            mode,
+            noPR,
+            title,
+            body,
+            deleteMergedHead,
+            env,
+        });
+    },
+    /**
+     * The needs-attention transition under the SAME strategy. The seam's contract
+     * is transition-kind-agnostic: durably record a stuck job =
+     *
+     *   - **OBSERVABLE** — publish the stuck state to the ledger surface so
+     *     `scan`/`status`/a fresh checkout/another machine can see it. (THIS mode-M
+     *     strategy does that by CHERRY-PICKING the move-only commit — the reason +
+     *     the `git mv` — onto the arbiter's `main`, all-or-nothing, never `--force`d,
+     *     so the half-finished wip below it never lands there. A future mode-P
+     *     strategy could make it observable WITHOUT writing `main`, e.g. by reading
+     *     work-branch tips.)
+     *   - **RECOVERABLE** — push the work branch (when there IS one), so the saved
+     *     work travels cross-machine and a requeue continues from its tip. (Mode M
+     *     does that by `git push`ing the branch; the WHICH branch is the caller's,
+     *     not assumed `work/<slug>` — a build bounce pushes `work/<slug>`, a tasking
+     *     bounce its `work/prd-<slug>`, a temp-branch caller pushes NOTHING.)
+     *
+     * Both halves are ONE operation done in ONE place: it delegates to {@link
+     * routeToNeedsAttention}, which appends the reason as body prose (never a
+     * frontmatter field — WORK-CONTRACT rule 3), saves the aborted work as a
+     * **wip** commit, `git mv`s the item to `work/needs-attention/` as the
+     * **move-only** commit (the tip), and — when an `arbiter` is given — pushes the
+     * work branch (best-effort, branch-parameterised, emptiness-guarded; SURFACE-
+     * ONLY when `pushBranch: false`). The seam does NOT strip the arbiter: the same
+     * arbiter both publishes the surface (here) AND drives the helper's branch push,
+     * so "record stuck" and "save the work" can never drift apart. The human-vs-
+     * autonomous gate rides on whether an `arbiter` is given at all (human
+     * `complete` passes none → no surface, no push, local-only; autonomous `do`/`run`
+     * pass it → both).
+     */
+    async applyNeedsAttentionTransition(input) {
+        // BOUNCE = SAVE WIP + PUSH BRANCH (recoverable) + MARK LOCK STUCK (observable)
+        // — task `cutover-needs-attention-becomes-lock-stuck-recovery-surface`
+        // (decision i+). The OBSERVABLE half is now the per-item lock `state: stuck`
+        // (full reason prose + any agent-surfaced questions on the entry), NOT a
+        // `git mv` to `needs-attention/` and NOT an on-`main` surface — so a
+        // protected-`main` bounce succeeds and a branch cut from `main` inherits no
+        // stuck record. The RECOVERABLE half is UNCHANGED: {@link routeToNeedsAttention}
+        // commits the agent's uncommitted wip to the `work/<slug>` branch tip and
+        // pushes the branch (best-effort, branch-parameterised, emptiness-guarded,
+        // outage-retried), so the partial work travels cross-machine and a `requeue`
+        // continues from the tip. The work-branch push is NOT a `main` write.
+        const saved = await routeToNeedsAttention(input);
+        const stuck = await bounceToStuckLock({
+            cwd: input.cwd,
+            slug: input.slug,
+            reason: input.reason,
+            questions: input.questions,
+            arbiter: input.arbiter,
+            env: input.env,
+            note: input.note,
+        });
+        return {
+            // `moved` reflects the OBSERVABLE half (the stuck record): the lock amend.
+            moved: stuck.moved,
+            reasonNotMoved: stuck.reasonNotMoved,
+            // The branch push outcome is the honest RECOVERABLE report (`do`/`run` read
+            // it). The on-`main` surface half is GONE (the lock is the surface now).
+            branchPush: saved.branchPush,
+            pushError: saved.pushError,
+        };
+    },
+    /**
+     * The return-to-backlog transition under the SAME strategy: re-queue the
+     * stuck item by delegating to {@link returnToBacklog}, which moves the slug's
+     * current `work/<needs-attention|in-progress>/<slug>.md → work/backlog/<slug>.md`
+     * TREE-LESSLY — it
+     * builds the move off `<arbiter>/main` with plumbing and CAS-publishes it back
+     * THROUGH this same write seam (`applyTransition`, the very push+lease+verify
+     * `claim` uses), never staging/committing in the cwd working tree.
+     */
+    applyReturnToBacklogTransition(input) {
+        return returnToBacklog(input);
+    },
+    /**
+     * The tree-less surface transition under the SAME strategy: surface the stuck
+     * AFTER-COMMIT, LEDGER-ONLY item by delegating to the tree-less surface (now a pure lock amend),
+     * which moves `work/in-progress/<slug>.md → work/needs-attention/<slug>.md`
+     * (reason in the body) TREE-LESSLY — it builds the move off `<arbiter>/main` with
+     * plumbing and CAS-publishes it THROUGH this same write seam
+     * (`applyTransition`, the very push+lease+verify `claim`/`requeue` use), never
+     * staging/committing in the cwd working tree. The reverse of
+     * {@link applyReturnToBacklogTransition}, the same one mechanism.
+     */
+    async applyTreelessNeedsAttentionTransition(input) {
+        // PURE LOCK AMEND (task
+        // `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+):
+        // the after-commit / ledger-only surface (continue-push-failure /
+        // continue-rebase-conflict) is now the SAME `active → stuck` lock amend as the
+        // cwd-bound bounce — NO `git mv`, NO `main` write. The recoverable work is
+        // already committed on the kept `work/<slug>` branch (intact on the arbiter);
+        // the stuck reason + questions ride on the lock entry. A re-surface of an
+        // already-stuck item is a tolerated idempotent no-op (`wrong-state`).
+        const moved = await bounceToStuckLock({
+            cwd: input.cwd,
+            slug: input.slug,
+            reason: input.reason,
+            questions: input.questions,
+            arbiter: input.arbiter,
+            env: input.env,
+            note: input.note,
+        });
+        return { moved: moved.moved, reasonNotMoved: moved.reasonNotMoved };
+    },
+    /**
+     * The resolve-needs-attention transition under the SAME strategy — satisfying
+     * the INTENT "clear the stuck surface + restore in-progress." It delegates to
+     * the resume lock amend (reverse `git mv` needs-attention →
+     * in-progress, committed) and, when an `arbiter` is given, publishes that
+     * reverse move-only commit to the arbiter's `main` — CLEARING the stuck surface
+     * there (the item is back in in-progress on the ledger). Same all-or-nothing,
+     * never-`--force` publish. "Reverse-move on `main`" is a detail of THIS
+     * strategy; the seam's contract is only the intent "clear the surface."
+     */
+    async applyResolveNeedsAttentionTransition(input) {
+        // PURE LOCK AMEND (task
+        // `cutover-needs-attention-becomes-lock-stuck-recovery-surface`, decision i+):
+        // resolving a stuck item is `stuck → active` on the per-item lock (a human is
+        // picking it up), NOT a `needs-attention/ → in-progress/` folder move. NO `main`
+        // write — the body already rests in `backlog/` (task 9a) and the work stays on
+        // the kept `work/<slug>` branch. Without an arbiter there is no lock ref to
+        // amend (the human-local face), so it is a recorded no-op success.
+        if (!input.arbiter) {
+            return { moved: true };
+        }
+        const r = await resumeItemLock({
+            item: `task:${input.slug}`,
+            cwd: input.cwd,
+            arbiter: input.arbiter,
+            env: input.env,
+        });
+        if (r.outcome === 'transitioned') {
+            return { moved: true };
+        }
+        // `wrong-state` (already active — not actually stuck) is tolerated as a no-op
+        // success: the item is already in-flight, the caller onboards onto it anyway.
+        if (r.outcome === 'wrong-state') {
+            return { moved: true };
+        }
+        return {
+            moved: false,
+            reasonNotMoved: `could not resume '${input.slug}' (${r.outcome}: ${r.message}).`,
+        };
+    },
+};
+/**
+ * The SOLE stuck-state RECORD: amend the item's HELD per-item lock
+ * `active → stuck` + the FULL reason prose + any agent-surfaced questions, via the
+ * state machine's mark-stuck CAS amend ({@link markStuckItemLock}) — task
+ * `cutover-needs-attention-becomes-lock-stuck-recovery-surface` (decision i+; prd
+ * `ledger-status-per-item-lock-refs` US #5/#8; ADR
+ * `ledger-status-on-per-item-lock-refs`). This REPLACES the `git mv →
+ * needs-attention/` folder bounce + its on-`main` surface + branch push: the
+ * bounce now touches ONLY the lock ref (NO `main` write — so a protected-`main`
+ * bounce succeeds, and a work branch cut from `main` inherits no stuck record).
+ *
+ * The bounce holds the TASK's `implement` lock that `claim` acquired (task
+ * `claim-acquires-unified-lock-no-body-move`), so the normal stuck path is a plain
+ * `active → stuck` amend (`transitioned`). The OUTCOME MAPPING onto `{moved}`:
+ *   - `transitioned`  — the lock is now stuck (the stuck state is recorded) ⇒
+ *     `moved: true`.
+ *   - `wrong-state`   — the lock is ALREADY `stuck` (an idempotent re-surface of a
+ *     still-stuck item) ⇒ `moved: true` (the stuck record stands).
+ *   - `not-held`      — there is NO held lock to amend (an item that predates the
+ *     lock, or a flow where claim did not acquire) ⇒ `moved: false` honestly: with
+ *     the folder retired there is no other substrate to record the stuck state on,
+ *     so the caller reports the bounce did NOT land (retry/resolve) rather than
+ *     fake a success.
+ *   - `lost`/`error`  — a concurrent CAS race / environment fault ⇒ `moved: false`.
+ *   - no arbiter      — a human local-only `complete` (no arbiter handle): the lock
+ *     ref lives on the arbiter, so there is no lock to amend; treat as a recorded
+ *     no-op (`moved: true`) — a human is right there (the same human-vs-autonomous
+ *     posture the old local-only folder move took). NOTE this records nothing
+ *     durable, by design: the human is in the loop.
+ *
+ * Keyed on `task:<slug>` (the bounce surfaces a TASK; the prd/observation locks
+ * are tasking/advance holds whose own bounce paths are separate).
+ */
+async function bounceToStuckLock(params) {
+    const { cwd, slug, reason, questions, arbiter, env } = params;
+    const note = params.note ?? (() => { });
+    if (!arbiter) {
+        // No arbiter handle ⇒ no lock ref to amend. A human local-only `complete`:
+        // the human is right there, so this is a recorded no-op (parity with the old
+        // local-only folder move that wrote nothing cross-machine).
+        note(`'${slug}' bounced locally (no arbiter) — the stuck reason is not recorded ` +
+            'on a lock ref (a human is right here).');
+        return { moved: true };
+    }
+    try {
+        const r = await markStuckItemLock({
+            item: `task:${slug}`,
+            reason,
+            questions,
+            cwd,
+            arbiter,
+            env,
+        });
+        const movedOutcomes = ['transitioned', 'wrong-state'];
+        if (movedOutcomes.includes(r.outcome)) {
+            if (r.outcome === 'transitioned') {
+                note(`Marked the per-item lock for '${slug}' stuck: ${reason}`);
+            }
+            else {
+                note(`The per-item lock for '${slug}' is already stuck (re-surface).`);
+            }
+            return { moved: true };
+        }
+        const reasonNotMoved = r.outcome === 'not-held'
+            ? `'${slug}' has no held lock to mark stuck (the bounce could not record ` +
+                'the stuck state — the item is not lock-held).'
+            : `could not mark the per-item lock for '${slug}' stuck (${r.outcome}: ` +
+                `${r.message}).`;
+        note(reasonNotMoved);
+        return { moved: false, reasonNotMoved };
+    }
+    catch (err) {
+        const reasonNotMoved = `could not mark the per-item lock for '${slug}' stuck ` +
+            `(${err instanceof Error ? err.message : String(err)}).`;
+        note(reasonNotMoved);
+        return { moved: false, reasonNotMoved };
+    }
+}
+/**
+ * The active ledger-write strategy. There is exactly one (current behaviour);
+ * this indirection is the seam's single insertion point — NOT a selectable mode.
+ */
+export const ledgerWrite = currentLedgerWrite;
+//# sourceMappingURL=ledger-write.js.map

package/dist/ledger-write.js.map

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

package/dist/lifecycle-gather.d.ts

@@ -0,0 +1,30 @@
+import { type LedgerReadStrategy } from './ledger-read.js';
+import { type LifecyclePoolGates } from './lifecycle-pools.js';
+import type { SelectedLifecyclePools } from './select-priority.js';
+/**
+ * Gather + build the lifecycle pools for an IN-PLACE working checkout (sync).
+ * Reads `work/notes/observations/` + the per-item sidecar state through the read seam +
+ * the filesystem, then hands them to the shared {@link buildLifecyclePools}. The
+ * gates default BOTH OFF (the interim hardcoded-off, calm by default).
+ */
+export declare function gatherLifecycleInPlace(input: {
+    repoPath: string;
+    read?: LedgerReadStrategy;
+    gates?: LifecyclePoolGates;
+}): SelectedLifecyclePools;
+/**
+ * Gather + build the lifecycle pools for a MIRROR-SIDE bare hub mirror (async).
+ * Reads the SAME logical inputs as {@link gatherLifecycleInPlace} \u2014 observations +
+ * the `needsAnswers` pool from the mirror's committed `main` (via
+ * `resolveMirrorState`), the prd pool via `resolveMirrorSpecPool`, and each item's
+ * sidecar via `git show` \u2014 then hands them to the SAME shared
+ * {@link buildLifecyclePools}, so the in-place + mirror enumerations AGREE.
+ */
+export declare function gatherLifecycleMirror(input: {
+    mirrorPath: string;
+    ref?: string;
+    read?: LedgerReadStrategy;
+    gates?: LifecyclePoolGates;
+    env?: NodeJS.ProcessEnv;
+}): Promise<SelectedLifecyclePools>;
+//# sourceMappingURL=lifecycle-gather.d.ts.map

package/dist/lifecycle-gather.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-gather.d.ts","sourceRoot":"","sources":["../src/lifecycle-gather.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAOrE,OAAO,EAEN,KAAK,kBAAkB,EAGvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAC,sBAAsB,EAAC,MAAM,sBAAsB,CAAC;AAiHjE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC3B,GAAG,sBAAsB,CA4BzB;AA2BD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA0FlC"}