@limina-labs/momentum 0.30.2

package/core/swarm/lib/saga.js

@@ -0,0 +1,146 @@
+'use strict';
+
+/**
+ * Swarm saga record — per-supervisor durable state.
+ *
+ * Each supervisor writes one `dispatch-run-<NNNNNN>.json` per wave to
+ * its own `<repo>/.momentum/runs/`. Distinct from the existing
+ * `dispatch-run-NNN.md` artifacts written by Phase 11's
+ * `core/orchestration/run-artifact.js` — those are scout/dispatch/
+ * handoff markdown artifacts; these are JSON saga steps for the
+ * conductor's polling loop + `/swarm resume`.
+ *
+ * Allocation is independent of the .md counters: a separate
+ * `.counters.json` key `swarm-supervise` tracks the swarm sequence.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const RUNS_DIR = '.momentum/runs';
+const COUNTERS_FILENAME = '.counters.json';
+const PRIMITIVE = 'swarm-supervise';
+
+function runsDir(repoPath) {
+  return path.join(repoPath, RUNS_DIR);
+}
+
+function countersPath(repoPath) {
+  return path.join(runsDir(repoPath), COUNTERS_FILENAME);
+}
+
+function allocateRunId(repoPath) {
+  const dir = runsDir(repoPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const cp = countersPath(repoPath);
+  let counters = {};
+  if (fs.existsSync(cp)) {
+    try { counters = JSON.parse(fs.readFileSync(cp, 'utf8')); } catch { counters = {}; }
+  }
+  const next = (counters[PRIMITIVE] || 0) + 1;
+  counters[PRIMITIVE] = next;
+  fs.writeFileSync(cp, JSON.stringify(counters, null, 2) + '\n');
+  return String(next).padStart(3, '0');
+}
+
+function recordPath(repoPath, runId) {
+  return path.join(runsDir(repoPath), `dispatch-run-${runId}.json`);
+}
+
+function writeRecord(repoPath, runId, record) {
+  const file = recordPath(repoPath, runId);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n', 'utf8');
+  return file;
+}
+
+function loadRecord(repoPath, runId) {
+  const file = recordPath(repoPath, runId);
+  if (!fs.existsSync(file)) return null;
+  return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+
+function listRecords(repoPath) {
+  const dir = runsDir(repoPath);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((n) => /^dispatch-run-\d{3,6}\.json$/.test(n))
+    .map((n) => ({
+      runId: n.replace(/^dispatch-run-(\d+)\.json$/, '$1'),
+      path: path.join(dir, n),
+    }));
+}
+
+function findActiveByWave(repoPath, swarmId, wave) {
+  for (const r of listRecords(repoPath)) {
+    try {
+      const rec = JSON.parse(fs.readFileSync(r.path, 'utf8'));
+      if (rec.swarm_id === swarmId && rec.wave === wave && rec.primitive === PRIMITIVE) {
+        return Object.assign({}, rec, { runId: r.runId, path: r.path });
+      }
+    } catch {
+      // ignore malformed
+    }
+  }
+  return null;
+}
+
+/**
+ * Convenience: open-or-create record for (repo, swarm, wave). Allocates
+ * a new run id only if none exists yet for that triple. `seed` is the
+ * default state for a fresh record.
+ */
+function openRecord(repoPath, swarmId, wave, seed) {
+  const existing = findActiveByWave(repoPath, swarmId, wave);
+  if (existing) return existing;
+  const runId = allocateRunId(repoPath);
+  const fresh = Object.assign({
+    run_id: runId,
+    primitive: PRIMITIVE,
+    swarm_id: swarmId,
+    saga_id: seed.saga_id,
+    wave,
+    repo: seed.repo,
+    phase_slug: seed.phase_slug,
+    branch: seed.branch,
+    started: seed.started,
+    step_n: 0,
+    done: false,
+    exit_status: 'in-progress',
+    tasks_done: 0,
+    tasks_total: 0,
+    tokens_used: 0,
+    inbox_items: [],
+    history_tail_offset: 0,
+    claimed_by_session: seed.claimed_by_session,
+  }, seed.overrides || {});
+  writeRecord(repoPath, runId, fresh);
+  return Object.assign({}, fresh, { path: recordPath(repoPath, runId) });
+}
+
+/**
+ * Read-modify-write a saga record. Bumps step_n unless `bumpStep:false`.
+ */
+function updateRecord(repoPath, runId, mutate, opts = {}) {
+  const file = recordPath(repoPath, runId);
+  if (!fs.existsSync(file)) throw new Error(`saga: no record at ${file}`);
+  const cur = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const result = mutate(cur);
+  const next = result === undefined ? cur : result;
+  if (opts.bumpStep !== false) next.step_n = (next.step_n || 0) + 1;
+  fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return next;
+}
+
+module.exports = {
+  PRIMITIVE,
+  RUNS_DIR,
+  allocateRunId,
+  recordPath,
+  writeRecord,
+  loadRecord,
+  listRecords,
+  findActiveByWave,
+  openRecord,
+  updateRecord,
+};

package/core/swarm/lib/sessions.js

@@ -0,0 +1,83 @@
+'use strict';
+
+/**
+ * Swarm sessions[] registry CRUD.
+ *
+ * Phase 17.5 portability — extracted from manifest.js for cleaner
+ * reuse by `/swarm join`. The sessions[] array on the swarm manifest
+ * is append-only and de-duped by `session_id`:
+ *
+ *   - registerSession(eco, swarmId, sessionId, nowIso)
+ *       If sessionId is new → append { session_id, first_seen, last_seen }
+ *       If sessionId exists → no-op (use touchSession to bump last_seen)
+ *
+ *   - touchSession(eco, swarmId, sessionId, nowIso)
+ *       Updates last_seen. Inserts if missing (idempotent).
+ *
+ *   - findSession(manifest, sessionId)
+ *       Pure helper. Returns the entry or null.
+ *
+ *   - listSessions(eco, swarmId)
+ *       Pure helper. Returns the sessions[] array (or []).
+ *
+ * All mutating helpers go through `manifestLib.updateManifest` for
+ * mkdir-locked, validated writes.
+ */
+
+const manifestLib = require('./manifest');
+
+function findSession(manifest, sessionId) {
+  if (!manifest || !Array.isArray(manifest.sessions)) return null;
+  return manifest.sessions.find((s) => s && s.session_id === sessionId) || null;
+}
+
+function listSessions(ecosystemRoot, swarmId) {
+  const m = manifestLib.loadManifest(ecosystemRoot, swarmId);
+  if (!m || !Array.isArray(m.sessions)) return [];
+  return m.sessions.slice();
+}
+
+function registerSession(ecosystemRoot, swarmId, sessionId, nowIso) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new TypeError('registerSession: sessionId required');
+  }
+  return manifestLib.updateManifest(ecosystemRoot, swarmId, (m) => {
+    if (!Array.isArray(m.sessions)) m.sessions = [];
+    const existing = findSession(m, sessionId);
+    if (existing) {
+      // No-op: registerSession is for the FIRST time. last_seen bumps via touch.
+      return;
+    }
+    m.sessions.push({
+      session_id: sessionId,
+      first_seen: nowIso,
+      last_seen: nowIso,
+    });
+  });
+}
+
+function touchSession(ecosystemRoot, swarmId, sessionId, nowIso) {
+  if (typeof sessionId !== 'string' || sessionId.length === 0) {
+    throw new TypeError('touchSession: sessionId required');
+  }
+  return manifestLib.updateManifest(ecosystemRoot, swarmId, (m) => {
+    if (!Array.isArray(m.sessions)) m.sessions = [];
+    const existing = findSession(m, sessionId);
+    if (existing) {
+      existing.last_seen = nowIso;
+    } else {
+      m.sessions.push({
+        session_id: sessionId,
+        first_seen: nowIso,
+        last_seen: nowIso,
+      });
+    }
+  });
+}
+
+module.exports = {
+  findSession,
+  listSessions,
+  registerSession,
+  touchSession,
+};

package/core/swarm/lib/tokens.js

@@ -0,0 +1,255 @@
+'use strict';
+
+/**
+ * Swarm transfer tokens.
+ *
+ * Phase 17.5 portability — opaque tokens for `/swarm focus` and
+ * `/swarm join`. Each token is a small JSON file at
+ * `<eco>/swarms/<id>/tokens/<token>.json`. Single-use: `consumeToken`
+ * deletes on read.
+ *
+ * Shape:
+ *   {
+ *     token: "<16-hex>",
+ *     version: 1,
+ *     kind: "focus" | "join",
+ *     issued_by: "<session-id>",
+ *     issued_at: "<ISO ts>",
+ *     expires_at: "<ISO ts>",
+ *     target_repo?: "<slug>",     // required for kind=focus
+ *     swarm_id?: "<NNNN-slug>"    // required for kind=join (= containing swarm)
+ *   }
+ *
+ * Tokens are NOT secrets in the cryptographic sense — they're
+ * single-attempt short-lived strings on the local filesystem, used to
+ * avoid embedding session UUIDs in spawn directives the user copy-pastes.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const manifestLib = require('./manifest');
+
+const TOKENS_DIR = 'tokens';
+const VALID_KINDS = Object.freeze(['focus', 'join']);
+const TOKEN_HEX = /^[0-9a-f]{16}$/;
+const SLUG = /^[a-z][a-z0-9-]*$/;
+const SWARM_ID = /^[0-9]{4}-[a-z][a-z0-9-]*$/;
+const ISO_DATETIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/;
+
+const DEFAULT_EXPIRY_MS = 60 * 60 * 1000; // 1 hour
+
+function tokensDir(ecosystemRoot, swarmId) {
+  return path.join(manifestLib.swarmDir(ecosystemRoot, swarmId), TOKENS_DIR);
+}
+
+function tokenPath(ecosystemRoot, swarmId, token) {
+  return path.join(tokensDir(ecosystemRoot, swarmId), `${token}.json`);
+}
+
+function ensureLayout(ecosystemRoot, swarmId) {
+  manifestLib.ensureSwarmLayout(ecosystemRoot, swarmId);
+}
+
+function newTokenString() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+function isoFromMs(ms) {
+  return new Date(ms).toISOString();
+}
+
+function nowMsFromIso(iso) {
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) {
+    throw new TypeError(`tokens: invalid ISO timestamp ${JSON.stringify(iso)}`);
+  }
+  return t;
+}
+
+function validateToken(obj) {
+  const errors = [];
+  const push = (p, m) => errors.push({ path: p, message: m });
+
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, errors: [{ path: '$', message: 'token must be a JSON object' }] };
+  }
+  if (typeof obj.token !== 'string' || !TOKEN_HEX.test(obj.token)) {
+    push('$.token', 'must be 16-hex');
+  }
+  if (obj.version !== 1) push('$.version', 'must be 1');
+  if (!VALID_KINDS.includes(obj.kind)) {
+    push('$.kind', `must be one of: ${VALID_KINDS.join(', ')}`);
+  }
+  if (typeof obj.issued_by !== 'string' || obj.issued_by.length === 0) {
+    push('$.issued_by', 'required non-empty string');
+  }
+  if (typeof obj.issued_at !== 'string' || !ISO_DATETIME.test(obj.issued_at)) {
+    push('$.issued_at', 'required ISO-8601 date-time');
+  }
+  if (typeof obj.expires_at !== 'string' || !ISO_DATETIME.test(obj.expires_at)) {
+    push('$.expires_at', 'required ISO-8601 date-time');
+  }
+  if (obj.kind === 'focus') {
+    if (typeof obj.target_repo !== 'string' || !SLUG.test(obj.target_repo)) {
+      push('$.target_repo', 'required slug for kind=focus');
+    }
+  }
+  if (obj.kind === 'join') {
+    if (typeof obj.swarm_id !== 'string' || !SWARM_ID.test(obj.swarm_id)) {
+      push('$.swarm_id', 'required swarm-id for kind=join');
+    }
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+/**
+ * Issue a token and persist it. Returns the full token record.
+ *
+ * @param {object} args
+ * @param {string} args.ecosystemRoot
+ * @param {string} args.swarmId
+ * @param {'focus'|'join'} args.kind
+ * @param {string} args.issuedBy           session id
+ * @param {string} args.nowIso             ISO timestamp
+ * @param {string} [args.targetRepo]       required for kind=focus
+ * @param {string} [args.targetSwarmId]    required for kind=join; defaults to swarmId
+ * @param {number} [args.expiresInMs]      default 1 hour
+ */
+function writeToken(args) {
+  const {
+    ecosystemRoot, swarmId, kind, issuedBy, nowIso,
+    targetRepo, targetSwarmId, expiresInMs = DEFAULT_EXPIRY_MS,
+  } = args;
+  ensureLayout(ecosystemRoot, swarmId);
+  const token = newTokenString();
+  const issuedMs = nowMsFromIso(nowIso);
+  const record = {
+    token,
+    version: 1,
+    kind,
+    issued_by: issuedBy,
+    issued_at: nowIso,
+    expires_at: isoFromMs(issuedMs + expiresInMs),
+  };
+  if (kind === 'focus') record.target_repo = targetRepo;
+  if (kind === 'join') record.swarm_id = targetSwarmId || swarmId;
+
+  const v = validateToken(record);
+  if (!v.ok) {
+    const summary = v.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+    throw new Error(`writeToken: validation failed:\n${summary}`);
+  }
+  const file = tokenPath(ecosystemRoot, swarmId, token);
+  manifestLib.withLock(file, () => {
+    fs.writeFileSync(file, JSON.stringify(record, null, 2) + '\n', 'utf8');
+  });
+  return record;
+}
+
+/**
+ * Read a token without consuming it. Returns null if missing.
+ * Validates and surfaces expiry.
+ */
+function readToken(ecosystemRoot, swarmId, token, nowIso) {
+  const file = tokenPath(ecosystemRoot, swarmId, token);
+  if (!fs.existsSync(file)) return null;
+  const raw = fs.readFileSync(file, 'utf8');
+  const record = JSON.parse(raw);
+  const v = validateToken(record);
+  if (!v.ok) {
+    const summary = v.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+    throw new Error(`readToken: invalid token at ${file}:\n${summary}`);
+  }
+  const expired = nowMsFromIso(nowIso) > nowMsFromIso(record.expires_at);
+  return { ...record, expired };
+}
+
+/**
+ * Read and delete a token in one mkdir-locked step. Throws if the
+ * token does not exist or is expired.
+ */
+function consumeToken(ecosystemRoot, swarmId, token, nowIso) {
+  const file = tokenPath(ecosystemRoot, swarmId, token);
+  if (!fs.existsSync(file)) {
+    throw new Error(`consumeToken: token ${token} not found in swarm ${swarmId}`);
+  }
+  return manifestLib.withLock(file, () => {
+    const raw = fs.readFileSync(file, 'utf8');
+    const record = JSON.parse(raw);
+    const v = validateToken(record);
+    if (!v.ok) {
+      const summary = v.errors.map((e) => `  ${e.path}: ${e.message}`).join('\n');
+      throw new Error(`consumeToken: invalid token at ${file}:\n${summary}`);
+    }
+    if (nowMsFromIso(nowIso) > nowMsFromIso(record.expires_at)) {
+      throw new Error(`consumeToken: token ${token} expired at ${record.expires_at}`);
+    }
+    fs.unlinkSync(file);
+    return record;
+  });
+}
+
+/**
+ * Sweep expired tokens. Returns the list of removed token strings.
+ */
+function purgeExpired(ecosystemRoot, swarmId, nowIso) {
+  ensureLayout(ecosystemRoot, swarmId);
+  const dir = tokensDir(ecosystemRoot, swarmId);
+  const removed = [];
+  const nowMs = nowMsFromIso(nowIso);
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(dir, name);
+    try {
+      const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (nowMs > nowMsFromIso(record.expires_at)) {
+        fs.unlinkSync(file);
+        removed.push(record.token);
+      }
+    } catch (_e) {
+      // skip malformed files
+    }
+  }
+  return removed;
+}
+
+/**
+ * List all current (non-expired) tokens. Read-only.
+ */
+function listTokens(ecosystemRoot, swarmId, nowIso) {
+  ensureLayout(ecosystemRoot, swarmId);
+  const dir = tokensDir(ecosystemRoot, swarmId);
+  const nowMs = nowMsFromIso(nowIso);
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    const file = path.join(dir, name);
+    try {
+      const record = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const expired = nowMs > nowMsFromIso(record.expires_at);
+      out.push({ ...record, expired });
+    } catch (_e) {
+      // skip
+    }
+  }
+  out.sort((a, b) => (a.issued_at < b.issued_at ? -1 : 1));
+  return out;
+}
+
+module.exports = {
+  TOKENS_DIR,
+  VALID_KINDS,
+  DEFAULT_EXPIRY_MS,
+  tokensDir,
+  tokenPath,
+  ensureLayout,
+  newTokenString,
+  validateToken,
+  writeToken,
+  readToken,
+  consumeToken,
+  purgeExpired,
+  listTokens,
+};

package/core/swarm/lib/wave-ordering.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Wave ordering — topological sort from ecosystem.json dependency edges.
+ *
+ * Since Phase 21c this is a thin adapter over the recursive wave engine
+ * (core/waves/lib/waves.js, ADR-0003): identical algorithm, identical
+ * wave output, identical error strings — swarm is the engine's top-scale
+ * consumer. The public surface below is unchanged from Phase 17.
+ *
+ * Input: a list of impacted member ids + the ecosystem manifest's
+ * `dependencies` array ({ from: A, to: B } = A depends on B; B first).
+ * Output: an ordered list of waves, each `{ index, repos }` with repos
+ * sorted lexicographically for stable repeated runs.
+ */
+
+const path = require('path');
+
+const { computeWaveLayers } = require(path.join(__dirname, '..', '..', 'waves', 'lib', 'waves'));
+
+/**
+ * @typedef {Object} EcoDependency
+ * @property {string} from   — the dependent (must produce its work after `to`)
+ * @property {string} to     — the dependency (must produce its work first)
+ * @property {string} [kind] — informational; not used by ordering
+ */
+
+/**
+ * @param {string[]} impactedRepos        — non-empty list of member ids
+ * @param {EcoDependency[]} dependencies  — full ecosystem dependency array
+ * @returns {{ index: number, repos: string[] }[]}
+ */
+function computeWaves(impactedRepos, dependencies) {
+  return computeWaveLayers(impactedRepos, dependencies, { label: 'computeWaves' })
+    .map(({ index, nodes }) => ({ index, repos: nodes }));
+}
+
+/**
+ * Given a list of all members and a dependency list, compute the
+ * waves for the entire ecosystem (used by /swarm verify + diagnostic
+ * tooling). Equivalent to `computeWaves(member_ids, dependencies)`.
+ */
+function computeFullEcosystemWaves(ecosystemManifest) {
+  const members = (ecosystemManifest && Array.isArray(ecosystemManifest.members))
+    ? ecosystemManifest.members.map((m) => m && m.id).filter(Boolean)
+    : [];
+  const deps = (ecosystemManifest && Array.isArray(ecosystemManifest.dependencies))
+    ? ecosystemManifest.dependencies : [];
+  return computeWaves(members, deps);
+}
+
+module.exports = {
+  computeWaves,
+  computeFullEcosystemWaves,
+};

package/core/swarm/schema/board.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/swarm-board-v1.json",
+  "title": "Momentum Swarm Board (Materialized Cache)",
+  "description": "Slim conductor-turn view derived from manifest.json + per-supervisor dispatch-run records. Regenerated on any write to manifest or a supervisor's saga step. Conductor reads ONLY this on most turns — naive manifest+briefs+history = ~290KB; this = ~3KB. The materializer lives in core/swarm/lib/board.js.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["swarm_id", "version", "saga_id", "mode", "rendered_at", "status", "repos", "inbox_count"],
+  "properties": {
+    "swarm_id": {"type": "string", "pattern": "^[0-9]{4}-[a-z][a-z0-9-]*$"},
+    "version": {"type": "integer", "const": 1},
+    "saga_id": {"type": "string", "pattern": "^sg_[a-z0-9]{4,16}$"},
+    "mode": {"type": "string", "enum": ["autopilot", "checkpoint", "interactive"]},
+    "rendered_at": {"type": "string", "format": "date-time"},
+    "status": {"type": "string", "enum": ["running", "paused", "complete", "cancelled", "failed"]},
+    "active_wave": {"type": "integer", "minimum": 1},
+    "repos": {
+      "type": "array",
+      "description": "One row per repo. Pre-rendered display strings — conductor doesn't compute anything.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "wave", "status"],
+        "properties": {
+          "name": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+          "wave": {"type": "integer", "minimum": 1},
+          "status": {"type": "string", "enum": ["queued", "running", "blocked", "complete", "failed", "cancelled"]},
+          "tasks": {"type": "string", "description": "Pre-rendered N/M string, e.g. \"3/9\"."},
+          "tokens": {"type": "string", "description": "Pre-rendered NkB/MkB string, e.g. \"42k/300k\"."},
+          "commits": {"type": "integer", "minimum": 0},
+          "current": {"type": "string"},
+          "inbox_count": {"type": "integer", "minimum": 0},
+          "waiting_on": {"type": "string", "description": "Pre-rendered comma-separated repo list."}
+        }
+      }
+    },
+    "inbox_count": {"type": "integer", "minimum": 0},
+    "recent_activity": {
+      "type": "array",
+      "maxItems": 10,
+      "description": "Last N audit events, newest first. Each is a one-line summary for the board UI.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ts", "msg"],
+        "properties": {
+          "ts": {"type": "string", "description": "Short HH:MM display string, not full timestamp."},
+          "repo": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+          "msg": {"type": "string"}
+        }
+      }
+    }
+  }
+}

package/core/swarm/schema/contract.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/LiminaLabsAI/momentum/schemas/swarm-contract-v1.json",
+  "title": "Momentum Swarm Contract (Pact-Style Shape Declaration)",
+  "description": "Declares a cross-repo surface (REST endpoint, message type, library export). One file per surface at <eco>/swarms/<id>/contracts/<surface>.contract.json. Content-hashed; version-bumped on approval. Wave checkpoint verifies producer↔consumer shape agreement before letting the next wave start.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["surface", "version", "owner", "consumers", "kind", "shape", "content_hash"],
+  "properties": {
+    "surface": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Slug naming this surface (e.g. user-auth-token, billing-events). Used in manifest.contracts[].surface back-reference."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Bumped on every approved breaking shape change. v0.20.0 verifier is structural — semantic compatibility is the user's call."
+    },
+    "owner": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Ecosystem member id that produces this surface."
+    },
+    "consumers": {
+      "type": "array",
+      "minItems": 1,
+      "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]*$"},
+      "description": "Member ids that depend on this surface. Wave ordering ensures owner is in an earlier wave than every consumer."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["http", "rpc", "event", "library", "schema", "other"],
+      "description": "Coarse category. \"http\": REST/GraphQL endpoint. \"rpc\": gRPC/etc. \"event\": Kafka/queue/etc. \"library\": exported function. \"schema\": JSON/Protobuf type. \"other\": opaque (the user-defined shape is authoritative)."
+    },
+    "shape": {
+      "description": "Free-form shape declaration. The verifier compares producer-declared shape against consumer-expected shape — structural diff only. For JSON-shaped contracts a nested object literal works; for libraries an exported-symbols list; for opaque \"other\" surfaces a content-hashed blob.",
+      "oneOf": [
+        {"type": "object"},
+        {"type": "array"},
+        {"type": "string"}
+      ]
+    },
+    "content_hash": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8,64}$",
+      "description": "SHA256-prefix of the canonical serialization of `shape`. The verifier compares hashes first; mismatches fall through to a structural diff for human review."
+    },
+    "created": {"type": "string", "format": "date-time"},
+    "approved_by_session": {
+      "type": "string",
+      "description": "Session id of the conductor that approved this contract version (checkpoint mode). Null in autopilot."
+    },
+    "note": {"type": "string", "description": "Free-form human note explaining the surface and any non-obvious shape decisions."}
+  }
+}