approval-md 0.3.0 → 0.4.1

package/dist/src/core/harness-version.js

@@ -54,7 +54,14 @@
 import { spawnSync } from "node:child_process";
 import { childEnvironment } from "./child-env.js";
 /** The harnesses this runtime speaks a hook protocol for. */
-export const HARNESS_KINDS = ["claude-code", "cursor", "codex", "grok", "muse"];
+export const HARNESS_KINDS = [
+    "claude-code",
+    "cursor",
+    "codex",
+    "grok",
+    "muse",
+    "hermes",
+];
 /** Is `value` one of the harnesses this runtime knows? */
 export function isHarnessKind(value) {
     return typeof value === "string" && HARNESS_KINDS.includes(value);
@@ -71,6 +78,7 @@ export const HARNESS_BINARY = {
     codex: "codex",
     grok: "grok",
     muse: "muse",
+    hermes: "hermes",
 };
 /**
  * How long a version string may be, and the reason there is a cap at all.
@@ -121,7 +129,40 @@ export function normalizeHarnessVersion(raw) {
  */
 export const HARNESS_PROBE_TIMEOUT_MS = 10_000;
 /**
- * Run `<binary> --version` once, uncached, and normalize what came back.
+ * How long the RAW first line of `<binary> --version` may be.
+ *
+ * Wider than {@link HARNESS_VERSION_LIMIT} because it holds a different kind of
+ * value for a different reader: nothing capped by this number is ever appended to
+ * the log (only {@link normalizeHarnessVersion}'s output is), and what needs the
+ * raw line is a diagnostic that must be able to read a build stamp a harness
+ * prints beside its semver. Hermes prints
+ * `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`, which the log's own
+ * rule rejects on the non-ASCII separator alone. Capped and stripped of control
+ * characters all the same: this is third-party output on its way to a terminal.
+ */
+export const HARNESS_RAW_VERSION_LIMIT = 200;
+/**
+ * The first line of a `--version` output, as a line a diagnostic may print.
+ *
+ * One line, trimmed, control characters removed, capped. `null` for empty output
+ * or a line past the cap. It keeps non-ASCII bytes, which is the whole difference
+ * from {@link normalizeHarnessVersion}: a build stamp behind a typographic
+ * separator is exactly the fact a version floor has to read, and it is exactly
+ * the fact the write boundary will not accept.
+ */
+export function rawHarnessVersionLine(raw) {
+    if (typeof raw !== "string")
+        return null;
+    const first = raw.split("\n", 1)[0] ?? "";
+    // `\p{Cc}` rather than an escaped range: the class is the Unicode CONTROL
+    // category, which is the thing being removed, and it reads as that.
+    const text = first.replace(/\p{Cc}/gu, "").trim();
+    if (text.length === 0 || text.length > HARNESS_RAW_VERSION_LIMIT)
+        return null;
+    return text;
+}
+/**
+ * Run `<binary> --version` once, uncached, and return its raw first line.
  *
  * Every failure is a value rather than an exception, in the manner of
  * {@link spawnGloss}: a missing binary, a non-zero exit and a timeout kill are
@@ -132,7 +173,7 @@ export const HARNESS_PROBE_TIMEOUT_MS = 10_000;
  * vault passphrase, and it has no use for either. Nothing is declared, because
  * reading a version is not a granted action.
  */
-export function probeHarnessVersion(kind) {
+export function probeHarnessVersionRaw(kind) {
     let result;
     try {
         result = spawnSync(HARNESS_BINARY[kind], ["--version"], {
@@ -150,32 +191,158 @@ export function probeHarnessVersion(kind) {
     }
     if (result.error !== undefined || result.status !== 0)
         return null;
-    return normalizeHarnessVersion(result.stdout);
+    return rawHarnessVersionLine(result.stdout);
+}
+/**
+ * Run `<binary> --version` once, uncached, and normalize what came back.
+ *
+ * The recordable form: one line, printable ASCII, capped. Exported for the test
+ * that proves the memo below is a memo.
+ */
+export function probeHarnessVersion(kind) {
+    return normalizeHarnessVersion(probeHarnessVersionRaw(kind));
 }
 /**
  * The memo. Holds the FAILURES too: a harness that is not on PATH is not on
  * PATH, and asking a second time in the same process would pay a second spawn
  * for the same `null`.
- */
-const probed = new Map();
-/**
- * The installed version of `kind`, read at most once per process.
  *
- * This is the only entry point callers should use. `probeHarnessVersion` is
- * exported for the test that proves the memo is a memo.
+ * It holds the RAW line rather than the recordable one, so the two readers — the
+ * provenance field and the version floor — still cost ONE spawn per process
+ * between them. A harness whose raw line the write boundary rejects has a
+ * `null` recordable version and a readable raw one, which is precisely Hermes's
+ * case and precisely why the floor is not read off a record.
  */
-export function installedHarnessVersion(kind) {
+const probed = new Map();
+/** The raw first line of `<binary> --version`, read at most once per process. */
+export function installedHarnessVersionRaw(kind) {
     const memo = probed.get(kind);
     if (memo !== undefined)
         return memo;
-    const value = probeHarnessVersion(kind);
+    const value = probeHarnessVersionRaw(kind);
     probed.set(kind, value);
     return value;
 }
+/**
+ * The installed version of `kind`, read at most once per process.
+ *
+ * This is the only entry point callers should use for a RECORDABLE version.
+ * `probeHarnessVersion` is exported for the test that proves the memo is a memo.
+ */
+export function installedHarnessVersion(kind) {
+    return normalizeHarnessVersion(installedHarnessVersionRaw(kind));
+}
 /** Drop the memo. TEST ONLY: a process reads a version once, by design. */
 export function resetHarnessVersionCache() {
     probed.clear();
 }
+// ---------------------------------------------------------------------------
+// The Hermes fail-closed version floor (APRV-415)
+// ---------------------------------------------------------------------------
+/**
+ * The build at which Hermes Agent starts honouring `fail_closed` (APRV-415).
+ *
+ * ## Why a floor exists at all, and why it is a DATE rather than a version
+ *
+ * `approval hook hermes` is enforcement rather than a backstop only because of a
+ * per-entry `fail_closed: true` that makes a hook crash, a hook timeout and
+ * unparseable hook output BLOCK. The live probe measured both halves of that on
+ * two builds of the same harness, and the answer differs between them:
+ *
+ * - `main` at `118984d7`, built 2026-09-20: crash, garbage and hang were all
+ *   REFUSED (the hang at the 300s per-entry cap). The key works;
+ * - `v0.21.3`, built 2026.9.14: all three PROCEEDED. That build does not know the
+ *   key and ignores it SILENTLY. `hermes hooks list` renders no `fail_closed`
+ *   flag on either build, so the listing cannot be used to tell them apart.
+ *
+ * The two builds report the SAME semver. `hermes --version` on the older one
+ * prints `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`, and the update
+ * that fixed the behaviour moved 670 commits without moving `0.21.3`. So a floor
+ * expressed as a semantic version would compare the one field that did not
+ * change, and would pass a build that fails open. The build DATE and the upstream
+ * commit are the two fields that did move, and they are what this compares.
+ *
+ * ## What it can and cannot do
+ *
+ * It can only ADD a red line to `approval doctor` (SPEC.md §11.1 invariant 4: a
+ * self-reported field never reduces scrutiny). A build claiming a later date buys
+ * nothing — it defeats a row that would have asked a human to look — and nothing
+ * in the runtime reads this to widen a verdict, skip a wait or lower a class. The
+ * refusals the adapter emits are the same on every build; what changes below the
+ * floor is whether a BROKEN hook stops the call, which no code in this repository
+ * can observe from inside the hook it is broken in.
+ */
+export const HERMES_FAIL_CLOSED_FLOOR = {
+    /** The first build observed to honour the key, by upstream commit. */
+    upstream: "118984d7",
+    /** That build's date, in the `YYYY.M.D` stamp `hermes --version` prints. */
+    date: { year: 2026, month: 9, day: 20 },
+    /** The one sentence every surface quotes, so they cannot drift apart. */
+    statement: "a build at or after main 118984d7 of 2026-09-20; v0.21.3 (2026.9.14) fails open silently",
+};
+/**
+ * Read the fields out of `hermes --version`'s first line, or `null`.
+ *
+ * Shape-only and forgiving in one direction: a field this cannot find is `null`
+ * rather than a guess, and a line naming none of the three is not a Hermes
+ * version line at all. The observed line is
+ * `Hermes Agent v0.21.3 (2026.9.14) · upstream 913d4098`; the separator is read
+ * past rather than required, because a release that changes its punctuation must
+ * not silently turn the floor check into an unknown.
+ */
+export function parseHermesVersion(raw) {
+    const line = rawHarnessVersionLine(raw);
+    if (line === null)
+        return null;
+    const semver = /\bv(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)\b/u.exec(line);
+    const stamp = /\((\d{4})\.(\d{1,2})\.(\d{1,2})\)/u.exec(line);
+    const upstream = /\bupstream\s+([0-9a-f]{7,40})\b/iu.exec(line);
+    if (semver === null && stamp === null && upstream === null)
+        return null;
+    return {
+        semver: semver?.[1] ?? null,
+        date: stamp === null
+            ? null
+            : {
+                year: Number(stamp[1]),
+                month: Number(stamp[2]),
+                day: Number(stamp[3]),
+            },
+        upstream: upstream?.[1]?.toLowerCase() ?? null,
+    };
+}
+/**
+ * Does this Hermes build honour `fail_closed`?
+ *
+ * - `"honours"` — its upstream commit IS the floor's, or its build date is on or
+ *   after the floor's date;
+ * - `"ignores"` — its build date is BEFORE the floor's. This is the one answer
+ *   that names a fault, and it is the state a live probe measured rather than
+ *   inferred;
+ * - `"unknown"` — no version could be read, or the line carries neither a build
+ *   date nor the floor's commit. Two commit hashes cannot be ORDERED without a
+ *   repository, so a build stamped with an unfamiliar commit and no date is
+ *   honestly unknown rather than quietly either.
+ *
+ * `"unknown"` is not a synonym for `"ignores"`, deliberately. This value feeds a
+ * health check, and a health check that cried fault on every unreadable banner
+ * would train an operator to stop reading it, which costs more than the case it
+ * would catch. What guards the unknown case instead is the doc, the help block
+ * and the probe's own report, all of which state {@link
+ * HERMES_FAIL_CLOSED_FLOOR.statement} verbatim.
+ */
+export function hermesFailClosedSupport(raw) {
+    const fields = parseHermesVersion(raw);
+    if (fields === null)
+        return "unknown";
+    const floor = HERMES_FAIL_CLOSED_FLOOR;
+    if (fields.upstream !== null && fields.upstream.startsWith(floor.upstream))
+        return "honours";
+    if (fields.date === null)
+        return "unknown";
+    const asNumber = (date) => date.year * 10_000 + date.month * 100 + date.day;
+    return asNumber(fields.date) >= asNumber(floor.date) ? "honours" : "ignores";
+}
 /**
  * Build the pair for `kind`, preferring the version the hook event supplied.
  *

package/dist/src/core/harness-version.js.map

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

package/dist/src/core/harness-wait.d.ts

@@ -2,13 +2,16 @@
  * How long a harness hook waits, and how long the question it opened outlives
  * that wait (APRV-287).
  *
- * Two numbers with two readers each, which is the whole reason they live here
- * rather than beside either one. `cli/hook.ts` uses them to decide when a
- * request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
+ * Three numbers with two readers each, which is the whole reason they live
+ * here rather than beside any one of them. `cli/hook.ts` uses them to decide
+ * when a request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
  * to decide which pending requests on a listener's first cycle are stale enough
  * to collapse into one message. Two copies of the same duration would be two
  * answers to "is anybody still waiting on this", and the channel would collapse
  * questions the hook was still holding open, or leave a dead queue on a phone.
+ * The third, APRV-423's margin, is read by the hook (which refuses a harness
+ * ceiling too short to hold a human's answer) and by `core/state.ts` (which
+ * judges every request against the window that ceiling leaves).
  *
  * Nothing here reads a clock, a policy or the log: these are durations, and
  * every judgment made with them is made by a caller that already holds the
@@ -53,3 +56,79 @@ export declare const HOOK_RETRY_GRACE_MS: number;
  * caller states about when it started waiting.
  */
 export declare function abandonedAfterMs(waitMs: number, graceMs: number): number;
+/**
+ * How far below a harness's own timeout a hook-originated request must lapse
+ * (APRV-423).
+ *
+ * A harness bounds the hook process: Hermes caps a `pre_tool_call` entry at
+ * 300 s, Claude Code kills the hook at the `timeout` in its settings file, and
+ * every one of them treats the killed process as a NON-BLOCKING error and runs
+ * the tool call. So when the harness gives up first the hook is already gone,
+ * the request is still pending on somebody's phone, and the tap that arrives
+ * afterwards is recorded as a grant on a call nobody holds (APRV-410, observed
+ * 2026-09-20). The two records then disagree about the same moment: one says
+ * denied, the other says approved.
+ *
+ * The fix is to make the question end BEFORE the process that asked it does,
+ * and this is the distance between the two. It is 60 s because the daemon's
+ * TTL sweep runs on a 30 s interval (`daemon/daemon.ts`'s
+ * `DEFAULT_INTERVAL_MS`): a request that lapses one millisecond after a sweep
+ * waits a whole interval for the next one, so a margin of two intervals leaves
+ * the `approval.expired` append a full tick of room in the common case, and it
+ * lands inside the cap. Anything smaller would make the ordering this task is
+ * about depend on where in the sweep cycle the lapse fell.
+ *
+ * The common case, and not a guarantee. `Daemon.tick` skips a sweep when the
+ * previous tick is still running, and the request record's `ts` is stamped at
+ * the write boundary, some intake latency after the harness spawned the hook,
+ * so the cap runs from an instant slightly before the one the margin counts
+ * from. An overrunning tick plus a slow intake can put the `approval.expired`
+ * record after the kill. What keeps a late tap safe regardless is not this
+ * margin but the lazy refusal: `core/state.ts` judges the lapse by arithmetic
+ * whether or not the record exists, so `decide` refuses the tap `expired` and
+ * materialises the record then. The margin buys the ORDERING in the common
+ * case, so the two records agree without a human ever seeing the disagreement;
+ * the refusal is what makes the grant impossible in every case.
+ *
+ * It is a floor on the cap as well as a subtraction from it. A cap at or below
+ * the margin leaves no window in which a human could answer at all: `cli/hook.ts`
+ * refuses such a configuration rather than opening a question that is already
+ * dead, and `schema/event.schema.json` refuses a record carrying one at the
+ * write boundary (its `minimum` is this constant plus one, pinned equal by
+ * `tests/harness-cap-ttl.test.ts`).
+ */
+export declare const HARNESS_CAP_MARGIN_MS = 60000;
+/**
+ * The deadline a hook-originated request is judged by: the SHORTER of the
+ * policy's TTL and the harness's cap minus {@link HARNESS_CAP_MARGIN_MS}
+ * (APRV-423).
+ *
+ * `null` means no deadline, exactly as `defaults.approval_ttl`'s absence means
+ * it (SPEC.md §6): nothing lapses, and no duration is invented for a policy
+ * that declared none.
+ *
+ * **The cap may only shorten.** It is a self-reported field (the hook states
+ * the ceiling its own harness runs it under), and SPEC.md §11.1 invariant 4
+ * says such a field never reduces scrutiny. Recording it raw and taking the
+ * minimum HERE is what makes that structural: a cap larger than the policy TTL
+ * changes nothing, a cap of an hour under a one-minute TTL changes nothing, and
+ * the only direction a requester can move its own deadline is earlier. The same
+ * shape as `core/gate-window.ts`'s `expires_at`, which clamps a claimed window
+ * against the derived one for the same reason.
+ *
+ * A cap that does not clear the margin yields `0`, which reads as lapsed from
+ * the instant the request is written. That is the fail-closed answer for a
+ * harness whose ceiling leaves no room for a human, and it is unreachable
+ * through the write path: the hook refuses the configuration before it
+ * appends, and the event schema refuses the record for any caller that did
+ * not come through the hook.
+ */
+export declare function harnessCappedTtlMs(policyTtlMs: number | null, capMs: number | null): number | null;
+/**
+ * Does `capMs` leave a window a human could answer in?
+ *
+ * The one question `cli/hook.ts` asks before it opens a request under a cap.
+ * Strictly greater: a cap EQUAL to the margin yields a zero-length window,
+ * which is a question that expires as it is asked.
+ */
+export declare function harnessCapFitsMargin(capMs: number): boolean;

package/dist/src/core/harness-wait.js

@@ -2,13 +2,16 @@
  * How long a harness hook waits, and how long the question it opened outlives
  * that wait (APRV-287).
  *
- * Two numbers with two readers each, which is the whole reason they live here
- * rather than beside either one. `cli/hook.ts` uses them to decide when a
- * request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
+ * Three numbers with two readers each, which is the whole reason they live
+ * here rather than beside any one of them. `cli/hook.ts` uses them to decide
+ * when a request it opened has been abandoned; `cli/channel-telegram.ts` uses the wait
  * to decide which pending requests on a listener's first cycle are stale enough
  * to collapse into one message. Two copies of the same duration would be two
  * answers to "is anybody still waiting on this", and the channel would collapse
  * questions the hook was still holding open, or leave a dead queue on a phone.
+ * The third, APRV-423's margin, is read by the hook (which refuses a harness
+ * ceiling too short to hold a human's answer) and by `core/state.ts` (which
+ * judges every request against the window that ceiling leaves).
  *
  * Nothing here reads a clock, a policy or the log: these are durations, and
  * every judgment made with them is made by a caller that already holds the
@@ -55,4 +58,87 @@ export const HOOK_RETRY_GRACE_MS = 5 * 60_000;
 export function abandonedAfterMs(waitMs, graceMs) {
     return Math.max(0, waitMs) + Math.max(0, graceMs);
 }
+/**
+ * How far below a harness's own timeout a hook-originated request must lapse
+ * (APRV-423).
+ *
+ * A harness bounds the hook process: Hermes caps a `pre_tool_call` entry at
+ * 300 s, Claude Code kills the hook at the `timeout` in its settings file, and
+ * every one of them treats the killed process as a NON-BLOCKING error and runs
+ * the tool call. So when the harness gives up first the hook is already gone,
+ * the request is still pending on somebody's phone, and the tap that arrives
+ * afterwards is recorded as a grant on a call nobody holds (APRV-410, observed
+ * 2026-09-20). The two records then disagree about the same moment: one says
+ * denied, the other says approved.
+ *
+ * The fix is to make the question end BEFORE the process that asked it does,
+ * and this is the distance between the two. It is 60 s because the daemon's
+ * TTL sweep runs on a 30 s interval (`daemon/daemon.ts`'s
+ * `DEFAULT_INTERVAL_MS`): a request that lapses one millisecond after a sweep
+ * waits a whole interval for the next one, so a margin of two intervals leaves
+ * the `approval.expired` append a full tick of room in the common case, and it
+ * lands inside the cap. Anything smaller would make the ordering this task is
+ * about depend on where in the sweep cycle the lapse fell.
+ *
+ * The common case, and not a guarantee. `Daemon.tick` skips a sweep when the
+ * previous tick is still running, and the request record's `ts` is stamped at
+ * the write boundary, some intake latency after the harness spawned the hook,
+ * so the cap runs from an instant slightly before the one the margin counts
+ * from. An overrunning tick plus a slow intake can put the `approval.expired`
+ * record after the kill. What keeps a late tap safe regardless is not this
+ * margin but the lazy refusal: `core/state.ts` judges the lapse by arithmetic
+ * whether or not the record exists, so `decide` refuses the tap `expired` and
+ * materialises the record then. The margin buys the ORDERING in the common
+ * case, so the two records agree without a human ever seeing the disagreement;
+ * the refusal is what makes the grant impossible in every case.
+ *
+ * It is a floor on the cap as well as a subtraction from it. A cap at or below
+ * the margin leaves no window in which a human could answer at all: `cli/hook.ts`
+ * refuses such a configuration rather than opening a question that is already
+ * dead, and `schema/event.schema.json` refuses a record carrying one at the
+ * write boundary (its `minimum` is this constant plus one, pinned equal by
+ * `tests/harness-cap-ttl.test.ts`).
+ */
+export const HARNESS_CAP_MARGIN_MS = 60_000;
+/**
+ * The deadline a hook-originated request is judged by: the SHORTER of the
+ * policy's TTL and the harness's cap minus {@link HARNESS_CAP_MARGIN_MS}
+ * (APRV-423).
+ *
+ * `null` means no deadline, exactly as `defaults.approval_ttl`'s absence means
+ * it (SPEC.md §6): nothing lapses, and no duration is invented for a policy
+ * that declared none.
+ *
+ * **The cap may only shorten.** It is a self-reported field (the hook states
+ * the ceiling its own harness runs it under), and SPEC.md §11.1 invariant 4
+ * says such a field never reduces scrutiny. Recording it raw and taking the
+ * minimum HERE is what makes that structural: a cap larger than the policy TTL
+ * changes nothing, a cap of an hour under a one-minute TTL changes nothing, and
+ * the only direction a requester can move its own deadline is earlier. The same
+ * shape as `core/gate-window.ts`'s `expires_at`, which clamps a claimed window
+ * against the derived one for the same reason.
+ *
+ * A cap that does not clear the margin yields `0`, which reads as lapsed from
+ * the instant the request is written. That is the fail-closed answer for a
+ * harness whose ceiling leaves no room for a human, and it is unreachable
+ * through the write path: the hook refuses the configuration before it
+ * appends, and the event schema refuses the record for any caller that did
+ * not come through the hook.
+ */
+export function harnessCappedTtlMs(policyTtlMs, capMs) {
+    if (capMs === null)
+        return policyTtlMs;
+    const fromCap = Math.max(0, capMs - HARNESS_CAP_MARGIN_MS);
+    return policyTtlMs === null ? fromCap : Math.min(policyTtlMs, fromCap);
+}
+/**
+ * Does `capMs` leave a window a human could answer in?
+ *
+ * The one question `cli/hook.ts` asks before it opens a request under a cap.
+ * Strictly greater: a cap EQUAL to the margin yields a zero-length window,
+ * which is a question that expires as it is asked.
+ */
+export function harnessCapFitsMargin(capMs) {
+    return capMs > HARNESS_CAP_MARGIN_MS;
+}
 //# sourceMappingURL=harness-wait.js.map

package/dist/src/core/harness-wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-wait.js","sourceRoot":"","sources":["../../../src/core/harness-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"harness-wait.js","sourceRoot":"","sources":["../../../src/core/harness-wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC,iDAAiD;AACjD,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,MAAM,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAe;IAC9D,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAA0B,EAC1B,KAAoB;IAEpB,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,WAAW,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,qBAAqB,CAAC,CAAC;IAC3D,OAAO,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,GAAG,qBAAqB,CAAC;AACvC,CAAC"}