things-api 0.19.4 → 0.20.1

package/dist/model/today-placement.d.ts

@@ -0,0 +1,65 @@
+/**
+ * THE Today / This-Evening placement law — one derivation, every surface.
+ *
+ * Things stores a Today member's evening flag as a raw `startBucket` byte, and it
+ * NEVER cleans that byte when the day it belongs to goes past ([SIT3
+ * REMSTALE](../../docs/lab/sit3-arrival-evening-lists.md), oddities §9n). The app
+ * instead re-derives placement at RENDER time against the device's current local
+ * day, so a `startBucket=1` row whose `startDate` has passed — a STALE evening
+ * row — renders in **Today proper**, below the day's daytime rows and ABOVE the
+ * "This Evening" section header, exactly like any other arrived member
+ * ([STEV1](../../docs/lab/stev1-stale-evening.md) cell 1).
+ *
+ * Every consumer of the evening flag therefore has to apply the same gate, and
+ * they must all apply the SAME one: the read views, the reorder scopes' member
+ * census, the bounce's concurrent-edit re-check, and the move planner's axis
+ * choice. Four independent spellings is what left a stale evening item refused by
+ * BOTH reorder scopes (#657) — `--in today` called it an evening-bucket item and
+ * `--in evening` called it stale. This module is the single spelling.
+ */
+/**
+ * Where a row sits in the Today view: `"today"` (the daytime section),
+ * `"evening"` (the This Evening section), or `null` (not a Today member on the
+ * scheduled arm at all).
+ */
+export type TodayPlacement = "today" | "evening" | null;
+/** The columns the placement law reads. */
+export interface TodayPlacementRow {
+    /** `start`: 0 = inbox, 1 = anytime/active, 2 = someday. */
+    start: number;
+    /** Packed `startDate`, or null for an undated row. */
+    startDate: number | null;
+    /** Raw `startBucket`: 0 = Today proper, 1 = This Evening. */
+    startBucket: number | null;
+}
+/**
+ * The Today/Evening placement of a row on the SCHEDULED arm, under `packedToday`
+ * (the device-local day, encoded — never a UTC date; see
+ * [timezones](../../docs/reference/timezones.md)).
+ *
+ * - An Inbox row (`start=0`) is never a scheduled Today member.
+ * - An undated or strictly-future row is not a member either.
+ * - An ARRIVED row (`startDate <= today`, `start` 1 or 2) IS a Today member — an
+ *   overdue day and an arrived someday-scheduled row included.
+ * - It is in **This Evening** only while its evening flag is LIVE: `startBucket=1`
+ *   with a `startDate` of EXACTLY today. Evening membership expires daily, so a
+ *   past-dated bucket-1 row is `"today"`.
+ *
+ * Arrivedness is judged on the DATE alone, never on the start state: an arrived
+ * someday-scheduled row (`start=2`, `startDate <= today`) is a Today member and
+ * buckets today/evening like any other, matching how `deriveStage` reports it as
+ * `anytime` carrying the Today marker (#325).
+ *
+ * The DEADLINE arm of Today membership (an undated row pulled in by a due or
+ * overdue deadline) is not expressible from these three columns and is layered on
+ * by the reader (`mappers.todayMarkers`); it is never an evening member.
+ */
+export declare function todayPlacement(row: TodayPlacementRow, packedToday: number): TodayPlacement;
+/**
+ * Whether a row's evening flag has gone STALE: the `startBucket=1` byte is still
+ * set, but the day it was set for has passed, so the app renders the row in Today
+ * proper. The reorder scopes use this to tell a stale movee (accepted by the
+ * `today` scope) from a live evening one (refused there, O03), and to point a
+ * stale movee's `evening`-scope refusal at the scope that does take it.
+ */
+export declare function isStaleEvening(row: TodayPlacementRow, packedToday: number): boolean;

package/dist/model/today-placement.js

@@ -0,0 +1,59 @@
+/**
+ * THE Today / This-Evening placement law — one derivation, every surface.
+ *
+ * Things stores a Today member's evening flag as a raw `startBucket` byte, and it
+ * NEVER cleans that byte when the day it belongs to goes past ([SIT3
+ * REMSTALE](../../docs/lab/sit3-arrival-evening-lists.md), oddities §9n). The app
+ * instead re-derives placement at RENDER time against the device's current local
+ * day, so a `startBucket=1` row whose `startDate` has passed — a STALE evening
+ * row — renders in **Today proper**, below the day's daytime rows and ABOVE the
+ * "This Evening" section header, exactly like any other arrived member
+ * ([STEV1](../../docs/lab/stev1-stale-evening.md) cell 1).
+ *
+ * Every consumer of the evening flag therefore has to apply the same gate, and
+ * they must all apply the SAME one: the read views, the reorder scopes' member
+ * census, the bounce's concurrent-edit re-check, and the move planner's axis
+ * choice. Four independent spellings is what left a stale evening item refused by
+ * BOTH reorder scopes (#657) — `--in today` called it an evening-bucket item and
+ * `--in evening` called it stale. This module is the single spelling.
+ */
+/**
+ * The Today/Evening placement of a row on the SCHEDULED arm, under `packedToday`
+ * (the device-local day, encoded — never a UTC date; see
+ * [timezones](../../docs/reference/timezones.md)).
+ *
+ * - An Inbox row (`start=0`) is never a scheduled Today member.
+ * - An undated or strictly-future row is not a member either.
+ * - An ARRIVED row (`startDate <= today`, `start` 1 or 2) IS a Today member — an
+ *   overdue day and an arrived someday-scheduled row included.
+ * - It is in **This Evening** only while its evening flag is LIVE: `startBucket=1`
+ *   with a `startDate` of EXACTLY today. Evening membership expires daily, so a
+ *   past-dated bucket-1 row is `"today"`.
+ *
+ * Arrivedness is judged on the DATE alone, never on the start state: an arrived
+ * someday-scheduled row (`start=2`, `startDate <= today`) is a Today member and
+ * buckets today/evening like any other, matching how `deriveStage` reports it as
+ * `anytime` carrying the Today marker (#325).
+ *
+ * The DEADLINE arm of Today membership (an undated row pulled in by a due or
+ * overdue deadline) is not expressible from these three columns and is layered on
+ * by the reader (`mappers.todayMarkers`); it is never an evening member.
+ */
+export function todayPlacement(row, packedToday) {
+    if (row.start !== 1 && row.start !== 2)
+        return null;
+    if (row.startDate === null || row.startDate > packedToday)
+        return null;
+    return row.startBucket === 1 && row.startDate === packedToday ? "evening" : "today";
+}
+/**
+ * Whether a row's evening flag has gone STALE: the `startBucket=1` byte is still
+ * set, but the day it was set for has passed, so the app renders the row in Today
+ * proper. The reorder scopes use this to tell a stale movee (accepted by the
+ * `today` scope) from a live evening one (refused there, O03), and to point a
+ * stale movee's `evening`-scope refusal at the scope that does take it.
+ */
+export function isStaleEvening(row, packedToday) {
+    return row.startBucket === 1 && todayPlacement(row, packedToday) === "today";
+}
+//# sourceMappingURL=today-placement.js.map

package/dist/model/today-placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"today-placement.js","sourceRoot":"","sources":["../../src/model/today-placement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmBH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,cAAc,CAAC,GAAsB,EAAE,WAAmB;IACxE,IAAI,GAAG,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,GAAG,CAAC,SAAS,GAAG,WAAW;QAAE,OAAO,IAAI,CAAC;IACvE,OAAO,GAAG,CAAC,WAAW,KAAK,CAAC,IAAI,GAAG,CAAC,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,GAAsB,EAAE,WAAmB;IACxE,OAAO,GAAG,CAAC,WAAW,KAAK,CAAC,IAAI,cAAc,CAAC,GAAG,EAAE,WAAW,CAAC,KAAK,OAAO,CAAC;AAC/E,CAAC"}

package/dist/op-result.d.ts

@@ -10,7 +10,14 @@ export interface OpResultOptions {
      */
     traceDir?: string;
 }
-export type OpResultStatus = "found" | "intent-only" | "unknown";
+export type OpResultStatus = "found" | "in-flight" | "orphaned" | "intent-only" | "unknown";
+/** The writing process behind an unsuperseded intent, and whether it still exists. */
+export interface OpResultHolder {
+    pid: number;
+    /** The pid's recorded start time, which is what makes pid reuse detectable. */
+    start: string | null;
+    alive: boolean;
+}
 export interface OpResultData {
     opId: string;
     status: OpResultStatus;
@@ -51,8 +58,14 @@ export interface OpResultData {
     ts: string | null;
     /** The final record's wall-clock duration in ms; null when INTENT-ONLY / UNKNOWN. */
     durationMs: number | null;
-    /** The newest correlated trace file path (INTENT-ONLY, best-effort); null otherwise. */
+    /** The newest correlated trace file path (unsuperseded intent, best-effort); null otherwise. */
     tracePath: string | null;
+    /**
+     * The process behind an unsuperseded intent — the identity that decides
+     * IN-FLIGHT from ORPHANED (#639). Null on every settled status, and on the
+     * legacy intent that recorded no holder.
+     */
+    holder: OpResultHolder | null;
     /** A one-line behavioral explanation of the outcome for a human/agent caller. */
     note: string;
 }

package/dist/op-result.js

@@ -14,17 +14,26 @@
  * caller runs `things op-result <op-id>` in a FRESH short-lived process and reads
  * the final outcome the killed process already durably wrote (fsync per record).
  *
- * Three outcomes:
+ * Four outcomes:
  *  - FOUND — a final (non-intent) record carries the id: report its result code,
  *    target uuid, and post-verify observation (the standard fields the killed
  *    process would have printed).
- *  - INTENT-ONLY — only an `intent` marker exists: the op is still running, or the
- *    process died between touching the app and writing its final record — the
- *    outcome is UNCERTAIN (the app-side change may have landed). The newest
+ *  - IN-FLIGHT — an unsuperseded `intent` marker whose HOLDER IS ALIVE: the op is
+ *    still running right now. The caller's move is to poll again, not to retry.
+ *  - ORPHANED — an unsuperseded `intent` marker whose holder is GONE: the process
+ *    died between touching the app and writing its final record, so the outcome is
+ *    genuinely UNCERTAIN (the app-side change may have landed). The newest
  *    correlated trace file is surfaced when determinable.
  *  - UNKNOWN — no record carries the id: it never ran, the id is mistyped, or the
  *    record has aged out of the local history.
  *
+ * Splitting the last two used to be impossible: an intent recorded no holder, so
+ * this could only hedge ("still running, OR died mid-flight") and the caller had
+ * to guess which. A keyed intent now carries the writing process's instance
+ * identity (#639), which makes it a question with an answer. The rare third
+ * shape — an intent with no holder recorded — keeps the old hedged status,
+ * because for that record the honest answer really is "cannot tell".
+ *
  * This is a pure history read — it opens no database and drives nothing. Reused by
  * the CLI subcommand and (read-only) the MCP surface through the single library
  * entry point (src/index.ts), like {@link diagnose}.
@@ -32,6 +41,7 @@
 import { readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { auditDir as defaultAuditDir, traceDir as defaultTraceDir } from "./paths.js";
+import { instanceAlive } from "./process-instance.js";
 import { readAuditRecords } from "./write/undo.js";
 /** The trace file whose mtime is closest to `targetTs` (within a window), else null. */
 function correlatedTrace(traceDir, targetTs) {
@@ -120,15 +130,22 @@ export function opResult(opId, options = {}) {
             ts: null,
             durationMs: null,
             tracePath: null,
+            holder: null,
             note: `no change-history record carries op-id "${opId}" — it never ran, the id is mistyped, or ` +
                 "the record has aged out of the local history (`things doctor` shows the history health)",
         };
     }
-    // A final (non-intent) record supersedes the intent marker. Take the NEWEST one
-    // (an ambiguously-failed op can be re-dispatched under the same id, yielding
-    // several finals — the last is the current truth).
-    const finals = matched.filter((r) => r.result !== "intent");
-    if (finals.length > 0) {
+    // An intent is superseded by the final of its OWN attempt, paired by `ts` —
+    // both records of one attempt derive from the same `startedAt`, which is the
+    // schema's documented sibling invariant. Deliberately NOT "the last record
+    // wins": `readAuditRecords` RE-SORTS the trail by `ts`, so file order does not
+    // survive the read. `findPendingIntent` (write/opid.ts) applies the identical
+    // rule, so the reporting surface and the dispatch gate can never disagree
+    // about whether a key is in flight.
+    const settled = new Set(matched.filter((r) => r.result !== "intent").map((r) => r.ts));
+    const pending = matched.findLast((r) => r.result === "intent" && !settled.has(r.ts));
+    if (pending === undefined) {
+        const finals = matched.filter((r) => r.result !== "intent");
         const rec = finals[finals.length - 1];
         return {
             opId,
@@ -143,29 +160,64 @@ export function opResult(opId, options = {}) {
             ts: rec.ts,
             durationMs: rec.durationMs,
             tracePath: null,
+            holder: null,
             note: foundNote(rec.result, rec.uuid),
         };
     }
-    // Only intent marker(s): still running, or the process died mid-flight.
-    const rec = matched[matched.length - 1];
-    const tracePath = correlatedTrace(traceDir, rec.ts);
-    return {
+    // An unsuperseded intent. Its holder decides which of the two very different
+    // situations this is — and the caller's next move differs completely between
+    // them, which is why the old single hedged answer was worth splitting.
+    const last = pending;
+    const tracePath = correlatedTrace(traceDir, last.ts);
+    const recorded = last.holder;
+    const holder = recorded === undefined ? null : { ...recorded, alive: instanceAlive(recorded) };
+    const target = last.uuid ?? "<uuid>";
+    const base = {
         opId,
-        status: "intent-only",
-        op: rec.op,
+        op: last.op,
         result: null,
-        uuid: rec.uuid,
+        uuid: last.uuid,
         observed: null,
         verify: null,
         // An intent marker is written BEFORE the app is touched, so it never carries
         // steps — the drive had not run yet. The trace file is the recovery here.
         steps: null,
-        ts: rec.ts,
+        ts: last.ts,
         durationMs: null,
         tracePath,
-        note: "the operation was recorded as STARTED but no final outcome was written — it is still " +
-            "running, or the process died mid-flight (its GUI-side change may have landed). The outcome " +
-            "is UNCERTAIN: re-read the target and inspect the trace" +
+        holder,
+    };
+    if (holder !== null && holder.alive) {
+        return {
+            ...base,
+            status: "in-flight",
+            note: `the operation is STILL RUNNING — it started ${last.ts} and the process that owns it ` +
+                `(pid ${holder.pid}) is alive. Nothing to recover yet: run this command again in a few ` +
+                "seconds until it reports a final outcome. Do NOT resubmit the write — a GUI-driven " +
+                "change takes seconds, and longer on a large or syncing database. (Resubmitting the same " +
+                "op-id while it runs is refused rather than executed, so a retry costs you the wait " +
+                "either way.)",
+        };
+    }
+    if (holder !== null) {
+        return {
+            ...base,
+            status: "orphaned",
+            note: `the operation started ${last.ts} and the process that owned it (pid ${holder.pid}) is ` +
+                "GONE without recording an outcome — its app-side change may or may not have landed. " +
+                `Re-read the target (\`things show ${target}\`) and inspect the trace` +
+                (tracePath !== null ? ` (${tracePath})` : "") +
+                " rather than blind-retrying. Resubmitting the SAME command with the SAME op-id is safe: " +
+                "it re-reads state to decide whether that change is there, replaying it rather than " +
+                "repeating it (and refusing outright when the record cannot settle the question)",
+        };
+    }
+    return {
+        ...base,
+        status: "intent-only",
+        note: "the operation was recorded as STARTED but no final outcome was written, and the record " +
+            "names no process, so whether it is still running cannot be determined from here. The " +
+            `outcome is UNCERTAIN: re-read the target (\`things show ${target}\`) and inspect the trace` +
             (tracePath !== null ? ` (${tracePath})` : "") +
             " rather than blind-retrying",
     };

package/dist/op-result.js.map

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

package/dist/process-instance.d.ts

@@ -0,0 +1,41 @@
+/** The process that owns an in-flight piece of work, as an identity (not just a pid). */
+export interface ProcessInstance {
+    pid: number;
+    /**
+     * The pid's start time (`ps -o lstart=`), stable for that process's whole
+     * life. Null when it could not be read — the pid alone then carries the
+     * answer, which is weaker but never fabricated.
+     */
+    start: string | null;
+}
+/**
+ * Does a process with this pid exist right now? (Signal 0 tests existence only.)
+ *
+ * Non-positive pids are rejected BEFORE the syscall, and that guard is
+ * load-bearing rather than defensive tidiness: in `kill(2)`, pid 0 means "every
+ * process in the caller's group" and a negative pid means "the group" — both
+ * succeed, so a zero or negative holder would report itself alive forever and
+ * wedge its idempotency key. A holder is always a real process or it is nothing.
+ */
+export declare function pidAlive(pid: number): boolean;
+/** A pid's start time, or null when the pid is gone / `ps` could not answer. */
+export declare function processStart(pid: number): string | null;
+/** This process, as the identity to record on a piece of work it is starting. */
+export declare function currentInstance(): ProcessInstance;
+/** Seams so tests never shell out. */
+export interface InstanceLivenessDeps {
+    pidAlive?: (pid: number) => boolean;
+    processStart?: (pid: number) => string | null;
+}
+/**
+ * Is the RECORDED instance still running?
+ *
+ * Deliberately CONSERVATIVE: this answers a question whose wrong answer is
+ * expensive in one direction only. Reporting a dead writer as alive costs a
+ * caller one more poll; reporting a LIVE writer as dead invites a second
+ * execution of a mutation that is still in flight. So every ambiguity — a start
+ * time that was never recorded, a `ps` that would not answer now — resolves to
+ * "alive". Only a pid that is gone, or one whose start time PROVES it is a
+ * different process wearing the same number, is reported dead.
+ */
+export declare function instanceAlive(instance: ProcessInstance, deps?: InstanceLivenessDeps): boolean;

package/dist/process-instance.js

@@ -0,0 +1,82 @@
+/**
+ * PROCESS INSTANCE IDENTITY — a pid paired with its start time, which is what
+ * makes "is that process still alive?" answerable across a pid reuse.
+ *
+ * A bare pid is not an identity: the kernel recycles pids, so a dead writer's
+ * number can belong to an unrelated process minutes later and `kill(pid, 0)`
+ * would report the writer as alive. Pairing the pid with `ps -o lstart=` — a
+ * value the reusing process cannot reproduce, because it is the moment the
+ * kernel started IT — turns the pair into an identity that only the original
+ * process satisfies.
+ *
+ * This is the same instance-key shape `session-grant.ts` uses to decide whether
+ * the app instance a grant was minted for is still the one running; both callers
+ * share this module so the liveness rule is stated once.
+ */
+import { execFileSync } from "node:child_process";
+/**
+ * Does a process with this pid exist right now? (Signal 0 tests existence only.)
+ *
+ * Non-positive pids are rejected BEFORE the syscall, and that guard is
+ * load-bearing rather than defensive tidiness: in `kill(2)`, pid 0 means "every
+ * process in the caller's group" and a negative pid means "the group" — both
+ * succeed, so a zero or negative holder would report itself alive forever and
+ * wedge its idempotency key. A holder is always a real process or it is nothing.
+ */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A pid's start time, or null when the pid is gone / `ps` could not answer. */
+export function processStart(pid) {
+    try {
+        const out = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+            encoding: "utf8",
+            timeout: 3000,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        const trimmed = out.trim();
+        return trimmed === "" ? null : trimmed;
+    }
+    catch {
+        // A dead pid exits nonzero — the instance is gone, which is an answer.
+        return null;
+    }
+}
+/** This process, as the identity to record on a piece of work it is starting. */
+export function currentInstance() {
+    return { pid: process.pid, start: processStart(process.pid) };
+}
+/**
+ * Is the RECORDED instance still running?
+ *
+ * Deliberately CONSERVATIVE: this answers a question whose wrong answer is
+ * expensive in one direction only. Reporting a dead writer as alive costs a
+ * caller one more poll; reporting a LIVE writer as dead invites a second
+ * execution of a mutation that is still in flight. So every ambiguity — a start
+ * time that was never recorded, a `ps` that would not answer now — resolves to
+ * "alive". Only a pid that is gone, or one whose start time PROVES it is a
+ * different process wearing the same number, is reported dead.
+ */
+export function instanceAlive(instance, deps = {}) {
+    const alive = deps.pidAlive ?? pidAlive;
+    const start = deps.processStart ?? processStart;
+    if (!alive(instance.pid))
+        return false;
+    // The pid exists. Without both start times we cannot rule out reuse, so we
+    // do not: the conservative answer is that this is still our process.
+    if (instance.start === null)
+        return true;
+    const current = start(instance.pid);
+    if (current === null)
+        return true;
+    return current === instance.start;
+}
+//# sourceMappingURL=process-instance.js.map

package/dist/process-instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-instance.js","sourceRoot":"","sources":["../src/process-instance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAalD;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE;YACnE,QAAQ,EAAE,MAAM;YAChB,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;AAChE,CAAC;AAQD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,QAAyB,EAAE,OAA6B,EAAE;IACtF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC;IACxC,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC;IAChD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,2EAA2E;IAC3E,qEAAqE;IACrE,IAAI,QAAQ,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,OAAO,KAAK,QAAQ,CAAC,KAAK,CAAC;AACpC,CAAC"}