@chatpanel/gateway 0.6.87 → 0.6.90

package/src/model-ledger.js

@@ -0,0 +1,205 @@
+// VENDORED from @chatpanel/events/model-ledger.js — edit there, then copy over.
+// 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,
+  };
+}
+
+// `cardOverride` and `applyCard` — the card over the name-based guess — live in
+// model-candidates.js beside `applyOverride`, the seam they feed; 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/src/project-store.js

@@ -0,0 +1,139 @@
+// The projects — every goal's page and everything done for it, as the record both clients
+// read (F8 §12). The page itself is data in the shared `projects` prefs section; this store
+// holds the RECORD: the jobs posted on it, who applied and who was recruited, the runs it
+// spawned and what they spent, the stakeholder's decisions, the report. Folded from events
+// with the shared fold (project.js `foldProject`, vendored), so the desktop, the extension
+// and this store never disagree on what a project is.
+//
+// Encrypted at rest with the team store's key, like the runs. Events append; nothing is
+// edited; a watcher gets each event as it lands (the live project board).
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import os from 'node:os';
+import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
+import { emptyProjectRecord, foldProject, projectProgress, PROJECT_ID_RE } from './project.js';
+import { normalizeJob, canTransition as canJobTransition } from './job.js';
+
+const DIR = join(os.homedir(), '.chatpanel');
+const STORE_PATH = process.env.CHATPANEL_PROJECTS_STORE || join(DIR, 'projects.enc');
+const MAX_EVENTS_PER_PROJECT = 20_000;
+const MAX_EVENT_BYTES = 64 * 1024;
+
+function encrypt(key, buf) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ct = Buffer.concat([cipher.update(buf), cipher.final()]);
+  return { v: 1, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), ct: ct.toString('base64') };
+}
+function decrypt(key, env) {
+  const d = createDecipheriv('aes-256-gcm', key, Buffer.from(env.iv, 'base64'));
+  d.setAuthTag(Buffer.from(env.tag, 'base64'));
+  return Buffer.concat([d.update(Buffer.from(env.ct, 'base64')), d.final()]);
+}
+const clone = (v) => (v === undefined ? undefined : JSON.parse(JSON.stringify(v)));
+
+export class ProjectStore {
+  constructor({ storePath = STORE_PATH, key = null, now = () => Date.now() } = {}) {
+    this.path = storePath;
+    this.key = key;
+    this.now = now;
+    this.projects = new Map(); // id -> { ...record, events: [] }
+    this.watchers = new Map(); // id -> Set<fn(ev)>
+  }
+  load() {
+    try {
+      if (existsSync(this.path) && this.key) {
+        const env = JSON.parse(readFileSync(this.path, 'utf8'));
+        const doc = JSON.parse(decrypt(this.key, env).toString('utf8'));
+        for (const p of Array.isArray(doc?.projects) ? doc.projects : []) if (p?.id) this.projects.set(p.id, p);
+      }
+    } catch { this.projects = new Map(); }
+    return this;
+  }
+  save() {
+    if (!this.key) return;
+    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+    const env = encrypt(this.key, Buffer.from(JSON.stringify({ v: 1, projects: [...this.projects.values()] }), 'utf8'));
+    const tmp = `${this.path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(env), { mode: 0o600 });
+    renameSync(tmp, this.path);
+  }
+  _view(rec, { events = false } = {}) {
+    const v = clone({ ...rec, events: undefined });
+    delete v.events;
+    v.progress = projectProgress(v);
+    if (events) v.events = clone(rec.events);
+    return v;
+  }
+  /** Open a record for a page (idempotent: a page saved twice is one record). */
+  create({ id, project = null, by = 'person' } = {}) {
+    if (!PROJECT_ID_RE.test(String(id || ''))) throw new Error('project id: a short identifier');
+    let rec = this.projects.get(id);
+    if (!rec) { rec = { ...emptyProjectRecord({ id, now: this.now() }), events: [] }; this.projects.set(id, rec); }
+    if (project) this.append(id, [{ type: rec.page ? 'project.updated' : 'project.created', at: this.now(), project: { ...project, id }, by }]);
+    else this.save();
+    return this._view(rec);
+  }
+  append(id, events) {
+    const rec = this.projects.get(String(id || ''));
+    if (!rec) throw new Error(`no project ${id}`);
+    const list = Array.isArray(events) ? events : [events];
+    let seq = rec.events.length;
+    for (const e of list) {
+      if (!e || typeof e !== 'object' || !e.type) continue;
+      let bytes; try { bytes = Buffer.byteLength(JSON.stringify(e), 'utf8'); } catch { continue; }
+      if (bytes > MAX_EVENT_BYTES) continue;
+      if (rec.events.length >= MAX_EVENTS_PER_PROJECT) break;
+      const { type, at, ...payload } = e;
+      const ev = { seq: seq++, type: String(type), at: Number(at) || this.now(), payload };
+      rec.events.push(ev);
+      foldProject(rec, ev);
+      for (const fn of this.watchers.get(rec.id) || []) { try { fn(ev); } catch { /* a dead watcher */ } }
+    }
+    this.save();
+    return this._view(rec);
+  }
+  get(id, opts) { const r = this.projects.get(String(id || '')); return r ? this._view(r, opts) : null; }
+  /** Newest activity first; the list a board shows — jobs counted, not listed. */
+  list({ limit = 50, status = '' } = {}) {
+    return [...this.projects.values()]
+      .filter((r) => !status || r.status === status)
+      .sort((a, b) => b.lastEventAt - a.lastEventAt)
+      .slice(0, Math.max(1, Math.min(200, Number(limit) || 50)))
+      .map((r) => { const v = this._view(r); return { ...v, jobs: undefined, decisions: undefined, report: undefined, runs: undefined, jobCount: r.jobs.length, runCount: r.runs.length }; });
+  }
+  /** Every open posting across projects — the job board. */
+  openJobs() {
+    return [...this.projects.values()].flatMap((r) => r.jobs.filter((j) => ['open', 'evaluating', 'recruited'].includes(j.status)).map((j) => ({ ...j, projectTitle: r.page?.title || r.id })));
+  }
+  /** Post a job on a project: validated as a posting, appended as an event. */
+  postJob(id, job, { by = 'person' } = {}) {
+    const rec = this.projects.get(String(id || ''));
+    if (!rec) throw new Error(`no project ${id}`);
+    const j = normalizeJob({ ...job, projectId: rec.id, postedBy: job?.postedBy || by });
+    if (rec.jobs.some((x) => x.id === j.id)) throw new Error(`job ${j.id} already exists`);
+    return this.append(rec.id, [{ type: 'job.posted', at: this.now(), job: j, by }]);
+  }
+  /** Move a job along its machine, or update its fields (applications, recruited, result). */
+  updateJob(id, jobId, patch, { by = 'person' } = {}) {
+    const rec = this.projects.get(String(id || ''));
+    if (!rec) throw new Error(`no project ${id}`);
+    const cur = rec.jobs.find((x) => x.id === jobId);
+    if (!cur) throw new Error(`no job ${jobId}`);
+    if (patch?.status && patch.status !== cur.status && !canJobTransition(cur.status, patch.status)) throw new Error(`a job cannot go from ${cur.status} to ${patch.status}`);
+    const allowed = ['status', 'applications', 'recruited', 'runId', 'result', 'workspace', 'budget', 'brief', 'title', 'needs', 'dependsOn'];
+    const job = { id: jobId };
+    for (const k of allowed) if (patch?.[k] !== undefined) job[k] = patch[k];
+    return this.append(rec.id, [{ type: 'job.updated', at: this.now(), job, by }]);
+  }
+  watch(id, fn) {
+    const set = this.watchers.get(String(id)) || new Set();
+    set.add(fn); this.watchers.set(String(id), set);
+    return () => { set.delete(fn); };
+  }
+  eventsSince(id, after = -1) { const r = this.projects.get(String(id || '')); return r ? r.events.filter((e) => e.seq > after) : []; }
+  remove(id) { const had = this.projects.delete(String(id || '')); if (had) this.save(); return had; }
+}
+
+export function createProjectStore(opts) { return new ProjectStore(opts).load(); }

package/src/project.js

@@ -0,0 +1,171 @@
+// VENDORED from @chatpanel/events/project.js — edit there, then copy over.
+// 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' };
+}

package/src/scorecard-store.js

@@ -82,7 +82,7 @@ export class ScorecardStore {
     if (!p.agentId) return null;
     return this.append({
       agentId: p.agentId, kind: p.outcome === 'task.failed' ? 'task.failed' : 'task.done', at: ev.at,
-      runId: run?.id || p.runId, taskId: p.taskId, model: p.model, size: p.size, roleKind: p.roleKind,
+      runId: run?.id || p.runId, taskId: p.taskId, model: p.model, engine: p.engine, scm: p.scm, size: p.size, roleKind: p.roleKind,
       tools: p.tools, with: p.with, refs: p.refs, error: p.error,
       ...(run?.projectId ? { projectId: run.projectId } : {}), ...(run?.jobId ? { jobId: run.jobId } : {}),
     }).catch(() => null);