@dungle-scrubs/harness-cli-normalizer 0.1.3 → 0.3.0

package/dist/interpretation/limits.d.ts

@@ -9,8 +9,17 @@
  * Feed these wall-eligible output only - stderr and the non-JSON tail of a
  * dying turn - never assistant message content, where the model merely
  * TALKING about limits would match.
+ *
+ * Matchers are serializable objects {pattern, flags, code/kind}; compilation
+ * to RegExp happens here with bounded inputs (pattern length, count, flags)
+ * and a WeakMap cache. The input window (first 4096 chars of a line), not
+ * pattern analysis, is the backtracking bound - a malicious pattern could
+ * otherwise catastrophically backtrack on a long line.
  */
-import type { AuthFailureKind, HarnessDescriptor, LimitCode } from "../knowledge/descriptor.js";
+import type { AuthFailureKind, AuthMatcher, HarnessDescriptor, LimitCode, LimitMatcher } from "../knowledge/descriptor.js";
+export declare const compileLimitMatchers: (matchers: ReadonlyArray<LimitMatcher>) => ReadonlyArray<readonly [RegExp, LimitCode]>;
+export declare const compileAuthMatchers: (matchers: ReadonlyArray<AuthMatcher>) => ReadonlyArray<readonly [RegExp, AuthFailureKind]>;
+export declare const compileMatchers: <T extends LimitMatcher | AuthMatcher>(matchers: ReadonlyArray<T>) => ReadonlyArray<readonly [RegExp, unknown]>;
 /** Per-line entry point for streaming readers: O(1) per line, no rescans. */
 export declare const detectLimitInLine: (h: HarnessDescriptor, line: string) => LimitCode | null;
 /** Batch convenience over a turn's tail, bounded and bottom-up. */

package/dist/interpretation/limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/interpretation/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAoChG,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,MAAO,iBAAiB,QAAQ,MAAM,KAAG,SAAS,GAAG,IAC3C,CAAC;AAEzC,mEAAmE;AACnE,eAAO,MAAM,WAAW,MAAO,iBAAiB,UAAU,MAAM,KAAG,SAAS,GAAG,IAC5C,CAAC;AAEpC,eAAO,MAAM,uBAAuB,MAC/B,iBAAiB,QACd,MAAM,KACX,eAAe,GAAG,IAA6C,CAAC;AAEnE,eAAO,MAAM,iBAAiB,MAAO,iBAAiB,UAAU,MAAM,KAAG,eAAe,GAAG,IACzD,CAAC"}
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/interpretation/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,YAAY,EACb,MAAM,4BAA4B,CAAC;AA0CpC,eAAO,MAAM,oBAAoB,aACrB,aAAa,CAAC,YAAY,CAAC,KACpC,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAS5C,CAAC;AAEF,eAAO,MAAM,mBAAmB,aACpB,aAAa,CAAC,WAAW,CAAC,KACnC,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,CASlD,CAAC;AAGF,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,YAAY,GAAG,WAAW,YACxD,aAAa,CAAC,CAAC,CAAC,KACzB,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAW1C,CAAC;AAgCF,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,MAAO,iBAAiB,QAAQ,MAAM,KAAG,SAAS,GAAG,IACrB,CAAC;AAE/D,mEAAmE;AACnE,eAAO,MAAM,WAAW,MAAO,iBAAiB,UAAU,MAAM,KAAG,SAAS,GAAG,IACtB,CAAC;AAE1D,eAAO,MAAM,uBAAuB,MAC/B,iBAAiB,QACd,MAAM,KACX,eAAe,GAAG,IAAkE,CAAC;AAExF,eAAO,MAAM,iBAAiB,MAAO,iBAAiB,UAAU,MAAM,KAAG,eAAe,GAAG,IACpC,CAAC"}

package/dist/interpretation/limits.js

@@ -1,11 +1,90 @@
+/**
+ * Wall detection: pure classification of harness output against the
+ * descriptor's limit and auth matchers. Returns the CODE, never the matched
+ * line - the consumers of a detection are a retained record and a viewer
+ * warning, and anything the harness printed on that line (a prompt, a
+ * filename, a customer's name) must not ride along (v1 D-005: records carry
+ * identifiers and outcomes, never content).
+ *
+ * Feed these wall-eligible output only - stderr and the non-JSON tail of a
+ * dying turn - never assistant message content, where the model merely
+ * TALKING about limits would match.
+ *
+ * Matchers are serializable objects {pattern, flags, code/kind}; compilation
+ * to RegExp happens here with bounded inputs (pattern length, count, flags)
+ * and a WeakMap cache. The input window (first 4096 chars of a line), not
+ * pattern analysis, is the backtracking bound - a malicious pattern could
+ * otherwise catastrophically backtrack on a long line.
+ */
 /** Bottom-up batch scans stop after this many non-empty lines: the wall is
  * virtually always the last thing a dying turn printed, and an unbounded
  * scan over an accumulating session buffer is O(turns x output). */
 const BATCH_SCAN_MAX_LINES = 200;
+/** Max pattern length and max matchers per harness per kind - load-bearing
+ * bounds that prevent a crafted override file from DoS'ing the matcher
+ * compiler or the scanner. */
+const MAX_PATTERN_LENGTH = 200;
+const MAX_MATCHERS_PER_KIND = 64;
+const WINDOW = 4096;
+// WeakMap cache: same matcher array instance reuses identical RegExp objects
+const limitCache = new WeakMap();
+const authCache = new WeakMap();
+const validateAndCompile = (pattern, flags) => {
+    const f = flags ?? "i";
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        throw new Error(`pattern over ${MAX_PATTERN_LENGTH} characters`);
+    }
+    if (f.includes("g") || f.includes("y")) {
+        throw new Error(`flags must not contain g or y (got ${JSON.stringify(f)})`);
+    }
+    for (const ch of f) {
+        if (!"imsu".includes(ch))
+            throw new Error(`flag ${JSON.stringify(ch)} outside imsu`);
+    }
+    try {
+        return new RegExp(pattern, f);
+    }
+    catch (e) {
+        throw new Error(`uncompilable pattern ${JSON.stringify(pattern)}: ${e.message}`);
+    }
+};
+export const compileLimitMatchers = (matchers) => {
+    const cached = limitCache.get(matchers);
+    if (cached !== undefined)
+        return cached;
+    if (matchers.length > MAX_MATCHERS_PER_KIND) {
+        throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
+    }
+    const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), m.code]);
+    limitCache.set(matchers, compiled);
+    return compiled;
+};
+export const compileAuthMatchers = (matchers) => {
+    const cached = authCache.get(matchers);
+    if (cached !== undefined)
+        return cached;
+    if (matchers.length > MAX_MATCHERS_PER_KIND) {
+        throw new Error(`more than ${MAX_MATCHERS_PER_KIND} matchers per harness per kind`);
+    }
+    const compiled = matchers.map((m) => [validateAndCompile(m.pattern, m.flags), m.kind]);
+    authCache.set(matchers, compiled);
+    return compiled;
+};
+// Generic alias for tests that call compileMatchers directly
+export const compileMatchers = (matchers) => {
+    // Dispatch based on first element's shape - limit has code, auth has kind
+    if (matchers.length === 0)
+        return [];
+    const first = matchers[0];
+    if ("code" in first)
+        return compileLimitMatchers(matchers);
+    return compileAuthMatchers(matchers);
+};
 const scanLine = (line, matchers) => {
+    const windowed = line.slice(0, WINDOW);
     for (let i = 0; i < matchers.length; i++) {
         const matcher = matchers[i];
-        if (matcher?.[0].test(line))
+        if (matcher?.[0].test(windowed))
             return matcher[1];
     }
     return null;
@@ -27,9 +106,9 @@ const scanTail = (output, matchers) => {
     return null;
 };
 /** Per-line entry point for streaming readers: O(1) per line, no rescans. */
-export const detectLimitInLine = (h, line) => scanLine(line.trim(), h.limitMatchers);
+export const detectLimitInLine = (h, line) => scanLine(line.trim(), compileLimitMatchers(h.limitMatchers));
 /** Batch convenience over a turn's tail, bounded and bottom-up. */
-export const detectLimit = (h, output) => scanTail(output, h.limitMatchers);
-export const detectAuthFailureInLine = (h, line) => scanLine(line.trim(), h.authMatchers);
-export const detectAuthFailure = (h, output) => scanTail(output, h.authMatchers);
+export const detectLimit = (h, output) => scanTail(output, compileLimitMatchers(h.limitMatchers));
+export const detectAuthFailureInLine = (h, line) => scanLine(line.trim(), compileAuthMatchers(h.authMatchers));
+export const detectAuthFailure = (h, output) => scanTail(output, compileAuthMatchers(h.authMatchers));
 //# sourceMappingURL=limits.js.map

package/dist/interpretation/limits.js.map

@@ -1 +1 @@
-{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/interpretation/limits.ts"],"names":[],"mappings":"AAcA;;oEAEoE;AACpE,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,MAAM,QAAQ,GAAG,CACf,IAAY,EACZ,QAAgD,EACnC,EAAE;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,QAAQ,GAAG,CACf,MAAc,EACd,QAAgD,EACnC,EAAE;IACf,IAAI,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC;IACxB,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,GAAG,GAAG,CAAC,IAAI,OAAO,GAAG,oBAAoB,EAAE,CAAC;QACjD,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACjD,GAAG,GAAG,KAAK,CAAC;QACZ,IAAI,IAAI,KAAK,EAAE;YAAE,SAAS;QAC1B,OAAO,EAAE,CAAC;QACV,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;IACjC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAoB,EAAE,IAAY,EAAoB,EAAE,CACxF,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC;AAEzC,mEAAmE;AACnE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAoB,EAAE,MAAc,EAAoB,EAAE,CACpF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC;AAEpC,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,CAAoB,EACpB,IAAY,EACY,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC;AAEnE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAoB,EAAE,MAAc,EAA0B,EAAE,CAChG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,CAAC"}
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/interpretation/limits.ts"],"names":[],"mappings":"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"}

package/dist/interpretation/refusal.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structured argv refusals: closed issue vocabulary and the typed error
+ * that carries harness, option, facet, and supported alternatives. The
+ * helper builds the message from those fields so the two cannot drift - a
+ * consumer branching on `issue` never has to parse English.
+ */
+import type { DiscoveryFacet, HarnessName, TurnOptionKey } from "../knowledge/descriptor.js";
+export declare const REFUSAL_ISSUES: readonly ["unsupported-option", "unsupported-option-facet", "unsupported-on-resume", "invalid-option-value", "unknown-effort", "unknown-model", "invalid-env", "invalid-tool-grant", "prompt-flag-injection", "no-autonomy-mode", "no-session-mode"];
+export type RefusalIssue = (typeof REFUSAL_ISSUES)[number];
+/** One helper builds the message from the structured fields so message and
+ * fields cannot drift. Every message names an alternative, not only a
+ * negation, so an agent can pivot without reading the descriptor. */
+export declare const buildRefusalMessage: (issue: RefusalIssue, harness: HarnessName, option?: TurnOptionKey, facet?: DiscoveryFacet, supported?: readonly string[], detail?: string) => string;
+/** Raised when launch options would corrupt or subvert the spawned argv. */
+export declare class ArgvRefusalError extends Error {
+    readonly issue: RefusalIssue;
+    readonly harness: HarnessName;
+    readonly option?: TurnOptionKey;
+    readonly facet?: DiscoveryFacet;
+    readonly supported: readonly string[];
+    constructor(args: {
+        readonly issue: RefusalIssue;
+        readonly harness: HarnessName;
+        readonly option?: TurnOptionKey;
+        readonly facet?: DiscoveryFacet;
+        readonly supported?: readonly string[];
+        readonly detail?: string;
+        readonly message?: string;
+    });
+}
+//# sourceMappingURL=refusal.d.ts.map

package/dist/interpretation/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/interpretation/refusal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAG7F,eAAO,MAAM,cAAc,sPAYhB,CAAC;AACZ,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;qEAEqE;AACrE,eAAO,MAAM,mBAAmB,UACvB,YAAY,WACV,WAAW,WACX,aAAa,UACd,cAAc,cACX,SAAS,MAAM,EAAE,WACnB,MAAM,KACd,MA4CF,CAAC;AAEF,4EAA4E;AAC5E,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,YAAY,IAAI,EAAE;QAChB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;QAC7B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;QAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;QAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;QAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;KAC3B,EAkBA;CACF"}

package/dist/interpretation/refusal.js

@@ -0,0 +1,87 @@
+/**
+ * Structured argv refusals: closed issue vocabulary and the typed error
+ * that carries harness, option, facet, and supported alternatives. The
+ * helper builds the message from those fields so the two cannot drift - a
+ * consumer branching on `issue` never has to parse English.
+ */
+import { deepFreeze } from "../knowledge/descriptor.js";
+export const REFUSAL_ISSUES = deepFreeze([
+    "unsupported-option",
+    "unsupported-option-facet",
+    "unsupported-on-resume",
+    "invalid-option-value",
+    "unknown-effort",
+    "unknown-model",
+    "invalid-env",
+    "invalid-tool-grant",
+    "prompt-flag-injection",
+    "no-autonomy-mode",
+    "no-session-mode",
+]);
+/** One helper builds the message from the structured fields so message and
+ * fields cannot drift. Every message names an alternative, not only a
+ * negation, so an agent can pivot without reading the descriptor. */
+export const buildRefusalMessage = (issue, harness, option, facet, supported = [], detail) => {
+    const supportedStr = supported.length > 0 ? `supported: ${supported.join(", ")}` : "supported: (none)";
+    const facetSuffix = facet ? ` facet ${JSON.stringify(facet)}` : "";
+    const optionPart = option
+        ? ` option ${JSON.stringify(option)}${facetSuffix}`
+        : facet
+            ? ` facet ${JSON.stringify(facet)}`
+            : "";
+    const detailSuffix = detail ? ` (${detail})` : "";
+    switch (issue) {
+        case "unsupported-option":
+            return `${harness} cannot express${optionPart}${detailSuffix}; ${supportedStr} - drop the option or route this work to a harness that supports it`;
+        case "unsupported-option-facet":
+            return `${harness} cannot express discovery${facetSuffix}${detailSuffix}; ${supportedStr} - drop the facet or route this work to a harness that supports it`;
+        case "unsupported-on-resume": {
+            const name = option
+                ? JSON.stringify(option) + (facet ? `:${facet}` : "")
+                : facet
+                    ? JSON.stringify(facet)
+                    : "option";
+            return `${name} cannot be expressed on resume for ${harness}${detailSuffix}; ${supportedStr} - re-launch instead of resuming or drop the option`;
+        }
+        case "invalid-option-value":
+            return `invalid value for${optionPart} on ${harness}${detailSuffix}; ${supportedStr} - use a supported value instead`;
+        case "unknown-effort":
+            return `unknown effort for ${harness}${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the ladder values`;
+        case "unknown-model":
+            return `unknown ${harness} model${detail ? ` ${JSON.stringify(detail)}` : ""}; ${supportedStr} - use one of the supported models`;
+        case "invalid-env":
+            return `invalid env key or value for ${harness}${detailSuffix}; ${supportedStr} - keys must match ^[A-Za-z_][A-Za-z0-9_]*$ and contain no NUL`;
+        case "invalid-tool-grant":
+            return `tool grant for ${harness} contains an empty entry or a comma; a blank tool flag value grants nothing detectable, and a comma inside one name silently splits the grant; ${supportedStr} - provide comma-free, non-empty tool names as separate entries`;
+        case "prompt-flag-injection":
+            return `positional prompt may not start with '-'; it would be parsed as a flag by ${harness}${detailSuffix}; ${supportedStr} - remove leading '-' or prefix with a space`;
+        case "no-autonomy-mode":
+            return `${harness} has no unattended-run flag; ${supportedStr} - drop autonomy or route to a supporting harness (claude --dangerously-skip-permissions, codex/muse --yolo)`;
+        case "no-session-mode":
+            return `${harness} declares no persistent headless session mode; ${supportedStr} - use streamTurn instead of openSession`;
+        default: {
+            const exhaustive = issue;
+            return `${exhaustive} for ${harness}${optionPart}${detailSuffix}; ${supportedStr}`;
+        }
+    }
+};
+/** Raised when launch options would corrupt or subvert the spawned argv. */
+export class ArgvRefusalError extends Error {
+    issue;
+    harness;
+    option;
+    facet;
+    supported;
+    constructor(args) {
+        const message = args.message ??
+            buildRefusalMessage(args.issue, args.harness, args.option, args.facet, args.supported ?? [], args.detail);
+        super(message);
+        this.name = "ArgvRefusalError";
+        this.issue = args.issue;
+        this.harness = args.harness;
+        this.option = args.option;
+        this.facet = args.facet;
+        this.supported = args.supported ?? [];
+    }
+}
+//# sourceMappingURL=refusal.js.map

package/dist/interpretation/refusal.js.map

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

package/dist/interpretation/turn-options.d.ts

@@ -0,0 +1,18 @@
+/**
+ * turn-options: rendering and validation of per-call turn options into argv.
+ *
+ * This lives separately from argv.ts because argv.ts owns argv *assembly and
+ * ordering* (where the prompt goes, that tools is last, that resume never
+ * inherits launch flags). Turn-option *rendering and validation* - which
+ * flag spells a dimension, how its value is validated and quoted, and when
+ * it must refuse - is a distinct responsibility with its own vocabulary.
+ * Folding it into argv.ts would make the largest interpretation file the
+ * place two unrelated questions are answered.
+ */
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import type { TurnOptions } from "./argv.js";
+/** Render turn options for a given phase, in TURN_OPTION_KEYS order and with
+ * discovery facets in DISCOVERY_FACETS order, de-duplicating by exact token
+ * sequence (first wins) so claude's two facets sharing one flag emit once. */
+export declare const renderTurnOptions: (h: HarnessDescriptor, opts: TurnOptions, phase: "launch" | "resume") => string[];
+//# sourceMappingURL=turn-options.d.ts.map

package/dist/interpretation/turn-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-options.d.ts","sourceRoot":"","sources":["../../src/interpretation/turn-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAA0B,MAAM,4BAA4B,CAAC;AAE5F,OAAO,KAAK,EAAoB,WAAW,EAAE,MAAM,WAAW,CAAC;AAY/D;;8EAE8E;AAC9E,eAAO,MAAM,iBAAiB,MACzB,iBAAiB,QACd,WAAW,SACV,QAAQ,GAAG,QAAQ,KACzB,MAAM,EAuYR,CAAC"}