witnora 0.9.3 → 0.10.2

package/dist/generic-eval.js

@@ -0,0 +1,160 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { sha256Canonical } from "./canonical.js";
+export const GENERIC_EVAL_SCHEMA_VERSION = "witnora.generic_eval.v0.1";
+export const GENERIC_EVAL_REPORT_SCHEMA_VERSION = "witnora.generic_eval_report.v0.1";
+const OBSERVATION_STATUSES = ["SATISFIED", "NOT_SATISFIED", "NOT_OBSERVED", "INDETERMINATE", "EXCLUDED"];
+const TOP_LEVEL_FIELDS = new Set(["schemaVersion", "suite", "agent", "environment", "scopeFingerprint", "cases"]);
+const AGENT_FIELDS = new Set(["name", "version", "framework"]);
+const CASE_FIELDS = new Set(["id", "capability", "initialState", "task", "faultInjection", "prohibitedActions", "reportedSuccess", "reportedResult", "observedResult", "observedOutcome", "outcomePredicate", "evaluator", "limitations", "artifacts", "timestamps", "resultStatus", "costUsd", "latencyMs", "tokenUsage"]);
+export function validateGenericEval(input) {
+    const value = requireRecord(input, "generic eval");
+    rejectUnknown(value, TOP_LEVEL_FIELDS, "generic eval");
+    if (value.schemaVersion !== GENERIC_EVAL_SCHEMA_VERSION)
+        throw new Error(`schemaVersion must be ${GENERIC_EVAL_SCHEMA_VERSION}`);
+    const agent = requireRecord(value.agent, "agent");
+    rejectUnknown(agent, AGENT_FIELDS, "agent");
+    requireString(agent.name, "agent.name");
+    requireString(agent.version, "agent.version");
+    if (agent.framework !== undefined)
+        requireString(agent.framework, "agent.framework");
+    requireString(value.suite, "suite");
+    requireString(value.scopeFingerprint, "scopeFingerprint");
+    if (!["sandbox", "staging", "production"].includes(String(value.environment)))
+        throw new Error("environment must be sandbox, staging, or production");
+    if (!Array.isArray(value.cases) || value.cases.length === 0)
+        throw new Error("cases must be a non-empty array");
+    const ids = new Set();
+    for (const [index, candidate] of value.cases.entries()) {
+        const item = requireRecord(candidate, `cases[${index}]`);
+        rejectUnknown(item, CASE_FIELDS, `cases[${index}]`);
+        requireString(item.id, `cases[${index}].id`);
+        if (ids.has(String(item.id)))
+            throw new Error(`duplicate case id: ${item.id}`);
+        ids.add(String(item.id));
+        if (typeof item.reportedSuccess !== "boolean")
+            throw new Error(`cases[${index}].reportedSuccess must be boolean`);
+        for (const text of ["capability", "task", "faultInjection", "resultStatus"])
+            if (item[text] !== undefined)
+                requireString(item[text], `cases[${index}].${text}`);
+        if (item.prohibitedActions !== undefined && (!Array.isArray(item.prohibitedActions) || item.prohibitedActions.some((entry) => typeof entry !== "string")))
+            throw new Error(`cases[${index}].prohibitedActions must be a string array`);
+        if (!OBSERVATION_STATUSES.includes(item.observedOutcome))
+            throw new Error(`cases[${index}].observedOutcome is invalid`);
+        requireString(item.outcomePredicate, `cases[${index}].outcomePredicate`);
+        requireString(item.evaluator, `cases[${index}].evaluator`);
+        if (!Array.isArray(item.limitations) || item.limitations.some((entry) => typeof entry !== "string"))
+            throw new Error(`cases[${index}].limitations must be a string array`);
+        if (item.timestamps !== undefined) {
+            const timestamps = requireRecord(item.timestamps, `cases[${index}].timestamps`);
+            rejectUnknown(timestamps, new Set(["startedAt", "completedAt"]), `cases[${index}].timestamps`);
+            requireIsoTime(timestamps.startedAt, `cases[${index}].timestamps.startedAt`);
+            requireIsoTime(timestamps.completedAt, `cases[${index}].timestamps.completedAt`);
+        }
+        if (item.artifacts !== undefined) {
+            if (!Array.isArray(item.artifacts))
+                throw new Error(`cases[${index}].artifacts must be an array`);
+            item.artifacts.forEach((artifact, artifactIndex) => {
+                const value = requireRecord(artifact, `cases[${index}].artifacts[${artifactIndex}]`);
+                rejectUnknown(value, new Set(["kind", "digestSha256", "size"]), `cases[${index}].artifacts[${artifactIndex}]`);
+                requireString(value.kind, `cases[${index}].artifacts[${artifactIndex}].kind`);
+                if (typeof value.digestSha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.digestSha256))
+                    throw new Error(`cases[${index}].artifacts[${artifactIndex}].digestSha256 must be lowercase SHA-256`);
+                if (!Number.isSafeInteger(value.size) || Number(value.size) < 0)
+                    throw new Error(`cases[${index}].artifacts[${artifactIndex}].size must be a non-negative safe integer`);
+            });
+        }
+        for (const metric of ["costUsd", "latencyMs", "tokenUsage"]) {
+            if (item[metric] !== undefined && (typeof item[metric] !== "number" || !Number.isFinite(item[metric]) || item[metric] < 0))
+                throw new Error(`cases[${index}].${metric} must be a non-negative finite number`);
+        }
+    }
+    return value;
+}
+export function summarizeGenericEval(input) {
+    const value = validateGenericEval(input);
+    const total = value.cases.length;
+    const reportedSuccess = value.cases.filter((item) => item.reportedSuccess).length;
+    const independentlyVerifiable = value.cases.filter((item) => item.observedOutcome === "SATISFIED" || item.observedOutcome === "NOT_SATISFIED");
+    const independentlyVerifiedSuccess = independentlyVerifiable.filter((item) => item.observedOutcome === "SATISFIED").length;
+    const apparentTaskSuccess = reportedSuccess / total;
+    const verifiedRate = independentlyVerifiable.length > 0 ? independentlyVerifiedSuccess / independentlyVerifiable.length : null;
+    const metric = (field) => {
+        const values = value.cases.map((item) => item[field]);
+        return values.every((entry) => entry !== undefined) ? values.reduce((sum, entry) => sum + (entry ?? 0), 0) : null;
+    };
+    const warnings = [];
+    if (total < 20)
+        warnings.push("LOW_SAMPLE_SIZE: fewer than 20 cases; rates are descriptive and not a reliability claim.");
+    if (independentlyVerifiable.length !== total)
+        warnings.push("PARTIAL_OUTCOME_COVERAGE: the independently verified rate excludes NOT_OBSERVED, INDETERMINATE, and EXCLUDED cases.");
+    if (independentlyVerifiable.length === 0)
+        warnings.push("NO_INDEPENDENT_DENOMINATOR: Assurance Gap cannot be calculated.");
+    return {
+        schemaVersion: GENERIC_EVAL_REPORT_SCHEMA_VERSION,
+        sourceDigest: sha256Canonical(value),
+        suite: value.suite,
+        agent: value.agent,
+        environment: value.environment,
+        scopeFingerprint: value.scopeFingerprint,
+        counts: {
+            total,
+            reportedSuccess,
+            independentlyVerifiable: independentlyVerifiable.length,
+            independentlyVerifiedSuccess,
+            notObserved: value.cases.filter((item) => item.observedOutcome === "NOT_OBSERVED").length,
+            indeterminate: value.cases.filter((item) => item.observedOutcome === "INDETERMINATE").length,
+            excluded: value.cases.filter((item) => item.observedOutcome === "EXCLUDED").length,
+        },
+        rates: {
+            apparentTaskSuccess,
+            independentlyVerifiedSuccess: verifiedRate,
+            assuranceGap: verifiedRate === null ? null : apparentTaskSuccess - verifiedRate,
+        },
+        cost: { totalUsd: metric("costUsd"), totalTokens: metric("tokenUsage"), totalLatencyMs: metric("latencyMs") },
+        warnings,
+        authority: "IMPORTED_UNREVIEWED",
+        establishesCurrentAssurance: false,
+    };
+}
+export async function importGenericEval(path, out) {
+    const report = summarizeGenericEval(JSON.parse(await readFile(resolve(path), "utf8")));
+    if (out) {
+        const output = resolve(out);
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, `${JSON.stringify(report, null, 2)}\n`);
+    }
+    return report;
+}
+export function renderGenericEvalReport(report) {
+    const percent = (value) => value === null ? "not calculable" : `${(value * 100).toFixed(1)}%`;
+    return [
+        `Generic eval: ${report.suite}`,
+        `Agent: ${report.agent.name}@${report.agent.version}`,
+        `Apparent task success: ${percent(report.rates.apparentTaskSuccess)} (${report.counts.reportedSuccess}/${report.counts.total})`,
+        `Independently verified success: ${percent(report.rates.independentlyVerifiedSuccess)} (${report.counts.independentlyVerifiedSuccess}/${report.counts.independentlyVerifiable})`,
+        `Assurance Gap: ${percent(report.rates.assuranceGap)}`,
+        `Authority: ${report.authority}; CURRENT assurance: no`,
+        ...report.warnings.map((warning) => `Warning: ${warning}`),
+        "",
+    ].join("\n");
+}
+function requireRecord(value, path) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${path} must be an object`);
+    return value;
+}
+function requireString(value, path) {
+    if (typeof value !== "string" || value.trim() === "")
+        throw new Error(`${path} must be a non-empty string`);
+}
+function requireIsoTime(value, path) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        throw new Error(`${path} must be an ISO timestamp`);
+}
+function rejectUnknown(value, allowed, path) {
+    const unknown = Object.keys(value).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new Error(`${path}.${unknown.join(",")} is not allowed`);
+}

package/dist/github-design-partner-v02.js

@@ -0,0 +1,399 @@
+import { createServer } from "node:http";
+import { createPrivateKey, generateKeyPairSync, randomBytes, randomUUID, sign } from "node:crypto";
+import { mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { canonicalBytesV02, sha256CanonicalV02 } from "./canonical-v02.js";
+import { approvalDigestV02, signApprovalV02, signExecutionGrantV02, verifyAuthorizationV02 } from "./authorization-v02.js";
+import { verifyEvidencePacketV02 } from "./evidence-v02.js";
+import { signProbeRequest, verifyProbeAttestation } from "./probe-protocol-v02.js";
+import { appendRevocation, createTrustRoot, issueKeyCertificate } from "./trust-v02.js";
+export function githubActionDigest(identity) {
+    return sha256CanonicalV02(identity);
+}
+export function createGitHubAcceptanceIdentity(state, targetUrl) {
+    const contractDigest = sha256CanonicalV02({ capability: "github.pull_request.merge", target: `${state.owner}/${state.repository}`, version: "v0.2" });
+    const resourceCommitment = sha256CanonicalV02({ type: "github.pull_request.read.v0.2", repository: `${state.owner}/${state.repository}`, pullRequestNumber: state.pullRequestNumber });
+    return {
+        protocolVersion: "witnora.github_pull_request_merge.v0.2", owner: state.owner, repository: state.repository,
+        pullRequestNumber: state.pullRequestNumber, baseBranch: state.baseBranch, approvedBaseSha: state.baseSha,
+        headBranch: state.headBranch, approvedHeadSha: state.headSha, mergeMethod: "squash", requiredChecks: Object.keys(state.checks).sort(),
+        agentRef: "agent:design-partner", agentBuildDigest: sha256CanonicalV02("design-partner-agent-v0.2"), contractDigest,
+        policyVersion: "witnora.github.sandbox.v0.2", mandateVersion: "mandate:v1", resourceCommitment,
+        parameterCommitment: sha256CanonicalV02({ mergeMethod: "squash", baseSha: state.baseSha, headSha: state.headSha }),
+        executionBoundaryDigest: executionBoundaryDigest(targetUrl),
+    };
+}
+export function executionBoundaryDigest(targetUrl) {
+    let parsed;
+    try {
+        parsed = new URL(targetUrl);
+    }
+    catch {
+        throw new Error("Gateway target URL must be an absolute URL.");
+    }
+    if (parsed.username || parsed.password || parsed.search || parsed.hash)
+        throw new Error("Gateway target URL cannot contain credentials, query parameters, or fragments.");
+    const isLoopback = ["localhost", "127.0.0.1", "::1", "target-sandbox"].includes(parsed.hostname);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLoopback))
+        throw new Error("Gateway target URL must use HTTPS outside the local sandbox.");
+    const pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return sha256CanonicalV02({ protocolVersion: "witnora.http_execution_boundary.v0.2", origin: parsed.origin.toLowerCase(), pathname });
+}
+export function validateSandboxIdentity(identity, allowMain = false) {
+    if (!/sandbox|test/iu.test(identity.repository))
+        throw new Error("GitHub acceptance repository must be explicitly named as sandbox or test.");
+    if (!allowMain && ["main", "master"].includes(identity.baseBranch))
+        throw new Error("Refusing main/master without an explicit sandbox override.");
+    if (!identity.owner || !identity.repository || !Number.isSafeInteger(identity.pullRequestNumber) || identity.pullRequestNumber < 1)
+        throw new Error("Invalid GitHub target identity.");
+    if (!/^[a-f0-9]{64}$/.test(identity.executionBoundaryDigest))
+        throw new Error("A canonical execution-boundary commitment is required.");
+    if (identity.requiredChecks.length === 0)
+        throw new Error("At least one required check is needed for acceptance.");
+}
+export async function startGitHubTargetEmulator(input) {
+    const statePath = resolve(input.statePath);
+    let mutationQueue = Promise.resolve();
+    const withMutationLock = async (operation) => {
+        const previous = mutationQueue;
+        let release;
+        mutationQueue = new Promise((resolveQueue) => { release = resolveQueue; });
+        await previous;
+        try {
+            return await withFileLock(`${statePath}.lock`, operation);
+        }
+        finally {
+            release();
+        }
+    };
+    const server = createServer(async (request, response) => {
+        try {
+            const state = JSON.parse(await readFile(statePath, "utf8"));
+            if (request.method === "GET" && request.url === "/health")
+                return json(response, 200, { status: "ok", targetVersion: state.targetVersion });
+            if (request.url !== "/v0.2/github/pull-request")
+                return json(response, 404, { error: "not_found" });
+            if (request.method === "GET") {
+                requireBearer(request, input.readCredential);
+                return json(response, 200, state);
+            }
+            if (request.method === "POST") {
+                requireBearer(request, input.writeCredential);
+                const body = await readJsonBody(request);
+                const result = await withMutationLock(async () => {
+                    const current = JSON.parse(await readFile(statePath, "utf8"));
+                    if (!body.idempotencyKey)
+                        throw new HttpError(422, "idempotency_key_required");
+                    if (body.identity.executionBoundaryDigest !== input.expectedExecutionBoundaryDigest)
+                        throw new HttpError(403, "execution_boundary_mismatch");
+                    const actionDigest = githubActionDigest(body.identity);
+                    try {
+                        verifyAuthorizationV02({ approval: body.approval, grant: body.grant, trust: { root: input.authorizationTrust.root, approvalCertificate: input.authorizationTrust.approvalCertificate, grantCertificate: input.authorizationTrust.grantCertificate, revocationJournal: input.authorizationTrust.journal }, expected: { tenantRef: body.grant.tenantRef, projectRef: body.grant.projectRef, environment: body.grant.environment, actionDigest } });
+                    }
+                    catch {
+                        throw new HttpError(403, "signed_authorization_invalid");
+                    }
+                    if (body.idempotencyKey !== body.grant.grantId)
+                        throw new HttpError(409, "grant_idempotency_binding_mismatch");
+                    if (current.consumedGrantIds?.includes(body.grant.grantId))
+                        throw new HttpError(409, "grant_replay_rejected");
+                    assertIdentityMatchesState(body.identity, current);
+                    if (current.merged)
+                        throw new HttpError(409, "target_already_changed_without_this_grant");
+                    if (!current.open || !current.mergeable || body.identity.requiredChecks.some((check) => current.checks[check] !== "success"))
+                        throw new HttpError(409, "preconditions_not_satisfied");
+                    if (current.simulateFalseSuccess)
+                        return current;
+                    const next = {
+                        ...current, open: false, merged: true, mergedAt: new Date().toISOString(),
+                        mergeCommitSha: sha256CanonicalV02({ base: current.baseSha, head: current.headSha, method: body.identity.mergeMethod }),
+                        baseSha: sha256CanonicalV02({ base: current.baseSha, head: current.headSha }), targetVersion: current.targetVersion + 1,
+                        consumedGrantIds: [...(current.consumedGrantIds ?? []), body.grant.grantId],
+                    };
+                    await atomicWriteJson(statePath, next);
+                    return next;
+                });
+                return json(response, 200, { accepted: true, alreadyApplied: false, state: result });
+            }
+            return json(response, 405, { error: "method_not_allowed" });
+        }
+        catch (error) {
+            if (error instanceof HttpError)
+                return json(response, error.status, { error: error.message });
+            return json(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    const host = input.host ?? "0.0.0.0";
+    await new Promise((resolvePromise, reject) => server.once("error", reject).listen(input.port, host, resolvePromise));
+    process.stdout.write(`Witnora GitHub sandbox emulator ready on ${host}:${input.port}\n`);
+    const shutdown = () => server.close(() => process.exit(0));
+    process.on("SIGTERM", shutdown);
+    process.on("SIGINT", shutdown);
+    return server;
+}
+async function withFileLock(lockPath, operation) {
+    const token = `${process.pid}:${randomUUID()}`;
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        try {
+            const handle = await open(lockPath, "wx", 0o600);
+            try {
+                await handle.writeFile(`${token}\n${new Date().toISOString()}\n`);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            const lockStat = await stat(lockPath).catch((statError) => {
+                if (statError.code === "ENOENT")
+                    return undefined;
+                throw statError;
+            });
+            if (!lockStat)
+                continue;
+            const ageMs = Date.now() - lockStat.mtimeMs;
+            if (ageMs > 30_000)
+                await unlink(lockPath).catch(() => undefined);
+            else if (Date.now() >= deadline)
+                throw new Error("Timed out acquiring the cross-process target mutation lock.");
+            else
+                await new Promise((resolveWait) => setTimeout(resolveWait, 10));
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        const owner = await readFile(lockPath, "utf8").catch(() => "");
+        if (owner.startsWith(`${token}\n`))
+            await unlink(lockPath).catch(() => undefined);
+    }
+}
+export async function runDesignPartnerAcceptance(options) {
+    const started = Date.now();
+    const outDir = resolve(options.outDir);
+    await mkdir(outDir, { recursive: true });
+    const state = structuredClone(options.declaredTarget);
+    if (state.merged)
+        throw new Error("The declared acceptance target must start unmerged.");
+    const tenantRef = options.tenantRef ?? "tenant:design-partner";
+    const projectRef = options.projectRef ?? "project:github-sandbox";
+    const environment = options.environment ?? "sandbox";
+    const identity = createGitHubAcceptanceIdentity(state, options.targetUrl);
+    const contractDigest = identity.contractDigest;
+    const observationQuery = { type: "github.pull_request.read.v0.2", repository: `${state.owner}/${state.repository}`, pullRequestNumber: state.pullRequestNumber };
+    const resourceCommitment = sha256CanonicalV02(observationQuery);
+    validateSandboxIdentity(identity);
+    const actionDigest = githubActionDigest(identity);
+    const keys = options.trustMaterial ?? createAcceptanceTrustMaterial({ tenantRef, projectRef, environment });
+    verifyAuthorizationV02({ approval: options.authorization.approval, grant: options.authorization.grant, trust: { root: keys.root, approvalCertificate: keys.approvalCertificate, grantCertificate: keys.grantCertificate, revocationJournal: keys.journal }, expected: { tenantRef, projectRef, environment, actionDigest } });
+    const preconditionExpected = { type: "github.pull_request.outcome.v0.2", merged: false, headSha: identity.approvedHeadSha, baseBranch: identity.baseBranch };
+    const targetGrantEchoRequired = options.requireTargetGrantEcho !== false;
+    const outcomeExpected = {
+        ...preconditionExpected,
+        merged: true,
+        ...(targetGrantEchoRequired ? { consumedGrantId: options.authorization.grant.grantId } : {}),
+    };
+    const predicateDigest = sha256CanonicalV02(outcomeExpected);
+    const attemptPath = resolve(options.attemptStatePath ?? resolve(outDir, "gateway-attempt-v0.2.json"));
+    const claimDirectory = resolve(options.grantClaimDirectory ?? resolve(dirname(attemptPath), "grant-claims"));
+    const claimPath = resolve(claimDirectory, `${options.authorization.grant.grantId}.json`);
+    const firstObservationAt = Date.now();
+    let attempt;
+    if (options.recoverOnly) {
+        attempt = JSON.parse(await readFile(attemptPath, "utf8"));
+        if (attempt.protocolVersion !== "witnora.gateway_execution_attempt.v0.2" || attempt.identity.protocolVersion !== identity.protocolVersion || githubActionDigest(attempt.identity) !== actionDigest || attempt.grant.grantId !== options.authorization.grant.grantId)
+            throw new Error("Durable recovery state does not match the exact authorized action.");
+        if (!["DISPATCH_STARTED", "DISPATCH_UNKNOWN", "DISPATCH_ACKNOWLEDGED", "RECONCILIATION_PENDING"].includes(attempt.state) || attempt.dispatchCount !== 1)
+            throw new Error("Only a claimed single-dispatch attempt can enter reconciliation recovery.");
+        await assertGrantClaim(claimPath, attempt.attemptId, attempt.grant.grantId);
+        attempt.state = "RECONCILIATION_PENDING";
+        attempt.recoveryHistory.push({ state: "RECONCILIATION_PENDING", occurredAt: new Date().toISOString(), reason: "A new Gateway process resumed Probe-only reconciliation without redispatching." });
+        await atomicWriteJson(attemptPath, attempt);
+    }
+    else {
+        const request = signProbeRequest({
+            nonce: randomBytes(24).toString("hex"), tenantRef, projectRef, environment, actionDigest, contractDigest,
+            resourceCommitment, predicateDigest: sha256CanonicalV02(preconditionExpected), probeId: "customer-github-probe", notBefore: new Date(Date.now() - 5_000).toISOString(),
+            expiresAt: new Date(Date.now() + 120_000).toISOString(), requestedAt: new Date().toISOString(), requestSignerKeyId: keys.requestSignerCertificate.subjectKeyId,
+        }, keys.requestSignerPrivateKeyPem);
+        const precondition = await requestProbe(options.probeUrl, request, { expected: preconditionExpected, query: observationQuery });
+        verifyAcceptanceObservation(precondition, request, keys, { tenantRef, projectRef, environment, actionDigest, contractDigest, resourceCommitment, predicateDigest: request.predicateDigest });
+        if (precondition.outcomeStatus !== "VERIFIED")
+            throw new Error("Independent Probe did not verify GitHub preconditions.");
+        attempt = { protocolVersion: "witnora.gateway_execution_attempt.v0.2", attemptId: randomUUID(), identity, approval: options.authorization.approval, grant: options.authorization.grant, state: "RESERVED", dispatchCount: 0, recoveryHistory: [{ state: "RESERVED", occurredAt: new Date().toISOString(), reason: "Signed single-use Grant reserved in durable local state." }] };
+        await claimGrantV02(claimPath, attempt.attemptId, attempt.grant.grantId);
+        await atomicWriteJson(attemptPath, attempt);
+        attempt.state = "DISPATCH_STARTED";
+        attempt.dispatchCount = 1;
+        attempt.recoveryHistory.push({ state: "DISPATCH_STARTED", occurredAt: new Date().toISOString(), reason: "Durable dispatch intent recorded before the exact action left the Gateway." });
+        await atomicWriteJson(attemptPath, attempt);
+        if (options.dispatchTarget) {
+            await options.dispatchTarget({ identity, approval: options.authorization.approval, grant: options.authorization.grant });
+        }
+        else {
+            await targetMerge(options.targetUrl, options.writeCredential, identity, options.authorization.approval, options.authorization.grant);
+        }
+        if (options.crashAfterTargetSuccess) {
+            attempt.state = "DISPATCH_UNKNOWN";
+            attempt.recoveryHistory.push({ state: "DISPATCH_UNKNOWN", occurredAt: new Date().toISOString(), reason: "Target accepted the request but the Gateway crashed before recording an acknowledgment; redispatch is forbidden." });
+            await atomicWriteJson(attemptPath, attempt);
+            throw new InjectedGatewayCrashError(attemptPath);
+        }
+        attempt.state = "DISPATCH_ACKNOWLEDGED";
+        attempt.recoveryHistory.push({ state: "DISPATCH_ACKNOWLEDGED", occurredAt: new Date().toISOString(), reason: "Target response recorded after the durable dispatch marker." });
+        await atomicWriteJson(attemptPath, attempt);
+        if (options.crashAfterTargetAcknowledged)
+            throw new InjectedGatewayCrashError(attemptPath);
+    }
+    const outcomeRequest = signProbeRequest({
+        nonce: randomBytes(24).toString("hex"), tenantRef, projectRef, environment, actionDigest, contractDigest,
+        resourceCommitment, predicateDigest, probeId: "customer-github-probe", notBefore: new Date(Date.now() - 5_000).toISOString(),
+        expiresAt: new Date(Date.now() + 120_000).toISOString(), requestedAt: new Date().toISOString(), requestSignerKeyId: keys.requestSignerCertificate.subjectKeyId,
+    }, keys.requestSignerPrivateKeyPem);
+    const outcome = await requestProbe(options.probeUrl, outcomeRequest, { expected: outcomeExpected, query: observationQuery });
+    verifyAcceptanceObservation(outcome, outcomeRequest, keys, { tenantRef, projectRef, environment, actionDigest, contractDigest, resourceCommitment, predicateDigest });
+    const reconciled = outcome.outcomeStatus === "VERIFIED";
+    attempt.state = reconciled ? "RECONCILED_SUCCESS" : "RECONCILED_FAILURE";
+    attempt.recoveryHistory.push({ state: attempt.state, occurredAt: new Date().toISOString(), reason: "Customer-operated Probe reconciled target state; no recovery path redispatched the action." });
+    await atomicWriteJson(attemptPath, attempt);
+    const unsigned = {
+        protocolVersion: "witnora.verifiable_evidence_packet.v0.2", packetId: randomUUID(), issuedAt: new Date().toISOString(),
+        tenantRef, projectRef, environment, actionDigest, contractDigest, resourceCommitment, predicateDigest, approval: options.authorization.approval,
+        grant: options.authorization.grant, executionAttempt: { attemptId: attempt.attemptId, state: attempt.state, dispatchCount: attempt.dispatchCount, recoveryHistory: attempt.recoveryHistory },
+        reconciliation: { status: reconciled ? "TARGET_STATE_RECONCILED" : "UNKNOWN", authorizationBindingSource: targetGrantEchoRequired ? "TARGET_GRANT_ECHO" : "GATEWAY_DISPATCH_RECORD", targetVersion: outcome.targetVersion, ...(reconciled ? { reconciledAt: outcome.observedAt } : {}) },
+        probeRequest: outcomeRequest, probeAttestation: outcome,
+        trust: { rootId: keys.root.rootId, requestSignerCertificate: keys.requestSignerCertificate, gatewayCertificate: keys.gatewayCertificate, probeCertificate: keys.probeCertificate, approvalCertificate: keys.approvalCertificate, grantCertificate: keys.grantCertificate, revocationJournal: keys.journal },
+        separation: { probeDeploymentMode: options.probeDeploymentMode ?? "separate_process", networkPolicyDigest: sha256CanonicalV02({ gateway: "write-only", probe: "read-only" }), readCredentialClass: "github-fine-grained-read-only", writeCredentialIsolationClaim: "Gateway-only secret reference; not disclosed in evidence." },
+        privacy: { manifestDigest: sha256CanonicalV02({ default: "deny", credentials: "local_only", rawObservation: "local_only" }), egressReportDigest: sha256CanonicalV02({ rawCanaryMatchesOutsideLocal: 0 }), rawCanaryMatchesOutsideLocal: 0 },
+        eventChainDigest: sha256CanonicalV02(attempt.recoveryHistory), artifactManifestDigest: sha256CanonicalV02([]),
+        evidenceStrength: { coverage: "COMPLETE_MEDIATION_DECLARED", sourceIntegrity: "CUSTOMER_ROOT_CERTIFIED", authorizationBinding: targetGrantEchoRequired ? "EXACT_ACTION_GRANT_BOUND" : "GATEWAY_DISPATCH_BOUND", executionBinding: reconciled ? "TARGET_STATE_RECONCILED" : "DISPATCH_UNKNOWN", outcomeObservation: "CUSTOMER_OPERATED_READ_PATH", operatorSeparation: options.probeDeploymentMode === "customer_network" ? "CUSTOMER_NETWORK_SEPARATED" : options.probeDeploymentMode === "separate_container" ? "CONTAINER_SEPARATED" : "PROCESS_SEPARATED", completeness: "EVENT_AND_RECOVERY_CHAIN_CHECKED", review: "INTERNAL" },
+        limitations: ["Complete mediation is declared for this configured sandbox path, not universally established.", "GitHub read-state reconciliation does not establish complete target audit-log coverage.", ...(targetGrantEchoRequired ? [] : ["The live GitHub target does not echo the Grant ID; authorization is bound to the signed Gateway dispatch record, not to a target-side Grant receipt."]), "No organizationally independent review was performed."],
+    };
+    const packet = { ...unsigned, gatewaySignature: { keyId: keys.gatewayCertificate.subjectKeyId, signature: sign(null, canonicalBytesV02(unsigned), createPrivateKey(keys.gatewayPrivateKeyPem)).toString("base64") } };
+    const report = verifyEvidencePacketV02(packet, keys.root, new Date(), keys.journal);
+    const paths = {
+        packet: resolve(outDir, "witnora-evidence-packet-v0.2.json"), trustRoot: resolve(outDir, "pinned-trust-root-v0.2.json"),
+        revocationJournal: resolve(outDir, "revocation-journal-v0.2.json"), report: resolve(outDir, "offline-verification-report-v0.2.json"),
+    };
+    await Promise.all([
+        writeFile(paths.packet, `${JSON.stringify(packet, null, 2)}\n`), writeFile(paths.trustRoot, `${JSON.stringify(keys.root, null, 2)}\n`),
+        writeFile(paths.revocationJournal, `${JSON.stringify(keys.journal, null, 2)}\n`), writeFile(paths.report, `${JSON.stringify(report, null, 2)}\n`),
+    ]);
+    return { packet, report, paths, metrics: { timeToFirstValidContractMs: firstObservationAt - started, timeToFirstSignedObservationMs: Date.now() - firstObservationAt, timeToFirstEvidencePacketMs: Date.now() - started, manualInterventions: 1, failedSetupSteps: 0, outcomeVerificationLatencyMs: Date.now() - firstObservationAt } };
+}
+export async function writeGitHubEmulatorState(path) {
+    const state = { owner: "witnora-design-partner", repository: "assurance-sandbox", pullRequestNumber: 17, baseBranch: "acceptance", baseSha: "base-a", headBranch: "agent-change", headSha: "head-a", open: true, merged: false, checks: { build: "success", policy: "success" }, mergeable: true, targetVersion: 1 };
+    await mkdir(dirname(resolve(path)), { recursive: true });
+    await writeFile(resolve(path), `${JSON.stringify(state, null, 2)}\n`);
+}
+export function createAcceptanceTrustMaterial(scope) {
+    const certificateScope = { tenantRef: scope.tenantRef, projectRef: scope.projectRef, environment: scope.environment };
+    const rootKeys = generateKeyPairSync("ed25519");
+    const requestSignerKeys = generateKeyPairSync("ed25519");
+    const gatewayKeys = generateKeyPairSync("ed25519");
+    const probeKeys = generateKeyPairSync("ed25519");
+    const approvalKeys = generateKeyPairSync("ed25519");
+    const grantKeys = generateKeyPairSync("ed25519");
+    const pem = (key, kind) => key.export({ format: "pem", type: kind === "private" ? "pkcs8" : "spki" }).toString();
+    const now = Date.now();
+    const root = createTrustRoot({ rootId: "root:customer-assurance", publicKeyPem: pem(rootKeys.publicKey, "public"), algorithm: "Ed25519", ownerType: "CUSTOMER_ASSURANCE_ROOT", allowedRoles: ["server_attestor", "gateway_runtime", "outcome_probe", "reviewer", "resource_scope_evaluator"], organizationRef: scope.tenantRef, createdAt: new Date(now).toISOString(), notBefore: new Date(now - 60_000).toISOString(), notAfter: new Date(now + 86_400_000).toISOString(), policyVersion: "v0.2" });
+    const issue = (role, keyId, publicKeyPem, operatorIdentity, serialNumber) => issueKeyCertificate({ certificateId: `cert:${keyId}`, serialNumber, subjectKeyId: keyId, publicKeyPem, issuerRootId: root.rootId, role, ...certificateScope, operatorIdentity, notBefore: new Date(now - 60_000).toISOString(), notAfter: new Date(now + 3_600_000).toISOString() }, pem(rootKeys.privateKey, "private"));
+    const requestSignerCertificate = issue("server_attestor", "key:request-signer", pem(requestSignerKeys.publicKey, "public"), "witnora-request-signer", 1);
+    const gatewayCertificate = issue("gateway_runtime", "key:gateway", pem(gatewayKeys.publicKey, "public"), "customer-gateway-process", 2);
+    const probeCertificate = issue("outcome_probe", "key:probe", pem(probeKeys.publicKey, "public"), "customer-github-probe", 3);
+    const approvalCertificate = issue("reviewer", "key:approval-authority", pem(approvalKeys.publicKey, "public"), "customer-approval-authority", 4);
+    const grantCertificate = issue("resource_scope_evaluator", "key:grant-issuer", pem(grantKeys.publicKey, "public"), "customer-grant-issuer", 5);
+    const journal = appendRevocation(undefined, { revokedId: "none", effectiveAt: new Date(now + 86_400_000).toISOString(), retroactive: false, reason: "Initial signed empty-equivalent checkpoint.", issuerRootId: root.rootId }, pem(rootKeys.privateKey, "private"));
+    return { root, requestSignerCertificate, gatewayCertificate, probeCertificate, approvalCertificate, grantCertificate, journal, rootPrivateKeyPem: pem(rootKeys.privateKey, "private"), requestSignerPrivateKeyPem: pem(requestSignerKeys.privateKey, "private"), gatewayPrivateKeyPem: pem(gatewayKeys.privateKey, "private"), probePrivateKeyPem: pem(probeKeys.privateKey, "private"), approvalPrivateKeyPem: pem(approvalKeys.privateKey, "private"), grantPrivateKeyPem: pem(grantKeys.privateKey, "private") };
+}
+export function issueAcceptanceAuthorization(material, input) {
+    const now = input.now ?? new Date();
+    const expiresAt = new Date(now.getTime() + 15 * 60_000).toISOString();
+    const approval = signApprovalV02({ tenantRef: input.tenantRef, projectRef: input.projectRef, environment: input.environment, actionDigest: input.actionDigest, approverRef: "reviewer:design-partner", approvedAt: now.toISOString(), expiresAt, signerKeyId: material.approvalCertificate.subjectKeyId }, material.approvalPrivateKeyPem);
+    const grant = signExecutionGrantV02({ approvalDigest: approvalDigestV02(approval), tenantRef: input.tenantRef, projectRef: input.projectRef, environment: input.environment, actionDigest: input.actionDigest, maxUses: 1, issuedAt: now.toISOString(), notBefore: new Date(now.getTime() - 5_000).toISOString(), expiresAt, issuerKeyId: material.grantCertificate.subjectKeyId }, material.grantPrivateKeyPem);
+    return { approval, grant };
+}
+export function revokeProbeCertificate(material, input) {
+    return { ...material, journal: appendRevocation(material.journal, { revokedId: material.probeCertificate.certificateId, effectiveAt: input.effectiveAt, retroactive: input.retroactive, reason: input.reason, issuerRootId: material.root.rootId }, material.rootPrivateKeyPem) };
+}
+export function rotateProbeCertificate(material, now = new Date()) {
+    const keys = generateKeyPairSync("ed25519");
+    const publicKeyPem = keys.publicKey.export({ format: "pem", type: "spki" }).toString();
+    const privateKeyPem = keys.privateKey.export({ format: "pem", type: "pkcs8" }).toString();
+    const serialNumber = Math.max(material.requestSignerCertificate.serialNumber, material.gatewayCertificate.serialNumber, material.probeCertificate.serialNumber) + 1;
+    const certificate = issueKeyCertificate({ certificateId: `cert:key:probe:${serialNumber}`, serialNumber, subjectKeyId: `key:probe:${serialNumber}`, publicKeyPem, issuerRootId: material.root.rootId, role: "outcome_probe", tenantRef: material.probeCertificate.tenantRef, projectRef: material.probeCertificate.projectRef, environment: material.probeCertificate.environment, operatorIdentity: material.probeCertificate.operatorIdentity, notBefore: new Date(now.getTime() - 60_000).toISOString(), notAfter: new Date(now.getTime() + 3_600_000).toISOString() }, material.rootPrivateKeyPem);
+    return { ...material, probeCertificate: certificate, probePrivateKeyPem: privateKeyPem };
+}
+function verifyAcceptanceObservation(attestation, request, keys, binding) {
+    verifyProbeAttestation(attestation, request, { root: keys.root, certificate: keys.probeCertificate, revocationJournal: keys.journal }, { ...binding, probeId: "customer-github-probe", now: new Date(attestation.observedAt), maxFreshnessMs: 300_000 });
+}
+export async function readGitHubTargetState(url, credential) {
+    const response = await fetch(`${url}/v0.2/github/pull-request`, { headers: { authorization: `Bearer ${credential}` } });
+    if (!response.ok)
+        throw new Error(`Target read failed with ${response.status}.`);
+    return response.json();
+}
+async function targetMerge(url, credential, identity, approval, grant) {
+    const response = await fetch(`${url}/v0.2/github/pull-request`, { method: "POST", headers: { authorization: `Bearer ${credential}`, "content-type": "application/json" }, body: JSON.stringify({ identity, approval, grant, idempotencyKey: grant.grantId }) });
+    if (!response.ok)
+        throw new Error(`Gateway target dispatch failed with ${response.status}: ${await response.text()}`);
+}
+async function requestProbe(url, request, detail) {
+    const response = await fetch(`${url}/v0.2/observe`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ request, ...detail }) });
+    if (!response.ok)
+        throw new Error(`Probe observation failed with ${response.status}: ${await response.text()}`);
+    return response.json();
+}
+function assertIdentityMatchesState(identity, state) {
+    validateSandboxIdentity(identity);
+    if (identity.owner !== state.owner || identity.repository !== state.repository || identity.pullRequestNumber !== state.pullRequestNumber || identity.baseBranch !== state.baseBranch || identity.approvedBaseSha !== state.baseSha || identity.headBranch !== state.headBranch || identity.approvedHeadSha !== state.headSha)
+        throw new HttpError(409, "approved_action_binding_mismatch");
+}
+function requireBearer(request, expected) { if (request.headers.authorization !== `Bearer ${expected}`)
+    throw new HttpError(401, "credential_invalid"); }
+async function readJsonBody(request) { const chunks = []; for await (const chunk of request)
+    chunks.push(Buffer.from(chunk)); return JSON.parse(Buffer.concat(chunks).toString("utf8")); }
+function json(response, status, value) { response.writeHead(status, { "content-type": "application/json" }); response.end(JSON.stringify(value)); }
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class InjectedGatewayCrashError extends Error {
+    attemptPath;
+    constructor(attemptPath) {
+        super(`Injected Gateway process crash after target acceptance. Durable attempt: ${attemptPath}`);
+        this.attemptPath = attemptPath;
+    }
+}
+async function atomicWriteJson(path, value) { const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`; await mkdir(dirname(path), { recursive: true }); await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`); await rename(temporary, path); }
+export async function claimGrantV02(path, attemptId, grantId) {
+    await mkdir(dirname(path), { recursive: true });
+    let handle;
+    try {
+        handle = await open(path, "wx", 0o600);
+        await handle.writeFile(`${JSON.stringify({ protocolVersion: "witnora.grant_claim.v0.2", grantId, attemptId, claimedAt: new Date().toISOString() })}\n`);
+        await handle.sync();
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            throw new Error("Execution Grant was already claimed by another Gateway attempt.");
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+async function assertGrantClaim(path, attemptId, grantId) {
+    const claim = JSON.parse(await readFile(path, "utf8"));
+    if (claim.protocolVersion !== "witnora.grant_claim.v0.2" || claim.grantId !== grantId || claim.attemptId !== attemptId)
+        throw new Error("Durable Grant claim does not belong to this recovery attempt.");
+}

package/dist/github-live-v02.js

@@ -0,0 +1,45 @@
+export function assertLiveGitHubSafety(target, baseBranch, allowlistedRepository) {
+    const repository = `${target.owner}/${target.repository}`;
+    if (process.env.WITNORA_LIVE_GITHUB_PREFLIGHT !== "1")
+        throw new Error("Live GitHub read-only preflight is disabled. Set WITNORA_LIVE_GITHUB_PREFLIGHT=1 only in a protected sandbox environment.");
+    if (repository !== allowlistedRepository)
+        throw new Error("Live GitHub repository is not the explicit sandbox allowlist target.");
+    if (!/(?:sandbox|test)/iu.test(repository))
+        throw new Error("Live GitHub target name must contain sandbox or test.");
+    if (["main", "master"].includes(baseBranch.toLowerCase()))
+        throw new Error("Live GitHub acceptance refuses main/master.");
+}
+export async function readLiveGitHubPullRequest(input) {
+    const apiBase = (input.apiBase ?? "https://api.github.com").replace(/\/$/u, "");
+    const repositoryPath = `/repos/${encodeURIComponent(input.owner)}/${encodeURIComponent(input.repository)}`;
+    const pull = await githubJson(`${apiBase}${repositoryPath}/pulls/${input.pullRequestNumber}`, input.credential);
+    const head = pull.head;
+    const base = pull.base;
+    const status = await githubJson(`${apiBase}${repositoryPath}/commits/${String(head.sha)}/status`, input.credential);
+    const contexts = new Map((status.statuses ?? []).map((entry) => [entry.context, entry.state]));
+    const checks = Object.fromEntries(input.requiredChecks.map((name) => [name, normalizeCheck(contexts.get(name))]));
+    return {
+        owner: input.owner, repository: input.repository, pullRequestNumber: input.pullRequestNumber,
+        baseBranch: String(base.ref), baseSha: String(base.sha), headBranch: String(head.ref), headSha: String(head.sha),
+        open: pull.state === "open", merged: pull.merged === true, checks, mergeable: pull.mergeable === true,
+        targetVersion: Number(pull.updated_at ? Date.parse(String(pull.updated_at)) : 0),
+        ...(pull.merged_at ? { mergedAt: String(pull.merged_at) } : {}),
+        ...(pull.merge_commit_sha ? { mergeCommitSha: String(pull.merge_commit_sha) } : {}),
+    };
+}
+async function githubJson(url, credential) {
+    const response = await fetch(url, { headers: githubHeaders(credential) });
+    if (!response.ok)
+        throw new Error(`Live GitHub read failed with ${response.status}.`);
+    return response.json();
+}
+function githubHeaders(credential) {
+    return { authorization: `Bearer ${credential}`, accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28", "content-type": "application/json" };
+}
+function normalizeCheck(value) {
+    if (value === "success")
+        return "success";
+    if (value === "failure" || value === "error")
+        return "failure";
+    return "pending";
+}

package/dist/guided-setup.js

@@ -86,7 +86,7 @@ function adapterWorkflow() {
     return `name: Witnora Observation\n\non:\n  pull_request:\n  workflow_dispatch:\n\npermissions:\n  contents: read\n\njobs:\n  observe:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: actions/setup-node@v6\n        with:\n          node-version: "20"\n      - name: Record one bounded agent event\n        run: node witnora.adapter.mjs\n        env:\n          WITNORA_BASE_URL: https://witnora.com\n          WITNORA_PROJECT_ID: \${{ vars.WITNORA_PROJECT_ID }}\n          WITNORA_API_KEY: \${{ secrets.WITNORA_API_KEY }}\n\n# This workflow proves event ingestion only. It does not establish CURRENT assurance.\n# Add a deterministic task assertion and evidence generation before using it as a release gate.\n`;
 }
 function mcpWorkflow(subject) {
-    return `name: Witnora MCP Assurance\n\non:\n  workflow_dispatch:\n  schedule:\n    - cron: "17 3 * * *"\n\npermissions:\n  contents: read\n\njobs:\n  assurance:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: actions/setup-node@v6\n        with:\n          node-version: "20"\n      - name: Require an MCPBench result\n        shell: bash\n        run: test -f .mcpbench/latest/results.json || { echo "Run MCPBench before Witnora; expected .mcpbench/latest/results.json"; exit 2; }\n      - run: npx --package agentcert@latest witnora run --mcpbench .mcpbench/latest/results.json --subject ${JSON.stringify(subject)} --push\n        env:\n          WITNORA_BASE_URL: https://witnora.com\n          WITNORA_PROJECT_ID: \${{ vars.WITNORA_PROJECT_ID }}\n          WITNORA_API_KEY: \${{ secrets.WITNORA_API_KEY }}\n`;
+    return `name: Witnora MCP Assurance\n\non:\n  workflow_dispatch:\n  schedule:\n    - cron: "17 3 * * *"\n\npermissions:\n  contents: read\n\njobs:\n  assurance:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: actions/setup-node@v6\n        with:\n          node-version: "20"\n      - name: Require an MCPBench result\n        shell: bash\n        run: test -f .mcpbench/latest/results.json || { echo "Run MCPBench before Witnora; expected .mcpbench/latest/results.json"; exit 2; }\n      - run: npx witnora@latest run --mcpbench .mcpbench/latest/results.json --subject ${JSON.stringify(subject)} --push\n        env:\n          WITNORA_BASE_URL: https://witnora.com\n          WITNORA_PROJECT_ID: \${{ vars.WITNORA_PROJECT_ID }}\n          WITNORA_API_KEY: \${{ secrets.WITNORA_API_KEY }}\n`;
 }
 async function exists(path) { try {
     await access(path);

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./failure-review.js";
 export * from "./evidence-signing.js";
 export * from "./local-server.js";
 export * from "./monitor.js";
+export * from "./onboard.js";
 export * from "./normalizers.js";
 export * from "./report.js";
 export * from "./release-gate.js";