@weftlet/toolkit 0.0.0-stage → 0.1.0

package/dist/application/overlay.js

@@ -0,0 +1,110 @@
+import { execFile } from 'node:child_process';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { GitRepository } from "../repository/git.js";
+import { withCommittedTree } from "../repository/committed-tree.js";
+import { RepositoryContractExtractor, RepositoryFileExtractor, ScipSymbolExtractor, ScipTypeScriptIndexer } from "../extraction/static.js";
+import { sha256, stableJson } from "../infrastructure/util.js";
+import { contextPackEvidenceAuthority } from "../graph/query.js";
+import { inWorkingScope, readWorkingContent } from "../repository/working-content.js";
+const execute = promisify(execFile);
+const implementationExtractors = new Set([
+    'repository-file-extractor', 'repository-contract-extractor', 'scip-symbol-extractor',
+]);
+/** Conservative code overlay: reindex implementation; invalidate changed prose, never synthesize intent. */
+export async function buildWorkingOverlay(repository, config, store, storageRoot, baseSnapshotId, agent = 'default') {
+    const base = await store.read(baseSnapshotId);
+    if (!base || base.manifest.overlayDigest)
+        throw new Error('Overlay requires a committed base snapshot');
+    if (base.manifest.configurationDigest !== sha256(stableJson(config))) {
+        throw new Error('Overlay configuration must match its base snapshot');
+    }
+    const head = await repository.resolveRef('HEAD');
+    if (head !== base.manifest.commitSha)
+        throw new Error('Overlay base must match checkout HEAD');
+    const changed = await repository.workingChanges();
+    if (changed.length > 500)
+        throw new Error('Overlay exceeds the 500 changed-path bound');
+    const captured = [];
+    const roots = [...config.codeRoots, ...config.semanticSources, ...config.evidenceRoots,
+        ...config.contractPatterns];
+    const excluded = [];
+    for (const path of changed) {
+        if (!inWorkingScope(path, roots)) {
+            excluded.push(path);
+            continue;
+        }
+        const content = await readWorkingContent(repository.root, path);
+        captured.push({ path, content });
+    }
+    const overlayCapture = {
+        files: captured.map(({ path, content }) => ({ path, digest: content === null ? null : sha256(content) })),
+        sourcePatterns: roots, excludedPaths: excluded,
+    };
+    const overlayDigest = sha256(stableJson({ version: 2, ...overlayCapture }));
+    const snapshotId = `${head}-overlay-${sha256(base.manifest.contentDigest + overlayDigest).slice(0, 32)}`;
+    const affected = new Set(captured.map((file) => file.path));
+    const facts = await withCommittedTree(repository.root, head, async (root) => {
+        for (const file of captured) {
+            const target = join(root, file.path);
+            if (file.content === null)
+                await rm(target, { force: true });
+            else {
+                await mkdir(dirname(target), { recursive: true });
+                await writeFile(target, file.content);
+            }
+        }
+        const git = (...args) => execute('git', args, { cwd: root });
+        await git('init', '--quiet');
+        await git('add', '.');
+        await git('-c', 'user.name=Context Graph Draft', '-c', 'user.email=draft@example.invalid', '-c', 'commit.gpgsign=false', 'commit', '--quiet', '-m', 'Isolated overlay input');
+        const draftRepository = new GitRepository(root);
+        const context = {
+            repositoryRoot: root, repositoryId: config.repositoryId, ref: 'HEAD',
+            commitSha: await draftRepository.resolveRef('HEAD'), snapshotId,
+            changedPaths: captured.filter((f) => f.content !== null).map((f) => f.path),
+            deletedPaths: captured.filter((f) => f.content === null).map((f) => f.path),
+            renamedPaths: {},
+        };
+        const scip = await new ScipTypeScriptIndexer(config.scip, storageRoot).index(context);
+        const extractors = [
+            new RepositoryFileExtractor(draftRepository, config.codeRoots, scip.digest),
+            new RepositoryContractExtractor(draftRepository, config.contractPatterns, config.contractConsumerRoots ?? config.codeRoots, config.contractAliases),
+            new ScipSymbolExtractor(draftRepository, scip),
+        ];
+        return (await Promise.all(extractors.map((e) => e.extract(context)))).flat().map(({ id: _id, ...fact }) => {
+            const draft = { ...fact, snapshotId, authority: 'draft',
+                provenance: { ...fact.provenance, commitSha: head } };
+            return { ...draft, id: sha256(stableJson(draft)) };
+        });
+    });
+    const retained = base.facts.filter((fact) => !implementationExtractors.has(fact.extractor.id) &&
+        contextPackEvidenceAuthority(fact) !== 'implemented' &&
+        fact.extractor.id !== 'otlp-runtime-evidence' &&
+        !affected.has(fact.provenance.path) &&
+        ![fact.subject, fact.object].some((node) => [...affected].some((path) => node.id === `component:file:${path}` || node.id === `document:${path}` || node.label === path))).map((fact) => ({ ...fact, snapshotId }));
+    const allFacts = [...retained, ...facts].sort((a, b) => a.id.localeCompare(b.id));
+    const overlay = {
+        ...base,
+        manifest: {
+            ...base.manifest, snapshotId, baseSha: head, overlayDigest, overlayCapture,
+            generatedAt: new Date().toISOString(), contentDigest: sha256(stableJson(allFacts)),
+        },
+        facts: allFacts,
+        invariants: base.invariants.map((rule) => ({
+            ...rule, status: 'unknown', message: `Draft overlay requires revalidation: ${rule.invariantId}`,
+        })),
+        runtimeEvidence: [],
+        unresolved: [
+            'Draft implementation overlay: changed semantic documents require explicit re-extraction.',
+            `Changes outside configured source scope are excluded: ${excluded.join(', ') || '(none)'}`,
+        ],
+        diagnostics: [],
+    };
+    if (await repository.resolveRef('HEAD') !== head)
+        throw new Error('HEAD changed during overlay capture; retry');
+    await store.write(overlay);
+    await store.updateHead(`overlay-${sha256(`${resolve(repository.root)}:${agent}`).slice(0, 24)}`, snapshotId);
+    return overlay;
+}

package/dist/application/saved-evidence.d.ts

@@ -0,0 +1,38 @@
+import type { ImpactQueryService, ImpactScanRequest } from "@weftlet/core";
+import type { GitRepository } from "../repository/git.js";
+/** Read-side metadata; never calls an indexer, model, compiler, or refresh operation. */
+export declare class SavedEvidenceQueryService implements ImpactQueryService {
+    private readonly queries;
+    private readonly repository;
+    private readonly configurationDigest;
+    constructor(queries: ImpactQueryService, repository: GitRepository, configurationDigest: string);
+    scan(request: ImpactScanRequest): Promise<{
+        markdown: string;
+        evidenceState: {
+            stale: boolean;
+            configurationMatches: boolean;
+            eligibleForCurrentDiffValidation: false;
+            overlayFreshness?: "current" | "stale" | "unknown" | undefined;
+            capturedWorkingChanges?: string[] | undefined;
+            changedSinceCapture?: string[] | undefined;
+            currentCommit: string | undefined;
+            excludedWorkingChanges: string[];
+        };
+        snapshot: Pick<import("@weftlet/core").SnapshotManifest, "snapshotId" | "commitSha" | "contentDigest" | "configurationDigest" | "scope" | "baseSha" | "overlayDigest" | "overlayCapture">;
+        capabilities: readonly import("@weftlet/core").GraphNode[];
+        facts: readonly import("@weftlet/core").GraphFact[];
+        invariants: readonly import("@weftlet/core").InvariantResult[];
+        runtimeEvidence: readonly import("@weftlet/core").RuntimeTraceReference[];
+        suggestedFiles: readonly string[];
+        coverage: import("@weftlet/core").ContextPackCoverage;
+        diagnostics: import("@weftlet/core").DiagnosticReport;
+        exploration?: {
+            readonly returned: number;
+            readonly reachableFacts: number;
+            readonly maxDepth: number;
+            readonly depthLimitReached: boolean;
+            readonly truncated: boolean;
+            readonly continuation?: string;
+        };
+    }>;
+}

package/dist/application/saved-evidence.js

@@ -0,0 +1,59 @@
+import { MarkdownContextPackRenderer } from "../graph/query.js";
+import { inWorkingScope, readWorkingContent } from "../repository/working-content.js";
+import { sha256 } from "../infrastructure/util.js";
+/** Read-side metadata; never calls an indexer, model, compiler, or refresh operation. */
+export class SavedEvidenceQueryService {
+    queries;
+    repository;
+    configurationDigest;
+    constructor(queries, repository, configurationDigest) {
+        this.queries = queries;
+        this.repository = repository;
+        this.configurationDigest = configurationDigest;
+    }
+    async scan(request) {
+        const pack = await this.queries.scan(request);
+        const currentCommit = await this.repository.resolveRef('HEAD').catch(() => undefined);
+        const workingChanges = await this.repository.workingChanges();
+        const capturedWorkingChanges = [];
+        const changedSinceCapture = new Set();
+        let overlayFreshness;
+        if (pack.snapshot.overlayDigest) {
+            overlayFreshness = 'unknown';
+            const capture = pack.snapshot.overlayCapture;
+            if (capture) {
+                overlayFreshness = 'current';
+                for (const file of capture.files) {
+                    try {
+                        const content = await readWorkingContent(this.repository.root, file.path);
+                        if ((content === null ? null : sha256(content)) === file.digest)
+                            capturedWorkingChanges.push(file.path);
+                        else
+                            changedSinceCapture.add(file.path);
+                    }
+                    catch {
+                        overlayFreshness = 'unknown';
+                        changedSinceCapture.add(file.path);
+                    }
+                }
+                for (const path of workingChanges) {
+                    if (!capturedWorkingChanges.includes(path) && inWorkingScope(path, capture.sourcePatterns))
+                        changedSinceCapture.add(path);
+                }
+                if (changedSinceCapture.size && overlayFreshness !== 'unknown')
+                    overlayFreshness = 'stale';
+            }
+        }
+        const excludedWorkingChanges = workingChanges.filter((path) => !capturedWorkingChanges.includes(path));
+        const evidenceState = {
+            currentCommit,
+            excludedWorkingChanges,
+            ...(overlayFreshness ? { overlayFreshness, capturedWorkingChanges, changedSinceCapture: [...changedSinceCapture].sort() } : {}),
+            stale: currentCommit !== pack.snapshot.commitSha || (overlayFreshness !== undefined && overlayFreshness !== 'current'),
+            configurationMatches: pack.snapshot.configurationDigest === this.configurationDigest,
+            eligibleForCurrentDiffValidation: false,
+        };
+        const result = { ...pack, evidenceState };
+        return { ...result, markdown: new MarkdownContextPackRenderer().render(result) };
+    }
+}

package/dist/application/snapshot-checks.d.ts

@@ -0,0 +1,16 @@
+import type { AgentSemanticScopeResolver } from "./agent-context.js";
+import type { ImpactScanRequest, SnapshotStore } from "@weftlet/core";
+import type { GitRepository } from "../repository/git.js";
+import type { ContextGraphHydrator } from "./hydrator.js";
+export declare class SnapshotChecks {
+    private readonly store;
+    private readonly repository;
+    private readonly hydrator;
+    private readonly scopeResolver?;
+    private readonly configurationDigest?;
+    constructor(store: Pick<SnapshotStore, 'readHead'>, repository: Pick<GitRepository, 'resolveRef'> & Partial<Pick<GitRepository, 'workingChanges'>>, hydrator: Pick<ContextGraphHydrator, 'compareClean'>, scopeResolver?: Pick<AgentSemanticScopeResolver, "resolve"> | undefined, configurationDigest?: string | undefined);
+    private target;
+    private readTarget;
+    read(request: ImpactScanRequest, ref?: string): Promise<import("@weftlet/core").GraphSnapshot>;
+    compare(request: ImpactScanRequest, ref?: string): Promise<import("./hydrator.js").HydrationResult>;
+}

package/dist/application/snapshot-checks.js

@@ -0,0 +1,51 @@
+// Final checks must use the same scope resolver as prepared impact scans, without silently
+// starting hydration or substituting another owner's (or an older commit's) evidence.
+export class SnapshotChecks {
+    store;
+    repository;
+    hydrator;
+    scopeResolver;
+    configurationDigest;
+    constructor(store, repository, hydrator, scopeResolver, configurationDigest) {
+        this.store = store;
+        this.repository = repository;
+        this.hydrator = hydrator;
+        this.scopeResolver = scopeResolver;
+        this.configurationDigest = configurationDigest;
+    }
+    async target(request, ref) {
+        if (request.snapshotId)
+            throw new Error('Final checks select exact-ref evidence, not --snapshot');
+        const commitSha = await this.repository.resolveRef(ref);
+        if ((await this.repository.workingChanges?.())?.length) {
+            throw new Error('Saved committed evidence cannot validate excluded working changes');
+        }
+        const scope = await this.scopeResolver?.resolve(request);
+        if (scope && scope.commitSha !== commitSha) {
+            throw new Error('Agent final checks require the current HEAD; the requested ref differs');
+        }
+        return {
+            ref: commitSha,
+            headName: scope?.headName ?? 'default',
+            semanticSources: scope?.semanticSources,
+        };
+    }
+    async readTarget(target) {
+        const snapshot = await this.store.readHead(target.headName);
+        if (!snapshot || snapshot.manifest.commitSha !== target.ref || snapshot.manifest.overlayDigest) {
+            throw new Error(`No exact-commit graph snapshot for scope ${target.headName} at ${target.ref}. Run hydrate with the same config and owner/task selectors first.`);
+        }
+        if (this.configurationDigest && snapshot.manifest.configurationDigest !== this.configurationDigest) {
+            throw new Error('Snapshot configuration differs from current configuration; refresh required');
+        }
+        return snapshot;
+    }
+    async read(request, ref = 'HEAD') {
+        return this.readTarget(await this.target(request, ref));
+    }
+    async compare(request, ref = 'HEAD') {
+        const target = await this.target(request, ref);
+        await this.readTarget(target);
+        return this.hydrator.compareClean(target);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import '../runtime-check.mjs';
+import './interfaces/cli.js';

package/dist/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+// Stable executable entry point; implementation lives in interfaces/.
+import '../runtime-check.mjs';
+import './interfaces/cli.js';

package/dist/configuration/cache.d.ts

@@ -0,0 +1,2 @@
+import type { ContextGraphConfig } from "./config.js";
+export declare function resolveStorageRoot(repositoryRoot: string, config: ContextGraphConfig, userCacheRoot?: string): string;

package/dist/configuration/cache.js

@@ -0,0 +1,10 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { sha256, stableJson } from "../infrastructure/util.js";
+export function resolveStorageRoot(repositoryRoot, config, userCacheRoot = resolve(homedir(), '.cache', 'context-graph')) {
+    if (config.storageScope !== 'user')
+        return resolve(repositoryRoot, config.storagePath);
+    const profile = sha256(stableJson({ config, checkout: resolve(repositoryRoot) })).slice(0, 20);
+    return resolve(userCacheRoot, profile);
+}

package/dist/configuration/config.d.ts

@@ -0,0 +1,79 @@
+export interface ContextGraphConfig {
+    readonly schemaVersion: 1;
+    readonly repositoryRoot?: string;
+    readonly repositoryId: string;
+    readonly namespace: string;
+    readonly adapter?: string;
+    readonly semanticSources: readonly string[];
+    /** Explicit owner-approved source paths/globs; other model-derived prose remains inferred. */
+    readonly approvedIntentSources?: readonly string[];
+    readonly codeRoots: readonly string[];
+    readonly contractPatterns: readonly string[];
+    readonly contractConsumerRoots?: readonly string[];
+    readonly contractAliases?: Readonly<Record<string, readonly string[]>>;
+    readonly evidenceRoots: readonly string[];
+    readonly semantic: {
+        readonly provider: 'codex-cli' | 'module';
+        /** Codex authentication only; secrets stay in the process environment. */
+        readonly auth?: {
+            readonly mode: 'chatgpt';
+        } | {
+            readonly mode: 'api-key';
+            readonly apiKeyEnv?: string;
+        };
+        readonly providerModule?: string;
+        readonly providerIdentity?: string;
+        readonly timeoutMs?: number;
+        readonly retries?: number;
+        readonly maxDocuments?: number;
+        readonly maxSourceBytes?: number;
+        readonly model: string;
+        readonly reasoningEffort: string;
+        readonly promptVersion: string;
+        readonly extractorVersion: string;
+        readonly adapterVersion: string;
+        readonly ontologyVersion: string;
+        readonly minimumConfidence: number;
+        readonly failOnUnresolved: boolean;
+        readonly concurrency: number;
+    };
+    readonly scip: {
+        readonly version: string;
+        readonly command: string;
+        readonly args: readonly string[];
+    };
+    readonly ontology: {
+        readonly backend?: 'rdf' | 'opencaesar';
+        readonly toolVersion: string;
+        readonly containerImage?: string;
+        readonly projectPath?: string;
+        readonly usedVocabularyIris?: readonly string[];
+        readonly includedDescriptionIris?: readonly string[];
+    };
+    readonly runtimeEvidence: readonly string[];
+    readonly runtimeEvidencePolicy?: {
+        readonly retentionDays: number;
+        readonly maxReferences: number;
+        readonly maxSourceBytes: number;
+        readonly requireEnvironment: boolean;
+        readonly requireServiceInstance: boolean;
+        readonly allowedServiceNames?: readonly string[];
+        readonly allowedEnvironments?: readonly string[];
+        readonly capabilityKeys: readonly string[];
+        readonly operationKeys: readonly string[];
+    };
+    readonly storagePath: string;
+    readonly storageScope?: 'workspace' | 'user';
+    readonly agentContext?: {
+        readonly alwaysSemanticSources: readonly string[];
+        readonly followDocumentReferences: boolean;
+        readonly includeMatchingEvidence: boolean;
+        readonly maxReferencedDocuments: number;
+    };
+}
+export interface LoadedConfig {
+    readonly config: ContextGraphConfig;
+    readonly configPath: string;
+    readonly repositoryRoot: string;
+}
+export declare function loadConfig(configPath: string, initialDirectory?: string | undefined): Promise<LoadedConfig>;

package/dist/configuration/config.js

@@ -0,0 +1,165 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function requireConfig(condition, path, absolutePath) {
+    if (!condition) {
+        throw new Error(`Invalid context graph config (${absolutePath}): ${path}`);
+    }
+}
+function validateConfig(value, absolutePath) {
+    requireConfig(isRecord(value), 'root must be an object', absolutePath);
+    if (!isRecord(value))
+        return;
+    requireConfig(value.schemaVersion === 1, 'schemaVersion must be 1', absolutePath);
+    for (const field of ['repositoryId', 'namespace', 'storagePath']) {
+        requireConfig(isNonEmptyString(value[field]), `${field} must be a non-empty string`, absolutePath);
+    }
+    if (value.repositoryRoot !== undefined) {
+        requireConfig(isNonEmptyString(value.repositoryRoot), 'repositoryRoot must be a non-empty string when provided', absolutePath);
+    }
+    if (value.adapter !== undefined) {
+        requireConfig(isNonEmptyString(value.adapter), 'adapter must be a non-empty string when provided', absolutePath);
+    }
+    if (value.approvedIntentSources !== undefined) {
+        requireConfig(isStringArray(value.approvedIntentSources), 'approvedIntentSources must be an array of strings', absolutePath);
+    }
+    for (const field of [
+        'semanticSources',
+        'codeRoots',
+        'contractPatterns',
+        'evidenceRoots',
+        'runtimeEvidence',
+    ]) {
+        requireConfig(isStringArray(value[field]), `${field} must be an array of strings`, absolutePath);
+    }
+    if (value.contractConsumerRoots !== undefined) {
+        requireConfig(isStringArray(value.contractConsumerRoots), 'contractConsumerRoots must be an array of strings when provided', absolutePath);
+    }
+    if (value.contractAliases !== undefined) {
+        requireConfig(isRecord(value.contractAliases), 'contractAliases must be an object when provided', absolutePath);
+        if (isRecord(value.contractAliases)) {
+            for (const [path, aliases] of Object.entries(value.contractAliases)) {
+                requireConfig(isNonEmptyString(path) && isStringArray(aliases) && aliases.length > 0, `contractAliases.${path} must be a non-empty array of strings`, absolutePath);
+            }
+        }
+    }
+    if (value.runtimeEvidencePolicy !== undefined) {
+        requireConfig(isRecord(value.runtimeEvidencePolicy), 'runtimeEvidencePolicy must be an object', absolutePath);
+        if (isRecord(value.runtimeEvidencePolicy)) {
+            for (const field of ['retentionDays', 'maxReferences', 'maxSourceBytes']) {
+                requireConfig(Number.isInteger(value.runtimeEvidencePolicy[field]) &&
+                    Number(value.runtimeEvidencePolicy[field]) > 0, `runtimeEvidencePolicy.${field} must be a positive integer`, absolutePath);
+            }
+            for (const field of ['requireEnvironment', 'requireServiceInstance']) {
+                requireConfig(typeof value.runtimeEvidencePolicy[field] === 'boolean', `runtimeEvidencePolicy.${field} must be a boolean`, absolutePath);
+            }
+            for (const field of [
+                'allowedServiceNames',
+                'allowedEnvironments',
+                'capabilityKeys',
+                'operationKeys',
+            ]) {
+                if (value.runtimeEvidencePolicy[field] === undefined && field.startsWith('allowed')) {
+                    continue;
+                }
+                requireConfig(isStringArray(value.runtimeEvidencePolicy[field]) &&
+                    value.runtimeEvidencePolicy[field].length > 0, `runtimeEvidencePolicy.${field} must be a non-empty array of strings`, absolutePath);
+            }
+        }
+    }
+    if (value.storageScope !== undefined) {
+        requireConfig(value.storageScope === 'workspace' || value.storageScope === 'user', 'storageScope must be workspace or user when provided', absolutePath);
+    }
+    if (value.agentContext !== undefined) {
+        requireConfig(isRecord(value.agentContext), 'agentContext must be an object', absolutePath);
+        if (isRecord(value.agentContext)) {
+            requireConfig(isStringArray(value.agentContext.alwaysSemanticSources), 'agentContext.alwaysSemanticSources must be an array of strings', absolutePath);
+            requireConfig(typeof value.agentContext.followDocumentReferences === 'boolean', 'agentContext.followDocumentReferences must be a boolean', absolutePath);
+            requireConfig(typeof value.agentContext.includeMatchingEvidence === 'boolean', 'agentContext.includeMatchingEvidence must be a boolean', absolutePath);
+            requireConfig(Number.isInteger(value.agentContext.maxReferencedDocuments) &&
+                Number(value.agentContext.maxReferencedDocuments) > 0, 'agentContext.maxReferencedDocuments must be a positive integer', absolutePath);
+        }
+    }
+    requireConfig(isRecord(value.semantic), 'semantic must be an object', absolutePath);
+    if (isRecord(value.semantic)) {
+        requireConfig(value.semantic.provider === 'codex-cli' || value.semantic.provider === 'module', 'semantic.provider is invalid', absolutePath);
+        if (value.semantic.provider === 'module') {
+            requireConfig(isNonEmptyString(value.semantic.providerModule) && isNonEmptyString(value.semantic.providerIdentity), 'module providers require providerModule and providerIdentity', absolutePath);
+        }
+        if (value.semantic.auth !== undefined) {
+            const auth = value.semantic.auth;
+            requireConfig(value.semantic.provider === 'codex-cli' && isRecord(auth), 'semantic.auth must be an object for codex-cli only', absolutePath);
+            if (isRecord(auth)) {
+                requireConfig(auth.mode === 'chatgpt' || auth.mode === 'api-key', 'semantic.auth.mode must be chatgpt or api-key', absolutePath);
+                requireConfig(Object.keys(auth).every(key => key === 'mode' || (auth.mode === 'api-key' && key === 'apiKeyEnv')), 'semantic.auth accepts only mode and, for api-key, apiKeyEnv; never store credentials here', absolutePath);
+                requireConfig(auth.apiKeyEnv === undefined || (typeof auth.apiKeyEnv === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(auth.apiKeyEnv)), 'semantic.auth.apiKeyEnv must name an environment variable', absolutePath);
+            }
+        }
+        for (const [field, max] of [['timeoutMs', 300_000], ['retries', 2], ['maxDocuments', 1000], ['maxSourceBytes', 1_048_576]]) {
+            const item = value.semantic[field];
+            if (item !== undefined)
+                requireConfig(Number.isInteger(item) && Number(item) >= (field === 'retries' ? 0 : 1) && Number(item) <= max, `semantic.${field} exceeds supported bounds`, absolutePath);
+        }
+        for (const field of [
+            'model',
+            'reasoningEffort',
+            'promptVersion',
+            'extractorVersion',
+            'adapterVersion',
+            'ontologyVersion',
+        ]) {
+            requireConfig(isNonEmptyString(value.semantic[field]), `semantic.${field} must be a non-empty string`, absolutePath);
+        }
+        requireConfig(typeof value.semantic.minimumConfidence === 'number' &&
+            value.semantic.minimumConfidence >= 0 &&
+            value.semantic.minimumConfidence <= 1, 'semantic.minimumConfidence must be between 0 and 1', absolutePath);
+        requireConfig(typeof value.semantic.failOnUnresolved === 'boolean', 'semantic.failOnUnresolved must be a boolean', absolutePath);
+        requireConfig(Number.isInteger(value.semantic.concurrency) && Number(value.semantic.concurrency) > 0 && Number(value.semantic.concurrency) <= 4, 'semantic.concurrency must be a positive integer no greater than 4', absolutePath);
+    }
+    requireConfig(isRecord(value.scip), 'scip must be an object', absolutePath);
+    if (isRecord(value.scip)) {
+        requireConfig(isNonEmptyString(value.scip.version), 'scip.version is required', absolutePath);
+        requireConfig(isNonEmptyString(value.scip.command), 'scip.command is required', absolutePath);
+        requireConfig(isStringArray(value.scip.args), 'scip.args must be an array of strings', absolutePath);
+    }
+    requireConfig(isRecord(value.ontology), 'ontology must be an object', absolutePath);
+    if (isRecord(value.ontology)) {
+        requireConfig(value.ontology.backend === undefined || ['rdf', 'opencaesar'].includes(String(value.ontology.backend)), 'ontology.backend must be rdf or opencaesar', absolutePath);
+        for (const field of ['toolVersion']) {
+            requireConfig(isNonEmptyString(value.ontology[field]), `ontology.${field} must be a non-empty string`, absolutePath);
+        }
+        for (const field of ['containerImage', 'projectPath']) {
+            if (value.ontology.backend === 'opencaesar' || value.ontology[field] !== undefined) {
+                requireConfig(isNonEmptyString(value.ontology[field]), `ontology.${field} must be a non-empty string`, absolutePath);
+            }
+        }
+        for (const field of ['usedVocabularyIris', 'includedDescriptionIris']) {
+            if (value.ontology[field] !== undefined) {
+                requireConfig(isStringArray(value.ontology[field]), `ontology.${field} must be an array of strings when provided`, absolutePath);
+            }
+        }
+    }
+}
+export async function loadConfig(configPath, initialDirectory = process.env.INIT_CWD) {
+    const directPath = resolve(configPath);
+    const initialPath = initialDirectory ? resolve(initialDirectory, configPath) : undefined;
+    const absolutePath = existsSync(directPath) || !initialPath || !existsSync(initialPath) ? directPath : initialPath;
+    const parsed = JSON.parse(await readFile(absolutePath, 'utf8'));
+    validateConfig(parsed, absolutePath);
+    const repositoryRoot = resolve(dirname(absolutePath), parsed.repositoryRoot ?? '.');
+    return {
+        config: parsed,
+        configPath: absolutePath,
+        repositoryRoot,
+    };
+}

package/dist/core.d.ts

@@ -0,0 +1 @@
+export * from '@weftlet/core';

package/dist/core.js

@@ -0,0 +1,2 @@
+// Modified for standalone extraction; see docs/extraction-manifest.json.
+export * from '@weftlet/core';

package/dist/extraction/codex-auth.d.ts

@@ -0,0 +1,12 @@
+import type { ContextGraphConfig } from '../configuration/config.js';
+import { type SemanticRunOptions } from './semantic-process.js';
+export type SemanticCommandEnvironment = Record<string, string | undefined>;
+export declare function semanticCommandEnvironment(source: Readonly<Record<string, string | undefined>>): SemanticCommandEnvironment;
+export type CodexLoginMode = 'chatgpt' | 'api-key' | 'unknown' | 'unavailable';
+export type CodexLoginProbe = (command: string, environment: SemanticCommandEnvironment, options?: SemanticRunOptions) => Promise<CodexLoginMode>;
+/** Read-only status check. Never expose output: API login status may contain key fragments. */
+export declare const readCodexLoginMode: CodexLoginProbe;
+type CodexAuth = ContextGraphConfig['semantic']['auth'];
+/** No auth mutation or fallback. A missing key must not fall back to a saved account. */
+export declare function prepareCodexAuthentication(auth: CodexAuth, source: Readonly<Record<string, string | undefined>>, command: string, options?: SemanticRunOptions, probe?: CodexLoginProbe): Promise<SemanticCommandEnvironment>;
+export {};

package/dist/extraction/codex-auth.js

@@ -0,0 +1,74 @@
+// Environment allowlist adapted from the extracted semantic.ts; see docs/extraction-manifest.json.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SemanticProviderError } from './semantic-process.js';
+const semanticEnvironmentAllowlist = [
+    'APPDATA',
+    'CODEX_HOME',
+    'COMSPEC',
+    'HOME',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'LANG',
+    'LC_ALL',
+    'LOCALAPPDATA',
+    'NODE_EXTRA_CA_CERTS',
+    'NO_PROXY',
+    'PATH',
+    'PATHEXT',
+    'SSL_CERT_FILE',
+    'SYSTEMROOT',
+    'TEMP',
+    'TMP',
+    'USERPROFILE',
+    'WINDIR',
+];
+export function semanticCommandEnvironment(source) {
+    const result = {};
+    for (const allowed of semanticEnvironmentAllowlist) {
+        const match = Object.keys(source).find((key) => key.toUpperCase() === allowed);
+        if (match && source[match] !== undefined)
+            result[allowed] = source[match];
+    }
+    return result;
+}
+/** Read-only status check. Never expose output: API login status may contain key fragments. */
+export const readCodexLoginMode = async (command, environment, options = {}) => {
+    try {
+        const result = await promisify(execFile)(command, ['login', 'status'], {
+            env: environment, timeout: Math.min(options.timeoutMs ?? 5000, 5000),
+            signal: options.signal, maxBuffer: 8192, windowsHide: true,
+        });
+        const output = `${result.stdout}\n${result.stderr}`;
+        if (/logged in using chatgpt/i.test(output))
+            return 'chatgpt';
+        if (/logged in using an? api key/i.test(output))
+            return 'api-key';
+        return 'unknown';
+    }
+    catch {
+        if (options.signal?.aborted)
+            throw new SemanticProviderError('cancelled', 'Semantic extraction cancelled');
+        return 'unavailable';
+    }
+};
+/** No auth mutation or fallback. A missing key must not fall back to a saved account. */
+export async function prepareCodexAuthentication(auth, source, command, options = {}, probe = readCodexLoginMode) {
+    options.signal?.throwIfAborted();
+    const environment = semanticCommandEnvironment(source);
+    if (auth?.mode === 'api-key') {
+        const keyName = auth.apiKeyEnv ?? 'CODEX_API_KEY';
+        const key = source[keyName];
+        if (!key?.trim())
+            throw new SemanticProviderError('unavailable', `Codex API-key authentication requires the ${keyName} environment variable; no login fallback was attempted`);
+        environment.CODEX_API_KEY = key;
+        return environment;
+    }
+    if (auth !== undefined && auth.mode !== 'chatgpt') {
+        throw new SemanticProviderError('unavailable', 'Unsupported Codex authentication mode');
+    }
+    const mode = await probe(command, environment, options);
+    if (mode !== 'chatgpt')
+        throw new SemanticProviderError('unavailable', 'ChatGPT authentication requires Codex signed in with ChatGPT (codex login). Status could not confirm that login type; no API fallback was attempted');
+    return environment;
+}

package/dist/extraction/document.d.ts

@@ -0,0 +1,5 @@
+import type { ExtractionContext, GraphFact, SemanticArtifact, SemanticSource } from "@weftlet/core";
+export declare function linkSemanticDocuments(context: ExtractionContext, hydrated: readonly {
+    source: SemanticSource;
+    artifact: SemanticArtifact;
+}[], trackedPaths?: readonly string[]): readonly GraphFact[];