@planu/cli 4.12.3 → 4.14.1

package/dist/tools/validate.js

@@ -1,6 +1,58 @@
 /* eslint-disable max-lines -- validate coordinates multiple legacy gate payloads in one tool. */
 // tools/validate.ts — Compare spec vs implementation (SPEC-595: elicitation on failures)
 // Uses the validator engine to check coverage, missing items, quality issues.
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import { elicitOrFallback, buildEnumSchema } from '../engine/elicitation/elicit-helper.js';
 import { compactObj } from '../engine/compact-obj.js';
 import { resolveProjectId, missingProjectIdError } from './resolve-project-id.js';
@@ -22,11 +74,146 @@ import { runLintCheck } from './validate-lint.js';
 import { checkPlanuUncommittedChanges, runAssuranceGates } from './validate-assurance.js';
 import { applyValidateStructuredCompat } from './validate-structured-compat.js';
 import { getToolExecutionSignal } from './safe-handler.js';
+import { durableJobCursor, DurableJobRuntime } from '../engine/execution/job-runtime.js';
+import { scheduleValidateJobExecution } from '../engine/execution/validate-job-executor.js';
+import { createPendingValidationSubmission } from '../engine/validation/durable-validation.js';
+import { PROJECT_ID as CANONICAL_PROJECT_ID } from '../engine/validation/validation-receipt-codec.js';
+import { acquireLock, releaseLock } from '../engine/safety/cross-process-lock.js';
+import { getRuntimePolicy } from '../engine/runtime-policy.js';
 // Re-export for external use (SPEC-018)
 export { validateContractCompliance };
-// SPEC-595: server? param enables elicitation on failures
+/** Public MCP boundary: persist and acknowledge validation work without running it inline. */
+export async function handleValidate(args) {
+    const projectId = resolveProjectId(args);
+    if (!projectId) {
+        return missingProjectIdError;
+    }
+    if (!CANONICAL_PROJECT_ID.test(projectId)) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: '[Planu] Validation requires the canonical project identity. Run init_project with the absolute projectPath to migrate legacy state, then retry validate with projectPath.',
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'legacy_project_identity',
+                code: 409,
+                context: { projectId, expected: 'canonical-32-hex' },
+                nextAction: {
+                    tool: 'init_project',
+                    arguments: { projectPath: '<absolute-project-path>' },
+                },
+            },
+        };
+    }
+    const [spec, knowledge] = await Promise.all([
+        specStore.getSpec(projectId, args.specId),
+        knowledgeStore.getKnowledge(projectId),
+    ]);
+    if (!spec) {
+        return {
+            content: [{ type: 'text', text: ti('spec.notFound', { id: args.specId }) }],
+            isError: true,
+            structuredContent: {
+                error: 'spec_not_found',
+                code: 404,
+                context: { specId: args.specId, projectId },
+            },
+        };
+    }
+    if (!knowledge) {
+        return {
+            content: [{ type: 'text', text: t('project.notFound') }],
+            isError: true,
+            structuredContent: { error: 'project_not_found', code: 404, context: { projectId } },
+        };
+    }
+    const projectPath = args.projectPath ?? knowledge.projectPath;
+    const submissionLock = await acquireValidationSubmissionLock(projectId, args.specId);
+    try {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const runtime = __addDisposableResource(env_1, new DurableJobRuntime(), false);
+            const active = runtime.list(projectId).find((candidate) => {
+                const payload = candidate.payload;
+                return (['accepted', 'checkpointed', 'running'].includes(candidate.state) &&
+                    payload?.kind === 'validate' &&
+                    payload.input?.specId === args.specId);
+            });
+            if (active) {
+                if (active.state === 'accepted' || active.state === 'checkpointed') {
+                    scheduleValidateJobExecution(projectId, active.workspaceId);
+                }
+                return validationAcceptedResult(active, projectId);
+            }
+            const job = createPendingValidationSubmission({
+                runtime,
+                canonicalProjectId: projectId,
+                spec: { id: args.specId, projectPath, specPath: spec.specPath },
+                deadlineAt: Date.now() + getRuntimePolicy().validation.defaultDeadlineMs,
+            });
+            if (job.state === 'accepted' || job.state === 'checkpointed') {
+                scheduleValidateJobExecution(projectId, job.workspaceId);
+            }
+            return validationAcceptedResult(job, projectId);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    finally {
+        await releaseLock(submissionLock);
+    }
+}
+async function acquireValidationSubmissionLock(projectId, specId) {
+    const policy = getRuntimePolicy().validation;
+    const deadlineAt = Date.now() + policy.submissionLockWaitMs;
+    while (Date.now() < deadlineAt) {
+        const handle = await acquireLock(projectId, `${specId}-validation-submit`, {
+            reason: 'durable-validation-submit',
+        });
+        if (handle) {
+            return handle;
+        }
+        const remainingMs = deadlineAt - Date.now();
+        if (remainingMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, Math.min(policy.submissionLockPollMs, remainingMs)));
+        }
+    }
+    throw new Error('[Planu] Timed out waiting for the validation submission lock');
+}
+function validationAcceptedResult(job, projectId) {
+    const accepted = {
+        schemaVersion: 1,
+        operationId: job.id,
+        projectId,
+        workspaceId: job.workspaceId,
+        state: job.state,
+        submittedAt: job.createdAt,
+        cursor: durableJobCursor(job),
+        terminalStates: ['completed', 'failed', 'cancelled', 'dead-letter'],
+        resultSchema: 'validate-completion/v1',
+        observation: {
+            get: 'get_job',
+            watch: 'watch_job',
+            cancel: 'cancel_job',
+            restart: 'restart_job',
+        },
+    };
+    return {
+        content: [{ type: 'text', text: `Validation accepted as durable job ${job.id}.` }],
+        structuredContent: accepted,
+    };
+}
+// SPEC-595: server? param enables elicitation for direct internal/test execution.
 // eslint-disable-next-line max-lines-per-function -- validate orchestrates many existing gates in one handler.
-export async function handleValidate(args, server) {
+export async function executeValidate(args, server) {
     const { specId } = args;
     const projectId = resolveProjectId(args);
     if (!projectId) {
@@ -441,10 +628,26 @@ function buildCompactSummary(specId, score, passedCount, failedCount, totalCrite
     };
 }
 function buildValidateStructuredContent(args) {
-    const failedDorItems = args.dor.items.filter((item) => item.status === 'failed').slice(0, 5);
+    const failedDorItems = args.dor.items
+        .filter((item) => item.status === 'failed')
+        .slice(0, 5)
+        .map((item) => ({
+        id: item.id,
+        description: item.description,
+        category: item.category,
+        status: item.status,
+        required: item.required,
+    }));
     const failedDodItems = args.dod.items
         .filter((item) => item.required === true && item.status !== 'passed')
-        .slice(0, 5);
+        .slice(0, 5)
+        .map((item) => ({
+        id: item.id,
+        description: item.description,
+        category: item.category,
+        status: item.status,
+        required: item.required,
+    }));
     const failedGates = args.validationReport.gates.filter((gate) => !gate.passed);
     const minimalityBlockingFindings = args.minimalityReport?.findings.filter((finding) => finding.blocksDone) ?? [];
     const blockers = [
@@ -542,7 +745,12 @@ function buildValidateStructuredContent(args) {
                 blocked: args.minimalityReport.blocked,
                 findingCount: args.minimalityReport.findings.length,
                 blockingFindingCount: minimalityBlockingFindings.length,
-                blockingFindingsTop5: minimalityBlockingFindings.slice(0, 5),
+                blockingFindingsTop5: minimalityBlockingFindings.slice(0, 5).map((finding) => ({
+                    ruleId: finding.ruleId,
+                    target: finding.target,
+                    evidence: finding.evidence,
+                    blocksDone: finding.blocksDone,
+                })),
             }
             : undefined,
         graphCoverage: {

package/dist/transports/http-transport.js

@@ -11,6 +11,23 @@ import { compactToolsListMessage, isToolsListResponse, } from '../engine/compact
 const MAX_BODY_BYTES = 5 * 1024 * 1024; // 5MB
 const SHUTDOWN_GRACE_MS = 5_000;
 const sessions = new Map();
+function observeHttpDisconnect(req, res) {
+    const controller = new AbortController();
+    const abort = () => {
+        if (!res.writableEnded && !controller.signal.aborted) {
+            controller.abort(new Error('HTTP client disconnected'));
+        }
+    };
+    req.once('aborted', abort);
+    res.once('close', abort);
+    return {
+        signal: controller.signal,
+        dispose: () => {
+            req.off('aborted', abort);
+            res.off('close', abort);
+        },
+    };
+}
 async function handleNodeTransportRequest(transport, req, res, parsedBody) {
     // The SDK's Node wrapper pins @hono/node-server 1.x. Adapt the Web Standard
     // transport here so the published package executes against our direct Hono 2 dependency.
@@ -43,7 +60,7 @@ const SERVER_CARD = JSON.stringify({
     authentication: { required: false },
     capabilities: { tools: true, resources: true, prompts: false },
     installation: {
-        npm: 'npx -y @planu/cli@latest',
+        npm: `npx -y @planu/cli@${PLANU_VERSION}`,
         docker: 'docker run -i --rm ghcr.io/planu-dev/planu',
     },
 });
@@ -71,7 +88,7 @@ async function readBody(req) {
         req.on('error', reject);
     });
 }
-async function handlePost(req, res, sessionId, serverFactory) {
+async function handlePost(req, res, sessionId, serverFactory, requestSignal) {
     let body;
     try {
         body = await readBody(req);
@@ -94,7 +111,7 @@ async function handlePost(req, res, sessionId, serverFactory) {
     if (sessionId) {
         const entry = sessions.get(sessionId);
         if (entry) {
-            await runWithSessionContext({ sessionId, licenseKey: entry.licenseKey }, () => handleNodeTransportRequest(entry.transport, req, res, parsedBody));
+            await runWithSessionContext({ sessionId, licenseKey: entry.licenseKey, signal: requestSignal }, () => handleNodeTransportRequest(entry.transport, req, res, parsedBody));
             return;
         }
     }
@@ -113,79 +130,85 @@ async function handlePost(req, res, sessionId, serverFactory) {
     };
     const sessionServer = serverFactory();
     await sessionServer.connect(transport);
-    await runWithSessionContext({ sessionId: transport.sessionId ?? sessionId ?? 'unknown', licenseKey }, () => handleNodeTransportRequest(transport, req, res, parsedBody));
+    await runWithSessionContext({ sessionId: transport.sessionId ?? sessionId ?? 'unknown', licenseKey, signal: requestSignal }, () => handleNodeTransportRequest(transport, req, res, parsedBody));
     const newSessionId = transport.sessionId;
     if (newSessionId) {
         sessions.set(newSessionId, { transport, server: sessionServer, licenseKey });
     }
 }
 async function handleMcpRequest(req, res, serverFactory, corsOrigin) {
-    setSecurityHeaders(res);
-    if (corsOrigin) {
-        setCorsHeaders(res, corsOrigin);
-    }
-    // OAuth 2.1 Bearer token validation (SPEC-161)
-    const oauthConfig = loadOAuthConfig();
-    if (oauthConfig.enabled) {
-        const token = extractBearerToken(req.headers.authorization);
-        if (!token) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Unauthorized', message: 'Bearer token required' }));
-            return;
+    const cancellation = observeHttpDisconnect(req, res);
+    try {
+        setSecurityHeaders(res);
+        if (corsOrigin) {
+            setCorsHeaders(res, corsOrigin);
         }
-        const authResult = await validateToken(token, oauthConfig);
-        if (!authResult.valid) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Unauthorized', message: authResult.reason }));
+        // OAuth 2.1 Bearer token validation (SPEC-161)
+        const oauthConfig = loadOAuthConfig();
+        if (oauthConfig.enabled) {
+            const token = extractBearerToken(req.headers.authorization);
+            if (!token) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unauthorized', message: 'Bearer token required' }));
+                return;
+            }
+            const authResult = await validateToken(token, oauthConfig);
+            if (!authResult.valid) {
+                res.writeHead(401, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Unauthorized', message: authResult.reason }));
+                return;
+            }
+        }
+        const sessionId = req.headers['mcp-session-id'];
+        // Rate limit per session (or IP for new sessions)
+        const rateLimitKey = sessionId ?? req.socket.remoteAddress ?? 'unknown';
+        const rateResult = checkHttpRateLimit(rateLimitKey);
+        if (!rateResult.allowed) {
+            res.writeHead(429, {
+                'Content-Type': 'application/json',
+                'Retry-After': String(Math.ceil(rateResult.retryAfterMs / 1000)),
+            });
+            res.end(JSON.stringify({ error: 'Too many requests. Try again later.' }));
             return;
         }
-    }
-    const sessionId = req.headers['mcp-session-id'];
-    // Rate limit per session (or IP for new sessions)
-    const rateLimitKey = sessionId ?? req.socket.remoteAddress ?? 'unknown';
-    const rateResult = checkHttpRateLimit(rateLimitKey);
-    if (!rateResult.allowed) {
-        res.writeHead(429, {
-            'Content-Type': 'application/json',
-            'Retry-After': String(Math.ceil(rateResult.retryAfterMs / 1000)),
-        });
-        res.end(JSON.stringify({ error: 'Too many requests. Try again later.' }));
-        return;
-    }
-    if (req.method === 'GET') {
-        res.setHeader('Cache-Control', 'no-store');
-        if (sessionId) {
-            const entry = sessions.get(sessionId);
-            if (entry) {
-                await runWithSessionContext({ sessionId, licenseKey: entry.licenseKey }, () => handleNodeTransportRequest(entry.transport, req, res));
-                return;
+        if (req.method === 'GET') {
+            res.setHeader('Cache-Control', 'no-store');
+            if (sessionId) {
+                const entry = sessions.get(sessionId);
+                if (entry) {
+                    await runWithSessionContext({ sessionId, licenseKey: entry.licenseKey, signal: cancellation.signal }, () => handleNodeTransportRequest(entry.transport, req, res));
+                    return;
+                }
             }
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Missing or invalid session ID' }));
+            return;
         }
-        res.writeHead(400, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'Missing or invalid session ID' }));
-        return;
-    }
-    if (req.method === 'DELETE') {
-        if (sessionId) {
-            const entry = sessions.get(sessionId);
-            if (entry) {
-                await entry.transport.close();
-                sessions.delete(sessionId);
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ status: 'session closed' }));
-                return;
+        if (req.method === 'DELETE') {
+            if (sessionId) {
+                const entry = sessions.get(sessionId);
+                if (entry) {
+                    await entry.transport.close();
+                    sessions.delete(sessionId);
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ status: 'session closed' }));
+                    return;
+                }
             }
+            res.writeHead(404, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Session not found' }));
+            return;
         }
-        res.writeHead(404, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: 'Session not found' }));
-        return;
+        if (req.method === 'POST') {
+            await handlePost(req, res, sessionId, serverFactory, cancellation.signal);
+            return;
+        }
+        res.writeHead(405, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Method not allowed' }));
     }
-    if (req.method === 'POST') {
-        await handlePost(req, res, sessionId, serverFactory);
-        return;
+    finally {
+        cancellation.dispose();
     }
-    res.writeHead(405, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ error: 'Method not allowed' }));
 }
 function installToolsListCompaction(transport) {
     const originalSend = transport.send.bind(transport);

package/dist/transports/middleware/with-telemetry.js

@@ -3,6 +3,7 @@ import { appendFile, mkdir } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { shouldSkip } from './overrides.js';
+import { TELEMETRY_CONSENT_VERSION } from '../../engine/telemetry/telemetry-store.js';
 /**
  * Project root resolution — tries to get from input args or falls back to cwd.
  */
@@ -27,7 +28,7 @@ export function isTelemetryEnabled(projectRoot) {
         return false;
     }
     if (process.env.PLANU_TELEMETRY === 'on') {
-        return true;
+        return process.env.PLANU_TELEMETRY_CONSENT_VERSION === String(TELEMETRY_CONSENT_VERSION);
     }
     // Read conventions.json for opt-in flag
     try {
@@ -38,7 +39,7 @@ export function isTelemetryEnabled(projectRoot) {
         const raw = readFileSync(conventionsPath, 'utf-8');
         const parsed = JSON.parse(raw);
         const telemetry = parsed.telemetry;
-        return telemetry?.enabled === true;
+        return telemetry?.enabled === true && telemetry.consentVersion === TELEMETRY_CONSENT_VERSION;
     }
     catch {
         return false;

package/dist/types/abortable-process.d.ts

@@ -12,6 +12,8 @@ export interface AbortableProcessOptions {
     timeoutMs: number;
     maxBufferBytes: number;
     signal?: AbortSignal;
+    /** Called synchronously after process-group termination has been requested. */
+    onCancellationAcknowledged?: () => void;
 }
 export interface ProjectCommandPlan {
     requestedCommand: string;

package/dist/types/advanced-framework.js

@@ -1,5 +1,3 @@
-// SPEC-597-EXEMPT: canonical type union (framework names enumerated for type safety)
-// — these literals ARE the canonical contract; no runtime detection logic to migrate.
 // Planu — Advanced framework detection types (SPEC-017b)
 export {};
 //# sourceMappingURL=advanced-framework.js.map

package/dist/types/atomic-upgrade.d.ts

@@ -0,0 +1,71 @@
+import type { SpawnSyncReturns } from 'node:child_process';
+import type { InstallationManifest, InstallationRecord } from '../cli/commands/install.js';
+export type UpgradePhase = 'after-runtime-verification' | 'before-adapter-switch' | 'after-adapter-switch' | 'before-manifest-switch' | 'after-manifest-switch' | 'after-trust-switch';
+export type UpgradeJournalState = 'prepared' | 'switching' | 'trust-switched' | 'committed';
+export interface UpgradeJournal {
+    schemaVersion: 2;
+    state: UpgradeJournalState;
+    manifestPath: string;
+    previousVersion: string;
+    targetVersion: string;
+    originalManifest: string;
+    trustStatePath: string;
+    originalTrustState: string | null;
+    adapters: {
+        configPath: string;
+        original: string;
+    }[];
+    switchedPaths: string[];
+    updatedAt: string;
+}
+export interface ReleaseVerificationReport {
+    version: string;
+    cliPackage: string;
+    nativePackage: string;
+    cliVerified: true;
+    nativeVerified: true;
+    mcpSmokeVerified: true;
+    canaryVerified: true;
+    verifiedAt: string;
+}
+export interface QuarantinedNativeVersion {
+    version: string;
+    failedAt: string;
+    reason: 'verification-failed' | 'activation-failed';
+}
+export interface UpgradeTrustState {
+    schemaVersion: 1;
+    lastKnownGoodVersion: string;
+    lastVerifiedAt: string;
+    quarantined: QuarantinedNativeVersion[];
+}
+export interface UpgradeFaultContext {
+    phase: UpgradePhase;
+    adapter?: InstallationRecord;
+    switchedAdapters: number;
+}
+export interface AtomicUpgradeDependencies {
+    stageAndVerify?: (version: string) => Promise<ReleaseVerificationReport>;
+    writeFile?: (path: string, content: string) => Promise<void>;
+    faultInjector?: (context: UpgradeFaultContext) => void | Promise<void>;
+    now?: () => Date;
+}
+export interface AtomicUpgradeResult {
+    previousVersion: string;
+    version: string;
+    switchedAdapters: number;
+    manifest: InstallationManifest;
+    verification: ReleaseVerificationReport;
+}
+export interface PreparedUpgradeAdapter {
+    record: InstallationRecord;
+    original: string;
+    updated: string;
+}
+export type ReleaseCommandRunner = (command: string, args: readonly string[], options: {
+    encoding: 'utf8';
+    timeout: number;
+    env: NodeJS.ProcessEnv;
+    input?: string;
+}) => SpawnSyncReturns<string>;
+//# sourceMappingURL=atomic-upgrade.d.ts.map

package/dist/types/atomic-upgrade.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=atomic-upgrade.js.map

package/dist/types/ci.js

@@ -1,5 +1,3 @@
-// SPEC-597-EXEMPT: canonical type union (framework names enumerated for type safety)
-// — these literals ARE the canonical contract; no runtime detection logic to migrate.
 // Planu — CI/CD types (SPEC-066)
 export {};
 //# sourceMappingURL=ci.js.map

package/dist/types/core-bridge.d.ts

@@ -15,6 +15,79 @@ export interface SpecAnnotation {
     line: number;
     raw: string;
 }
+/** Versioned contract returned by a native runtime before it may execute work. */
+export interface NativeRuntimeHandshake {
+    engineVersion: string;
+    buildId: string;
+    protocolAbi: number;
+    capabilityAbi: number;
+    nodeApiAbi: number;
+    capabilities: string[];
+    storageSchemaMin: number;
+    storageSchemaMax: number;
+    target: string;
+}
+/** Externally generated release metadata stored next to the native artifact. */
+export interface NativeArtifactManifest extends NativeRuntimeHandshake {
+    schemaVersion: 2;
+    cliVersion: string;
+    artifactSha256: string;
+    platform: NodeJS.Platform;
+    arch: string;
+    libc: 'glibc' | 'musl' | null;
+    sbom: {
+        format: 'CycloneDX-1.5';
+        path: string;
+        sha256: string;
+    };
+    provenance: {
+        builder: string;
+        sourceCommit: string;
+        sourceTreeDirty: boolean;
+        sourceDateEpoch: number;
+        rustToolchain: string;
+        zigVersion: string | null;
+    };
+    signature: {
+        algorithm: 'Ed25519';
+        keyId: string;
+        value: string;
+    };
+}
+export interface NativeRuntimeCompatibility {
+    compatible: boolean;
+    reasons: string[];
+    handshake: NativeRuntimeHandshake | null;
+}
+export type NativeFallbackClass = 'optimization' | 'correctness-critical';
+export type NativeFallbackMode = 'typescript-visible-degradation' | 'fail-closed';
+export interface NativeCapabilityPolicy {
+    readonly capability: string;
+    readonly classification: NativeFallbackClass;
+    readonly fallback: NativeFallbackMode;
+    readonly parityContract: string;
+}
+export interface NativeCapabilityDiagnostic {
+    capability: string;
+    state: 'available' | 'degraded' | 'unavailable';
+    fallback: NativeFallbackMode;
+}
+export interface NativeLoadDiagnostic {
+    attempted: string[];
+    errors: string[];
+    loaded?: string;
+    artifactSha256?: string;
+    origin?: 'local' | 'package';
+    compatibility?: NativeRuntimeCompatibility;
+    rejectedOverrides?: string[];
+    capabilities?: NativeCapabilityDiagnostic[];
+    executionScope?: 'isolated-worker-and-keychain-port';
+}
+export interface NativePlatformInfo {
+    platform: NodeJS.Platform;
+    arch: string;
+    libc: 'glibc' | 'musl' | null;
+}
 export interface DriftResult {
     foundKeywords: string[];
     fileCount: number;
@@ -141,6 +214,8 @@ export interface ProjectGraphNeighborRs {
     relation: string;
 }
 export interface PlanuCore {
+    /** Mandatory for runtimes loaded by the versioned bridge. */
+    planuRuntimeHandshake?(): NativeRuntimeHandshake;
     hashProjectPath(projectPath: string): string;
     isSafeProjectId(projectId: string): boolean;
     getProjectDataPath(baseDir: string, project_id: string): string | null;
@@ -161,7 +236,9 @@ export interface PlanuCore {
     fastHnswSearchFlat(query: number[], nodes: VectorNode[], topK: number): SearchResult[];
     fastHmacSign(secret: string, data: string): string;
     fastHmacVerify(secret: string, data: string, signature: string): boolean;
-    startProjectWatcher(rootPath: string, callback: (err: Error | null, event: string) => void): void;
+    macosKeychainSet?(account: string, secret: Buffer): Promise<void>;
+    macosKeychainGet?(account: string): Promise<Buffer | null>;
+    macosKeychainDelete?(account: string): Promise<void>;
     scanProjectGraphSources?(rootPath: string, limits: ResolvedProjectGraphLimitsRs): ProjectGraphSourceFileRs[];
     extractTsRelations?(rootPath: string, paths: string[], limits: ResolvedProjectGraphLimitsRs): TsRelationRs[];
     queryAffectedNodes?(seed: string, edges: GraphEdgeInputRs[], relationFilter: string[], limits: ResolvedProjectGraphLimitsRs): AffectedNodeRs[];