@occasiolabs/occasio 0.8.1

package/src/anomaly/index.js

@@ -0,0 +1,169 @@
+'use strict';
+
+/**
+ * anomaly/index.js — runtime anomaly detection over the tamper-evident audit
+ * chain (`~/.occasio/pipeline-events.jsonl`).
+ *
+ * Complements src/baseline.js (which does per-project, novelty-based detection
+ * over the session log) with **time-windowed rate detectors over the chain**.
+ * Where baseline.js answers "did this session do something it never did",
+ * this module answers "did the last 15 minutes look anomalous compared to the
+ * preceding history".
+ *
+ * Architecture
+ *   loadChainRows(file)               read + parse rows once
+ *   splitByWindow(rows, ms, now)      split into windowRows vs historical
+ *   runDetectors(...)                 invoke every detector, collect alerts
+ *
+ * Each detector is a small module exporting:
+ *   {
+ *     id:            'deny-rate' | ...,
+ *     label:         'Human-readable name',
+ *     evaluate(windowRows, historicalRows, opts) → Alert[]
+ *   }
+ *
+ * Alert shape (stable contract for CLI + chain-persist + tests)
+ *   {
+ *     detector_id, severity: 'low'|'medium'|'high',
+ *     observed, baseline, message,
+ *     rows_implicated: string[]  // first ≤5 row hashes that triggered
+ *   }
+ *
+ * Runner result shape:
+ *   {
+ *     alerts:  Alert[]   anomalies the detectors observed in the window
+ *     errors:  Error[]   detectors that threw — bug reports, NOT anomalies
+ *     window_start, window_end, window_rows, history_rows
+ *   }
+ *
+ * Why alerts and errors are separate:
+ *   A crashed detector is a *bug in the detector*, not an *anomaly in the
+ *   chain*. Surfacing detector crashes as low-severity alerts trains
+ *   compliance reviewers to dismiss real anomalies. Separate channels:
+ *   alerts get human attention; errors go to the operator log and CI.
+ *
+ * Read-only by default. Persistence (writing alerts back into the chain as
+ * `kind:"anomaly_alert"` rows) is opt-in via the CLI's --persist flag and
+ * piggybacks the existing JsonlAuditor so alerts inherit the chain's
+ * tamper-evident property.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const DEFAULT_CHAIN = path.join(os.homedir(), '.occasio', 'pipeline-events.jsonl');
+const DEFAULT_WINDOW_MS = 15 * 60 * 1000;   // 15 minutes
+
+// ── Built-in detectors ──────────────────────────────────────────────────────
+// Order is the order alerts appear in CLI output. Keep deterministic.
+function builtinDetectors() {
+  return [
+    require('./detectors/deny-rate'),
+    require('./detectors/file-read-volume'),
+    require('./detectors/unknown-tool-input'),
+    require('./detectors/secret-redact-rate'),
+  ];
+}
+
+// ── Chain row loader ─────────────────────────────────────────────────────────
+
+function loadChainRows(filePath) {
+  let text;
+  try { text = fs.readFileSync(filePath, 'utf8'); }
+  catch { return []; }
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try {
+      const row = JSON.parse(line);
+      if (row && row.ts) out.push(row);
+    } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
+// ── Window split ─────────────────────────────────────────────────────────────
+// Split rows into { window, historical }: window contains rows whose ts is
+// within [now - windowMs, now]; historical contains everything strictly
+// before that. We use rows[i].ts (ISO 8601) — parse failures fall through to
+// historical (treat as old).
+function splitByWindow(rows, windowMs, now) {
+  const nowMs   = typeof now === 'number' ? now : (now ? new Date(now).getTime() : Date.now());
+  const cutoff  = nowMs - windowMs;
+  const window     = [];
+  const historical = [];
+  for (const r of rows) {
+    const t = Date.parse(r.ts);
+    if (!Number.isFinite(t)) { historical.push(r); continue; }
+    if (t >= cutoff && t <= nowMs) window.push(r);
+    else if (t < cutoff)            historical.push(r);
+    // rows in the future (t > nowMs) are skipped — they're either clock skew
+    // or rows we shouldn't be evaluating yet
+  }
+  return { window, historical, windowStartMs: cutoff, windowEndMs: nowMs };
+}
+
+// ── Runner ───────────────────────────────────────────────────────────────────
+function runDetectors({
+  chainFile = DEFAULT_CHAIN,
+  windowMs  = DEFAULT_WINDOW_MS,
+  now       = null,
+  detectors = null,
+  // For tests: pass rows directly instead of reading from disk.
+  rows      = null,
+} = {}) {
+  const allRows = rows || loadChainRows(chainFile);
+  const split   = splitByWindow(allRows, windowMs, now);
+  const list    = detectors || builtinDetectors();
+
+  const alerts = [];
+  const errors = [];
+  for (const d of list) {
+    try {
+      const out = d.evaluate(split.window, split.historical, {
+        windowMs, windowStartMs: split.windowStartMs, windowEndMs: split.windowEndMs,
+      });
+      if (!Array.isArray(out)) continue;
+      for (const a of out) {
+        if (!a) continue;
+        alerts.push({
+          detector_id:   d.id,
+          severity:      a.severity || 'medium',
+          observed:      a.observed,
+          baseline:      a.baseline,
+          message:       a.message || `${d.label}: anomaly detected`,
+          rows_implicated: (a.rows_implicated || []).slice(0, 5),
+        });
+      }
+    } catch (e) {
+      // A crashed detector is a bug, not an anomaly. Surface it on the
+      // errors channel so operators / CI see it without contaminating
+      // the alerts stream that compliance reviews.
+      errors.push({
+        detector_id: d.id,
+        label:       d.label,
+        error:       e.message || String(e),
+        stack:       e.stack || null,
+      });
+    }
+  }
+
+  return {
+    alerts,
+    errors,
+    window_start: new Date(split.windowStartMs).toISOString(),
+    window_end:   new Date(split.windowEndMs).toISOString(),
+    window_rows:  split.window.length,
+    history_rows: split.historical.length,
+  };
+}
+
+module.exports = {
+  runDetectors,
+  loadChainRows,
+  splitByWindow,
+  builtinDetectors,
+  DEFAULT_CHAIN,
+  DEFAULT_WINDOW_MS,
+};

package/src/attest/canonicalize.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * canonicalize.js — deterministic JSON serialisation for predicate/payload
+ * byte-equivalence comparisons.
+ *
+ * This is a pragmatic subset of RFC 8785 (JSON Canonicalization Scheme):
+ *   - object keys sorted lexicographically (UTF-16 code units; equivalent to
+ *     default Array.prototype.sort on strings)
+ *   - keys whose value is `undefined` are omitted (matches JSON.stringify)
+ *   - arrays preserve order; `undefined` elements become `null`
+ *   - numbers must be integers (see below); JSON.stringify form is used
+ *   - strings use V8's JSON.stringify escaping
+ *   - rejects: undefined at top level, non-finite numbers, NON-INTEGER
+ *     numbers (see below), functions, symbols
+ *
+ * Why non-integer numbers are rejected (enforced cross-language invariant)
+ *   JavaScript has a single `number` type. JSON.parse('1.0') yields the
+ *   integer 1; JSON.stringify(1) emits '1'. Python distinguishes int from
+ *   float: json.loads('1.0') yields float(1.0); json.dumps(1.0) emits
+ *   '1.0'. If we silently accepted floats, the JS verifier and the Python
+ *   verifier would canonicalize the same JSON file to different bytes —
+ *   silent byte-equivalence breakage and the schema is no longer language-
+ *   independent. We reject non-integer numbers explicitly on both sides,
+ *   matching error messages, so the failure mode is loud and identical.
+ *
+ *   Integer-valued floats (1.0 parsed by Python as float(1.0)) ARE
+ *   accepted: both implementations coerce to the integer representation
+ *   so a round-trip through either side produces the same canonical bytes.
+ *
+ *   If a future schema requires decimal precision (it should not — counts
+ *   and timestamps don't need it), encode as a string ("1.5") and parse
+ *   numerically in the consumer. The canonicalize boundary stays integer-
+ *   only.
+ *
+ * Where this deviates from strict RFC 8785:
+ *   - Float serialisation: RFC 8785 mandates a specific ECMAScript form
+ *     for non-integer floats. We sidestep this entirely by rejecting them
+ *     above. The deviation is intentional and load-bearing for cross-
+ *     language byte-equivalence; remove it only when adopting a vetted JCS
+ *     library that handles ECMAScript Number.prototype.toString exactly.
+ *   - Lone surrogate handling: JSON.stringify produces \uXXXX escapes which
+ *     are valid RFC 8259. JCS specifies the same. Identical in practice.
+ *
+ * Why a tiny in-tree implementation instead of a dependency:
+ *   - Must run unchanged in three places: Node (sign/verify), GitHub Action
+ *     (no extra npm install before this runs), and the browser viewer
+ *     (no build step). A copy-paste-ready ~30 lines is the cheapest path
+ *     to "same bytes everywhere".
+ *
+ * IMPORTANT: keep this function logically identical to the inline copy in
+ * integrations/attest-view/viewer.js. Any change here must be mirrored there.
+ */
+
+function canonicalize(value) {
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'boolean':
+      return value ? 'true' : 'false';
+    case 'number':
+      if (!Number.isFinite(value)) {
+        throw new Error('canonicalize: non-finite number');
+      }
+      if (!Number.isInteger(value)) {
+        // See the header comment "Why non-integer numbers are rejected".
+        // If you hit this, encode the field as a string in the schema
+        // instead of changing this guard.
+        throw new Error(
+          'canonicalize: non-integer number ' + value +
+          ' — cross-language byte-equivalence requires schema fields be ' +
+          'integers or strings. Encode decimal values as strings.'
+        );
+      }
+      return JSON.stringify(value);
+    case 'string':
+      return JSON.stringify(value);
+    case 'object': {
+      if (Array.isArray(value)) {
+        return '[' + value.map(v =>
+          canonicalize(v === undefined ? null : v)
+        ).join(',') + ']';
+      }
+      const keys = Object.keys(value)
+        .filter(k => value[k] !== undefined)
+        .sort();
+      return '{' + keys.map(k =>
+        JSON.stringify(k) + ':' + canonicalize(value[k])
+      ).join(',') + '}';
+    }
+    case 'undefined':
+      throw new Error('canonicalize: undefined at top level');
+    default:
+      throw new Error('canonicalize: unsupported type ' + typeof value);
+  }
+}
+
+module.exports = { canonicalize };

package/src/attest/index.js

@@ -0,0 +1,355 @@
+'use strict';
+
+/**
+ * occasio attest — produce an AI-Agent Behavioral Attestation (v1) for a
+ * single Occasio session (run_id). The output is a self-contained JSON file
+ * that *commits* (via first_hash/last_hash) to a contiguous slice of the
+ * tamper-evident audit chain and summarises what happened during the run.
+ *
+ * Phase 0: unsigned attestations (`signature: null`). Phase 1 will wrap this
+ * object in an in-toto Statement envelope and Sigstore-sign it.
+ *
+ * Usage:
+ *   occasio attest --run-id <uuid> [--out <path>] [--log <path>]
+ *                     [--policy <path>] [--stdout]
+ *
+ * Reads (all read-only — never mutates the chain):
+ *   ~/.occasio/pipeline-events.jsonl   (or --log)
+ *   ~/.occasio/policy.yml              (or --policy)
+ *
+ * Writes:
+ *   ./attestation.json                    (or --out, or stdout with --stdout)
+ *
+ * Exit codes:
+ *   0 — success
+ *   1 — no events found for the given run_id (user error)
+ *   2 — invalid arguments / I/O error
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const { loadRunSlice } = require('./run-slice');
+const { computePolicyHash } = require('../policy/loader');
+
+const SCHEMA_VERSION = '1.0.0';
+const PREDICATE_TYPE =
+  'https://github.com/occasiolabs/occasio/spec/agent-attestation/v1';
+const GENESIS = '0'.repeat(64);
+const VERIFIER_URL =
+  'https://github.com/occasiolabs/occasio/blob/main/docs/audit_walker.py';
+
+const DEFAULT_LOG    = path.join(os.homedir(), '.occasio', 'pipeline-events.jsonl');
+const DEFAULT_POLICY = path.join(os.homedir(), '.occasio', 'policy.yml');
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function isoSeconds(a, b) {
+  const ai = new Date(a).getTime();
+  const bi = new Date(b).getTime();
+  if (!Number.isFinite(ai) || !Number.isFinite(bi)) return 0;
+  return Math.max(0, Math.round((bi - ai) / 1000));
+}
+
+function offsetSeconds(start, then) {
+  const ai = new Date(start).getTime();
+  const bi = new Date(then).getTime();
+  if (!Number.isFinite(ai) || !Number.isFinite(bi)) return 0;
+  return Math.max(0, Math.round((bi - ai) / 1000));
+}
+
+// Best-effort rules digest from a parsed policy.yml. We deliberately do NOT
+// require ../policy/loader.load() (which mutates module-level cache + fires
+// change listeners) — `attest` is a pure read.
+function readPolicyRulesDigest(policyFile) {
+  let text;
+  try { text = fs.readFileSync(policyFile, 'utf8'); }
+  catch { return null; }
+
+  // Tiny line-level scan — full parsing is overkill for a digest. Counts only.
+  let denyPaths = 0, denyPatterns = 0, blockSecrets = null;
+  let inDenyPaths = false, inDenyPatterns = false;
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/#.*$/, '');     // strip comments
+    if (/^\s*deny_paths\s*:/.test(line))   { inDenyPaths = true; inDenyPatterns = false; continue; }
+    if (/^\s*allow_paths\s*:/.test(line))  { inDenyPaths = false; inDenyPatterns = false; continue; }
+    if (/^\s*deny_patterns\s*:/.test(line)){ inDenyPatterns = true; inDenyPaths = false; continue; }
+    if (/^\s*tools\s*:/.test(line))        { inDenyPaths = false; inDenyPatterns = false; continue; }
+
+    if (/^\s*block_secrets_in_tool_results\s*:\s*(true|false)\b/.test(line)) {
+      blockSecrets = /true/.test(line);
+    }
+
+    if (inDenyPaths && /^\s*-\s+\S/.test(line))    denyPaths++;
+    if (inDenyPatterns && /^\s{2,}\S+\s*:/.test(line)) denyPatterns++;
+  }
+  return {
+    deny_paths_count:    denyPaths,
+    deny_patterns_count: denyPatterns,
+    block_secrets:       blockSecrets === null ? true : blockSecrets,  // schema default
+  };
+}
+
+// Extract platform + model from the slice. Most rows don't carry model directly;
+// model is best-effort sourced from the first row that has one.
+function pickAgentMeta(events) {
+  let platform = null, model = null, session_id = null;
+  for (const e of events) {
+    if (!platform && typeof e.agent === 'string' && e.agent !== 'occasio') platform = e.agent;
+    if (!model && typeof e.model === 'string') model = e.model;
+    if (!session_id && typeof e.session_id === 'string') session_id = e.session_id;
+    if (platform && model && session_id) break;
+  }
+  return {
+    platform:   platform || 'claude-code',   // adapter default
+    model:      model || null,
+    session_id: session_id || null,
+  };
+}
+
+function summariseExecution(events, startedAt) {
+  const summary = {
+    tool_calls: 0, local: 0, passed: 0, blocked: 0,
+    transformed: 0, secrets_redacted: 0,
+    blocked_events: [],
+  };
+  for (const e of events) {
+    if (e.kind !== 'tool_call') continue;
+    summary.tool_calls++;
+    switch (e.action) {
+      case 'LOCAL':     summary.local++; break;
+      case 'PASS':      summary.passed++; break;
+      case 'BLOCK':     summary.blocked++; break;
+      case 'TRANSFORM': summary.transformed++; break;
+    }
+    if (typeof e.secrets_redacted === 'number' && e.secrets_redacted > 0) {
+      summary.secrets_redacted += e.secrets_redacted;
+    }
+    if (e.action === 'BLOCK') {
+      const target = (e.tool_inputs && (e.tool_inputs.path || e.tool_inputs.pattern)) || null;
+      summary.blocked_events.push({
+        tool:        e.tool_name || 'unknown',
+        target,
+        rule:        e.reason || 'unknown',
+        at_offset_s: offsetSeconds(startedAt, e.ts || e.iso),
+      });
+    }
+  }
+  return summary;
+}
+
+// ── public API ───────────────────────────────────────────────────────────────
+
+/**
+ * buildAttestation({ runId, logFile, policyFile, gitCommit, filesChanged })
+ *   → attestation object.
+ *
+ * `gitCommit` / `filesChanged` are optional v1.1 subject extensions —
+ * populated by the GitHub Action (Phase 2) to bind a run to a specific
+ * commit. Schema already permits both (declared in v1).
+ *
+ * Throws if runId is missing. Returns null if no events match the run_id.
+ */
+function buildAttestation({ runId, logFile, policyFile, gitCommit, filesChanged } = {}) {
+  if (!runId || typeof runId !== 'string') {
+    throw new Error('buildAttestation: runId is required');
+  }
+  const log = logFile  || DEFAULT_LOG;
+  const pol = policyFile || DEFAULT_POLICY;
+
+  const slice = loadRunSlice(log, runId);
+  if (slice.event_count === 0) return null;
+
+  // Look for a policy_loaded row inside the slice — it tells us exactly which
+  // policy hash was active during the run. Fall back to the file's current
+  // hash if no such row exists.
+  let polHash = null, polPath = null, polSource = 'unknown', polVersion = null;
+  for (const e of slice.events) {
+    if (e.kind === 'policy_loaded' && e.tool_inputs) {
+      polHash    = e.tool_inputs.policy_hash || polHash;
+      polPath    = e.tool_inputs.policy_path || polPath;
+      polVersion = (typeof e.tool_inputs.version === 'number') ? e.tool_inputs.version : polVersion;
+      polSource  = e.policy_source || (polPath ? 'user' : 'default');
+      break;
+    }
+  }
+  if (!polHash) {
+    // No policy_loaded row inside this run slice — we cannot prove which
+    // policy was active during the run. Mark the source as 'inferred' so a
+    // downstream verifier knows the hash came from the file's *current*
+    // bytes (which may have been edited after the run ended).
+    polHash   = computePolicyHash(pol);
+    polPath   = pol;
+    polSource = 'inferred';
+  }
+
+  const agent = pickAgentMeta(slice.events);
+  const first = slice.events[0];
+  const last  = slice.events[slice.events.length - 1];
+  const startedAt = first.ts || first.iso || new Date().toISOString();
+  const endedAt   = last.ts  || last.iso  || startedAt;
+
+  return {
+    schema_version: SCHEMA_VERSION,
+    predicate_type: PREDICATE_TYPE,
+    subject: Object.assign(
+      { run_id: runId },
+      (gitCommit && typeof gitCommit === 'string') ? { git_commit: gitCommit } : {},
+      (Array.isArray(filesChanged) && filesChanged.length) ? { files_changed: filesChanged.slice() } : {}
+    ),
+    agent: {
+      platform:    agent.platform,
+      model:       agent.model,
+      session_id:  agent.session_id,
+      started_at:  startedAt,
+      ended_at:    endedAt,
+      wall_time_s: isoSeconds(startedAt, endedAt),
+    },
+    policy: {
+      file_hash:    polHash,
+      file_path:    polPath,
+      source:       polSource,
+      version:      polVersion,
+      rules_digest: readPolicyRulesDigest(pol) || {
+        deny_paths_count: 0, deny_patterns_count: 0, block_secrets: true,
+      },
+    },
+    execution_summary: summariseExecution(slice.events, startedAt),
+    audit_chain: {
+      genesis:      GENESIS,
+      first_hash:   slice.first_hash,
+      last_hash:    slice.last_hash,
+      event_count:  slice.event_count,
+      chain_file:   log,
+      verifier_url: VERIFIER_URL,
+    },
+    signature:    null,
+    generated_at: new Date().toISOString(),
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+function flag(args, name) {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+function bool(args, name) { return args.indexOf(name) >= 0; }
+
+function runAttestCli(args) {
+  args = args || [];
+
+  // Subcommand: `occasio attest verify <file>` → delegate.
+  if (args[0] === 'verify') {
+    const { runAttestVerifyCli } = require('./verify');
+    return runAttestVerifyCli(args.slice(1)).catch(e => {
+      process.stderr.write(`[Occasio] attest verify: ${e.message}\n`);
+      process.exit(2);
+    });
+  }
+
+  if (bool(args, '--help') || bool(args, '-h')) {
+    process.stdout.write(
+      'Usage:\n' +
+      '  occasio attest --run-id <uuid> [--out <path>] [--log <path>] [--policy <path>] [--stdout]\n' +
+      '                    [--sign] [--sign-mode ci|token] [--oidc-token <jwt>] [--bundle-out <path>]\n' +
+      '                    [--git-commit <sha>] [--files-changed <a,b,c>]\n' +
+      '  occasio attest verify <attestation.json> [--bundle <path>]\n'
+    );
+    return;
+  }
+
+  const runId  = flag(args, '--run-id');
+  if (!runId) {
+    process.stderr.write('[Occasio] attest: --run-id <uuid> is required\n');
+    process.exit(2);
+  }
+  const logFile    = flag(args, '--log')    || DEFAULT_LOG;
+  const policyFile = flag(args, '--policy') || DEFAULT_POLICY;
+  const out        = flag(args, '--out')    || path.resolve(process.cwd(), 'attestation.json');
+  const toStdout   = bool(args, '--stdout');
+  const sign       = bool(args, '--sign');
+  const signMode   = flag(args, '--sign-mode');     // 'ci' | 'token' | undefined
+  const oidcToken  = flag(args, '--oidc-token');    // explicit JWT (token-mode)
+  const bundleOut  = flag(args, '--bundle-out')
+                     || out.replace(/\.json$/i, '') + '.sigstore.json';
+  const gitCommit  = flag(args, '--git-commit');
+  const filesRaw   = flag(args, '--files-changed');
+  const filesChanged = filesRaw
+    ? filesRaw.split(',').map(s => s.trim()).filter(Boolean)
+    : undefined;
+
+  let attestation;
+  try {
+    attestation = buildAttestation({ runId, logFile, policyFile, gitCommit, filesChanged });
+  } catch (e) {
+    process.stderr.write(`[Occasio] attest: ${e.message}\n`);
+    process.exit(2);
+  }
+  if (!attestation) {
+    process.stderr.write(`[Occasio] attest: no events found for run_id ${runId}\n`);
+    process.stderr.write(`  Checked: ${logFile}\n`);
+    process.exit(1);
+  }
+
+  if (!sign) {
+    emitUnsigned(attestation, out, toStdout, runId);
+    return;
+  }
+
+  // Signing path — async. Lazy-require sign.js to keep cold-start cheap.
+  const { signAttestation } = require('./sign');
+  return signAttestation(attestation, { oidcToken, signMode })
+    .then(({ bundle, signatureBlock }) => {
+      attestation.signature = signatureBlock;
+      const json = JSON.stringify(attestation, null, 2);
+      if (toStdout) {
+        process.stdout.write(json + '\n');
+        return;
+      }
+      fs.writeFileSync(out,       json + '\n', 'utf8');
+      fs.writeFileSync(bundleOut, JSON.stringify(bundle, null, 2) + '\n', 'utf8');
+      process.stdout.write(`✓ Wrote signed attestation: ${out}\n`);
+      process.stdout.write(`  bundle:    ${bundleOut}\n`);
+      process.stdout.write(
+        `  run_id: ${runId}  ·  events: ${attestation.audit_chain.event_count}` +
+        `  ·  blocked: ${attestation.execution_summary.blocked}` +
+        `  ·  secrets_redacted: ${attestation.execution_summary.secrets_redacted}\n`
+      );
+      process.stdout.write(`  identity:  ${signatureBlock.identity}\n`);
+      if (signatureBlock.rekor_entry) process.stdout.write(`  rekor:     ${signatureBlock.rekor_entry}\n`);
+    })
+    .catch(e => {
+      process.stderr.write(`[Occasio] attest: signing failed: ${e.message}\n`);
+      process.exit(2);
+    });
+}
+
+function emitUnsigned(attestation, out, toStdout, runId) {
+  const json = JSON.stringify(attestation, null, 2);
+  if (toStdout) { process.stdout.write(json + '\n'); return; }
+  try {
+    fs.writeFileSync(out, json + '\n', 'utf8');
+    process.stdout.write(`✓ Wrote attestation: ${out}\n`);
+    process.stdout.write(
+      `  run_id: ${runId}  ·  events: ${attestation.audit_chain.event_count}` +
+      `  ·  blocked: ${attestation.execution_summary.blocked}` +
+      `  ·  secrets_redacted: ${attestation.execution_summary.secrets_redacted}\n`
+    );
+    process.stdout.write('  signature: null  ·  use --sign to Sigstore-sign\n');
+  } catch (e) {
+    process.stderr.write(`[Occasio] attest: cannot write ${out}: ${e.message}\n`);
+    process.exit(2);
+  }
+}
+
+module.exports = {
+  buildAttestation,
+  runAttestCli,
+  SCHEMA_VERSION,
+  PREDICATE_TYPE,
+  GENESIS,
+  // exported for tests
+  _readPolicyRulesDigest: readPolicyRulesDigest,
+};

package/src/attest/run-slice.js

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * run-slice.js — load a tamper-evident audit chain and return the slice of rows
+ * belonging to a single run_id, preserving the original on-disk order.
+ *
+ * Returns:
+ *   {
+ *     events:       [row, …]   // sorted by file order (which is chain order)
+ *     event_count:  integer    // events.length
+ *     first_hash:   string|null  // hash field of the first row in the slice
+ *     last_hash:    string|null  // hash field of the last row in the slice
+ *   }
+ *
+ * Why we don't sort by ISO timestamp here (unlike replay.groupByRun): the
+ * chain's hash linkage is the canonical order. If two rows share an iso
+ * second, the on-disk order is the only correct sequence — any other sort
+ * would produce a `first_hash`/`last_hash` pair that does not correspond
+ * to a contiguous block of `prev_hash → hash` links.
+ *
+ * Legacy rows (no `hash` field — pre-hash-chain) are included if their
+ * `run_id` matches, but their `hash` will be undefined, so `first_hash`/
+ * `last_hash` may be null. Callers that need cryptographic commitments
+ * should check `first_hash !== null` and gate accordingly.
+ */
+
+const fs = require('fs');
+
+function readJsonlFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map(line => { try { return JSON.parse(line); } catch { return null; } })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function loadRunSlice(logFile, runId) {
+  if (!runId || typeof runId !== 'string') {
+    return { events: [], event_count: 0, first_hash: null, last_hash: null };
+  }
+  const all = readJsonlFile(logFile);
+  const events = all.filter(e => e && e.run_id === runId);
+  const first = events[0];
+  const last  = events[events.length - 1];
+  return {
+    events,
+    event_count: events.length,
+    first_hash:  (first && typeof first.hash === 'string') ? first.hash : null,
+    last_hash:   (last  && typeof last.hash  === 'string') ? last.hash  : null,
+  };
+}
+
+module.exports = { loadRunSlice, readJsonlFile };