@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/agent/runtime/remote_resources.d.ts

@@ -0,0 +1,29 @@
+import type { Tool } from '../tools/types.js';
+import { type RemoteBrokerConfiguration } from './remote_broker_transport.js';
+export { RemoteResourceRejectedError } from './remote_resource_errors.js';
+export interface RemoteResource {
+    id: string;
+    host: string;
+    user: string;
+    port?: number;
+    root: string;
+    broker?: RemoteBrokerConfiguration;
+}
+/** Host-only process boundary. Model arguments cannot replace the transport. */
+export type RemoteResourceTransport = (resource: Readonly<RemoteResource>, request: Readonly<Record<string, unknown>>, signal?: AbortSignal) => Promise<unknown>;
+export interface RemoteResourceSession {
+    ownerId: string;
+    resources: readonly RemoteResource[];
+    transport?: RemoteResourceTransport;
+    /** Host-only durable journal location; never accepted from model arguments. */
+    journalDirectory?: string;
+}
+export declare function remoteResourceOwnerId(sessionId: string): string;
+/** A session's guard remains active through agent reloads and queued messages. */
+export declare function guardedRemoteSession(sessionId: string, resources?: readonly RemoteResource[], transport?: RemoteResourceTransport, journalDirectory?: string): RemoteResourceSession | undefined;
+/** Legacy entry point retained to refuse unsafe callers explicitly. */
+export declare const sshRemoteResourceTransport: RemoteResourceTransport;
+export declare function requestRemoteResource(session: RemoteResourceSession, resourceId: string, operation: string, args?: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+export declare function createRemoteResourceTool(session: RemoteResourceSession): Tool;
+/** Object identity prevents a plugin or alias from spoofing the broker's name. */
+export declare function isManagedRemoteResourceTool(tool: Tool, session: RemoteResourceSession): boolean;

package/dist/agent/runtime/remote_resources.js

@@ -0,0 +1,160 @@
+import { isIP } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { ToolCapability } from './capabilities.js';
+import { remoteResourceEndpoint } from './remote_resource_endpoint.js';
+import { makeRemoteBrokerTransport } from './remote_broker_transport.js';
+import { RemoteResourceRejectedError } from './remote_resource_errors.js';
+import { reserveUserSubprocessCredentials } from '../../utils/subprocess_env.js';
+export { RemoteResourceRejectedError } from './remote_resource_errors.js';
+import { admitRemoteMutation, findRemoteMutation, pendingRemoteMutations, remoteMutationJournalDirectory, resolveRemoteMutation } from './remote_mutation_journal.js';
+const identities = new Map();
+const sessions = new Map();
+const managedTools = new WeakMap();
+export function remoteResourceOwnerId(sessionId) {
+    let id = identities.get(sessionId);
+    if (!id) {
+        id = randomUUID();
+        identities.set(sessionId, id);
+    }
+    return id;
+}
+/** A session's guard remains active through agent reloads and queued messages. */
+export function guardedRemoteSession(sessionId, resources, transport, journalDirectory) {
+    const existing = sessions.get(sessionId);
+    if (existing)
+        return existing;
+    if (resources === undefined)
+        return undefined;
+    if (!Array.isArray(resources))
+        throw new Error('Guarded remote resources must be an array');
+    if (resources.length > 100)
+        throw new Error('At most 100 guarded remote resources may be configured');
+    const copy = resources.map(resource => Object.freeze({ ...resource, ...(resource.broker ? { broker: Object.freeze({ ...resource.broker }) } : {}) }));
+    for (const resource of copy)
+        validateResource(resource);
+    if (new Set(copy.map(resource => resource.id)).size !== copy.length)
+        throw new Error('Remote resource IDs must be unique');
+    reserveUserSubprocessCredentials(copy.flatMap(resource => resource.broker ? [resource.broker.tokenEnv] : []));
+    const ownerId = remoteResourceOwnerId(sessionId);
+    const directory = remoteMutationJournalDirectory({ ownerId, resources: copy, journalDirectory });
+    const session = Object.freeze({ ownerId, resources: Object.freeze(copy), transport, journalDirectory: directory });
+    sessions.set(sessionId, session);
+    return session;
+}
+function validateResource(resource) {
+    if (typeof resource.id !== 'string' || typeof resource.host !== 'string' || typeof resource.user !== 'string' || typeof resource.root !== 'string'
+        || !resource.id || resource.id.length > 100 || !/^[a-zA-Z0-9._:-]+$/.test(resource.id)
+        || (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(resource.host) && isIP(resource.host) !== 6)
+        || !/^[a-zA-Z0-9_][a-zA-Z0-9._-]*$/.test(resource.user)
+        || !resource.root.startsWith('/') || resource.root.includes('\0')
+        || (resource.port !== undefined && (!Number.isSafeInteger(resource.port) || resource.port < 1 || resource.port > 65535))) {
+        throw new Error('Invalid host-managed remote resource configuration');
+    }
+}
+/** Legacy entry point retained to refuse unsafe callers explicitly. */
+export const sshRemoteResourceTransport = async () => {
+    throw new Error('Legacy SSH execution is unavailable in guarded sessions; configure an immutable RPC broker');
+};
+export async function requestRemoteResource(session, resourceId, operation, args = {}, signal) {
+    const resource = session.resources.find(candidate => candidate.id === resourceId);
+    if (!resource)
+        throw new Error(`Unknown host-managed resource: ${resourceId}`);
+    validateResource(resource);
+    const transport = session.transport ?? makeRemoteBrokerTransport(resource);
+    // Authority, IDs and durable linkage come from the host, after model arguments.
+    const mutation = (operation === 'delete' || operation === 'write') && args.dry_run !== true
+        ? admitRemoteMutation(session, resource, operation, args) : undefined;
+    const operationId = mutation?.id ?? (operation === 'delete' ? randomUUID() : undefined);
+    const bound = { client_journal: remoteMutationJournalDirectory(session), root: resource.root, owner_id: session.ownerId, resource_id: resource.id,
+        endpoint: remoteResourceEndpoint(resource) };
+    const local = ['reconcile', 'resolve', 'receipt'].includes(operation) && typeof args.receipt_id === 'string'
+        ? findRemoteMutation(session, args.receipt_id) : undefined;
+    if (local && operation !== 'receipt' && (local.endpoint.host !== resource.host || local.endpoint.user !== resource.user || local.endpoint.port !== remoteResourceEndpoint(resource).port
+        || local.resource_id !== resource.id || local.target !== posix.resolve(resource.root, local.requested_path)))
+        throw new Error('Operation does not belong to this configured endpoint and root');
+    let dispatchReturned = false;
+    try {
+        const result = await transport(resource, { ...args, ...(local ? { path: local.requested_path, original_operation: local.operation, original_owner_id: local.owner_id, original_tool_call_id: local.tool_call_id } : {}), ...bound, operation,
+            ...(operationId ? { operation_id: operationId } : {}) }, signal);
+        dispatchReturned = true;
+        if (operationId || operation === 'receipt') {
+            const receipt = result?.receipt;
+            const endpoint = receipt?.endpoint;
+            if (!receipt || receipt.version !== 1 || !['delete', 'write'].includes(String(receipt.operation))
+                || (local && receipt.operation !== local.operation)
+                || receipt.id !== (operationId ?? args.receipt_id) || receipt.owner_id !== session.ownerId
+                || receipt.resource_id !== resource.id || receipt.configured_root !== resource.root
+                || endpoint?.host !== resource.host || endpoint?.user !== resource.user || endpoint?.port !== remoteResourceEndpoint(resource).port
+                || (operationId && (receipt.operation !== operation || receipt.requested_path !== (args.path ?? '.') || receipt.tool_call_id !== (args.tool_call_id ?? null)))) {
+                throw new Error('Remote deletion receipt does not match the exact host request');
+            }
+            if (mutation && ['verified', 'failed'].includes(String(receipt.status))) {
+                const acknowledged = await transport(resource, { ...bound, operation: 'ack', receipt_id: operationId }, signal);
+                if (acknowledged.receipt?.id !== mutation.id || acknowledged.receipt.admission_resolved !== true)
+                    throw new Error('Remote acknowledgement does not match the mutation');
+                receipt.admission_resolved = true;
+                resolveRemoteMutation(session, mutation.id);
+            }
+        }
+        if (operation === 'status') {
+            const status = result;
+            try {
+                const pending = pendingRemoteMutations(session, resource);
+                status.local_pending_operations = pending.operations;
+                status.local_pending_operation_count = pending.count;
+            }
+            catch (error) {
+                status.local_mutation_journal_error = error.message;
+            }
+        }
+        if (operation === 'resolve') {
+            const resolved = result;
+            if (!resolved || !resolved.receipt || resolved.receipt.id !== args.receipt_id || resolved.receipt.admission_resolved !== true
+                || resolved.observation?.receipt_id !== args.receipt_id || resolved.observation_token !== args.observation_token
+                || resolved.decision !== 'accept_current_state')
+                throw new Error('Remote reconciliation does not match the confirmed operation and observation');
+            resolveRemoteMutation(session, String(args.receipt_id));
+        }
+        return result;
+    }
+    catch (error) {
+        if (mutation && !dispatchReturned && error instanceof RemoteResourceRejectedError && error.operationId === mutation.id) {
+            resolveRemoteMutation(session, mutation.id, 'not_dispatched');
+            throw new Error(`Remote mutation rejected before effect; operation ${mutation.id}. ${error.message}`);
+        }
+        if (operationId)
+            throw new Error(`Remote ${operation === 'delete' ? 'deletion' : 'mutation'} outcome unresolved; operation ${operationId}. Inspect its receipt and reconcile through /resources before retrying. ${error.message}`);
+        throw error;
+    }
+}
+export function createRemoteResourceTool(session) {
+    reserveUserSubprocessCredentials(session.resources.flatMap(resource => resource.broker ? [resource.broker.tokenEnv] : []));
+    const tool = {
+        capabilities: [ToolCapability.NETWORK, ToolCapability.FILE_READ, ToolCapability.FILE_WRITE],
+        effect: 'external',
+        definition: {
+            name: 'remote_resource',
+            description: 'Operate on a host-configured remote resource under its required lease. Status shows your host-assigned owner label and the current owner. Labels identify cooperative host sessions; the bearer credential authenticates the host, not individual owners. Ask the user to claim or transfer through /resources. Arbitrary remote commands are unavailable. Use dry_run before mutation; deletion removes a file or empty directory only. Deletion returns a durable receipt with verified target state. Removed logical bytes do not establish reclaimed quota or free space; attribution is unknown without measurement. Unresolved writes and deletions fence overlapping targets. Inspect receipt after any unresolved result; ask the user to reconcile through /resources. Never retry mutations automatically.',
+            parameters: { type: 'object', properties: {
+                    resource: { type: 'string', description: 'Host-configured resource ID', enum: session.resources.map(resource => resource.id) },
+                    operation: { type: 'string', description: 'Bounded filesystem operation', enum: ['status', 'read', 'list', 'stat', 'write', 'delete', 'receipt'] },
+                    path: { type: 'string', description: 'Path relative to the configured remote root' },
+                    receipt_id: { type: 'string', description: 'Exact operation UUID to inspect after an interrupted or uncertain deletion' },
+                    content: { type: 'string', description: 'UTF-8 text for a write' }, dry_run: { type: 'boolean', description: 'Validate ownership and target without changing the target' },
+                }, required: ['resource', 'operation'] },
+        },
+        execute: async (args, context) => {
+            const operation = String(args.operation);
+            if (!['status', 'read', 'list', 'stat', 'write', 'delete', 'receipt'].includes(operation))
+                throw new Error('Lease control requires a confirmed user /resources command');
+            const result = await requestRemoteResource(session, String(args.resource), operation, { path: args.path ?? '.', content: args.content, dry_run: args.dry_run ?? false,
+                receipt_id: args.receipt_id, tool_call_id: context?.toolCallId }, context?.signal);
+            return JSON.stringify({ resource: args.resource, requesting_owner_id: session.ownerId, result });
+        },
+    };
+    managedTools.set(tool, session);
+    return tool;
+}
+/** Object identity prevents a plugin or alias from spoofing the broker's name. */
+export function isManagedRemoteResourceTool(tool, session) { return managedTools.get(tool) === session; }

package/dist/agent/runtime/source_verification.d.ts

@@ -0,0 +1,12 @@
+import { type CommandVerificationReceipt, type CurrentVerificationProjection, type SourceSnapshot, type VerificationRequest } from './source_verification_contract.js';
+export type SourceInspectionGate = (source: SourceSnapshot) => boolean | Promise<boolean>;
+export declare const SOURCE_FILE_MAX_BYTES: number;
+export declare const SOURCE_CAPTURE_MAX_BYTES: number;
+/** Capture only declared files. This is a sequence of bounded observations, not an atomic input snapshot. */
+export declare function captureSourceSnapshot(cwd: string, sourcePaths: readonly string[], options?: {
+    includeGit?: boolean;
+}): Promise<SourceSnapshot>;
+export declare function createCommandVerification(request: VerificationRequest, cwd: string, command: string, kind: CommandVerificationReceipt['command_kind']): Promise<CommandVerificationReceipt>;
+export declare function finishCommandVerification(receipt: CommandVerificationReceipt, outcome: CommandVerificationReceipt['process_outcome'], canInspectSource?: SourceInspectionGate): Promise<CommandVerificationReceipt>;
+/** Current applicability is a fresh projection; never replace the original or terminal source capture. */
+export declare function projectCurrentVerification(receipt: CommandVerificationReceipt, canInspectSource?: SourceInspectionGate): Promise<CurrentVerificationProjection>;

package/dist/agent/runtime/source_verification.js

@@ -0,0 +1,210 @@
+import { execFile } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { canonicalSourceContent, canonicalSourceIdentity, parseCommandVerificationReceipt, parseSourceSnapshot, SOURCE_SNAPSHOT_MAX_BYTES } from './source_verification_contract.js';
+export const SOURCE_FILE_MAX_BYTES = 2 * 1024 * 1024;
+export const SOURCE_CAPTURE_MAX_BYTES = 8 * 1024 * 1024;
+const exec = promisify(execFile);
+const digest = (text) => createHash('sha256').update(text).digest('hex');
+const within = (root, path) => {
+    const suffix = relative(root, path);
+    return !isAbsolute(suffix) && suffix !== '..' && !suffix.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`);
+};
+/** Resolve the nearest existing ancestor too: a missing leaf cannot hide an escaped parent. */
+async function assertScopedLocation(root, path) {
+    let probe = path;
+    while (true) {
+        try {
+            const resolved = await realpath(probe);
+            if (!within(root, resolved))
+                throw new Error('Source verification path escapes its working directory');
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'ELOOP' || code === 'EACCES' || code === 'EPERM')
+                return;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+            const parent = dirname(probe);
+            if (parent === probe)
+                throw new Error('Source verification working directory is unavailable');
+            probe = parent;
+        }
+    }
+}
+async function gitIdentity(cwd) {
+    // Read-only Git probes are bounded process-boundary observations, never shell text.
+    try {
+        const env = { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+        for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES'])
+            delete env[key];
+        const options = { cwd, timeout: 2000, maxBuffer: 256 * 1024, encoding: 'utf8',
+            env };
+        const [head, status] = await Promise.all([
+            exec('git', ['rev-parse', '--verify', 'HEAD'], options),
+            exec('git', ['-c', 'core.fsmonitor=false', 'status', '--porcelain=v1', '--untracked-files=normal'], options),
+        ]);
+        const commit = head.stdout.trim();
+        return { commit: /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(commit) ? commit : null, dirty: status.stdout.length > 0 };
+    }
+    catch {
+        return { commit: null, dirty: null };
+    }
+}
+function sealSnapshot(snapshot) {
+    const content = canonicalSourceContent(snapshot);
+    if (content === null)
+        throw new Error('Source verification snapshot is invalid');
+    snapshot.content_sha256 = digest(content);
+    const identity = canonicalSourceIdentity(snapshot);
+    if (identity === null)
+        throw new Error('Source verification identity is invalid');
+    snapshot.source_id = digest(identity);
+    const parsed = parseSourceSnapshot(snapshot);
+    if (parsed === null)
+        throw new Error('Source verification snapshot exceeds its metadata bound');
+    return parsed;
+}
+/** Capture only declared files. This is a sequence of bounded observations, not an atomic input snapshot. */
+export async function captureSourceSnapshot(cwd, sourcePaths, options = {}) {
+    const root = await realpath(resolve(cwd));
+    const paths = [...sourcePaths].sort();
+    if (paths.length < 1 || paths.length > 64 || new Set(paths).size !== paths.length
+        || paths.some(path => !path || Buffer.byteLength(path) > 512 || /[\\\u0000-\u001f\u007f]/u.test(path) || /^[A-Za-z]:/.test(path)
+            || path.split('/').some(part => !part || part === '.' || part === '..'))) {
+        throw new Error('Source verification requires 1–64 unique relative scoped file paths');
+    }
+    // Admit worst-case endpoint metadata before execution; later file changes cannot grow an unrepresentable receipt.
+    const worst = { schema_version: 1, source_id: 'f'.repeat(64), content_sha256: 'f'.repeat(64), cwd: root,
+        origin: 'local', captured_at: new Date().toISOString(), git: { commit: 'f'.repeat(64), dirty: false },
+        coverage: 'incomplete', files: paths.map(path => ({ path, kind: 'unavailable', sha256: 'f'.repeat(64),
+            bytes: Number.MAX_SAFE_INTEGER, mode: 4095 })), reason: 'x'.repeat(512) };
+    if (Buffer.byteLength(JSON.stringify(worst)) > SOURCE_SNAPSHOT_MAX_BYTES) {
+        throw new Error('Source verification snapshot metadata exceeds 16KiB; narrow source_paths');
+    }
+    for (const path of paths)
+        await assertScopedLocation(root, resolve(root, path));
+    const files = [];
+    let remaining = SOURCE_CAPTURE_MAX_BYTES;
+    for (const path of paths) {
+        const absolute = resolve(root, path);
+        let row = { path, kind: 'unavailable', sha256: null, bytes: 0, mode: 0 };
+        try {
+            await assertScopedLocation(root, absolute);
+            const stat = await lstat(absolute);
+            row.bytes = Number.isSafeInteger(stat.size) && stat.size >= 0 ? stat.size : 0;
+            row.mode = stat.mode & 0o7777;
+            // Symlink leaves are explicitly incomplete even when their target is inside the root.
+            if (stat.isFile() && stat.size <= SOURCE_FILE_MAX_BYTES && stat.size <= remaining) {
+                const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const before = await handle.stat();
+                    if (before.isFile() && before.size === stat.size && before.dev === stat.dev && before.ino === stat.ino) {
+                        const hash = createHash('sha256');
+                        const buffer = Buffer.alloc(Math.min(65536, Math.max(1, before.size)));
+                        let count = 0;
+                        while (count < before.size) {
+                            const read = await handle.read(buffer, 0, Math.min(buffer.length, before.size - count), count);
+                            if (read.bytesRead === 0)
+                                break;
+                            hash.update(buffer.subarray(0, read.bytesRead));
+                            count += read.bytesRead;
+                            remaining -= read.bytesRead;
+                        }
+                        const after = await handle.stat();
+                        if (count === before.size && after.size === before.size && after.mtimeMs === before.mtimeMs
+                            && after.ctimeMs === before.ctimeMs)
+                            row = { ...row, kind: 'file', sha256: hash.digest('hex') };
+                    }
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+        }
+        catch (error) {
+            if (error.message.includes('escapes its working directory'))
+                throw error;
+            if (error.code === 'ENOENT')
+                row = { path, kind: 'missing', sha256: null, bytes: 0, mode: 0 };
+        }
+        files.push(row);
+    }
+    const incomplete = files.some(file => file.kind !== 'file');
+    return sealSnapshot({ schema_version: 1, source_id: '0'.repeat(64), content_sha256: '0'.repeat(64), cwd: root,
+        origin: 'local', captured_at: new Date().toISOString(),
+        git: options.includeGit === false ? { commit: null, dirty: null } : await gitIdentity(root),
+        coverage: incomplete ? 'incomplete' : 'complete', files,
+        ...(incomplete ? { reason: 'Some scoped inputs were missing, unavailable, changed while read, or exceeded the capture budget.' } : {}) });
+}
+export async function createCommandVerification(request, cwd, command, kind) {
+    const source = await captureSourceSnapshot(cwd, request.source_paths);
+    const receipt = { schema_version: 1, receipt_id: randomUUID(), source, end_source: null,
+        purpose: request.purpose, scope: request.scope, command_sha256: digest(command), command_kind: kind,
+        environment: { platform: process.platform, arch: process.arch, node_version: process.version, declared_id: request.environment_id ?? null },
+        build_identity: request.build_identity ?? null, instrumentation: request.instrumentation,
+        process_outcome: 'running', source_binding: 'unknown', qualification: 'unverified', artifact_refs: [] };
+    const parsed = parseCommandVerificationReceipt(receipt);
+    if (parsed === null)
+        throw new Error('Source verification receipt exceeds its metadata bound');
+    return parsed;
+}
+export async function finishCommandVerification(receipt, outcome, canInspectSource) {
+    let end;
+    try {
+        if (canInspectSource && !await canInspectSource(receipt.source))
+            throw new Error('Source inspection permission denied');
+        end = await captureSourceSnapshot(receipt.source.cwd, receipt.source.files.map(file => file.path));
+    }
+    catch {
+        end = sealSnapshot({ ...structuredClone(receipt.source), captured_at: new Date().toISOString(),
+            coverage: 'incomplete', git: { commit: null, dirty: null },
+            files: receipt.source.files.map(file => ({ path: file.path, kind: 'unavailable', sha256: null, bytes: 0, mode: 0 })),
+            reason: 'The terminal scoped source capture was unavailable or source read permission was denied.' });
+    }
+    const value = { ...structuredClone(receipt), end_source: end, process_outcome: outcome,
+        source_binding: receipt.source.origin === 'local' && receipt.source.coverage === 'complete' && end.coverage === 'complete'
+            && end.source_id === receipt.source.source_id && outcome !== 'running' ? 'observed_endpoints' : 'unknown' };
+    const parsed = parseCommandVerificationReceipt(value);
+    if (parsed === null)
+        throw new Error('The terminal source verification receipt is invalid');
+    return parsed;
+}
+/** Current applicability is a fresh projection; never replace the original or terminal source capture. */
+export async function projectCurrentVerification(receipt, canInspectSource) {
+    const base = { receipt_id: receipt.receipt_id, checked_at: new Date().toISOString() };
+    if (receipt.source.origin !== 'local')
+        return { ...base, source_id: null, applicability: 'unknown',
+            reason: 'External reported source and artifacts cannot establish current local source applicability.' };
+    if (canInspectSource) {
+        let admitted = false;
+        try {
+            admitted = await canInspectSource(receipt.source);
+        }
+        catch { /* A failed admission cannot authorize a file read. */ }
+        if (!admitted)
+            return { ...base, source_id: null, applicability: 'unknown', reason: 'Current scoped source read permission was denied.' };
+    }
+    let current;
+    try {
+        current = await captureSourceSnapshot(receipt.source.cwd, receipt.source.files.map(file => file.path), { includeGit: false });
+    }
+    catch {
+        return { ...base, source_id: null, applicability: 'unknown', reason: 'Current scoped source is unavailable.' };
+    }
+    if (receipt.source.coverage !== 'complete' || current.coverage !== 'complete')
+        return { ...base,
+            source_id: current.source_id, applicability: 'unknown', reason: 'The original or current scoped capture is incomplete.' };
+    if (current.content_sha256 !== receipt.source.content_sha256)
+        return { ...base, source_id: current.source_id,
+            applicability: 'stale', reason: 'Current scoped source differs from the original command source observation; it is unverified by this result.' };
+    if (receipt.process_outcome !== 'running' && receipt.source_binding !== 'observed_endpoints')
+        return { ...base,
+            source_id: current.source_id, applicability: 'unknown', reason: 'Scoped bytes now match, but terminal input binding was not established.' };
+    return { ...base, source_id: current.source_id, applicability: 'current',
+        reason: 'Scoped bytes match the captured observation. Endpoint samples do not prove immutable execution or semantic qualification.' };
+}

package/dist/agent/runtime/source_verification_contract.d.ts

@@ -0,0 +1,75 @@
+/** Scoped byte observations and process outcomes never establish semantic qualification. */
+export interface VerificationRequest {
+    purpose: 'compile' | 'test' | 'benchmark' | 'qualification';
+    scope: string;
+    source_paths: string[];
+    environment_id?: string;
+    build_identity?: string;
+    instrumentation: 'production' | 'diagnostic' | 'unknown';
+}
+export interface SourceSnapshot {
+    schema_version: 1;
+    source_id: string;
+    content_sha256: string;
+    cwd: string;
+    origin: 'local' | 'external';
+    captured_at: string;
+    git: {
+        commit: string | null;
+        dirty: boolean | null;
+    };
+    coverage: 'complete' | 'incomplete';
+    files: {
+        path: string;
+        kind: 'file' | 'missing' | 'unavailable';
+        sha256: string | null;
+        bytes: number;
+        mode: number;
+    }[];
+    reason?: string;
+}
+export interface VerificationArtifactReference {
+    origin: 'local' | 'external';
+    path: string;
+    sha256: string;
+    source_observation_id?: string;
+}
+export interface CommandVerificationReceipt {
+    schema_version: 1;
+    receipt_id: string;
+    source: SourceSnapshot;
+    end_source: SourceSnapshot | null;
+    purpose: VerificationRequest['purpose'];
+    scope: string;
+    command_sha256: string;
+    command_kind: 'shell' | 'checked' | 'host_verifier';
+    environment: {
+        platform: string;
+        arch: string;
+        node_version: string;
+        declared_id: string | null;
+    };
+    build_identity: string | null;
+    instrumentation: VerificationRequest['instrumentation'];
+    process_outcome: 'running' | 'passed' | 'failed' | 'timed_out' | 'cancelled' | 'interrupted' | 'unknown';
+    source_binding: 'observed_endpoints' | 'unknown';
+    qualification: 'unverified';
+    artifact_refs: VerificationArtifactReference[];
+}
+export interface CurrentVerificationProjection {
+    receipt_id: string;
+    checked_at: string;
+    source_id: string | null;
+    applicability: 'current' | 'stale' | 'unknown';
+    reason: string;
+}
+export declare const VERIFICATION_REQUEST_MAX_BYTES: number;
+export declare const SOURCE_SNAPSHOT_MAX_BYTES: number;
+export declare const VERIFICATION_RECEIPT_MAX_BYTES: number;
+export declare function parseVerificationRequest(value: unknown): VerificationRequest | null;
+export declare function parseSourceSnapshot(value: unknown): SourceSnapshot | null;
+export declare function parseCommandVerificationReceipt(value: unknown): CommandVerificationReceipt | null;
+export declare function parseCurrentVerificationProjection(value: unknown): CurrentVerificationProjection | null;
+/** Canonical preimages, not digest verification. The host scanner hashes these observed fields. */
+export declare function canonicalSourceContent(value: unknown): string | null;
+export declare function canonicalSourceIdentity(value: unknown): string | null;