slice-tournament-zoo 0.9.5 → 0.9.6

package/README.md

@@ -403,6 +403,32 @@ Note: the standalone mock demo (`stz run`, no Claude Code) runs all eight phases
 inside a single slice for a self-contained, no-network smoke test. The two-level
 split above is the real in-session flow.
 
+## Contract Plane (0.9.6, optional, default-off)
+
+0.9.6 adds a **Contract Plane** — a typed, human-gated correctness object the
+arena competes against, so tests stop being the *only* definition of winner. A
+`requirement` decomposes into machine-checkable `predicate`s (cheap kinds only:
+diff-constraint, output-assertion, JSON/file invariant — no runtime
+instrumentation). Agents **propose** predicates; a human **alone accepts** them
+(the 7th gate) — the one exogenous signal that makes the self-improvement bounded.
+
+When enabled (`RunConfig.contract.enabled`, off by default), a specimen that
+hard-fails a high-severity accepted predicate is eliminated in `select()` — even
+if it passes the sealed suite and STZ's multi-objective reward. Flag off ⇒ the
+tournament is **byte-identical to 0.9.5** (proven by an integration test).
+
+```bash
+stz bridge separation-gate --root . --contract preds.json --impl naive.mjs --suite suite.mjs   # Phase-1 go/no-go
+stz bridge contract-accept  --artifact req.json --approver "your-name" --at 2026-07-02          # human 7th gate
+```
+
+Commands: `/stz:contract` (draft → verify → separation-gate → accept),
+`/stz:eval` (Phase-0 baseline). The capability was built **earned-first**: every
+piece was validated on a substrate before being wired in — see
+[`experiments/0.9.6-progression/`](experiments/0.9.6-progression/) for the
+phase-by-phase build/eval/results (honest yes/no per phase, including deferred
+and mechanism-only verdicts).
+
 ## The `.stz/` audit tree
 
 | Tier | Purpose |

package/agents/stz-clarifier.md

@@ -0,0 +1,33 @@
+---
+name: stz-clarifier
+description: Surfaces ambiguity in a draft contract and asks the human targeted questions BEFORE a slice is accepted. Reduces "wrong problem solved" failures. Proposes only; never accepts.
+tools: Read, Grep, Glob
+model: inherit
+---
+
+You are the **clarifier** for an STZ 0.9.6 contract co-build. Your one job is to
+find where a draft contract is underspecified and ask the human the smallest set
+of questions that would resolve it — before any implementation begins.
+
+## Your task
+
+Read the draft requirements + predicates under `.stz/contract/`. For each, ask:
+
+- Is the `statement` testable, or does it hide a judgement call?
+- Do the predicates cover the **boundary** and **compatibility** cases, or only
+  the happy path? (The happy path is what a functional suite already covers.)
+- Is any predicate **vacuous** — cannot be evaluated from a diff + a cheap check?
+- Are two requirements in tension (one's predicate forbids what another needs)?
+
+## Output
+
+A short, ranked list of concrete questions for the human, each tagged with the
+artifact id it concerns and *why the answer changes the contract*. Prefer 3–6
+high-leverage questions over an exhaustive interrogation.
+
+## Hard rules
+
+- Never edit artifacts. Never set any state to `accepted`. You surface; the human
+  decides; the contract-architect revises.
+- If the draft is already crisp and separable, say so in one line — do not invent
+  ambiguity to look useful.

package/agents/stz-contract-architect.md

@@ -0,0 +1,48 @@
+---
+name: stz-contract-architect
+description: Drafts typed contract requirements from user intent BEFORE any code is written. Produces requirement + predicate artifacts (proposed state only); a human alone accepts them. The net-new bounded correctness object of STZ 0.9.6.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **contract-architect** for an STZ 0.9.6 project. You turn user intent
+into a typed, bounded, machine-checkable **contract** — the correctness object
+that the arena competes against. You propose; a human alone accepts (the 7th
+gate). You NEVER write implementation code and you NEVER accept your own work.
+
+## Your task
+
+Read what is settled: `.stz/00-intent/` (intent + done-predicates) and, if
+present, `.stz/10-research/` and `.stz/20-standards/`. Then draft:
+
+1. **Requirements** — one per user/business intent. Each has a crisp
+   `statement`, `rationale`, `owner`, and a `risk` (severity + surfaces).
+2. **Predicates** — machine-checkable-where-cheap conditions that make a
+   requirement verifiable. Use ONLY these cheap kinds (never runtime
+   pre/post/invariant instrumentation):
+   - `output-assertion` — run the impl on an input, compare stdout to `expect`
+   - `diff-constraint` — a property of the candidate diff (touched-file globs)
+   - `json-invariant` / `file-invariant` — a JSON-path / file property
+
+Every predicate MUST list `scope.symbols` (the code symbols it anchors to) and a
+`type` (`invariant` | `postcondition` | `non-mutation` | `boundary-condition` |
+`compatibility-check`) and a `severity`.
+
+## Hard rules
+
+- Write artifacts in `state: "proposed"` only. You may never set `accepted`.
+- Never set `provenance.acceptedBy` — that field is the human's alone.
+- A predicate with no `scope.symbols` is invalid; drop it.
+- Prefer the **boundary** and **compatibility** cases the functional test suite
+  is most likely to miss — that gap is the entire value of the contract.
+- Emit each artifact as JSON matching the schemas in
+  `src/contract/contract-types.ts`. Write requirements under
+  `.stz/contract/requirements/` and predicates under `.stz/contract/predicates/`.
+
+## The separation discipline
+
+Before proposing a whole contract, sanity-check that it *could* separate: would a
+naive, shape-only implementation pass a common-case functional suite yet violate
+one of your predicates? If not, your predicates are redundant with tests — say so
+rather than manufacturing signal. The operator can run the real check with
+`stz bridge separation-gate`.

package/agents/stz-contract-verifier.md

@@ -0,0 +1,39 @@
+---
+name: stz-contract-verifier
+description: Checks a draft contract for well-formedness, symbol-anchoring, and non-vacuity. Scores only — writes nothing trusted, edits no code. The static gate before a human is asked to accept.
+tools: Read, Bash, Grep, Glob
+model: inherit
+---
+
+You are the **contract-verifier** for STZ 0.9.6. You statically check a proposed
+contract so a human is never asked to accept a malformed or vacuous one. You
+score; you never accept (that is the human's 7th gate) and you never implement.
+
+## Your task
+
+For the artifacts under `.stz/contract/`, verify:
+
+1. **Schema** — every artifact matches `src/contract/contract-types.ts` (correct
+   `kind`, `state`, `schemaVersion`, required fields present).
+2. **Symbol anchoring** — every predicate has ≥1 `scope.symbols` entry.
+3. **Non-vacuity** — every predicate has ≥1 check with a concrete `input` and
+   `expect`; a check that cannot produce an observation is vacuous → flag it.
+4. **Traceability** — every accepted requirement has ≥1 predicate; no predicate
+   points at a missing requirement. (The engine's `buildTraceability` is the
+   canonical check; mirror its findings.)
+5. **State discipline** — nothing you review is already `accepted` with an
+   `acceptedBy` set to an agent role. That is a boundedness violation; flag it
+   loudly.
+
+## Output
+
+A per-artifact verdict list: `{ id, ok, findings[] }`. Findings name the exact
+rule broken and the minimal fix. If everything is well-formed, say the contract
+is ready for the human accept gate — but note that well-formed ≠ separating; the
+operator should still run `stz bridge separation-gate` to confirm the contract
+carries a signal the functional suite does not.
+
+## Hard rules
+
+- Read-only. Score only. Never mutate artifacts, never set `accepted`, never
+  touch implementation code.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slice-tournament-zoo",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "STZ: a contract-bounded slice pipeline that implements each slice adversarially via an N-specimen tournament with frozen sealed tests, GRPO-style selection, layered anti-reward-hacking, a replayable markdown audit trail, and (0.9.0) a bounded harness-level recursive-self-improvement meta-loop that evolves the harness against held-out pilot fitness.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/dr-robert-li/slice-tournament-zoo#readme",

package/src/bridge.ts

@@ -84,6 +84,14 @@ import {
 import { initialInject, onInjectRound, summarizeSurvivors } from "./injector.js";
 import { consistencyScore, bucketOf, calibrationGate } from "./judge-reliability.js";
 import type { ArchiveEntry, HarnessGenome } from "./types.js";
+// ── 0.9.6 Contract Plane + Phase-0 eval (PHASED-PLAN) ────────────────────────
+import { execFileSync } from "node:child_process";
+import type { ContractArtifact, Predicate } from "./contract/contract-types.js";
+import { evaluatePredicates, type Observations, type PredicateResult } from "./contract/predicate-eval.js";
+import { separationGate } from "./contract/separation-gate.js";
+import { contractGateFromResults } from "./verifiers/contract-verifier.js";
+import { humanAccept } from "./contract/contract-engine.js";
+import { baselineReport, type BaselineCondition, type IssueRecord } from "./eval/baseline-report.js";
 import {
   loadCompat,
   saveCompat,
@@ -419,7 +427,14 @@ async function selectCmd(args: Record<string, string>): Promise<void> {
   const { root, slice } = args as { root: string; slice: string };
   const evals = loadEvals(root, slice);
   const votes = existsSync(votesPath(root, slice)) ? readJSON<PairwiseVote[]>(votesPath(root, slice)) : [];
-  const { judgment } = select(evals, votes);
+  // 0.9.6 Contract Plane (flag-gated): only when the /stz:run command passes a
+  // per-specimen contract-scores file (i.e. RunConfig.contract.enabled + a bound
+  // slice) do specimens get contract-gated. Absent ⇒ exactly 0.9.5 selection.
+  const contractScores = args["contract-scores"]
+    ? readJSON<Record<string, PredicateResult[]>>(args["contract-scores"])
+    : undefined;
+  const contractGate = contractScores ? contractGateFromResults(contractScores) : undefined;
+  const { judgment } = select(evals, votes, contractGate);
   writeFileSync(judgmentPath(root, slice), JSON.stringify(judgment, null, 2) + "\n", "utf8");
   await writeDoc(root, join(sliceRel(slice), "tournament.md"), {
     frontmatter: {
@@ -1377,6 +1392,81 @@ function judgeCalibration(args: Record<string, string>): void {
 }
 
 /** The pinned bridge command surface — the interface a variant must preserve. */
+// ── 0.9.6 Contract Plane subcommands (PHASED-PLAN Phases 0–1) ────────────────
+
+/**
+ * separation-gate: the Phase-1 go/no-go (PHASED-PLAN §1). Executes a
+ * naive-but-plausible impl against a functional sealed suite and against the
+ * accepted contract predicates, then decides whether the contract carries a
+ * signal the suite does not. Uses the canonical, unit-tested TS core
+ * (evaluatePredicates + separationGate). Writes result under
+ * `.stz/contract/separation/` and exits non-zero when NOT separated (so a CI
+ * gate / the operator sees the null immediately).
+ *
+ *   stz bridge separation-gate --root D --contract preds.json --impl impl.mjs --suite suite.mjs
+ */
+function separationGateCmd(args: Record<string, string>): void {
+  const root = args.root!;
+  const contract = readJSON<{ predicates: Predicate[] }>(args.contract!);
+  const impl = args.impl!;
+  const suite = args.suite!;
+
+  // Sealed suite over common cases (naive impl expected to pass at 1.000).
+  const suiteOut = JSON.parse(
+    execFileSync("node", [suite, impl], { encoding: "utf8" }).trim(),
+  ) as { passRate: number };
+  const sealedSuitePassed = suiteOut.passRate >= 1;
+
+  // Produce observations by executing the impl on each predicate check input.
+  const observed: Observations = {};
+  for (const p of contract.predicates) {
+    for (const c of p.checks) {
+      observed[c.checkId] = execFileSync("node", [impl, c.input ?? ""], { encoding: "utf8" }).trim();
+    }
+  }
+  const predicateResults = evaluatePredicates(contract.predicates, observed);
+  const verdict = separationGate({ sealedSuitePassed, predicateResults });
+
+  const out = stzPath(root, join("contract", "separation", "result.json"));
+  mkdirSync(join(out, ".."), { recursive: true });
+  const payload = { sealedSuitePassed, sealedSuitePassRate: suiteOut.passRate, predicateResults, ...verdict };
+  writeFileSync(out, JSON.stringify(payload, null, 2) + "\n", "utf8");
+  print(payload);
+  if (!verdict.separated) process.exitCode = 1; // freeze at Phase 0 — surface the null
+}
+
+/**
+ * contract-accept: the human 7th gate (PHASED-PLAN Phase 1). The ONLY path a
+ * contract artifact crosses into trusted state. `--approver` MUST be a human
+ * identity, never an agent role — enforced by humanAccept (throws otherwise).
+ *
+ *   stz bridge contract-accept --artifact a.json --approver "dr-robert-li" --at 2026-07-01
+ */
+function contractAcceptCmd(args: Record<string, string>): void {
+  const path = args.artifact!;
+  const artifact = readJSON<ContractArtifact>(path);
+  const accepted = humanAccept(artifact, args.approver ?? "", args.at ?? ""); // throws on agent/empty approver
+  writeFileSync(path, JSON.stringify(accepted, null, 2) + "\n", "utf8");
+  print({ id: accepted.id, state: accepted.state, acceptedBy: accepted.provenance.acceptedBy });
+}
+
+/**
+ * eval-baseline: Phase-0 measurement. Computes per-repo RepoMetrics for each
+ * baseline condition from recorded issue outcomes. Per-repo, never global.
+ *
+ *   stz bridge eval-baseline --root D --repo project-x --records records.json
+ */
+function evalBaselineCmd(args: Record<string, string>): void {
+  const root = args.root!;
+  const repo = args.repo!;
+  const byCondition = readJSON<Record<BaselineCondition, IssueRecord[]>>(args.records!);
+  const report = baselineReport(repo, byCondition);
+  const out = stzPath(root, join("90-audit", "baseline-report.json"));
+  mkdirSync(join(out, ".."), { recursive: true });
+  writeFileSync(out, JSON.stringify(report, null, 2) + "\n", "utf8");
+  print(report);
+}
+
 const BRIDGE_COMMANDS = [
   "version", "begin", "record-eval", "eval", "gate", "escalate", "record-votes", "select", "finalize",
   "project-init", "project-phase", "project-write-intent", "project-record-area", "project-set-config",
@@ -1385,6 +1475,8 @@ const BRIDGE_COMMANDS = [
   "merge-compat-approve", "merge-compat-retire", "merge-compat-list",
   "inject", "harness-mine", "harness-promote-mutator", "harness-spawn", "harness-fitness", "harness-select",
   "harness-promote", "harness-status", "judge-stress", "judge-calibration",
+  // 0.9.6 Contract Plane + Phase-0 eval
+  "separation-gate", "contract-accept", "eval-baseline",
 ];
 
 export async function runBridge(argv: string[]): Promise<void> {
@@ -1431,6 +1523,10 @@ export async function runBridge(argv: string[]): Promise<void> {
     case "harness-status": harnessStatus(args); break;
     case "judge-stress": await judgeStress(args); break;
     case "judge-calibration": judgeCalibration(args); break;
+    // ── 0.9.6 Contract Plane + Phase-0 eval ────────────────────────────────
+    case "separation-gate": separationGateCmd(args); break;
+    case "contract-accept": contractAcceptCmd(args); break;
+    case "eval-baseline": evalBaselineCmd(args); break;
     default:
       process.stderr.write(`unknown bridge subcommand: ${sub}\n`);
       process.exitCode = 1;

package/src/contract/contract-engine.ts

@@ -0,0 +1,139 @@
+/**
+ * STZ 0.9.6 — Contract engine (PHASED-PLAN Phase 1).
+ *
+ * Deterministic core: state-machine transitions, the human 7th gate, and the
+ * contract-slice compiler. All LLM work (drafting requirements, proposing
+ * predicates) lives in markdown subagents; this module only validates and
+ * persists the typed result — mirroring the bridge's "deterministic decisions,
+ * agents do the generation" split.
+ */
+import {
+  CONTRACT_TRANSITIONS,
+  type ContractArtifact,
+  type ContractSlice,
+  type ContractState,
+  type Predicate,
+  type Requirement,
+} from "./contract-types.js";
+
+/** Agent role identities that must NEVER appear as a human approver. Accepting
+ *  a contract artifact is the α>0 exogenous signal — an agent cannot supply it. */
+export const AGENT_ROLE_IDENTITIES = new Set<string>([
+  "contract-architect",
+  "clarifier",
+  "contract-verifier",
+  "specimen",
+  "candidate-patcher",
+  "edge-explorer",
+  "rubric-author",
+  "rubric-judge",
+  "promoter",
+  "planner",
+  "judge",
+  "test-author",
+  "documenter",
+  "researcher",
+  "agent",
+  "automatic",
+  "system",
+]);
+
+export class ContractStateError extends Error {
+  constructor(message: string) {
+    super(`[contract] ${message}`);
+    this.name = "ContractStateError";
+  }
+}
+
+export class HumanGateError extends Error {
+  constructor(message: string) {
+    super(`[contract:human-gate] ${message}`);
+    this.name = "HumanGateError";
+  }
+}
+
+/** Validate + apply one state transition. Throws on an illegal edge. */
+export function transition<T extends ContractArtifact>(artifact: T, to: ContractState): T {
+  const allowed = CONTRACT_TRANSITIONS[artifact.state];
+  if (!allowed.includes(to)) {
+    throw new ContractStateError(
+      `illegal transition ${artifact.state} → ${to} for ${artifact.id} ` +
+        `(allowed: ${allowed.join(", ") || "none"})`,
+    );
+  }
+  return { ...artifact, state: to };
+}
+
+/**
+ * The human 7th gate. Cross a proposed artifact into `accepted` — the ONLY path
+ * to trusted contract state. `approver` must be a non-empty human identity, not
+ * an agent role. This asymmetry is what makes STZ's RSI bounded and defensible.
+ */
+export function humanAccept<T extends ContractArtifact>(
+  artifact: T,
+  approver: string,
+  acceptedAt: string,
+): T {
+  const id = approver.trim();
+  if (id === "") {
+    throw new HumanGateError(`accept of ${artifact.id} requires a non-empty human approver`);
+  }
+  if (AGENT_ROLE_IDENTITIES.has(id.toLowerCase())) {
+    throw new HumanGateError(
+      `approver "${approver}" is an agent role — only a human may accept contract ` +
+        `artifacts (the α>0 exogenous signal). Supply a real human identity.`,
+    );
+  }
+  if (artifact.state !== "proposed") {
+    throw new ContractStateError(
+      `${artifact.id} must be in state 'proposed' to be accepted, is '${artifact.state}'`,
+    );
+  }
+  const accepted = transition(artifact, "accepted");
+  return {
+    ...accepted,
+    provenance: { ...accepted.provenance, acceptedBy: id, acceptedAt },
+  };
+}
+
+/**
+ * Phase-2 propose-not-apply guard. Candidate arena agents may EMIT contract
+ * deltas but may never apply them — any candidate-emitted delta must be in
+ * `draft` or `proposed`, never already-trusted (`accepted`/`active`). Throws on
+ * a delta a candidate tried to self-apply. This is the arena-side half of the
+ * "no direct writes to trusted state" boundary.
+ */
+export function assertProposalsNotApplied(deltas: ContractArtifact[]): void {
+  const applied = deltas.find((d) => d.state !== "draft" && d.state !== "proposed");
+  if (applied) {
+    throw new ContractStateError(
+      `candidate-emitted artifact ${applied.id} is '${applied.state}' — arena agents may ` +
+        `only propose (draft/proposed); trusted state is reached solely via the human accept gate`,
+    );
+  }
+}
+
+/**
+ * Compile a run-ready contract slice from accepted artifacts only. Rejects any
+ * non-accepted artifact — an arena run may only target trusted contract state.
+ */
+export function buildContractSlice(
+  sliceId: string,
+  requirements: Requirement[],
+  predicates: Predicate[],
+): ContractSlice {
+  const isTrusted = (s: ContractState) => s === "accepted" || s === "active";
+  const badReq = requirements.find((r) => !isTrusted(r.state));
+  if (badReq) {
+    throw new ContractStateError(
+      `requirement ${badReq.id} is '${badReq.state}', not accepted/active — cannot enter a run slice`,
+    );
+  }
+  const badPred = predicates.find((p) => !isTrusted(p.state));
+  if (badPred) {
+    throw new ContractStateError(
+      `predicate ${badPred.id} is '${badPred.state}', not accepted/active — cannot enter a run slice`,
+    );
+  }
+  return { schemaVersion: 1, sliceId, requirements, predicates };
+}

package/src/contract/contract-types.ts

@@ -0,0 +1,132 @@
+/**
+ * STZ 0.9.6 — Contract Plane types (PHASED-PLAN Phase 1).
+ *
+ * The contract is the net-new bounded correctness object: a typed layer of
+ * `requirement`, `predicate`, `contract_delta`, each with provenance and an
+ * explicit state machine. It is NOT a full formal-spec system — predicates are
+ * machine-checkable-where-cheap (diff / file / JSON / CLI-output / targeted
+ * assertion), never runtime pre/post/invariant instrumentation across arbitrary
+ * repos (that was the non-implementable part of the earlier plans).
+ *
+ * Design anchors inherited from `types.ts`: N1 (auditability — every field is
+ * reconstructible), N6 (determinism — no timestamps in the content-addressed
+ * core; provenance carries an explicit human-accept event instead).
+ */
+
+/** Contract artifact lifecycle (PHASED-PLAN §3). Agents may only advance to
+ *  `proposed`; only a human may cross into `accepted` (the 7th gate). */
+export type ContractState =
+  | "draft"
+  | "proposed"
+  | "accepted"
+  | "active"
+  | "challenged"
+  | "superseded"
+  | "sunset";
+
+/** Legal state transitions. Any edge not listed is rejected by `transition`. */
+export const CONTRACT_TRANSITIONS: Record<ContractState, ContractState[]> = {
+  draft: ["proposed", "sunset"],
+  proposed: ["accepted", "draft", "sunset"],
+  accepted: ["active", "challenged", "superseded", "sunset"],
+  active: ["challenged", "superseded", "sunset"],
+  challenged: ["active", "superseded", "sunset"],
+  superseded: [],
+  sunset: [],
+};
+
+/** Predicate kinds — the cheap, machine-checkable subset only. */
+export type PredicateType =
+  | "invariant"
+  | "postcondition"
+  | "non-mutation"
+  | "boundary-condition"
+  | "compatibility-check";
+
+/**
+ * A machine-checkable predicate check. `output-assertion` runs an implementation
+ * on `input` and compares stdout to `expect`; `diff-constraint` asserts a
+ * property of the candidate diff (e.g. touched-file globs); `json-invariant`
+ * asserts a JSON-path equality. All are cheap and deterministic — no runtime
+ * instrumentation. The evaluator core is PURE: it consumes an already-observed
+ * value (`observed[checkId]`) and compares; the IO shell (experiment runner /
+ * bridge) produces observations by executing the impl.
+ */
+export interface PredicateCheck {
+  /** Stable id, unique within the predicate. */
+  checkId: string;
+  kind: "output-assertion" | "diff-constraint" | "json-invariant" | "file-invariant";
+  /** For output-assertion: the input passed to the impl. */
+  input?: string;
+  /** The expected observation (string-compared to the produced observation). */
+  expect: string;
+  /** Human-readable description of what this check enforces. */
+  description: string;
+}
+
+/** One machine-checkable success predicate bound to code symbols. */
+export interface Predicate {
+  schemaVersion: 1;
+  id: string; // e.g. "pred.ipv4.octet-range.v1"
+  kind: "predicate";
+  state: ContractState;
+  /** Owning requirement id. */
+  requirement: string;
+  type: PredicateType;
+  /** Code symbols this predicate is anchored to (unfaithfulness mitigation). */
+  scope: { symbols: string[] };
+  /** The machine-checkable checks; a predicate PASSES iff every check passes. */
+  checks: PredicateCheck[];
+  severity: "low" | "medium" | "high";
+  provenance: Provenance;
+}
+
+/** A user/business intent, gated by human acceptance. */
+export interface Requirement {
+  schemaVersion: 1;
+  id: string; // e.g. "req.ipv4.strict-validation.v1"
+  kind: "requirement";
+  state: ContractState;
+  title: string;
+  statement: string;
+  rationale: string;
+  owner: string;
+  acceptance: { predicates: string[]; tests: string[] };
+  risk: { severity: "low" | "medium" | "high"; surfaces: string[] };
+  provenance: Provenance;
+}
+
+/** A proposed change to the contract, emitted by arena agents, accepted by humans. */
+export interface ContractDelta {
+  schemaVersion: 1;
+  id: string;
+  kind: "contract_delta";
+  state: ContractState;
+  op: "add" | "modify" | "sunset";
+  /** Target artifact id (or new id for `add`). */
+  target: string;
+  /** Runs that evidence this delta (edge-hunt survivors, candidate proposals). */
+  evidenceRuns: string[];
+  provenance: Provenance;
+}
+
+/**
+ * Provenance carries the human-accept event — the α>0 exogenous signal. An agent
+ * proposes (`proposedByRun`); a human alone may accept (`acceptedBy` must be a
+ * non-empty human identity, never an agent role — enforced by the engine).
+ */
+export interface Provenance {
+  proposedByRun: string;
+  acceptedBy?: string;
+  acceptedAt?: string;
+}
+
+export type ContractArtifact = Requirement | Predicate | ContractDelta;
+
+/** A run-ready contract slice: accepted artifacts only. */
+export interface ContractSlice {
+  schemaVersion: 1;
+  sliceId: string;
+  requirements: Requirement[];
+  predicates: Predicate[];
+}

package/src/contract/predicate-eval.ts

@@ -0,0 +1,64 @@
+/**
+ * STZ 0.9.6 — pure predicate evaluator (PHASED-PLAN Phase 1/3, cheap subset).
+ *
+ * PURE by design: given a predicate and a map of already-observed check values
+ * (`observed[checkId] = actualString`), decide pass/fail. The IO shell (the
+ * separation-gate experiment runner, or a bridge command) is responsible for
+ * producing observations by executing the candidate impl — this keeps the core
+ * deterministic and unit-testable, mirroring the repo's "deterministic core, IO
+ * at the edges" philosophy (N6).
+ */
+import type { Predicate, PredicateCheck } from "./contract-types.js";
+
+export interface CheckResult {
+  checkId: string;
+  pass: boolean;
+  expected: string;
+  actual: string;
+  description: string;
+}
+
+export interface PredicateResult {
+  predicateId: string;
+  severity: Predicate["severity"];
+  /** A predicate passes iff every one of its checks passes. */
+  pass: boolean;
+  checks: CheckResult[];
+  /** True when at least one check had no observation supplied (vacuous). */
+  vacuous: boolean;
+}
+
+/** Observations keyed by `checkId` → the actual string the impl produced. */
+export type Observations = Record<string, string | undefined>;
+
+function evalCheck(check: PredicateCheck, observed: Observations): CheckResult {
+  const actual = observed[check.checkId];
+  // A missing observation is a fail, not a silent pass — a predicate that cannot
+  // be evaluated must never be counted as satisfied (spec-vacuity guard).
+  const pass = actual !== undefined && actual === check.expect;
+  return {
+    checkId: check.checkId,
+    pass,
+    expected: check.expect,
+    actual: actual ?? "<no-observation>",
+    description: check.description,
+  };
+}
+
+/** Evaluate one predicate against observations. Pure. */
+export function evaluatePredicate(pred: Predicate, observed: Observations): PredicateResult {
+  const checks = pred.checks.map((c) => evalCheck(c, observed));
+  const vacuous = pred.checks.some((c) => observed[c.checkId] === undefined);
+  return {
+    predicateId: pred.id,
+    severity: pred.severity,
+    pass: checks.length > 0 && checks.every((c) => c.pass),
+    checks,
+    vacuous,
+  };
+}
+
+/** Evaluate a set of predicates against one observation map. Pure. */
+export function evaluatePredicates(preds: Predicate[], observed: Observations): PredicateResult[] {
+  return preds.map((p) => evaluatePredicate(p, observed));
+}