@opensip-cli/mcp 0.1.15

package/dist/freshness.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Catalog freshness mapping (ADR-0084).
+ *
+ * Reuses the graph engine's `classifyCatalog` verdict (never a filesystem mtime
+ * heuristic outside the engine) and maps the `CatalogVerdict` to the agent-facing
+ * {@link Freshness} DTO. Building the `ValidationContext` from the working tree
+ * (current file set + adapter cache key) is the server's wiring concern (Phase 3),
+ * supplied to the SQLite port as an injected provider — this module is the pure
+ * verdict→DTO mapping.
+ *
+ * Missing catalog ⇒ `{ fresh: false, reason: 'missing' }` (no auto-build). A
+ * loaded catalog whose freshness cannot be verified (no context provider wired)
+ * is reported `fresh: true` with its `builtAt` — matching `opensip graph lookup`,
+ * which serves the persisted catalog without re-verification.
+ */
+import type { Freshness } from './symbol-dto.js';
+import type { Catalog } from '@opensip-cli/graph';
+import type { CatalogVerdict, ValidationContext } from '@opensip-cli/graph/internal';
+/** Freshness for an absent catalog — empty data, explicit refresh required. */
+export declare function missingFreshness(): Freshness;
+/** Freshness for a loaded catalog whose staleness was not verified (no context). */
+export declare function unverifiedFreshness(builtAt: string): Freshness;
+/** Map a {@link CatalogVerdict} (+ the served catalog's `builtAt`) to {@link Freshness}. */
+export declare function freshnessFromVerdict(verdict: CatalogVerdict, builtAt: string): Freshness;
+/** Classify a loaded catalog against the current working-tree context. */
+export declare function classifyFreshness(catalog: Catalog, ctx: ValidationContext): Freshness;
+/**
+ * Build the working-tree {@link ValidationContext} a real staleness check needs,
+ * derived from the catalog's OWN recorded inputs (Task 4.4).
+ *
+ * A fully-correct context (the one `runGraph`/the cache path builds) requires
+ * re-running discovery + the adapter `cacheKey` over the live tree. We implement
+ * the closest correct subset that needs no engine re-entry: the catalog persists
+ * its `filesFingerprint` (`<count>\n<path>|<mtime>|<size>` per file), so we
+ * recover the EXACT tracked file set (in the recorded order) and echo the
+ * catalog's own `language`/`cacheKey`. `classifyCatalog` then re-stats those
+ * files and recomputes the fingerprint — so any **mutated or deleted tracked
+ * file** flips the verdict to stale (`fresh === false`), which is what Phase 7
+ * asserts.
+ *
+ * Documented approximation: a brand-new source file (absent from the recorded
+ * set) is NOT detected as a staleness trigger without re-running discovery; and
+ * a language/tsconfig change is not detected (we echo the cached key rather than
+ * recomputing it). Those are catalog-additive changes the explicit `refresh_graph`
+ * op resolves. Mutations/deletions of tracked files — the common drift — ARE
+ * detected. Returns `undefined` when the catalog carries no fingerprint (older
+ * builds), leaving the port on its unverified-fresh fallback.
+ */
+export declare function workingTreeContextFromCatalog(catalog: Catalog): ValidationContext | undefined;
+//# sourceMappingURL=freshness.d.ts.map

package/dist/freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../src/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAErF,+EAA+E;AAC/E,wBAAgB,gBAAgB,IAAI,SAAS,CAE5C;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAE9D;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,CAgBxF;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAErF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,SAAS,CAU7F"}

package/dist/freshness.js

@@ -0,0 +1,96 @@
+/**
+ * Catalog freshness mapping (ADR-0084).
+ *
+ * Reuses the graph engine's `classifyCatalog` verdict (never a filesystem mtime
+ * heuristic outside the engine) and maps the `CatalogVerdict` to the agent-facing
+ * {@link Freshness} DTO. Building the `ValidationContext` from the working tree
+ * (current file set + adapter cache key) is the server's wiring concern (Phase 3),
+ * supplied to the SQLite port as an injected provider — this module is the pure
+ * verdict→DTO mapping.
+ *
+ * Missing catalog ⇒ `{ fresh: false, reason: 'missing' }` (no auto-build). A
+ * loaded catalog whose freshness cannot be verified (no context provider wired)
+ * is reported `fresh: true` with its `builtAt` — matching `opensip graph lookup`,
+ * which serves the persisted catalog without re-verification.
+ */
+import { classifyCatalog } from '@opensip-cli/graph/internal';
+/** Freshness for an absent catalog — empty data, explicit refresh required. */
+export function missingFreshness() {
+    return { fresh: false, reason: 'missing' };
+}
+/** Freshness for a loaded catalog whose staleness was not verified (no context). */
+export function unverifiedFreshness(builtAt) {
+    return { fresh: true, builtAt };
+}
+/** Map a {@link CatalogVerdict} (+ the served catalog's `builtAt`) to {@link Freshness}. */
+export function freshnessFromVerdict(verdict, builtAt) {
+    switch (verdict.kind) {
+        case 'valid': {
+            return { fresh: true, builtAt };
+        }
+        case 'incremental': {
+            return {
+                fresh: false,
+                builtAt,
+                reason: `stale: ${String(verdict.changedFiles.length)} file(s) changed since build`,
+            };
+        }
+        case 'invalid': {
+            return { fresh: false, builtAt, reason: `stale: ${verdict.reason}` };
+        }
+    }
+}
+/** Classify a loaded catalog against the current working-tree context. */
+export function classifyFreshness(catalog, ctx) {
+    return freshnessFromVerdict(classifyCatalog(catalog, ctx), catalog.builtAt);
+}
+/**
+ * Build the working-tree {@link ValidationContext} a real staleness check needs,
+ * derived from the catalog's OWN recorded inputs (Task 4.4).
+ *
+ * A fully-correct context (the one `runGraph`/the cache path builds) requires
+ * re-running discovery + the adapter `cacheKey` over the live tree. We implement
+ * the closest correct subset that needs no engine re-entry: the catalog persists
+ * its `filesFingerprint` (`<count>\n<path>|<mtime>|<size>` per file), so we
+ * recover the EXACT tracked file set (in the recorded order) and echo the
+ * catalog's own `language`/`cacheKey`. `classifyCatalog` then re-stats those
+ * files and recomputes the fingerprint — so any **mutated or deleted tracked
+ * file** flips the verdict to stale (`fresh === false`), which is what Phase 7
+ * asserts.
+ *
+ * Documented approximation: a brand-new source file (absent from the recorded
+ * set) is NOT detected as a staleness trigger without re-running discovery; and
+ * a language/tsconfig change is not detected (we echo the cached key rather than
+ * recomputing it). Those are catalog-additive changes the explicit `refresh_graph`
+ * op resolves. Mutations/deletions of tracked files — the common drift — ARE
+ * detected. Returns `undefined` when the catalog carries no fingerprint (older
+ * builds), leaving the port on its unverified-fresh fallback.
+ */
+export function workingTreeContextFromCatalog(catalog) {
+    const fingerprint = catalog.filesFingerprint;
+    if (typeof fingerprint !== 'string')
+        return undefined;
+    const currentFiles = filesFromFingerprint(fingerprint);
+    if (currentFiles.length === 0)
+        return undefined;
+    return {
+        currentLanguage: catalog.language,
+        currentCacheKey: catalog.cacheKey,
+        currentFiles,
+    };
+}
+/** Recover the tracked file paths (in order) from a `computeFilesFingerprint` string. */
+function filesFromFingerprint(fingerprint) {
+    const lines = fingerprint.split('\n');
+    const files = [];
+    // Line 0 is the leading file-count; each subsequent line is `path|mtime|size`.
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (typeof line !== 'string' || line.length === 0)
+            continue;
+        const pipe = line.indexOf('|');
+        files.push(pipe === -1 ? line : line.slice(0, pipe));
+    }
+    return files;
+}
+//# sourceMappingURL=freshness.js.map

package/dist/freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness.js","sourceRoot":"","sources":["../src/freshness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAM9D,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB;IAC9B,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC7C,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAAC,OAAuB,EAAE,OAAe;IAC3E,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACrB,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAClC,CAAC;QACD,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,OAAO;gBACP,MAAM,EAAE,UAAU,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,8BAA8B;aACpF,CAAC;QACJ,CAAC;QACD,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACvE,CAAC;IACH,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,iBAAiB,CAAC,OAAgB,EAAE,GAAsB;IACxE,OAAO,oBAAoB,CAAC,eAAe,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,6BAA6B,CAAC,OAAgB;IAC5D,MAAM,WAAW,GAAI,OAAyC,CAAC,gBAAgB,CAAC;IAChF,IAAI,OAAO,WAAW,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACtD,MAAM,YAAY,GAAG,oBAAoB,CAAC,WAAW,CAAC,CAAC;IACvD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAChD,OAAO;QACL,eAAe,EAAE,OAAO,CAAC,QAAQ;QACjC,eAAe,EAAE,OAAO,CAAC,QAAQ;QACjC,YAAY;KACb,CAAC;AACJ,CAAC;AAED,yFAAyF;AACzF,SAAS,oBAAoB,CAAC,WAAmB;IAC/C,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/graph-read-port.d.ts

@@ -0,0 +1,111 @@
+/**
+ * `GraphReadPort` — the narrow read interface every MCP graph tool handler
+ * depends on (ADR-0084). Handlers NEVER touch `CatalogRepo` / `Indexes`
+ * directly; they go through this port. Two named benefits justify the boundary:
+ *   1. **Test seam** — handlers are unit-tested against an in-memory fake port,
+ *      no SQLite needed (Phase 6).
+ *   2. **Compile-time SaaS parity** — a handler cannot reach the storage layer,
+ *      so an alternate (cloud) backend can substitute behind the same interface.
+ *
+ * Every read returns `Result<McpToolResult<T>, McpReadError>` (ADR-0084): the
+ * success arm carries `{ data, freshness }`; `throw` is reserved for the
+ * SQLite/Drizzle boundary inside the impl. A missing catalog is NOT an error —
+ * it surfaces as `freshness.fresh === false` with empty data and no auto-build.
+ */
+import type { McpReadError } from './mcp-error.js';
+import type { Freshness, McpToolResult, SymbolRef } from './symbol-dto.js';
+import type { Result } from '@opensip-cli/core';
+/** Identity of the in-memory catalog generation a read was served from. */
+export interface GraphGeneration {
+    /** ISO timestamp the served generation's catalog was built at. */
+    readonly builtAt: string;
+}
+/** A blast-radius score for one symbol (graph's canonical scoring — reused, not reinvented). */
+export interface BlastDto {
+    readonly symbol: SymbolRef;
+    /** Direct (depth-1) caller count. */
+    readonly direct: number;
+    /** Transitive (depth 2..5) caller count. */
+    readonly transitive: number;
+    /** `direct + 0.5 × transitive`. */
+    readonly score: number;
+}
+/** One dead-code (orphan) finding projected from `graph:orphan-subtree`. */
+export interface DeadCodeDto {
+    readonly symbol: SymbolRef;
+    /** The rule's human-readable message. */
+    readonly message: string;
+}
+/** The outcome of the `trace_path` tool: an ordered symbol chain. */
+export interface PathTraceDto {
+    /** `true` when a call path `from → … → to` exists within the depth bound. */
+    readonly found: boolean;
+    /** The ordered path (empty when not found). */
+    readonly path: readonly SymbolRef[];
+}
+/**
+ * A walkable adjacency snapshot for one call direction. The MCP call-graph tools
+ * (`who_calls`/`callees_of`/`trace_path`) run the shared `boundedBfs` over this
+ * — the port exposes the engine's `Indexes.callers`/`callees` body-hash
+ * adjacency (twin-union per ADR-0003) plus a body-hash → {@link SymbolRef}
+ * resolver, so the single walk lives in MCP (rule of three) and the port never
+ * re-implements a parallel BFS.
+ */
+export interface AdjacencySnapshot {
+    /** Body-hash → neighbor body-hashes for this direction. */
+    readonly edges: ReadonlyMap<string, readonly string[]>;
+    /** Resolve a body hash to its representative {@link SymbolRef} (metadata only). */
+    resolve(bodyHash: string): SymbolRef | undefined;
+}
+/** One package-coupling row in the architecture summary. */
+export interface ArchitecturePackageDto {
+    readonly name: string;
+    /** Distinct callee packages this package depends on. */
+    readonly couplingOut: number;
+    /** Distinct caller packages that depend on this one. */
+    readonly couplingIn: number;
+}
+/** A compact architecture overview: counts, languages, top-coupled packages, blast hotspots. */
+export interface ArchitectureSummaryDto {
+    readonly functionCount: number;
+    readonly edgeCount: number;
+    /** Languages present in the catalog (single-language per catalog today). */
+    readonly languages: readonly string[];
+    readonly packages: readonly ArchitecturePackageDto[];
+    /** Highest-blast symbols (graph's canonical scoring), capped. */
+    readonly hotspots: readonly BlastDto[];
+}
+/** Options for {@link GraphReadPort.searchSymbols}. */
+export interface SearchSymbolsOptions {
+    /** Max results before truncation (handler-clamped; impl applies a default). */
+    readonly limit?: number;
+}
+export interface GraphReadPort {
+    /** Identity of the current generation (`undefined` when no catalog is loaded). */
+    getGeneration(): Result<McpToolResult<GraphGeneration | undefined>, McpReadError>;
+    /** Resolve a `file:line:col` symbolId to its {@link SymbolRef}. */
+    resolveSymbolId(symbolId: string): Result<McpToolResult<SymbolRef | undefined>, McpReadError>;
+    /** Search symbols by simple name (substring, case-insensitive). */
+    searchSymbols(query: string, opts?: SearchSymbolsOptions): Result<McpToolResult<readonly SymbolRef[]>, McpReadError>;
+    /** All symbols declared in `file` enclosing (or starting at) `line`. */
+    findBySpan(file: string, line: number): Result<McpToolResult<readonly SymbolRef[]>, McpReadError>;
+    /** Reverse-call adjacency snapshot (who-calls): walked by MCP's `boundedBfs`. */
+    callerGraph(): Result<McpToolResult<AdjacencySnapshot>, McpReadError>;
+    /** Forward-call adjacency snapshot (callees): walked by MCP's `boundedBfs`. */
+    calleeGraph(): Result<McpToolResult<AdjacencySnapshot>, McpReadError>;
+    /** Blast radius of `symbolId` — graph's canonical `buildFeatures` scoring. */
+    blast(symbolId: string): Result<McpToolResult<BlastDto | undefined>, McpReadError>;
+    /** Orphan (dead-code) symbols via `graph:orphan-subtree` (no filesystem reads). */
+    deadCode(limit?: number): Result<McpToolResult<readonly DeadCodeDto[]>, McpReadError>;
+    /** Package-coupling architecture overview. */
+    architectureSummary(limit?: number): Result<McpToolResult<ArchitectureSummaryDto>, McpReadError>;
+    /**
+     * Rebuild the catalog (the single state-changing op) and swap the generation
+     * atomically. Async — runs the graph programmatic build at a genuine infra
+     * boundary. Wired in Phase 4.
+     */
+    refresh(): Promise<Result<McpToolResult<GraphGeneration>, McpReadError>>;
+    /** The current freshness verdict (read without serving data). */
+    freshness(): Freshness;
+}
+//# sourceMappingURL=graph-read-port.d.ts.map

package/dist/graph-read-port.d.ts.map

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

package/dist/graph-read-port.js

@@ -0,0 +1,16 @@
+/**
+ * `GraphReadPort` — the narrow read interface every MCP graph tool handler
+ * depends on (ADR-0084). Handlers NEVER touch `CatalogRepo` / `Indexes`
+ * directly; they go through this port. Two named benefits justify the boundary:
+ *   1. **Test seam** — handlers are unit-tested against an in-memory fake port,
+ *      no SQLite needed (Phase 6).
+ *   2. **Compile-time SaaS parity** — a handler cannot reach the storage layer,
+ *      so an alternate (cloud) backend can substitute behind the same interface.
+ *
+ * Every read returns `Result<McpToolResult<T>, McpReadError>` (ADR-0084): the
+ * success arm carries `{ data, freshness }`; `throw` is reserved for the
+ * SQLite/Drizzle boundary inside the impl. A missing catalog is NOT an error —
+ * it surfaces as `freshness.fresh === false` with empty data and no auto-build.
+ */
+export {};
+//# sourceMappingURL=graph-read-port.js.map

package/dist/graph-read-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-read-port.js","sourceRoot":"","sources":["../src/graph-read-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @opensip-cli/mcp public barrel.
+ *
+ * Re-exports the Tool descriptor the host loads by name through the bundled
+ * plugin path. The MCP server internals (ports, command, tools) are not public
+ * API — they are consumed only within this package and its test suites.
+ */
+export { mcpTool, mcpTool as tool, MCP_IDENTITY, MCP_STABLE_ID } from './tool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @opensip-cli/mcp public barrel.
+ *
+ * Re-exports the Tool descriptor the host loads by name through the bundled
+ * plugin path. The MCP server internals (ports, command, tools) are not public
+ * API — they are consumed only within this package and its test suites.
+ */
+export { mcpTool, mcpTool as tool, MCP_IDENTITY, MCP_STABLE_ID } from './tool.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,IAAI,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/mcp-error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The structured error the MCP read ports return in the failure arm of their
+ * `Result<T, E>` (ADR-0084). Ports return `Result` across domain boundaries;
+ * `throw` is reserved for genuine infra failures (SQLite/Drizzle, the
+ * `runGraph` child build). This is a plain DTO — not a thrown `Error`.
+ */
+export interface McpReadError {
+    /** Machine-readable reason, e.g. `'ambiguous-symbol'`, `'not-found'`. */
+    readonly code: string;
+    /** Human-readable detail (already scrubbed/truncated where relevant). */
+    readonly message: string;
+}
+/** Build an {@link McpReadError}. */
+export declare function readError(code: string, message: string): McpReadError;
+//# sourceMappingURL=mcp-error.d.ts.map

package/dist/mcp-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-error.d.ts","sourceRoot":"","sources":["../src/mcp-error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAErE"}

package/dist/mcp-error.js

@@ -0,0 +1,5 @@
+/** Build an {@link McpReadError}. */
+export function readError(code, message) {
+    return { code, message };
+}
+//# sourceMappingURL=mcp-error.js.map

package/dist/mcp-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-error.js","sourceRoot":"","sources":["../src/mcp-error.ts"],"names":[],"mappings":"AAaA,qCAAqC;AACrC,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,OAAe;IACrD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/register-mcp-graph-adapters.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityRegistrar } from '@opensip-cli/core';
+export declare const registerMcpGraphAdapter: CapabilityRegistrar;
+//# sourceMappingURL=register-mcp-graph-adapters.d.ts.map

package/dist/register-mcp-graph-adapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-mcp-graph-adapters.d.ts","sourceRoot":"","sources":["../src/register-mcp-graph-adapters.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D,eAAO,MAAM,uBAAuB,EAAE,mBAErC,CAAC"}

package/dist/register-mcp-graph-adapters.js

@@ -0,0 +1,21 @@
+// @fitness-ignore-file hot-paths-require-spans -- Registration wiring, not a runtime hot path: this registrar runs once per adapter at scope build (it just routes the contribution into the scope-owned registry). It mirrors graph's own internal registerGraphAdapter; the graph engine owns the span boundary and traces adapter work centrally per pipeline stage.
+/**
+ * MCP's registrar for its `mcp-graph-adapter` capability domain (ADR-0084).
+ *
+ * Mirrors graph's `registerGraphAdapter` (graph `tool.ts`): a routed
+ * contribution (already shape-checked against the domain's `requiredKeys: ['id']`
+ * by the host) is registered into THIS run's scope-owned adapter registry.
+ *
+ * Why this works: graph's `contributeScope` runs for EVERY bundled tool (the host
+ * loops all contributing tools when building the RunScope), so `scope.graph.adapters`
+ * exists under `opensip mcp` even though the dispatched tool is `mcp`.
+ * `currentAdapterRegistry()` resolves that registry; MCP declares its OWN domain id
+ * (`mcp-graph-adapter`) with `markerKind: 'graph-adapter'`, so the host's
+ * bundled-pack lookup (keyed by markerKind) loads the same `graph-*` adapter packs
+ * under MCP's domain and routes each contribution through this registrar.
+ */
+import { currentAdapterRegistry } from '@opensip-cli/graph';
+export const registerMcpGraphAdapter = (contribution) => {
+    currentAdapterRegistry().register(contribution);
+};
+//# sourceMappingURL=register-mcp-graph-adapters.js.map

package/dist/register-mcp-graph-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-mcp-graph-adapters.js","sourceRoot":"","sources":["../src/register-mcp-graph-adapters.ts"],"names":[],"mappings":"AAAA,wWAAwW;AACxW;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,sBAAsB,EAA6B,MAAM,oBAAoB,CAAC;AAIvF,MAAM,CAAC,MAAM,uBAAuB,GAAwB,CAAC,YAAY,EAAE,EAAE;IAC3E,sBAAsB,EAAE,CAAC,QAAQ,CAAC,YAAoC,CAAC,CAAC;AAC1E,CAAC,CAAC"}

package/dist/result-dto.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Result/history DTOs for the MCP {@link ResultsReadPort} (ADR-0084).
+ *
+ * Every result response carries session provenance + `recommendedNext` commands
+ * so an agent can drill in (or re-run) without guessing the CLI grammar. The
+ * payloads are the host-owned generic replay projection (the same decoded signal
+ * list `sessions show` produces) — never another tool's opaque payload
+ * vocabulary (ADR-0042 opacity boundary holds).
+ */
+import type { SignalEnvelope } from '@opensip-cli/contracts';
+import type { SignalSeverity, ToolShortId } from '@opensip-cli/core';
+/** The verdict-count block shared with `SignalEnvelope`. */
+export type RunVerdictSummary = SignalEnvelope['verdict']['summary'];
+/** A lean stored-run pointer (the `sessions list` row, agent-shaped). */
+export interface RunSummary {
+    readonly id: string;
+    readonly tool: string;
+    readonly startedAt: string;
+    readonly completedAt: string;
+    readonly score: number;
+    readonly passed: boolean;
+    /** The `opensip sessions show … --json` command that replays this run. */
+    readonly showCommand: string;
+    /** Verdict counts when the stored payload carried a summary. */
+    readonly summary?: RunVerdictSummary;
+}
+/** Options for {@link ResultsReadPort.latestFindings}. */
+export interface LatestFindingsOptions {
+    readonly tool: ToolShortId;
+    /** `errors` → errors-only, `warnings` → warnings-only, `all` → no severity filter. */
+    readonly severity?: 'errors' | 'warnings' | 'all';
+    /** Cap the returned findings (maps to the `top:<n>` filter). */
+    readonly limit?: number;
+}
+/** A compact finding row projected from a replayed envelope signal. */
+export interface McpFinding {
+    readonly ruleId: string;
+    readonly message: string;
+    readonly severity: SignalSeverity;
+    readonly filePath?: string;
+    readonly line?: number;
+    readonly column?: number;
+}
+/** The `show_run` payload: the replayed envelope + its fidelity marker. */
+export interface ShowRunData {
+    /** Always `'projection'` — replays are rebuilt from persisted data. */
+    readonly fidelity: 'projection';
+    readonly envelope: SignalEnvelope;
+}
+/**
+ * The shared result-replay envelope: `data` + session provenance + (when a
+ * filter narrowed the signals) the agent filter metadata + `recommendedNext`
+ * follow-up commands.
+ */
+export interface McpResultReplay<T> {
+    readonly data: T;
+    readonly session?: RunSummary;
+    readonly filtersApplied?: readonly string[];
+    readonly originalSignalCount?: number;
+    readonly returnedSignalCount?: number;
+    readonly recommendedNext?: Record<string, string>;
+}
+//# sourceMappingURL=result-dto.d.ts.map

package/dist/result-dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-dto.d.ts","sourceRoot":"","sources":["../src/result-dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErE,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC;AAErE,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;CACtC;AAED,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;IAClD,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnD"}

package/dist/result-dto.js

@@ -0,0 +1,11 @@
+/**
+ * Result/history DTOs for the MCP {@link ResultsReadPort} (ADR-0084).
+ *
+ * Every result response carries session provenance + `recommendedNext` commands
+ * so an agent can drill in (or re-run) without guessing the CLI grammar. The
+ * payloads are the host-owned generic replay projection (the same decoded signal
+ * list `sessions show` produces) — never another tool's opaque payload
+ * vocabulary (ADR-0042 opacity boundary holds).
+ */
+export {};
+//# sourceMappingURL=result-dto.js.map

package/dist/result-dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-dto.js","sourceRoot":"","sources":["../src/result-dto.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/results-read-port.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `ResultsReadPort` — the narrow read interface the MCP result/history tool
+ * handlers depend on (ADR-0084). Kept separate from `GraphReadPort` because
+ * session reads and graph-catalog reads are distinct backends with distinct
+ * consumers (SRP) — each has exactly one production impl + one test fake.
+ *
+ * Result tools **never** re-execute the underlying OpenSIP tool; they replay
+ * persisted sessions only (paired with the `mcp-results-no-rerun` check). The
+ * impl reads through the `@opensip-cli/session-store` read API — it never names
+ * `SessionRepo` and never raw-queries the datastore.
+ */
+import type { McpReadError } from './mcp-error.js';
+import type { LatestFindingsOptions, McpFinding, McpResultReplay, RunSummary, ShowRunData } from './result-dto.js';
+import type { AgentCatalog } from '@opensip-cli/contracts';
+import type { Result, ToolShortId } from '@opensip-cli/core';
+/** Options for {@link ResultsReadPort.listRuns}. */
+export interface ListRunsOptions {
+    readonly tool?: ToolShortId;
+    readonly limit?: number;
+    /** Omit heavy stored payloads (agent-friendly; defaults on in the impl). */
+    readonly summaryOnly?: boolean;
+}
+/** Options for {@link ResultsReadPort.showRun}. */
+export interface ShowRunOptions {
+    /** Session id, or the sentinel `'latest'` (which requires `tool`). */
+    readonly ref: string;
+    readonly tool?: ToolShortId;
+    /** Agent ergonomics filters applied to the replayed envelope (ADR-0085). */
+    readonly filters?: readonly string[];
+    /** Request the minimal payload (handler presentation hint). */
+    readonly raw?: boolean;
+}
+export interface ResultsReadPort {
+    /** The self-describing agent command catalog. */
+    agentCatalog(): Result<AgentCatalog, McpReadError>;
+    /** List stored runs as lean {@link RunSummary} pointers. */
+    listRuns(opts?: ListRunsOptions): Result<readonly RunSummary[], McpReadError>;
+    /** Replay one stored run (resolve `ref`, decode, filter) — never re-run. */
+    showRun(opts: ShowRunOptions): Promise<Result<McpResultReplay<ShowRunData>, McpReadError>>;
+    /** The latest run's findings for `tool`, severity/limit-filtered. */
+    latestFindings(opts: LatestFindingsOptions): Promise<Result<McpResultReplay<readonly McpFinding[]>, McpReadError>>;
+}
+//# sourceMappingURL=results-read-port.d.ts.map

package/dist/results-read-port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results-read-port.d.ts","sourceRoot":"","sources":["../src/results-read-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EACV,qBAAqB,EACrB,UAAU,EACV,eAAe,EACf,UAAU,EACV,WAAW,EACZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE7D,oDAAoD;AACpD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,YAAY,IAAI,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;IACnD,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,SAAS,UAAU,EAAE,EAAE,YAAY,CAAC,CAAC;IAC9E,4EAA4E;IAC5E,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;IAC3F,qEAAqE;IACrE,cAAc,CACZ,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,SAAS,UAAU,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;CAC1E"}

package/dist/results-read-port.js

@@ -0,0 +1,13 @@
+/**
+ * `ResultsReadPort` — the narrow read interface the MCP result/history tool
+ * handlers depend on (ADR-0084). Kept separate from `GraphReadPort` because
+ * session reads and graph-catalog reads are distinct backends with distinct
+ * consumers (SRP) — each has exactly one production impl + one test fake.
+ *
+ * Result tools **never** re-execute the underlying OpenSIP tool; they replay
+ * persisted sessions only (paired with the `mcp-results-no-rerun` check). The
+ * impl reads through the `@opensip-cli/session-store` read API — it never names
+ * `SessionRepo` and never raw-queries the datastore.
+ */
+export {};
+//# sourceMappingURL=results-read-port.js.map

package/dist/results-read-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"results-read-port.js","sourceRoot":"","sources":["../src/results-read-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/server.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The stdio MCP server (ADR-0084).
+ *
+ * `opensip mcp` is the first long-lived, BLOCKING command in opensip-cli. Two
+ * properties make its construction unusual and are the whole point of this file:
+ *
+ *   1. **Scope captured, never ambient.** The MCP SDK dispatches tool handlers
+ *      off an internal EventEmitter, so `currentScope()` (AsyncLocalStorage) does
+ *      NOT propagate into them — a handler that read `currentScope()` would find
+ *      `undefined` and silently degrade (no datastore, no logger runId). The fix
+ *      is to capture the `RunScope` at construction and re-enter it per call via
+ *      `runWithScope(capturedScope, …)` (see {@link McpStdioServer.register}). The
+ *      ports are likewise PRE-BUILT and injected; handlers never reach for scope.
+ *
+ *   2. **stdout is JSON-RPC only.** The stdio transport owns stdout for the
+ *      protocol frames. Every diagnostic must go to stderr. The `@opensip-cli/core`
+ *      structured logger never writes stdout (it writes the per-project log file
+ *      and — in debug mode — stderr), so we route its sink to stderr for the serve
+ *      lifetime via the `configureLogger` seam and emit only at decision points
+ *      (`mcp.server.start|stop`, `mcp.tool.dispatch[.ok|.error]`). No `console.*`
+ *      / `process.stdout.write` for diagnostics anywhere in the serve path.
+ *
+ * No tools are registered here yet — Phase 4 mounts the catalog onto this server
+ * through the {@link McpStdioServer.register} seam (which guarantees the
+ * scope-wrap for every handler). The server resolves its lifetime promise on
+ * stdin EOF (or a SIGINT-driven graceful close); it never calls `process.exit`,
+ * leaving the final exit code to the host command handler.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GraphReadPort } from './graph-read-port.js';
+import type { ResultsReadPort } from './results-read-port.js';
+import type { RunScope } from '@opensip-cli/core';
+type SdkRegisterTool = McpServer['registerTool'];
+export type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** Construction deps — captured ONCE; handlers never read ambient scope. */
+export interface McpStdioServerDeps {
+    /**
+     * The `RunScope` the host entered for this invocation. Captured here and
+     * re-entered (`runWithScope`) around every tool handler — the load-bearing
+     * fix for the SDK's EventEmitter dispatch dropping AsyncLocalStorage.
+     */
+    readonly scope: RunScope;
+    /** Pre-built graph read port (Phase 2). */
+    readonly graph: GraphReadPort;
+    /** Pre-built results/history read port (Phase 2). */
+    readonly results: ResultsReadPort;
+    /** Server version advertised in the handshake (the `@opensip-cli/mcp` version). */
+    readonly version: string;
+}
+/**
+ * A long-lived stdio MCP server bound to one captured {@link RunScope}.
+ *
+ * Construct with pre-built ports + the captured scope, register tools through
+ * {@link register} (Phase 4), then `await serve()` — the promise resolves when
+ * the transport closes (stdin EOF / graceful SIGINT).
+ */
+export declare class McpStdioServer {
+    private readonly mcp;
+    private readonly transport;
+    private readonly scope;
+    private readonly version;
+    /** The graph read port handlers close over (Phase 4 reads it). */
+    readonly graph: GraphReadPort;
+    /** The results read port handlers close over (Phase 4 reads it). */
+    readonly results: ResultsReadPort;
+    constructor(deps: McpStdioServerDeps);
+    /**
+     * Register a tool, wrapping its handler so EVERY dispatch re-enters the
+     * captured scope (`runWithScope`) and is bracketed by `mcp.tool.dispatch`
+     * decision-point logging. The public signature is exactly the SDK's
+     * `registerTool` (full generic fidelity for the Phase-4 call sites); the thin
+     * forwarder casts internally because it is scope-/schema-agnostic.
+     */
+    register: SdkRegisterTool;
+    /** Run one wrapped handler inside the captured scope, with decision logging. */
+    private dispatch;
+    /**
+     * Serve until the stdio transport closes. Resolves on stdin EOF (or a
+     * SIGINT-driven graceful close). Never calls `process.exit` — the host command
+     * handler resolves cleanly and owns the final exit code (ADR-0084).
+     */
+    serve(): Promise<void>;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAYlD,KAAK,eAAe,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;AACjD,YAAY,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,4EAA4E;AAC5E,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAW;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBAEtB,IAAI,EAAE,kBAAkB;IAUpC;;;;;;OAMG;IACH,QAAQ,EAAE,eAAe,CASvB;IAEF,gFAAgF;IAChF,OAAO,CAAC,QAAQ;IAwBhB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA6C7B"}