@codragraph/cli 2.1.6 → 2.2.0

package/dist/core/semantic/relationships.js

@@ -0,0 +1,261 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { FsCAS, getJson, parseObjectId, readCommit, resolveHeadCommit, } from '@codragraph/graphstore';
+import { GRAPHSTORE_SUBDIR } from '../graphstore/index.js';
+export const SEMANTIC_RELATIONSHIP_VERSION = 'semantic-extractor-v1';
+export const analyzeSemanticRelationships = async (opts) => {
+    const graphstoreRoot = path.join(opts.storagePath, GRAPHSTORE_SUBDIR);
+    const cas = new FsCAS({ root: graphstoreRoot });
+    const head = await resolveHeadCommit({ root: graphstoreRoot });
+    if (head === null) {
+        throw new Error('semantic analyze requires a graphstore HEAD. Run `codragraph analyze` first.');
+    }
+    const commit = await readCommit(cas, head);
+    const snapshot = await getJson(cas, commit.snapshot);
+    const manifest = await getJson(cas, parseObjectId(snapshot.manifestId));
+    const nodes = await loadNodes(cas, manifest);
+    const relationships = await inferRelationships({
+        cas,
+        manifest,
+        nodes,
+        limit: opts.limit ?? 1000,
+    });
+    const report = {
+        snapshotId: commit.snapshot,
+        extractorVersion: SEMANTIC_RELATIONSHIP_VERSION,
+        llmEnabled: opts.llm === true,
+        relationships,
+        summary: summarize(relationships),
+    };
+    if (opts.write) {
+        await fs.writeFile(path.join(opts.storagePath, 'semantic-relationships.json'), `${JSON.stringify(report, null, 2)}\n`, 'utf-8');
+    }
+    return report;
+};
+const loadNodes = async (cas, manifest) => {
+    const nodes = new Map();
+    for (const [table, tableManifest] of Object.entries(manifest.nodeTables)) {
+        for (const [id, objectId] of Object.entries(tableManifest.rows)) {
+            const row = await getJson(cas, parseObjectId(objectId));
+            nodes.set(id, {
+                id,
+                table,
+                name: stringProp(row, 'name'),
+                filePath: stringProp(row, 'filePath'),
+                startLine: numberProp(row, 'startLine'),
+                endLine: numberProp(row, 'endLine'),
+            });
+        }
+    }
+    return nodes;
+};
+const inferRelationships = async (opts) => {
+    const highSignal = [];
+    const fallback = [];
+    const seen = new Set();
+    const edgeEntries = Object.entries(opts.manifest.edges.rows);
+    for (const [edgeKey, objectId] of edgeEntries) {
+        let edge;
+        const parsed = parseEdgeKey(edgeKey);
+        if (!parsed)
+            edge = await getJson(opts.cas, parseObjectId(objectId));
+        const from = parsed?.from ?? stringProp(edge, 'from');
+        const to = parsed?.to ?? stringProp(edge, 'to');
+        const rawType = parsed?.rawType ?? stringProp(edge, 'type');
+        if (!from || !to || !rawType)
+            continue;
+        if (!SEMANTIC_RAW_EDGE_TYPES.has(rawType))
+            continue;
+        const source = opts.nodes.get(from);
+        const target = opts.nodes.get(to);
+        const classified = classifySemanticEdge({ rawType, source, target });
+        if (!classified)
+            continue;
+        const key = `${from}|${classified.family}|${to}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const relationship = {
+            id: `semantic:${hashKey(key).slice(0, 32)}`,
+            family: classified.family,
+            sourceId: from,
+            ...(source?.name ? { sourceName: source.name } : {}),
+            targetId: to,
+            ...(target?.name ? { targetName: target.name } : {}),
+            confidence: classified.confidence,
+            provenance: rawType === classified.family ? 'extracted' : 'inferred',
+            extractorVersion: SEMANTIC_RELATIONSHIP_VERSION,
+            evidence: {
+                filePath: source?.filePath ?? target?.filePath,
+                startLine: source?.startLine ?? target?.startLine,
+                endLine: source?.endLine ?? target?.endLine,
+                rawEdgeType: rawType,
+                rawEdgeConfidence: edge ? numberProp(edge, 'confidence') : undefined,
+                reason: classified.reason,
+            },
+        };
+        const bucket = classified.family === 'COMPOSES' ? fallback : highSignal;
+        bucket.push(relationship);
+        if (highSignal.length >= opts.limit)
+            break;
+    }
+    return [
+        ...highSignal.sort(compareSemanticRelationships),
+        ...fallback.sort(compareSemanticRelationships),
+    ].slice(0, opts.limit);
+};
+const SEMANTIC_RAW_EDGE_TYPES = new Set([
+    'CALLS',
+    'IMPORTS',
+    'EXTENDS',
+    'IMPLEMENTS',
+    'HAS_METHOD',
+    'HAS_PROPERTY',
+    'ACCESSES',
+    'METHOD_OVERRIDES',
+    'METHOD_IMPLEMENTS',
+    'WRAPS',
+    'FETCHES',
+    'HANDLES_ROUTE',
+    'HANDLES_TOOL',
+    'QUERIES',
+]);
+const parseEdgeKey = (edgeKey) => {
+    const parts = edgeKey.split('|');
+    if (parts.length < 3)
+        return null;
+    const [from, rawType, ...toParts] = parts;
+    if (!from || !rawType || toParts.length === 0)
+        return null;
+    return { from, rawType, to: toParts.join('|') };
+};
+const classifySemanticEdge = (input) => {
+    const sourceName = input.source?.name ?? input.source?.id ?? '';
+    const targetName = input.target?.name ?? input.target?.id ?? '';
+    const source = sourceName.toLowerCase();
+    const target = targetName.toLowerCase();
+    const rawType = input.rawType;
+    if (rawType === 'WRAPS' || hasAny(source, ['wrapper', 'middleware', 'decorator'])) {
+        return {
+            family: 'WRAPS',
+            confidence: rawType === 'WRAPS' ? 0.95 : 0.78,
+            reason: 'wrapper/decorator naming or raw WRAPS edge',
+        };
+    }
+    if (rawType === 'IMPLEMENTS' && hasAny(source, ['adapter', 'adaptor'])) {
+        return { family: 'ADAPTS', confidence: 0.86, reason: 'adapter implementation edge' };
+    }
+    if (hasAny(source, ['adapter', 'adaptor']) && ['CALLS', 'IMPORTS'].includes(rawType)) {
+        return { family: 'ADAPTS', confidence: 0.72, reason: 'adapter symbol delegates to target' };
+    }
+    if (hasAny(source, ['proxy', 'client']) && ['CALLS', 'FETCHES', 'IMPORTS'].includes(rawType)) {
+        return {
+            family: 'PROXIES_TO',
+            confidence: 0.74,
+            reason: 'proxy/client symbol forwards to target',
+        };
+    }
+    if (hasAny(source, ['factory', 'builder']) || /^(create|make|build)[A-Z_]/.test(sourceName)) {
+        if (['CALLS', 'HAS_METHOD', 'IMPORTS'].includes(rawType)) {
+            return {
+                family: 'FACTORY_CREATES',
+                confidence: 0.75,
+                reason: 'factory/create/build symbol reaches constructed target',
+            };
+        }
+    }
+    if (hasAny(source, ['config', 'configure', 'setup', 'options']) &&
+        ['CALLS', 'ACCESSES', 'IMPORTS'].includes(rawType)) {
+        return {
+            family: 'CONFIGURES',
+            confidence: 0.7,
+            reason: 'configuration symbol controls target behavior',
+        };
+    }
+    if (hasAny(source, ['orchestrator', 'coordinator', 'workflow', 'pipeline', 'runner']) &&
+        rawType === 'CALLS') {
+        return {
+            family: 'ORCHESTRATES',
+            confidence: 0.76,
+            reason: 'orchestrator/coordinator call edge',
+        };
+    }
+    if (hasAny(source, ['mapper', 'map', 'dto', 'transformer', 'serializer']) ||
+        hasAny(target, ['dto', 'schema', 'model'])) {
+        if (['CALLS', 'IMPORTS', 'ACCESSES'].includes(rawType)) {
+            return { family: 'MAPS_TO', confidence: 0.7, reason: 'mapper/DTO transformation signal' };
+        }
+    }
+    if (rawType === 'HAS_PROPERTY' || rawType === 'ACCESSES') {
+        return {
+            family: 'COMPOSES',
+            confidence: 0.68,
+            reason: 'field/property ownership or access edge',
+        };
+    }
+    if (rawType === 'CALLS' && /^(handle|run|execute|process|dispatch)/i.test(sourceName)) {
+        return {
+            family: 'DELEGATES_TO',
+            confidence: 0.66,
+            reason: 'handler/executor delegates to callee',
+        };
+    }
+    return null;
+};
+const summarize = (relationships) => {
+    const summary = {
+        COMPOSES: 0,
+        ADAPTS: 0,
+        DELEGATES_TO: 0,
+        WRAPS: 0,
+        CONFIGURES: 0,
+        FACTORY_CREATES: 0,
+        ORCHESTRATES: 0,
+        PROXIES_TO: 0,
+        MAPS_TO: 0,
+    };
+    for (const rel of relationships)
+        summary[rel.family]++;
+    return summary;
+};
+const compareSemanticRelationships = (a, b) => {
+    const byFamily = familyPriority(a.family) - familyPriority(b.family);
+    if (byFamily !== 0)
+        return byFamily;
+    return b.confidence - a.confidence;
+};
+const familyPriority = (family) => {
+    switch (family) {
+        case 'ADAPTS':
+            return 0;
+        case 'WRAPS':
+            return 1;
+        case 'PROXIES_TO':
+            return 2;
+        case 'FACTORY_CREATES':
+            return 3;
+        case 'ORCHESTRATES':
+            return 4;
+        case 'CONFIGURES':
+            return 5;
+        case 'MAPS_TO':
+            return 6;
+        case 'DELEGATES_TO':
+            return 7;
+        case 'COMPOSES':
+            return 8;
+    }
+};
+const hasAny = (value, needles) => needles.some((needle) => value.includes(needle));
+const stringProp = (row, key) => {
+    const value = row[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+};
+const numberProp = (row, key) => {
+    const value = row[key];
+    return typeof value === 'number' ? value : undefined;
+};
+const hashKey = (key) => {
+    return crypto.createHash('sha256').update(key).digest('hex');
+};

package/dist/mcp/local/local-backend.js

@@ -768,6 +768,48 @@ export class LocalBackend {
                     params?.id ??
                     ''), params?.repo, params?.direction ??
                     'upstream', clampNumber(params?.limit, 1, 500, 100));
+            case 'graphpack_status': {
+                const { getGraphpackStatus } = await import('../../core/graphpack/index.js');
+                return getGraphpackStatus({
+                    repoPath: repo.repoPath,
+                    storagePath: repo.storagePath,
+                    strict: params?.strict === true,
+                });
+            }
+            case 'graphpack_publish': {
+                const { publishGraphpack } = await import('../../core/graphpack/index.js');
+                const args = params ?? {};
+                return publishGraphpack({
+                    repoPath: repo.repoPath,
+                    storagePath: repo.storagePath,
+                    repoName: typeof args['repo'] === 'string' ? args['repo'] : repo.name,
+                    analyzerVersion: 'mcp',
+                    target: args['target'] === 'pr' ? 'pr' : 'main',
+                    artifactDir: typeof args['artifact_dir'] === 'string' ? args['artifact_dir'] : undefined,
+                    artifactUrl: typeof args['artifact_url'] === 'string' ? args['artifact_url'] : undefined,
+                    baseSnapshotId: typeof args['base_snapshot_id'] === 'string' ? args['base_snapshot_id'] : undefined,
+                    headSnapshotId: typeof args['head_snapshot_id'] === 'string' ? args['head_snapshot_id'] : undefined,
+                    pullRequest: typeof args['pull_request'] === 'string' ? args['pull_request'] : undefined,
+                });
+            }
+            case 'graphpack_pull': {
+                const { pullGraphpack } = await import('../../core/graphpack/index.js');
+                const args = params ?? {};
+                return pullGraphpack({
+                    repoPath: repo.repoPath,
+                    storagePath: repo.storagePath,
+                    artifactDir: typeof args['artifact_dir'] === 'string' ? args['artifact_dir'] : undefined,
+                });
+            }
+            case 'semantic_relationships': {
+                const { analyzeSemanticRelationships } = await import('../../core/semantic/relationships.js');
+                return analyzeSemanticRelationships({
+                    storagePath: repo.storagePath,
+                    llm: params?.llm === true,
+                    limit: clampNumber(params?.limit, 1, 10000, 1000),
+                    write: false,
+                });
+            }
             case 'harness_swarm_run': {
                 // Same lazy-import dance as harness_run (see comments below) — keeps
                 // codragraph-harness optional and avoids a circular build-time dep.

package/dist/mcp/resources.js

@@ -96,6 +96,24 @@ export function getResourceTemplates() {
             description: "Phase 4: the indexed repo's current branch + head commit, plus the snapshot it points at. Pairs with graphstore_log/diff/blame.",
             mimeType: 'text/yaml',
         },
+        {
+            uriTemplate: 'codragraph://repo/{name}/graphpack/status',
+            name: 'Team Graphpack Status',
+            description: 'Team graphpack provenance: canonical main graph, PR overlay, local graph, chunk health, and compatibility.',
+            mimeType: 'text/yaml',
+        },
+        {
+            uriTemplate: 'codragraph://repo/{name}/graphpack/lock',
+            name: 'Team Graphpack Lock',
+            description: 'Committed .codragraph/index.lock.json content for shared team graph bootstrapping.',
+            mimeType: 'application/json',
+        },
+        {
+            uriTemplate: 'codragraph://repo/{name}/semantic-relationships',
+            name: 'Semantic Relationships',
+            description: 'Developer-intent relationship families with confidence, evidence, provenance, and extractor version.',
+            mimeType: 'text/yaml',
+        },
         {
             uriTemplate: 'codragraph://repo/{name}/recipes',
             name: 'Harness Recipes',
@@ -267,6 +285,12 @@ export async function readResource(uri, backend) {
             return getGraphstoreBranchesResource(backend, repoName);
         case 'graphstore/head':
             return getGraphstoreHeadResource(backend, repoName);
+        case 'graphpack/status':
+            return getGraphpackStatusResource(backend, repoName);
+        case 'graphpack/lock':
+            return getGraphpackLockResource(backend, repoName);
+        case 'semantic-relationships':
+            return getSemanticRelationshipsResource(backend, repoName);
         case 'recipes':
             return getRecipesResource(backend, repoName);
         default:
@@ -340,6 +364,8 @@ async function getContextResource(backend, repoName) {
     lines.push('  - impact: Blast radius analysis (what breaks if you change a symbol)');
     lines.push('  - detect_changes: Git-diff impact analysis (what do your changes affect)');
     lines.push('  - rename: Multi-file coordinated rename with confidence tags');
+    lines.push('  - graphpack_status: Team graph provenance and artifact health');
+    lines.push('  - semantic_relationships: Developer-intent semantic edge families');
     lines.push('  - cypher: Raw graph queries');
     lines.push('  - list_repos: Discover all indexed repositories');
     lines.push('');
@@ -350,6 +376,8 @@ async function getContextResource(backend, repoName) {
     lines.push(`  - codragraph://repo/${context.projectName}/clusters: All functional areas`);
     lines.push(`  - codragraph://repo/${context.projectName}/feature-clusters: Human-facing feature areas`);
     lines.push(`  - codragraph://repo/${context.projectName}/processes: All execution flows`);
+    lines.push(`  - codragraph://repo/${context.projectName}/graphpack/status: Team graphpack status`);
+    lines.push(`  - codragraph://repo/${context.projectName}/semantic-relationships: Developer-intent relationships`);
     lines.push(`  - codragraph://repo/${context.projectName}/cluster/{name}: Module details`);
     lines.push(`  - codragraph://repo/${context.projectName}/feature/{name}: Feature context pack`);
     lines.push(`  - codragraph://repo/${context.projectName}/process/{name}: Process trace`);
@@ -759,6 +787,100 @@ async function getGraphstoreBranchesResource(backend, repoName) {
     }
     return lines.join('\n');
 }
+async function getGraphpackStatusResource(backend, repoName) {
+    const repo = await backend.resolveRepo(repoName);
+    const { getGraphpackStatus } = await import('../core/graphpack/index.js');
+    try {
+        const status = await getGraphpackStatus({
+            repoPath: repo.repoPath,
+            storagePath: repo.storagePath,
+        });
+        const lines = [
+            `repo: "${repo.name}"`,
+            `source: "${status.source}"`,
+            `lockPresent: ${status.lockPresent}`,
+            `compatible: ${status.compatibility.ok}`,
+            `localGraphstore: ${status.local.graphstorePresent}`,
+            `verifiedChunks: ${status.chunks.verified}`,
+            `expectedChunks: ${status.chunks.expected}`,
+        ];
+        if (status.lock?.graphpack.id)
+            lines.push(`graphpack: "${status.lock.graphpack.id}"`);
+        if (status.lock?.graphpack.graphstoreSnapshot) {
+            lines.push(`snapshot: "${status.lock.graphpack.graphstoreSnapshot}"`);
+        }
+        if (status.local.headCommit)
+            lines.push(`localHead: "${status.local.headCommit}"`);
+        if (status.compatibility.reasons.length > 0) {
+            lines.push('reasons:');
+            for (const reason of status.compatibility.reasons)
+                lines.push(`  - ${JSON.stringify(reason)}`);
+        }
+        if (status.chunks.missing.length > 0) {
+            lines.push('missingChunks:');
+            for (const chunk of status.chunks.missing)
+                lines.push(`  - "${chunk}"`);
+        }
+        if (status.chunks.mismatched.length > 0) {
+            lines.push('mismatchedChunks:');
+            for (const chunk of status.chunks.mismatched)
+                lines.push(`  - "${chunk}"`);
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+async function getGraphpackLockResource(backend, repoName) {
+    const repo = await backend.resolveRepo(repoName);
+    const { defaultLockPath, readGraphpackLock } = await import('../core/graphpack/index.js');
+    const lock = await readGraphpackLock(defaultLockPath(repo.repoPath));
+    if (!lock) {
+        return JSON.stringify({ error: 'No .codragraph/index.lock.json found', repo: repo.name });
+    }
+    return JSON.stringify(lock, null, 2);
+}
+async function getSemanticRelationshipsResource(backend, repoName) {
+    const repo = await backend.resolveRepo(repoName);
+    const { analyzeSemanticRelationships } = await import('../core/semantic/relationships.js');
+    try {
+        const report = await analyzeSemanticRelationships({
+            storagePath: repo.storagePath,
+            limit: 200,
+            write: false,
+        });
+        const lines = [
+            `repo: "${repo.name}"`,
+            `snapshot: "${report.snapshotId ?? 'unknown'}"`,
+            `extractor: "${report.extractorVersion}"`,
+            `relationships: ${report.relationships.length}`,
+            'summary:',
+        ];
+        for (const [family, count] of Object.entries(report.summary)) {
+            lines.push(`  ${family}: ${count}`);
+        }
+        lines.push('edges:');
+        for (const rel of report.relationships.slice(0, 50)) {
+            lines.push(`  - family: "${rel.family}"`);
+            lines.push(`    source: ${JSON.stringify(rel.sourceName ?? rel.sourceId)}`);
+            lines.push(`    target: ${JSON.stringify(rel.targetName ?? rel.targetId)}`);
+            lines.push(`    confidence: ${rel.confidence}`);
+            lines.push(`    provenance: "${rel.provenance}"`);
+            lines.push(`    extractor: "${rel.extractorVersion}"`);
+            if (rel.evidence.filePath)
+                lines.push(`    file: "${rel.evidence.filePath}"`);
+            if (rel.evidence.startLine !== undefined)
+                lines.push(`    startLine: ${rel.evidence.startLine}`);
+            lines.push(`    reason: ${JSON.stringify(rel.evidence.reason)}`);
+            lines.push(`    rawEdgeType: "${rel.evidence.rawEdgeType}"`);
+        }
+        return lines.join('\n');
+    }
+    catch (err) {
+        return `error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
 async function getRecipesResource(backend, repoName, taskFamily) {
     const repo = await backend.resolveRepo(repoName);
     let result;
@@ -794,6 +916,9 @@ async function getRecipesResource(backend, repoName, taskFamily) {
         lines.push(`  - id: "${r.id}"`);
         lines.push(`    taskFamily: "${r.taskFamily}"`);
         lines.push(`    snapshotId: "${r.snapshotId}"`);
+        if (r.requiredSubgraphSignature) {
+            lines.push(`    requiredSubgraphSignature: "${r.requiredSubgraphSignature}"`);
+        }
         lines.push(`    accuracy: ${r.accuracy}`);
         lines.push(`    tokens: ${r.tokens}`);
         lines.push(`    latencyMs: ${r.latencyMs}`);

package/dist/mcp/tools.js

@@ -642,6 +642,99 @@ WHEN TO USE: After changing group.yaml or re-indexing member repos.`,
             required: ['name'],
         },
     },
+    {
+        name: 'graphpack_status',
+        description: `Show the team graphpack state for a repo.
+
+WHEN TO USE: before answering team-shared-context questions. Reports whether the answer should be considered canonical main graph, PR overlay, local graph, or missing/fallback.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                strict: {
+                    type: 'boolean',
+                    description: 'Recompute graphstore CAS digest instead of trusting local presence.',
+                    default: false,
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'graphpack_publish',
+        description: `Create a thin .codragraph/index.lock.json plus graphpack manifest for GitHub-native artifact publishing.
+
+WHEN TO USE: CI on main or PR branches after analyze. Commits the lock only; heavy graphstore chunks remain artifact storage.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                target: {
+                    type: 'string',
+                    enum: ['main', 'pr'],
+                    description: 'Graphpack target.',
+                    default: 'main',
+                },
+                artifact_dir: { type: 'string', description: 'Local artifact staging directory.' },
+                artifact_url: { type: 'string', description: 'Remote artifact URL to record in the lock.' },
+                base_snapshot_id: { type: 'string', description: 'PR overlay base snapshot id.' },
+                head_snapshot_id: { type: 'string', description: 'PR overlay head snapshot id.' },
+                pull_request: { type: 'string', description: 'Pull request number or URL.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'graphpack_pull',
+        description: `Validate/pull a graphpack from a lock and report whether local materialization can proceed.
+
+WHEN TO USE: developer bootstrap after clone/checkout. If unavailable or incompatible, the result includes a safe local analyze fallback reason.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                artifact_dir: { type: 'string', description: 'Local graphpack artifact directory.' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'semantic_relationships',
+        description: `Return developer-intent semantic relationships above raw graph edges.
+
+Families include COMPOSES, ADAPTS, DELEGATES_TO, WRAPS, CONFIGURES, FACTORY_CREATES, ORCHESTRATES, PROXIES_TO, and MAPS_TO. Every edge includes evidence, confidence, extractor version, and provenance.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                repo: {
+                    type: 'string',
+                    description: 'Repository name or path. Omit if only one repo is indexed.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum relationships to return.',
+                    default: 1000,
+                    minimum: 1,
+                    maximum: 10000,
+                },
+                llm: {
+                    type: 'boolean',
+                    description: 'Allow optional LLM-inferred edges when provider support is configured.',
+                    default: false,
+                },
+            },
+            required: [],
+        },
+    },
     {
         name: 'harness_swarm_run',
         description: `Phase 3 swarm: Explorer + Exploiter (subprocess) + Critic (in-process), with hybrid termination.
@@ -727,6 +820,10 @@ Returns the Pareto frontier plus per-role attribution stats (which role contribu
                     type: 'string',
                     description: 'Phase 4 moat: codragraph-graphstore snapshot id (sha256:...). Required to enable recipe caching.',
                 },
+                required_subgraph_signature: {
+                    type: 'string',
+                    description: 'Phase 4 moat: stable signature of the task-required subgraph. Exact cache reuse keys on (snapshot_id, task_family, required_subgraph_signature).',
+                },
                 use_cache: {
                     type: 'boolean',
                     description: 'Phase 4 moat: when true and an exact (snapshot_id, task_family) recipe exists, return it instead of running the swarm.',
@@ -757,6 +854,10 @@ This is the Phase 4 × Phase 3 moat — versioned recipe memory. Recipes auto-in
             properties: {
                 task_family: { type: 'string', description: 'Filter by task family.' },
                 snapshot_id: { type: 'string', description: 'Filter by snapshot id (sha256:...).' },
+                required_subgraph_signature: {
+                    type: 'string',
+                    description: 'Filter by required subgraph signature.',
+                },
                 recipe_store: {
                     type: 'string',
                     description: 'Recipe store root. Defaults to <cwd>/.codragraph/recipes.',
@@ -780,6 +881,10 @@ WHEN TO USE: before kicking off a swarm. If exact matches exist, you can skip th
             properties: {
                 task_family: { type: 'string', description: 'Task family identifier.' },
                 snapshot_id: { type: 'string', description: 'Current codragraph-graphstore snapshot id.' },
+                required_subgraph_signature: {
+                    type: 'string',
+                    description: 'Stable signature of the subgraph this task needs. Exact reuse requires matching snapshot, family, and signature.',
+                },
                 recipe_store: {
                     type: 'string',
                     description: 'Recipe store root. Defaults to <cwd>/.codragraph/recipes.',