configproof 0.3.0

package/dist/runtime/recorder.d.ts

@@ -0,0 +1,59 @@
+import { WatchSet, PathScrubber } from '../core/privacy';
+import { type AdapterManifest, type Observation, type Origin, type SafeValue, type Notice, type ProcessInfo } from '../core/schema';
+import type { RuntimeConfig } from './api';
+type ValueOperation = 'baseline' | 'read' | 'write' | 'delete' | 'candidate' | 'skip';
+interface RecordOptions {
+    before?: string;
+    hasBefore?: boolean;
+    candidate?: string;
+    hasCandidate?: boolean;
+    origin?: Origin;
+    outcome?: Observation['outcome'];
+    site?: Observation['site'];
+}
+export declare class Recorder {
+    readonly config: RuntimeConfig;
+    readonly watch: WatchSet;
+    readonly paths: PathScrubber;
+    readonly process: ProcessInfo;
+    private readonly writer;
+    private readonly start;
+    private readonly states;
+    private readonly keys;
+    private readonly notices;
+    private readonly origins;
+    private seq;
+    private count;
+    private dropped;
+    private depth;
+    private stopped;
+    private adapterIds;
+    sharedEnvironment: boolean;
+    constructor(config: RuntimeConfig, instanceId: string, parentId?: string, worker?: {
+        threadId: number;
+        environmentMode: ProcessInfo['environmentMode'];
+    });
+    get suppressed(): boolean;
+    suppress<T>(action: () => T): T;
+    withOrigin<T>(origin: Origin | ((key: string) => Origin), action: () => T): T;
+    currentOrigin(key: string): Origin | undefined;
+    token(key: string, value: string | undefined): SafeValue;
+    site(): Observation['site'];
+    latestId(key: string): string | undefined;
+    notice(notice: Notice): void;
+    private emit;
+    /** Instrumentation failures are contained; the original operation has already run. */
+    observe(operation: ValueOperation, key: string, raw: string | undefined, options?: RecordOptions): Observation | undefined;
+    declareAdapter(manifest: AdapterManifest, installedVersion?: string): void;
+    loader(file: string | undefined, outcome: 'read-success' | 'read-failed' | 'declared', options?: {
+        kind?: 'dotenv' | 'native-env';
+        phase?: 'startup' | 'runtime';
+        method?: Observation['loaderMethod'];
+        confidence?: Origin['confidence'];
+    }): void;
+    child(childId: string, outcome: 'spawned' | 'spawn-failed'): void;
+    worker(childId: string, outcome: 'spawned' | 'spawn-failed', environmentMode: Observation['environmentMode']): void;
+    boundary(kind: 'manual' | 'uncaught-exception'): Observation | undefined;
+    finish(exitCode: number): void;
+}
+export {};

package/dist/runtime/recorder.js

@@ -0,0 +1,254 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Recorder = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const privacy_1 = require("../core/privacy");
+const schema_1 = require("../core/schema");
+const callsite_1 = require("./callsite");
+class StreamWriter {
+    maxBytes;
+    fd;
+    bytes = 0;
+    closed = false;
+    failed = false;
+    constructor(file, maxBytes) {
+        this.maxBytes = maxBytes;
+        this.fd = node_fs_1.default.openSync(file, 'wx', 0o600);
+    }
+    write(record, reserved = false) {
+        if (this.closed || this.failed)
+            return false;
+        try {
+            const data = Buffer.from(JSON.stringify(record) + '\n');
+            if (!reserved && this.bytes + data.length > this.maxBytes - 8192)
+                return false;
+            if (this.bytes + data.length > this.maxBytes)
+                return false;
+            let offset = 0;
+            while (offset < data.length) {
+                const n = node_fs_1.default.writeSync(this.fd, data, offset, data.length - offset);
+                if (n <= 0)
+                    throw new Error('Recorder write failed');
+                offset += n;
+            }
+            this.bytes += data.length;
+            return true;
+        }
+        catch {
+            this.failed = true;
+            return false;
+        }
+    }
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            try {
+                node_fs_1.default.closeSync(this.fd);
+            }
+            catch {
+                this.failed = true;
+            }
+        }
+    }
+}
+class Recorder {
+    config;
+    watch;
+    paths;
+    process;
+    writer;
+    start = process.hrtime.bigint();
+    states = new Map();
+    keys = new Set();
+    notices = new Set();
+    origins = [];
+    seq = 0;
+    count = 0;
+    dropped = 0;
+    depth = 0;
+    stopped = false;
+    adapterIds = new Set();
+    sharedEnvironment = false;
+    constructor(config, instanceId, parentId, worker) {
+        this.config = config;
+        this.watch = new privacy_1.WatchSet(config.watch, process.platform === 'win32' && !worker);
+        this.paths = new privacy_1.PathScrubber(config.root, config.comparison.secret);
+        this.process = {
+            id: instanceId, parentId, role: worker ? 'worker' : parentId ? 'child' : 'root',
+            threadId: worker?.threadId, environmentMode: worker?.environmentMode,
+            caseMode: this.watch.insensitive ? 'insensitive' : 'sensitive',
+            pid: process.pid, ppid: process.ppid, node: process.version, platform: process.platform,
+            entry: this.paths.scrub(process.argv[1] || '<eval>'), startedAt: new Date().toISOString(),
+            ended: false, exitCode: null, eventsDropped: 0,
+        };
+        this.sharedEnvironment = worker?.environmentMode === 'shared';
+        this.writer = new StreamWriter(node_path_1.default.join(config.directory, `${instanceId}.jsonl`), config.maxBytes);
+        this.writer.write({ type: 'start', process: this.process }, true);
+    }
+    get suppressed() { return this.depth > 0 || this.stopped; }
+    suppress(action) { this.depth++; try {
+        return action();
+    }
+    finally {
+        this.depth--;
+    } }
+    withOrigin(origin, action) {
+        this.origins.push(typeof origin === 'function' ? origin : () => origin);
+        try {
+            return action();
+        }
+        finally {
+            this.origins.pop();
+        }
+    }
+    currentOrigin(key) { return this.origins.at(-1)?.(key); }
+    token(key, value) {
+        return (0, privacy_1.fingerprint)(this.config.comparison, this.watch.canonical(key), value);
+    }
+    site() { return this.suppress(() => (0, callsite_1.captureSite)(this.paths, this.config.sourceMaps)); }
+    latestId(key) { return this.states.get(this.watch.canonical(key))?.eventId; }
+    notice(notice) {
+        if (notice === 'worker_shared_env')
+            this.sharedEnvironment = true;
+        if (this.notices.has(notice) || this.stopped)
+            return;
+        this.notices.add(notice);
+        this.suppress(() => this.writer.write({ type: 'notice', notice }, true));
+    }
+    emit(event) {
+        if (this.stopped)
+            return;
+        if (this.count >= this.config.maxEvents) {
+            this.dropped++;
+            this.notice('event_limit');
+            return;
+        }
+        const seq = this.seq++;
+        const full = { ...event, id: `${this.process.id}:${seq}`, processId: this.process.id, seq, at: Number(process.hrtime.bigint() - this.start) / 1e6 };
+        if (!this.writer.write({ type: 'event', event: full })) {
+            this.dropped++;
+            this.notice(this.writer.failed ? 'recorder_failed' : 'byte_limit');
+            return;
+        }
+        this.count++;
+        return full;
+    }
+    /** Instrumentation failures are contained; the original operation has already run. */
+    observe(operation, key, raw, options = {}) {
+        if (this.suppressed || !this.watch.matches(key))
+            return;
+        return this.suppress(() => {
+            try {
+                key = this.watch.canonical(key);
+                if (!this.keys.has(key) && this.keys.size >= 256) {
+                    this.dropped++;
+                    this.notice('key_limit');
+                    return;
+                }
+                this.keys.add(key);
+                const value = this.token(key, raw);
+                const previous = this.states.get(key);
+                let origin = options.origin ?? this.currentOrigin(key);
+                let causedBy;
+                if (operation === 'read') {
+                    if (previous && (0, privacy_1.sameValue)(previous.value, value)) {
+                        causedBy = previous.eventId;
+                        origin = { ...previous.origin, confidence: 'inferred' };
+                    }
+                    else
+                        origin = { kind: 'unknown', confidence: 'unknown' };
+                }
+                if (!origin)
+                    origin = { kind: operation === 'baseline' ? 'startup' : 'runtime', confidence: 'observed' };
+                if (origin.file)
+                    origin = { ...origin, file: this.paths.scrub(origin.file) };
+                const event = this.emit({
+                    key, operation, value, origin, causedBy,
+                    before: options.hasBefore ? this.token(key, options.before) : undefined,
+                    candidate: options.hasCandidate ? this.token(key, options.candidate) : undefined,
+                    outcome: options.outcome,
+                    purpose: this.origins.length ? 'loader' : 'application',
+                    site: operation === 'baseline' ? undefined : options.site ?? (0, callsite_1.captureSite)(this.paths, this.config.sourceMaps),
+                });
+                if (event && ['baseline', 'write', 'delete'].includes(operation))
+                    this.states.set(key, { value, eventId: event.id, origin });
+                return event;
+            }
+            catch {
+                this.notice('recorder_failed');
+                return;
+            }
+        });
+    }
+    declareAdapter(manifest, installedVersion) {
+        try {
+            const checked = schema_1.AdapterManifestSchema.parse(manifest);
+            if (this.adapterIds.has(checked.id) || this.adapterIds.size >= 8)
+                return;
+            this.adapterIds.add(checked.id);
+            const written = this.suppress(() => this.writer.write({ type: 'adapter', declaration: {
+                    processId: this.process.id, manifest: checked,
+                    installedVersion: installedVersion?.slice(0, 80), validation: 'unverified',
+                } }, true));
+            if (!written) {
+                this.dropped++;
+                this.notice(this.writer.failed ? 'recorder_failed' : 'byte_limit');
+            }
+        }
+        catch {
+            this.notice('adapter_failed');
+        }
+    }
+    loader(file, outcome, options = {}) {
+        try {
+            this.suppress(() => this.emit({ operation: 'load', origin: {
+                    kind: options.kind || 'dotenv', confidence: options.confidence || (file ? 'observed' : 'unknown'),
+                    file: file ? this.paths.scrub(file) : undefined,
+                }, outcome, purpose: 'loader', phase: options.phase, loaderMethod: options.method }));
+        }
+        catch {
+            this.notice('recorder_failed');
+        }
+    }
+    child(childId, outcome) {
+        try {
+            this.suppress(() => this.emit({ operation: 'child-spawn', childId, outcome, site: (0, callsite_1.captureSite)(this.paths, this.config.sourceMaps) }));
+        }
+        catch {
+            this.notice('recorder_failed');
+        }
+    }
+    worker(childId, outcome, environmentMode) {
+        try {
+            this.suppress(() => this.emit({ operation: 'worker-spawn', childId, outcome, environmentMode, site: (0, callsite_1.captureSite)(this.paths, this.config.sourceMaps) }));
+        }
+        catch {
+            this.notice('recorder_failed');
+        }
+    }
+    boundary(kind) {
+        try {
+            this.notice('failure_boundary_recorded');
+            return this.suppress(() => this.emit({ operation: 'boundary', boundaryKind: kind, site: (0, callsite_1.captureSite)(this.paths, this.config.sourceMaps) }));
+        }
+        catch {
+            this.notice('recorder_failed');
+            return undefined;
+        }
+    }
+    finish(exitCode) {
+        if (this.stopped)
+            return;
+        this.suppress(() => {
+            this.writer.write({ type: 'end', exitCode, eventsDropped: this.dropped }, true);
+            this.writer.close();
+        });
+        this.stopped = true;
+    }
+}
+exports.Recorder = Recorder;
+//# sourceMappingURL=recorder.js.map

package/dist/runtime/recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.js","sourceRoot":"","sources":["../../src/runtime/recorder.ts"],"names":[],"mappings":"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"}

package/dist/runtime/workers.d.ts

@@ -0,0 +1,12 @@
+import type { Recorder } from './recorder';
+export declare const WORKER_SESSION_KEY = "__configtrace_worker_session_v1";
+export interface WorkerSession {
+    configPath: string;
+    id: string;
+    parentId: string;
+    depth: number;
+    environmentMode: 'copied' | 'explicit' | 'shared';
+}
+/** Consume the thread-local clone, without touching process.env (especially SHARE_ENV). */
+export declare function takeWorkerSession(): WorkerSession | undefined;
+export declare function installWorkers(recorder: Recorder, depth: number): () => void;

package/dist/runtime/workers.js

@@ -0,0 +1,127 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKER_SESSION_KEY = void 0;
+exports.takeWorkerSession = takeWorkerSession;
+exports.installWorkers = installWorkers;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_module_1 = require("node:module");
+const workers = require("node:worker_threads");
+const io_1 = require("../core/io");
+exports.WORKER_SESSION_KEY = '__configtrace_worker_session_v1';
+/** Consume the thread-local clone, without touching process.env (especially SHARE_ENV). */
+function takeWorkerSession() {
+    const value = workers.getEnvironmentData(exports.WORKER_SESSION_KEY);
+    workers.setEnvironmentData(exports.WORKER_SESSION_KEY, undefined);
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const v = value;
+    if (typeof v.configPath !== 'string' || typeof v.id !== 'string' || typeof v.parentId !== 'string'
+        || !Number.isInteger(v.depth) || !['copied', 'explicit', 'shared'].includes(v.environmentMode || ''))
+        return undefined;
+    return v;
+}
+function claimSlot(recorder) {
+    // Exclusive files make the worker budget session-wide, including workers in children.
+    for (let slot = 0; slot < recorder.config.maxWorkers; slot++) {
+        let fd;
+        try {
+            fd = node_fs_1.default.openSync(node_path_1.default.join(recorder.config.directory, `worker-slot-${slot}`), 'wx', 0o600);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                continue;
+            throw error;
+        }
+        node_fs_1.default.closeSync(fd);
+        return true;
+    }
+    return false;
+}
+function installWorkers(recorder, depth) {
+    if (!recorder.config.workers) {
+        recorder.notice('workers_disabled');
+        return () => { };
+    }
+    recorder.notice('workers_opt_in');
+    const module = workers;
+    const OriginalWorker = module.Worker;
+    const WrappedWorker = new Proxy(OriginalWorker, {
+        construct(target, args, newTarget) {
+            let prepared;
+            let session;
+            let previous = workers.getEnvironmentData(exports.WORKER_SESSION_KEY);
+            let mode = 'unknown';
+            try {
+                const options = args[1];
+                if (options !== undefined && (!options || typeof options !== 'object' || Object.getPrototypeOf(options) !== Object.prototype
+                    || Object.values(Object.getOwnPropertyDescriptors(options)).some(d => !('value' in d)))) {
+                    recorder.notice('worker_shape_unsupported');
+                }
+                else if (depth >= recorder.config.maxDepth)
+                    recorder.notice('worker_depth_limit');
+                else {
+                    const opts = options || {};
+                    const execArgv = opts.execArgv === undefined ? process.execArgv : opts.execArgv;
+                    if (!Array.isArray(execArgv) || !execArgv.every((arg) => typeof arg === 'string'))
+                        recorder.notice('worker_shape_unsupported');
+                    else if (!recorder.suppress(() => claimSlot(recorder)))
+                        recorder.notice('worker_count_limit');
+                    else {
+                        mode = opts.env === workers.SHARE_ENV ? 'shared' : opts.env === undefined ? 'copied' : 'explicit';
+                        if (mode === 'shared')
+                            recorder.notice('worker_shared_env');
+                        session = { configPath: recorder.config.configPath, id: (0, io_1.uniqueId)('p'), parentId: recorder.process.id, depth: depth + 1, environmentMode: mode };
+                        prepared = [args[0], { ...opts, execArgv: ['--require', recorder.config.preloadPath, ...execArgv] }];
+                        // Environment data is cloned synchronously by Worker construction. No env/workerData rewrite.
+                        previous = workers.getEnvironmentData(exports.WORKER_SESSION_KEY);
+                    }
+                }
+            }
+            catch {
+                prepared = undefined;
+                session = undefined;
+                recorder.notice('worker_shape_unsupported');
+            }
+            if (!prepared || !session)
+                return Reflect.construct(target, args, newTarget);
+            try {
+                workers.setEnvironmentData(exports.WORKER_SESSION_KEY, session);
+            }
+            catch {
+                recorder.notice('worker_shape_unsupported');
+                return Reflect.construct(target, args, newTarget);
+            }
+            try {
+                let instance;
+                try {
+                    instance = recorder.suppress(() => Reflect.construct(target, prepared, newTarget));
+                }
+                catch (error) {
+                    recorder.worker(session.id, 'spawn-failed', mode);
+                    throw error;
+                }
+                recorder.worker(session.id, 'spawned', mode);
+                return instance;
+            }
+            finally {
+                try {
+                    workers.setEnvironmentData(exports.WORKER_SESSION_KEY, previous);
+                }
+                catch {
+                    recorder.notice('adapter_failed');
+                }
+            }
+        },
+    });
+    module.Worker = WrappedWorker;
+    (0, node_module_1.syncBuiltinESMExports)();
+    return () => { if (module.Worker === WrappedWorker) {
+        module.Worker = OriginalWorker;
+        (0, node_module_1.syncBuiltinESMExports)();
+    } };
+}
+//# sourceMappingURL=workers.js.map

package/dist/runtime/workers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers.js","sourceRoot":"","sources":["../../src/runtime/workers.ts"],"names":[],"mappings":";;;;;;AAcA,8CAQC;AAWD,wCAkDC;AAnFD,sDAAyB;AACzB,0DAA6B;AAC7B,6CAAoD;AACpD,+CAAgD;AAGhD,mCAAsC;AAEzB,QAAA,kBAAkB,GAAG,iCAAiC,CAAC;AAKpE,2FAA2F;AAC3F,SAAgB,iBAAiB;IAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,kBAAkB,CAAC,0BAAkB,CAAC,CAAC;IAC7D,OAAO,CAAC,kBAAkB,CAAC,0BAAkB,EAAE,SAAS,CAAC,CAAC;IAC1D,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC1D,MAAM,CAAC,GAAG,KAA+B,CAAC;IAC1C,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ;WAC7F,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,eAAe,IAAI,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACzH,OAAO,CAAkB,CAAC;AAC5B,CAAC;AACD,SAAS,SAAS,CAAC,QAAkB;IACnC,sFAAsF;IACtF,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC;QAC7D,IAAI,EAAU,CAAC;QACf,IAAI,CAAC;YAAC,EAAE,GAAG,iBAAE,CAAC,QAAQ,CAAC,mBAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,eAAe,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAAC,CAAC;QACnG,OAAO,KAAK,EAAE,CAAC;YAAC,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAAC,MAAM,KAAK,CAAC;QAAC,CAAC;QAChG,iBAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAAC,OAAO,IAAI,CAAC;IAChC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AACD,SAAgB,cAAc,CAAC,QAAkB,EAAE,KAAa;IAC9D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAAC,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;IAAC,CAAC;IACvF,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,OAAuD,CAAC;IACvE,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IACrC,MAAM,aAAa,GAAG,IAAI,KAAK,CAAC,cAAc,EAAE;QAC9C,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS;YAC/B,IAAI,QAA+B,CAAC;YACpC,IAAI,OAAkC,CAAC;YACvC,IAAI,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC,0BAAkB,CAAC,CAAC;YAC9D,IAAI,IAAI,GAAmC,SAAS,CAAC;YACrD,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;gBACxB,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,MAAM,CAAC,SAAS;uBACvH,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,yBAAyB,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC1F,QAAQ,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;gBAC9C,CAAC;qBAAM,IAAI,KAAK,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ;oBAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;qBAC/E,CAAC;oBACJ,MAAM,IAAI,GAAG,OAAO,IAAI,EAAE,CAAC;oBAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC;oBAChF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC;wBAAE,QAAQ,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;yBACnI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;wBAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;yBACzF,CAAC;wBACJ,IAAI,GAAG,IAAI,CAAC,GAAG,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;wBAClG,IAAI,IAAI,KAAK,QAAQ;4BAAE,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;wBAC5D,OAAO,GAAG,EAAE,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,EAAE,IAAA,aAAQ,EAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;wBAChJ,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC;wBACrG,8FAA8F;wBAC9F,QAAQ,GAAG,OAAO,CAAC,kBAAkB,CAAC,0BAAkB,CAAC,CAAC;oBAC5D,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBAAC,QAAQ,GAAG,SAAS,CAAC;gBAAC,OAAO,GAAG,SAAS,CAAC;gBAAC,QAAQ,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;YAAC,CAAC;YACnG,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO;gBAAE,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YAC7E,IAAI,CAAC;gBAAC,OAAO,CAAC,kBAAkB,CAAC,0BAAkB,EAAE,OAAO,CAAC,CAAC;YAAC,CAAC;YAChE,MAAM,CAAC;gBAAC,QAAQ,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;gBAAC,OAAO,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;YAAC,CAAC;YACzG,IAAI,CAAC;gBACH,IAAI,QAAwB,CAAC;gBAC7B,IAAI,CAAC;oBAAC,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,QAAS,EAAE,SAAS,CAAC,CAAmB,CAAC;gBAAC,CAAC;gBAC9G,OAAO,KAAK,EAAE,CAAC;oBAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;oBAAC,MAAM,KAAK,CAAC;gBAAC,CAAC;gBACjF,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;gBAC7C,OAAO,QAAQ,CAAC;YAClB,CAAC;oBAAS,CAAC;gBACT,IAAI,CAAC;oBAAC,OAAO,CAAC,kBAAkB,CAAC,0BAAkB,EAAE,QAAQ,CAAC,CAAC;gBAAC,CAAC;gBACjE,MAAM,CAAC;oBAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;gBAAC,CAAC;YAC9C,CAAC;QACH,CAAC;KACF,CAAC,CAAC;IACH,MAAM,CAAC,MAAM,GAAG,aAAa,CAAC;IAC9B,IAAA,mCAAqB,GAAE,CAAC;IACxB,OAAO,GAAG,EAAE,GAAG,IAAI,MAAM,CAAC,MAAM,KAAK,aAAa,EAAE,CAAC;QAAC,MAAM,CAAC,MAAM,GAAG,cAAc,CAAC;QAAC,IAAA,mCAAqB,GAAE,CAAC;IAAC,CAAC,CAAC,CAAC,CAAC;AACrH,CAAC"}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,54 @@
+# Architecture — v0.3
+
+## Runtime path
+
+```text
+CLI direct Node launch
+  -> private temporary session + preload
+  -> selected process.env Proxy
+  -> dotenv / native env / trusted adapter observations
+  -> optional child and Worker preload propagation
+  -> in-memory keyed fingerprint boundary
+  -> bounded per-context JSONL streams + declarations/notices
+  -> collector validates contexts/order and records missing streams
+  -> configtrace/2 artifact
+```
+
+The launcher does not replace arbitrary shells. It passes through application output, exit codes, and signals where supported. The temporary session contains the comparison secret; it is restricted local state, not an exported artifact. Same-privilege application code is outside the isolation guarantee.
+
+## Analysis path
+
+```text
+readTrace / strict schema
+  -> context selection and captured key evidence
+  -> provenance DAG
+  -> paired diff / deterministic diagnosis / contracts / ordered drift
+  -> terminal, JSON, offline HTML
+  -> token-free authorized MCP projection
+```
+
+The provenance engine distinguishes observed operations from derived/inferred relationships. Context-local order and confirmed parent-child creation are the only ordering links used; it does not merge process or Worker timestamps into a global causal sequence. Source files are origins; read-site nodes are sinks; these identities are intentionally distinct.
+
+Diagnosis uses common call-site occurrence comparisons and bounded relevance intervals. A marker is explicit metadata without exception arguments. A nonzero exit does not create an invented first-failure boundary. Contracts evaluate captured evidence, with a separate inconclusive result. History compares adjacent entries in a chosen order, not unobserved deployment state.
+
+## Worker boundary
+
+The Worker constructor wrapper preserves `env` and `workerData`, injects preload arguments, and supplies context metadata through cloned environment data. Session-wide exclusive slot files bound instrumented creations; each Worker writes its own stream. Known children without streams are unconfirmed. Shared environments do not imply observed cross-thread writers.
+
+## Persistence and formats
+
+Core schemas and runtime capture remain in one npm package. Capture output uses configtrace/2; the reader retains configtrace/1 compatibility. Derived payloads have independent schema labels. Older binaries need not read new captures. Custom adapters must use the recorder for value-bearing observations and must not persist raw values independently.
+
+Artifact parse/byte/event limits protect normal read paths; they are not an application sandbox or a complete denial-of-service guarantee. Most typed library APIs assume parsed Trace objects. Disk inputs must pass through readTrace. Evidence files are unsigned and unauthenticated.
+
+## Module ownership
+
+- `core/`: schema, privacy, I/O, collection, original explanations/diffs, export.
+- `runtime/`: instrumentation, session/bootstrap, context capture, recorder lifecycle.
+- `adapters/`: dotenv, native env, declared adapter catalog.
+- `analysis/`: graph, diagnosis, contracts, history; no application execution.
+- `agent/`: tools-only MCP snapshots and token-free projections.
+- `report/`: offline HTML and local filtering.
+- `cli.ts`: validated command dispatch; execution is confined to explicit run/demo commands.
+
+See the README and requested-features document for scoped or unfinished behavior. No architecture claim is a test result.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,24 @@
+# Compatibility targets — NOT validated
+
+Every entry below is a source-level target. No platform, runtime, library, browser, or MCP client was exercised during this update. Existing v0.2 claims were not upgraded into test results.
+
+| Area | Target | Status / limitation |
+|---|---|---|
+| Node | 22.14+ within 22.x, 24.x | Unrun; engines enforced by manifest only where the package manager honors them. |
+| OS | Windows, Linux, macOS | Unrun; Windows Worker/main case behavior and filesystem permissions need special verification. |
+| Application modules | Direct Node CJS and ESM | Unrun; early preloads/retained references/native access may bypass hooks. |
+| TypeScript | Compiled JS with optional source maps | Unrun; no universal ts-node/tsx/framework loader claim. |
+| dotenv | 16.x / 17.x targets; development dependency 17.2.3 | Unrun; eager load/private CJS interception may alter behavior. |
+| Native env | process.loadEnvFile + util.parseEnv where available | Unrun; bounded extra file read yields inferred candidates. |
+| Startup env files | --env-file, --env-file-if-exists declarations | Conservative hints only; parsing occurs before preload. |
+| Workers | Plain-data options; copied/explicit/SHARE_ENV; direct constructor hook | Unrun, opt-in; no promise for early constructors, internal threads, custom loaders or accessor options. |
+| Children | Async direct Node spawn/execFile/fork paths within bounds | Unrun; no sync/shell/detached/general process tracing. |
+| HTML | Browser supporting inline SHA-256 CSP and local JS/DOM | Unrun; no browser or accessibility audit. |
+| MCP | Tools-only stdio; 2025-11-25 / 2025-06-18 negotiation | Unrun; no HTTP transport and no verified named-client configuration. |
+| Legacy artifact | configtrace/1, toolVersion 0.2.0 | Reader code accepts it; backward-read tests are unrun. |
+| New artifact | configtrace/2, toolVersion 0.3.0 | New capture target, unrun. |
+| node-config / convict / NestJS | No implementation | Planned catalog entries only. |
+
+Native-addon access, original process.env references, pre-instrumentation history, replaced environment objects, early/nested lifecycle paths, build-time/browser substitution, and late exit-handler operations are not fully observed.
+
+Record actual runtime, OS, dependency version, command, output, fixture expectation, result, and failure evidence before changing an entry to validated. Do not infer broad support from a single passing demo.

package/docs/PRIVACY.md

@@ -0,0 +1,17 @@
+# Privacy boundary and disclosure model
+
+Raw environment values are fingerprinted in the recorder before its event stream is serialized. HMAC inputs include the selected key identity. Explicitly paired runs share a private domain key; unrelated domains are not treated as comparable. New value metadata distinguishes empty from missing. This is intentional information disclosure, not a plaintext-value feature.
+
+Temporary native-loader candidate maps and before/after snapshots hold raw strings briefly in memory. The extra bounded candidate read uses Node's parser. Maps are cleared after the call, but JavaScript strings are not securely erased and the process is not a secret-isolated sandbox. The temporary session configuration holds the comparison key, as required for descendant recorders.
+
+Original artifacts retain fingerprints plus metadata such as key names, scrubbed paths, identities, timing, and sources. Local HTML replaces fingerprints with masked equality classes. DAG/diagnosis/verification/history payloads expose states and evidence rather than plaintext. MCP event projection also withholds fingerprints, comparison-domain identifiers, and secret keys. It authorizes snapshots explicitly and does not expose run/file-discovery/shell functions.
+
+Export generates a fresh keyed transformation and optional key aliases, preserving intended paired relationships. Minimal metadata drops OS PIDs, parent OS PIDs, thread IDs, timestamps, and adapter declarations. Exported context relationships remain pseudonymous. Disabling comparisons removes present-value equality information; missing state can remain visible. Removing loaders/call sites reduces what later policy or analysis can conclude.
+
+Sanitization does not certify that all arbitrary metadata is harmless. Paths, key names, source labels, application-chosen strings, event timing, relationships, and manifest text may identify users, infrastructure, or secrets. Review the actual exported files before sharing or authorizing an agent. A malicious producer can put sensitive content in metadata fields; the schema is not a secret detector.
+
+Application stdout/stderr are inherited, not captured or sanitized. Uncaught exceptions may still be printed by Node/application handlers. ConfigTrace's marker does not persist exception messages, but does not suppress the application's output. Never treat terminal transcripts as equivalent to sanitized artifacts.
+
+Windows permissions and race behavior require testing. Regular-file and size checks reject direct symlink inputs where implemented, but do not establish a sandbox against same-user races, malicious ancestors, or a cooperating application. Same-privilege code can inspect or tamper with recorder/session state. Artifacts are unsigned and not tamper-evident.
+
+No canary tests, dependency audits, secret scans, runtime privacy validation, or penetration tests were executed for this source-only delivery. See VALIDATION.md before using real credentials.

package/docs/VALIDATION.md

@@ -0,0 +1,42 @@
+# Validation guide
+
+## First local checks
+
+```sh
+npm install --ignore-scripts
+npm run typecheck
+npm run build
+npm test
+```
+
+These commands passed locally for the v0.3.0 release snapshot. Repeat them in a clean checkout and on each supported Node runtime before publishing. Resolve actual failures before marking anything complete. Use synthetic values and an isolated development directory.
+
+## Extended acceptance checklist
+
+- [ ] Compile the entire package and generated declarations on each supported Node/types target.
+- [ ] Re-run preserved v0.2 tests: env operation semantics, dotenv source handling, custom targets, paired export, failed streams, children, source maps, stdout/exit preservation, metadata escaping.
+- [ ] Read actual saved v0.2 artifacts and reject malformed v0.3 event/context references.
+- [ ] Prove DAG acyclicity over fixtures, repeated source/read sites, parent/child/Worker edges, and malicious ancestry.
+- [ ] Verify native runtime apply/skip/failure, option hints, missing files, optional files, Buffer/file-URL arguments, file races, parser-unavailable fallbacks, ESM imports, earlier references and disabling the adapter.
+- [ ] Compare instrumented and uninstrumented Worker outputs across copied, explicit, SHARE_ENV, nested, eval, execArgv overrides, constructor failures, depth/count limits, termination, missing footers, Windows key case and concurrent mutation.
+- [ ] Confirm no original environment or workerData rewriting, no added Worker error listener, and preserved application errors.
+- [ ] Check policy 0/2/3 results for missing/empty/present, unread keys, post-first-read transient changes, inferred/unknown sources, forbidden loaders, transformed exports, pair mismatch and partial coverage.
+- [ ] Check deterministic diagnosis ordering, shared/unrelated domains, missing sites, explicit/uncaught/no marker, post-boundary reads, and no fabricated causal verdict.
+- [ ] Check history ordering, first divergence in supplied series, new read sites, source/loader/mutation changes, coverage regressions, absent timestamps, file permissions/symlinks and budgets.
+- [ ] Open single/pair reports offline; inspect CSP, no requests, filtering, context selection, graph/timeline jumps, truncation notices, keyboard use and malicious metadata escaping.
+- [ ] Exercise MCP initialization/notifications/ping, supported and unsupported versions, fixed tool list, schemas, unauthorized aliases, paging, oversize input/output, EOF, invalid JSON, and protocol-only stdout.
+- [ ] Connect actual target coding clients. No client is considered verified until its specific configuration/handshake/tool calls are recorded.
+- [ ] Seed synthetic secrets in every value/exception/input path; inspect all created artifacts, reports, exports, and protocol responses. Separately confirm application stdout remains unsanitized.
+- [ ] Exercise malicious metadata and same-user tampering assumptions. Ensure documentation does not overclaim artifact authenticity.
+- [ ] Measure overhead, event loss and storage growth on named fixtures; publish actual raw results, not estimates.
+- [ ] Review dependency versions, security advisories, workflow action pins, runtime hooks and publication configuration.
+
+## Test material
+
+`tests/core.test.cjs` and `tests/integration.test.cjs` preserve the earlier acceptance sources. `tests/v03-analysis.test.cjs` covers new pure analysis/schema/report/agent behavior. `tests/v03-runtime.test.cjs` covers selected native loader/Worker/boundary paths. The automated suite passed locally, but these focused tests are not a substitute for the extended checks above.
+
+Fixtures use synthetic values only. `fixtures/v03-manifest.json` lists the new cases. Verify the GitHub workflow independently for each release.
+
+## Results record
+
+When executing, record: date, OS, exact Node version, installed dependency lockfile, commit/source digest, command, actual result, artifacts, interpretation, and unresolved cases. Keep failures visible. Do not label a passing policy as proof of complete runtime provenance.

package/fixtures/bypass/app.cjs

@@ -0,0 +1,6 @@
+if (globalThis.__configtraceSavedOriginalEnv) {
+  globalThis.__configtraceSavedOriginalEnv.CONFIGTRACE_FIXTURE = 'synthetic-bypass';
+  void globalThis.__configtraceSavedOriginalEnv.CONFIGTRACE_FIXTURE;
+}
+void process.env.CONFIGTRACE_FIXTURE;
+console.log('An original-reference bypass must not acquire a fictional write origin.');

package/fixtures/bypass/early.cjs

@@ -0,0 +1,2 @@
+// Load this BEFORE the ConfigTrace preload, using NODE_OPTIONS for the negative fixture.
+globalThis.__configtraceSavedOriginalEnv = process.env;

package/fixtures/child-process/child.cjs

@@ -0,0 +1,2 @@
+void process.env.CONFIGTRACE_FIXTURE;
+console.log('Child environment read.');