@mikenguyen69/harness 0.1.0-beta.1

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

@@ -0,0 +1,176 @@
+/**
+ * ledger — the record plane (schema/ledger-event.schema.json, solution design §5).
+ *
+ * One append-only, hash-chained event log per system, stored as JSONL segments
+ * under `.harness/ledger/`. Every event carries `prev_hash` (the previous
+ * event's `hash`) and `hash` (SHA-256 over this event's canonical JSON with the
+ * `hash` key removed). Any edit, reorder, deletion or truncation-in-the-middle
+ * is detectable by `verifyChain`.
+ *
+ * Invariants:
+ *   - seq is 0-based, strictly +1 per event, no gaps
+ *   - the genesis event (seq 0) has prev_hash = 64 zeros
+ *   - hashing is deterministic (canonical JSON: sorted keys, no whitespace,
+ *     undefined dropped) so a chain re-verifies byte-for-byte
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, appendFileSync, openSync, closeSync, unlinkSync, } from "node:fs";
+import { join } from "node:path";
+export const ZERO_HASH = "0".repeat(64);
+const SEGMENT_RE = /^\d{6}\.jsonl$/;
+const FIRST_SEGMENT = "000000.jsonl";
+export class LedgerConflict extends Error {
+    expected;
+    actual;
+    name = "LedgerConflict";
+    constructor(expected, actual) {
+        super(`ledger moved: expected tail ${expected.slice(0, 12)}…, found ${actual.slice(0, 12)}…`);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/** 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 sha256hex(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+/** The hash an event must carry: over its canonical form with `hash` removed. */
+export function hashEvent(event) {
+    return sha256hex(canonicalJSON(event));
+}
+function segmentFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((n) => SEGMENT_RE.test(n))
+        .sort();
+}
+/** Every event, in chain order, across all segments. */
+export function read(dir) {
+    const out = [];
+    for (const seg of segmentFiles(dir)) {
+        const text = readFileSync(join(dir, seg), "utf8");
+        for (const line of text.split("\n")) {
+            if (line.trim() === "")
+                continue;
+            out.push(JSON.parse(line));
+        }
+    }
+    return out;
+}
+/** The chain tail: seq and hash of the last event, or genesis defaults. */
+function tail(dir) {
+    const events = read(dir);
+    const last = events.at(-1);
+    return last
+        ? { seq: last.seq, hash: last.hash }
+        : { seq: -1, hash: ZERO_HASH };
+}
+/**
+ * Cross-process mutex over one ledger dir: an exclusive-create lock file. All
+ * writers serialize through this, so the tail read + CAS check + append is
+ * atomic against other processes on the same filesystem.
+ */
+function withLock(dir, fn) {
+    const lockPath = join(dir, ".lock");
+    const deadline = Date.now() + 5000;
+    let fd;
+    for (;;) {
+        try {
+            fd = openSync(lockPath, "wx");
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            if (Date.now() > deadline)
+                throw new Error(`ledger lock at ${lockPath} held too long`, { cause: e });
+            // brief sync spin — appends are sub-millisecond
+            const until = Date.now() + 3 + Math.floor(Math.random() * 5);
+            while (Date.now() < until) {
+                /* spin */
+            }
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        closeSync(fd);
+        try {
+            unlinkSync(lockPath);
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/** Append one event; returns the full event as written. */
+export function append(dir, ev, opts = {}) {
+    mkdirSync(dir, { recursive: true });
+    return withLock(dir, () => {
+        const prev = tail(dir);
+        if (opts.expectPrevHash !== undefined &&
+            opts.expectPrevHash !== prev.hash) {
+            throw new LedgerConflict(opts.expectPrevHash, prev.hash);
+        }
+        const unhashed = {
+            v: 1,
+            seq: prev.seq + 1,
+            ts: ev.ts ?? new Date().toISOString(),
+            system: ev.system,
+            actor: ev.actor,
+            type: ev.type,
+            prev_hash: prev.hash,
+            ...(ev.sig !== undefined ? { sig: ev.sig } : {}),
+            body: ev.body,
+        };
+        const event = { ...unhashed, hash: hashEvent(unhashed) };
+        const segs = segmentFiles(dir);
+        const target = segs.at(-1) ?? FIRST_SEGMENT;
+        appendFileSync(join(dir, target), JSON.stringify(event) + "\n", "utf8");
+        return event;
+    });
+}
+/** Recompute every hash and link; report the first break by seq. */
+export function verifyChain(dir) {
+    const events = read(dir);
+    let expectedPrev = ZERO_HASH;
+    for (let i = 0; i < events.length; i++) {
+        const e = events[i];
+        if (e.seq !== i)
+            return {
+                ok: false,
+                seq: e.seq,
+                reason: `seq ${e.seq} out of order (expected ${i})`,
+            };
+        if (e.prev_hash !== expectedPrev)
+            return {
+                ok: false,
+                seq: e.seq,
+                reason: `prev_hash mismatch at seq ${e.seq}`,
+            };
+        const { hash, ...unhashed } = e;
+        if (hashEvent(unhashed) !== hash)
+            return {
+                ok: false,
+                seq: e.seq,
+                reason: `content hash mismatch at seq ${e.seq} (tampered)`,
+            };
+        expectedPrev = hash;
+    }
+    return { ok: true, length: events.length };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,207 @@
+/**
+ * manifest — loads and resolves component.toml against schema/manifest.schema.json
+ * (Contract A). (ADR 0003: the file is component.toml, not harness.toml.)
+ *
+ * Invariants owned here:
+ *   - every required vocabulary gate is bound or explicitly declined with a
+ *     reason; absence is a config error ("all-skip ≠ pass" made structural)
+ *   - a gate name outside the closed vocabulary is a config error, not a skip
+ *   - `external: true` gates never run in `verify` context (hermetic rule)
+ *   - severity and cost are data — the maturity ramp never forks the tooling
+ *   - the resolved bindings hash into Contract B's binding_hash
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { parse as parseToml } from "smol-toml";
+export function isDeclination(e) {
+    return "declined" in e;
+}
+export class ManifestError extends Error {
+    name = "ManifestError";
+}
+/**
+ * The abstract vocabulary (ADR 0004). The standard owns these names and the
+ * semantics of "pass". CLOSED: an unknown gate name is a config error.
+ * `sec:*` is a namespace — any `sec:<tool>` gate (sec:deps, sec:secrets, …) is
+ * valid; see GATE_NAMESPACES.
+ */
+export const GATE_VOCABULARY = [
+    "spec",
+    "fmt",
+    "lint",
+    "types",
+    "test",
+    "arch",
+    "contract",
+    "size",
+    "gen:fresh",
+];
+/** Namespace prefixes: a gate named `<prefix><tool>` is in-vocabulary. */
+export const GATE_NAMESPACES = ["sec:"];
+/** Namespaces that must have ≥1 concrete gate present (security can't be silently absent). */
+const REQUIRED_NAMESPACES = ["sec:"];
+/** True iff `name` is a valid gate name under the closed vocabulary. */
+export function isVocabularyGate(name) {
+    return (GATE_VOCABULARY.includes(name) ||
+        GATE_NAMESPACES.some((p) => name.startsWith(p) && name.length > p.length));
+}
+// ---------------------------------------------------------------------------
+// parsing
+// ---------------------------------------------------------------------------
+function asEntry(name, v) {
+    if (typeof v !== "object" || v === null) {
+        throw new ManifestError(`gate "${name}": expected a binding or a declination table`);
+    }
+    const o = v;
+    if ("declined" in o) {
+        if (typeof o.declined !== "string" || o.declined.trim().length < 10) {
+            throw new ManifestError(`gate "${name}": declination reason must be ≥10 chars`);
+        }
+        return { declined: o.declined };
+    }
+    if (typeof o.run !== "string" || o.run === "") {
+        throw new ManifestError(`gate "${name}": binding needs a non-empty "run"`);
+    }
+    const severity = o.severity;
+    if (!["advisory", "changed-lines", "blocking"].includes(severity)) {
+        throw new ManifestError(`gate "${name}": severity "${String(o.severity)}" is not advisory|changed-lines|blocking`);
+    }
+    const cost = o.cost;
+    if (!["cheap", "expensive"].includes(cost)) {
+        throw new ManifestError(`gate "${name}": cost "${String(o.cost)}" is not cheap|expensive`);
+    }
+    const entry = { run: o.run, severity, cost };
+    if (typeof o.external === "boolean")
+        entry.external = o.external;
+    if (typeof o.timeout_seconds === "number")
+        entry.timeoutSeconds = o.timeout_seconds;
+    if (typeof o.snapshot_max_age_days === "number")
+        entry.snapshotMaxAgeDays = o.snapshot_max_age_days;
+    return entry;
+}
+function parseGates(raw) {
+    const gates = {};
+    const src = (raw ?? {});
+    for (const [name, v] of Object.entries(src)) {
+        if (!isVocabularyGate(name)) {
+            throw new ManifestError(`gate "${name}" is outside the closed vocabulary (${GATE_VOCABULARY.join(", ")}, sec:*)`);
+        }
+        gates[name] = asEntry(name, v);
+    }
+    return gates;
+}
+/** Parse and structurally validate a component.toml. */
+export function loadManifest(path) {
+    const raw = parseToml(readFileSync(path, "utf8"));
+    const h = (raw.harness ?? {});
+    if (typeof h.policy_version !== "string" || typeof h.profile !== "string") {
+        throw new ManifestError(`${path}: [harness] needs policy_version and profile`);
+    }
+    const mode = h.mode ?? "standard";
+    if (mode !== "standard" && mode !== "ratchet") {
+        throw new ManifestError(`${path}: [harness].mode must be standard|ratchet`);
+    }
+    const manifest = {
+        harness: { policyVersion: h.policy_version, profile: h.profile, mode },
+        gates: parseGates(raw.gates),
+    };
+    if (mode === "ratchet") {
+        const r = (raw.ratchet ?? {});
+        const baselinePath = r.baseline_path ?? ".harness/baseline.json";
+        manifest.ratchet = { baselinePath };
+    }
+    const sub = raw.substrate;
+    if (sub && typeof sub.enforced_from === "string") {
+        manifest.substrate = { enforcedFrom: sub.enforced_from };
+    }
+    return manifest;
+}
+/** Parse a profile's bindings.toml. */
+export function loadProfile(path) {
+    const raw = parseToml(readFileSync(path, "utf8"));
+    const h = (raw.harness ?? {});
+    return {
+        profileVersion: h.profile_version ?? "0.0.0",
+        gates: parseGates(raw.gates),
+    };
+}
+// ---------------------------------------------------------------------------
+// resolution
+// ---------------------------------------------------------------------------
+function bindingHash(bound) {
+    const canon = [...bound]
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .map((g) => ({
+        name: g.name,
+        run: g.run,
+        severity: g.severity,
+        cost: g.cost,
+        external: g.external,
+    }));
+    return createHash("sha256")
+        .update(JSON.stringify(canon), "utf8")
+        .digest("hex");
+}
+/**
+ * Resolve a component manifest against its profile: the component's entry for a
+ * gate wins; a gate the component omits falls back to the profile's entry.
+ *
+ * @param opts.context "verify" (default) rejects `external: true` gates — verify
+ * stays hermetic; those gates run only in the deploy phase.
+ */
+export function resolveManifest(manifest, profile, opts = {}) {
+    const context = opts.context ?? "verify";
+    const names = new Set([
+        ...Object.keys(profile.gates),
+        ...Object.keys(manifest.gates),
+    ]);
+    const bound = [];
+    const declined = [];
+    for (const name of names) {
+        const entry = manifest.gates[name] ?? profile.gates[name];
+        if (isDeclination(entry)) {
+            declined.push({ name, reason: entry.declined });
+            continue;
+        }
+        if (context === "verify" && entry.external) {
+            throw new ManifestError(`gate "${name}" is external:true — it runs only in the deploy phase, never in verify`);
+        }
+        bound.push({
+            name,
+            run: entry.run,
+            severity: entry.severity,
+            cost: entry.cost,
+            external: entry.external ?? false,
+            ...(entry.timeoutSeconds !== undefined
+                ? { timeoutSeconds: entry.timeoutSeconds }
+                : {}),
+            ...(entry.snapshotMaxAgeDays !== undefined
+                ? { snapshotMaxAgeDays: entry.snapshotMaxAgeDays }
+                : {}),
+        });
+    }
+    // every base vocabulary gate must be present (bound or declined)
+    const covered = new Set([
+        ...bound.map((g) => g.name),
+        ...declined.map((d) => d.name),
+    ]);
+    for (const req of GATE_VOCABULARY) {
+        if (!covered.has(req)) {
+            throw new ManifestError(`gate "${req}" is neither bound nor declined — absence is a config error`);
+        }
+    }
+    for (const ns of REQUIRED_NAMESPACES) {
+        if (![...covered].some((n) => n.startsWith(ns))) {
+            throw new ManifestError(`no "${ns}*" gate is bound or declined — security cannot be silently absent`);
+        }
+    }
+    return {
+        policyVersion: manifest.harness.policyVersion,
+        profile: manifest.harness.profile,
+        mode: manifest.harness.mode,
+        bound,
+        declined,
+        bindingHash: bindingHash(bound),
+    };
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * provenance — writes and verifies attestations for a merge: commit → spec →
+ * model → approval chain. Shaped after the SLSA Source Track (v1.2) — the
+ * track that covers authoring/review before the build — with in-toto link
+ * metadata as the wire format.
+ *
+ * Honesty caveat carried from Contract B: until signing lands, agent identity
+ * is self-reported. The attested flag makes that visible instead of pretended.
+ */
+export function writeAttestation(_a, _outDir) {
+    throw new Error("not implemented (skeleton)");
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,15 @@
+/**
+ * report — merges per-gate SARIF output into one file and wraps it in the
+ * Contract B envelope (schema/envelope.schema.json).
+ *
+ * The envelope is the provenance record and the ONLY evidence `work done`
+ * accepts — the agent's claim is never evidence; the artifact is.
+ *
+ * Kept in sync with the extended schema (review pass): `componentId`,
+ * `featureId`, `sessionId`, `artifacts`, `scopeAttested`, `signature`, and
+ * per-gate `preFailures`.
+ */
+export function emitEnvelope(_envelope, _outDir) {
+    throw new Error("not implemented (skeleton)");
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,74 @@
+/**
+ * runner — executes resolved gates: cheap first, retries recorded per gate,
+ * run at the component root with a scrubbed environment.
+ *
+ * "No network during verify" is enforced structurally, not by a sandbox: a
+ * gate that needs the network must declare `external: true`, and
+ * `resolveManifest({ context: "verify" })` refuses those. OS-level egress
+ * blocking is a substrate concern (later). What this module does: strip proxy
+ * vars, set HARNESS_HERMETIC=1, and run each `run` string at `cwd`.
+ *
+ * Deliberately thin: process orchestration is commodity. The differentiated
+ * product is manifest semantics (src/manifest), the envelope (src/verify +
+ * src/report), the generators (src/adapters), and the corpus.
+ */
+import { spawnSync } from "node:child_process";
+const STRIP_ENV = [
+    "HTTP_PROXY",
+    "HTTPS_PROXY",
+    "http_proxy",
+    "https_proxy",
+    "ALL_PROXY",
+    "all_proxy",
+    "NO_PROXY",
+    "no_proxy",
+    "npm_config_proxy",
+    "npm_config_https_proxy",
+];
+function hermeticEnv() {
+    const env = { ...process.env, HARNESS_HERMETIC: "1" };
+    for (const k of STRIP_ENV)
+        delete env[k];
+    return env;
+}
+function runOnce(cmd, cwd, cap) {
+    const r = spawnSync(cmd, {
+        cwd,
+        shell: true,
+        encoding: "utf8",
+        env: hermeticEnv(),
+        windowsHide: true,
+    });
+    const output = ((r.stdout ?? "") + (r.stderr ?? "")).slice(-cap);
+    return { code: r.status, output };
+}
+/** Run every bound gate, cheap-first. Ordering only — no fail-fast short-circuit yet. */
+export function runGates(bound, opts) {
+    const cap = opts.outputCap ?? 4000;
+    const maxRetries = opts.retries ?? 0;
+    const ordered = [...bound].sort((a, b) => {
+        const rank = (c) => (c === "cheap" ? 0 : 1);
+        return rank(a.cost) - rank(b.cost) || a.name.localeCompare(b.name);
+    });
+    const results = [];
+    for (const gate of ordered) {
+        const start = Date.now();
+        let attempt = 0;
+        let last = runOnce(gate.run, opts.cwd, cap);
+        while (last.code !== 0 && attempt < maxRetries) {
+            attempt++;
+            last = runOnce(gate.run, opts.cwd, cap);
+        }
+        results.push({
+            name: gate.name,
+            outcome: last.code === 0 ? "pass" : "fail",
+            severity: gate.severity,
+            durationMs: Date.now() - start,
+            retries: attempt,
+            exitCode: last.code,
+            output: last.output,
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,86 @@
+/**
+ * `harness runstatus` — the run-status overlay's write + read sides.
+ *
+ *   publish [--file <path>] --spool <dir> [--machine <id>]
+ *     push a run-status document into the hub spool (P7.1). Doc from `--file`
+ *     or stdin. `machine_id` is stamped from `--machine`, else
+ *     `HARNESS_MACHINE_ID`, else the OS hostname — a value in the document is
+ *     overridden.
+ *   project --spool <dir> [--redact] [--stale-after <ms>] [--expire-after <ms>]
+ *     classify the spool into the board overlay (P7.2): live | stale; retired
+ *     runs (terminal outcome or past expiry) are dropped. `--redact` strips
+ *     needs-you reason text (P5.3 rule).
+ *
+ * Exit 0 on success, 2 on a bad document / missing spool.
+ */
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { projectRuns, publishRunStatus, RunStatusError } from "./index.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+export function runstatusCommand(args) {
+    const sub = args[0];
+    if (sub !== "publish" && sub !== "project") {
+        process.stderr.write("harness runstatus <publish [--file <path>] --spool <dir> [--machine <id>] | project --spool <dir> [--redact] [--stale-after <ms>] [--expire-after <ms>]>\n");
+        return 2;
+    }
+    if (sub === "project") {
+        const spool = flag(args, "spool");
+        if (!spool) {
+            process.stderr.write("runstatus project: --spool <dir> is required\n");
+            return 2;
+        }
+        const staleAfterMs = flag(args, "stale-after");
+        const expireAfterMs = flag(args, "expire-after");
+        const overlay = projectRuns(spool, {
+            redact: args.includes("--redact"),
+            ...(staleAfterMs !== undefined ? { staleAfterMs: Number(staleAfterMs) } : {}),
+            ...(expireAfterMs !== undefined ? { expireAfterMs: Number(expireAfterMs) } : {}),
+        });
+        process.stdout.write(JSON.stringify(overlay, null, 2) + "\n");
+        return 0;
+    }
+    const spoolDir = flag(args, "spool");
+    if (!spoolDir) {
+        process.stderr.write("runstatus publish: --spool <dir> is required\n");
+        return 2;
+    }
+    const machineId = flag(args, "machine") ?? process.env.HARNESS_MACHINE_ID ?? safeHostname();
+    const file = flag(args, "file");
+    let text;
+    try {
+        text = file ? readFileSync(file, "utf8") : readFileSync(0, "utf8");
+    }
+    catch (e) {
+        process.stderr.write(`runstatus publish: cannot read document: ${e.message}\n`);
+        return 2;
+    }
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (e) {
+        process.stderr.write(`runstatus publish: document is not JSON: ${e.message}\n`);
+        return 2;
+    }
+    try {
+        const r = publishRunStatus(doc, { spoolDir, machineId });
+        process.stdout.write(`published ${r.key} → ${r.path}\n`);
+        return 0;
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n`);
+        return e instanceof RunStatusError ? 2 : 1;
+    }
+}
+function safeHostname() {
+    try {
+        return hostname() || "local";
+    }
+    catch {
+        return "local";
+    }
+}
+//# sourceMappingURL=cli.js.map