@mikenguyen69/harness 0.1.0-beta.1

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

@@ -0,0 +1,184 @@
+/**
+ * `harness door` / `harness merge` — the operator's decision surface.
+ *
+ *   harness door list                          open doors, highest decision value first
+ *   harness door show <id>
+ *   harness door approve <id> --reason <r> [--who <w>]
+ *   harness door reject  <id> --reason <r> [--who <w>]
+ *   harness door init-key                      one-time: create the operator key
+ *   harness merge <unit-id> --check [--system <system.toml>] [facts…]
+ *   harness merge <unit-id> --landed <sha> [--system <system.toml>] [facts…]
+ *
+ * merge facts: --one-way | --two-way | --adds-dependency | --schema-change
+ *              --security | --gate-external | --artifact-producer-change
+ *              --component <id> | --mode <name>
+ *
+ * `--check` authorizes without writing `unit.merged`; the actuator lands Git,
+ * then calls the `--landed` form to record the actual object id. A one-way /
+ * propose-only class opens a door and blocks until an operator approves it.
+ * `unit.merged` is written nowhere else. Every view of
+ * door state here re-verifies `door.decided` against the operator public key
+ * (ADR 0002) — an unsigned or forged decision displays and merges as if it
+ * never happened.
+ */
+import { read as ledgerRead } from "../ledger/index.js";
+import { loadOperatorPublicKey, loadOrCreateKey, operatorKeyExists } from "../verify/signing.js";
+import { classifyMerge } from "./classify.js";
+import { DoorError, bareUnitId, decideDoor, mergeGate, mergeUnit, openDoor, projectDoors, sweepExpired, } from "./index.js";
+import { doorMetricsFromLedger } from "./metrics.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+const has = (args, name) => args.includes(`--${name}`);
+function opts(args) {
+    return {
+        ledgerDir: flag(args, "ledger") ?? ".harness/ledger",
+        keyDir: flag(args, "keys") ?? ".harness",
+    };
+}
+export function doorCommand(args) {
+    const sub = args[0];
+    if (sub === "init-key") {
+        const keyDir = opts(args).keyDir;
+        const existed = operatorKeyExists(keyDir);
+        loadOrCreateKey(keyDir, "operator-key");
+        process.stdout.write(existed
+            ? `operator key already exists at ${keyDir}/operator-key.pem\n`
+            : `operator key created at ${keyDir}/operator-key.pem — keep this private; only a human should hold it\n`);
+        return 0;
+    }
+    if (sub === "list") {
+        if (has(args, "sweep")) {
+            const gone = sweepExpired(opts(args));
+            if (gone.length)
+                process.stderr.write(`expired: ${gone.join(", ")}\n`);
+        }
+        const pub = loadOperatorPublicKey(opts(args).keyDir);
+        const doors = [
+            ...projectDoors(ledgerRead(opts(args).ledgerDir), pub).values(),
+        ]
+            .filter((d) => d.state === "opened")
+            .sort((a, b) => Date.parse(a.openedAt) - Date.parse(b.openedAt));
+        for (const d of doors)
+            process.stdout.write(`${d.id}  ${d.unitId}  [${d.classes.join(", ")}]  opened ${d.openedAt}\n`);
+        if (doors.length === 0)
+            process.stderr.write("no open doors\n");
+        return 0;
+    }
+    if (sub === "metrics") {
+        const window = Number(flag(args, "window") ?? 30);
+        const m = doorMetricsFromLedger(opts(args).ledgerDir, Date.now(), window, opts(args).keyDir);
+        process.stdout.write(JSON.stringify(m, null, 2) + "\n");
+        if (m.rubberStampFlag) {
+            process.stderr.write(`⚠ rubber-stamp: approval ${(m.approvalRate * 100).toFixed(0)}% at ${m.medianDecisionSeconds}s median — below ${m.thresholds.approvalRateThreshold * 100}% / ${m.thresholds.minDeliberationSeconds}s\n`);
+            return 1;
+        }
+        return 0;
+    }
+    if (sub === "show") {
+        const pub = loadOperatorPublicKey(opts(args).keyDir);
+        const d = projectDoors(ledgerRead(opts(args).ledgerDir), pub).get(args[1] ?? "");
+        if (!d) {
+            process.stderr.write("no such door\n");
+            return 1;
+        }
+        process.stdout.write(JSON.stringify(d, null, 2) + "\n");
+        return 0;
+    }
+    if (sub === "approve" || sub === "reject") {
+        const id = args[1];
+        const reason = flag(args, "reason");
+        if (!id || !reason) {
+            process.stderr.write(`harness door ${sub} <id> --reason "<why>" [--who <w>]\n`);
+            return 2;
+        }
+        try {
+            const e = decideDoor(id, sub === "approve" ? "approved" : "rejected", reason, flag(args, "who") ?? "operator", opts(args));
+            process.stdout.write(`${sub === "approve" ? "approved" : "rejected"} ${id} (seq ${e.seq})\n`);
+            return 0;
+        }
+        catch (e) {
+            process.stderr.write(`${e.message}\n`);
+            return e instanceof DoorError ? 1 : 2;
+        }
+    }
+    process.stderr.write("harness door <list [--sweep] | show <id> | metrics [--window N] | approve <id> --reason … | reject <id> --reason … | init-key>\n");
+    return 2;
+}
+function factsFrom(args) {
+    const f = {};
+    if (has(args, "one-way"))
+        f.unitDoor = "one-way";
+    if (has(args, "two-way"))
+        f.unitDoor = "two-way";
+    if (has(args, "adds-dependency"))
+        f.addsDependency = true;
+    if (has(args, "schema-change"))
+        f.touchesSchemaOrApi = true;
+    if (has(args, "security"))
+        f.touchesSecurity = true;
+    if (has(args, "gate-external"))
+        f.gateExternal = true;
+    if (has(args, "artifact-producer-change"))
+        f.artifactProducerChange = true;
+    const component = flag(args, "component");
+    if (component)
+        f.component = component;
+    const mode = flag(args, "mode");
+    if (mode)
+        f.mode = mode;
+    return f;
+}
+export function mergeCommand(args) {
+    const unitId = args[0];
+    if (!unitId || unitId.startsWith("--")) {
+        process.stderr.write("harness merge <unit-id> <--check | --landed <sha>> [--system <system.toml>] [facts…]\n");
+        return 2;
+    }
+    const o = {
+        ...opts(args),
+        ...(flag(args, "system") ? { systemTomlPath: flag(args, "system") } : {}),
+    };
+    const facts = factsFrom(args);
+    const landed = flag(args, "landed") ?? "0000000";
+    if (has(args, "check")) {
+        const gate = mergeGate(unitId, facts, o);
+        if (gate.ok) {
+            process.stdout.write(`merge authorized ${unitId}\n`);
+            return 0;
+        }
+        return reportBlockedMerge(unitId, facts, o, gate.blockedBy);
+    }
+    const result = mergeUnit(unitId, facts, landed, o);
+    if (result.merged) {
+        process.stdout.write(`merged ${unitId}\n`);
+        return 0;
+    }
+    return reportBlockedMerge(unitId, facts, o, result.blockedBy);
+}
+function reportBlockedMerge(unitId, facts, o, blockedBy) {
+    // blocked — if it's a door situation, make sure one is open
+    const classification = classifyMerge(facts, o.systemTomlPath);
+    if (classification.requiresHuman) {
+        const pub = loadOperatorPublicKey(o.keyDir);
+        const existing = [
+            ...projectDoors(ledgerRead(o.ledgerDir), pub).values(),
+        ].find((d) => bareUnitId(d.unitId) === bareUnitId(unitId) &&
+            (d.state === "opened" || d.state === "rejected"));
+        if (!existing) {
+            const id = openDoor(unitId, classification, o);
+            process.stderr.write(`⛔ merge blocked — door ${id} opened. Decide with: harness door approve ${id} --reason "…"\n`);
+        }
+        else if (existing.state === "rejected") {
+            process.stderr.write(`⛔ merge blocked — door ${existing.id} was REJECTED: ${existing.reason}\n`);
+        }
+        else {
+            process.stderr.write(`⛔ merge blocked — door ${existing.id} awaits a decision\n`);
+        }
+        return 2;
+    }
+    process.stderr.write(`⛔ merge blocked — ${blockedBy}\n`);
+    return 2;
+}
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,249 @@
+/**
+ * doors — the halt-and-decide gate on the transition to `merged`.
+ *
+ * A door is a ledger fact (door.opened → door.decided | door.expired), not a
+ * stored record. A one-way (or propose-only) class on a merge means the unit
+ * CANNOT reach `merged` until an operator decides the door — enforced by
+ * `mergeGate`; `mergeUnit` is the only writer of `unit.merged` and is called
+ * only after the actuator has actually landed Git.
+ *
+ * `door.decided` is signed by the operator key (ADR 0002) and every reader
+ * that treats a door as approved or rejected — `mergeGate` above all —
+ * re-verifies that signature against the public key at `opts.keyDir`. A
+ * `door.decided` event with no key material to check against, a missing
+ * `sig`, or a `sig` that doesn't verify is never applied: the door simply
+ * stays in its prior state, so an unsigned or forged decision cannot unblock
+ * a merge. The key itself is never auto-provisioned on the decide path — see
+ * `harness door init-key`.
+ */
+import { append, read as ledgerRead, } from "../ledger/index.js";
+import { projectUnits } from "../units/index.js";
+import { canonicalJSON, loadOperatorPublicKey, loadOrCreateKey, verifySignature, } from "../verify/signing.js";
+import { sign } from "node:crypto";
+import { classifyMerge, } from "./classify.js";
+const DEFAULT_EXPIRY_MS = 24 * 60 * 60 * 1000;
+export function doorId(unitId, openSeq) {
+    return `door-${unitId.replace(/[#/]/g, "-")}-${openSeq}`;
+}
+/** Strip a `system#` prefix, if any — units and doors may be addressed either way. */
+export function bareUnitId(id) {
+    return id.includes("#") ? id.slice(id.indexOf("#") + 1) : id;
+}
+/**
+ * Fold door.* events into current per-door state.
+ *
+ * `operatorPublicKey`, when given, gates every `door.decided`: an event with
+ * a missing or invalid signature is skipped entirely (the door stays
+ * "opened") instead of being trusted. Omitting the key preserves the old,
+ * unverified projection — used only by read-only, cross-machine aggregation
+ * (the hub) that does not hold the operator's key material and never writes
+ * `unit.merged`; every writer/decider path always passes the key.
+ */
+export function projectDoors(events, operatorPublicKey) {
+    const doors = new Map();
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        const b = e.body;
+        if (e.type === "door.opened" && b.door_id && b.unit_id) {
+            doors.set(b.door_id, {
+                id: b.door_id,
+                unitId: b.unit_id,
+                classes: b.classes ?? [],
+                state: "opened",
+                openedAt: e.ts,
+                expiresAt: b.expires_at ??
+                    new Date(Date.parse(e.ts) + DEFAULT_EXPIRY_MS).toISOString(),
+                lastSeq: e.seq,
+            });
+        }
+        else if (e.type === "door.decided" && b.door_id) {
+            const d = doors.get(b.door_id);
+            if (d && d.state === "opened") {
+                if (operatorPublicKey) {
+                    const verified = e.sig !== undefined &&
+                        verifySignature({ id: b.door_id, verdict: b.verdict, reason: b.reason, who: b.who }, e.sig, operatorPublicKey);
+                    if (!verified)
+                        continue; // unsigned or forged — never applied
+                }
+                d.state = b.verdict === "approved" ? "approved" : "rejected";
+                if (b.reason !== undefined)
+                    d.reason = b.reason;
+                if (b.who !== undefined)
+                    d.who = b.who;
+                d.decidedAt = e.ts;
+                d.lastSeq = e.seq;
+            }
+        }
+        else if (e.type === "door.expired" && b.door_id) {
+            const d = doors.get(b.door_id);
+            if (d && d.state === "opened") {
+                d.state = "expired";
+                d.lastSeq = e.seq;
+            }
+        }
+    }
+    return doors;
+}
+/** The operator public key for these options, if one has been initialized. */
+function operatorKeyFor(opts) {
+    return loadOperatorPublicKey(opts.keyDir ?? ".harness");
+}
+/** Open a door for a unit whose merge classification requires one. Returns the door id, or null if no human is required. */
+export function openDoor(unitId, classification, opts) {
+    if (!classification.requiresHuman)
+        return null;
+    const events = ledgerRead(opts.ledgerDir);
+    const seq = (events.at(-1)?.seq ?? -1) + 1;
+    const id = doorId(unitId, seq);
+    const ts = opts.now ?? new Date().toISOString();
+    const ev = {
+        system: opts.system ?? events[0]?.system ?? unitId,
+        actor: { kind: "harness", id: "harness" },
+        type: "door.opened",
+        ts,
+        body: {
+            door_id: id,
+            unit_id: unitId,
+            classes: classification.fired.map((f) => `${f.source}:${f.match}(${f.class})`),
+            expires_at: new Date(Date.parse(ts) + DEFAULT_EXPIRY_MS).toISOString(),
+        },
+    };
+    append(opts.ledgerDir, ev);
+    return id;
+}
+export class DoorError extends Error {
+    name = "DoorError";
+}
+/**
+ * Decide an open door. Requires a reason and a pre-existing operator key —
+ * this never creates one (`harness door init-key` does that, deliberately,
+ * once, before any decision is possible).
+ */
+export function decideDoor(id, verdict, reason, who, opts) {
+    if (reason.trim() === "")
+        throw new DoorError("a decision needs a reason");
+    const keyDir = opts.keyDir ?? ".harness";
+    let sig;
+    try {
+        const { privateKey } = loadOrCreateKey(keyDir, "operator-key", {
+            create: false,
+        });
+        sig = sign(null, Buffer.from(canonicalJSON({ id, verdict, reason, who }), "utf8"), privateKey).toString("base64");
+    }
+    catch {
+        throw new DoorError(`no operator key at ${keyDir} — run "harness door init-key" first (a human, not an agent, should hold this key)`);
+    }
+    const events = ledgerRead(opts.ledgerDir);
+    const door = projectDoors(events, operatorKeyFor(opts)).get(id);
+    if (!door)
+        throw new DoorError(`no such door: ${id}`);
+    if (door.state !== "opened")
+        throw new DoorError(`door ${id} is already ${door.state}`);
+    return append(opts.ledgerDir, {
+        system: opts.system ?? events[0]?.system ?? door.unitId,
+        actor: { kind: "human", id: who },
+        type: "door.decided",
+        ts: opts.now ?? new Date().toISOString(),
+        sig,
+        body: { door_id: id, unit_id: door.unitId, verdict, reason, who },
+    });
+}
+/**
+ * `scope_attested` from a unit's most recent `envelope` event — `undefined` if
+ * it has none. Scope attestation is a merge precondition (it is NOT a HALT
+ * inside verify): a unit whose latest verify envelope did not attest its diff
+ * against a declared scope may not reach `merged`.
+ */
+function latestEnvelopeScopeAttested(events, bareId) {
+    let attested;
+    for (const e of [...events].sort((a, b) => a.seq - b.seq)) {
+        if (e.type !== "envelope")
+            continue;
+        const b = e.body;
+        if (bareUnitId(b.unit_id ?? "") === bareId)
+            attested = b.scope_attested === true;
+    }
+    return attested;
+}
+/**
+ * Can this unit reach `merged`? It must be in-review, its latest verify
+ * envelope must carry `scope_attested: true`, and every human-required door
+ * class must have a matching APPROVED door. This function is read-only; the
+ * actuator uses it before Git land, then `mergeUnit` rechecks it when
+ * recording the post-land fact.
+ */
+export function mergeGate(unitId, facts, opts) {
+    const events = ledgerRead(opts.ledgerDir);
+    const bare = bareUnitId(unitId);
+    const unit = projectUnits(events).get(bare);
+    const classification = classifyMerge(facts, opts.systemTomlPath);
+    if (unit?.mode === "explore") {
+        throw new DoorError(`unit "${unitId}" is mode: explore — explore units have NO edge to merged (D7). Exit via abort or graduate.`);
+    }
+    if (!unit || unit.state !== "in-review") {
+        return {
+            ok: false,
+            blockedBy: `unit is ${unit?.state ?? "unknown"}, not in-review`,
+            classification,
+        };
+    }
+    const scopeAttested = latestEnvelopeScopeAttested(events, bare);
+    if (scopeAttested !== true) {
+        return {
+            ok: false,
+            blockedBy: scopeAttested === undefined
+                ? "no verify envelope for this unit — scope attestation is required before merge (run `harness verify --base <ref> --specs <dir>`)"
+                : "latest verify envelope has scope_attested: false — re-run `harness verify --base <ref> --specs <dir>` with the diff inside the unit's declared scope",
+            classification,
+        };
+    }
+    if (!classification.requiresHuman)
+        return { ok: true, classification };
+    const approved = [
+        ...projectDoors(events, operatorKeyFor(opts)).values(),
+    ].some((d) => bareUnitId(d.unitId) === bare && d.state === "approved");
+    return approved
+        ? { ok: true, classification }
+        : {
+            ok: false,
+            blockedBy: "a one-way/propose-only door class fired and no approved door covers this unit",
+            classification,
+        };
+}
+/** Perform the merge — only through the gate. */
+export function mergeUnit(unitId, facts, landedSha, opts) {
+    const gate = mergeGate(unitId, facts, opts);
+    if (!gate.ok)
+        return {
+            merged: false,
+            ...(gate.blockedBy ? { blockedBy: gate.blockedBy } : {}),
+        };
+    const events = ledgerRead(opts.ledgerDir);
+    append(opts.ledgerDir, {
+        system: opts.system ?? events[0]?.system ?? unitId,
+        actor: { kind: "harness", id: "harness" },
+        type: "unit.merged",
+        ts: opts.now ?? new Date().toISOString(),
+        body: { unit_id: unitId, landed: landedSha },
+    });
+    return { merged: true };
+}
+/** Sweep: append door.expired for every open door past its expiry. */
+export function sweepExpired(opts) {
+    const now = Date.parse(opts.now ?? new Date().toISOString());
+    const events = ledgerRead(opts.ledgerDir);
+    const expired = [];
+    for (const d of projectDoors(events, operatorKeyFor(opts)).values()) {
+        if (d.state === "opened" && Date.parse(d.expiresAt) <= now) {
+            append(opts.ledgerDir, {
+                system: opts.system ?? events[0]?.system ?? d.unitId,
+                actor: { kind: "harness", id: "harness" },
+                type: "door.expired",
+                ts: new Date(now).toISOString(),
+                body: { door_id: d.id, unit_id: d.unitId },
+            });
+            expired.push(d.id);
+        }
+    }
+    return expired;
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/doors/metrics.js

@@ -0,0 +1,47 @@
+import { read as ledgerRead } from "../ledger/index.js";
+import { loadOperatorPublicKey } from "../verify/signing.js";
+import { classifyMerge } from "./classify.js";
+import { projectDoors } from "./index.js";
+function median(xs) {
+    if (xs.length === 0)
+        return null;
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+export function doorMetrics(events, now = Date.now(), windowDays = 30, operatorPublicKey) {
+    const cutoff = now - windowDays * 24 * 60 * 60 * 1000;
+    const doors = [...projectDoors(events, operatorPublicKey).values()];
+    const thresholds = classifyMerge({}).antiRubberStamp;
+    const inWindow = doors.filter((d) => Date.parse(d.decidedAt ?? d.openedAt) >= cutoff);
+    const decidedDoors = inWindow.filter((d) => d.state === "approved" || d.state === "rejected");
+    const approved = decidedDoors.filter((d) => d.state === "approved").length;
+    const rejected = decidedDoors.filter((d) => d.state === "rejected").length;
+    const expired = inWindow.filter((d) => d.state === "expired").length;
+    const open = doors.filter((d) => d.state === "opened").length;
+    const decisionSecs = decidedDoors
+        .filter((d) => d.decidedAt)
+        .map((d) => (Date.parse(d.decidedAt) - Date.parse(d.openedAt)) / 1000);
+    const med = median(decisionSecs);
+    const rate = decidedDoors.length ? approved / decidedDoors.length : null;
+    const rubberStampFlag = rate !== null &&
+        rate > thresholds.approvalRateThreshold &&
+        med !== null &&
+        med < thresholds.minDeliberationSeconds;
+    return {
+        windowDays,
+        decided: decidedDoors.length,
+        approved,
+        rejected,
+        expired,
+        open,
+        approvalRate: rate,
+        medianDecisionSeconds: med,
+        rubberStampFlag,
+        thresholds,
+    };
+}
+export function doorMetricsFromLedger(ledgerDir, now, windowDays, keyDir) {
+    return doorMetrics(ledgerRead(ledgerDir), now, windowDays, keyDir ? loadOperatorPublicKey(keyDir) : undefined);
+}
+//# sourceMappingURL=metrics.js.map

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

@@ -0,0 +1,45 @@
+/**
+ * `harness escape route <scenario-id>` — route a failed integration scenario to
+ * its owning component as a new fix unit.
+ *
+ *   harness escape route <scenario-id> --system <system.toml>
+ *                        [--ledger <dir>] [--context "<failing context>"]
+ */
+import { integrationReady, routeEscape } from "./index.js";
+import { loadSystem } from "../system/index.js";
+import { read as ledgerRead } from "../ledger/index.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+export function escapeCommand(args) {
+    const sub = args[0];
+    const ledgerDir = flag(args, "ledger") ?? ".harness/ledger";
+    const systemTomlPath = flag(args, "system");
+    if (sub === "ready") {
+        if (!systemTomlPath) {
+            process.stderr.write("harness escape ready <component-id> --system <system.toml>\n");
+            return 2;
+        }
+        const ok = integrationReady(args[1] ?? "", loadSystem(systemTomlPath), ledgerRead(ledgerDir));
+        process.stdout.write(ok ? "ready\n" : "not ready (a dep is not green)\n");
+        return ok ? 0 : 1;
+    }
+    if (sub === "route") {
+        const scenario = args[1];
+        if (!scenario || !systemTomlPath) {
+            process.stderr.write('harness escape route <scenario-id> --system <system.toml> [--context "…"]\n');
+            return 2;
+        }
+        const r = routeEscape(scenario, {
+            ledgerDir,
+            systemTomlPath,
+            ...(flag(args, "context") ? { failContext: flag(args, "context") } : {}),
+        });
+        process.stdout.write(`routed ${r.scenario} → ${r.owners.join(", ") || "(unrouted)"}; new unit ${r.newUnit}\n`);
+        return 0;
+    }
+    process.stderr.write("harness escape <route <scenario-id> | ready <component-id>> --system <system.toml>\n");
+    return 2;
+}
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1,81 @@
+/**
+ * escapes — ring 3 routing. A failing integration scenario is matched against
+ * `scenario_ownership` in system.toml, routed to the owning component(s) as a
+ * new scoped fix unit, and recorded as escape.detected → escape.routed. The
+ * failing context travels with the new unit.
+ */
+import picomatch from "picomatch";
+import { append, read as ledgerRead, } from "../ledger/index.js";
+import { loadSystem } from "../system/index.js";
+/** Which component(s) own failures matching `scenarioId`. */
+export function ownersOf(scenarioId, manifest) {
+    const owners = new Set();
+    for (const so of manifest.scenario_ownership) {
+        if (picomatch(so.match)(scenarioId))
+            for (const o of so.owns)
+                owners.add(o);
+    }
+    return [...owners];
+}
+/**
+ * Detect + route an escaped integration failure. Appends escape.detected,
+ * escape.routed, and unit.planned for the fix unit (deps = the owning
+ * components' latest work is implied; the unit carries the failing context).
+ */
+export function routeEscape(scenarioId, opts) {
+    const manifest = loadSystem(opts.systemTomlPath);
+    const owners = ownersOf(scenarioId, manifest);
+    const primary = owners[0] ?? "unrouted";
+    const events = ledgerRead(opts.ledgerDir);
+    const seq = (events.at(-1)?.seq ?? -1) + 1;
+    const newUnit = `${primary}#escape-${scenarioId.replace(/[^a-z0-9]+/gi, "-")}-${seq}`;
+    const ts = opts.now ?? new Date().toISOString();
+    const sys = manifest.system.id;
+    const actor = { kind: "harness", id: "integration-ring" };
+    append(opts.ledgerDir, {
+        system: sys,
+        actor,
+        type: "escape.detected",
+        ts,
+        body: {
+            scenario: scenarioId,
+            ...(opts.failContext ? { context: opts.failContext } : {}),
+        },
+    });
+    append(opts.ledgerDir, {
+        system: sys,
+        actor,
+        type: "escape.routed",
+        ts,
+        body: { scenario: scenarioId, owner: primary, owners, new_unit: newUnit },
+    });
+    append(opts.ledgerDir, {
+        system: sys,
+        actor,
+        type: "unit.planned",
+        ts,
+        body: {
+            unit_id: newUnit,
+            component: primary,
+            from_escape: scenarioId,
+            ...(opts.failContext ? { context: opts.failContext } : {}),
+        },
+    });
+    return { scenario: scenarioId, owners, newUnit };
+}
+/** Whether an integration component may run: every dep has a passing latest envelope. */
+export function integrationReady(componentId, manifest, events) {
+    const comp = manifest.component.find((c) => c.id === componentId);
+    if (!comp || comp.role !== "integration")
+        return false;
+    const latestVerdict = new Map();
+    for (const e of events) {
+        if (e.type !== "envelope")
+            continue;
+        const b = e.body;
+        if (b.component_id)
+            latestVerdict.set(b.component_id, b.verdict ?? "");
+    }
+    return (comp.deps ?? []).every((d) => latestVerdict.get(d) === "pass");
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,77 @@
+/**
+ * `harness explore` — the exploration lane's two exits.
+ *
+ *   harness explore abort    <unit-id> [--ledger <dir>]
+ *   harness explore graduate <unit-id> --intent "…" --scope "glob,glob"
+ *                            [--criterion "stmt|verifier"]... [--ledger <dir>]
+ */
+import { abortExplore, ExploreError, graduateExplore, } 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 exploreCommand(args) {
+    const sub = args[0];
+    const unitId = args[1];
+    const ledgerDir = flag(args, "ledger") ?? ".harness/ledger";
+    if (!unitId || unitId.startsWith("--")) {
+        process.stderr.write("harness explore <abort|graduate> <unit-id> …\n");
+        return 2;
+    }
+    try {
+        if (sub === "abort") {
+            const e = abortExplore(unitId, { ledgerDir });
+            process.stdout.write(`aborted ${unitId} (seq ${e.seq})\n`);
+            return 0;
+        }
+        if (sub === "graduate") {
+            const intent = flag(args, "intent");
+            const scope = (flag(args, "scope") ?? "")
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            if (!intent || scope.length === 0) {
+                process.stderr.write('harness explore graduate <unit-id> --intent "…" --scope "glob,glob" [--criterion "stmt|verifier"]…\n');
+                return 2;
+            }
+            const acceptanceCriteria = multi(args, "criterion").map((c) => {
+                const [statement, v] = c.split("|");
+                return v
+                    ? { statement: statement.trim(), verifier: v.trim() }
+                    : {
+                        statement: statement.trim(),
+                        manual: "carried from the spike; sharpen before build",
+                    };
+            });
+            const discovered = {
+                intent,
+                scope,
+                acceptanceCriteria: acceptanceCriteria.length
+                    ? acceptanceCriteria
+                    : [
+                        {
+                            statement: "TODO from the spike",
+                            manual: "sharpen before build",
+                        },
+                    ],
+            };
+            const r = graduateExplore(unitId, discovered, { ledgerDir });
+            process.stdout.write(`graduated ${unitId} → draft build spec ${r.draftSpecId}\n`);
+            return 0;
+        }
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return e instanceof ExploreError ? 1 : 2;
+    }
+    process.stderr.write("harness explore <abort|graduate> <unit-id> …\n");
+    return 2;
+}
+//# sourceMappingURL=cli.js.map