@weftlet/toolkit 0.6.1 → 0.7.0

package/dist/index.js

@@ -20,3 +20,25 @@ export * from './application/document-coverage.js';
 export * from './extraction/document-traversal.js';
 export * from './extraction/document-classification.js';
 export * from './extraction/document-evidence.js';
+export * from './graph/neighborhood.js';
+export * from './graph/neighborhood-request.js';
+export * from './graph/neighborhood-renderer.js';
+export * from './graph/paths.js';
+export * from './graph/path-request.js';
+export * from './graph/paths-renderer.js';
+export * from './extraction/document-code-bindings.js';
+export * from './extraction/document-obligations.js';
+export * from './graph/compatibility.js';
+export * from './graph/compatibility-request.js';
+export * from './graph/compatibility-renderer.js';
+export * from './graph/code-coverage.js';
+export * from './graph/code-coverage-projection.js';
+export * from './graph/code-coverage-request.js';
+export * from './graph/code-coverage-renderer.js';
+export { MappingProposalService } from './application/mapping-proposals.js';
+export { createMappingProposalService } from './application/mapping-service.js';
+export { prepareMappingProposal } from './extraction/mapping-plan.js';
+export { createMappingProvider, mappingProviderIdentity } from './extraction/mapping-provider.js';
+export { parseMappingRequest } from './extraction/mapping-request.js';
+export { validateMappingOutput } from './extraction/mapping-output.js';
+export { FileMappingProposalStore } from './storage/mapping-proposals.js';

package/dist/infrastructure/json-digest.d.ts

@@ -0,0 +1,2 @@
+/** Identity of persisted JSON, excluding undefined optional fields that JSON cannot retain. */
+export declare const jsonDigest: (value: unknown) => string;

package/dist/infrastructure/json-digest.js

@@ -0,0 +1,3 @@
+import { sha256, stableJson } from './util.js';
+/** Identity of persisted JSON, excluding undefined optional fields that JSON cannot retain. */
+export const jsonDigest = (value) => sha256(stableJson(JSON.parse(JSON.stringify(value))));

package/dist/infrastructure/unique-json.d.ts

@@ -0,0 +1,2 @@
+/** JSON.parse silently accepts duplicate keys, including differently escaped spellings. */
+export declare function parseUniqueJson(content: string): unknown;

package/dist/infrastructure/unique-json.js

@@ -0,0 +1,20 @@
+/** JSON.parse silently accepts duplicate keys, including differently escaped spellings. */
+export function parseUniqueJson(content) {
+    const parsed = JSON.parse(content);
+    const objects = [];
+    for (const token of content.matchAll(/"(?:\\.|[^"\\])*"|[{}\[\]]/g)) {
+        const value = token[0];
+        if (value === '{' || value === '[')
+            objects.push(value === '{' ? new Set() : undefined);
+        else if (value === '}' || value === ']')
+            objects.pop();
+        else if (/^\s*:/.test(content.slice(token.index + value.length))) {
+            const keys = objects.at(-1);
+            const key = JSON.parse(value);
+            if (keys.has(key))
+                throw new Error('Duplicate JSON key');
+            keys.add(key);
+        }
+    }
+    return parsed;
+}

package/dist/interfaces/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 // Modified for standalone extraction; see docs/extraction-manifest.json.
 import "../../runtime-check.mjs";
+import { runMappingsCommand } from './mapping-proposals.js';
 import { resolve } from 'node:path';
 import process from 'node:process';
 import { createContextGraphApplication } from "../application/application.js";
@@ -20,6 +21,10 @@ import { adoptSemanticCache } from '../application/cache-adoption.js';
 import { SemanticHydrationError } from '../application/hydration-failure.js';
 import { GraphIdentityConflictError } from '../graph/identity-preflight.js';
 import { runDocumentCoverage } from './document-coverage.js';
+import { graphNeighborsRequestFromArgs } from './graph-exploration.js';
+import { graphPathsRequestFromArgs } from './graph-paths.js';
+import { graphCompatibilityRequestFromArgs } from './graph-compatibility.js';
+import { codeCoverageRequestFromArgs } from './code-coverage.js';
 function valueAfter(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -98,7 +103,7 @@ function formatHydrationPlan(plan) {
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || !args.length) {
-        process.stdout.write('weftlet documents plan|init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\ndocuments plan --entry <document> [--entry <document>] [--root <path>] [--document-policy <json-file>] [--ref <commit>] [--json] previews prospective committed link coverage; it does not change hydration inputs or estimate model/cache work. Source classification/ownership completeness is separate from traversal readiness. The preview policy is an operation input. Set documentTraversal in configuration to activate traversal hydration; hydrate --plan describes its execution inputs. Safety limits: --max-read-documents, --max-read-bytes, --max-document-bytes.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Traversal coverage and role ambiguity block new model work; direct-source selection retains its existing behavior.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\nhydrate|overlay --validation-details explicitly includes local node/fact identities, extractor names and source citations in identity-conflict errors; default reports use opaque references. This flag writes no diagnostic file. Use --json --quiet for structured identity-conflict stderr and empty failure stdout. Validation timings report phase boundaries, not a live heartbeat or percentage.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
+        process.stdout.write('weftlet mappings plan|mappings propose|mappings read|documents plan|init|config show|config validate|doctor|hydrate|cache adopt|overlay|impact scan|graph neighbors|graph paths|graph compatibility|graph coverage|sparql|validate|govern|visualize|diagnostics show|invariant check|clean-compare|ontology compile\nmappings plan|propose --request <json-file> [--allow-model for propose] previews or runs one opt-in proposal; mappings read --snapshot <id> --key <key> reads saved unreviewed results.\nUse --config <file>; queries accept --snapshot <id>. impact scan accepts --changed-file, --capability, --max-facts, --max-depth, --continuation.\ngraph neighbors --snapshot <id> --node <exact-id> [--direction incoming|outgoing|both] [--predicate <relation>] [--max-facts <1..200>] [--continuation <token>] [--json] reads one-hop saved evidence; repeat --predicate to select multiple relations.\ngraph paths --snapshot <id> --from <exact-id> --to <exact-id> [--direction incoming|outgoing|both] [--predicate <relation>] [--max-depth <1..32>] [--max-paths <1..20>] [--max-steps <1..10000>] [--continuation <token>] [--json] explores cited simple paths; incomplete searches report frontier and limits.\ngraph coverage --snapshot <id> [--project <exact-package-root>] [--max-items <1..200>] [--continuation <token>] [--json] pages saved package/file coverage; absence or zero references is not proof of no impact.\ngraph compatibility --snapshot <id> --producer-fact <assertion-id> --consumer-fact <assertion-id> [--json] compares two documented numeric obligations; advisory only, with explicit unknowns and no implementation or CI verdict.\ndocuments plan --entry <document> [--entry <document>] [--root <path>] [--document-policy <json-file>] [--ref <commit>] [--json] previews prospective committed link coverage; it does not change hydration inputs or estimate model/cache work. Source classification/ownership completeness is separate from traversal readiness. The preview policy is an operation input. Set documentTraversal in configuration to activate traversal hydration; hydrate --plan describes its execution inputs. Safety limits: --max-read-documents, --max-read-bytes, --max-document-bytes.\nhydrate --plan [--json] [--ref <commit>] [--force-semantic] previews scope, cache and budgets without model calls or graph writes. Traversal coverage and role ambiguity block new model work; direct-source selection retains its existing behavior.\nhydrate --json --quiet emits structured semantic failures on stderr with no progress lines; failure stdout stays empty. hydrate --plan maps opaque source IDs to local document paths.\nhydrate|overlay --validation-details explicitly includes local node/fact identities, extractor names and source citations in identity-conflict errors; default reports use opaque references. This flag writes no diagnostic file. Use --json --quiet for structured identity-conflict stderr and empty failure stdout. Validation timings report phase boundaries, not a live heartbeat or percentage.\ncache adopt --from-config <previous.json> [--config <current.json>] [--ref <commit>] [--dry-run] returns JSON and copies only validated compatible artifacts, without model calls or snapshot writes. --dry-run performs no cache writes. Agent configurations accept the same --owner-doc, --task and --capability selection as hydrate.\ninit [--yes] [--directory <project>] [--config <file>] [--repository-id <id>] [--code-root <path>] [--semantic-source <path>] [--evidence-root <path>] [--model <name>] [--no-gitignore]\nSource flags may be repeated. init never overwrites an existing config. See README.md for examples.\n');
         return;
     }
     if (await runDocumentCoverage(args, defaultConfigPath))
@@ -164,6 +169,13 @@ async function main() {
     }
     const application = await createContextGraphApplication(configPath);
     const [command, subcommand] = args;
+    if (command === 'mappings') {
+        const report = await runMappingsCommand(application.mappingProposalService, args.slice(1));
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        if ('ready' in report && !report.ready)
+            process.exitCode = 1;
+        return;
+    }
     if (command === 'sparql' || command === 'validate') {
         const id = valueAfter(args, '--snapshot');
         const snapshot = id ? await application.snapshotStore.read(id) :
@@ -235,6 +247,26 @@ async function main() {
         process.stdout.write(args.includes('--json') ? `${JSON.stringify(pack, null, 2)}\n` : `${pack.markdown}\n`);
         return;
     }
+    if (command === 'graph' && subcommand === 'compatibility') {
+        const result = await application.compatibilityService.assess(graphCompatibilityRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
+    if (command === 'graph' && subcommand === 'coverage') {
+        const result = await application.codeCoverageService.coverage(codeCoverageRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
+    if (command === 'graph' && subcommand === 'paths') {
+        const result = await application.pathService.paths(graphPathsRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
+    if (command === 'graph' && subcommand === 'neighbors') {
+        const result = await application.explorationService.neighbors(graphNeighborsRequestFromArgs(args.slice(2)));
+        process.stdout.write(`${args.includes('--json') ? JSON.stringify(result, null, 2) : result.markdown}\n`);
+        return;
+    }
     if (command === 'visualize') {
         const outputPath = valueAfter(args, '--output');
         if (!outputPath)

package/dist/interfaces/code-coverage.d.ts

@@ -0,0 +1,46 @@
+import type { CodeCoverageService } from '@weftlet/core';
+export declare const graphCoverageTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            projectRoot: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            maxItems: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleCodeCoverage(service: CodeCoverageService, value: unknown): Promise<import("@weftlet/core").CodeCoverageReport>;
+export declare function codeCoverageRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    projectRoot?: string | undefined;
+    snapshotId: string;
+    maxItems: number;
+};

package/dist/interfaces/code-coverage.js

@@ -0,0 +1,18 @@
+import { parseCodeCoverageRequest } from '../graph/code-coverage-request.js';
+import { parseGraphQueryArgs } from './graph-query-args.js';
+export const graphCoverageTool = {
+    name: 'graph.coverage',
+    description: 'Inspect saved TypeScript-family source coverage. Page package boundaries, then select an exact projectRoot to page files. Distinguishes code-root selection, requested index entries, observed SCIP documents, cross-package references and unresolved evidence. Missing or zero observations never prove no impact. Does not rebuild evidence.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['snapshotId'], properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 }, projectRoot: { type: 'string', minLength: 1, maxLength: 8192 },
+            maxItems: { type: 'integer', minimum: 1, maximum: 200, default: 50 }, continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        } }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleCodeCoverage(service, value) {
+    return service.coverage(parseCodeCoverageRequest(value));
+}
+export function codeCoverageRequestFromArgs(args) {
+    return parseCodeCoverageRequest(parseGraphQueryArgs(args, 'coverage', {
+        '--snapshot': 'snapshotId', '--project': 'projectRoot', '--max-items': 'maxItems', '--continuation': 'continuation',
+    }));
+}

package/dist/interfaces/graph-compatibility.d.ts

@@ -0,0 +1,35 @@
+import type { ContractCompatibilityService } from '@weftlet/core';
+export declare const graphCompatibilityTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            producerFactId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            consumerFactId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphCompatibility(service: ContractCompatibilityService, value: unknown): Promise<import("@weftlet/core").ContractCompatibilityReport>;
+export declare function graphCompatibilityRequestFromArgs(args: readonly string[]): import("@weftlet/core").ContractCompatibilityRequest;

package/dist/interfaces/graph-compatibility.js

@@ -0,0 +1,21 @@
+import { parseContractCompatibilityRequest } from '../graph/compatibility-request.js';
+import { parseGraphQueryArgs } from './graph-query-args.js';
+export const graphCompatibilityTool = {
+    name: 'graph.compatibility',
+    description: 'Compare two exact cited producer/consumer numeric obligations from a saved snapshot. Reports subset, insufficient guarantee, disjoint constraints, required revalidation or unknown. Advisory only: never proves implementation, current-diff validity or a CI policy violation. Discover assertion IDs with graph.neighbors.',
+    inputSchema: { type: 'object', additionalProperties: false,
+        required: ['snapshotId', 'producerFactId', 'consumerFactId'], properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            producerFactId: { type: 'string', minLength: 1, maxLength: 8192 },
+            consumerFactId: { type: 'string', minLength: 1, maxLength: 8192 },
+        } },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphCompatibility(service, value) {
+    return service.assess(parseContractCompatibilityRequest(value));
+}
+export function graphCompatibilityRequestFromArgs(args) {
+    return parseContractCompatibilityRequest(parseGraphQueryArgs(args, 'compatibility', {
+        '--snapshot': 'snapshotId', '--producer-fact': 'producerFactId', '--consumer-fact': 'consumerFactId',
+    }));
+}

package/dist/interfaces/graph-exploration.d.ts

@@ -0,0 +1,59 @@
+import { type GraphExplorationService } from '@weftlet/core';
+export declare const graphNeighborsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            nodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            direction: {
+                type: string;
+                enum: string[];
+            };
+            predicates: {
+                type: string;
+                maxItems: 16;
+                items: {
+                    type: string;
+                    enum: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+                };
+            };
+            maxFacts: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphNeighbors(service: GraphExplorationService, value: unknown): Promise<import("@weftlet/core").GraphNeighborhood>;
+export declare function graphNeighborsRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    nodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxFacts: number;
+};

package/dist/interfaces/graph-exploration.js

@@ -0,0 +1,27 @@
+import { parseGraphQueryArgs } from './graph-query-args.js';
+import { graphPredicates } from '@weftlet/core';
+import { parseGraphNeighborsRequest } from '../graph/neighborhood-request.js';
+export const graphNeighborsTool = {
+    name: 'graph.neighbors',
+    description: 'Look up an exact node ID in an explicit saved snapshot and page through its cited one-hop relationships. Follow returned neighbor IDs to explore further; no hydration or model calls.',
+    inputSchema: {
+        type: 'object', additionalProperties: false, required: ['snapshotId', 'nodeId'],
+        properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            nodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            direction: { type: 'string', enum: ['incoming', 'outgoing', 'both'] },
+            predicates: { type: 'array', maxItems: graphPredicates.length, items: { type: 'string', enum: [...graphPredicates] } },
+            maxFacts: { type: 'integer', minimum: 1, maximum: 200 },
+            continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        },
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphNeighbors(service, value) {
+    return service.neighbors(parseGraphNeighborsRequest(value));
+}
+export function graphNeighborsRequestFromArgs(args) {
+    const flags = { '--snapshot': 'snapshotId', '--node': 'nodeId',
+        '--direction': 'direction', '--predicate': 'predicates', '--max-facts': 'maxFacts', '--continuation': 'continuation' };
+    return parseGraphNeighborsRequest(parseGraphQueryArgs(args, 'neighbors', flags));
+}

package/dist/interfaces/graph-paths.d.ts

@@ -0,0 +1,77 @@
+import { type GraphPathQueryService } from '@weftlet/core';
+export declare const graphPathsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            fromNodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            toNodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            direction: {
+                type: string;
+                enum: string[];
+            };
+            predicates: {
+                type: string;
+                maxItems: 16;
+                items: {
+                    type: string;
+                    enum: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+                };
+            };
+            maxDepth: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxPaths: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxSteps: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphPaths(service: GraphPathQueryService, value: unknown): Promise<import("@weftlet/core").GraphPaths>;
+export declare function graphPathsRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxDepth: number;
+    maxPaths: number;
+    maxSteps: number;
+};

package/dist/interfaces/graph-paths.js

@@ -0,0 +1,31 @@
+import { parseGraphQueryArgs } from './graph-query-args.js';
+import { graphPredicates } from '@weftlet/core';
+import { parseGraphPathsRequest } from '../graph/path-request.js';
+export const graphPathsTool = {
+    name: 'graph.paths',
+    description: 'Explore simple cited paths between exact node IDs in an explicit saved snapshot. Depth-first assertion order, not shortest/causal paths. Follow continuation with identical selectors; inspect depth/work limits and unexplored frontier. No hydration or model calls.',
+    inputSchema: {
+        type: 'object', additionalProperties: false, required: ['snapshotId', 'fromNodeId', 'toNodeId'],
+        properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            fromNodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            toNodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            direction: { type: 'string', enum: ['incoming', 'outgoing', 'both'] },
+            predicates: { type: 'array', maxItems: graphPredicates.length, items: { type: 'string', enum: [...graphPredicates] } },
+            maxDepth: { type: 'integer', minimum: 1, maximum: 32 },
+            maxPaths: { type: 'integer', minimum: 1, maximum: 20 },
+            maxSteps: { type: 'integer', minimum: 1, maximum: 10000 },
+            continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        },
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphPaths(service, value) {
+    return service.paths(parseGraphPathsRequest(value));
+}
+export function graphPathsRequestFromArgs(args) {
+    const flags = { '--snapshot': 'snapshotId', '--from': 'fromNodeId', '--to': 'toNodeId',
+        '--direction': 'direction', '--predicate': 'predicates', '--max-depth': 'maxDepth', '--max-paths': 'maxPaths',
+        '--max-steps': 'maxSteps', '--continuation': 'continuation' };
+    return parseGraphPathsRequest(parseGraphQueryArgs(args, 'paths', flags));
+}

package/dist/interfaces/graph-query-args.d.ts

@@ -0,0 +1,2 @@
+/** Shared flag grammar for exact-ID graph queries; semantic validation stays in the query layer. */
+export declare function parseGraphQueryArgs(args: readonly string[], operation: string, flags: Readonly<Record<string, string>>): Record<string, unknown>;

package/dist/interfaces/graph-query-args.js

@@ -0,0 +1,25 @@
+/** Shared flag grammar for exact-ID graph queries; semantic validation stays in the query layer. */
+export function parseGraphQueryArgs(args, operation, flags) {
+    const values = {};
+    for (let index = 0; index < args.length; index++) {
+        const flag = args[index];
+        if (flag === '--json')
+            continue;
+        if (flag !== '--config' && !Object.hasOwn(flags, flag))
+            throw new Error(`Unknown graph ${operation} argument: ${flag}`);
+        const value = args[++index];
+        if (value === undefined || value.startsWith('--'))
+            throw new Error(`Missing value for ${flag}`);
+        if (flag === '--config')
+            continue;
+        const key = flags[flag];
+        if (key === 'predicates')
+            values[key] = [...(values[key] ?? []), value];
+        else {
+            if (Object.hasOwn(values, key))
+                throw new Error(`Repeated graph ${operation} argument: ${flag}`);
+            values[key] = key.startsWith('max') ? Number(value) : value;
+        }
+    }
+    return values;
+}