quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/objects/fetch.js

@@ -0,0 +1,170 @@
+/**
+ * Data for the inline object views, from the real services only. Every read is bounded (timeouts are
+ * short on purpose: an inline card must not hang the composer) and every failure comes back as a
+ * reason string, never as an empty result. Status is checked before anything is parsed: the client
+ * throws on non-2xx, and the throw is what becomes the reason.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { findSkill } from '../skills.js';
+import { packFrom } from './ladder.js';
+import { slotFor } from './agent.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ASSISTANTS_DIR = path.resolve(HERE, '../../../../src/config/entities/assistants');
+const listOf = (d, ...keys) => { for (const k of keys) if (Array.isArray(d?.[k])) return d[k]; return Array.isArray(d) ? d : []; };
+const why = (e) => (e?.status ? `HTTP ${e.status}` : /timed out/i.test(e?.message || '') ? 'timed out' : e?.message || 'failed');
+
+/** The shipped assistant identities: id -> { name, tagline, description }. */
+export function bundledIdentities(dir = ASSISTANTS_DIR) {
+  const out = new Map();
+  let files = [];
+  try { files = fs.readdirSync(dir).filter(f => f.endsWith('.json')); } catch { return out; }
+  for (const f of files) {
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      if (j?.id) out.set(j.id, { name: j.identity?.name || j.id, tagline: j.identity?.tagline || null, description: j.identity?.description || null });
+    } catch { /* skip unreadable */ }
+  }
+  return out;
+}
+
+export function createObjectsApi({ client, orgId = () => null, home = os.homedir(), identities = bundledIdentities }) {
+  const get = (service, p, query, timeout = 12000) => client.get(p, { service, query, retries: 0, timeout });
+  const post = (service, p, body, timeout = 8000) => client.post(p, { service, body, retries: 0, timeout });
+  const org = () => { const o = orgId(); return typeof o === 'string' ? o : null; };
+  let ids = null;
+  const idents = () => (ids ??= identities());
+  const nameOf = (id) => idents().get(id)?.name || id;
+
+  async function verifyReceipt(envelopeId, timeoutS = 8) {
+    try { const d = await post('collector', '/ward/verify-receipt', { source_id: envelopeId, source_kind: 'AEE' }, timeoutS * 1000); return { ok: true, result: d?.result || d }; }
+    catch (e) { return { ok: false, error: why(e), timeout: /timed out/i.test(e?.message || '') ? timeoutS : null }; }
+  }
+  async function aeeGet(id) {
+    try { const d = await get('collector', `/aee/${encodeURIComponent(id)}`, undefined, 10000); return { ok: true, env: d?.envelope || d }; }
+    catch (e) { return { ok: false, status: e?.status, error: why(e) }; }
+  }
+
+  /** Workflow by id or display name (quoxflow GET /api/workflows). -> { id, name, definition } | null */
+  async function findWorkflow(ref) {
+    const r = String(ref || '').trim();
+    try { const d = await get('quoxflow', `/api/workflows/${encodeURIComponent(r)}`); const w = d?.data || d; if (w?.id) return w; } catch (e) { if (e?.status && e.status !== 404) throw e; }
+    const all = listOf(await get('quoxflow', '/api/workflows', { limit: 100 }), 'data', 'workflows', 'items');
+    const lc = r.toLowerCase();
+    return all.find(w => String(w.name || '').toLowerCase() === lc) || all.find(w => String(w.name || '').toLowerCase().includes(lc)) || null;
+  }
+  async function pageExecutions(workflowId, status, max = 500) {
+    const out = [];
+    for (let offset = 0; offset < max; offset += 100) {
+      const rows = listOf(await get('quoxflow', '/api/executions', { workflowId, status, limit: 100, offset }), 'data', 'executions');
+      out.push(...rows);
+      if (rows.length < 100) break;
+    }
+    return out;
+  }
+
+  return {
+    /** E1 */
+    async skill(name) {
+      const all = listOf(await get('collector', '/quoxflow/skills', { orgId: org() || undefined }), 'data', 'skills');
+      const hit = findSkill(all, name);
+      if (!hit) return { error: `No skill named "${name}". /skills lists them.`, tone: 'warn' };
+      let skill = hit;
+      try { const d = await get('collector', `/quoxflow/skills/${encodeURIComponent(hit.id)}`, { orgId: org() || undefined }); skill = d?.data || d || hit; } catch { /* the list row is the same record */ }
+      let scoreboard = null;
+      // The org-scoped per-skill route; 404 = no recorded runs. (The bulk /scoreboards list is not
+      // org-filtered in quoxflow, so it is deliberately not used here.)
+      try { const d = await get('quoxflow', `/api/quox-skills/${encodeURIComponent(skill.id)}/scoreboard`, undefined, 8000); scoreboard = { ok: true, row: d?.data || null }; }
+      catch (e) { scoreboard = e?.status === 404 ? { ok: true, row: null } : { ok: false, error: why(e) }; }
+      return { data: { skill, scoreboard, agentName: nameOf } };
+    },
+
+    /** E2: ref = execution id / correlation id, or a workflow id or name (its latest run). */
+    async workflowRun(ref) {
+      let execution = null;
+      try { const d = await get('quoxflow', `/api/executions/${encodeURIComponent(ref)}`); execution = d?.data || d; } catch (e) { if (e?.status && e.status !== 404) throw e; }
+      if (!execution?.id) {
+        const wf = await findWorkflow(ref);
+        if (!wf) return { error: `No workflow or run called "${ref}".`, tone: 'warn' };
+        const rows = listOf(await get('quoxflow', '/api/executions', { workflowId: wf.id, limit: 1 }), 'data', 'executions');
+        if (!rows.length) return { error: `${wf.name || wf.id} has never run.`, tone: 'warn' };
+        execution = rows[0];
+      }
+      let envelopes = null, def = null;
+      try { const d = await get('quoxflow', `/api/executions/${encodeURIComponent(execution.id)}/envelopes`); envelopes = listOf(d?.data || d, 'envelopes'); } catch { envelopes = null; }
+      try { const d = await get('quoxflow', `/api/workflows/${encodeURIComponent(execution.workflowId)}`); def = (d?.data || d)?.definition || null; } catch { def = null; }
+      return { data: { execution, envelopes, def } };
+    },
+
+    /** E3 */
+    async crystal(ref) {
+      const wf = await findWorkflow(ref);
+      if (!wf) return { error: `No workflow called "${ref}".`, tone: 'warn' };
+      const [completed, failed] = await Promise.all([pageExecutions(wf.id, 'completed'), pageExecutions(wf.id, 'failed')]);
+      return { data: { workflow: { id: wf.id, name: wf.name }, executions: [...completed, ...failed], def: wf.definition || null } };
+    },
+
+    /** E4 */
+    async agent(name) {
+      const q = String(name || '').trim().toLowerCase();
+      let toolMap = null, toolErr = null;
+      try { toolMap = (await client.get('/api/v1/tools/agents', { service: 'collector', noAuth: true, retries: 0, timeout: 10000 }))?.agentTools || null; } catch (e) { toolErr = why(e); }
+      let orgAgents = [];
+      try { if (org()) orgAgents = listOf(await get('auth', `/api/orgs/${org()}/agents`, { includeTools: 'false' }), 'agents', 'data'); } catch { /* optional */ }
+      const known = new Set([...Object.keys(toolMap || {}), ...idents().keys(), ...orgAgents.map(a => a.agent_id)]);
+      let id = [...known].find(k => k.toLowerCase() === q);
+      if (!id) id = [...known].find(k => String(nameOf(k)).toLowerCase() === q) || orgAgents.find(a => String(a.name || '').toLowerCase() === q)?.agent_id;
+      if (!id) return { error: `No agent called "${name}".${toolErr ? ` (agent list: ${toolErr})` : ''}`, tone: 'warn' };
+      const record = orgAgents.find(a => a.agent_id === id) || null;
+      const ident = idents().get(id) || {};
+      let slot = null;
+      try { slot = slotFor(listOf(await get('collector', '/api/v1/slots', undefined, 10000), 'slots'), id); } catch { slot = null; }
+      let last = null, lastErr = null, receipt = null;
+      try { last = listOf(await get('collector', '/aee/query', { from: `agent.${id}`, limit: 1 }, 10000), 'envelopes')[0] || null; } catch (e) { lastErr = why(e); }
+      if (last?.id) receipt = await verifyReceipt(last.id);
+      return { data: { id, name: ident.name || record?.name || id, tagline: ident.tagline, description: record?.description || ident.description || null, status: record?.status || null, record, tools: toolMap ? (toolMap[id] || []) : null, toolsErr: toolErr, slot, last, lastErr, receipt } };
+    },
+
+    /** E6 */
+    async memory(query) {
+      const d = await get('memory', '/api/memory/search', { q: query, limit: 10 });
+      return { data: { query, results: listOf(d, 'results', 'memories', 'data') } };
+    },
+
+    /** E7 */
+    async rules() {
+      let policies;
+      const o = org();
+      if (!o) policies = { ok: false, error: 'no org on this profile' };
+      else {
+        try { policies = { ok: true, list: listOf(await get('collector', `/orgs/${o}/governance/policies`, undefined, 15000), 'policies') }; }
+        catch (e) { policies = { ok: false, error: why(e) }; }
+      }
+      const pack = packFrom((f) => fs.readFileSync(path.join(home, '.claude', 'skills', f), 'utf8'));
+      return { data: { policies, pack } };
+    },
+
+    /** D1 */
+    async proof(tool) {
+      const envelope = await aeeGet(tool.envelopeId);
+      let aocl = null;
+      const corr = envelope.ok ? envelope.env?.corr : null;
+      if (corr) {
+        try { aocl = { ok: true, list: listOf(await get('collector', '/aee/query', { corr, limit: 50 }, 10000), 'envelopes').filter(e => /^aocl\./.test(String(e.intent || ''))) }; }
+        catch (e) { aocl = { ok: false, error: why(e) }; }
+      }
+      const receipt = await verifyReceipt(tool.envelopeId);
+      return { data: { tool, envelope, aocl, receipt } };
+    },
+
+    /** D3 */
+    async reconcile(tools) {
+      const items = [];
+      for (const t of tools) items.push({ tool: t.tool, envelopeId: t.envelopeId || null, record: t.envelopeId ? await aeeGet(t.envelopeId) : null });
+      return { data: { items } };
+    }
+  };
+}

package/lib/quoxon/objects/index.js

@@ -0,0 +1,85 @@
+/**
+ * Inline object views: one entry point for app.js. `runObjectCommand` fetches and returns either an
+ * object item ({ type, data }) that history renders with <ObjectView/>, or a note ({ text, tone }).
+ * The view itself is rebuilt from data at render width (resize reprints history), so items stay
+ * pure data.
+ */
+import { skillCard } from './skill.js';
+import { stepFlow } from './workflow.js';
+import { crystalCard } from './crystal.js';
+import { agentCard } from './agent.js';
+import { memoryFacts } from './memory.js';
+import { rulesLadder } from './ladder.js';
+import { proofChain, reconcileView } from './proof.js';
+
+export { skillCard, stepFlow, crystalCard, agentCard, memoryFacts, rulesLadder, proofChain, reconcileView };
+export { createObjectsApi } from './fetch.js';
+export { decodeRow, arrivalSeconds } from './model.js';
+
+export const BUILDERS = { skill: skillCard, workflow: stepFlow, crystal: crystalCard, agent: agentCard, memory: memoryFacts, rules: rulesLadder, proof: proofChain, reconcile: reconcileView };
+
+/** -> view { box?, rows } for an object item at this width (now injected for tests). */
+export function buildObject(obj, cols, now = Date.now()) {
+  const b = BUILDERS[obj?.type];
+  if (!b) return { rows: [] };
+  return b({ now, ...obj.data }, cols);
+}
+
+/** Tool blocks of this session that carry an envelope id, newest last. */
+export function toolCalls(items) {
+  return (items || []).filter(b => b && b.kind === 'tool' && b.status !== 'running');
+}
+
+const USAGE = {
+  '/workflow': 'Usage: /workflow <name | workflow id | run id>',
+  '/crystal': 'Usage: /crystal <workflow name or id>',
+  '/memory': 'Usage: /memory <query>',
+  '/agents': 'Usage: /agents <name>'
+};
+
+/**
+ * cmd: '/skills' (with a name), '/workflow', '/crystal', '/agents' (with a name), '/memory', '/rules',
+ * '/proof', '/reconcile'. ctx: { objects (createObjectsApi), rules, rulesOn, items (history + live
+ * blocks) }. -> { object: { type, data } } | { note: text, tone } | null (not ours).
+ */
+export async function runObjectCommand(cmd, arg, ctx) {
+  const o = ctx.objects;
+  const a = String(arg || '').trim();
+  // A bare /skills or /agents is a list, not an object: leave it to its own handler.
+  if (!['/workflow', '/crystal', '/memory', '/rules', '/proof', '/reconcile'].includes(cmd) && !((cmd === '/skills' || cmd === '/agents') && a)) return null;
+  if (!o) return cmd === '/rules' || cmd === '/skills' ? null : { note: 'Object views are not available in this mode.', tone: 'warn' };
+  const wrap = async (type, fn) => {
+    try {
+      const r = await fn();
+      if (r?.error) return { note: r.error, tone: r.tone || 'warn' };
+      return { object: { type, data: r.data } };
+    } catch (e) {
+      return { note: `${type}: ${e?.status ? `HTTP ${e.status}: ` : ''}${e?.message || 'failed'}`, tone: 'warn' };
+    }
+  };
+  switch (cmd) {
+    case '/skills': return a ? wrap('skill', () => o.skill(a)) : null;
+    case '/agents': return a ? wrap('agent', () => o.agent(a)) : null;
+    case '/workflow': return a ? wrap('workflow', () => o.workflowRun(a)) : { note: USAGE['/workflow'], tone: 'warn' };
+    case '/crystal': return a ? wrap('crystal', () => o.crystal(a)) : { note: USAGE['/crystal'], tone: 'warn' };
+    case '/memory': return a ? wrap('memory', () => o.memory(a)) : { note: USAGE['/memory'], tone: 'warn' };
+    case '/rules': {
+      return wrap('rules', async () => {
+        const r = await o.rules();
+        return { data: { ...r.data, quoxmd: ctx.rules || null, enabled: ctx.rulesOn !== false } };
+      });
+    }
+    case '/proof': {
+      const calls = toolCalls(ctx.items).filter(b => b.envelopeId);
+      const t = a ? calls.find(b => b.envelopeId === a || b.callId === a) : calls[calls.length - 1];
+      if (!t) return { note: a ? `No tool call "${a}" with an envelope in this session.` : 'No tool call with an envelope id in this session yet.', tone: 'warn' };
+      return wrap('proof', () => o.proof({ tool: t.tool, status: t.status, envelopeId: t.envelopeId, callId: t.callId }));
+    }
+    case '/reconcile': {
+      const unk = toolCalls(ctx.items).filter(b => b.status === 'effect_unknown');
+      if (!unk.length) return { note: 'Nothing to reconcile: no tool call in this session ended with effect unknown.' };
+      return wrap('reconcile', () => o.reconcile(unk.map(b => ({ tool: b.tool, envelopeId: b.envelopeId }))));
+    }
+    default: return null;
+  }
+}

package/lib/quoxon/objects/ladder.js

@@ -0,0 +1,71 @@
+/**
+ * E7 rules precedence: three layers that are visibly different and never confused.
+ *   advisory  QUOX.md files this client found (sent as context; cannot grant or bypass anything)
+ *   pack      the signed core dev pack on this machine (~/.claude/skills/.pack-version and
+ *             .pack-rights.json, written by the collector's skill-pack installer): team guidance for
+ *             coding agents, still advisory
+ *   enforced  ARMED governance policies on the server (GET /orgs/:org/governance/policies): the only
+ *             layer that can stop an action
+ * The effective layer is the highest one that has rules. An unreadable layer is reported, and never
+ * treated as empty when deciding what is effective.
+ */
+import { seg, fit, plural } from './model.js';
+
+/** Pure: read the pack marker files through an injected reader (fs.readFileSync-like, may throw). */
+export function packFrom(read) {
+  let marker = null, rights = null;
+  try { marker = String(read('.pack-version')).trim(); } catch { /* absent */ }
+  try { rights = JSON.parse(read('.pack-rights.json')); } catch { /* absent */ }
+  if (!marker && !rights) return { state: 'none' };
+  let m = null;
+  try { m = marker ? JSON.parse(marker) : null; } catch { m = null; }
+  const version = rights?.version ?? m?.version ?? (marker && !m ? marker : null);
+  return { state: 'installed', version: version != null ? String(version) : null, packId: rights?.packId ?? m?.packId ?? null, skills: Array.isArray(rights?.rights) ? rights.rights.length : null };
+}
+
+/**
+ * d: { quoxmd: loadRules() result | null, enabled: boolean, pack: packFrom() result,
+ *      policies: { ok: true, list } | { ok: false, error } }
+ */
+export function rulesLadder(d, cols) {
+  const nw = cols < 66;
+  const rows = [];
+  const files = d.quoxmd?.files || [];
+  const pol = d.policies || { ok: false, error: 'not read' };
+  const armed = pol.ok ? (pol.list || []).filter(p => p.state === 'armed') : [];
+  const staged = pol.ok ? (pol.list || []).filter(p => p.state === 'draft') : [];
+  const layers = [
+    { tag: 'advisory', role: 'muted', has: files.length > 0 && d.enabled !== false,
+      src: !files.length ? 'no QUOX.md found' : d.enabled === false ? `QUOX.md (${files.length}) · off this session` : `QUOX.md (${plural(files.length, 'file')}${d.quoxmd?.truncated ? ', cut' : ''})`,
+      scope: nw ? 'local' : 'you, this machine · guides only' },
+    { tag: 'pack', role: 'teal', has: d.pack?.state === 'installed',
+      src: d.pack?.state === 'installed' ? `core dev pack${d.pack.version ? ` v${d.pack.version}` : ''}${d.pack.skills != null && !nw ? ` · ${d.pack.skills} skills` : ''}` : 'not installed here',
+      scope: nw ? 'team' : 'team, signed · guides only' },
+    { tag: 'enforced', role: 'indigo', has: armed.length > 0, unknown: !pol.ok,
+      src: pol.ok ? (armed.length ? `${plural(armed.length, 'governance policy', 'governance policies')} armed` : 'no armed policy') : `could not read (${fit(pol.error, 28)})`,
+      scope: nw ? 'server' : 'server, cannot be bypassed' }
+  ];
+  const top = pol.ok ? [...layers].reverse().find(l => l.has) : null;
+  rows.push([seg('rules ', 'muted'), seg(nw ? 'precedence, top wins' : 'precedence · the highest layer with rules wins', 'value', true)]);
+  for (const l of [...layers].reverse()) {
+    const on = top === l;
+    const lose = top && !on && l.has;
+    rows.push([
+      seg(on ? '▸ ' : '  ', on ? 'value' : 'faint', true),
+      seg(l.tag.padEnd(9), lose ? 'faint' : l.unknown ? 'warn' : l.role, on),
+      seg(fit(l.src, nw ? cols - 14 : 34).padEnd(nw ? 0 : 35), l.unknown ? 'warn' : lose ? 'muted' : 'value', on),
+      ...(nw ? [] : [seg(fit(l.scope, Math.max(0, cols - 50)), 'muted')])
+    ]);
+  }
+  for (const p of armed.slice(0, 4)) rows.push([seg('    · ', 'faint'), seg(fit(`"${p.rule_text}"`, cols - 24), 'value'), seg(` → ${p.policy?.effect || 'enforced'}`, 'indigo')]);
+  if (armed.length > 4) rows.push([seg(`    … ${armed.length - 4} more armed`, 'muted')]);
+  if (staged.length) rows.push([seg(`    ${plural(staged.length, 'draft')} not armed (enforce nothing until armed)`, 'muted')]);
+  let eff;
+  if (!pol.ok) eff = [seg(nw ? 'effective: unknown (policies unreadable)' : 'effective: unknown · the server\'s policies could not be read, so nothing here is called enforced', 'warn')];
+  else if (top?.tag === 'enforced') eff = [seg(nw ? 'effective: enforced (server wins)' : 'effective: enforced · server policy outranks pack and QUOX.md', 'indigo')];
+  else if (top) eff = [seg(nw ? `effective: ${top.tag} (advisory only)` : `effective: ${top.tag} · advisory, guides the agent but enforces nothing`, top.role === 'muted' ? 'value' : top.role)];
+  else eff = [seg('effective: none · no rules at any layer', 'muted')];
+  rows.push(eff);
+  rows.push([seg(nw ? '/rules files: the QUOX.md text' : '/rules files shows the QUOX.md text · /rules off|on', 'faint')]);
+  return { rows };
+}

package/lib/quoxon/objects/memory.js

@@ -0,0 +1,44 @@
+/**
+ * E6 memory facts with provenance, from GET /api/memory/search (memory service). Each fact shows what
+ * the record says about where it came from (provenance, type, source conversation or agent), how old
+ * and how trusted it is (confidence, verification, use), and any conflict state (superseded or
+ * invalid) in plain sight, never hidden.
+ */
+import { seg, fit, ago, short, plural } from './model.js';
+
+const PROVENANCE = {
+  model_inference: 'inferred by a model', user_stated: 'stated by a user', user_confirmed: 'confirmed by a user',
+  tool_output: 'from a tool result', document: 'from a document', imported: 'imported', system: 'system'
+};
+export const provenanceWord = (p) => (p ? PROVENANCE[p] || String(p).replace(/_/g, ' ') : null);
+
+/** d: { query, results: [...], total?, now } */
+export function memoryFacts(d, cols, { max = 5 } = {}) {
+  const now = d.now ?? Date.now();
+  const nw = cols < 70;
+  const inner = Math.max(20, cols - 6);
+  const rows = [];
+  const res = (d.results || []).slice(0, max);
+  if (!res.length) return { rows: [[seg(`No memory matches "${fit(d.query, 40)}".`, 'muted')]] };
+  rows.push([seg(`${plural((d.results || []).length, 'fact')} for "${fit(d.query, 40)}"${(d.results || []).length > max ? `, showing ${max}` : ''}`, 'muted')]);
+  const L = (label, text, role = 'value') => [seg('  '), seg(label.padEnd(7), 'muted'), seg(fit(text, inner - 9), role)];
+  for (const m of res) {
+    rows.push([seg(' ')]);
+    rows.push([seg('◆ ', 'indigo', true), seg(m.memory_role === 'fact' || !m.memory_role ? 'fact ' : `${m.memory_role} `, 'muted'), seg(fit(m.content, inner - 8), 'value', true)]);
+    const src = [provenanceWord(m.provenance), m.memory_type].filter(Boolean);
+    if (m.source_conversation_id) src.push(nw ? `chat ${short(m.source_conversation_id, 8)}` : `conversation ${short(m.source_conversation_id, 10)}`);
+    if (m.agent_id) src.push(`agent ${m.agent_id}`);
+    if (src.length) rows.push(L('source', src.join(' · ')));
+    const age = [];
+    const created = m.created_at || m.createdAt;
+    if (created) age.push(`${ago(created, now)} old`);
+    if (m.confidence != null) age.push(`confidence ${Math.round(Number(m.confidence) * 100)}%`);
+    if (m.verified_at) age.push(`verified${m.verified_by ? ` by ${short(m.verified_by, 10)}` : ''} ${ago(m.verified_at, now)} ago`);
+    else age.push('not verified');
+    if (m.access_count) age.push(`used ${plural(Number(m.access_count), 'time')}`);
+    rows.push(L('age', age.join(' · '), 'muted'));
+    if (m.superseded_by) rows.push(L('status', `superseded by ${short(m.superseded_by, 12)}`, 'warn'));
+    else if (m.valid === false || m.valid === 0) rows.push(L('status', 'marked invalid', 'error'));
+  }
+  return { rows };
+}

package/lib/quoxon/objects/model.js

@@ -0,0 +1,118 @@
+/**
+ * Inline object views (QUOXON plan E2/E3, lab group E and D): shared, pure helpers.
+ *
+ * A view is { box?, rows } where a row is an array of segments { text, role, bold? }. Roles are theme
+ * roles ('value', 'muted', 'ok', 'warn', 'error', 'key', 'sky', 'teal', 'indigo', 'violet', 'faint') or
+ * 'agent:<name>', 'provider:<id>', 'proto:<aee|aocl|volt|ward>'. Nothing here does I/O or reads a clock:
+ * time arrives as `now`. Rule for every builder: a field the server did not supply is omitted, never
+ * invented, and an unreachable source is said plainly.
+ */
+import { KANA } from '../qhello.js';
+
+export const seg = (text, role = 'value', bold = false) => ({ text: String(text ?? ''), role, bold });
+export const len = (s) => [...String(s ?? '')].length;
+export const rowText = (row) => row.map(s => s.text).join('');
+export const rowLen = (row) => len(rowText(row));
+
+/** Clip a string to n display chars with an ellipsis (the lab's fit()). */
+export const fit = (s, n) => {
+  const g = [...String(s ?? '').replace(/\s+/g, ' ').trim()];
+  if (n <= 0) return '';
+  return g.length > n ? g.slice(0, Math.max(0, n - 1)).join('') + '…' : g.join('');
+};
+
+/** Clip a row of segments to n chars total; later segments shrink first, the last one gets the ellipsis. */
+export function fitRow(row, n) {
+  const out = [];
+  let used = 0;
+  for (const s of row) {
+    const room = n - used;
+    if (room <= 0) break;
+    const l = len(s.text);
+    if (l <= room) { out.push(s); used += l; continue; }
+    out.push({ ...s, text: fit(s.text, room) });
+    used = n;
+    break;
+  }
+  return out;
+}
+
+/** Pad a row to exactly n chars (clip first). */
+export function padRow(row, n) {
+  const r = fitRow(row, n);
+  const l = rowLen(r);
+  return l < n ? [...r, seg(' '.repeat(n - l), 'muted')] : r;
+}
+
+/** Server timestamps: epoch ms, ISO, or SQLite "YYYY-MM-DD HH:MM:SS" (UTC). */
+export function parseTs(v) {
+  if (v == null || v === '') return null;
+  if (typeof v === 'number') return v;
+  const s = String(v);
+  const t = Date.parse(/^\d{4}-\d\d-\d\d \d\d:\d\d(:\d\d)?$/.test(s) ? s.replace(' ', 'T') + 'Z' : s);
+  return Number.isFinite(t) ? t : null;
+}
+
+/** "45s", "3m", "2h", "28d" between two epoch ms. '' when unknown. */
+export function ago(ts, now) {
+  const t = parseTs(ts);
+  if (t == null || !Number.isFinite(now)) return '';
+  const s = Math.max(0, Math.floor((now - t) / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 48) return `${h}h`;
+  return `${Math.floor(h / 24)}d`;
+}
+
+/** Duration in ms -> "0.4s", "3.4s", "2m05". */
+export function dur(ms) {
+  if (ms == null || !Number.isFinite(ms)) return '';
+  if (ms < 60000) return `${(Math.max(0, ms) / 1000).toFixed(1)}s`;
+  const s = Math.round(ms / 1000);
+  return `${Math.floor(s / 60)}m${String(s % 60).padStart(2, '0')}`;
+}
+
+/** "21:20 UTC" from a timestamp (UTC on purpose: the box and the owner are in different zones). */
+export function hhmm(ts) {
+  const t = parseTs(ts);
+  return t == null ? '' : `${new Date(t).toISOString().slice(11, 16)} UTC`;
+}
+export const day = (ts) => { const t = parseTs(ts); return t == null ? '' : new Date(t).toISOString().slice(0, 10); };
+export const short = (id, n = 8) => { const s = String(id ?? ''); return s.length > n + 1 ? s.slice(0, n) + '…' : s; };
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** Box geometry the lab uses: the box is at most `max` wide and never wider than the terminal less 2. */
+export const boxWidth = (cols, max) => Math.max(20, Math.min((cols || 80) - 2, max));
+
+// ---- decode-in (the lab's text arrival) --------------------------------------------------------------
+// Katakana flicker just ahead of the reveal edge; resolved letters keep their role. Pure: t and t0 in
+// seconds, salt keeps rows distinct. The colour-only afterglow is left to the renderer (it maps `glow`).
+const LEAD = 0.07, GLOW = 0.6, PER_CHAR = 0.012;
+const hash = (a, b, c) => { let h = (a * 374761393 + b * 668265263 + c * 2147483647) | 0; h = Math.imul(h ^ (h >>> 13), 1274126177); return ((h ^ (h >>> 16)) >>> 0) / 4294967296; };
+
+/**
+ * -> cells [{ ch, role, bold, glyph, glow }] for one row at time t (seconds since the object arrived).
+ * t = Infinity (or quiet) gives the settled row. A row starts at t0 and resolves left to right over dur.
+ */
+export function decodeRow(row, t, t0 = 0, d = 0.25, salt = 1) {
+  const chars = [];
+  for (const s of row) for (const ch of s.text) chars.push({ ch, role: s.role, bold: Boolean(s.bold) });
+  if (!Number.isFinite(t)) return chars.map(c => ({ ...c, glyph: false, glow: 0 }));
+  const n = chars.length;
+  const span = Math.max(d, n * PER_CHAR);
+  return chars.map((c, i) => {
+    if (c.ch === ' ') return { ...c, glyph: false, glow: 0 };
+    const r = t0 + (n > 1 ? (i / (n - 1)) * span : 0), dt = t - r;
+    if (dt < -LEAD) return { ch: ' ', role: c.role, bold: false, glyph: false, glow: 0 };
+    if (dt < 0) return { ch: KANA[Math.floor(hash(i, Math.floor(t * 30), salt) * KANA.length)], role: 'sky', bold: false, glyph: true, glow: 0 };
+    return { ...c, bold: c.bold || dt < 0.05, glyph: false, glow: dt < GLOW ? (1 - dt / GLOW) ** 1.6 : 0 };
+  });
+}
+
+/** Seconds the arrival of a view takes: rows start 0.1 s apart and each resolves over 0.25 s. */
+export function arrivalSeconds(view) {
+  const rows = view?.rows?.length || 0;
+  return rows ? 0.1 * (rows - 1) + Math.max(0.25, Math.max(...view.rows.map(r => rowLen(r))) * PER_CHAR) + GLOW : 0;
+}

package/lib/quoxon/objects/proof.js

@@ -0,0 +1,110 @@
+/**
+ * D1 evidence integrity chain and D3 reconciliation for one tool call of this session.
+ *   AEE   the call's envelope, read back (GET /aee/:envelope_id)
+ *   AOCL  aocl.* envelopes on the same correlation id (GET /aee/query?corr=)
+ *   TOOL  what the server recorded for the call (payload.success / tool_name) vs what the stream said
+ *   WARD  the envelope's inclusion receipt (POST /ward/verify-receipt, server-verified, bounded)
+ * A link is drawn confirmed only when its read succeeded and said so. Nothing is recomputed locally,
+ * so the card says the server's WARD verified it, never "recomputed locally".
+ *
+ * D3: a tool that ended effect_unknown is reconciled against the server's own record of the call
+ * (the ops.tool envelope's payload.success). No envelope id means it cannot be reconciled from here.
+ */
+import { seg, fit, short, plural } from './model.js';
+
+const LINKS = ['AEE', 'AOCL', 'TOOL', 'WARD'];
+
+/** -> [{ name, ok: true|false|null, sub }] in chain order. ok null = not confirmed (unknown). */
+export function chainLinks(d) {
+  const t = d.tool || {};
+  const env = d.envelope?.ok ? d.envelope.env : null;
+  const out = [];
+  out.push(env ? { name: 'AEE', ok: true, sub: `envelope ${short(env.id || t.envelopeId, 14)}` }
+    : { name: 'AEE', ok: d.envelope?.status === 404 ? false : null, sub: d.envelope?.status === 404 ? 'envelope not found' : `envelope not read${d.envelope?.error ? ` (${fit(d.envelope.error, 24)})` : ''}` });
+  const aocl = d.aocl?.ok ? d.aocl.list || [] : null;
+  if (aocl && aocl.length) {
+    const has = (i) => aocl.some(e => e.intent === i);
+    const pol = aocl.filter(e => e.intent === 'aocl.policy.evaluated');
+    const polOk = pol.length ? pol.every(e => e.payload?.allPassed !== false) : null;
+    const bits = [];
+    if (has('aocl.identity.verified')) bits.push('identity');
+    if (polOk != null) bits.push(polOk ? 'policy ok' : 'policy blocked');
+    out.push({ name: 'AOCL', ok: polOk === false ? false : true, sub: bits.length ? bits.join(' + ') : plural(aocl.length, 'AOCL record') });
+  } else out.push({ name: 'AOCL', ok: null, sub: aocl ? 'no AOCL record on this corr' : `not read${d.aocl?.error ? ` (${fit(d.aocl.error, 20)})` : ''}` });
+  const rec = env?.payload || null;
+  if (rec && rec.success != null) {
+    const want = t.status === 'ok';
+    const match = Boolean(rec.success) === want || t.status === 'effect_unknown';
+    out.push({ name: 'TOOL', ok: match && Boolean(rec.success), sub: `${rec.tool_name || t.tool || 'tool'} ${rec.success ? 'succeeded' : 'failed'}${match ? '' : ` (stream said ${t.status})`}` });
+  } else out.push({ name: 'TOOL', ok: null, sub: `${t.tool || 'tool'} ${t.status || ''} (no server record)`.trim() });
+  const r = d.receipt?.ok ? d.receipt.result : null;
+  if (r?.status === 'WITNESSED') out.push({ name: 'WARD', ok: true, sub: `witnessed seq ${r.entry?.seq}` });
+  else if (r?.status === 'UNTIPPED') out.push({ name: 'WARD', ok: null, sub: `seq ${r.entry?.seq}, no signed tip yet` });
+  else if (r?.status === 'NOT_WITNESSED') out.push({ name: 'WARD', ok: null, sub: 'not witnessed yet' });
+  else if (r?.status) out.push({ name: 'WARD', ok: false, sub: `${r.status}${r.reason ? ` ${r.reason}` : ''}` });
+  else out.push({ name: 'WARD', ok: null, sub: d.receipt?.timeout ? `no answer in ${d.receipt.timeout}s` : `not checked${d.receipt?.error ? ` (${fit(d.receipt.error, 24)})` : ''}` });
+  return out;
+}
+
+const markOf = (ok) => (ok === true ? ['✔', 'ok'] : ok === false ? ['✖', 'error'] : ['○', 'faint']);
+
+/** d: { tool, envelope, aocl, receipt } -> view { rows } (wide row at >= 90 cols, vertical below). */
+export function proofChain(d, cols) {
+  const links = chainLinks(d);
+  const rows = [];
+  rows.push([seg('proof ', 'muted'), seg(fit(`${d.tool?.tool || 'tool call'}${d.tool?.envelopeId ? ` · ${short(d.tool.envelopeId, 18)}` : ''}`, cols - 10), 'value', true)]);
+  if (cols >= 90) {
+    const head = [], sub = [], cw = Math.max(23, Math.floor((cols - 4) / 4));
+    links.forEach((l, i) => {
+      const role = `proto:${l.name.toLowerCase() === 'tool' ? 'volt' : l.name.toLowerCase()}`;
+      head.push(seg(l.name, l.name === 'TOOL' ? 'value' : role, true));
+      sub.push(seg(fit(l.sub, cw - 1).padEnd(i < 3 ? cw : 0), l.ok === false ? 'error' : 'muted'));
+      if (i < 3) {
+        const linked = l.ok === true && links[i + 1].ok === true;
+        head.push(seg(' ' + (linked ? '━' : '╌').repeat(cw - 2 - l.name.length) + ' ', linked ? 'indigo' : 'faint'));
+      }
+    });
+    rows.push(head, sub);
+  } else {
+    links.forEach((l, i) => {
+      const role = `proto:${l.name.toLowerCase() === 'tool' ? 'volt' : l.name.toLowerCase()}`;
+      const [m, mr] = markOf(l.ok);
+      rows.push([seg(m, mr), seg(' '), seg(l.name.padEnd(5), l.name === 'TOOL' ? 'value' : role, true), seg(fit(l.sub, cols - 12), l.ok === false ? 'error' : 'muted')]);
+      if (i < 3) rows.push([seg(l.ok === true && links[i + 1].ok === true ? '┃' : '╎', l.ok === true && links[i + 1].ok === true ? 'indigo' : 'faint')]);
+    });
+  }
+  const n = links.filter(l => l.ok === true).length;
+  const bad = links.filter(l => l.ok === false).length;
+  if (n === 4) rows.push([seg('✔ ', 'ok'), seg(cols < 60 ? 'chain verified · 4 links' : 'chain verified · 4 links · WARD receipt checked by the server', 'value')]);
+  else rows.push([seg(bad ? '✖ ' : '◐ ', bad ? 'error' : 'warn'), seg(`${n} of 4 links confirmed${bad ? ` · ${bad} contradicted` : ''}`, bad ? 'error' : 'warn')]);
+  return { rows, links };
+}
+
+/** One effect_unknown call reconciled against the server's record of it. */
+export function reconcileItem(it) {
+  if (!it.envelopeId) return { mark: '?', role: 'muted', state: 'unverified', why: 'no envelope id, cannot be checked from here' };
+  if (!it.record) return { mark: '?', role: 'muted', state: 'unverified', why: it.error ? `record not read (${fit(it.error, 30)})` : 'not checked' };
+  if (!it.record.ok) return { mark: '?', role: 'muted', state: 'unverified', why: it.record.status === 404 ? 'no server record of the call' : `record not read (${fit(it.record.error || '', 30)})` };
+  const ok = it.record.env?.payload?.success;
+  if (ok === true) return { mark: '✔', role: 'ok', state: 'confirmed', why: 'server recorded success' };
+  if (ok === false) return { mark: '✖', role: 'error', state: 'mismatch', why: 'server recorded a failure, not done' };
+  return { mark: '?', role: 'muted', state: 'unverified', why: 'server record has no outcome' };
+}
+
+/** d: { items: [{ tool, envelopeId, record }] } -> view { rows } */
+export function reconcileView(d, cols) {
+  const nw = cols < 60;
+  const items = d.items || [];
+  const rows = [[seg(nw ? `reconcile · ${items.length} unknown` : `reconcile · ${plural(items.length, 'call')} ended with effect unknown, checking each`, 'muted')]];
+  let conf = 0, mis = 0;
+  for (const it of items) {
+    const r = reconcileItem(it);
+    if (r.state === 'confirmed') conf++; else if (r.state === 'mismatch') mis++;
+    const row = [seg(r.mark, r.role), seg(' '), seg(fit(it.tool || 'tool', 15).padEnd(16), 'value'), seg(r.state.padEnd(12), r.role === 'muted' ? 'muted' : r.role, r.state !== 'unverified')];
+    if (!nw) row.push(seg(fit(r.why, cols - 34), 'muted'));
+    rows.push(row);
+  }
+  const un = items.length - conf - mis;
+  rows.push([seg(`${conf} confirmed · ${mis} mismatch · ${un} unverified`, mis ? 'warn' : 'muted')]);
+  return { rows };
+}