witnora 0.9.3 → 0.10.2

package/dist/design-partner-pilot.js

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { access, cp, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { compileAssuranceContract, diffAssuranceContracts, validateAssuranceContract } from "./assurance-contract.js";
+import { summarizeGenericEval } from "./generic-eval.js";
+import { inspectPrivacy, validatePrivacyManifest } from "./privacy-manifest.js";
+import { assertNotRevoked, verifyKeyCertificate, verifyRevocationJournal } from "./trust-v02.js";
+const execFileAsync = promisify(execFile);
+export function pilotPackageFiles(config) {
+    const command = "node docker/runtime/dist/cli.js design-partner";
+    const runner = (arguments_) => `import { spawnSync } from "node:child_process";\nimport { dirname, resolve } from "node:path";\nimport { fileURLToPath } from "node:url";\nconst kit = resolve(dirname(fileURLToPath(import.meta.url)), "..");\nconst cli = resolve(kit, "docker/runtime/dist/cli.js");\nconst result = spawnSync(process.execPath, [cli, "design-partner", ${arguments_.split(" ").map((value) => JSON.stringify(value)).join(", ")}, "--dir", kit], { stdio: "inherit" });\nprocess.exit(result.status ?? 1);\n`;
+    return {
+        "README.md": `# Witnora Design Partner Pilot\n\nThis package runs one consequential **sandbox** action through a customer-operated Gateway and a separately deployed outcome Probe. It produces a signed Evidence Packet that can be verified without Witnora Cloud.\n\nStart with [QUICKSTART.md](./QUICKSTART.md). After the normal path passes, run \`node scripts/failure-exercises.mjs\` to execute the seven safe adversarial exercises in an isolated temporary sandbox. The package does not enable a production GitHub write path.\n`,
+        "QUICKSTART.md": `# Quickstart\n\nThis first run is a synthetic local emulator. It needs no real GitHub token and performs no production write. Run every command from this directory.\n\n## 1. Configure local-only synthetic secrets\n\nCopy \`.env.example\` to \`.env\` and load it into your shell. The generated values are intentionally local dummy credentials; use a secret manager and real least-privilege credentials only for a separately reviewed live sandbox. Never commit \`.env\`.\n\nInstall the bundled, pinned Python verifier without using Witnora source code:\n\n\`\`\`bash\npython -m pip install ./verifiers/python\n\`\`\`\n\n## 2. Issue short-lived authorization\n\n\`\`\`bash\n${command} authorization issue --dir .\n\`\`\`\n\n## 3. Start the customer-owned topology\n\nThe explicit \`--env-file\` is required because the Compose file lives under \`docker/\`.\n\n\`\`\`bash\ndocker compose --env-file .env -f docker/compose.yml up -d --build target-sandbox probe\n${command} doctor --dir .\n${command} privacy inspect --dir .\n${command} dry-run --dir . --target-url http://127.0.0.1:4311\n\`\`\`\n\n## 4. Run and verify one sandbox action\n\n\`\`\`bash\ndocker compose --env-file .env -f docker/compose.yml --profile acceptance run --rm gateway-acceptance\ndocker compose --env-file .env -f docker/compose.yml --profile acceptance run --rm offline-verifier\n${command} verify-offline --dir . --packet acceptance/witnora-evidence-packet-v0.2.json --root trust/pinned-root.json --revocation-journal trust/revocation-journal.json\npython -m witnora_verifier.cli evidence acceptance/witnora-evidence-packet-v0.2.json --root trust/pinned-root.json --revocation-journal trust/revocation-journal.json\n${command} collect-support-bundle --dir .\n${command} pilot-report --dir .\n\`\`\`\n\nExpected result: one target transition, one independently observed outcome, TypeScript and Python verifier PASS, and no raw customer secret in the support bundle.\n`,
+        "ARCHITECTURE.md": `# Architecture\n\n- **Target sandbox** owns simulated read and write APIs.\n- **Gateway** is the only process with the write credential. It validates the exact signed Approval and one-use Grant before dispatch.\n- **Probe** has only a read credential and a separate signing key. It observes target state independently of the Gateway.\n- **Offline verifiers** pin the customer root and verify signatures, roles, scope, revocation, dispatch history, and outcome binding.\n\nContainer separation is tested. Customer-network and organizational separation are deployment choices and are not implied by this package.\n`,
+        "PRIVACY.md": `# Privacy\n\nRun \`${command} privacy inspect --dir .\` for the exact field-by-field disclosure plan. Raw prompts, credentials, action arguments, target results, and source code remain customer-local. The reference manifest sends only declared outcome/policy metadata and tenant-keyed commitments. Undeclared fields fail closed.\n`,
+        "SECURITY.md": `# Security boundaries\n\nThe pilot covers one configured sandbox action path. Direct writes with unmanaged credentials remain outside Witnora. Root private material is generated for a sandbox ceremony and should move to customer KMS/HSM custody before production. A bounded model check and internal role-separated review are not an external audit or proof of universal complete mediation.\n`,
+        "TROUBLESHOOTING.md": `# Troubleshooting\n\n1. Run \`${command} doctor --dir .\`.\n2. Follow the single **Next action** at the end.\n3. Run \`${command} collect-support-bundle --dir .\`.\n4. Share only the generated support bundle. It excludes private keys, credentials, prompts, raw arguments, raw results, cookies, and authorization headers.\n\nStable setup failures use FAIL or NOT_CONFIGURED instead of silently continuing.\n`,
+        "contract/assurance-contract.json": "__COPY_ROOT_CONTRACT__",
+        "privacy/privacy-manifest.json": "__COPY_ROOT_PRIVACY__",
+        "privacy/README.md": "# Privacy manifest\n\nThis directory contains the canonical customer disclosure declaration. The root-level copy remains only for v0.2 CLI compatibility and must have the same SHA-256 digest.\n",
+        "trust/README.md": "# Trust material\n\nVerify `pinned-root.json` out of band. Public certificates are shareable. Files under `secrets/` are private and must never enter source control or a support bundle.\n",
+        "trust/root-fingerprint.example": "Compare the exact rootFingerprint from trust/pinned-root.json through a separate trusted channel.\n",
+        "gateway/config.example.json": JSON.stringify({ mode: "single-use-sandbox-action", writeCredentialRef: `env:${config.writeCredentialEnv}`, targetUrl: config.targetUrl, failClosed: true }, null, 2),
+        "probe/config.example.json": JSON.stringify({ mode: "independent-read-observation", readCredentialRef: `env:${config.readCredentialEnv}`, probeUrl: config.probeUrl, rawStore: "customer_local_encrypted" }, null, 2),
+        "scripts/doctor.mjs": runner("doctor"),
+        "scripts/dry-run.mjs": runner("dry-run"),
+        "scripts/privacy-inspect.mjs": runner("privacy inspect"),
+        "scripts/collect-support-bundle.mjs": runner("collect-support-bundle"),
+        "scripts/run-acceptance.mjs": runner("run-acceptance"),
+        "scripts/recover.mjs": runner("recover-acceptance"),
+        "scripts/pilot-lifecycle.mjs": runner("pilot-lifecycle"),
+        "LIFECYCLE.md": `# Assurance lifecycle demonstration\n\nAfter the sandbox acceptance and both offline verifiers pass, run:\n\n\`\`\`bash\nnode scripts/pilot-lifecycle.mjs\n\`\`\`\n\nThe command imports the bundled Generic Eval, establishes a synthetic local release baseline, changes the Contract policy reference, and proves that the new scope becomes \`REVALIDATION_REQUIRED\`. It demonstrates lifecycle state semantics only; it is not an independent release decision.\n`,
+        "examples/generic-eval.json": JSON.stringify(genericEvalExample("0".repeat(64)), null, 2),
+        "expected-output/privacy-inspect.txt": "PROMPT\nLocation: customer only\nSent to Witnora Cloud: no\n\nOUTCOME STATUS\nSent to Witnora Cloud: yes\nExample: VERIFIED\n",
+        "expected-output/verification-report.txt": "overall: PASS\ntrust root: caller pinned\noutcome: VERIFIED\nreview strength: INTERNAL or NONE unless an external reviewer signs\n",
+        "FAILURE-EXERCISES.md": `# Safe failure exercises\n\nRun \`node scripts/failure-exercises.mjs\`. It creates a temporary local-only sandbox and intentionally demonstrates:\n\n1. parameter substitution blocked before dispatch;\n2. consumed Grant replay blocked without a second write;\n3. apparent success classified NOT_VERIFIED when target state is unchanged;\n4. crash after target success reconciled without redispatch;\n5. Probe observation replay rejected;\n6. revoked Probe certificate blocks future covered dispatch until rotation;\n7. packet tampering rejected by both bundled TypeScript and Python verifiers.\n\nThe command uses synthetic credentials and deletes its temporary target state unless \`WITNORA_E2E_KEEP_TEMP=1\` is set. Its machine-readable report is written to \`failure-exercises/design-partner-v02-e2e-report.json\`.\n`,
+    };
+}
+export async function snapshotPilotRuntime(outDir) {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    const cliDist = basename(moduleDirectory) === "src" ? resolve(moduleDirectory, "../dist") : moduleDirectory;
+    const probeDistCandidates = [join(cliDist, "vendor/witnora-probe"), resolve(cliDist, "../../witnora-probe/dist")];
+    const probeDist = await firstExistingDirectory(probeDistCandidates);
+    if (!probeDist)
+        throw new Error("The built Witnora package does not contain the Probe runtime. Run the Witnora build before generating a pilot kit.");
+    const pythonVerifierCandidates = [join(cliDist, "vendor/witnora-verifier-python"), resolve(cliDist, "../../witnora-verifier-python")];
+    const pythonVerifier = await firstExistingDirectory(pythonVerifierCandidates);
+    if (!pythonVerifier)
+        throw new Error("The built Witnora package does not contain the Python verifier. Run the Witnora build before generating a pilot kit.");
+    const runtime = join(outDir, "docker/runtime");
+    await mkdir(join(runtime, "dist/vendor"), { recursive: true });
+    await cp(cliDist, join(runtime, "dist"), { recursive: true, filter: (source) => !source.includes(`${join("vendor", "witnora-probe")}`) && !source.includes(`${join("vendor", "witnora-verifier-python")}`) });
+    await cp(probeDist, join(runtime, "dist/vendor/witnora-probe"), { recursive: true });
+    await cp(pythonVerifier, join(outDir, "verifiers/python"), { recursive: true });
+    await cp(join(cliDist, "vendor/design-partner/failure-exercises.mjs"), join(outDir, "scripts/failure-exercises.mjs"));
+    await writeFile(join(runtime, "package.json"), `${JSON.stringify({ name: "witnora-design-partner-runtime", private: true, type: "module", engines: { node: ">=20" } }, null, 2)}\n`);
+    await writeFile(join(runtime, "Dockerfile"), "FROM node:22-alpine\nWORKDIR /app\nCOPY package.json ./package.json\nCOPY dist ./dist\nUSER 10001:10001\nENTRYPOINT [\"node\", \"/app/dist/cli.js\"]\n");
+}
+export async function runPilotDoctor(dir, config) {
+    const checks = [];
+    const add = (area, status, message, nextAction) => checks.push({ area, status, message, ...(nextAction ? { nextAction } : {}) });
+    const major = Number(process.versions.node.split(".")[0]);
+    add("runtime", major >= 20 ? "PASS" : "FAIL", `Node ${process.versions.node}`, major >= 20 ? undefined : "Install Node 20 or newer.");
+    const required = ["witnora.assurance-contract.json", "witnora.privacy-manifest.json", "docker/compose.yml", "docker/runtime/Dockerfile", "trust/pinned-root.json", "trust/request-signer-certificate.json", "trust/gateway-certificate.json", "trust/probe-certificate.json", "trust/approval-certificate.json", "trust/grant-certificate.json", "trust/revocation-journal.json", "secrets/gateway-private.pem", "secrets/probe-private.pem", "authorization/approval.json", "authorization/grant.json"];
+    for (const relative of required)
+        add("package", await exists(join(dir, relative)) ? "PASS" : "NOT_CONFIGURED", `${relative}: ${await exists(join(dir, relative)) ? "present" : "missing"}`, `Create the missing file or rerun design-partner init in an empty directory.`);
+    try {
+        validateAssuranceContract(JSON.parse(await readFile(join(dir, "witnora.assurance-contract.json"), "utf8")));
+        add("package", "PASS", "Assurance Contract is valid.");
+    }
+    catch (error) {
+        add("package", "FAIL", errorMessage(error), "Restore a valid generated Assurance Contract.");
+    }
+    let manifest;
+    try {
+        manifest = validatePrivacyManifest(JSON.parse(await readFile(join(dir, "witnora.privacy-manifest.json"), "utf8")));
+        add("privacy", "PASS", "Privacy Manifest is strict and deny-by-default.");
+    }
+    catch (error) {
+        add("privacy", "FAIL", errorMessage(error), "Restore a valid generated Privacy Manifest; unknown fields are rejected.");
+    }
+    if (manifest) {
+        add("privacy", manifest.fields.prompt === "local_only" ? "PASS" : "FAIL", "Prompt is declared customer-local.");
+        add("privacy", manifest.fields.credentials === "local_only" ? "PASS" : "FAIL", "Credentials are declared customer-local.");
+        add("privacy", manifest.fields.actionParameters === "commit_only" ? "PASS" : "FAIL", "Raw action parameters are not disclosed.");
+        add("privacy", manifest.fields.rawResult === "local_only" ? "PASS" : "FAIL", "Raw target results are customer-local.");
+    }
+    add("privacy", config.legacyUnprotectedPathEnabled === true ? "FAIL" : "PASS", "Legacy unprotected path is disabled.", "Disable every legacy ingestion path for this pilot.");
+    const composeText = await readFile(join(dir, "docker/compose.yml"), "utf8").catch(() => "");
+    add("secrets", composeText.includes("probe-key-data:/app/keys:ro") && !composeServiceBlock(composeText, "probe").includes("WITNORA_GITHUB_WRITE_CREDENTIAL") ? "PASS" : "FAIL", "Probe has a role-specific read path and signing-key mount.", "Restore the generated Probe boundary.");
+    add("secrets", composeText.includes("gateway-key-data:/app/keys:ro") && !composeServiceBlock(composeText, "gateway-acceptance").includes("WITNORA_GITHUB_READ_CREDENTIAL") ? "PASS" : "FAIL", "Gateway has a role-specific write path and signing-key mount.", "Restore the generated Gateway boundary.");
+    const readCredential = process.env[config.readCredentialEnv];
+    const writeCredential = process.env[config.writeCredentialEnv];
+    if (!readCredential)
+        add("secrets", "NOT_CONFIGURED", `${config.readCredentialEnv} is not resolved.`, "Set the Probe read credential in the customer secret store.");
+    else
+        add("secrets", "PASS", "Probe read credential reference resolves locally.");
+    if (!writeCredential)
+        add("secrets", "NOT_CONFIGURED", `${config.writeCredentialEnv} is not resolved.`, "Set the Gateway write credential in the customer secret store.");
+    else
+        add("secrets", "PASS", "Gateway write credential reference resolves locally.");
+    if (readCredential && writeCredential)
+        add("secrets", readCredential === writeCredential ? "FAIL" : "PASS", readCredential === writeCredential ? "Read and write credentials are identical." : "Read and write credential values are distinct.", "Issue separate least-privilege credentials.");
+    try {
+        const root = await readJson(join(dir, "trust/pinned-root.json"));
+        const journal = await readJson(join(dir, "trust/revocation-journal.json"));
+        verifyRevocationJournal(journal, root);
+        add("trust", "PASS", `Pinned root ${root.rootFingerprint} and revocation journal are valid.`);
+        const bindings = { tenantRef: config.tenantRef, projectRef: config.projectRef, environment: config.environment };
+        const certificates = [["gateway", "gateway_runtime"], ["request-signer", "server_attestor"], ["probe", "outcome_probe"], ["approval", "reviewer"], ["grant", "resource_scope_evaluator"]];
+        for (const [name, role] of certificates) {
+            const certificate = await readJson(join(dir, `trust/${name}-certificate.json`));
+            verifyKeyCertificate(certificate, root, new Date(), { role, ...bindings });
+            assertNotRevoked(certificate, journal, new Date());
+            add("trust", "PASS", `${name} certificate is valid, role-bound, and active.`);
+        }
+    }
+    catch (error) {
+        add("trust", "FAIL", errorMessage(error), "Repair trust material before issuing or accepting a Grant.");
+    }
+    const docker = await commandAvailable("docker", ["version", "--format", "{{.Server.Version}}"]).catch(() => false);
+    add("runtime", docker ? "PASS" : "WARN", docker ? "Docker engine is available." : "Docker engine is unavailable; process-mode tests remain possible but container separation cannot be exercised.", "Start Docker before the container pilot.");
+    const targetHealthy = await endpointHealthy(`${localEndpoint(config.targetUrl)}/v0.2/github/pull-request`, readCredential ? { authorization: `Bearer ${readCredential}` } : undefined);
+    const probeHealthy = await endpointHealthy(`${localEndpoint(config.probeUrl)}/ready`);
+    add("target", targetHealthy ? "PASS" : "NOT_CONFIGURED", targetHealthy ? "Sandbox target is reachable." : "Sandbox target is not reachable.", "Start target-sandbox with docker compose.");
+    add("runtime", probeHealthy ? "PASS" : "NOT_CONFIGURED", probeHealthy ? "Probe is reachable and ready." : "Probe is not reachable.", "Start the Probe after the sandbox target.");
+    add("runtime", "PASS", "Gateway is a one-shot container with no persistent listening endpoint.");
+    add("target", config.environment === "sandbox" && !["main", "master"].includes(config.declaredTarget.baseBranch) ? "PASS" : "FAIL", "Target is allowlisted as a non-protected sandbox branch.", "Use a sandbox/test repository and non-main branch.");
+    const now = Date.now();
+    add("clock", now > Date.UTC(2024, 0, 1) && now < Date.UTC(2100, 0, 1) ? "PASS" : "FAIL", `Local UTC clock: ${new Date(now).toISOString()}`, "Synchronize the local clock.");
+    const summary = { PASS: 0, WARN: 0, FAIL: 0, NOT_CONFIGURED: 0 };
+    for (const check of checks)
+        summary[check.status] += 1;
+    const ready = summary.FAIL === 0 && summary.NOT_CONFIGURED === 0;
+    const nextAction = checks.find((check) => check.status === "FAIL")?.nextAction ?? checks.find((check) => check.status === "NOT_CONFIGURED")?.nextAction ?? checks.find((check) => check.status === "WARN")?.nextAction;
+    const report = { schemaVersion: "witnora.design_partner_doctor.v0.1", generatedAt: new Date().toISOString(), ready, checks, summary, ...(nextAction ? { nextAction } : {}) };
+    await writeJson(join(dir, "pilot/doctor-report.json"), report);
+    await updatePilotState(dir, (state) => ({
+        ...state,
+        ...(ready && !state.doctorReadyAt ? { doctorReadyAt: report.generatedAt } : {}),
+        ...(probeHealthy && !state.firstProbeHealthyAt ? { firstProbeHealthyAt: report.generatedAt } : {}),
+        failedSetupStepCount: state.failedSetupStepCount + summary.FAIL,
+        doctorWarningCount: summary.WARN,
+    }));
+    return report;
+}
+export function formatDoctorReport(report) {
+    const lines = report.checks.map((check) => `${check.status.padEnd(14)} ${check.area.toUpperCase().padEnd(8)} ${check.message}`);
+    lines.push("", report.ready ? "READY FOR DRY RUN" : "NOT READY");
+    if (report.nextAction)
+        lines.push(`Next action: ${report.nextAction}`);
+    return `${lines.join("\n")}\n`;
+}
+export function formatPrivacyInspection(manifestInput, config) {
+    const manifest = validatePrivacyManifest(manifestInput);
+    const sections = [
+        "WITNORA DESIGN PARTNER PRIVACY INSPECTION",
+        "",
+        "What Witnora Cloud can see",
+        ...privacyFields(manifest, "disclose").map((field) => `- ${field}: declared metadata sent to ${manifest.cloudEndpoint.url}`),
+        "",
+        "What Witnora Cloud cannot see",
+        ...privacyFields(manifest, "local_only").map((field) => `- ${field}: customer only; not sent to Witnora Cloud`),
+        "",
+        "Values transformed into commitments",
+        ...privacyFields(manifest, "commit_only").map((field) => `- ${field}: tenant-scoped HMAC-SHA256 using customer-owned key ${manifest.tenantKeyId}`),
+        "",
+        "Credential and key ownership",
+        `- ${config.readCredentialEnv}: Probe only; never sent to Gateway or Witnora Cloud`,
+        `- ${config.writeCredentialEnv}: Gateway only; never sent to Probe or Witnora Cloud`,
+        "- Probe signing private key: Probe-only secret volume",
+        "- Gateway signing private key: Gateway-only secret volume",
+        `- Commitment key: ${manifest.keyOwnership.commitmentKey}; Hosted decryption capability: ${manifest.keyOwnership.hostedDecryptionCapability}`,
+        "",
+        "Retention and legacy paths",
+        `- Disclosed metadata retention: ${manifest.retentionDays} days`,
+        `- Raw artifacts: local at ${manifest.artifacts.localStore}; upload allowed: ${manifest.artifacts.rawUploadAllowed ? "yes" : "no"}`,
+        `- Legacy unprotected path enabled: ${config.legacyUnprotectedPathEnabled === true ? "yes (unsafe)" : "no"}`,
+        "- Unknown fields: denied by default",
+        "",
+        inspectPrivacy(manifest).trim(),
+    ];
+    return `${sections.join("\n")}\n`;
+}
+export async function collectSupportBundle(dir, config, outDir = join(dir, "support-bundle")) {
+    await mkdir(outDir, { recursive: true });
+    const contract = await readJson(join(dir, "witnora.assurance-contract.json"));
+    const manifest = await readJson(join(dir, "witnora.privacy-manifest.json"));
+    const root = await readJson(join(dir, "trust/pinned-root.json"));
+    const journal = await readJson(join(dir, "trust/revocation-journal.json"));
+    const certificates = await Promise.all(["gateway", "request-signer", "probe", "approval", "grant"].map(async (name) => {
+        const certificate = await readJson(join(dir, `trust/${name}-certificate.json`));
+        return { certificateId: certificate.certificateId, subjectKeyId: certificate.subjectKeyId, role: certificate.role, notBefore: certificate.notBefore, notAfter: certificate.notAfter, certificateDigest: certificate.certificateDigest };
+    }));
+    const bundle = {
+        schemaVersion: "witnora.design_partner_support_bundle.v0.1",
+        generatedAt: new Date().toISOString(),
+        versions: { node: process.version, platform: process.platform, architecture: process.arch, protocol: config.protocolVersion },
+        configuration: { environment: config.environment, targetOrigin: safeOrigin(config.targetUrl), probeOrigin: safeOrigin(config.probeUrl), readCredentialReference: `env:${config.readCredentialEnv}`, writeCredentialReference: `env:${config.writeCredentialEnv}`, legacyUnprotectedPathEnabled: config.legacyUnprotectedPathEnabled === true },
+        digests: { contract: sha256Json(contract), privacyManifest: sha256Json(manifest), revocationJournal: journal.checkpointDigest },
+        trust: { rootId: root.rootId, rootFingerprint: root.rootFingerprint, certificates },
+        health: {
+            target: await endpointHealthy(`${localEndpoint(config.targetUrl)}/v0.2/github/pull-request`, process.env[config.readCredentialEnv]
+                ? { authorization: `Bearer ${process.env[config.readCredentialEnv]}` }
+                : undefined),
+            probe: await endpointHealthy(`${localEndpoint(config.probeUrl)}/ready`),
+        },
+        stableErrors: await stableErrors(dir),
+        exclusions: ["prompts", "source code", "credentials", "private keys", "raw tool arguments", "raw tool results", "raw target data", "authorization headers", "cookies"],
+    };
+    const serialized = `${JSON.stringify(bundle, null, 2)}\n`;
+    const canaries = sensitiveEnvironmentValues();
+    const matches = scanSensitive(serialized, canaries);
+    if (matches.length)
+        throw new Error(`Support bundle privacy scan failed: ${matches.join(", ")}`);
+    const bundlePath = join(outDir, "support-bundle.json");
+    const scanPath = join(outDir, "privacy-scan.json");
+    await writeFile(bundlePath, serialized);
+    await writeJson(scanPath, { schemaVersion: "witnora.support_bundle_privacy_scan.v0.1", generatedAt: new Date().toISOString(), rawSecretCanaryMatches: 0, checkedEnvironmentSecretCount: canaries.length, status: "PASS" });
+    return { bundlePath, scanPath };
+}
+export async function initializePilotState(dir) {
+    const now = new Date().toISOString();
+    const state = { schemaVersion: "witnora.pilot_lifecycle_state.v0.1", pilotType: "synthetic_internal_pilot", setupStartedAt: now, firstValidContractAt: now, manualInterventionCount: 0, failedSetupStepCount: 0, doctorWarningCount: 0, privacyWarningCount: 0, trustErrorCount: 0, recoveryRequiredCount: 0 };
+    await writeJson(join(dir, "pilot/state.json"), state);
+}
+export async function markPilotLifecycle(dir, fields) {
+    await updatePilotState(dir, (state) => ({ ...state, ...fields, schemaVersion: "witnora.pilot_lifecycle_state.v0.1", pilotType: "synthetic_internal_pilot" }));
+}
+export async function writePilotAcceptanceReport(dir) {
+    const state = await readJson(join(dir, "pilot/state.json"));
+    const report = {
+        ...state,
+        schemaVersion: "witnora.pilot_acceptance_report.v0.1",
+        generatedAt: new Date().toISOString(),
+        ...durationFields(state),
+    };
+    await writeJson(join(dir, "pilot/witnora-pilot-acceptance-report-v0.1.json"), report);
+    return report;
+}
+export async function runPilotLifecycleDemonstration(dir) {
+    const evalReport = summarizeGenericEval(await readJson(join(dir, "examples/generic-eval.json")));
+    const contract = validateAssuranceContract(await readJson(join(dir, "witnora.assurance-contract.json")));
+    const compiled = compileAssuranceContract(contract);
+    const changed = structuredClone(contract);
+    changed.metadata.version += 1;
+    changed.authority.policyRef = `${contract.authority.policyRef}:scope-change-demo`;
+    const contractDiff = diffAssuranceContracts(contract, changed);
+    if (!contractDiff.revalidationRequired)
+        throw new Error("Synthetic scope change did not require revalidation.");
+    const result = {
+        schemaVersion: "witnora.design_partner_lifecycle_demo.v0.1",
+        pilotType: "synthetic_internal_pilot",
+        generatedAt: new Date().toISOString(),
+        stages: [
+            { stage: "GENERIC_EVAL_IMPORTED", status: "PASS", authority: evalReport.authority, establishesCurrentAssurance: false },
+            { stage: "SANDBOX_RELEASE_ASSURANCE_BASELINE", status: "ESTABLISHED_FOR_DEMONSTRATION", contractDigest: compiled.sourceContractDigest, scopeFingerprint: compiled.revalidationFingerprint },
+            { stage: "CONTRACT_SCOPE_CHANGED", status: "PASS", changedPaths: contractDiff.changedPaths },
+            { stage: "CURRENT_ASSURANCE", status: "REVALIDATION_REQUIRED", reasons: contractDiff.reasons },
+        ],
+        limitation: "This local lifecycle demonstration validates state semantics. It is not an independent release decision or customer assurance result.",
+    };
+    await Promise.all([
+        writeJson(join(dir, "pilot/generic-eval-report.json"), evalReport),
+        writeJson(join(dir, "pilot/release-assurance-baseline.json"), { schemaVersion: "witnora.synthetic_release_assurance_baseline.v0.1", contractDigest: compiled.sourceContractDigest, scopeFingerprint: compiled.revalidationFingerprint, authority: "SYNTHETIC_INTERNAL_DEMONSTRATION" }),
+        writeJson(join(dir, "pilot/changed-assurance-contract.json"), changed),
+        writeJson(join(dir, "pilot/lifecycle-demonstration.json"), result),
+    ]);
+    return result;
+}
+export function referenceReleaseCandidateManifest() {
+    return {
+        schemaVersion: "witnora.reference_release_candidate.v0.1",
+        proposedTag: "design-partner-assurance-reference-v0.2",
+        mergeCommits: { privacyVerifiableV01: "PENDING_PR_115_MERGE", designPartnerV02: "PENDING_PR_116_MERGE" },
+        protocolVersions: ["witnora.assurance_contract.v0.1", "witnora.privacy_manifest.v0.1", "witnora.verifiable_evidence_packet.v0.1", "witnora.verifiable_evidence_packet.v0.2"],
+        canonicalizationVersions: ["witnora.canonical_json.v0.1", "witnora.canonical_json.v0.2"],
+        components: { typescriptVerifier: "0.10.0-rc", pythonVerifier: "0.2.0-rc", probe: "0.2.0-rc" },
+        digests: { schemas: "FINALIZE_AFTER_MERGE", tlcModel: "FINALIZE_AFTER_MERGE", tlcConfig: "FINALIZE_AFTER_MERGE", privacyCanaryTest: "FINALIZE_AFTER_MERGE", containerAcceptanceTest: "FINALIZE_AFTER_MERGE" },
+        knownLimitations: ["sandbox reference target only", "no production GitHub write path", "no external audit", "no organizational independence claim", "no HSM/KMS ceremony", "coverage is limited to declared mediated paths"],
+    };
+}
+async function updatePilotState(dir, update) {
+    const path = join(dir, "pilot/state.json");
+    const state = await readJson(path);
+    await writeJson(path, update(state));
+}
+function durationFields(state) {
+    const elapsed = (end) => end ? new Date(end).getTime() - new Date(state.setupStartedAt).getTime() : undefined;
+    return { timeToDoctorReady: elapsed(state.doctorReadyAt), timeToFirstEvidence: elapsed(state.firstSignedObservationAt), timeToVerifiedOutcome: elapsed(state.firstVerifiedOutcomeAt), timeToOfflineVerification: elapsed(state.firstOfflineVerificationAt) };
+}
+export function genericEvalExample(scopeFingerprint) {
+    return {
+        schemaVersion: "witnora.generic_eval.v0.1",
+        suite: "design-partner-sandbox-v0.2",
+        agent: { name: "design-partner-github-agent", version: "0.2.0", framework: "customer-workflow" },
+        environment: "sandbox",
+        scopeFingerprint,
+        cases: [{
+                id: "sandbox-pr-preconditions",
+                capability: "github.pull_request.merge",
+                task: "Validate the declared sandbox pull-request preconditions.",
+                prohibitedActions: ["merge protected branch", "change undeclared repository"],
+                reportedSuccess: true,
+                observedOutcome: "SATISFIED",
+                outcomePredicate: "open=true and merged=false and required checks=success",
+                evaluator: "customer-operated read-only Probe",
+                limitations: ["Single synthetic fixture; not a statistical reliability claim."],
+                resultStatus: "PASSED",
+                latencyMs: 0,
+                tokenUsage: 0,
+                costUsd: 0,
+            }],
+    };
+}
+async function firstExistingDirectory(paths) {
+    for (const path of paths) {
+        try {
+            if ((await stat(path)).isDirectory())
+                return path;
+        }
+        catch { /* continue */ }
+    }
+    return undefined;
+}
+async function exists(path) { try {
+    await access(path);
+    return true;
+}
+catch {
+    return false;
+} }
+async function readJson(path) { return JSON.parse(await readFile(path, "utf8")); }
+async function writeJson(path, value) { await mkdir(dirname(path), { recursive: true }); await writeFile(path, `${JSON.stringify(value, null, 2)}\n`); }
+function errorMessage(error) { return error instanceof Error ? error.message.split("\n")[0] : String(error); }
+function privacyFields(manifest, disposition) { return Object.entries(manifest.fields).filter(([, value]) => value === disposition).map(([field]) => field).sort(); }
+function sha256Json(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function safeOrigin(value) { try {
+    const url = new URL(value);
+    return `${url.protocol}//${url.host}`;
+}
+catch {
+    return "invalid";
+} }
+function localEndpoint(value) { try {
+    const url = new URL(value);
+    if (["target-sandbox", "probe"].includes(url.hostname))
+        url.hostname = "127.0.0.1";
+    return url.origin;
+}
+catch {
+    return value;
+} }
+function composeServiceBlock(compose, service) {
+    const marker = `  ${service}:`;
+    const start = compose.indexOf(marker);
+    if (start < 0)
+        return "";
+    const remainder = compose.slice(start + marker.length);
+    const next = remainder.search(/^  [a-z0-9][a-z0-9-]*:\s*$/mu);
+    const top = remainder.search(/^[a-z][a-z0-9-]*:\s*$/mu);
+    const stops = [next, top].filter((index) => index >= 0);
+    return stops.length ? remainder.slice(0, Math.min(...stops)) : remainder;
+}
+async function endpointHealthy(url, headers) { try {
+    const response = await fetch(url, { headers, signal: AbortSignal.timeout(750) });
+    return response.ok;
+}
+catch {
+    return false;
+} }
+async function commandAvailable(command, args) { try {
+    await execFileAsync(command, args, { timeout: 2_000, windowsHide: true });
+    return true;
+}
+catch {
+    return false;
+} }
+function sensitiveEnvironmentValues() { return Object.entries(process.env).filter(([name, value]) => value && /(secret|credential|token|private.*key|cookie|authorization|canary)/iu.test(name) && value.length >= 8).map(([, value]) => value); }
+function scanSensitive(value, canaries) {
+    const matches = [];
+    if (/-----BEGIN [A-Z ]*PRIVATE KEY-----/u.test(value))
+        matches.push("private_key");
+    if (/\bBearer\s+[A-Za-z0-9._~+\/-]{8,}/u.test(value))
+        matches.push("authorization_header");
+    if (/\b(?:sk|rk)_(?:live|test|proj)_[A-Za-z0-9_-]{8,}/u.test(value))
+        matches.push("provider_secret");
+    canaries.forEach((canary, index) => { if (value.includes(canary))
+        matches.push(`environment_secret_${index}`); });
+    return matches;
+}
+async function stableErrors(dir) {
+    const reportPath = join(dir, "pilot/doctor-report.json");
+    if (!(await exists(reportPath)))
+        return [];
+    const report = await readJson(reportPath);
+    return report.checks.filter((check) => check.status === "FAIL" || check.status === "NOT_CONFIGURED").map((check) => `${check.status}:${check.area}:${check.message}`);
+}