looply-cli 0.0.0-stage → 0.2.0

package/dist/publication-recorder.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordObservedPublication = recordObservedPublication;
+exports.nodeRevisionOf = nodeRevisionOf;
+exports.nodePublicationRecorder = nodePublicationRecorder;
+const core_1 = require("@looply/core");
+const compatible_sets_1 = require("./compatible-sets");
+const git_driver_1 = require("./git-driver");
+const integration_1 = require("./integration");
+const ledger_store_1 = require("./ledger-store");
+const self_repo_id_1 = require("./self-repo-id");
+/**
+ * Offer one observed publication to the ruling, and write the record only if it
+ * says to.
+ *
+ * The order matters and is the ruling's, not this function's: what makes the
+ * recording the WRONG ACT first, then drift, then whether it is already down.
+ * The one check that lives here is the last one, because it is about the
+ * OBSERVATION rather than about the set.
+ */
+async function recordObservedPublication(deps, observed) {
+    const declared = deps.declared();
+    const records = await deps.records();
+    const setId = (0, compatible_sets_1.newestSetId)(records);
+    const set = setId === null ? null : (0, compatible_sets_1.setFrom)(records, setId);
+    const current = new Map();
+    for (const r of declared) {
+        const at = await deps.revisionOf(r);
+        if (at !== null)
+            current.set(r.id, at.sha);
+    }
+    const ruling = (0, core_1.publicationRuling)({
+        declared: declared.map((d) => d.id),
+        set,
+        current,
+        repo: observed.repo,
+    });
+    if (ruling.kind !== 'record') {
+        return { ruling, recorded: false, line: (0, core_1.describePublicationRuling)(ruling) };
+    }
+    /**
+     * 🔴 THE RECEIPT HAS TO BE ABOUT THE OPERATION THAT WAS OBSERVED.
+     *
+     * Everything above is about the SET: does it exist, does it name this
+     * repository, has anything drifted. None of that notices that the ref moved
+     * AGAIN between the tick and this call — another lane, another run, a person
+     * with a shell. The set could still hold and the record would still be true
+     * about the world, and it would name an operation that is not why the world
+     * looks like that. "Only observed authorized operations create receipts"
+     * means this one, not a later one that happens to agree.
+     */
+    const here = current.get(observed.repo);
+    if (here !== observed.to) {
+        const because = `the tick left ${observed.ref} at ${observed.to.slice(0, 7)} and it is at ` +
+            `${here === undefined ? 'a revision that could not be read' : here.slice(0, 7)} now — ` +
+            'nothing was recorded, because the receipt would name an operation that is not why it is there';
+        return { ruling: { kind: 'refused', because }, recorded: false, line: `refusing — ${because}` };
+    }
+    await deps.append({
+        id: (0, compatible_sets_1.publishedId)(ruling.setId, ruling.repo),
+        kind: 'published',
+        setId: ruling.setId,
+        at: deps.now(),
+        repo: ruling.repo,
+    });
+    return { ruling, recorded: true, line: (0, core_1.describePublicationRuling)(ruling) };
+}
+/**
+ * Where a repository is now, on this machine.
+ *
+ * ⚠️ ONE IMPLEMENTATION, TWO CALLERS — `looply repos` and the daemon's
+ * integrator. Two copies of "where is this repository" are two copies that can
+ * disagree, and the one that disagrees is the one deciding whether a set has
+ * drifted.
+ */
+async function nodeRevisionOf(repo) {
+    try {
+        const git = new git_driver_1.GitDriver((0, git_driver_1.nodeGitExec)(repo.path));
+        // `listBranches` answers "does it exist" and "what is it at" in one call.
+        // It prefix-matches, so the name is compared exactly: a
+        // `looply/integration-old` lying around must not be read as the
+        // integration ref of this repository.
+        const branches = await git.listBranches(integration_1.INTEGRATION_BRANCH);
+        const integration = branches.find((b) => b.name === integration_1.INTEGRATION_BRANCH);
+        if (integration !== undefined)
+            return { sha: integration.sha, from: integration_1.INTEGRATION_BRANCH };
+        return { sha: await git.headSha(), from: 'HEAD' };
+    }
+    catch {
+        // 🔴 NULL, NEVER A GUESS. See `PublicationRecorderDeps.revisionOf`.
+        return null;
+    }
+}
+/**
+ * The daemon's recorder, or nothing at all.
+ *
+ * ⚠️ NOTHING is the right answer for most projects. A project that declares
+ * no sibling repositories has no compatible set to publish against, and a
+ * checkout that is not one of the declared repositories cannot say which one
+ * published — in both cases the honest thing is to have no recorder rather
+ * than one that refuses every tick into the log.
+ */
+function nodePublicationRecorder(cwd, projectState, declared) {
+    const self = (0, self_repo_id_1.selfRepoId)(declared, cwd);
+    if (declared.length === 0 || self === null)
+        return undefined;
+    const store = new compatible_sets_1.CompatibleSetStore(projectState, ledger_store_1.nodeLedgerFs);
+    let opened = false;
+    return async (observed) => {
+        if (!opened) {
+            await store.open();
+            opened = true;
+        }
+        const out = await recordObservedPublication({
+            declared: () => declared,
+            revisionOf: nodeRevisionOf,
+            records: async () => store.all(),
+            append: async (record) => store.append(record),
+            now: () => new Date().toISOString(),
+        }, { ...observed, repo: self });
+        return out.line;
+    };
+}
+//# sourceMappingURL=publication-recorder.js.map

package/dist/publication-recorder.js.map

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

package/dist/pursuit-delivery.d.ts

@@ -0,0 +1,24 @@
+import type { RunDelivery, RunRefusalMark } from './run-refusal-marks';
+/**
+ * What key 2 confirmed for a pursuit that ended `satisfied`, or null (L4b).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 READ AT SETTLE TIME, BESIDE THE DECISION, AND NOT THROUGH IT.
+ *
+ * The reducer that decides a pursuit is over (`autonomy-controller.ts`) is
+ * deliberately goal-blind and decision-only; threading a commit and a set of
+ * gate outcomes through it would give it facts it has no business holding. The
+ * facts already sit in the refusal marks, keyed by each Start's id, so the one
+ * place that SENDS the ending can look them up itself — the decision stays
+ * exactly where it was, and only the report gains its evidence.
+ *
+ * Every Start of a grant is `autonomyStartId(controllerId, n)` for n in
+ * 1..MAX_AUTONOMOUS_STARTS, so the search is bounded and exact. The newest
+ * `goal_satisfied` mark that carries a delivery wins: it is the refusal that
+ * ended the pursuit.
+ *
+ * Null is an honest answer — an older run wrote no delivery, or key 2 never
+ * answered — and the settle then goes out exactly as before.
+ */
+export declare function deliveryForPursuit(find: (requestId: string) => RunRefusalMark | null, controllerId: string, maxOrdinal?: number): RunDelivery | null;
+//# sourceMappingURL=pursuit-delivery.d.ts.map

package/dist/pursuit-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pursuit-delivery.d.ts","sourceRoot":"","sources":["../src/pursuit-delivery.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,cAAc,GAAG,IAAI,EAClD,YAAY,EAAE,MAAM,EACpB,UAAU,GAAE,MAA8B,GACzC,WAAW,GAAG,IAAI,CAQpB"}

package/dist/pursuit-delivery.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deliveryForPursuit = deliveryForPursuit;
+const core_1 = require("@looply/core");
+const autonomy_store_1 = require("./autonomy-store");
+/**
+ * What key 2 confirmed for a pursuit that ended `satisfied`, or null (L4b).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 READ AT SETTLE TIME, BESIDE THE DECISION, AND NOT THROUGH IT.
+ *
+ * The reducer that decides a pursuit is over (`autonomy-controller.ts`) is
+ * deliberately goal-blind and decision-only; threading a commit and a set of
+ * gate outcomes through it would give it facts it has no business holding. The
+ * facts already sit in the refusal marks, keyed by each Start's id, so the one
+ * place that SENDS the ending can look them up itself — the decision stays
+ * exactly where it was, and only the report gains its evidence.
+ *
+ * Every Start of a grant is `autonomyStartId(controllerId, n)` for n in
+ * 1..MAX_AUTONOMOUS_STARTS, so the search is bounded and exact. The newest
+ * `goal_satisfied` mark that carries a delivery wins: it is the refusal that
+ * ended the pursuit.
+ *
+ * Null is an honest answer — an older run wrote no delivery, or key 2 never
+ * answered — and the settle then goes out exactly as before.
+ */
+function deliveryForPursuit(find, controllerId, maxOrdinal = core_1.MAX_AUTONOMOUS_STARTS) {
+    let best = null;
+    for (let n = 1; n <= maxOrdinal; n++) {
+        const mark = find((0, autonomy_store_1.autonomyStartId)(controllerId, n));
+        if (mark === null || mark.code !== 'goal_satisfied' || mark.delivery === undefined)
+            continue;
+        if (best === null || mark.at > best.at)
+            best = mark;
+    }
+    return best?.delivery ?? null;
+}
+//# sourceMappingURL=pursuit-delivery.js.map

package/dist/pursuit-delivery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pursuit-delivery.js","sourceRoot":"","sources":["../src/pursuit-delivery.ts"],"names":[],"mappings":";;AAyBA,gDAYC;AArCD,uCAAqD;AACrD,qDAAmD;AAGnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,kBAAkB,CAChC,IAAkD,EAClD,YAAoB,EACpB,aAAqB,4BAAqB;IAE1C,IAAI,IAAI,GAA0B,IAAI,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAA,gCAAe,EAAC,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;QACpD,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS;YAAE,SAAS;QAC7F,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE;YAAE,IAAI,GAAG,IAAI,CAAC;IACtD,CAAC;IACD,OAAO,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC;AAChC,CAAC"}

package/dist/queue-store.d.ts

@@ -0,0 +1,132 @@
+import type { Item } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * The queue store — `queue.json` under the state dir, holding every item with its
+ * id, state, evidence, attempts and version (DESIGN §5, §13 row 7).
+ *
+ * Unlike `status.json`, the queue file is not a projection: it *is* the truth for
+ * curation. Two writers race over it — the loop marking an item `in_progress` and
+ * a phone PATCH reordering or blocking it — so every write is optimistic on the
+ * item's version. A write against a stale version is rejected with the current
+ * version, never silently applied (DESIGN §12 case 22).
+ *
+ * Reuses {@link LedgerFs} so the same in-memory double drives both stores' tests.
+ */
+/** Everything a caller may change. Id is identity; version is the store's token. */
+export type ItemPatch = Partial<Omit<Item, 'id' | 'version'>>;
+export type QueueWriteResult = {
+    ok: true;
+    item: Item;
+} | {
+    ok: false;
+    reason: 'not-found';
+} | {
+    ok: false;
+    reason: 'stale-version';
+    currentVersion: number;
+};
+/**
+ * Outcome of {@link QueueStore.insertAll}.
+ *
+ * `alreadyPresent` is not a failure. A caller that derives its ids from
+ * something stable — rather than minting a fresh one per attempt — will hand
+ * the same batch over again after a crash or a redelivery, and the honest
+ * answer to "insert this" for something already inserted is "it is already
+ * there", not an exception. Reported rather than swallowed, so a caller can
+ * tell a fresh batch from a repeat and say so.
+ */
+export type BatchInsertResult = {
+    ok: true;
+    inserted: Item[];
+    alreadyPresent: string[];
+}
+/** The same id twice in ONE batch. That is a caller bug, not a repeat. */
+ | {
+    ok: false;
+    reason: 'duplicate-id';
+    id: string;
+};
+/** All-or-nothing outcome of {@link QueueStore.patchAll}. */
+export type BatchWriteResult = {
+    ok: true;
+    items: Item[];
+} | {
+    ok: false;
+    reason: 'duplicate-id';
+} | {
+    ok: false;
+    reason: 'not-found';
+    id: string;
+} | {
+    ok: false;
+    reason: 'stale-version';
+    id: string;
+    currentVersion: number;
+};
+export declare class QueueStore {
+    private readonly stateDir;
+    private readonly fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    private static writes;
+    private items;
+    private opened;
+    constructor(stateDir: string, fs: LedgerFs);
+    private get queuePath();
+    /**
+     * Load whatever is on disk. A missing file is an empty queue; a corrupt file is
+     * a loud failure. The file only ever lands whole (temp-then-rename), so corrupt
+     * means something outside this store touched it — starting empty here would
+     * silently discard every item a night of scanning produced.
+     */
+    open(): Promise<Item[]>;
+    /** All items, in stored order. Callers sort by `orderKey` when order matters. */
+    list(): Item[];
+    get(id: string): Item | undefined;
+    /** New items enter at version 1; the store owns the concurrency token. */
+    insert(input: Omit<Item, 'version'>): Promise<Item>;
+    /**
+     * Apply `patch` only if the caller saw the current version. On success the
+     * version bumps, so the loser of a race gets `stale-version` with the number
+     * it must refetch — the rejection is the feature, not the error path.
+     */
+    update(id: string, expectedVersion: number, patch: ItemPatch): Promise<QueueWriteResult>;
+    /**
+     * Apply several patches as ONE durable write, or apply none of them.
+     *
+     * `update` in a loop is not this: it persists after each item, so a crash
+     * halfway leaves the queue in a state no caller asked for and no reader can
+     * name — half a set of items moved, half not. Every check runs first, then
+     * every change, then a single temp-then-rename. There is no window in which
+     * the file on disk holds a partial batch.
+     *
+     * Deliberately says nothing about WHY a caller wants several items changed
+     * together. It takes patches; what they mean is the caller's business.
+     */
+    patchAll(patches: readonly {
+        id: string;
+        expectedVersion: number;
+        patch: ItemPatch;
+    }[]): Promise<BatchWriteResult>;
+    private assertOpened;
+    /**
+     * Add several items as ONE durable write, or add none of them.
+     *
+     * `insert` in a loop is not this: it persists after each item, so a process
+     * that dies partway leaves an arbitrary PREFIX of the batch on disk. For a
+     * batch that means something as a whole — a compiled plan, say — a prefix is
+     * a shape nobody asked for and nothing records which part landed.
+     *
+     * An id the store already holds is SKIPPED, not refused. That is what makes
+     * a retry converge: re-offering a batch whose ids are derived from something
+     * stable inserts only what is missing, and re-offering it complete inserts
+     * nothing at all. `insert` still throws on a duplicate, because a single
+     * insert naming an existing id really is a mistake.
+     *
+     * Deliberately says nothing about WHY a caller wants several items added
+     * together. It takes items; what they mean is the caller's business.
+     */
+    insertAll(inputs: readonly Omit<Item, 'version'>[]): Promise<BatchInsertResult>;
+    private persist;
+    private writeList;
+}
+//# sourceMappingURL=queue-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue-store.d.ts","sourceRoot":"","sources":["../src/queue-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;GAWG;AAEH,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;AAE9D,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAClC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE;AAC1D,0EAA0E;GACxE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACrC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/E,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IARrB,kFAAkF;IAClF,OAAO,CAAC,MAAM,CAAC,MAAM,CAAK;IAE1B,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,MAAM,CAAS;gBAGJ,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ;IAG/B,OAAO,KAAK,SAAS,GAEpB;IAED;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAW7B,iFAAiF;IACjF,IAAI,IAAI,IAAI,EAAE;IAId,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIjC,0EAA0E;IACpE,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAWzD;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAa9F;;;;;;;;;;;OAWG;IACG,QAAQ,CACZ,OAAO,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,CAAA;KAAE,EAAE,GAC5E,OAAO,CAAC,gBAAgB,CAAC;IA2B5B,OAAO,CAAC,YAAY;IAOpB;;;;;;;;;;;;;;;;OAgBG;IACG,SAAS,CAAC,MAAM,EAAE,SAAS,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;YAoCvE,OAAO;YAIP,SAAS;CAcxB"}

package/dist/queue-store.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueueStore = void 0;
+class QueueStore {
+    stateDir;
+    fs;
+    /** Distinguishes two writes from ONE process; the pid distinguishes processes. */
+    static writes = 0;
+    items = new Map();
+    opened = false;
+    constructor(stateDir, fs) {
+        this.stateDir = stateDir;
+        this.fs = fs;
+    }
+    get queuePath() {
+        return `${this.stateDir}/queue.json`;
+    }
+    /**
+     * Load whatever is on disk. A missing file is an empty queue; a corrupt file is
+     * a loud failure. The file only ever lands whole (temp-then-rename), so corrupt
+     * means something outside this store touched it — starting empty here would
+     * silently discard every item a night of scanning produced.
+     */
+    async open() {
+        await this.fs.mkdir(this.stateDir);
+        const text = await this.fs.readFile(this.queuePath);
+        if (text !== null) {
+            const parsed = JSON.parse(text);
+            this.items = new Map(parsed.map((i) => [i.id, i]));
+        }
+        this.opened = true;
+        return this.list();
+    }
+    /** All items, in stored order. Callers sort by `orderKey` when order matters. */
+    list() {
+        return [...this.items.values()];
+    }
+    get(id) {
+        return this.items.get(id);
+    }
+    /** New items enter at version 1; the store owns the concurrency token. */
+    async insert(input) {
+        this.assertOpened();
+        if (this.items.has(input.id)) {
+            throw new Error(`queue: duplicate item id ${input.id}`);
+        }
+        const item = { ...input, version: 1 };
+        this.items.set(item.id, item);
+        await this.persist();
+        return item;
+    }
+    /**
+     * Apply `patch` only if the caller saw the current version. On success the
+     * version bumps, so the loser of a race gets `stale-version` with the number
+     * it must refetch — the rejection is the feature, not the error path.
+     */
+    async update(id, expectedVersion, patch) {
+        this.assertOpened();
+        const current = this.items.get(id);
+        if (current === undefined)
+            return { ok: false, reason: 'not-found' };
+        if (current.version !== expectedVersion) {
+            return { ok: false, reason: 'stale-version', currentVersion: current.version };
+        }
+        const next = { ...current, ...patch, id: current.id, version: current.version + 1 };
+        this.items.set(id, next);
+        await this.persist();
+        return { ok: true, item: next };
+    }
+    /**
+     * Apply several patches as ONE durable write, or apply none of them.
+     *
+     * `update` in a loop is not this: it persists after each item, so a crash
+     * halfway leaves the queue in a state no caller asked for and no reader can
+     * name — half a set of items moved, half not. Every check runs first, then
+     * every change, then a single temp-then-rename. There is no window in which
+     * the file on disk holds a partial batch.
+     *
+     * Deliberately says nothing about WHY a caller wants several items changed
+     * together. It takes patches; what they mean is the caller's business.
+     */
+    async patchAll(patches) {
+        this.assertOpened();
+        // The same id twice would make the second patch race the first through one
+        // map, and the caller almost certainly did not mean it.
+        const ids = new Set(patches.map((p) => p.id));
+        if (ids.size !== patches.length)
+            return { ok: false, reason: 'duplicate-id' };
+        const next = [];
+        for (const p of patches) {
+            const current = this.items.get(p.id);
+            if (current === undefined)
+                return { ok: false, reason: 'not-found', id: p.id };
+            if (current.version !== p.expectedVersion) {
+                return { ok: false, reason: 'stale-version', id: p.id, currentVersion: current.version };
+            }
+            next.push({ ...current, ...p.patch, id: current.id, version: current.version + 1 });
+        }
+        // Nothing above mutated anything, so a refusal leaves the store untouched
+        // in memory as well as on disk.
+        for (const item of next)
+            this.items.set(item.id, item);
+        // An empty batch is a legitimate no-op — "adopt nothing new" is a real
+        // request — and rewriting the file to prove it would be a write for nothing.
+        if (next.length)
+            await this.persist();
+        return { ok: true, items: next };
+    }
+    assertOpened() {
+        if (!this.opened) {
+            // Writing before replay would clobber the on-disk queue with an empty one.
+            throw new Error('queue: write before open() — would overwrite the queue on disk');
+        }
+    }
+    /**
+     * Add several items as ONE durable write, or add none of them.
+     *
+     * `insert` in a loop is not this: it persists after each item, so a process
+     * that dies partway leaves an arbitrary PREFIX of the batch on disk. For a
+     * batch that means something as a whole — a compiled plan, say — a prefix is
+     * a shape nobody asked for and nothing records which part landed.
+     *
+     * An id the store already holds is SKIPPED, not refused. That is what makes
+     * a retry converge: re-offering a batch whose ids are derived from something
+     * stable inserts only what is missing, and re-offering it complete inserts
+     * nothing at all. `insert` still throws on a duplicate, because a single
+     * insert naming an existing id really is a mistake.
+     *
+     * Deliberately says nothing about WHY a caller wants several items added
+     * together. It takes items; what they mean is the caller's business.
+     */
+    async insertAll(inputs) {
+        this.assertOpened();
+        // Checked across the WHOLE batch before anything is decided, so a refusal
+        // leaves the store exactly as it was.
+        const seen = new Set();
+        for (const input of inputs) {
+            if (seen.has(input.id))
+                return { ok: false, reason: 'duplicate-id', id: input.id };
+            seen.add(input.id);
+        }
+        const inserted = [];
+        const alreadyPresent = [];
+        for (const input of inputs) {
+            if (this.items.has(input.id)) {
+                alreadyPresent.push(input.id);
+                continue;
+            }
+            inserted.push({ ...input, version: 1 });
+        }
+        // Nothing new is a legitimate no-op — a fully repeated batch is the normal
+        // shape of a retry — and rewriting the file to prove it would be a write
+        // for nothing.
+        if (inserted.length) {
+            // Written from a computed list, then committed to memory, in that order.
+            // The other way round leaves this object claiming items the file does not
+            // have when the write fails — and the caller is told the write failed
+            // while `list()` cheerfully returns them.
+            const next = [...this.items.values(), ...inserted];
+            await this.writeList(next);
+            for (const item of inserted)
+                this.items.set(item.id, item);
+        }
+        return { ok: true, inserted, alreadyPresent };
+    }
+    async persist() {
+        await this.writeList(this.list());
+    }
+    async writeList(items) {
+        // Temp-then-rename, same contract as status.json: a concurrent reader
+        // (`looply queue`, the daemon) never sees half a file. It is also what
+        // makes a batch all-or-nothing — a process that dies before the rename
+        // leaves an orphaned temp file and a queue.json nobody touched.
+        // The temp name is PRIVATE TO THIS WRITER. A shared `queue.json.tmp` is
+        // two processes writing one path: the second truncates and rewrites what
+        // the first is midway through, and then both rename it into place. The
+        // rename is atomic and the file it renames is a splice of two writes, and
+        // nothing downstream can tell.
+        const tmp = `${this.queuePath}.${process.pid}.${(QueueStore.writes += 1)}.tmp`;
+        await this.fs.writeFile(tmp, JSON.stringify(items, null, 2) + '\n');
+        await this.fs.rename(tmp, this.queuePath);
+    }
+}
+exports.QueueStore = QueueStore;
+//# sourceMappingURL=queue-store.js.map

package/dist/queue-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-store.js","sourceRoot":"","sources":["../src/queue-store.ts"],"names":[],"mappings":";;;AA8CA,MAAa,UAAU;IAQF;IACA;IARnB,kFAAkF;IAC1E,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAElB,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAChC,MAAM,GAAG,KAAK,CAAC;IAEvB,YACmB,QAAgB,EAChB,EAAY;QADZ,aAAQ,GAAR,QAAQ,CAAQ;QAChB,OAAE,GAAF,EAAE,CAAU;IAC5B,CAAC;IAEJ,IAAY,SAAS;QACnB,OAAO,GAAG,IAAI,CAAC,QAAQ,aAAa,CAAC;IACvC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACpD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAW,CAAC;YAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,iFAAiF;IACjF,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,MAAM,CAAC,KAA4B;QACvC,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,4BAA4B,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1D,CAAC;QACD,MAAM,IAAI,GAAS,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9B,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,eAAuB,EAAE,KAAgB;QAChE,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;QACrE,IAAI,OAAO,CAAC,OAAO,KAAK,eAAe,EAAE,CAAC;YACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QACjF,CAAC;QACD,MAAM,IAAI,GAAS,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QAC1F,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACzB,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CACZ,OAA6E;QAE7E,IAAI,CAAC,YAAY,EAAE,CAAC;QAEpB,2EAA2E;QAC3E,wDAAwD;QACxD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9C,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;QAE9E,MAAM,IAAI,GAAW,EAAE,CAAC;QACxB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACrC,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;YAC/E,IAAI,OAAO,CAAC,OAAO,KAAK,CAAC,CAAC,eAAe,EAAE,CAAC;gBAC1C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,cAAc,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;YAC3F,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;QACtF,CAAC;QAED,0EAA0E;QAC1E,gCAAgC;QAChC,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACvD,uEAAuE;QACvE,6EAA6E;QAC7E,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;QACtC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACnC,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,2EAA2E;YAC3E,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACpF,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,SAAS,CAAC,MAAwC;QACtD,IAAI,CAAC,YAAY,EAAE,CAAC;QAEpB,0EAA0E;QAC1E,sCAAsC;QACtC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC;YACnF,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACrB,CAAC;QAED,MAAM,QAAQ,GAAW,EAAE,CAAC;QAC5B,MAAM,cAAc,GAAa,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC7B,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAC9B,SAAS;YACX,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1C,CAAC;QAED,2EAA2E;QAC3E,yEAAyE;QACzE,eAAe;QACf,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpB,yEAAyE;YACzE,0EAA0E;YAC1E,sEAAsE;YACtE,0CAA0C;YAC1C,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,GAAG,QAAQ,CAAC,CAAC;YACnD,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC3B,KAAK,MAAM,IAAI,IAAI,QAAQ;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAC7D,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;IAChD,CAAC;IAEO,KAAK,CAAC,OAAO;QACnB,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACpC,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,KAAsB;QAC5C,sEAAsE;QACtE,uEAAuE;QACvE,uEAAuE;QACvE,gEAAgE;QAChE,wEAAwE;QACxE,yEAAyE;QACzE,uEAAuE;QACvE,0EAA0E;QAC1E,+BAA+B;QAC/B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC;QAC/E,MAAM,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACpE,MAAM,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;;AA9LH,gCA+LC"}

package/dist/queue-summary.d.ts

@@ -0,0 +1,14 @@
+import type { Item, ItemState } from '@looply/core';
+export interface StateCount {
+    state: ItemState;
+    count: number;
+}
+/** Counts per state, in triage order. States with no items are left out. */
+export declare function countByState(items: readonly Pick<Item, 'state'>[]): StateCount[];
+/**
+ * One line explaining an unpickable queue. Always opens with `no ready items`
+ * — `scripts/cli-audit.sh` asserts that phrase, and it is the fact the run
+ * refused on.
+ */
+export declare function describeNoReady(items: readonly Pick<Item, 'state'>[]): string;
+//# sourceMappingURL=queue-summary.d.ts.map

package/dist/queue-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-summary.d.ts","sourceRoot":"","sources":["../src/queue-summary.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AA+BpD,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,GAAG,UAAU,EAAE,CAOhF;AA8BD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAS7E"}

package/dist/queue-summary.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countByState = countByState;
+exports.describeNoReady = describeNoReady;
+/**
+ * Why the run found nothing to pick.
+ *
+ * `looply run` picks items in exactly one state (`ready`), and every item a
+ * scan writes starts as `draft` — a claim about the code until a verify pass
+ * confirms it. So the commonest state right after a scan is a queue full of
+ * work the run refuses to touch, and saying only "no ready items" there reads
+ * as "the scan found nothing", which is the opposite of the truth. Name what
+ * is actually in the queue, and name what would make one of them pickable.
+ *
+ * Pure: the caller owns the queue file and the terminal.
+ */
+/** Triage order: what someone can act on first, what is settled last. */
+const STATE_ORDER = [
+    'ready',
+    'draft',
+    'verifying',
+    'in_progress',
+    'blocked',
+    'stale',
+    'duplicate',
+    'split',
+    'done',
+    'closed',
+];
+const STATE_LABEL = { in_progress: 'in progress' };
+/** Counts per state, in triage order. States with no items are left out. */
+function countByState(items) {
+    const counts = new Map();
+    for (const item of items)
+        counts.set(item.state, (counts.get(item.state) ?? 0) + 1);
+    return STATE_ORDER.filter((state) => counts.has(state)).map((state) => ({
+        state,
+        count: counts.get(state),
+    }));
+}
+function has(counts, state) {
+    return counts.some((c) => c.state === state && c.count > 0);
+}
+/**
+ * The one thing worth doing next. Ordered by which state is actually holding
+ * the run up, not by how many items are in it: a single unverified draft is a
+ * more useful thing to say than fifty closed ones.
+ */
+function nextStep(counts) {
+    if (has(counts, 'draft') || has(counts, 'verifying')) {
+        // This used to send people to the app, which predates `looply verify`.
+        // Marking an item ready by hand skips the very check that makes it
+        // pickable, so pointing at the app was wrong advice as well as remote.
+        return 'Run `looply verify` to check them against the code — a run does the same pass itself before picking.';
+    }
+    if (has(counts, 'in_progress')) {
+        // The advice used to be "reset it from the app", which was never possible:
+        // the phone patches the server's item table and nothing carries that back
+        // down to the queue this run picks from. The next run now recovers it.
+        return 'An item is still marked in progress, so a previous run did not finish it. Start a run and it will put the item back — or say why it cannot.';
+    }
+    if (has(counts, 'blocked')) {
+        return 'Every item is blocked. `looply queue` says why each one is; unblock one from the app, or run `looply scan` to find other work.';
+    }
+    return 'Everything in the queue is settled. Run `looply scan` to find more work.';
+}
+/**
+ * One line explaining an unpickable queue. Always opens with `no ready items`
+ * — `scripts/cli-audit.sh` asserts that phrase, and it is the fact the run
+ * refused on.
+ */
+function describeNoReady(items) {
+    const counts = countByState(items);
+    if (!counts.length) {
+        return 'no ready items: the queue is empty. Run `looply scan` to find work, or add an item from the app.';
+    }
+    const inventory = counts
+        .map(({ state, count }) => `${count} ${STATE_LABEL[state] ?? state}`)
+        .join(', ');
+    return `no ready items: the queue holds ${inventory}. ${nextStep(counts)}`;
+}
+//# sourceMappingURL=queue-summary.js.map

package/dist/queue-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-summary.js","sourceRoot":"","sources":["../src/queue-summary.ts"],"names":[],"mappings":";;AAqCA,oCAOC;AAmCD,0CASC;AAtFD;;;;;;;;;;;GAWG;AAEH,yEAAyE;AACzE,MAAM,WAAW,GAAyB;IACxC,OAAO;IACP,OAAO;IACP,WAAW;IACX,aAAa;IACb,SAAS;IACT,OAAO;IACP,WAAW;IACX,OAAO;IACP,MAAM;IACN,QAAQ;CACT,CAAC;AAEF,MAAM,WAAW,GAAuC,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AAOvF,4EAA4E;AAC5E,SAAgB,YAAY,CAAC,KAAqC;IAChE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACpF,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtE,KAAK;QACL,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAE;KAC1B,CAAC,CAAC,CAAC;AACN,CAAC;AAED,SAAS,GAAG,CAAC,MAA6B,EAAE,KAAgB;IAC1D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,MAA6B;IAC7C,IAAI,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC;QACrD,uEAAuE;QACvE,mEAAmE;QACnE,uEAAuE;QACvE,OAAO,sGAAsG,CAAC;IAChH,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC;QAC/B,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,OAAO,6IAA6I,CAAC;IACvJ,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC;QAC3B,OAAO,gIAAgI,CAAC;IAC1I,CAAC;IACD,OAAO,0EAA0E,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAAC,KAAqC;IACnE,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,kGAAkG,CAAC;IAC5G,CAAC;IACD,MAAM,SAAS,GAAG,MAAM;SACrB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;SACpE,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,mCAAmC,SAAS,KAAK,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;AAC7E,CAAC"}