@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/system/system/index.js

@@ -0,0 +1,159 @@
+/**
+ * system — Contract C load + ring 2 (`harness verify --system`).
+ *
+ * Pure data over the ledger + system.toml — never compiles, sub-second:
+ *   - the component DAG is acyclic
+ *   - every artifact a component's latest envelope CONSUMED still matches that
+ *     artifact's latest PRODUCED hash (a stale hash is a fail-closed halt, not
+ *     a warning)
+ *   - no merged unit's component crosses a boundary (its envelope's
+ *     component_id is a declared component)
+ *
+ * A failure appends `system.halted {cause}`; a clean pass appends
+ * `system.verified`.
+ */
+import { readFileSync } from "node:fs";
+import { parse as parseToml } from "smol-toml";
+import { append, read as ledgerRead, } from "../ledger/index.js";
+export class SystemError extends Error {
+    name = "SystemError";
+}
+export function loadSystem(path) {
+    const raw = parseToml(readFileSync(path, "utf8"));
+    if (!raw.system?.id)
+        throw new SystemError(`${path}: [system].id is required`);
+    const component = raw.component ?? [];
+    if (component.length === 0)
+        throw new SystemError(`${path}: at least one [[component]] is required`);
+    for (const c of component) {
+        if (!c.id || !c.profile)
+            throw new SystemError(`${path}: every component needs id + profile`);
+        if (!c.root && !c.repo)
+            throw new SystemError(`component "${c.id}": needs root or repo`);
+    }
+    return {
+        system: raw.system,
+        component,
+        artifact: raw.artifact ?? [],
+        door_class: raw.door_class ?? [],
+        scenario_ownership: raw.scenario_ownership ?? [],
+    };
+}
+function findCycle(components) {
+    const deps = new Map(components.map((c) => [c.id, c.deps ?? []]));
+    const WHITE = 0, GREY = 1, BLACK = 2;
+    const color = new Map();
+    const walk = (n) => {
+        color.set(n, GREY);
+        for (const d of deps.get(n) ?? []) {
+            const c = color.get(d) ?? WHITE;
+            if (c === GREY)
+                return true;
+            if (c === WHITE && deps.has(d) && walk(d))
+                return true;
+        }
+        color.set(n, BLACK);
+        return false;
+    };
+    for (const c of components)
+        if ((color.get(c.id) ?? WHITE) === WHITE && walk(c.id))
+            return c.id;
+    return null;
+}
+/**
+ * A bare `harness verify` (no `--unit`) stamps `unit_id` as `<cwd-basename>#adhoc`
+ * and `component_id` as that same basename. Such runs are out-of-band operator
+ * checks with no DAG standing — they must not drive ring-2's scope / freshness
+ * invariants, or an ad-hoc verify from a repo root or a worktree permanently
+ * halts every real unit with a phantom `scope_cross`.
+ */
+function isAdhoc(b) {
+    return typeof b.unit_id === "string" && b.unit_id.endsWith("#adhoc");
+}
+/** Latest produced hash per artifact name, across all passing envelope events, in ledger order. */
+function latestProduced(events) {
+    const latest = new Map();
+    for (const e of events) {
+        if (e.type !== "envelope")
+            continue;
+        const b = e.body;
+        if (isAdhoc(b))
+            continue;
+        for (const p of b.artifacts?.produced ?? [])
+            latest.set(p.name, p.hash);
+    }
+    return latest;
+}
+/** Latest envelope per component. */
+function latestEnvelopePerComponent(events) {
+    const latest = new Map();
+    for (const e of events) {
+        if (e.type !== "envelope")
+            continue;
+        const b = e.body;
+        if (isAdhoc(b))
+            continue;
+        if (b.component_id)
+            latest.set(b.component_id, b);
+    }
+    return latest;
+}
+/** Ring 2. */
+export function verifySystem(manifest, events) {
+    const halts = [];
+    const componentIds = new Set(manifest.component.map((c) => c.id));
+    const cycle = findCycle(manifest.component);
+    if (cycle)
+        halts.push({
+            cause: "dag_cycle",
+            detail: `cycle through component "${cycle}"`,
+        });
+    const produced = latestProduced(events);
+    for (const [componentId, env] of latestEnvelopePerComponent(events)) {
+        if (!componentIds.has(componentId)) {
+            halts.push({
+                cause: "scope_cross",
+                detail: `envelope names component "${componentId}" not in system.toml`,
+            });
+        }
+        for (const c of env.artifacts?.consumed ?? []) {
+            const current = produced.get(c.name);
+            if (current !== undefined && current !== c.hash) {
+                halts.push({
+                    cause: "stale_artifact",
+                    detail: `component "${componentId}" built against ${c.name}@${c.hash.slice(0, 8)} but the latest is @${current.slice(0, 8)}`,
+                });
+            }
+        }
+    }
+    return { ok: halts.length === 0, halts };
+}
+/** Run ring 2 and record the outcome on the ledger. */
+export function runSystemVerify(opts) {
+    const manifest = loadSystem(opts.systemTomlPath);
+    const events = ledgerRead(opts.ledgerDir);
+    const result = verifySystem(manifest, events);
+    const ts = opts.now ?? new Date().toISOString();
+    if (result.ok) {
+        append(opts.ledgerDir, {
+            system: manifest.system.id,
+            actor: { kind: "harness", id: "harness" },
+            type: "system.verified",
+            ts,
+            body: { system: manifest.system.id },
+        });
+    }
+    else {
+        for (const h of result.halts) {
+            append(opts.ledgerDir, {
+                system: manifest.system.id,
+                actor: { kind: "harness", id: "harness" },
+                type: "system.halted",
+                ts,
+                body: { cause: h.cause, detail: h.detail },
+            });
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/units/index.js

@@ -0,0 +1,87 @@
+const TRANSITION = {
+    "unit.planned": "planned",
+    "unit.ready": "ready",
+    "unit.claimed": "executing",
+    "unit.done": "in-review",
+    "unit.merged": "merged",
+    "unit.aborted": "aborted",
+};
+function bareId(ref) {
+    return ref.includes("#") ? ref.slice(ref.indexOf("#") + 1) : ref;
+}
+/** Fold `unit.*` (and `session.heartbeat`) events into current per-unit state. */
+export function projectUnits(events) {
+    const units = new Map();
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.type === "session.heartbeat" || e.type === "session.escalated") {
+            const uid = bareId(String(e.body.unit_id ?? ""));
+            const rec = units.get(uid);
+            if (!rec)
+                continue;
+            if (e.type === "session.heartbeat" && rec.state === "executing") {
+                rec.heartbeatAt = e.ts;
+                rec.lastSeq = e.seq;
+            }
+            else if (e.type === "session.escalated" &&
+                (rec.state === "executing" || rec.state === "in-review")) {
+                rec.escalated = true;
+                rec.lastSeq = e.seq;
+            }
+            continue;
+        }
+        const nextState = TRANSITION[e.type];
+        if (!nextState)
+            continue;
+        const body = e.body;
+        const id = bareId(String(body.unit_id ?? ""));
+        if (id === "")
+            continue;
+        const rec = units.get(id) ?? {
+            id,
+            deps: [],
+            state: "planned",
+            lastSeq: e.seq,
+        };
+        rec.state = nextState;
+        rec.lastSeq = e.seq;
+        if (body.component !== undefined)
+            rec.component = body.component;
+        if (body.mode !== undefined)
+            rec.mode = body.mode;
+        if (Array.isArray(body.deps))
+            rec.deps = body.deps.map(bareId);
+        if (nextState === "executing") {
+            const session = body.session ?? body.session_id ?? rec.claimedBy;
+            if (session !== undefined)
+                rec.claimedBy = session;
+            rec.heartbeatAt = e.ts;
+            delete rec.escalated; // a fresh claim (incl. --resume) clears a prior escalation
+            delete rec.doneAt;
+            delete rec.doneSeq;
+        }
+        else if (nextState === "in-review") {
+            rec.doneAt = e.ts;
+            rec.doneSeq = e.seq;
+            delete rec.claimedBy;
+            delete rec.heartbeatAt;
+            delete rec.escalated;
+        }
+        else {
+            delete rec.claimedBy;
+            delete rec.heartbeatAt;
+            delete rec.escalated;
+            delete rec.doneAt;
+            delete rec.doneSeq;
+            if (nextState === "merged" && typeof body.landed === "string") {
+                rec.landedSha = body.landed;
+            }
+        }
+        units.set(id, rec);
+    }
+    return units;
+}
+/** Convenience: the projected list, id-sorted. */
+export function unitList(events) {
+    return [...projectUnits(events).values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/verify/cli.js

@@ -0,0 +1,103 @@
+/**
+ * `harness verify` — ring 1 (default) or ring 2 (`--system <system.toml>`).
+ *
+ *   harness verify [--component <dir>] [--profiles <dir>] [--component-id <id>]
+ *                  [--unit <id>] [--session <id>] [--feature <id>] [--system-id <id>]
+ *                  [--ledger <dir>] [--base <commit>] [--specs <dir>]
+ *                  [--produces name=path]... [--consumes name]...
+ *
+ *   harness verify --system <system.toml> [--ledger <dir>]      # ring 2
+ *
+ *   --json   emit `{status, envelope_hash?}` on stdout instead of the human
+ *            report; exit codes are unchanged. `envelope_hash` is the `hash` of
+ *            the `envelope` ledger event this run appended (ring 1 only) — a
+ *            deterministic handle even when parallel verifies make the ledger
+ *            tail ambiguous (G2.4).
+ *
+ * Ring 1 exit: 0 pass · 1 fail · 2 halt.
+ * Ring 2 exit: 0 verified · 2 halted (dag_cycle | stale_artifact | scope_cross).
+ */
+import { basename } from "node:path";
+import { runSystemVerify } from "../system/index.js";
+import { verify } from "./index.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+function multi(args, name) {
+    const out = [];
+    for (let i = 0; i < args.length; i++)
+        if (args[i] === `--${name}` && args[i + 1])
+            out.push(args[i + 1]);
+    return out;
+}
+export function verifyCommand(args) {
+    const json = args.includes("--json");
+    const systemToml = flag(args, "system");
+    if (systemToml && systemToml.endsWith(".toml")) {
+        const result = runSystemVerify({
+            systemTomlPath: systemToml,
+            ledgerDir: flag(args, "ledger") ?? ".harness/ledger",
+        });
+        if (result.ok) {
+            process.stdout.write(json
+                ? JSON.stringify({ status: "pass" }) + "\n"
+                : "  ✓ verify --system: DAG acyclic, artifacts fresh, scope contained\n");
+            return 0;
+        }
+        if (json) {
+            process.stdout.write(JSON.stringify({ status: "halt", causes: result.halts.map((h) => h.cause) }) + "\n");
+        }
+        else {
+            for (const h of result.halts)
+                process.stderr.write(`  ⛔ system.halted {${h.cause}}: ${h.detail}\n`);
+        }
+        return 2;
+    }
+    const componentDir = flag(args, "component") ?? process.cwd();
+    const componentId = flag(args, "component-id") ?? basename(componentDir);
+    const unitId = flag(args, "unit") ?? `${componentId}#adhoc`;
+    const produces = {};
+    for (const kv of multi(args, "produces")) {
+        const eq = kv.indexOf("=");
+        if (eq > 0)
+            produces[kv.slice(0, eq)] = kv.slice(eq + 1);
+    }
+    const consumes = multi(args, "consumes");
+    const result = verify({
+        componentDir,
+        componentId,
+        unitId,
+        ...(flag(args, "session") ? { sessionId: flag(args, "session") } : {}),
+        ...(flag(args, "ledger") ? { ledgerDir: flag(args, "ledger") } : {}),
+        ...(flag(args, "base") ? { baseRef: flag(args, "base") } : {}),
+        ...(flag(args, "specs") ? { specsDir: flag(args, "specs") } : {}),
+        ...(flag(args, "profiles") ? { profilesDir: flag(args, "profiles") } : {}),
+        ...(flag(args, "feature") ? { featureId: flag(args, "feature") } : {}),
+        ...(flag(args, "system-id") ? { system: flag(args, "system-id") } : {}),
+        ...(Object.keys(produces).length ? { produces } : {}),
+        ...(consumes.length ? { consumes } : {}),
+        agentIdentity: { kind: "human", id: "cli", attested: false },
+    });
+    const exit = result.verdict === "pass" ? 0 : result.verdict === "fail" ? 1 : 2;
+    if (json) {
+        process.stdout.write(JSON.stringify({
+            status: result.verdict,
+            envelope_hash: result.envelopeHash,
+        }) + "\n");
+        return exit;
+    }
+    const gates = result.envelope.gates;
+    for (const g of gates) {
+        const mark = g.outcome === "pass" ? "✓" : g.outcome === "declined" ? "·" : "✗";
+        const retry = g.retries > 0
+            ? `  (retries: ${g.retries} — pass-on-retry, not clean)`
+            : "";
+        process.stdout.write(`  ${mark} ${g.name.padEnd(12)} ${String(g.duration_ms).padStart(6)}ms${retry}\n`);
+    }
+    process.stdout.write(`\n  verdict: ${String(result.verdict).toUpperCase()}\n`);
+    process.stdout.write(`  envelope: ${result.envelopePath}\n`);
+    process.stdout.write(`  binding-hash: ${result.envelope.binding_hash.slice(0, 12)}…\n`);
+    return exit;
+}
+//# sourceMappingURL=cli.js.map

package/dist/internal/system/verify/declined-reasons.js

@@ -0,0 +1,61 @@
+/**
+ * Declined-gate reasons live in component.toml and are copied verbatim into
+ * every verify envelope. They must describe a standing property of the
+ * component (absent tooling, unconfigured substrate, out-of-scope concern) —
+ * never a specific change, unit, or diff. A false reason launders an unrun
+ * gate as a considered decision.
+ */
+export class DeclinedReasonError extends Error {
+    name = "DeclinedReasonError";
+}
+/**
+ * Wording shapes frozen out by gate-declined-reasons-accurate. Anchored to
+ * the phrases that once justified skipping arch/contract/size for a long-past
+ * dependency refresh.
+ */
+export const CHANGE_SPECIFIC_REASON_PATTERNS = [
+    /\bthe upgrade\b/i,
+    /\bthe dependency refresh\b/i,
+    /\bthis change\b/i,
+    /\bthe change\b/i,
+    /\bthis unit\b/i,
+    /\bthe unit's\b/i,
+];
+/**
+ * The size gate measures diff magnitude (`size_budget`); scope is a different
+ * gate. Declining size because "scope bounds the change" conflates the two.
+ */
+export const SIZE_SCOPE_CONFLATION_PATTERNS = [
+    /\bbounded by\b[\s\S]{0,40}\bscope\b/i,
+    /\bscope\b[\s\S]{0,40}\bbound/i,
+    /\bfile scope\b/i,
+    /\bscope is enforced\b/i,
+    /\benforced from\b[\s\S]{0,40}\bunit\b/i,
+];
+export function matchingChangeSpecificPattern(reason) {
+    return CHANGE_SPECIFIC_REASON_PATTERNS.find((re) => re.test(reason));
+}
+export function matchingSizeScopeConflation(reason) {
+    return SIZE_SCOPE_CONFLATION_PATTERNS.find((re) => re.test(reason));
+}
+/**
+ * Fail closed when any declined reason is change-specific, or when `size` is
+ * declined on the grounds that scope bounds it.
+ */
+export function assertStandingDeclinedReasons(declined) {
+    for (const { name, reason } of declined) {
+        const changeHit = matchingChangeSpecificPattern(reason);
+        if (changeHit) {
+            throw new DeclinedReasonError(`gate "${name}": declined reason must state a standing component property, ` +
+                `not a specific change/unit/diff (matched ${changeHit}): ${reason}`);
+        }
+        if (name === "size") {
+            const sizeHit = matchingSizeScopeConflation(reason);
+            if (sizeHit) {
+                throw new DeclinedReasonError(`gate "size": declined reason must not conflate size with scope ` +
+                    `(matched ${sizeHit}); bind size_budget or give a standing size reason: ${reason}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=declined-reasons.js.map

package/dist/internal/system/verify/index.js

@@ -0,0 +1,188 @@
+/**
+ * verify — ring 1. Orchestrates: resolve the manifest, run the bound gates at
+ * the component root, mint a Contract B envelope, sign it with the harness
+ * binary key, validate it against schema/envelope.schema.json, write it, and
+ * append an `envelope` event to the ledger.
+ *
+ * An agent cannot fake a green result: the signature is over the canonical
+ * envelope body and only the harness key produces it, and verify re-runs every
+ * gate rather than trusting any prior claim.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, basename, isAbsolute, resolve } from "node:path";
+import { packageSchemaDir, targetOwnedPaths, targetPath } from "../assets.js";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormatsDefault from "ajv-formats";
+// ajv-formats ships as CJS: the default import resolves to module.exports, which
+// is the plugin function at runtime. NodeNext's static view disagrees — assert it.
+const addFormats = addFormatsDefault;
+import { append as ledgerAppend, read as ledgerRead } from "../ledger/index.js";
+import { loadManifest, loadProfile, resolveManifest, } from "../manifest/index.js";
+import { runGates } from "../runner/index.js";
+import { assertStandingDeclinedReasons } from "./declined-reasons.js";
+import { loadOrCreateKey, signCanonical } from "./signing.js";
+import { attestScope } from "../agentops/scope.js";
+export { assertStandingDeclinedReasons, CHANGE_SPECIFIC_REASON_PATTERNS, DeclinedReasonError, matchingChangeSpecificPattern, matchingSizeScopeConflation, SIZE_SCOPE_CONFLATION_PATTERNS, } from "./declined-reasons.js";
+const HARNESS_VERSION = "0.1.0";
+const SCHEMA_ID = "https://harness.local/schema/envelope.schema.json";
+function buildAjv() {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+    for (const f of ["envelope.schema.json"]) {
+        ajv.addSchema(JSON.parse(readFileSync(join(packageSchemaDir(), f), "utf8")));
+    }
+    return ajv;
+}
+/** Hash produced files; look up the latest produced hash for consumed artifacts. */
+function buildArtifacts(componentDir, ledgerDir, produces, consumes) {
+    const out = {};
+    if (produces && Object.keys(produces).length) {
+        out.produced = Object.entries(produces).map(([name, path]) => {
+            const full = isAbsolute(path) ? path : join(componentDir, path);
+            const hash = createHash("sha256")
+                .update(readFileSync(full))
+                .digest("hex");
+            return { name, hash, path };
+        });
+    }
+    if (consumes && consumes.length) {
+        const latest = new Map();
+        if (existsSync(ledgerDir)) {
+            for (const e of ledgerRead(ledgerDir)) {
+                if (e.type !== "envelope")
+                    continue;
+                const b = e.body;
+                for (const p of b.artifacts?.produced ?? [])
+                    latest.set(p.name, p.hash);
+            }
+        }
+        out.consumed = consumes.map((name) => ({
+            name,
+            hash: latest.get(name) ?? "unresolved",
+        }));
+    }
+    return out.produced || out.consumed ? out : undefined;
+}
+/**
+ * pass/fail policy shared by every ring: all-skip is never a pass; only
+ * blocking/changed-lines failures fail the verdict (advisory never does).
+ * `harness gate --pre` (ring 0) reuses this so it can never disagree with
+ * ring 1 about what a "failing" gate means.
+ */
+export function verdictOf(gates) {
+    if (gates.length === 0)
+        return "halt"; // all-skip is never a pass
+    const failed = gates.some((g) => g.outcome === "fail" &&
+        (g.severity === "blocking" || g.severity === "changed-lines"));
+    return failed ? "fail" : "pass";
+}
+export function verify(opts) {
+    const componentDir = resolve(opts.componentDir ?? process.cwd());
+    const owned = targetOwnedPaths(componentDir);
+    const profilesDir = opts.profilesDir ?? targetPath(componentDir, "profiles");
+    const componentId = opts.componentId ?? basename(componentDir);
+    const keyDir = opts.keyDir ?? owned.harnessDir;
+    const ledgerDir = opts.ledgerDir ?? owned.ledgerDir;
+    const startedAt = opts.now ?? new Date().toISOString();
+    const identity = opts.agentIdentity ?? {
+        kind: "ci",
+        id: "harness",
+        attested: false,
+    };
+    const manifest = loadManifest(owned.componentToml);
+    const profile = loadProfile(join(profilesDir, manifest.harness.profile, "bindings.toml"));
+    const resolved = resolveManifest(manifest, profile, { context: "verify" });
+    assertStandingDeclinedReasons(resolved.declined);
+    const t0 = Date.now();
+    const gateRuns = runGates(resolved.bound, { cwd: componentDir });
+    const gateVerdict = verdictOf(gateRuns);
+    const scope = attestScope({
+        componentDir,
+        unitId: opts.unitId,
+        ...(opts.baseRef ? { baseRef: opts.baseRef } : {}),
+        ...(opts.specsDir ? { specsDir: opts.specsDir } : {}),
+    });
+    // Scope attestation HALTs verify only when it was actually attempted — a unit
+    // context was supplied via --base + --specs — and failed. A contextless run
+    // (the CI dogfood, ad-hoc `harness verify`) records the scope gate as declined
+    // and takes its verdict from the bound gates. The "an unattested unit may not
+    // merge" rule is enforced in mergeGate, not here.
+    const verdict = scope.attempted && !scope.attested ? "halt" : gateVerdict;
+    const artifacts = buildArtifacts(componentDir, ledgerDir, opts.produces, opts.consumes);
+    const envelope = {
+        envelope_version: "2.0",
+        harness_version: HARNESS_VERSION,
+        policy_version: resolved.policyVersion,
+        profile_version: profile.profileVersion,
+        binding_hash: resolved.bindingHash,
+        component_id: componentId,
+        feature_id: opts.featureId ?? null,
+        session_id: opts.sessionId ?? null,
+        unit_id: opts.unitId,
+        spec_hash: opts.specHash ?? "0".repeat(8),
+        agent_identity: identity,
+        started_at: startedAt,
+        duration_ms: Date.now() - t0,
+        gates: [
+            ...gateRuns.map((g) => ({
+                name: g.name,
+                outcome: g.outcome,
+                severity: g.severity,
+                duration_ms: g.durationMs,
+                retries: g.retries,
+            })),
+            {
+                name: "scope",
+                outcome: scope.attested ? "pass" : scope.attempted ? "fail" : "declined",
+                severity: scope.attempted ? "blocking" : "advisory",
+                duration_ms: 0,
+                retries: 0,
+                ...(scope.attempted
+                    ? {}
+                    : { declined_reason: scope.reason ?? "scope was not attested" }),
+            },
+            ...resolved.declined.map((d) => ({
+                name: d.name,
+                outcome: "declined",
+                severity: "advisory",
+                duration_ms: 0,
+                retries: 0,
+                declined_reason: d.reason,
+            })),
+        ],
+        ...(artifacts ? { artifacts } : {}),
+        scope_attested: scope.attested,
+        scope_evidence: {
+            base_ref: opts.baseRef ?? null,
+            changed_files: scope.changedFiles,
+            effective_scope: scope.effectiveScope,
+            violations: scope.violations,
+            reason: scope.reason ?? null,
+        },
+        verdict,
+        sarif_path: `.harness/reports/${startedAt.replace(/[:.]/g, "-")}_${opts.unitId.replace(/[#/]/g, "-")}.sarif`,
+    };
+    const { privateKey } = loadOrCreateKey(keyDir);
+    envelope.signature = signCanonical(envelope, privateKey);
+    const ajv = buildAjv();
+    const validate = ajv.getSchema(SCHEMA_ID);
+    if (!validate(envelope)) {
+        throw new Error("minted envelope failed schema validation:\n" +
+            ajv.errorsText(validate.errors, { separator: "\n" }));
+    }
+    const reportsDir = targetPath(componentDir, ".harness", "reports");
+    mkdirSync(reportsDir, { recursive: true });
+    const envelopePath = join(reportsDir, `${startedAt.replace(/[:.]/g, "-")}_${opts.unitId.replace(/[#/]/g, "-")}.json`);
+    writeFileSync(envelopePath, JSON.stringify(envelope, null, 2) + "\n");
+    const appended = ledgerAppend(ledgerDir, {
+        system: opts.system ?? componentId,
+        actor: { kind: "harness", id: `harness@${HARNESS_VERSION}` },
+        type: "envelope",
+        body: envelope,
+        sig: envelope.signature,
+        ts: startedAt,
+    });
+    return { verdict, envelope, envelopePath, envelopeHash: appended.hash };
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/verify/signing.js

@@ -0,0 +1,79 @@
+/**
+ * signing — the harness binary key. Ed25519, detached signatures over the
+ * canonical envelope body (every field except `signature`).
+ *
+ * v1 key management: one keypair per component, generated on first `verify` and
+ * stored at <keyDir>/signing-key.pem (private, gitignored) + signing-key.pub.
+ * Multi-operator key distribution is a deferred decision (solution design §13).
+ */
+import { generateKeyPairSync, sign, verify as cryptoVerify, createPrivateKey, createPublicKey, } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, } from "node:fs";
+import { join } from "node:path";
+const PRIV = "signing-key.pem";
+const PUB = "signing-key.pub";
+/** True iff an operator key already exists (door approval requires one). */
+export function operatorKeyExists(keyDir) {
+    return existsSync(join(keyDir, "operator-key.pem"));
+}
+/**
+ * Read-only: the operator's public key, or undefined if none has been
+ * initialized at `keyDir` yet. Never creates one — used by every reader that
+ * needs to verify a `door.decided` signature (mergeGate, door cli, metrics).
+ */
+export function loadOperatorPublicKey(keyDir) {
+    const pubPath = join(keyDir, "operator-key.pub");
+    if (!existsSync(pubPath))
+        return undefined;
+    return createPublicKey(readFileSync(pubPath, "utf8"));
+}
+/** Deterministic serialization: sorted keys, no whitespace, undefined dropped. */
+export function canonicalJSON(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return "[" + value.map(canonicalJSON).join(",") + "]";
+    const obj = value;
+    const keys = Object.keys(obj)
+        .filter((k) => obj[k] !== undefined)
+        .sort();
+    return ("{" +
+        keys.map((k) => JSON.stringify(k) + ":" + canonicalJSON(obj[k])).join(",") +
+        "}");
+}
+export function loadOrCreateKey(keyDir, name = "signing-key", opts = {}) {
+    const create = opts.create ?? true;
+    const privPath = join(keyDir, name === "signing-key" ? PRIV : `${name}.pem`);
+    const pubPath = join(keyDir, name === "signing-key" ? PUB : `${name}.pub`);
+    if (existsSync(privPath)) {
+        const privateKey = createPrivateKey(readFileSync(privPath, "utf8"));
+        const publicKey = existsSync(pubPath)
+            ? createPublicKey(readFileSync(pubPath, "utf8"))
+            : createPublicKey(privateKey);
+        return { privateKey, publicKey };
+    }
+    if (!create) {
+        throw new Error(`no key at ${privPath} — it must be created explicitly, not auto-provisioned`);
+    }
+    mkdirSync(keyDir, { recursive: true });
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    writeFileSync(privPath, privateKey.export({ type: "pkcs8", format: "pem" }));
+    writeFileSync(pubPath, publicKey.export({ type: "spki", format: "pem" }));
+    try {
+        chmodSync(privPath, 0o600);
+    }
+    catch {
+        /* best effort on platforms without POSIX modes */
+    }
+    return { privateKey, publicKey };
+}
+/** Sign the canonical form of `body` with `signature` removed. Returns base64. */
+export function signCanonical(body, privateKey) {
+    const { signature: _drop, ...rest } = body;
+    return sign(null, Buffer.from(canonicalJSON(rest), "utf8"), privateKey).toString("base64");
+}
+/** Verify a base64 detached signature over the canonical body (minus `signature`). */
+export function verifySignature(body, signature, publicKey) {
+    const { signature: _drop, ...rest } = body;
+    return cryptoVerify(null, Buffer.from(canonicalJSON(rest), "utf8"), publicKey, Buffer.from(signature, "base64"));
+}
+//# sourceMappingURL=signing.js.map