@aquex/cmos-mcp 1.0.0

package/dist/tools/cmos/sender-identity.d.ts

@@ -0,0 +1,87 @@
+import type { DashboardClient } from './dashboard-client';
+/**
+ * Local sender identity — everything we know about *this* cwd's project, used to
+ * attribute outgoing messages. Both fields are resolved from the local DB in a
+ * single open; the async entrypoint also best-effort seeds `metadata.owner` and
+ * backfills the canonical cmos_address if they are missing.
+ */
+export interface LocalSenderIdentity {
+    /** Dashboard UUID for this local project, or null when never registered. */
+    projectId: string | null;
+    /** Canonical cmos://<owner>/<slug> address, or null when still empty/unknown. */
+    cmosAddress: string | null;
+}
+/**
+ * Read the local project's sender identity (dashboard UUID + cmos_address) from
+ * the CMOS database. Returns nulls — never bogus defaults — so the caller can
+ * fail closed rather than publishing a sibling project's identity.
+ *
+ * `cmosAddress` is null when the identity row holds an empty or `cmos://unknown/*`
+ * address; sending a bogus value is worse than omitting it (Sprint 52 m02, and
+ * the reason the Parts Town attribution bug is P0).
+ *
+ * Attempts a best-effort owner resolution + backfill first so that a fresh project
+ * with dashboard auth configured can emit a canonical address on its very first
+ * send.
+ */
+export declare function readLocalSenderIdentity(projectRoot?: string): Promise<LocalSenderIdentity>;
+/**
+ * Resolve the dashboard UUID to attribute an outbound message to.
+ *
+ * Resolution order (fail-closed):
+ *   1. `metadata.dashboard_project_id` — the canonical UUID written at
+ *      registration / first checkpoint. Authoritative: it is the dashboard's
+ *      own id for *this* cwd's project, so there is no ambiguity.
+ *   2. Match the local `project_identity.cmos_address` against
+ *      `/api/projects/me` by canonical address. Used when a project was
+ *      registered out-of-band and the metadata row is missing but the address
+ *      is already canonical.
+ *   3. Otherwise `undefined`. Callers pass it through as an omitted field; the
+ *      dashboard can then reject or apply its own (unrelated) fallback.
+ *
+ * NEVER pick `projects[0]` — the /api/projects/me response is "every project
+ * this user owns," and blindly taking the first one causes the Parts Town
+ * attribution corruption that Sprint 32's auto-detect shipped and Sprint 52
+ * failed to root-cause.
+ */
+export declare function resolveLocalSenderProjectId(client: DashboardClient, identity: LocalSenderIdentity): Promise<string | undefined>;
+/**
+ * Convenience wrapper: read the local identity and resolve the senderProjectId
+ * in a single call. Used by tools that don't need the cmosAddress separately.
+ */
+export declare function getLocalSenderProjectId(client: DashboardClient, projectRoot?: string): Promise<{
+    senderProjectId: string | undefined;
+    identity: LocalSenderIdentity;
+}>;
+/**
+ * Thrown when handleSend or any other authoritative-attribution call site cannot
+ * produce a complete sender identity (UUID + canonical cmos_address). Defense in
+ * depth on top of the dispatcher's `resolveSenderContext` gate — the resolver
+ * normally fail-closes before we ever reach this path, but keeping the assertion
+ * here prevents any caller that bypasses the boundary from silently publishing
+ * with a null sender.
+ *
+ * The thrown code `SENDER_ATTRIBUTION_INCOMPLETE` is distinct from the resolver's
+ * `SENDER_UNRESOLVABLE` so operators can tell which layer rejected the send.
+ */
+export declare class SenderAttributionIncompleteError extends Error {
+    readonly code = "SENDER_ATTRIBUTION_INCOMPLETE";
+    readonly identity: LocalSenderIdentity;
+    readonly senderProjectId: string | undefined;
+    constructor(identity: LocalSenderIdentity, senderProjectId: string | undefined);
+}
+/**
+ * Throw `SenderAttributionIncompleteError` when local identity is null — i.e.
+ * neither a resolved sender UUID nor a canonical cmos_address is available.
+ *
+ * Sprint 53 m02 decision: we fail-close only when there is *nothing* to
+ * attribute with. When either the UUID or the address is present, we forward
+ * what we have — the dashboard can cross-check (m04 adds echo-verification).
+ * This preserves existing pass-through semantics for edge cases where metadata
+ * is partially seeded, while still refusing to publish a completely-anonymous
+ * send. The full UUID+address authoritative attribution is enforced upstream
+ * by the dispatcher's `resolveSenderContext(requireSenderIdentity=true)` gate;
+ * this function is defense-in-depth for any caller that bypasses the boundary.
+ */
+export declare function assertSenderIdentityValid(identity: LocalSenderIdentity, senderProjectId: string | undefined): void;
+//# sourceMappingURL=sender-identity.d.ts.map

package/dist/tools/cmos/sender-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender-identity.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/sender-identity.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAK1D;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,iFAAiF;IACjF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAkED;;;;;;;;;;;;GAYG;AACH,wBAAsB,uBAAuB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgChG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,eAAe,EACvB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAIjF;AAED;;;;;;;;;;GAUG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,mCAAmC;IAChD,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEjC,QAAQ,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS;CAU/E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,EAC7B,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,IAAI,CAIN"}

package/dist/tools/cmos/sender-identity.js

@@ -0,0 +1,207 @@
+"use strict";
+// ABOUTME: Resolve the local project's sender identity (dashboard UUID + cmos_address)
+// ABOUTME: for outbound cross-project messaging. Single source of truth for attribution.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SenderAttributionIncompleteError = void 0;
+exports.readLocalSenderIdentity = readLocalSenderIdentity;
+exports.resolveLocalSenderProjectId = resolveLocalSenderProjectId;
+exports.getLocalSenderProjectId = getLocalSenderProjectId;
+exports.assertSenderIdentityValid = assertSenderIdentityValid;
+/**
+ * Sender Identity Resolver
+ *
+ * Every path that calls DashboardClient.sendMessage must attribute the send to the
+ * *local* project — the cwd this process is running in. The original Sprint 32
+ * auto-detect blindly returned `/api/projects/me` projects[0], which caused every
+ * message from every project to be tagged with whichever project the dashboard
+ * happened to list first for the user (Parts Town, for derek — P0 bug reported
+ * 2026-04-16 after Sprint 52 failed to root-cause it).
+ *
+ * This module centralises the resolution so any new sender path gets the right
+ * answer automatically. Fail-closed: when we cannot authoritatively resolve the
+ * local project, return `undefined` — never a sibling project's id.
+ *
+ * @module tools/cmos/sender-identity
+ */
+const client_1 = require("./client");
+const errors_1 = require("./errors");
+const project_identity_1 = require("./project-identity");
+const owner_resolution_1 = require("./owner-resolution");
+/** UUID regex used to validate the local dashboard_project_id before trusting it. */
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Normalise a cmos:// address the same way cmos_message(send) does before POSTing,
+ * so that local-vs-directory comparison is case-insensitive + whitespace-tolerant.
+ */
+function normalizeAddress(address) {
+    if (!address.startsWith('cmos://'))
+        return address;
+    const body = address.slice('cmos://'.length);
+    const normalized = body.toLowerCase().replace(/\s+/g, '-').replace(/-{2,}/g, '-');
+    return `cmos://${normalized}`;
+}
+function normalizeSlug(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed.toLowerCase().replace(/\s+/g, '-') : null;
+}
+function extractSlugFromAddress(address) {
+    if (!address || !address.startsWith('cmos://')) {
+        return null;
+    }
+    const body = address.slice('cmos://'.length);
+    const [, slug] = body.split('/');
+    return normalizeSlug(slug ?? null);
+}
+function readMetadataValue(db, key) {
+    const result = db.getOne('SELECT value FROM metadata WHERE key = ?', [key]);
+    if (!result.success || !result.data?.value) {
+        return null;
+    }
+    const trimmed = result.data.value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function shouldAttemptIdentityRepair(projectId, cmosAddress, db) {
+    if (!projectId || !UUID_REGEX.test(projectId)) {
+        return true;
+    }
+    if (!cmosAddress) {
+        return true;
+    }
+    const currentSlug = extractSlugFromAddress(cmosAddress);
+    const trustedSlugs = new Set([readMetadataValue(db, 'project_id'), readMetadataValue(db, 'project_name')]
+        .map((value) => normalizeSlug(value))
+        .filter((value) => value !== null));
+    if (trustedSlugs.size === 0) {
+        return false;
+    }
+    return currentSlug === null || !trustedSlugs.has(currentSlug);
+}
+/**
+ * Read the local project's sender identity (dashboard UUID + cmos_address) from
+ * the CMOS database. Returns nulls — never bogus defaults — so the caller can
+ * fail closed rather than publishing a sibling project's identity.
+ *
+ * `cmosAddress` is null when the identity row holds an empty or `cmos://unknown/*`
+ * address; sending a bogus value is worse than omitting it (Sprint 52 m02, and
+ * the reason the Parts Town attribution bug is P0).
+ *
+ * Attempts a best-effort owner resolution + backfill first so that a fresh project
+ * with dashboard auth configured can emit a canonical address on its very first
+ * send.
+ */
+async function readLocalSenderIdentity(projectRoot) {
+    try {
+        const result = await (0, client_1.withClientAsync)(async (db) => {
+            const readIdentity = () => {
+                const rawProjectId = readMetadataValue(db, 'dashboard_project_id') ?? '';
+                const projectId = rawProjectId.length > 0 ? rawProjectId : null;
+                const identity = (0, project_identity_1.getProjectIdentity)(db);
+                const addr = identity?.cmos_address?.trim() ?? '';
+                const cmosAddress = !addr || addr.startsWith('cmos://unknown/') ? null : addr;
+                return { projectId, cmosAddress };
+            };
+            let localIdentity = readIdentity();
+            if (shouldAttemptIdentityRepair(localIdentity.projectId, localIdentity.cmosAddress, db)) {
+                try {
+                    await (0, owner_resolution_1.resolveAndPersistOwner)(db);
+                    (0, project_identity_1.backfillUnknownCmosAddress)(db);
+                    localIdentity = readIdentity();
+                }
+                catch {
+                    // best-effort — fall through to whatever the DB currently has
+                }
+            }
+            return (0, errors_1.createSuccess)(localIdentity);
+        }, { projectRoot });
+        return result.success && result.data ? result.data : { projectId: null, cmosAddress: null };
+    }
+    catch {
+        return { projectId: null, cmosAddress: null };
+    }
+}
+/**
+ * Resolve the dashboard UUID to attribute an outbound message to.
+ *
+ * Resolution order (fail-closed):
+ *   1. `metadata.dashboard_project_id` — the canonical UUID written at
+ *      registration / first checkpoint. Authoritative: it is the dashboard's
+ *      own id for *this* cwd's project, so there is no ambiguity.
+ *   2. Match the local `project_identity.cmos_address` against
+ *      `/api/projects/me` by canonical address. Used when a project was
+ *      registered out-of-band and the metadata row is missing but the address
+ *      is already canonical.
+ *   3. Otherwise `undefined`. Callers pass it through as an omitted field; the
+ *      dashboard can then reject or apply its own (unrelated) fallback.
+ *
+ * NEVER pick `projects[0]` — the /api/projects/me response is "every project
+ * this user owns," and blindly taking the first one causes the Parts Town
+ * attribution corruption that Sprint 32's auto-detect shipped and Sprint 52
+ * failed to root-cause.
+ */
+async function resolveLocalSenderProjectId(client, identity) {
+    if (identity.projectId && UUID_REGEX.test(identity.projectId)) {
+        return identity.projectId;
+    }
+    if (!identity.cmosAddress)
+        return undefined;
+    const result = await client.getMyProjects();
+    if (!result.success || !result.data?.projects?.length) {
+        return undefined;
+    }
+    const normalizedLocal = normalizeAddress(identity.cmosAddress);
+    const match = result.data.projects.find((p) => normalizeAddress(p.address) === normalizedLocal);
+    return match?.id;
+}
+/**
+ * Convenience wrapper: read the local identity and resolve the senderProjectId
+ * in a single call. Used by tools that don't need the cmosAddress separately.
+ */
+async function getLocalSenderProjectId(client, projectRoot) {
+    const identity = await readLocalSenderIdentity(projectRoot);
+    const senderProjectId = await resolveLocalSenderProjectId(client, identity);
+    return { senderProjectId, identity };
+}
+/**
+ * Thrown when handleSend or any other authoritative-attribution call site cannot
+ * produce a complete sender identity (UUID + canonical cmos_address). Defense in
+ * depth on top of the dispatcher's `resolveSenderContext` gate — the resolver
+ * normally fail-closes before we ever reach this path, but keeping the assertion
+ * here prevents any caller that bypasses the boundary from silently publishing
+ * with a null sender.
+ *
+ * The thrown code `SENDER_ATTRIBUTION_INCOMPLETE` is distinct from the resolver's
+ * `SENDER_UNRESOLVABLE` so operators can tell which layer rejected the send.
+ */
+class SenderAttributionIncompleteError extends Error {
+    constructor(identity, senderProjectId) {
+        super(`Sender attribution incomplete: projectId=${identity.projectId ?? 'null'} ` +
+            `cmosAddress=${identity.cmosAddress ?? 'null'} senderProjectId=${senderProjectId ?? 'null'}. ` +
+            'Refusing to send — attribution must be authoritatively resolved before dashboard publish.');
+        this.code = 'SENDER_ATTRIBUTION_INCOMPLETE';
+        this.name = 'SenderAttributionIncompleteError';
+        this.identity = identity;
+        this.senderProjectId = senderProjectId;
+    }
+}
+exports.SenderAttributionIncompleteError = SenderAttributionIncompleteError;
+/**
+ * Throw `SenderAttributionIncompleteError` when local identity is null — i.e.
+ * neither a resolved sender UUID nor a canonical cmos_address is available.
+ *
+ * Sprint 53 m02 decision: we fail-close only when there is *nothing* to
+ * attribute with. When either the UUID or the address is present, we forward
+ * what we have — the dashboard can cross-check (m04 adds echo-verification).
+ * This preserves existing pass-through semantics for edge cases where metadata
+ * is partially seeded, while still refusing to publish a completely-anonymous
+ * send. The full UUID+address authoritative attribution is enforced upstream
+ * by the dispatcher's `resolveSenderContext(requireSenderIdentity=true)` gate;
+ * this function is defense-in-depth for any caller that bypasses the boundary.
+ */
+function assertSenderIdentityValid(identity, senderProjectId) {
+    if (!senderProjectId && !identity.cmosAddress) {
+        throw new SenderAttributionIncompleteError(identity, senderProjectId);
+    }
+}
+//# sourceMappingURL=sender-identity.js.map

package/dist/tools/cmos/sender-identity.js.map

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

package/dist/tools/cmos/staleness-detection.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Staleness Detection
+ *
+ * Detects and flags decisions/learnings that are older than N sprints
+ * and haven't been referenced. Surfaces stale counts for agent awareness.
+ *
+ * Staleness is sprint-based: items linked to sprints older than the threshold
+ * (default 20) relative to the current sprint are candidates. Items that are
+ * referenced (via supersession chains or evidence links) are exempt.
+ *
+ * @module tools/cmos/staleness-detection
+ */
+import type { CmosDatabaseClient } from './client';
+/**
+ * Default staleness threshold in sprints.
+ *
+ * Sprint 61 m02 — raised from 10 → 20. Halves trigger frequency without losing
+ * the abandonment signal: a learning that hasn't been touched OR cited across
+ * 20 sprints is genuinely stale, not just dormant. The original 10-sprint
+ * threshold was tripping the same institutional rules every sprint and
+ * compounding the staleness pile faster than it could be triaged.
+ *
+ * Override at runtime via `CMOS_STALENESS_THRESHOLD_SPRINTS`. Tests should
+ * import this constant rather than hard-coding 20 so future bumps don't
+ * require test churn.
+ */
+export declare const DEFAULT_STALENESS_THRESHOLD = 20;
+/**
+ * Result of staleness detection.
+ */
+export interface StalenessResult {
+    /** Number of decisions flagged as stale in this run */
+    decisionsFlagged: number;
+    /** Number of learnings flagged as stale in this run */
+    learningsFlagged: number;
+    /** Total stale decisions (including previously flagged) */
+    totalStaleDecisions: number;
+    /** Total stale learnings (including previously flagged) */
+    totalStaleLearnings: number;
+    /** The sprint threshold used */
+    threshold: number;
+    /** Current sprint number used for comparison */
+    currentSprintNumber: number | null;
+    /** Cutoff sprint number (items at or below this are stale candidates) */
+    cutoffSprintNumber: number | null;
+}
+/**
+ * Detect and flag stale decisions and learnings.
+ *
+ * Idempotent: re-running produces the same result. Items already flagged as
+ * 'stale' are not re-flagged. Items with status other than 'active' are skipped.
+ *
+ * Referenced items are exempt:
+ * - Decisions that are the target of another decision's superseded_by
+ * - Decisions with non-null evidence links
+ *
+ * @param client - Database client
+ * @param options - Optional threshold override
+ * @returns Staleness detection result with counts
+ */
+export declare function detectAndFlagStaleness(client: CmosDatabaseClient, options?: {
+    threshold?: number;
+}): StalenessResult;
+/**
+ * Get stale counts without flagging (read-only).
+ * Useful when you want to report counts without mutating.
+ *
+ * Sprint 61 m03: ensures the learnings.evergreen column exists before reading
+ * (the count filters on `evergreen = 0` to exclude institutional rules).
+ */
+export declare function getStaleCounts(client: CmosDatabaseClient): {
+    staleDecisions: number;
+    staleLearnings: number;
+};
+/**
+ * Per-decision staleness detail with scoring and suggested action.
+ */
+export interface StaleDecisionDetail {
+    /** Decision ID */
+    id: number;
+    /** Decision text (truncated to 200 chars) */
+    text: string;
+    /** Current status */
+    status: string;
+    /** Sprint ID the decision belongs to */
+    sprintId: string | null;
+    /** Sprint age: how many sprints ago this decision was made */
+    sprintAge: number;
+    /** Staleness score: 0 (fresh) to 1.0 (very stale) */
+    stalenessScore: number;
+    /** Category of the decision */
+    category: string | null;
+    /** Whether this decision has evidence references */
+    hasEvidence: boolean;
+    /** Whether this decision is referenced by a supersession chain */
+    isReferenced: boolean;
+    /** Suggested lifecycle action */
+    suggestedAction: 'archive' | 'review' | 'confirm';
+    /** Reason for the suggestion */
+    suggestedReason: string;
+}
+/**
+ * Result of a decision lifecycle review.
+ */
+export interface DecisionReviewResult {
+    /** Decisions needing attention (stale or approaching staleness) */
+    decisions: StaleDecisionDetail[];
+    /** Total active decisions */
+    totalActive: number;
+    /** Total stale decisions */
+    totalStale: number;
+    /** Current sprint number */
+    currentSprintNumber: number | null;
+    /** Staleness threshold in sprints */
+    threshold: number;
+}
+/**
+ * Get detailed staleness review for all decisions needing attention.
+ * Returns per-decision scoring and suggested actions.
+ *
+ * Unlike detectAndFlagStaleness, this does NOT mutate the database.
+ * It provides a read-only view for agents to triage.
+ */
+export declare function reviewDecisionStaleness(client: CmosDatabaseClient, options?: {
+    threshold?: number;
+    includeApproaching?: boolean;
+}): DecisionReviewResult;
+//# sourceMappingURL=staleness-detection.d.ts.map

package/dist/tools/cmos/staleness-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness-detection.d.ts","sourceRoot":"","sources":["../../../src/tools/cmos/staleness-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IAEzB,2DAA2D;IAC3D,mBAAmB,EAAE,MAAM,CAAC;IAE5B,2DAA2D;IAC3D,mBAAmB,EAAE,MAAM,CAAC;IAE5B,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAElB,gDAAgD;IAChD,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC,yEAAyE;IACzE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/B,eAAe,CAsEjB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG;IAC1D,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB,CAMA;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kBAAkB;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,YAAY,EAAE,OAAO,CAAC;IACtB,iCAAiC;IACjC,eAAe,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAClD,gCAAgC;IAChC,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,SAAS,EAAE,mBAAmB,EAAE,CAAC;IACjC,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7D,oBAAoB,CA8FtB"}