@chatpanel/events 0.85.0 → 0.89.0

package/model-ledger.js

@@ -0,0 +1,228 @@
+// The MODEL LEDGER — an engine's record, the scorecard pattern applied to engines
+// (architecture-pillars.md §13.2).
+//
+// One chained, store-attested ledger per ENGINE — keyed like the scorecard's `byEngine`
+// (`model:<provider>/<model>`, `harness:<id>`), because the same model at two providers is
+// two records: availability, cost and latency are the provider's, not the model's. Entries
+// are FACTS the runner and the gateway observe, never claims:
+//
+//   call          one turn: time to first token, total, tokens in/out, cost when priced, was
+//                 the JSON valid, were the tool calls valid, did it come back empty / refused
+//                 / truncated, did it succeed
+//   declined      it did not answer, and why (unavailable · auth · rate · credits · timeout ·
+//                 context) — the availability signal
+//   rotated-from  a task left it for another engine mid-run
+//   rating        a task's verdict, attributed to the engine that served it (and to the agent)
+//   capability    a proof: it was asked for X and it did / did not deliver
+//   price         what a token costs here — from the provider's list or typed by a person
+//
+// `summarizeEngine(entries)` → the ENGINE CARD: availability, reliability, latency, cost,
+// capability proofs (a capability with three failed proofs is WITHDRAWN until a person
+// re-enables it), quality by job kind, the last refs. model-candidates.js `applyCard` hands
+// the card to `applyOverride`: observed quality / latency / cost replace the name-based
+// guess wherever there is enough history (≥ `minCalls`), the guess stays as the prior until
+// then, and the result says which it used (`observed[]`). Reach is never learned, only
+// typed — a ledger cannot move a model closer than the URL says.
+//
+// Hashing, attestation and chain verification are scorecard.js's, unchanged: the same store
+// marks both, the same `verifyChain` checks both.
+
+import { canonical, sha256, engineKey, normalizeEngine } from './scorecard.js';
+export { verifyChain, attest, verifyAttested } from './scorecard.js';
+
+export const LEDGER_VERSION = 1;
+export const LEDGER_ENTRY_KINDS = Object.freeze(['call', 'declined', 'rotated-from', 'rating', 'capability', 'price']);
+export const DECLINE_REASONS = Object.freeze(['unavailable', 'auth', 'rate', 'credits', 'timeout', 'context', 'other']);
+export const STRUCTURED = Object.freeze(['ok', 'bad', 'n/a']);
+/** Failed proofs before a capability leaves the card. */
+export const WITHDRAW_AFTER = 3;
+/** Calls before an observed number outranks the name-based guess. Small; configurable. */
+export const DEFAULT_MIN_CALLS = 5;
+
+const n0 = (v) => Math.max(0, Math.round(Number(v) || 0));
+const money = (v) => (v == null || v === '' || !Number.isFinite(Number(v)) ? undefined : Math.max(0, Number(v)));
+const clamp01 = (n) => Math.max(0, Math.min(1, Number(n) || 0));
+const bool = (v) => v === true;
+const str = (v, n = 120) => (v == null || v === '' ? undefined : String(v).slice(0, n));
+const strip = (o) => { for (const k of Object.keys(o)) if (o[k] === undefined) delete o[k]; return o; };
+
+/** The ledger's key for an engine — the scorecard's `engineKey`, so the two join. */
+export function ledgerKey(engine) { return engineKey(engine); }
+
+/** A call fact, normalized. Rates are computed later; here every field is a plain observation. */
+export function normalizeCall(c) {
+  const src = c && typeof c === 'object' ? c : {};
+  return strip({
+    ok: src.ok !== false,
+    ttftMs: src.ttftMs != null ? n0(src.ttftMs) : undefined,
+    totalMs: src.totalMs != null ? n0(src.totalMs) : undefined,
+    tokensIn: src.tokensIn != null ? n0(src.tokensIn) : undefined,
+    tokensOut: src.tokensOut != null ? n0(src.tokensOut) : undefined,
+    // The total when the split is unknown (a harness reports one number, or none).
+    tokens: src.tokens != null && src.tokensIn == null && src.tokensOut == null ? n0(src.tokens) : undefined,
+    cost: money(src.cost),
+    structured: STRUCTURED.includes(src.structured) ? src.structured : 'n/a',
+    toolCalls: src.toolCalls && typeof src.toolCalls === 'object' ? { asked: n0(src.toolCalls.asked), valid: Math.min(n0(src.toolCalls.asked), n0(src.toolCalls.valid)) } : undefined,
+    empty: bool(src.empty) || undefined,
+    refused: bool(src.refused) || undefined,
+    truncated: bool(src.truncated) || undefined,
+  });
+}
+
+/**
+ * A new entry chained onto `prev`. `fact.engine` is required and keyed; the rest is by kind.
+ * Pure apart from the digest; the store attests.
+ */
+export async function makeLedgerEntry(fact, prev, { now = () => Date.now(), subtle } = {}) {
+  if (!fact || typeof fact !== 'object') throw new Error('model-ledger: an entry needs a fact');
+  if (!LEDGER_ENTRY_KINDS.includes(fact.kind)) throw new Error(`model-ledger: kind must be one of ${LEDGER_ENTRY_KINDS.join(', ')}`);
+  const engine = normalizeEngine(fact.engine);
+  if (!engine) throw new Error('model-ledger: engine required');
+  const key = engineKey(engine);
+  if (prev && prev.key !== key) throw new Error(`model-ledger: entry for ${key} chained onto ${prev.key}`);
+  const e = strip({
+    v: LEDGER_VERSION,
+    seq: prev ? prev.seq + 1 : 0,
+    key,
+    engine,
+    kind: fact.kind,
+    at: Number(fact.at) || now(),
+    runId: str(fact.runId), taskId: str(fact.taskId), agentId: str(fact.agentId), jobKind: str(fact.jobKind, 60),
+    call: fact.kind === 'call' ? normalizeCall(fact.call) : undefined,
+    declined: fact.kind === 'declined' ? { reason: DECLINE_REASONS.includes(fact.declined?.reason) ? fact.declined.reason : 'other', ...(fact.declined?.error ? { error: String(fact.declined.error).slice(0, 300) } : {}) } : undefined,
+    rotated: fact.kind === 'rotated-from' ? strip({ to: engineKey(fact.rotated?.to) || undefined, reason: str(fact.rotated?.reason, 300) }) : undefined,
+    rating: fact.kind === 'rating' ? strip({ by: String(fact.rating?.by || 'person').slice(0, 40), score: clamp01(fact.rating?.score), jobKind: str(fact.rating?.jobKind || fact.jobKind, 60), agentId: str(fact.rating?.agentId || fact.agentId) }) : undefined,
+    capability: fact.kind === 'capability' ? { id: String(fact.capability?.id || '').slice(0, 40), proved: bool(fact.capability?.proved) } : undefined,
+    price: fact.kind === 'price' ? strip({ per1kIn: money(fact.price?.per1kIn) ?? 0, per1kOut: money(fact.price?.per1kOut) ?? 0, source: fact.price?.source === 'user' ? 'user' : 'provider', currency: str(fact.price?.currency, 8) }) : undefined,
+    refs: Array.isArray(fact.refs) && fact.refs.length ? fact.refs.map(String).slice(0, 12) : undefined,
+    prev: prev ? prev.hash : null,
+  });
+  if (e.kind === 'capability' && !e.capability.id) throw new Error('model-ledger: capability.id required');
+  const { hash: _h, sig: _s, ...hashable } = e;
+  e.hash = await sha256(canonical(hashable), { subtle });
+  return e;
+}
+
+const percentile = (xs, p) => {
+  if (!xs.length) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  return s[Math.min(s.length - 1, Math.max(0, Math.ceil((p / 100) * s.length) - 1))];
+};
+const mean = (xs) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null);
+const rate = (n, of) => (of ? Math.round((n / of) * 1000) / 1000 : null);
+const r3 = (v) => (v == null ? null : Math.round(v * 1000) / 1000);
+
+/**
+ * The engine card. `minCalls` marks it `observed` once there is enough history; `now`
+ * bounds the by-hour availability band (the last 24 h) and the "declining right now" check.
+ */
+export function summarizeEngine(entries, { minCalls = DEFAULT_MIN_CALLS, now = Date.now(), recent = 5 } = {}) {
+  const list = (entries || []).filter((e) => e && e.kind);
+  const calls = list.filter((e) => e.kind === 'call');
+  const declines = list.filter((e) => e.kind === 'declined');
+  const attempts = calls.length + declines.length;
+  // Availability: declines over attempts, and the last 24 hours in bands of one.
+  const byHour = Array.from({ length: 24 }, () => ({ calls: 0, declines: 0 }));
+  for (const e of [...calls, ...declines]) {
+    const h = Math.floor((now - e.at) / 3600000);
+    if (h >= 0 && h < 24) byHour[23 - h][e.kind === 'call' ? 'calls' : 'declines'] += 1;
+  }
+  const declinesBy = {};
+  for (const e of declines) declinesBy[e.declined.reason] = (declinesBy[e.declined.reason] || 0) + 1;
+  // Declining right now: the last three attempts all declined, within the last hour.
+  const lastThree = [...calls, ...declines].sort((a, b) => a.at - b.at).slice(-3);
+  const decliningNow = lastThree.length === 3 && lastThree.every((e) => e.kind === 'declined' && now - e.at < 3600000);
+  // Reliability: each a rate over the calls it applies to.
+  const withJson = calls.filter((e) => e.call.structured !== 'n/a');
+  const withTools = calls.filter((e) => e.call.toolCalls?.asked);
+  const reliability = {
+    failRate: rate(calls.filter((e) => !e.call.ok).length, calls.length),
+    empty: rate(calls.filter((e) => e.call.empty).length, calls.length),
+    refused: rate(calls.filter((e) => e.call.refused).length, calls.length),
+    truncated: rate(calls.filter((e) => e.call.truncated).length, calls.length),
+    badJson: rate(withJson.filter((e) => e.call.structured === 'bad').length, withJson.length),
+    badToolCall: rate(withTools.reduce((n, e) => n + (e.call.toolCalls.asked - e.call.toolCalls.valid), 0), withTools.reduce((n, e) => n + e.call.toolCalls.asked, 0)),
+  };
+  // Latency.
+  const ttft = calls.map((e) => e.call.ttftMs).filter((v) => v != null);
+  const total = calls.map((e) => e.call.totalMs).filter((v) => v != null);
+  const latency = { ttft: { p50: percentile(ttft, 50), p95: percentile(ttft, 95), n: ttft.length }, total: { p50: percentile(total, 50), p95: percentile(total, 95), n: total.length } };
+  // Cost: the latest price entry prices every call that reported tokens; a call that
+  // reported its own cost is taken as is; otherwise the mean tokens per call stands in.
+  const price = list.filter((e) => e.kind === 'price').at(-1)?.price || null;
+  const costs = calls.map((e) => (e.call.cost != null ? e.call.cost : price && (e.call.tokensIn != null || e.call.tokensOut != null) ? ((e.call.tokensIn || 0) * price.per1kIn + (e.call.tokensOut || 0) * price.per1kOut) / 1000 : null)).filter((v) => v != null);
+  const tokens = calls.map((e) => (e.call.tokensIn || 0) + (e.call.tokensOut || 0) + (e.call.tokens || 0)).filter((v) => v > 0);
+  const cost = { perTask: r3(mean(costs)), priced: costs.length, tokensPerTask: tokens.length ? Math.round(mean(tokens)) : null, ...(price ? { per1kIn: price.per1kIn, per1kOut: price.per1kOut, source: price.source } : {}) };
+  // Capability proofs: asked vs proved; withdrawn after WITHDRAW_AFTER failures unless a
+  // later proof succeeded (a person re-enabling it is a proof they record).
+  const proofs = {};
+  for (const e of list.filter((x) => x.kind === 'capability')) {
+    const p = proofs[e.capability.id] || (proofs[e.capability.id] = { asked: 0, proved: 0, failedSince: 0 });
+    p.asked += 1;
+    if (e.capability.proved) { p.proved += 1; p.failedSince = 0; } else p.failedSince += 1;
+  }
+  const capabilities = {
+    proved: Object.keys(proofs).filter((id) => proofs[id].proved > 0 && proofs[id].failedSince < WITHDRAW_AFTER).sort(),
+    withdrawn: Object.keys(proofs).filter((id) => proofs[id].failedSince >= WITHDRAW_AFTER).sort(),
+    proofs: Object.fromEntries(Object.entries(proofs).map(([id, p]) => [id, { asked: p.asked, proved: p.proved }])),
+  };
+  // Quality: mean rating, overall and by job kind.
+  const ratings = list.filter((e) => e.kind === 'rating');
+  const byJobKind = {};
+  for (const e of ratings) { const k = e.rating.jobKind || 'any'; (byJobKind[k] = byJobKind[k] || []).push(e.rating.score); }
+  const quality = {
+    overall: { avg: r3(mean(ratings.map((e) => e.rating.score))), count: ratings.length },
+    byJobKind: Object.fromEntries(Object.entries(byJobKind).map(([k, xs]) => [k, { avg: r3(mean(xs)), count: xs.length }])),
+  };
+  const rotatedFrom = list.filter((e) => e.kind === 'rotated-from').length;
+  return {
+    key: list[0]?.key || null,
+    engine: list[0]?.engine || null,
+    entries: list.length,
+    calls: calls.length,
+    declines: declines.length,
+    observed: calls.length >= minCalls,
+    availability: { rate: attempts ? r3(1 - declines.length / attempts) : null, attempts, declinesBy, byHour, decliningNow },
+    reliability,
+    latency,
+    cost,
+    capabilities,
+    quality,
+    rotatedFrom,
+    refs: [...new Set(list.flatMap((e) => e.refs || []))].slice(-recent),
+    since: list[0]?.at || null,
+    last: list.at(-1)?.at || null,
+    head: list.at(-1)?.hash || null,
+  };
+}
+
+/**
+ * The override a card yields for model-candidates.js `applyOverride` — only the fields it
+ * has enough history for. `quality` is the mean rating (for `jobKind` when the card has
+ * ratings for it, else overall); `latencyMs` the observed p50 to first token (total when no
+ * ttft was recorded); `costPer1k` from the price when one is known; `available: false`
+ * only while it is declining right now. Returns `{ override, observed }`.
+ *
+ * Lives here, beside the card it reads, so recruit.js and a store without a router can use
+ * it; `applyCard` (the override over the guess) stays in model-candidates.js beside
+ * `applyOverride`, the seam it feeds.
+ */
+export function cardOverride(card, { minCalls = DEFAULT_MIN_CALLS, jobKind = null } = {}) {
+  const override = {}; const observed = [];
+  if (!card) return { override, observed };
+  const q = (jobKind && card.quality?.byJobKind?.[jobKind]?.count >= minCalls) ? card.quality.byJobKind[jobKind] : card.quality?.overall;
+  if (q && q.count >= minCalls && q.avg != null) { override.quality = q.avg; observed.push('quality'); }
+  const lat = card.latency?.ttft?.n >= minCalls ? card.latency.ttft.p50 : card.latency?.total?.n >= minCalls ? card.latency.total.p50 : null;
+  if (lat != null) { override.latencyMs = lat; observed.push('latencyMs'); }
+  // Six places, not three: a per-1k price is often 0.0004, and rounding it to 0 made a paid model read as free.
+  if (card.cost?.per1kIn != null && card.cost?.per1kOut != null) { override.costPer1k = Math.round(((card.cost.per1kIn + card.cost.per1kOut) / 2) * 1e6) / 1e6; observed.push('costPer1k'); }
+  if (card.availability?.decliningNow) { override.available = false; observed.push('available'); }
+  return { override, observed };
+}
+
+// `applyCard` — the card over the name-based guess — lives in model-candidates.js beside
+// `applyOverride`, the seam it feeds; this module stays importable by a store that has no
+// router (the gateway vendors it with scorecard.js only).
+// Agent scores normalised by engine (§13.3) live beside the card they adjust: scorecard.js
+// `adjustSummary` and `fit(job, type, summary, { qualityOf })`.
+export { adjustSummary } from './scorecard.js';

package/model-picker.js

@@ -102,7 +102,9 @@ export function groupModels(models, { selectedId = '' } = {}) {
   if (agents.length) {
     sections.push({
       key: 'agents',
-      label: 'Agents',
+      // Naming phase 1 (naming-revamp.md): the CLI coding agents are HARNESSES — a runtime one
+      // of the user's own agents can be given as its engine. The key and kind are code.
+      label: 'Harnesses',
       kind: 'agent',
       items: agents.slice().sort(availableFirst).map(decorate),
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatpanel/events",
-  "version": "0.85.0",
+  "version": "0.89.0",
   "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
   "type": "module",
   "main": "index.js",
@@ -8,6 +8,7 @@
     ".": "./index.js",
     "./adapters.js": "./adapters.js",
     "./adaptive-tool-policy.js": "./adaptive-tool-policy.js",
+    "./agent.js": "./agent.js",
     "./attribution.js": "./attribution.js",
     "./backup-envelope.js": "./backup-envelope.js",
     "./budget.js": "./budget.js",
@@ -21,6 +22,7 @@
     "./curate.js": "./curate.js",
     "./distance.js": "./distance.js",
     "./entitlement.js": "./entitlement.js",
+    "./engine.js": "./engine.js",
     "./entity.js": "./entity.js",
     "./event.js": "./event.js",
     "./extraction.js": "./extraction.js",
@@ -47,6 +49,7 @@
     "./meeting-text.js": "./meeting-text.js",
     "./memory.js": "./memory.js",
     "./model-candidates.js": "./model-candidates.js",
+    "./model-ledger.js": "./model-ledger.js",
     "./model-picker.js": "./model-picker.js",
     "./note-actions.js": "./note-actions.js",
     "./note-graph.js": "./note-graph.js",
@@ -63,6 +66,7 @@
     "./reach.js": "./reach.js",
     "./recipe-tool.js": "./recipe-tool.js",
     "./recipe.js": "./recipe.js",
+    "./recruit.js": "./recruit.js",
     "./record-list.js": "./record-list.js",
     "./redaction-tokens.js": "./redaction-tokens.js",
     "./ref.js": "./ref.js",
@@ -73,6 +77,7 @@
     "./rrf.js": "./rrf.js",
     "./rules.js": "./rules.js",
     "./schedule.js": "./schedule.js",
+    "./scm-connection.js": "./scm-connection.js",
     "./scopes.js": "./scopes.js",
     "./search-engines.js": "./search-engines.js",
     "./skill-manifest.js": "./skill-manifest.js",
@@ -95,6 +100,9 @@
     "./team-task.js": "./team-task.js",
     "./team-record.js": "./team-record.js",
     "./scorecard.js": "./scorecard.js",
+    "./project.js": "./project.js",
+    "./job.js": "./job.js",
+    "./gate.js": "./gate.js",
     "./team-plan.js": "./team-plan.js",
     "./team-run.js": "./team-run.js",
     "./team-tool.js": "./team-tool.js",
@@ -130,6 +138,8 @@
     "README.md",
     "adapters.js",
     "adaptive-tool-policy.js",
+    "agent.js",
+    "attribution.js",
     "backup-envelope.js",
     "budget.js",
     "capability.js",
@@ -142,6 +152,7 @@
     "curate.js",
     "distance.js",
     "entitlement.js",
+    "engine.js",
     "entity.js",
     "event.js",
     "extraction.js",
@@ -168,6 +179,8 @@
     "meeting-shape.js",
     "meeting-text.js",
     "memory.js",
+    "model-candidates.js",
+    "model-ledger.js",
     "model-picker.js",
     "note-actions.js",
     "note-graph.js",
@@ -184,15 +197,18 @@
     "reach.js",
     "recipe-tool.js",
     "recipe.js",
+    "recruit.js",
     "record-list.js",
     "redaction-tokens.js",
     "ref.js",
     "registry.js",
     "route-graph.js",
+    "route-strategies.js",
     "router.js",
     "rrf.js",
     "rules.js",
     "schedule.js",
+    "scm-connection.js",
     "scopes.js",
     "search-engines.js",
     "skill-manifest.js",
@@ -215,6 +231,9 @@
     "team-task.js",
     "team-record.js",
     "scorecard.js",
+    "project.js",
+    "job.js",
+    "gate.js",
     "team-plan.js",
     "team-run.js",
     "team-tool.js",
@@ -238,6 +257,7 @@
     "vault.js",
     "view.js",
     "voice-intents.js",
+    "voice-speaker.js",
     "weather-tool.js",
     "weather.js",
     "web-search-tool.js",

package/project.js

@@ -0,0 +1,170 @@
+// A project — the page a goal starts on, and the record that folds everything done for it.
+//
+// Every job or goal starts here (F8 §12): the goal, defined by its stakeholder — the *chief
+// executive*: a person by default, an agent from the pool when the person delegates it —
+// with a done-when a run can be checked against, a budget the jobs are carved from, the
+// repos the work happens in, and the gate that says how far a team may go without a person.
+// A project is data (a `projects` prefs section, both clients) and a gateway record that
+// folds its jobs, runs and spend from events, the way a run folds (team-record.js).
+//
+// A project's status is a small machine: draft (a goal being written) → open (jobs may be
+// posted) → active (a job was recruited) → done (done-when held, a person closed it) or
+// closed (abandoned). Nothing here runs anything: project-run.js is the executive loop.
+
+import { validateBudget, normalizeBudget } from './budget.js';
+import { normalizeGate, validateGate } from './gate.js';
+
+export const PROJECT_ID_RE = /^[a-z][a-z0-9_-]{0,63}$/i;
+export const PROJECT_STATUSES = Object.freeze(['draft', 'open', 'active', 'done', 'closed']);
+const NEXT = Object.freeze({ draft: ['open', 'closed'], open: ['active', 'closed', 'draft'], active: ['done', 'closed', 'open'], done: ['closed', 'open'], closed: ['open'] });
+export const MAX_REPOS = 16;
+
+export class ProjectError extends Error {
+  constructor(code, message) { super(message); this.name = 'ProjectError'; this.code = code; }
+}
+
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const clip = (s, n) => String(s || '').trim().slice(0, n);
+
+export function validateProject(p) {
+  const errors = [];
+  if (!isRecord(p)) return { ok: false, errors: ['project must be an object'] };
+  if (!PROJECT_ID_RE.test(String(p.id || ''))) errors.push('id: a short identifier (letters, digits, _ -)');
+  if (!clip(p.title, 200)) errors.push('title: what the project is called');
+  if (!clip(p.goal, 4000)) errors.push('goal: what done looks like, in the stakeholder\'s words');
+  if (p.doneWhen !== undefined && !clip(p.doneWhen, 2000)) errors.push('doneWhen: a check a run can be held to, or leave it out');
+  if (p.stakeholder !== undefined && p.stakeholder !== 'person' && !/^[a-z][a-z0-9_-]{0,63}$/i.test(String(p.stakeholder))) errors.push('stakeholder: "person" or an agent id');
+  if (p.status !== undefined && !PROJECT_STATUSES.includes(p.status)) errors.push(`status: one of ${PROJECT_STATUSES.join(', ')}`);
+  const b = validateBudget(p.budget);
+  if (!b.ok) errors.push(...b.errors.map((e) => `budget: ${e}`));
+  if (p.repos !== undefined) {
+    if (!Array.isArray(p.repos)) errors.push('repos: a list of repo ids');
+    else if (p.repos.length > MAX_REPOS) errors.push(`repos: at most ${MAX_REPOS}`);
+  }
+  if (p.gate !== undefined && p.gate !== null) errors.push(...validateGate(p.gate, { partial: true }).errors.map((e) => `gate: ${e}`));
+  return { ok: errors.length === 0, errors };
+}
+
+/** The stored form: defaults filled, the budget normalised, the gate (if any) normalised. */
+export function normalizeProject(p) {
+  const v = validateProject(p);
+  if (!v.ok) throw new ProjectError('INVALID', v.errors.join('; '));
+  return {
+    id: String(p.id),
+    title: clip(p.title, 200),
+    goal: clip(p.goal, 4000),
+    doneWhen: clip(p.doneWhen, 2000),
+    stakeholder: p.stakeholder ? String(p.stakeholder) : 'person',
+    budget: normalizeBudget(p.budget),
+    status: PROJECT_STATUSES.includes(p.status) ? p.status : 'draft',
+    repos: Array.isArray(p.repos) ? [...new Set(p.repos.map((r) => clip(r, 120)).filter(Boolean))].slice(0, MAX_REPOS) : [],
+    ...(p.gate ? { gate: normalizeGate(p.gate, { partial: true }) } : {}),
+    tags: Array.isArray(p.tags) ? [...new Set(p.tags.map((t) => clip(t, 40)).filter(Boolean))].slice(0, 12) : [],
+    createdBy: clip(p.createdBy, 80) || 'person',
+    createdAt: Number(p.createdAt) || Date.now(),
+    ...(p.updatedAt ? { updatedAt: Number(p.updatedAt) } : {}),
+  };
+}
+
+export function defineProject(p) { return Object.freeze(normalizeProject(p)); }
+
+/** May the project move from `from` to `to`? The machine above; a person's close is always allowed. */
+export function canTransition(from, to) {
+  return (NEXT[from] || []).includes(to);
+}
+
+/** A blank page for the form. */
+export function blankProject() {
+  return { id: '', title: '', goal: '', doneWhen: '', stakeholder: 'person', budget: { tokens: 200000, ms: 3600000 }, status: 'draft', repos: [], tags: [] };
+}
+
+/** The form → a project, or the errors (the same shaping both clients use). */
+export function projectFromForm(form) {
+  const budget = {};
+  for (const k of ['tokens', 'calls', 'ms', 'usd']) {
+    const v = Number(form?.budget?.[k]);
+    if (form?.budget?.[k] !== '' && form?.budget?.[k] != null && Number.isFinite(v) && v > 0) budget[k] = v;
+  }
+  const p = {
+    id: String(form?.id || '').trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[^a-z]+/, '').replace(/-+$/, '').slice(0, 64),
+    title: form?.title, goal: form?.goal, doneWhen: form?.doneWhen, stakeholder: form?.stakeholder || 'person',
+    budget, status: form?.status || 'draft',
+    repos: String(Array.isArray(form?.repos) ? form.repos.join(',') : form?.repos || '').split(/[,\s]+/).filter(Boolean),
+    tags: String(Array.isArray(form?.tags) ? form.tags.join(',') : form?.tags || '').split(/[,\s]+/).filter(Boolean),
+    ...(form?.gate ? { gate: form.gate } : {}), ...(form?.createdAt ? { createdAt: form.createdAt } : {}),
+  };
+  const v = validateProject(p);
+  return v.ok ? { ok: true, project: normalizeProject(p) } : { ok: false, errors: v.errors };
+}
+
+// ── the record: a project folded from its events ────────────────────────────────────────
+
+/** The empty record — what the gateway holds per project and both clients read. */
+export function emptyProjectRecord({ id, now = Date.now() } = {}) {
+  return { id, page: null, status: 'draft', jobs: [], runs: [], spend: { tokens: 0, calls: 0, usd: 0, ms: 0 }, decisions: [], report: null, createdAt: now, lastEventAt: now };
+}
+
+/**
+ * Fold one event into the record. Events: `project.created` `{ project }` · `project.updated`
+ * `{ project }` · `project.status` `{ status, by, note }` · `job.posted` `{ job }` ·
+ * `job.updated` `{ job }` (any field: applications, recruited, status) · `run.linked`
+ * `{ runId, jobId }` · `run.spent` `{ runId, spent }` · `project.decision` `{ by, kind, text,
+ * refs }` · `project.report` `{ text, by }`. Idempotent by job id and run id.
+ */
+export function foldProject(rec, ev) {
+  const type = String(ev?.type || '');
+  const p = ev?.payload && typeof ev.payload === 'object' ? ev.payload : (ev || {});
+  const at = Number(ev?.at) || Date.now();
+  rec.lastEventAt = at;
+  switch (type) {
+    case 'project.created':
+    case 'project.updated':
+      if (p.project && typeof p.project === 'object') { rec.page = { ...p.project, updatedAt: at }; rec.status = p.project.status || rec.status; }
+      break;
+    case 'project.status':
+      if (PROJECT_STATUSES.includes(p.status)) { rec.status = p.status; if (rec.page) rec.page.status = p.status; rec.decisions.push({ at, by: p.by || 'person', kind: 'status', text: `${p.status}${p.note ? ` — ${p.note}` : ''}` }); }
+      break;
+    case 'job.posted':
+      if (p.job?.id && !rec.jobs.some((j) => j.id === p.job.id)) rec.jobs.push({ ...p.job, postedAt: at });
+      if (rec.status === 'draft') rec.status = 'open';
+      break;
+    case 'job.updated': {
+      const i = rec.jobs.findIndex((j) => j.id === p.job?.id);
+      if (i >= 0) rec.jobs[i] = { ...rec.jobs[i], ...p.job, updatedAt: at };
+      if (p.job?.status === 'recruited' || p.job?.status === 'in-progress') { if (rec.status === 'open' || rec.status === 'draft') rec.status = 'active'; }
+      break;
+    }
+    case 'run.linked':
+      if (p.runId && !rec.runs.some((r) => r.runId === p.runId)) rec.runs.push({ runId: p.runId, jobId: p.jobId || null, at });
+      break;
+    case 'run.spent': {
+      const r = rec.runs.find((x) => x.runId === p.runId);
+      const prev = r?.spent || { tokens: 0, calls: 0, usd: 0, ms: 0 };
+      const next = { tokens: Number(p.spent?.tokens) || 0, calls: Number(p.spent?.calls) || 0, usd: Number(p.spent?.usd) || 0, ms: Number(p.spent?.ms) || 0 };
+      // A run reports its running total; the project's spend is the sum of every run's latest.
+      for (const k of Object.keys(next)) rec.spend[k] = Math.max(0, (rec.spend[k] || 0) - (prev[k] || 0) + next[k]);
+      if (r) r.spent = next; else rec.runs.push({ runId: p.runId, jobId: null, at, spent: next });
+      break;
+    }
+    case 'project.decision':
+      rec.decisions.push({ at, by: p.by || 'person', kind: p.kind || 'note', text: String(p.text || '').slice(0, 2000), refs: Array.isArray(p.refs) ? p.refs.slice(0, 8) : [] });
+      break;
+    case 'project.report':
+      rec.report = { text: String(p.text || ''), by: p.by || 'runner', at };
+      break;
+    default: break;
+  }
+  return rec;
+}
+
+/** How far along: jobs by status, spend against the budget, whether done-when is claimed. */
+export function projectProgress(rec) {
+  const by = {};
+  for (const j of rec?.jobs || []) by[j.status] = (by[j.status] || 0) + 1;
+  const cap = rec?.page?.budget || {};
+  const spend = rec?.spend || {};
+  const pct = cap.tokens ? Math.min(1, (spend.tokens || 0) / cap.tokens) : cap.usd ? Math.min(1, (spend.usd || 0) / cap.usd) : cap.ms ? Math.min(1, (spend.ms || 0) / cap.ms) : null;
+  const total = (rec?.jobs || []).length;
+  const done = by.done || 0;
+  return { jobs: { total, by }, done, open: (by.open || 0) + (by.evaluating || 0) + (by.recruited || 0) + (by['in-progress'] || 0), spend, cap, budgetUsed: pct, hasReport: !!rec?.report, status: rec?.status || 'draft' };
+}