@weftlet/toolkit 0.0.0-stage → 0.1.0

package/dist/extraction/document.js

@@ -0,0 +1,54 @@
+import { sha256, stableJson } from "../infrastructure/util.js";
+const identity = { id: 'document-linker', version: '1.0.0' };
+const repositoryPathPattern = /\b[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+/g;
+function documentNode(path) {
+    return { id: `document:${path}`, kind: 'Document', label: path };
+}
+export function linkSemanticDocuments(context, hydrated, trackedPaths = []) {
+    const facts = [];
+    const makeFact = (source, subject, predicate, object) => ({
+        id: sha256(stableJson({ source: source.path, subject: subject.id, predicate, object: object.id })),
+        subject,
+        predicate,
+        object,
+        provenance: {
+            path: source.path,
+            startLine: 1,
+            endLine: Math.max(1, source.content.split('\n').length),
+            digest: source.digest,
+            commitSha: context.commitSha,
+        },
+        extractor: identity,
+        confidence: 1,
+        authority: 'inferred',
+        extractionReview: predicate === 'contains' ? 'unreviewed' : 'deterministic',
+        snapshotId: context.snapshotId,
+    });
+    for (const { source, artifact } of hydrated) {
+        const owner = documentNode(source.path);
+        const nodes = new Map(artifact.facts.flatMap((fact) => [fact.subject, fact.object]).map((node) => [node.id, node]));
+        for (const node of nodes.values())
+            facts.push(makeFact(source, owner, 'contains', node));
+        const references = [
+            ...new Set((source.content.match(repositoryPathPattern) ?? []).map((path) => path.replace(/[.,;:]+$/, ''))),
+        ].sort();
+        const resolvedReferences = new Set();
+        for (const path of references) {
+            if (trackedPaths.includes(path) || /\.(?:md|mdx|txt)$/i.test(path)) {
+                resolvedReferences.add(path);
+                continue;
+            }
+            for (const trackedPath of trackedPaths) {
+                if (trackedPath.startsWith(`${path}/`))
+                    resolvedReferences.add(trackedPath);
+            }
+        }
+        for (const path of [...resolvedReferences].sort()) {
+            const target = /\.(?:md|mdx|txt)$/i.test(path)
+                ? documentNode(path)
+                : { id: `component:file:${path}`, kind: 'Component', label: path };
+            facts.push(makeFact(source, owner, 'references', target));
+        }
+    }
+    return facts;
+}

package/dist/extraction/ontology.d.ts

@@ -0,0 +1,32 @@
+import type { ContextGraphConfig } from "../configuration/config.js";
+import type { SemanticArtifact, ExtractionContext } from "@weftlet/core";
+import type { GitRepository } from "../repository/git.js";
+export interface OntologyCompileResult {
+    readonly root: string;
+    readonly rdfFiles: readonly string[];
+    readonly digest: string;
+}
+export interface OntologyCompiler {
+    checkReady?(): Promise<void>;
+    compile(snapshotId: string, artifacts: readonly SemanticArtifact[], context?: ExtractionContext): Promise<OntologyCompileResult>;
+}
+type DockerProbe = (cwd: string) => Promise<string>;
+export declare function requireLinuxDocker(cwd: string, probe?: DockerProbe): Promise<void>;
+export declare function dockerHostUserArguments(): readonly string[];
+export declare function compileOntologyAtExactCheckout(repository: GitRepository, compiler: OntologyCompiler, ref: string): Promise<OntologyCompileResult>;
+export declare function renderGeneratedOntologyRoot(artifacts: readonly SemanticArtifact[], usedVocabularyIris?: readonly string[], includedDescriptionIris?: readonly string[]): string;
+export declare class OpenCaesarOntologyCompiler implements OntologyCompiler {
+    private readonly config;
+    private readonly repositoryRoot;
+    private readonly storageRoot;
+    constructor(config: ContextGraphConfig['ontology'], repositoryRoot: string, storageRoot: string);
+    checkReady(): Promise<void>;
+    compile(snapshotId: string, artifacts: readonly SemanticArtifact[], context?: ExtractionContext): Promise<OntologyCompileResult>;
+}
+/** Default compiler preserves asserted semantics without Java, Docker, or an OWL reasoner. */
+export declare class DirectRdfOntologyCompiler implements OntologyCompiler {
+    private readonly storageRoot;
+    constructor(storageRoot: string);
+    compile(snapshotId: string, artifacts: readonly SemanticArtifact[]): Promise<OntologyCompileResult>;
+}
+export {};

package/dist/extraction/ontology.js

@@ -0,0 +1,164 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { randomUUID } from 'node:crypto';
+import { withCommittedTree } from "../repository/committed-tree.js";
+import { DataFactory, Store, Writer } from 'n3';
+import { CG, nodeIri } from "../graph/rdf.js";
+import { cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { runProcess } from "../infrastructure/process.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+const probeDocker = async (cwd) => {
+    const { stdout } = await promisify(execFile)('docker', ['info', '--format', '{{.OSType}}'], {
+        cwd,
+        encoding: 'utf8',
+        timeout: 10_000,
+        maxBuffer: 64 * 1024,
+        windowsHide: true,
+    });
+    return stdout;
+};
+export async function requireLinuxDocker(cwd, probe = probeDocker) {
+    try {
+        if ((await probe(cwd)).trim() !== 'linux')
+            throw new Error('Linux engine required');
+    }
+    catch (cause) {
+        throw new Error('Context graph Docker preflight failed: a responsive Linux Docker engine is required for openCAESAR. Start Docker Desktop (Linux containers) or repair the selected Docker context, then retry.', { cause });
+    }
+}
+export function dockerHostUserArguments() {
+    if (process.platform === 'win32' || !process.getuid || !process.getgid)
+        return [];
+    return [
+        '--user',
+        `${process.getuid()}:${process.getgid()}`,
+        '--env',
+        'GRADLE_USER_HOME=/workspace/.gradle',
+    ];
+}
+export async function compileOntologyAtExactCheckout(repository, compiler, ref) {
+    const commitSha = await repository.resolveRef(ref);
+    await repository.requireExactCleanCommit(commitSha);
+    return compiler.compile(commitSha, []);
+}
+export function renderGeneratedOntologyRoot(artifacts, usedVocabularyIris = [], includedDescriptionIris = []) {
+    const generatedImports = artifacts
+        .filter((artifact) => artifact.oml.trim())
+        .sort((left, right) => left.key.localeCompare(right.key))
+        .map((artifact) => `  includes <https://context-graph.dev/generated/${artifact.key}#>`);
+    const vocabularyImports = ['https://context-graph.dev/core#', ...usedVocabularyIris]
+        .filter((iri, index, values) => values.indexOf(iri) === index)
+        .map((iri) => `  uses <${iri}>`);
+    const staticImports = [...includedDescriptionIris].sort().map((iri) => `  includes <${iri}>`);
+    return [
+        'description bundle <https://context-graph.dev/generated/snapshot#> as snapshot {',
+        ...vocabularyImports,
+        ...staticImports,
+        ...generatedImports,
+        '}',
+    ].join('\n');
+}
+async function listRdfFiles(root) {
+    const files = [];
+    async function visit(path) {
+        for (const entry of await readdir(path, { withFileTypes: true })) {
+            const child = join(path, entry.name);
+            if (entry.isDirectory())
+                await visit(child);
+            else if (/\.(ttl|nt|rdf|owl)$/i.test(entry.name))
+                files.push(child);
+        }
+    }
+    await visit(root);
+    return files.sort();
+}
+export class OpenCaesarOntologyCompiler {
+    config;
+    repositoryRoot;
+    storageRoot;
+    constructor(config, repositoryRoot, storageRoot) {
+        this.config = config;
+        this.repositoryRoot = repositoryRoot;
+        this.storageRoot = storageRoot;
+    }
+    checkReady() {
+        return requireLinuxDocker(this.repositoryRoot);
+    }
+    async compile(snapshotId, artifacts, context) {
+        if (context) {
+            return withCommittedTree(context.repositoryRoot, context.commitSha, (root) => new OpenCaesarOntologyCompiler(this.config, root, this.storageRoot).compile(snapshotId, artifacts));
+        }
+        await this.checkReady();
+        if (!this.config.projectPath || !this.config.containerImage) {
+            throw new Error('Optional openCAESAR requires projectPath and containerImage');
+        }
+        const source = resolve(this.repositoryRoot, this.config.projectPath);
+        const work = join(this.storageRoot, 'work', `ontology-${snapshotId}-${randomUUID()}`);
+        await rm(work, { recursive: true, force: true });
+        await mkdir(dirname(work), { recursive: true });
+        const sourceBuild = join(source, 'build');
+        await cp(source, work, {
+            recursive: true,
+            filter: (path) => path !== sourceBuild && !path.startsWith(`${sourceBuild}${sep}`),
+        });
+        const generatedRoot = join(work, 'src', 'oml', 'context-graph.dev', 'generated');
+        await mkdir(generatedRoot, { recursive: true });
+        for (const artifact of artifacts) {
+            if (!artifact.oml.trim())
+                continue;
+            await writeFile(join(generatedRoot, `${artifact.key}.oml`), `${artifact.oml.trim()}\n`, 'utf8');
+        }
+        await writeFile(join(generatedRoot, 'snapshot.oml'), `${renderGeneratedOntologyRoot(artifacts, this.config.usedVocabularyIris, this.config.includedDescriptionIris)}\n`, 'utf8');
+        const dockerPath = work.replace(/\\/g, '/');
+        await runProcess('docker', [
+            'run',
+            '--rm',
+            ...dockerHostUserArguments(),
+            '-v',
+            `${dockerPath}:/workspace`,
+            '-w',
+            '/workspace',
+            this.config.containerImage,
+            'gradle',
+            '--no-daemon',
+            'clean',
+            'oml2owl',
+        ], this.repositoryRoot);
+        const rdfRoot = join(work, 'build', 'rdf');
+        const rdfFiles = await listRdfFiles(rdfRoot);
+        if (rdfFiles.length === 0)
+            throw new Error('openCAESAR produced no RDF files');
+        const digestParts = await Promise.all(rdfFiles.map(async (path) => ({
+            path: relative(rdfRoot, path),
+            content: await readFile(path, 'utf8'),
+        })));
+        return { root: rdfRoot, rdfFiles, digest: sha256(stableJson(digestParts)) };
+    }
+}
+/** Default compiler preserves asserted semantics without Java, Docker, or an OWL reasoner. */
+export class DirectRdfOntologyCompiler {
+    storageRoot;
+    constructor(storageRoot) {
+        this.storageRoot = storageRoot;
+    }
+    async compile(snapshotId, artifacts) {
+        const { namedNode } = DataFactory;
+        const dataset = new Store();
+        for (const artifact of [...artifacts].sort((a, b) => a.key.localeCompare(b.key))) {
+            for (const fact of artifact.facts) {
+                dataset.addQuad(namedNode(nodeIri(fact.subject.id)), namedNode(CG + fact.predicate), namedNode(nodeIri(fact.object.id)));
+            }
+        }
+        const writer = new Writer({ format: 'N-Triples' });
+        writer.addQuads(dataset.getQuads(null, null, null, null));
+        const text = await new Promise((accept, reject) => writer.end((error, value) => error ? reject(error) : accept(value)));
+        const content = text.split('\n').filter(Boolean).sort().join('\n') + '\n';
+        const root = join(this.storageRoot, 'work', `rdf-${snapshotId}-${randomUUID()}`);
+        await mkdir(root, { recursive: true });
+        const path = join(root, 'semantic.nt');
+        await writeFile(path, content);
+        return { root, rdfFiles: [path], digest: sha256(content) };
+    }
+}

package/dist/extraction/providers.d.ts

@@ -0,0 +1,8 @@
+import type { ContextGraphConfig } from "../configuration/config.js";
+import { type SemanticExtractor, type SemanticRunOptions } from "./semantic.js";
+export interface SemanticProviderModule {
+    /** Trusted local code. Providers must honor abort signals and never log private inputs. */
+    createSemanticExtractor(config: ContextGraphConfig['semantic'], options?: SemanticRunOptions): SemanticExtractor | Promise<SemanticExtractor>;
+}
+/** Lazy loading ensures a missing provider cannot disable saved-evidence queries. */
+export declare function createSemanticExtractor(config: ContextGraphConfig['semantic'], repositoryRoot: string): SemanticExtractor;

package/dist/extraction/providers.js

@@ -0,0 +1,58 @@
+import { CodexCliSemanticExtractor, SemanticProviderError } from "./semantic.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+import { resolveConsumerModule } from "../infrastructure/module-resolution.js";
+/** Lazy loading ensures a missing provider cannot disable saved-evidence queries. */
+export function createSemanticExtractor(config, repositoryRoot) {
+    if (config.provider === 'codex-cli')
+        return new CodexCliSemanticExtractor(config);
+    const modulePath = config.providerModule;
+    const identity = `${config.providerIdentity}:${sha256(stableJson(config))}:contract-v2`;
+    let extractor;
+    return {
+        identity,
+        async extract(source, context, options = {}) {
+            const deadline = new AbortController();
+            const timer = setTimeout(() => deadline.abort(new SemanticProviderError('timeout', 'Semantic module execution timed out')), options.timeoutMs ?? config.timeoutMs ?? 120_000);
+            const signal = AbortSignal.any([deadline.signal,
+                ...(options.signal ? [options.signal] : [])]);
+            const abortError = () => deadline.signal.aborted ? deadline.signal.reason :
+                new SemanticProviderError('cancelled', 'Semantic module execution cancelled');
+            const checkpoint = () => { if (signal.aborted)
+                throw abortError(); };
+            let onAbort = () => { };
+            try {
+                return await Promise.race([
+                    new Promise((_resolve, reject) => {
+                        onAbort = () => reject(abortError());
+                        signal.addEventListener('abort', onAbort, { once: true });
+                        if (signal.aborted)
+                            onAbort();
+                    }),
+                    Promise.resolve().then(async () => {
+                        checkpoint();
+                        if (!extractor) {
+                            const module = await import(resolveConsumerModule(modulePath, repositoryRoot));
+                            checkpoint();
+                            if (typeof module.createSemanticExtractor !== 'function')
+                                throw new Error('Provider module must export createSemanticExtractor(config)');
+                            const candidate = await module.createSemanticExtractor(config, { ...options, signal });
+                            checkpoint();
+                            if (candidate?.identity !== config.providerIdentity || typeof candidate.extract !== 'function') {
+                                throw new Error('Provider identity/contract does not match configuration');
+                            }
+                            extractor = candidate;
+                        }
+                        checkpoint();
+                        const result = await extractor.extract(source, context, { ...options, signal });
+                        checkpoint();
+                        return result;
+                    }),
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+                signal.removeEventListener('abort', onAbort);
+            }
+        },
+    };
+}

package/dist/extraction/runtime-evidence.d.ts

@@ -0,0 +1,2 @@
+import type { ExtractionContext, GraphFact, RuntimeTraceReference } from "@weftlet/core";
+export declare function runtimeEvidenceFacts(context: ExtractionContext, references: readonly RuntimeTraceReference[]): readonly GraphFact[];

package/dist/extraction/runtime-evidence.js

@@ -0,0 +1,84 @@
+import { sha256, stableJson } from "../infrastructure/util.js";
+const extractor = { id: 'otlp-runtime-evidence', version: '1.0.0' };
+function graphId(prefix, value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._:-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return `${prefix}:${normalized || 'unknown'}`;
+}
+function capabilityNode(value) {
+    const canonical = value.replace(/^(?:[^:]+:)?capability:/, '');
+    return {
+        id: graphId('capability', canonical),
+        kind: 'Capability',
+        label: canonical,
+        attributes: { evidenceLayer: 'observed' },
+    };
+}
+export function runtimeEvidenceFacts(context, references) {
+    const facts = [];
+    for (const reference of references) {
+        if (!reference.accepted || !reference.capability)
+            continue;
+        const service = {
+            id: graphId('component:runtime-service', reference.serviceName),
+            kind: 'Component',
+            label: reference.serviceName,
+            attributes: {
+                evidenceLayer: 'observed',
+                serviceVersion: reference.serviceVersion,
+                ...(reference.environment ? { environment: reference.environment } : {}),
+            },
+        };
+        const capability = capabilityNode(reference.capability);
+        const evidence = {
+            id: `evidence:runtime:${reference.traceId}:${reference.spanId}`,
+            kind: 'Evidence',
+            label: `Runtime trace ${reference.traceId.slice(0, 12)}`,
+            attributes: {
+                evidenceLayer: 'observed',
+                traceId: reference.traceId,
+                ...(reference.observedAt ? { observedAt: reference.observedAt } : {}),
+            },
+        };
+        const workflow = reference.operation
+            ? {
+                id: graphId('workflow:runtime-operation', reference.operation),
+                kind: 'Workflow',
+                label: reference.operation,
+                attributes: { evidenceLayer: 'observed' },
+            }
+            : undefined;
+        const provenance = {
+            path: reference.sourcePath,
+            startLine: 1,
+            endLine: 1,
+            digest: reference.sourceDigest,
+            commitSha: context.commitSha,
+        };
+        const relationships = [
+            { subject: service, predicate: 'realizes', object: capability },
+            { subject: capability, predicate: 'verifiedBy', object: evidence },
+            ...(workflow
+                ? [
+                    { subject: workflow, predicate: 'realizes', object: capability },
+                    { subject: workflow, predicate: 'routesThrough', object: service },
+                    { subject: workflow, predicate: 'verifiedBy', object: evidence },
+                ]
+                : []),
+        ];
+        for (const relationship of relationships) {
+            facts.push({
+                id: sha256(stableJson({ reference, relationship })),
+                ...relationship,
+                provenance,
+                extractor,
+                confidence: 1,
+                snapshotId: context.snapshotId,
+            });
+        }
+    }
+    return facts;
+}

package/dist/extraction/semantic-citations.d.ts

@@ -0,0 +1,7 @@
+/** Display line numbers without changing the source bytes used for provenance. */
+export declare function numberedSemanticSource(content: string): string;
+export declare function semanticCitationSchema(lineCount: number): object;
+export declare function assertSemanticCitation(citation: {
+    readonly startLine: number;
+    readonly endLine: number;
+}, path: string, lineCount: number, location: string): void;

package/dist/extraction/semantic-citations.js

@@ -0,0 +1,27 @@
+/** Display line numbers without changing the source bytes used for provenance. */
+export function numberedSemanticSource(content) {
+    return content
+        .split('\n')
+        .map((line, index) => `${index + 1}|${line.replace(/\r$/, '')}`)
+        .join('\n');
+}
+export function semanticCitationSchema(lineCount) {
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['startLine', 'endLine'],
+        properties: {
+            startLine: { type: 'integer', minimum: 1, maximum: lineCount },
+            endLine: { type: 'integer', minimum: 1, maximum: lineCount },
+        },
+    };
+}
+export function assertSemanticCitation(citation, path, lineCount, location) {
+    if (!Number.isInteger(citation.startLine) ||
+        !Number.isInteger(citation.endLine) ||
+        citation.startLine < 1 ||
+        citation.endLine < citation.startLine ||
+        citation.endLine > lineCount) {
+        throw new Error(`Invalid source citation for ${path}: ${location} cites ${citation.startLine}-${citation.endLine}; expected integer lines 1-${lineCount} with startLine <= endLine`);
+    }
+}

package/dist/extraction/semantic-process.d.ts

@@ -0,0 +1,11 @@
+export interface SemanticRunOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export declare class SemanticProviderError extends Error {
+    readonly code: 'timeout' | 'cancelled' | 'unavailable' | 'exit' | 'invalid-output';
+    readonly retryable: boolean;
+    constructor(code: 'timeout' | 'cancelled' | 'unavailable' | 'exit' | 'invalid-output', message: string, retryable?: boolean);
+}
+/** Intentionally never forwards provider stderr, prompts or environment values. */
+export declare function runSemanticProcess(command: string, args: readonly string[], cwd: string, prompt: string, environment: Record<string, string | undefined>, options?: SemanticRunOptions): Promise<void>;

package/dist/extraction/semantic-process.js

@@ -0,0 +1,68 @@
+import { spawn } from 'node:child_process';
+export class SemanticProviderError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = 'SemanticProviderError';
+    }
+}
+/** Intentionally never forwards provider stderr, prompts or environment values. */
+export function runSemanticProcess(command, args, cwd, prompt, environment, options = {}) {
+    if (options.signal?.aborted) {
+        return Promise.reject(new SemanticProviderError('cancelled', 'Semantic extraction cancelled'));
+    }
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [...args], {
+            cwd, env: environment, stdio: ['pipe', 'ignore', 'ignore'],
+            windowsHide: true, detached: process.platform !== 'win32',
+        });
+        let failure;
+        let killTimer;
+        const kill = (signal) => {
+            try {
+                if (process.platform !== 'win32' && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch { /* The process may have already exited. */ }
+        };
+        const stop = (code) => {
+            if (failure)
+                return;
+            failure = new SemanticProviderError(code, `Semantic extraction ${code}`);
+            kill('SIGTERM');
+            killTimer = setTimeout(() => kill('SIGKILL'), 1000);
+            killTimer.unref();
+        };
+        const cancel = () => stop('cancelled');
+        options.signal?.addEventListener('abort', cancel, { once: true });
+        const timer = setTimeout(() => stop('timeout'), options.timeoutMs ?? 120_000);
+        const cleanup = () => {
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.signal?.removeEventListener('abort', cancel);
+        };
+        child.once('error', () => {
+            cleanup();
+            reject(new SemanticProviderError('unavailable', 'Semantic provider executable could not start'));
+        });
+        child.once('close', (code) => {
+            cleanup();
+            if (failure)
+                reject(failure);
+            else if (code === 0)
+                resolve();
+            else
+                reject(new SemanticProviderError('exit', `Semantic provider exited with status ${code}`, code === 75));
+        });
+        child.stdin.on('error', () => { });
+        child.stdin.end(prompt);
+        if (options.signal?.aborted)
+            cancel();
+    });
+}

package/dist/extraction/semantic.d.ts

@@ -0,0 +1,73 @@
+import { type CodexLoginProbe, type SemanticCommandEnvironment } from './codex-auth.js';
+export { semanticCommandEnvironment } from './codex-auth.js';
+export type { SemanticCommandEnvironment } from './codex-auth.js';
+import { type SemanticRunOptions } from "./semantic-process.js";
+export { SemanticProviderError } from "./semantic-process.js";
+export type { SemanticRunOptions } from "./semantic-process.js";
+import type { ExtractionContext, GraphNodeKind, GraphPredicate, SemanticArtifact, SemanticSource, DiagnosticKind } from "@weftlet/core";
+import type { ContextGraphConfig } from "../configuration/config.js";
+import type { SemanticArtifactStore } from "../storage/storage.js";
+export interface ExtractedAssertion {
+    readonly subject: {
+        readonly id: string;
+        readonly kind: GraphNodeKind;
+        readonly label: string;
+    };
+    readonly predicate: GraphPredicate;
+    readonly object: {
+        readonly id: string;
+        readonly kind: GraphNodeKind;
+        readonly label: string;
+    };
+    readonly citation: {
+        readonly startLine: number;
+        readonly endLine: number;
+    };
+    readonly confidence: number;
+}
+export interface SemanticOutput {
+    readonly assertions: readonly ExtractedAssertion[];
+    readonly oml: string;
+    readonly unresolvedMappings?: readonly string[];
+    readonly diagnostics?: readonly {
+        readonly kind: Exclude<DiagnosticKind, 'runtimeGaps' | 'drift'>;
+        readonly reason: string;
+        readonly citation: {
+            readonly startLine: number;
+            readonly endLine: number;
+        };
+        readonly relatedNodeIds: readonly string[];
+    }[];
+}
+export interface SemanticExtractionResult {
+    readonly parsed: SemanticOutput;
+    readonly rawModelOutput: string;
+}
+export interface SemanticExtractor {
+    readonly identity: string;
+    extract(source: SemanticSource, context: ExtractionContext, options?: SemanticRunOptions): Promise<SemanticExtractionResult>;
+}
+export interface SemanticCommandRunner {
+    run(command: string, args: readonly string[], cwd: string, prompt: string, environment: SemanticCommandEnvironment, options?: SemanticRunOptions): Promise<void>;
+}
+export declare function semanticOutputSchema(lineCount: number): object;
+/** Runtime validation is shared by every provider; schema-constrained output is not trusted blindly. */
+export declare function assertSemanticOutput(value: unknown, source: SemanticSource): asserts value is SemanticOutput;
+export declare class CodexCliSemanticExtractor implements SemanticExtractor {
+    private readonly config;
+    private readonly runner;
+    private readonly loginProbe;
+    readonly identity: string;
+    constructor(config: ContextGraphConfig['semantic'], runner?: SemanticCommandRunner, loginProbe?: CodexLoginProbe);
+    extract(source: SemanticSource, context: ExtractionContext, options?: SemanticRunOptions): Promise<SemanticExtractionResult>;
+}
+export declare class SemanticHydrator {
+    private readonly config;
+    private readonly store;
+    private readonly extractor;
+    constructor(config: ContextGraphConfig['semantic'], store: SemanticArtifactStore, extractor: SemanticExtractor);
+    hydrate(source: SemanticSource, context: ExtractionContext, forceRevision?: string, options?: SemanticRunOptions): Promise<{
+        artifact: SemanticArtifact;
+        reused: boolean;
+    }>;
+}