@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.9000

package/dist/lib/captureVersion.js

@@ -0,0 +1,81 @@
+import { kernelCallWithSession } from './client.js';
+import { CLIError, ErrorCode } from './errors.js';
+import { buildVersionPatch, readVersionWriteOutcome } from './versionWrite.js';
+import { highestVerdictScore } from './captureGrounding.js';
+/** The TARGET entry's collection prose key — never the CAPTURE's chosen collection (decide()
+ *  matches across every collection, so the target can be in a different one). chain.updateEntry
+ *  merges `data` verbatim; it does not remap a write onto the target's real field the way
+ *  createEntry's own TEN-1258 remap does for a brand-new entry — this resolution is the only
+ *  thing standing between a captured prose body and the wrong field. Fail-open to 'description'
+ *  only when the fetch itself fails, same posture as capture.ts's own WHY-contract fetch. */
+async function resolveTargetProseKey(collectionSlug) {
+    try {
+        const contract = await kernelCallWithSession('chain.getCollectionFields', { slug: collectionSlug });
+        return contract?.descriptionFieldKey ?? 'description';
+    }
+    catch {
+        return 'description';
+    }
+}
+/** TASK-381: a capture that becomes a new version of an accepted entry carries its own text as the
+ *  Change reason (what the capturer wrote is why the entry changes). Empty text and no fields means
+ *  there is no change to justify, so nothing is sent. */
+function captureChangeReason(prose, fields) {
+    const text = prose.trim() || Object.keys(fields ?? {}).map((k) => `${k} set`).join(', ');
+    return text ? { changeReason: `Captured: ${text.slice(0, 300)}` } : {};
+}
+function refusalGuidance(refusal) {
+    return refusal.requiredAction ?? 'Route this change to the accountable role, or run `pb get <id>` to see the entry\'s current state.';
+}
+/**
+ * Runs the version-verdict write. Throws a CLIError on refusal (delegation / organisational-
+ * authority — returned, not thrown, by the door itself; requirePermission's ownership gate
+ * throws directly) or NOT_FOUND (an unresolvable target, e.g. deleted/cross-workspace — fails
+ * closed, no fallback create; a re-run re-decides against the current candidate pool). No
+ * proposal is created on refusal — the relation-consent proposal system this comment used to
+ * name (propose_change) is deleted outright (WP-776 S2a, DEC-1771), not merely absent here.
+ */
+export async function runVersionCapture(params) {
+    const { groundingResult, name, prose, fields, sourceRef, sourceExcerpt, sessionId, skipGrounding, groundingStart, groundingElapsed } = params;
+    const targetProseKey = await resolveTargetProseKey(groundingResult.collectionSlug);
+    const patch = buildVersionPatch({ capture: { name, prose, fields }, targetProseKey });
+    const rawResult = await kernelCallWithSession('chain.updateEntry', {
+        entryId: groundingResult.entryId,
+        ...patch,
+        autoPublish: true,
+        changeNote: 'Captured as a new version via CLI',
+        ...captureChangeReason(prose, fields),
+        changedBy: `agent:${sessionId}`,
+        ...(sourceRef ? { sourceRef } : {}),
+        ...(sourceExcerpt ? { sourceExcerpt } : {}),
+    });
+    // WP-319 S3 / STD-155: same observability this verdict would have fed via the create path's
+    // own recordGroundingOutcome call — fires regardless of write outcome, matching that call's
+    // own best-effort, never-blocks posture.
+    if (!skipGrounding && groundingStart > 0) {
+        void kernelCallWithSession('chain.recordGroundingOutcome', {
+            surface: 'cli',
+            promptShown: false,
+            highestRatio: highestVerdictScore(groundingResult),
+            hadGovernance: false,
+            grounding_ms: groundingElapsed,
+        }, { retryOnRateLimit: false }).catch(() => undefined);
+    }
+    const outcome = readVersionWriteOutcome(rawResult);
+    if (!outcome.ok) {
+        const authorityRefusal = outcome.refusal.category === 'auth';
+        throw new CLIError(outcome.refusal.reason ?? `Version write on ${groundingResult.entryId} was refused.`, {
+            code: authorityRefusal ? ErrorCode.AUTH_DENIED : ErrorCode.VALIDATION_FAILED,
+            category: authorityRefusal ? 'auth' : 'validation',
+            guidance: refusalGuidance(outcome.refusal),
+        });
+    }
+    const typed = rawResult;
+    return {
+        entryId: groundingResult.entryId,
+        name: groundingResult.name,
+        warnings: typed.warnings ?? [],
+        normalization: typed.normalization,
+    };
+}
+//# sourceMappingURL=captureVersion.js.map

package/dist/lib/captureVersion.js.map

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

package/dist/lib/checklist.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The quality checklist — one renderer for every surface (TASK-590, DEC-1910, DEC-1913).
+ *
+ * A blocked or pending accept shows every criterion of the entry's rubric as one short
+ * instruction with one of three states: met, not yet, or still judging (the AI verdict has
+ * not landed). The line is the repair; an unmet line adds what the AI judge named as missing.
+ * The judge's free-text explanation is never shown, so it can never contradict a tick.
+ *
+ * Lines exist only for the gated spine rubrics, purpose, vision, strategy, objective and key
+ * result (DEC-1913, DEC-1935), and for the strategy-link gate's rungs (TASK-609:
+ * kernel/strategy/spineRefusal.ts marks each rung above a work package, key result or objective
+ * met or not yet); for any other key `renderChecklist` returns null. No Chain ids in any line:
+ * these strings reach users. The AI judge decides every spine line, so no line names a word count.
+ *
+ * Dependency-free on purpose: scripts/generate-mcp-embedded-copies.mjs ships this exact
+ * source to the CLI and the MCP server, and the accept gate (convex/lib/gates/evaluate.ts)
+ * calls it for the Rail, so every surface prints the same lines.
+ */
+/** One instruction per criterion id, per gated rubric. A kernel test pins it to the rubrics. */
+export declare const CHECKLIST_LINES: Readonly<Record<string, Readonly<Record<string, string>>>>;
+export interface ChecklistCriterion {
+    id: string;
+    passed: boolean;
+    /** What the AI judge named as concretely absent, on a fail. */
+    missing?: string;
+}
+/**
+ * The checklist lines for an entry's verdict, or null when its type has no checklist.
+ * `judging` is true while the AI verdict has not settled.
+ */
+export declare function renderChecklist(canonicalKey: string, criteria: readonly ChecklistCriterion[], judging: boolean): string[] | null;
+//# sourceMappingURL=checklist.d.ts.map

package/dist/lib/checklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist.d.ts","sourceRoot":"","sources":["../../src/lib/checklist.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,gGAAgG;AAChG,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAmCtF,CAAC;AAEF,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAC9B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,SAAS,kBAAkB,EAAE,EACvC,OAAO,EAAE,OAAO,GACd,MAAM,EAAE,GAAG,IAAI,CAWjB"}

package/dist/lib/checklist.js

@@ -0,0 +1,77 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/quality/checklist.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/**
+ * The quality checklist — one renderer for every surface (TASK-590, DEC-1910, DEC-1913).
+ *
+ * A blocked or pending accept shows every criterion of the entry's rubric as one short
+ * instruction with one of three states: met, not yet, or still judging (the AI verdict has
+ * not landed). The line is the repair; an unmet line adds what the AI judge named as missing.
+ * The judge's free-text explanation is never shown, so it can never contradict a tick.
+ *
+ * Lines exist only for the gated spine rubrics, purpose, vision, strategy, objective and key
+ * result (DEC-1913, DEC-1935), and for the strategy-link gate's rungs (TASK-609:
+ * kernel/strategy/spineRefusal.ts marks each rung above a work package, key result or objective
+ * met or not yet); for any other key `renderChecklist` returns null. No Chain ids in any line:
+ * these strings reach users. The AI judge decides every spine line, so no line names a word count.
+ *
+ * Dependency-free on purpose: scripts/generate-mcp-embedded-copies.mjs ships this exact
+ * source to the CLI and the MCP server, and the accept gate (convex/lib/gates/evaluate.ts)
+ * calls it for the Rail, so every surface prints the same lines.
+ */
+/** One instruction per criterion id, per gated rubric. A kernel test pins it to the rubrics. */
+export const CHECKLIST_LINES = {
+    purpose: {
+        stranger_test: 'Explain it so a stranger knows why this company exists',
+        specificity: 'Say what would be missing from the world without this company',
+        not_a_platitude: 'Say something a reasonable company would not also claim',
+        beneficiary_named: 'Name who the company exists for: a role, a persona or a segment',
+        durable_not_dated: 'Leave out dates and planning cycles; those belong on goals',
+    },
+    vision: {
+        specificity: 'Say what will be different, in words only this product could use',
+        beneficiary: 'Name who benefits: a role, a persona or a segment',
+        falsifiability: 'Choose a direction a reasonable rival would reject',
+        stranger_test: 'Explain it so a stranger knows what will be different, and for whom',
+    },
+    strategy: {
+        coherent_narrative: 'Connect the diagnosis, the policy and the first actions',
+        decisiveness: 'Say what you will not do',
+        time_bounded: 'Name a horizon: a date, a duration or a milestone',
+    },
+    objective: {
+        outcome_not_activity: 'State what will be true once it is met, not the work to do',
+        serves_strategy: 'Say what must be true for the strategy to succeed',
+        observable: 'Make it something a reader could see has happened',
+    },
+    key_result: {
+        measurable: 'Name a measure and the target value or state',
+        bounded: 'Say by when, or how often, the measure is read',
+        moves_the_objective: 'Pick a result that shows the objective is happening, not that work was done',
+    },
+    /** One line per spine rung, keyed by the rung it reaches (kernel/strategy/spineTrace.ts order). */
+    strategy_link: {
+        key_result: 'Link this work to an accepted key result it validates',
+        objective: 'Put the key result under an accepted objective',
+        strategy: 'Put the objective under an accepted strategy',
+    },
+};
+const MARK = { met: '[x]', not_yet: '[ ]', judging: '[~]' };
+/**
+ * The checklist lines for an entry's verdict, or null when its type has no checklist.
+ * `judging` is true while the AI verdict has not settled.
+ */
+export function renderChecklist(canonicalKey, criteria, judging) {
+    const lines = CHECKLIST_LINES[canonicalKey];
+    if (!lines)
+        return null;
+    return criteria
+        .filter((c) => lines[c.id] !== undefined)
+        .map((c) => {
+        const state = !c.passed ? 'not_yet' : judging ? 'judging' : 'met';
+        const still = state === 'judging' ? ' (still judging)' : '';
+        const missing = state === 'not_yet' && c.missing ? ` — missing: ${c.missing}` : '';
+        return `${MARK[state]} ${lines[c.id]}${still}${missing}`;
+    });
+}
+//# sourceMappingURL=checklist.js.map

package/dist/lib/checklist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checklist.js","sourceRoot":"","sources":["../../src/lib/checklist.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,gEAAgE;AAChE,uDAAuD;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AAEH,gGAAgG;AAChG,MAAM,CAAC,MAAM,eAAe,GAA+D;IAC1F,OAAO,EAAE;QACR,aAAa,EAAE,wDAAwD;QACvE,WAAW,EAAE,+DAA+D;QAC5E,eAAe,EAAE,yDAAyD;QAC1E,iBAAiB,EAAE,iEAAiE;QACpF,iBAAiB,EAAE,4DAA4D;KAC/E;IACD,MAAM,EAAE;QACP,WAAW,EAAE,kEAAkE;QAC/E,WAAW,EAAE,mDAAmD;QAChE,cAAc,EAAE,oDAAoD;QACpE,aAAa,EAAE,qEAAqE;KACpF;IACD,QAAQ,EAAE;QACT,kBAAkB,EAAE,yDAAyD;QAC7E,YAAY,EAAE,0BAA0B;QACxC,YAAY,EAAE,mDAAmD;KACjE;IACD,SAAS,EAAE;QACV,oBAAoB,EAAE,4DAA4D;QAClF,eAAe,EAAE,mDAAmD;QACpE,UAAU,EAAE,mDAAmD;KAC/D;IACD,UAAU,EAAE;QACX,UAAU,EAAE,8CAA8C;QAC1D,OAAO,EAAE,gDAAgD;QACzD,mBAAmB,EAAE,6EAA6E;KAClG;IACD,mGAAmG;IACnG,aAAa,EAAE;QACd,UAAU,EAAE,uDAAuD;QACnE,SAAS,EAAE,gDAAgD;QAC3D,QAAQ,EAAE,8CAA8C;KACxD;CACD,CAAC;AASF,MAAM,IAAI,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAW,CAAC;AAErE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC9B,YAAoB,EACpB,QAAuC,EACvC,OAAgB;IAEhB,MAAM,KAAK,GAAG,eAAe,CAAC,YAAY,CAAC,CAAC;IAC5C,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO,QAAQ;SACb,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,SAAS,CAAC;SACxC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACV,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;QAClE,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,MAAM,OAAO,GAAG,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnF,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,GAAG,OAAO,EAAE,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/lib/client.d.ts

@@ -1,24 +1,93 @@
 /**
  * MCP HTTP client — POST to Convex gateway with Bearer auth.
  *
- * TEN-729: Detects sandbox-blocked fetch (Claude Code, Cursor, etc.) and
- * provides an actionable error instead of the opaque "fetch failed".
+ * TEN-729: Detects sandbox-blocked fetch (Claude Code, Cursor, etc.) and provides an
+ * actionable error instead of the opaque "fetch failed".
  *
- * Sandbox proxy support: Node.js fetch (undici) ignores proxy env vars by
- * default. We detect HTTPS_PROXY and configure a ProxyAgent so pb works in
- * sandboxed environments (Claude Code, Cursor) without requiring
- * NODE_OPTIONS="--use-env-proxy".
+ * Sandbox proxy support: Node.js fetch (undici) ignores proxy env vars by default. We detect
+ * HTTPS_PROXY and configure a ProxyAgent so pb works in sandboxed environments (Claude Code,
+ * Cursor) without requiring NODE_OPTIONS="--use-env-proxy".
  */
-export declare function mcpCall<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;
+import type { ValidationErrorDetail } from './kernelEnvelope.js';
+import { CLIError } from './errors.js';
+import { type KernelCallOptions } from './rate-limit.js';
+export declare function isPerEntryAuthorizationRefusal(code?: string): boolean;
+/** Error thrown by kernelCall/kernelCallWithSession when the server returns a non-OK response. */
+export declare class McpError extends CLIError {
+    details?: ValidationErrorDetail[];
+    /** Present only when code === 'rate-limited' — seconds until the caller may retry. */
+    retryAfterSeconds?: number;
+    constructor(message: string, code?: string, details?: ValidationErrorDetail[], retryAfterSeconds?: number);
+}
+export { resetTouchThrottle, type KernelCallOptions } from './rate-limit.js';
+export type { KernelEnvelope, ValidationErrorDetail } from './kernelEnvelope.js';
+/** Result of validateKey — used by `pb login` to verify a key before saving. */
+export type ValidateKeyResult = {
+    valid: true;
+    workspaceId: string;
+} | {
+    valid: false;
+    error: string;
+};
 /**
- * mcpCall variant that injects X-Agent-Session-Id header for write operations.
+ * Validate an API key against the server before saving it.
+ * Uses `resolveWorkspace` as a lightweight health check — if it returns data, the key works.
+ *
+ * Returns { valid: true, workspaceId } on success.
+ * Returns { valid: false, error } on auth failure (401) or other server error.
+ * Throws on network/timeout errors so the caller can distinguish "bad key" from "can't reach server".
+ *
+ * WP-575: `timeoutMs` now DEFAULTS to `resolveWorkspace`'s declared budget instead of a
+ * local `5000` literal — that literal was the last connector-owned timeout on the gateway
+ * path, and the point of this work package is that no connector gets to pick its own. It
+ * stays an explicit parameter so a caller (or a test) can still override deliberately.
+ * Widening 5s -> the declared 10s costs nothing in the case people actually hit: an
+ * unreachable host fails with ECONNREFUSED/ENOTFOUND immediately, not by timeout. The
+ * timeout only governs a server that ACCEPTS the connection then stalls, where waiting the
+ * route's real declared budget before calling the key invalid is the correct behavior.
+ */
+export declare function validateKey(apiKey: string, siteUrl: string, timeoutMs?: number): Promise<ValidateKeyResult>;
+/** Get a human-friendly spinner label for an MCP function name. */
+export declare function spinnerLabel(fn: string): string;
+/**
+ * POST to the admin gateway (/api/admin) — separate from /api/aki (STD-101, BR-109).
+ * Admin operations are not knowledge operations — they target the operator surface.
+ *
+ * No built-in spinner: callers wrap with withSpinner when appropriate.
+ * Throws CLIError on auth failure or non-OK response.
+ */
+export declare function adminCall(command: string, args?: Record<string, unknown>): Promise<unknown>;
+export declare function kernelCall<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<T>;
+/**
+ * kernelCall variant that returns the full kernel envelope (data + summary + _meta) instead
+ * of stripping to just `data` — mirrors packages/mcp-server/src/client.ts's
+ * `kernelCallEnvelope`. Use when a caller needs `_meta` (e.g. a route-specific additive
+ * flag like chain.shapeAdvisories' `truncated`, WP-571 sweep) without changing `data`'s own
+ * shape — the reason `_meta` exists as a side-channel at all (convex/lib/envelopeContract.ts).
+ */
+export declare function kernelCallEnvelope<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<{
+    data: T;
+    summary?: string;
+    _meta?: {
+        durationMs?: number;
+        truncated?: boolean;
+    };
+}>;
+/**
+ * kernelCall variant for write operations. Callers that need server-side session
+ * validation (e.g. `chain.verifyEntry`) pass `sessionId` in `args` explicitly —
+ * it now travels in the request body, not a header (http.ts never read the old
+ * `X-Agent-Session-Id` header).
  * All write commands (update, relate, unrelate, capture) should use this.
  *
+ * WP-711/712: the binding guard lives in the shared fetchKernelEnvelope. TEN-3398 (follow-up)
+ * added the effective-tenant notice here too, alongside the post-write session-touch below.
+ *
  * After a successful write, fires a non-blocking `agent.touchSession` call to
  * renew the session TTL — mirroring MCP server behavior (DEC-299, BET-181 Slice 1).
  * The touch is fire-and-forget: it does not block the write response, and errors
  * are silently swallowed. No touch is attempted if no session is active or if
  * the write itself fails.
  */
-export declare function mcpCallWithSession<T = unknown>(fn: string, args?: Record<string, unknown>): Promise<T>;
+export declare function kernelCallWithSession<T = unknown>(fn: string, args?: Record<string, unknown>, options?: KernelCallOptions): Promise<T>;
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA0CH,wBAAsB,OAAO,CAAC,CAAC,GAAG,OAAO,EACvC,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAsBZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAClD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAoCZ"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,KAAK,EAAkB,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjF,OAAO,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAGlD,OAAO,EAAkC,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAoBzF,wBAAgB,8BAA8B,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAErE;AAkCD,kGAAkG;AAClG,qBAAa,QAAS,SAAQ,QAAQ;IACpC,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClC,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAEf,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,EAAE,EAAE,iBAAiB,CAAC,EAAE,MAAM;CAc1G;AAGD,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAK7E,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAoDjF,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,SAAS,SAA8C,GACtD,OAAO,CAAC,iBAAiB,CAAC,CAqC5B;AA6BD,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,OAAO,CAAC,CAoClB;AAqFD,wBAAsB,UAAU,CAAC,CAAC,GAAG,OAAO,EAC1C,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAIZ;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAClD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;IAAE,IAAI,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAAC,CAI9F;AA+BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EACrD,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,CAAC,CAAC,CA8BZ"}