@lannguyensi/harness 0.5.0

package/dist/policies/ledger-client.js

@@ -0,0 +1,378 @@
+// Phase 4 #3 — grounding-mcp client adapter.
+//
+// Spawns the configured grounding-mcp server, performs the standard
+// init / notifications/initialized / tools/call handshake, and returns
+// ledger entries normalised to harness's LedgerEntry shape (see
+// src/policies/requires.ts). Any failure path resolves to
+// `{ kind: "degraded", reason }` so the policy evaluator can fall back to
+// warn-mode per ROADMAP §"Phase 4 — Policy layer" acceptance: "When the
+// evidence ledger is unreachable, policy evaluation defaults to
+// enforcement: warn-equivalent behaviour".
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 5_000;
+function expandHomePath(p) {
+    if (p === "~")
+        return process.env.HOME ?? "";
+    if (p.startsWith("~/"))
+        return `${process.env.HOME ?? ""}/${p.slice(2)}`;
+    return p;
+}
+function normaliseEntry(raw, bucketType) {
+    if (raw.id === undefined || raw.id === null)
+        return null;
+    if (typeof raw.content !== "string")
+        return null;
+    const createdAt = typeof raw.createdAt === "string"
+        ? raw.createdAt
+        : typeof raw.created_at === "string"
+            ? raw.created_at
+            : undefined;
+    if (createdAt === undefined)
+        return null;
+    // Prefer the bucket-derived type (Phase 5 #4 — bucket name is the
+    // canonical type signal); fall back to the row's own `type` field
+    // if the wire payload happens to carry it.
+    const type = bucketType ?? (typeof raw.type === "string" ? raw.type : undefined);
+    return {
+        id: String(raw.id),
+        content: raw.content,
+        source: typeof raw.source === "string" ? raw.source : undefined,
+        createdAt,
+        ...(type !== undefined && { type }),
+    };
+}
+/**
+ * Flatten the bucketed arrays returned by `ledger_summary` into one list.
+ * Tolerates both snake_case (`created_at`) and camelCase (`createdAt`) since
+ * the MCP wire format is JSON.stringify of whatever the underlying lib emits.
+ *
+ * Phase 5 #4 — surfaces the wire bucket as `LedgerEntry.type`
+ * (`facts` → `fact`, `policyDecisions` → `policy_decision`, etc.) so
+ * downstream filters can distinguish evidence from audit records.
+ * `flattenSummary` returns ALL buckets; consumers filter by type.
+ *
+ * Returns `null` when the payload doesn't carry an `entries` object — the
+ * caller treats that as a contract-drift degraded path.
+ */
+const BUCKET_TO_TYPE = {
+    facts: "fact",
+    hypotheses: "hypothesis",
+    rejected: "rejected",
+    unknowns: "unknown",
+    policyDecisions: "policy_decision",
+};
+function flattenSummary(payload) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const root = payload;
+    const entries = root.entries;
+    if (!entries || typeof entries !== "object" || Array.isArray(entries)) {
+        return null;
+    }
+    const buckets = entries;
+    const out = [];
+    for (const [bucketKey, type] of Object.entries(BUCKET_TO_TYPE)) {
+        const arr = buckets[bucketKey];
+        if (!Array.isArray(arr))
+            continue;
+        for (const raw of arr) {
+            const norm = normaliseEntry(raw, type);
+            if (norm)
+                out.push(norm);
+        }
+    }
+    return out;
+}
+function startSubprocess(opts) {
+    const list = opts.mcpCommand;
+    if (!list || list.length === 0) {
+        return { ok: false, reason: "grounding-mcp command is empty" };
+    }
+    const exe = expandHomePath(list[0]);
+    const args = list.slice(1).map(expandHomePath);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    let child;
+    try {
+        child = spawn(exe, args, {
+            cwd: opts.cwd,
+            env: { ...process.env, ...(opts.mcpEnv ?? {}) },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `grounding-mcp spawn failed: ${err.message}`,
+        };
+    }
+    const stderrBuf = { value: "" };
+    let stdoutBuf = "";
+    let processExited = false;
+    let exitCode = null;
+    let exitSignal = null;
+    const pending = new Map();
+    const timers = new Set();
+    child.stderr.on("data", (chunk) => {
+        stderrBuf.value += chunk.toString("utf8");
+    });
+    child.stdin.on("error", () => {
+        /* EPIPE on shutdown; surfaced via the exit listener. */
+    });
+    let spawnError = null;
+    child.on("error", (err) => {
+        spawnError = err;
+        processExited = true;
+    });
+    child.on("exit", (code, signal) => {
+        processExited = true;
+        exitCode = code;
+        exitSignal = signal;
+    });
+    child.stdout.on("data", (chunk) => {
+        stdoutBuf += chunk.toString("utf8");
+        let nl = stdoutBuf.indexOf("\n");
+        while (nl !== -1) {
+            const line = stdoutBuf.slice(0, nl).trim();
+            stdoutBuf = stdoutBuf.slice(nl + 1);
+            if (line) {
+                try {
+                    const msg = JSON.parse(line);
+                    if (typeof msg.id === "number") {
+                        const handler = pending.get(msg.id);
+                        if (handler) {
+                            pending.delete(msg.id);
+                            handler.resolve(msg);
+                        }
+                    }
+                }
+                catch {
+                    /* ignore non-JSON lines */
+                }
+            }
+            nl = stdoutBuf.indexOf("\n");
+        }
+    });
+    const exitPromise = new Promise((resolve) => {
+        if (processExited) {
+            resolve("exit");
+            return;
+        }
+        const done = () => resolve("exit");
+        child.once("exit", done);
+        child.once("error", done);
+    });
+    function timeoutPromise() {
+        return new Promise((resolve) => {
+            const t = setTimeout(() => {
+                timers.delete(t);
+                resolve("timeout");
+            }, timeoutMs);
+            t.unref();
+            timers.add(t);
+        });
+    }
+    function send(id, method, params) {
+        return new Promise((resolve) => {
+            pending.set(id, { id, resolve });
+            try {
+                if (!processExited && !child.stdin.destroyed && child.stdin.writable) {
+                    child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+                }
+            }
+            catch {
+                /* server closed stdin; the exit-promise race resolves the call */
+            }
+        });
+    }
+    function call(id, method, params) {
+        return Promise.race([send(id, method, params), exitPromise, timeoutPromise()]);
+    }
+    function notify(method, params = {}) {
+        try {
+            if (!processExited && !child.stdin.destroyed && child.stdin.writable) {
+                child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    function cleanup() {
+        for (const t of timers)
+            clearTimeout(t);
+        timers.clear();
+        if (!processExited)
+            child.kill("SIGTERM");
+    }
+    return {
+        ok: true,
+        ctl: {
+            child,
+            stderrBuf,
+            pending,
+            call,
+            notify,
+            exited: () => processExited,
+            exitCode: () => exitCode,
+            exitSignal: () => exitSignal,
+            spawnError: () => spawnError,
+            cleanup,
+        },
+    };
+}
+/**
+ * Phase 5 #5 — read the inputSchema for `ledger_summary` from a
+ * `tools/list` response and project the set of advertised property
+ * names (which are the args harness can send without tripping a zod
+ * rejection on an older server).
+ *
+ * Defensive: any unexpected shape (timeout, exit, non-array, missing
+ * inputSchema) returns the conservative `{ "sessionId" }` set so the
+ * caller falls back to client-side filtering instead of speculatively
+ * including args that an old server would reject.
+ */
+async function detectLedgerSummaryArgs(ctl, _timeoutMs) {
+    const fallback = new Set(["sessionId"]);
+    const result = await ctl.call(2, "tools/list", {});
+    if (result === "exit" || result === "timeout")
+        return fallback;
+    if (result.error)
+        return fallback;
+    const r = result.result;
+    if (!r || !Array.isArray(r.tools))
+        return fallback;
+    for (const tool of r.tools) {
+        const t = tool;
+        if (t.name !== "ledger_summary")
+            continue;
+        const schema = t.inputSchema;
+        if (!schema || !schema.properties || typeof schema.properties !== "object") {
+            return fallback;
+        }
+        return new Set(Object.keys(schema.properties));
+    }
+    return fallback;
+}
+function exitDiagnostic(ctl) {
+    const err = ctl.spawnError();
+    if (err)
+        return `spawn failed: ${err.message}`;
+    const tail = ctl.stderrBuf.value.trim().split("\n").pop()?.trim() || "(no stderr)";
+    const code = ctl.exitCode();
+    const sig = ctl.exitSignal();
+    const status = code !== null ? `exit ${code}` : sig ? `signal ${sig}` : "exited";
+    return `${status}: ${tail}`;
+}
+function extractToolPayload(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    if (r.structuredContent && typeof r.structuredContent === "object") {
+        return r.structuredContent;
+    }
+    if (Array.isArray(r.content)) {
+        for (const block of r.content) {
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string") {
+                try {
+                    return JSON.parse(b.text);
+                }
+                catch {
+                    /* not JSON; fall through */
+                }
+            }
+        }
+    }
+    return null;
+}
+export async function queryLedgerByTag(opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const start = startSubprocess(opts);
+    if (!start.ok)
+        return { kind: "degraded", reason: start.reason };
+    const ctl = start.ctl;
+    try {
+        const initResult = await ctl.call(1, "initialize", {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "harness-policies", version: "0.4.0" },
+        });
+        if (initResult === "exit") {
+            return {
+                kind: "degraded",
+                reason: `grounding-mcp ${exitDiagnostic(ctl)}`,
+            };
+        }
+        if (initResult === "timeout") {
+            return {
+                kind: "degraded",
+                reason: `grounding-mcp timeout after ${timeoutMs}ms`,
+            };
+        }
+        if (initResult.error) {
+            return {
+                kind: "degraded",
+                reason: `grounding-mcp initialize error: ${initResult.error.message ?? "unknown"}`,
+            };
+        }
+        ctl.notify("notifications/initialized");
+        // Phase 5 #5 — capability detection only when we actually want to
+        // push a filter server-side. Older grounding-mcp builds accept only
+        // `sessionId` on `ledger_summary`; harness spawns a binary path
+        // chosen by the operator, so we cannot assume a version. Skipping
+        // tools/list when no filter is requested keeps the unfiltered hot
+        // path one round-trip fewer.
+        const wantsFilter = opts.sinceIso !== undefined || opts.contentPrefix !== undefined;
+        const supportedArgs = wantsFilter
+            ? await detectLedgerSummaryArgs(ctl, timeoutMs)
+            : new Set(["sessionId"]);
+        const callArgs = { sessionId: opts.sessionId };
+        if (opts.sinceIso !== undefined && supportedArgs.has("sinceIso")) {
+            callArgs.sinceIso = opts.sinceIso;
+        }
+        if (opts.contentPrefix !== undefined && supportedArgs.has("contentPrefix")) {
+            callArgs.contentPrefix = opts.contentPrefix;
+        }
+        const callResult = await ctl.call(3, "tools/call", {
+            name: "ledger_summary",
+            arguments: callArgs,
+        });
+        if (callResult === "exit") {
+            return {
+                kind: "degraded",
+                reason: `grounding-mcp ${exitDiagnostic(ctl)}`,
+            };
+        }
+        if (callResult === "timeout") {
+            return {
+                kind: "degraded",
+                reason: `grounding-mcp timeout after ${timeoutMs}ms`,
+            };
+        }
+        if (callResult.error) {
+            return {
+                kind: "degraded",
+                reason: `ledger_summary error: ${callResult.error.message ?? "unknown"}`,
+            };
+        }
+        const payload = extractToolPayload(callResult.result);
+        if (payload === null) {
+            return {
+                kind: "degraded",
+                reason: "ledger_summary returned no parseable payload",
+            };
+        }
+        const entries = flattenSummary(payload);
+        if (entries === null) {
+            return {
+                kind: "degraded",
+                reason: "ledger_summary payload missing `entries` shape",
+            };
+        }
+        return { kind: "ok", entries };
+    }
+    finally {
+        ctl.cleanup();
+    }
+}
+//# sourceMappingURL=ledger-client.js.map

package/dist/policies/ledger-client.js.map

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

package/dist/policies/requires.d.ts

@@ -0,0 +1,44 @@
+import type { Requires } from "../schema/requires.js";
+export interface LedgerEntry {
+    id: string;
+    content: string;
+    source?: string;
+    createdAt: string | Date;
+    /**
+     * Phase 5 #4 — the wire bucket the entry came from. `flattenSummary`
+     * populates this from the `entries.<bucket>` key in the ledger_summary
+     * payload, mapping bucket names back to evidence-ledger types
+     * (`facts` → `fact`, `policyDecisions` → `policy_decision`, etc.).
+     *
+     * The requires evaluator uses this to skip `policy_decision` rows so
+     * past audit-log entries don't substring-match the tag they're about
+     * (the substring-pollution bug from PR #39's dogfood).
+     */
+    type?: string;
+}
+export interface RequiresEvaluation {
+    allowed: boolean;
+    reason: string;
+    matchedCount: number;
+    traceData: RequiresTrace;
+}
+export interface RequiresTrace {
+    ledgerTag: string;
+    windowSeconds: number | null;
+    totalEntries: number;
+    matchedEntryIds: string[];
+    countBound: {
+        min?: number;
+        max?: number;
+        exact?: number;
+    } | null;
+    evaluatedAt: string;
+}
+export interface EvaluateRequiresOptions {
+    /** Override "now" for deterministic testing. */
+    now?: Date;
+}
+export declare class RequiresEvaluationError extends Error {
+    constructor(message: string);
+}
+export declare function evaluateRequires(requires: Requires, ledgerEntries: LedgerEntry[], options?: EvaluateRequiresOptions): RequiresEvaluation;

package/dist/policies/requires.js

@@ -0,0 +1,146 @@
+import { InvalidDurationError, parseDurationSeconds } from "./duration.js";
+import { parseLedgerTimestamp } from "./timestamp.js";
+export class RequiresEvaluationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RequiresEvaluationError";
+    }
+}
+// Matches against `content` and `source` per ARCHITECTURE.md §6
+// ("substring/regex match against ledger entries' content/source columns").
+// v1 is substring-only; regex is a v2 deferral.
+function entryMatches(entry, tag) {
+    // Phase 5 #4 — `policy_decision` rows are audit records, not
+    // evidence. Their serialised payload incidentally contains the tag
+    // they're about ("ledgerTag":"review:42"), which under the old
+    // substring filter inflated matchedCount on the same tag the
+    // decision was about. Skip them at the matcher.
+    if (entry.type === "policy_decision")
+        return false;
+    // Legacy backstop: pre-Phase-5-#4 audit rows were written with
+    // type='fact' + a `policy_decision:` content prefix. They land in
+    // the `facts` bucket and would otherwise sneak past the type guard.
+    // The content-prefix check is exact and cheap, so a user upgrading
+    // harness without flushing their dev ledger doesn't keep paying the
+    // pollution tax until the rows age out.
+    if (entry.content.startsWith("policy_decision:"))
+        return false;
+    if (entry.content.includes(tag))
+        return true;
+    if (entry.source && entry.source.includes(tag))
+        return true;
+    return false;
+}
+function entryTime(entry) {
+    const v = entry.createdAt;
+    const ms = v instanceof Date ? v.getTime() : parseLedgerTimestamp(v);
+    if (Number.isNaN(ms)) {
+        throw new RequiresEvaluationError(`ledger entry ${entry.id} has unparseable createdAt: ${String(v)}`);
+    }
+    return ms;
+}
+function describeBound(c) {
+    if (c.exact !== undefined)
+        return String(c.exact);
+    if (c.min !== undefined && c.max !== undefined)
+        return `${c.min}..${c.max}`;
+    if (c.min !== undefined)
+        return String(c.min);
+    if (c.max !== undefined)
+        return `≤${c.max}`;
+    return "?";
+}
+export function evaluateRequires(requires, ledgerEntries, options = {}) {
+    const now = options.now ?? new Date();
+    const evaluatedAt = now.toISOString();
+    const tag = requires.ledger_tag;
+    let windowSeconds = null;
+    if (requires.within !== undefined) {
+        try {
+            windowSeconds = parseDurationSeconds(requires.within);
+        }
+        catch (err) {
+            if (err instanceof InvalidDurationError) {
+                throw new RequiresEvaluationError(err.message);
+            }
+            throw err;
+        }
+    }
+    if (requires.count?.min !== undefined && requires.count.min === 0) {
+        throw new RequiresEvaluationError("requires.count.min must be > 0 (count.min:0 is a no-op)");
+    }
+    const tagMatched = ledgerEntries.filter((e) => entryMatches(e, tag));
+    let windowMatched = tagMatched;
+    if (windowSeconds !== null) {
+        const cutoff = now.getTime() - windowSeconds * 1000;
+        windowMatched = tagMatched.filter((e) => entryTime(e) >= cutoff);
+    }
+    const matchedCount = windowMatched.length;
+    const matchedEntryIds = windowMatched.map((e) => e.id);
+    const countBound = requires.count
+        ? {
+            ...(requires.count.min !== undefined && { min: requires.count.min }),
+            ...(requires.count.max !== undefined && { max: requires.count.max }),
+            ...(requires.count.exact !== undefined && { exact: requires.count.exact }),
+        }
+        : null;
+    const trace = {
+        ledgerTag: tag,
+        windowSeconds,
+        totalEntries: ledgerEntries.length,
+        matchedEntryIds,
+        countBound,
+        evaluatedAt,
+    };
+    if (requires.count !== undefined) {
+        const c = requires.count;
+        const failsMin = c.min !== undefined && matchedCount < c.min;
+        const failsMax = c.max !== undefined && matchedCount > c.max;
+        const failsExact = c.exact !== undefined && matchedCount !== c.exact;
+        if (failsMin || failsMax || failsExact) {
+            let reason;
+            if (failsMax) {
+                reason = `${matchedCount} matching entries exceeds count.max ${c.max}`;
+            }
+            else {
+                const required = failsExact ? c.exact : c.min;
+                reason = `${matchedCount} of required ${required} entries found`;
+            }
+            return {
+                allowed: false,
+                reason,
+                matchedCount,
+                traceData: trace,
+            };
+        }
+        return {
+            allowed: true,
+            reason: `${matchedCount} entries matched (count bound: ${describeBound(c)})`,
+            matchedCount,
+            traceData: trace,
+        };
+    }
+    if (matchedCount === 0) {
+        if (windowSeconds !== null && tagMatched.length > 0) {
+            return {
+                allowed: false,
+                reason: `no matching entry within ${requires.within}`,
+                matchedCount,
+                traceData: trace,
+            };
+        }
+        return {
+            allowed: false,
+            reason: `no matching ledger entry for tag \`${tag}\``,
+            matchedCount,
+            traceData: trace,
+        };
+    }
+    return {
+        allowed: true,
+        reason: `${matchedCount} matching ledger entr${matchedCount === 1 ? "y" : "ies"} for tag \`${tag}\``,
+        matchedCount,
+        traceData: trace,
+    };
+}
+//# sourceMappingURL=requires.js.map

package/dist/policies/requires.js.map

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

package/dist/policies/timestamp.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalise a ledger `createdAt` string to an epoch-millis value.
+ *
+ * Accepted shapes:
+ *   - `YYYY-MM-DD HH:MM:SS`            (SQLite `datetime('now')`, UTC)
+ *   - `YYYY-MM-DD HH:MM:SS.sss`        (SQLite with subsecond precision)
+ *   - `YYYY-MM-DDTHH:MM:SS[.sss]`      (ISO-8601 without zone) — treated as UTC
+ *   - `YYYY-MM-DDTHH:MM:SS[.sss]Z`     (already-UTC ISO) — passed through
+ *   - `YYYY-MM-DDTHH:MM:SS[.sss]±HH:MM` (zoned ISO) — passed through
+ *
+ * Returns `NaN` when the input does not match any of these. Callers that
+ * want a hard failure should check `Number.isNaN`.
+ */
+export declare function parseLedgerTimestamp(raw: string): number;

package/dist/policies/timestamp.js

@@ -0,0 +1,36 @@
+// Phase 5 #8 — shared ledger-timestamp parser.
+//
+// `evidence-ledger`'s `created_at` column is populated by SQLite's
+// `datetime('now')`, which writes UTC text in `YYYY-MM-DD HH:MM:SS`
+// format (no `T`, no trailing `Z`). `Date.parse` of a space-separated
+// timestamp without an explicit zone is implementation-defined; modern
+// V8 interprets it as local time, so on any non-UTC host the parsed
+// epoch lands `(host TZ offset)` hours away from the actual UTC moment.
+//
+// This helper normalises the input before delegating to `Date.parse` so
+// every caller sees a UTC-correct epoch regardless of `TZ`.
+/**
+ * Normalise a ledger `createdAt` string to an epoch-millis value.
+ *
+ * Accepted shapes:
+ *   - `YYYY-MM-DD HH:MM:SS`            (SQLite `datetime('now')`, UTC)
+ *   - `YYYY-MM-DD HH:MM:SS.sss`        (SQLite with subsecond precision)
+ *   - `YYYY-MM-DDTHH:MM:SS[.sss]`      (ISO-8601 without zone) — treated as UTC
+ *   - `YYYY-MM-DDTHH:MM:SS[.sss]Z`     (already-UTC ISO) — passed through
+ *   - `YYYY-MM-DDTHH:MM:SS[.sss]±HH:MM` (zoned ISO) — passed through
+ *
+ * Returns `NaN` when the input does not match any of these. Callers that
+ * want a hard failure should check `Number.isNaN`.
+ */
+export function parseLedgerTimestamp(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return NaN;
+    // Already-zoned (ends with Z or ±HH:MM after the time portion).
+    if (/[Zz]$/.test(raw) || /[+-]\d{2}:?\d{2}$/.test(raw)) {
+        return Date.parse(raw);
+    }
+    // Space-separated SQL DATETIME → coerce to ISO-with-Z.
+    const iso = raw.includes("T") ? `${raw}Z` : `${raw.replace(" ", "T")}Z`;
+    return Date.parse(iso);
+}
+//# sourceMappingURL=timestamp.js.map

package/dist/policies/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp.js","sourceRoot":"","sources":["../../src/policies/timestamp.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,sEAAsE;AACtE,uEAAuE;AACvE,oEAAoE;AACpE,wEAAwE;AACxE,EAAE;AACF,wEAAwE;AACxE,4DAA4D;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,CAAC;IAC5D,gEAAgE;IAChE,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,uDAAuD;IACvD,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;IACxE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC"}