segreant 0.1.0 → 0.2.0

package/dist/dashboard/web/app/views/evidence.js

@@ -10,9 +10,11 @@
 import { h } from '../core/dom.js';
 import { signal, scopedEffect } from '../core/signal.js';
 import { api } from '../core/api.js';
-import { isPrecise, relative, basisWords, usd, usdFromMicros, count } from '../core/fmt.js';
+import { isPrecise, relative, basisWords, usd, usdFromMicros, count, date, pct } from '../core/fmt.js';
+import { pageNotice, step, field, errorText, holdFocus } from '../components/workflow.js';
 import { actionCard } from './spend.js';
 import { projectRenderedAxes } from '../core/claimTypes.js';
+import { residualBoundIsError, residualBoundWords, dayRange, quantizationWords } from '../core/reconcileWords.js';
 /**
  * The headline of this card, keyed on the BILLED CLAIM's state.
  *
@@ -54,44 +56,6 @@ const CLAIM_WORDS = {
         pill: 'pill-ok',
     },
 };
-/**
- * A `Record` rather than an if-chain, keyed by the wire's own union.
- *
- * That is the gate: adding a state to `offPathBound` in `shared-types.ts`
- * without a rendering here fails the BROWSER typecheck. With an if-chain the
- * new state fell through to the "older than the check" sentence below, which
- * would have said a fresh run predates a field it carries — an unrecognised
- * value rendered as an absent one, which is the defect class this screen keeps
- * finding.
- */
-const RESIDUAL_BOUND_WORDS = {
-    none_local_estimate_exceeds_provider: {
-        precise: 'residual bounds nothing — the local estimate exceeds the provider total, so no upper bound on off-path spend survives',
-        plain: 'This remainder cannot tell you how much went outside Segreant: our own estimate already came out higher than the provider’s bill.',
-    },
-    upper_bound_conditional: {
-        precise: 'residual is an upper bound on off-path spend while the local estimate does not exceed true on-path billed cost',
-        plain: 'At most this much could have gone outside Segreant — assuming our own pricing did not overshoot what you were really charged.',
-    },
-    unknown_local_total_truncated_by_retention: {
-        precise: 'residual bounds nothing — retention deleted request rows from inside this period, so the local total is a known undercount by an unknown amount',
-        plain: 'This remainder cannot tell you how much went outside Segreant: some of your own metered requests in this period were deleted by your retention setting, so part of the difference is traffic we did see.',
-    },
-};
-/** Whether the run's own bound state is bad news rather than a caveat. */
-function residualBoundIsError(bound) {
-    return bound === 'none_local_estimate_exceeds_provider'
-        || bound === 'unknown_local_total_truncated_by_retention';
-}
-function residualBoundWords(bound, precise) {
-    const words = bound === undefined ? undefined : RESIDUAL_BOUND_WORDS[bound];
-    if (words === undefined) {
-        return precise
-            ? 'this run predates the recorded bound condition, so what the residual bounds is not established'
-            : 'This run is older than the check that says what the remainder means, so we cannot tell you.';
-    }
-    return precise ? words.precise : words.plain;
-}
 /**
  * What a reconciliation would actually match, stated before the credential.
  *
@@ -173,9 +137,11 @@ function readinessPanel(d) {
         if (!truncated)
             return null;
         const before = r.localLedgerRetention.prunedBeforeMs;
+        const boundary = typeof before === 'number' && Number.isFinite(before) && before > 0 && before <= 8.64e15
+            ? new Date(before).toISOString().slice(0, 10) : 'an unrecorded boundary';
         return h('div', { class: 'drawer-warning', style: 'margin-top: var(--s4)' }, h('strong', { text: 'This ledger was emptied by retention' }), h('p', { text: () => (isPrecise()
-                ? `No OpenAI rows survive, and retention deleted rows before ${before === null ? 'an unrecorded boundary' : new Date(before).toISOString().slice(0, 10)}. Whether any OpenAI spend was metered here cannot be read from the ledger, so nothing about what a reconciliation would match is stated.`
-                : `Your older records were deleted, so there is no OpenAI spend left here to check. We cannot tell you whether there ever was any — only that it is gone.`) }));
+                ? `No OpenAI rows survive, and retention deleted rows before ${boundary}. Whether any OpenAI spend was metered here cannot be read from the ledger, so nothing about what a reconciliation would match is stated.`
+                : `Your older records were deleted, so there is no OpenAI spend left here to check. There's no record of whether there ever was any, only that it is gone.`) }));
     }
     const uncountable = c.importedUsd + c.proxyOffScopeUsd;
     if (c.onDeclaredRouteUsd > 0 || uncountable <= 0)
@@ -245,60 +211,343 @@ function mappingPanel(d) {
             ? `Still excluded from: ${m.excludedFrom.join(', ')}.`
             : 'Provider scope authority is present for this payload; review the recorded reconciliation before consuming the result.') }));
 }
+/** A step is done when readiness no longer lists anything that starts with these words. */
+function readinessHas(d, prefix) {
+    return (d.readiness?.missing ?? []).some((m) => m.step.startsWith(prefix));
+}
+/** The file's own bytes, base64, so the server hashes exactly what the CLI would. */
+async function fileBase64(file) {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
+function rows(pairs) {
+    return h('dl', { class: 'preview-rows' }, ...pairs.map(([k, v]) => h('div', { class: 'preview-row' }, h('dt', { text: k }), h('dd', { text: v }))));
+}
 export function evidenceView() {
     const data = signal(null);
     const error = signal(null);
+    const reloads = signal(0);
+    const { node: noticeNode, say } = pageNotice();
+    const reload = () => {
+        reloads.set(reloads() + 1);
+        // The spine's Billed band reads /api/billing once; a recorded run must reach it.
+        window.dispatchEvent(new CustomEvent('segreant:ledger-changed', { detail: { claim: 'billing' } }));
+    };
     scopedEffect(() => {
+        reloads();
         void api.billing()
-            .then((payload) => data.set(payload))
-            .catch((e) => error.set(e instanceof Error ? e.message : String(e)));
+            .then((payload) => { const restore = holdFocus(page); error.set(null); data.set(payload); restore(); })
+            .catch((e) => error.set(errorText(e)));
     });
-    return h('div', null, h('div', { class: 'view-head' }, h('h1', { class: 'view-title', text: 'Evidence' }), h('p', { class: 'view-plain', text: () => isPrecise()
-            ? 'Provider-side billing evidence and its reconciliation against the local ledger, at project-day grain. Status is never "reconciled" — only "reconciled with residual".'
-            : 'Everything in Spend is our own measurement. This is where we check it against what your provider actually billed you — and tell you honestly how much of it can be checked at all.' })), () => {
+    const page = h('div', null, h('div', { class: 'view-head' }, h('h1', { class: 'view-title', text: 'Close' }), h('p', { class: 'view-plain', text: () => isPrecise()
+            ? 'Provider-side billing evidence and its reconciliation against the local ledger, at project-day grain. Status is never "reconciled", only "reconciled with residual".'
+            : 'Spend is our own measurement. Here you check it against what your provider actually billed, and see how much of it could be checked at all.' })), noticeNode, () => {
         const err = error();
-        if (err)
-            return h('div', { class: 'card' }, h('p', { class: 'drawer-error', role: 'alert', 'aria-live': 'assertive', text: err }));
         const d = data();
+        if (!d && err)
+            return h('div', { class: 'card' }, h('p', { class: 'drawer-error', role: 'alert', text: err }));
         if (!d)
-            return h('div', { class: 'card' }, h('p', { class: 'drawer-muted', role: 'status', 'aria-live': 'polite', 'aria-busy': 'true', text: 'Loading…' }));
-        // A payload with no stated support is a payload that said nothing, which
-        // is `unknown` — not a licence to fall back to the records' label.
-        const claimState = d.claimSupport ? projectRenderedAxes(d.claimSupport.profile).epistemic : 'unknown';
-        const status = CLAIM_WORDS[claimState] ?? CLAIM_WORDS.unknown;
-        // Newest recorded run, read from the immutable collection the server
-        // sends. This used to read `reconciliation.latest`, a field that has
-        // never been on the wire — so it was always null and this screen reported
-        // "no check has been run" no matter how many reconciliations existed.
-        const latest = d.reconciliation?.runs?.[0] ?? null;
-        return h('div', null, h('div', { class: 'card' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: 'Reconciliation status' }), h('span', { class: `pill ${status.pill}`, text: claimState })), h('p', { text: () => (isPrecise() ? status.precise : status.plain) }), 
-        // The server's own one-line reason, where it has one the payload does
-        // not otherwise show. Rendering it beats restating the axes here in
-        // different words, which is how two descriptions of one judgement come
-        // apart.
-        d.claimSupport?.note
-            ? h('p', { class: 'basis', text: d.claimSupport.note })
-            : null, latest
-            ? h('div', null, 
-            // What the residual bounds is a property of THIS run, not of the
-            // status word, and it is the sentence an operator acts on.
-            h('p', { class: residualBoundIsError(latest.result.offPathBound) ? 'drawer-error' : 'basis',
-                text: () => residualBoundWords(latest.result.offPathBound, isPrecise()) }), h('span', { class: 'basis', text: () => `provider side: ${basisWords(latest.result.providerSourceKind)}` }), latest.result.snapshotStability === 'changed_across_observations'
-                ? h('span', { class: 'drawer-error', text: () => (isPrecise()
-                        ? `snapshot stability: changed across observations on ${(latest.result.unstableDayStartMs ?? []).length} day(s) — this reconciliation is contradicted, not established`
-                        : 'Careful: the provider reported different figures for the same days at different times. This check disagrees with itself.') })
-                : null, h('span', { class: 'basis', text: `last run ${relative(latest.computedAtMs)}` }), 
-            // The constant the headline used to be built from, restored to
-            // its actual subject: the held import records, not the run.
-            h('span', { class: 'basis', text: () => (isPrecise()
-                    ? `held provider records: ${d.evidence.reconciliationStatus.replace(/_/g, ' ')}`
-                    : 'The provider records themselves are still operator-supplied and unverified.') }))
-            : h('span', { class: 'basis', text: () => (isPrecise()
-                    ? 'zero recorded observation runs'
-                    : 'no check has been run on this machine yet') }), latest?.result.conditions?.length
-            ? h('ul', { class: 'drawer-notes' }, ...latest.result.conditions.map((c) => h('li', { text: c.replace(/_/g, ' ') })))
-            : null), h('div', { class: 'card', style: 'margin-top: var(--s4)' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: 'Provider records held' })), h('div', { class: 'stat', text: String(d.summary.recordCount) }), h('span', { class: 'basis', text: () => (isPrecise()
-                ? 'imported provider line items, unverified against the provider'
-                : 'billing lines you have given us from your provider') })), readinessPanel(d), mappingPanel(d), kernelPanel(d), h('div', { style: 'margin-top: var(--s6)' }, h('h2', { class: 'card-title', style: 'margin-bottom: var(--s3)', text: 'Start here' }), h('div', { class: 'actions' }, actionCard('billing-readiness'), actionCard('billing-scope'), actionCard('billing-adopt'))), h('div', { style: 'margin-top: var(--s5)' }, h('h2', { class: 'card-title', style: 'margin-bottom: var(--s3)', text: 'Only after readiness says it is worth it' }), h('div', { class: 'actions' }, actionCard('billing-pull'), actionCard('billing-reconcile'))));
+            return h('div', { class: 'card' }, h('p', { class: 'drawer-muted', role: 'status', 'aria-busy': 'true', text: 'Loading…' }));
+        const scopeDone = !readinessHas(d, 'declare the route scope') && !readinessHas(d, 'the active scope cannot');
+        const observed = !readinessHas(d, 'observe a closed period');
+        return h('div', null, statusCard(d), d.demo
+            ? h('p', { class: 'section-note', role: 'note', text: 'This is sample data, so nothing can be recorded here. Every step still previews. Start Segreant without --demo to close your own month.' })
+            : null, step({ n: 1, done: scopeDone }, () => (isPrecise() ? 'Declare the provider project' : 'Say which OpenAI project this machine uses'), () => (isPrecise()
+            ? 'An operator declaration bound to future proxy rows. Unverified by the provider; historical and imported rows are unchanged.'
+            : 'Only spend that goes through Segreant after this, to that project, can be matched against the bill. These are the ids from your OpenAI settings, not keys.'), d.activeScope ? declaredScope(d, reload, say) : null, scopeForm(d.demo, reload, say, scopeDone)), step({ n: 2, done: observed }, () => (isPrecise() ? 'Observe the provider side' : 'Bring in the bill'), () => (isPrecise()
+            ? 'Import an operator export, then adopt it as the Costs observation. Stamped operator-supplied; a direct read-only pull is stronger evidence.'
+            : 'Give Segreant the cost export from your OpenAI account, then use it for the comparison. No key or password is needed for this.'), importForm(d.demo, reload, say), importList(d, reload, say, scopeDone), 
+        // The stronger route needs an Admin credential, so it stays a card whose
+        // drawer states the consequence before any key is involved.
+        h('div', { class: 'actions step-aside' }, actionCard('billing-pull'))), step({ n: 3, done: (d.reconciliation?.runs?.length ?? 0) > 0 }, () => (isPrecise() ? 'Reconcile' : 'Compare and record'), () => (isPrecise()
+            ? 'Preview computes the comparison; Record persists an immutable run and issues it to the kernel.'
+            : 'See how our measurement compares with the bill. Nothing is saved until you record it.'), readinessPanel(d), reconcilePanel(d, reload, say), recordedComparisons(d)), h('details', { class: 'section close-details' }, h('summary', { class: 'section-title', text: () => (isPrecise() ? 'Evidence detail' : 'The evidence behind this') }), kernelPanel(d), mappingPanel(d)));
+    });
+    return page;
+}
+function statusCard(d) {
+    // A payload with no stated support said nothing, which is `unknown`.
+    const claimState = d.claimSupport ? projectRenderedAxes(d.claimSupport.profile).epistemic : 'unknown';
+    const status = CLAIM_WORDS[claimState] ?? CLAIM_WORDS.unknown;
+    // Newest recorded run, from the immutable collection the server sends.
+    const latest = d.reconciliation?.runs?.[0] ?? null;
+    return h('div', { class: 'card' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: 'Where this stands' }), h('span', { class: `pill ${status.pill}`, text: claimState })), h('p', { text: () => (isPrecise() ? status.precise : status.plain) }), d.claimSupport?.note ? h('p', { class: 'basis', text: d.claimSupport.note }) : null, latest
+        ? h('div', null, h('p', { class: residualBoundIsError(latest.result.offPathBound) ? 'drawer-error' : 'basis',
+            text: () => residualBoundWords(latest.result.offPathBound, isPrecise()) }), h('span', { class: 'basis', text: () => `provider side: ${basisWords(latest.result.providerSourceKind)} · last run ${relative(latest.computedAtMs)}` }), latest.result.snapshotStability === 'changed_across_observations'
+            ? h('span', { class: 'drawer-error', text: () => (isPrecise()
+                    ? `snapshot stability: changed across observations on ${(latest.result.unstableDayStartMs ?? []).length} day(s); this reconciliation is contradicted, not established`
+                    : 'Careful: the provider reported different figures for the same days at different times. This check disagrees with itself.') })
+            : null)
+        : h('span', { class: 'basis', text: () => `${count(d.summary.recordCount)} provider line(s) held · no comparison recorded yet` }));
+}
+/**
+ * What is declared now, and a way to stop it. Clearing previews first, like
+ * every write here, and says what it leaves alone: requests already recorded
+ * keep their scope and recorded comparisons stay as they were.
+ */
+function declaredScope(d, reload, say) {
+    const s = d.activeScope;
+    const preview = signal(null);
+    const project = s.providerProjectRef ?? 'no project id';
+    return h('div', { class: 'facts declared-scope' }, h('div', { class: 'fact fact-stack' }, h('div', { class: 'fact-line' }, h('span', { class: 'fact-key' }, h('span', { text: `${s.billingAccountRef} · ${project}` }), h('span', { class: 'fact-sub', text: `declared ${relative(s.declaredAtMs)} · your statement, not verified by the provider` })), h('span', { class: 'fact-val' }, h('button', { class: 'link-btn', type: 'button', text: 'Stop matching',
+        'aria-label': `Stop matching requests to ${project}`,
+        onclick: async () => {
+            try {
+                const r = await api.write.billing({ op: 'scope-clear' });
+                preview.set(r.message ?? '');
+            }
+            catch (e) {
+                say(false, errorText(e));
+            }
+        } }))), () => {
+        const message = preview();
+        if (message === null)
+            return null;
+        return h('div', { class: 'run-result' }, h('p', { class: 'basis', text: message }), h('div', { class: 'form-actions' }, d.demo
+            ? h('p', { class: 'drawer-muted', text: 'Sample data: the declaration cannot be cleared here.' })
+            : h('button', { class: 'btn-commit', type: 'button', text: 'Clear the declaration', onclick: async () => {
+                    try {
+                        const r = await api.write.billing({ op: 'scope-clear', apply: true });
+                        say(true, r.message ?? 'Cleared.');
+                        reload();
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                } }), h('button', { class: 'btn-ghost', type: 'button', text: 'Keep it', onclick: () => preview.set(null) })));
+    }));
+}
+function scopeForm(demo, reload, say, scopeDone) {
+    const account = signal('');
+    const project = signal('');
+    const checked = signal(null);
+    const body = () => ({ op: 'scope', accountRef: account().trim(), ...(project().trim() ? { projectRef: project().trim() } : {}) });
+    return h('form', {
+        class: 'inline-form',
+        onsubmit: async (event) => {
+            event.preventDefault();
+            try {
+                const r = await api.write.billing(body());
+                checked.set(r.scopePreview ?? {});
+            }
+            catch (e) {
+                checked.set(null);
+                say(false, errorText(e));
+            }
+        },
+    }, scopeDone ? h('p', { class: 'form-hint', text: 'A project is declared. Declaring another replaces it for future traffic.' }) : null, h('div', { class: 'form-row' }, field('scope-account', 'Organisation id', h('input', { id: 'scope-account', class: 'drawer-input', required: true, placeholder: 'org_…', autocomplete: 'off', spellcheck: 'false',
+        oninput: (e) => { account.set(e.target.value); checked.set(null); } })), field('scope-project', 'Project id', h('input', { id: 'scope-project', class: 'drawer-input', required: true, placeholder: 'proj_…', autocomplete: 'off', spellcheck: 'false',
+        oninput: (e) => { project.set(e.target.value); checked.set(null); } })), h('button', { class: 'btn-ghost', type: 'submit', text: 'Check' })), () => {
+        if (!checked())
+            return null;
+        return h('div', { class: 'run-result' }, rows([
+            ['Organisation', account().trim()],
+            ['Project', project().trim()],
+            ['Applies to', 'OpenAI requests that go through Segreant from now on'],
+            ['Past and imported spend', 'unchanged; it cannot be matched to the bill'],
+        ]), h('div', { class: 'form-actions' }, demo
+            ? h('p', { class: 'drawer-muted', text: 'Sample data: a project cannot be declared here.' })
+            : h('button', { class: 'btn-commit', type: 'button', text: 'Declare this project', onclick: async () => {
+                    try {
+                        const r = await api.write.billing({ ...body(), apply: true });
+                        say(true, isPrecise() ? r.message ?? 'Declared.' : 'Project declared for future OpenAI requests through Segreant. Past and imported spend is unchanged; the provider has not verified this declaration.');
+                        reload();
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                } })));
+    });
+}
+function importForm(demo, reload, say) {
+    const chosen = signal(null);
+    const preview = signal(null);
+    const busy = signal(false);
+    return h('div', { class: 'inline-form' }, h('div', { class: 'form-row' }, field('import-file', 'Cost export (.json)', h('input', {
+        id: 'import-file', class: 'drawer-input', type: 'file', accept: '.json,application/json',
+        onchange: async (e) => {
+            const file = e.target.files?.[0];
+            preview.set(null);
+            if (!file) {
+                chosen.set(null);
+                return;
+            }
+            busy.set(true);
+            try {
+                const picked = { name: file.name, base64: await fileBase64(file) };
+                chosen.set(picked);
+                const r = await api.write.billing({ op: 'import', fileName: picked.name, contentBase64: picked.base64 });
+                preview.set(r.preview ?? null);
+            }
+            catch (err) {
+                say(false, errorText(err));
+            }
+            finally {
+                busy.set(false);
+            }
+        },
+    }))), h('p', { class: 'form-hint', text: () => (busy() ? 'Reading the file…' : 'The file is checked here first. Nothing is saved until you import it.') }), () => {
+        const p = preview();
+        const c = chosen();
+        if (!p || !c)
+            return null;
+        const charges = Object.entries(p.byChargeType).map(([k, n]) => `${count(n)} ${k.replace(/_/g, ' ')}`).join(', ');
+        return h('div', { class: 'run-result' }, rows([
+            ['File', p.fileName],
+            ['Period', dayRange(p.source.periodStartMs, p.source.periodEndMs)],
+            ['Lines', `${count(p.recordsSeen)}${charges ? ` (${charges})` : ''}`],
+            ['Provider total', usdFromMicros(p.providerReportedUsdMicros)],
+            ['Complete?', p.source.coverage === 'complete' ? 'the export says it is complete (not verified)' : `the export says: ${p.source.coverage}`],
+        ]), h('div', { class: 'form-actions' }, demo
+            ? h('p', { class: 'drawer-muted', text: 'Sample data: an export cannot be imported here.' })
+            : h('button', { class: 'btn-commit', type: 'button', text: () => `Import ${count(p.recordsSeen)} line${p.recordsSeen === 1 ? '' : 's'}`, onclick: async () => {
+                    try {
+                        const r = await api.write.billing({ op: 'import', fileName: c.name, contentBase64: c.base64, apply: true });
+                        const inserted = typeof r.run?.recordsInserted === 'number' ? r.run.recordsInserted : p.recordsSeen;
+                        say(true, r.duplicateFile
+                            ? 'This file was already imported. Nothing new was written.'
+                            : `Imported ${count(inserted)} line${inserted === 1 ? '' : 's'}. They are kept as the provider's figures, apart from our own measurement. Next: use this export for the comparison.`);
+                        reload();
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                } })));
+    });
+}
+function importList(d, reload, say, scopeDone) {
+    const imports = d.imports ?? [];
+    if (imports.length === 0)
+        return null;
+    return h('div', { class: 'facts' }, ...imports.slice(0, 6).map((imp) => adoptRow(imp, d.demo, reload, say, scopeDone)));
+}
+function adoptRow(imp, demo, reload, say, scopeDone) {
+    const plan = signal(null);
+    return h('div', { class: 'fact fact-stack' }, h('div', { class: 'fact-line' }, h('span', { class: 'fact-key' }, h('span', { text: imp.fileName }), h('span', { class: 'fact-sub', text: `${dayRange(imp.periodStartMs, imp.periodEndMs)} · ${count(imp.recordsSeen)} lines · imported ${relative(imp.importedAtMs)}` })), h('span', { class: 'fact-val' }, imp.inUse
+        ? h('span', { class: 'in-use', text: `in use · adopted ${relative(imp.inUse.adoptedAtMs)}` })
+        : scopeDone
+            ? h('button', { class: 'link-btn', type: 'button', text: 'Use for the comparison', 'aria-label': `Use ${imp.fileName} for the comparison`, onclick: async () => {
+                    try {
+                        const r = await api.write.billing({ op: 'adopt', importId: imp.importId });
+                        plan.set(r.plan ?? null);
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                } })
+            : h('span', { text: 'declare the project first' }))), () => {
+        const p = plan();
+        if (!p)
+            return null;
+        if (!p.adoptable)
+            return h('p', { class: 'drawer-error', text: p.detail ?? p.refusal ?? 'This export cannot be used.' });
+        const left = p.excluded && p.excluded.otherOrNoProjectRecordCount > 0
+            ? `${count(p.excluded.otherOrNoProjectRecordCount)} line(s), ${usdFromMicros(p.excluded.otherOrNoProjectMicros)}, belong to no project or another one and are left out`
+            : 'none';
+        return h('div', { class: 'run-result' }, rows([
+            ['Matched to your project', `${count(p.matchedRecordCount)} line(s), ${usdFromMicros(p.matchedMicros)}`],
+            ['Left out', left],
+            ['Days', dayRange(p.periodStartMs, p.periodEndMs)],
+            ['Evidence class', 'supplied by you, not read from the provider; every comparison built on it says so'],
+        ]), h('div', { class: 'form-actions' }, demo
+            ? h('p', { class: 'drawer-muted', text: 'Sample data: nothing can be recorded here.' })
+            : h('button', { class: 'btn-commit', type: 'button', text: 'Use this export', onclick: async () => {
+                    try {
+                        await api.write.billing({ op: 'adopt', importId: imp.importId, apply: true });
+                        say(true, 'Recorded as the provider side for these days.');
+                        reload();
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                } })));
+    });
+}
+/**
+ * Every recorded comparison the server sends, newest first, each with its own
+ * days. A run is evidence for its own period only, so the list never sums
+ * them; opening one shows what was recorded, not a recomputation.
+ */
+function recordedComparisons(d) {
+    const runs = d.reconciliation?.runs ?? [];
+    if (runs.length === 0)
+        return null;
+    return h('section', { class: 'section recorded-runs' }, h('h3', { class: 'section-title', text: () => (isPrecise() ? 'Recorded reconciliations' : 'Recorded comparisons') }), h('div', { class: 'facts' }, ...runs.map((run) => {
+        const r = run.result;
+        const days = dayRange(r.periodStartMs, r.periodEndMs);
+        return h('details', { class: 'fact fact-stack recorded-run' }, h('summary', null, h('span', { class: 'fact-line' }, h('span', { class: 'fact-key' }, h('span', { text: days }), h('span', { class: 'fact-sub', text: `${r.providerProjectRef ? `${r.providerProjectRef} · ` : ''}recorded ${relative(run.computedAtMs)}` })), h('span', { class: 'fact-val', text: r.unexplainedVarianceMicros === undefined ? '—' : `${usdFromMicros(r.unexplainedVarianceMicros)} not explained` }))), rows([
+            ['Billed by the provider', r.providerReportedMicros === undefined ? '—' : usdFromMicros(r.providerReportedMicros)],
+            ['Measured by Segreant', r.localCapturedMicros === undefined ? '—' : usdFromMicros(r.localCapturedMicros)],
+            ['Not explained', r.unexplainedVarianceMicros === undefined ? '—' : usdFromMicros(r.unexplainedVarianceMicros)],
+            ['Days compared', r.coverage ? `${count(r.coverage.daysWithBoth)} with both · ${count(r.coverage.providerOnlyDays)} bill only · ${count(r.coverage.localOnlyDays)} ours only` : '—'],
+            ['Days that differ', r.coverage && r.materialityUsd !== undefined ? `${count(r.coverage.materialDays)} by more than ${usd(r.materialityUsd)}` : '—'],
+            ['Provider side', basisWords(r.providerSourceKind)],
+        ]), h('p', { class: residualBoundIsError(r.offPathBound) ? 'drawer-error' : 'basis', text: () => residualBoundWords(r.offPathBound, isPrecise()) }), () => { const q = quantizationWords(r.localQuantization, isPrecise()); return q ? h('p', { class: 'basis', text: q }) : null; }, r.snapshotStability === 'changed_across_observations'
+            ? h('p', { class: 'drawer-error', text: 'The provider reported different figures for the same days at different times. This comparison is contradicted.' })
+            : null);
+    })));
+}
+function reconcilePanel(d, reload, say) {
+    const result = signal(null);
+    const busy = signal(false);
+    // Blank means the server's default. The value previewed is the value
+    // recorded: changing it clears the preview, so a run is never recorded under
+    // a threshold nobody looked at.
+    const materiality = signal('');
+    const materialityUsd = () => {
+        const raw = materiality().trim();
+        return raw === '' ? undefined : Number(raw);
+    };
+    const remaining = (d.readiness?.missing ?? []).filter((m) => !m.step.startsWith('observe a closed period — route A'));
+    const run = async (apply) => {
+        busy.set(true);
+        try {
+            const m = materialityUsd();
+            const r = await api.write.billing({ op: 'reconcile', ...(m === undefined ? {} : { materialityUsd: m }), ...(apply ? { apply: true } : {}) });
+            if (apply) {
+                result.set(null);
+                say(true, 'Recorded. The comparison is saved, and the Billed claim above now rests on it.');
+                reload();
+            }
+            else
+                result.set(r.result ?? null);
+        }
+        catch (e) {
+            say(false, errorText(e));
+        }
+        finally {
+            busy.set(false);
+        }
+    };
+    if (d.readiness && !d.readiness.ready) {
+        return h('div', { class: 'run-panel' }, h('p', { class: 'drawer-muted', text: 'Not ready to compare. Still to do:' }), h('ul', { class: 'drawer-notes' }, ...remaining.map((m) => h('li', { text: m.step.replace(/^observe a closed period — route B, /, '') }))));
+    }
+    return h('div', { class: 'run-panel' }, h('div', { class: 'form-row run-row' }, field('reconcile-materiality', 'Ignore daily differences up to ($)', h('input', {
+        id: 'reconcile-materiality', class: 'drawer-input', type: 'number', min: '0', step: '0.01', inputmode: 'decimal',
+        placeholder: '0.50', 'aria-describedby': 'reconcile-materiality-hint',
+        oninput: (e) => { materiality.set(e.target.value); result.set(null); },
+    })), h('button', { class: 'btn-ghost', type: 'button', disabled: () => busy(), text: () => (busy() ? 'Working…' : 'Preview the comparison'), onclick: () => void run(false) })), h('p', { id: 'reconcile-materiality-hint', class: 'form-hint', text: 'A day counts as different only when the bill and our measurement differ by more than this. Blank uses $0.50.' }), () => {
+        const r = result();
+        if (!r)
+            return null;
+        const residual = r.unexplainedVarianceMicros;
+        return h('div', { class: 'run-result' }, rows([
+            ['Period', dayRange(r.periodStartMs, r.periodEndMs)],
+            ['Billed by the provider', usdFromMicros(r.providerReportedMicros)],
+            ['Measured by Segreant', usdFromMicros(r.localCapturedMicros)],
+            ['Not explained', `${usdFromMicros(residual)}${r.providerReportedMicros > 0 ? ` (${pct(residual / r.providerReportedMicros)} of the bill)` : ''}`],
+            ['Days compared', `${count(r.coverage.daysWithBoth)} with both · ${count(r.coverage.providerOnlyDays)} bill only · ${count(r.coverage.localOnlyDays)} ours only`],
+            ['Days that differ', `${count(r.coverage.materialDays)} by more than ${usd(r.materialityUsd)}`],
+            ['Provider side', basisWords(r.providerSourceKind)],
+        ]), h('p', { class: residualBoundIsError(r.offPathBound) ? 'drawer-error' : 'basis', text: () => residualBoundWords(r.offPathBound, isPrecise()) }), r.snapshotStability === 'changed_across_observations'
+            ? h('p', { class: 'drawer-error', text: 'The provider reported different figures for the same days at different times. This comparison would be contradicted.' })
+            : null, r.conditions.length > 0
+            ? h('ul', { class: 'drawer-notes' }, ...r.conditions.map((c) => h('li', { text: c.replace(/_/g, ' ') })))
+            : null, h('div', { class: 'form-actions' }, d.demo
+            ? h('p', { class: 'drawer-muted', text: 'Sample data: a comparison cannot be recorded here.' })
+            : h('button', { class: 'btn-commit', type: 'button', disabled: () => busy(), text: 'Record this comparison', onclick: () => void run(true) })));
     });
 }

package/dist/dashboard/web/app/views/privacy.js

@@ -0,0 +1,13 @@
+/**
+ * Privacy — the statement, read from this machine like every other page, so it
+ * is there with no network and says the same as docs/PRIVACY.md.
+ */
+import { h } from '../core/dom.js';
+import { PRIVACY_TITLE, PRIVACY_LEAD, PRIVACY_SECTIONS } from '../core/privacyText.js';
+/** Text with `backtick` spans as code. Built as nodes: no string is parsed as HTML. */
+function prose(text) {
+    return text.split('`').map((part, i) => (i % 2 === 1 ? h('code', { class: 'inline-code', text: part }) : document.createTextNode(part)));
+}
+export function privacyView() {
+    return h('div', { class: 'privacy' }, h('div', { class: 'view-head' }, h('h1', { class: 'view-title', text: PRIVACY_TITLE }), h('p', { class: 'privacy-lead' }, ...prose(PRIVACY_LEAD))), ...PRIVACY_SECTIONS.map((section) => h('section', { class: 'section privacy-section' }, h('h2', { class: 'section-title', text: section.heading }), ...section.paragraphs.map((p) => h('p', null, ...prose(p))), section.items ? h('ul', null, ...section.items.map((item) => h('li', null, ...prose(item)))) : null)));
+}

package/dist/dashboard/web/app/views/spend.js

@@ -10,17 +10,20 @@
 import { h } from '../core/dom.js';
 import { signal, scopedEffect, onCleanup } from '../core/signal.js';
 import { api, RANGES } from '../core/api.js';
-import { usd, count, pct, isPrecise, register } from '../core/fmt.js';
+import { period, setPeriod } from '../core/period.js';
+import { usd, count, isPrecise, register, share } from '../core/fmt.js';
 import { capability } from '../core/registry.js';
 import { openAction } from '../components/drawer.js';
 import { actionSpec, hasRunner } from '../core/actions.js';
+import { workbench } from './workbench.js';
 const AXES = [
     { id: 'project', label: 'Project', plain: 'which piece of work', precise: 'attribution label — basis varies by row' },
     { id: 'model', label: 'Model', plain: 'which AI model', precise: 'recorded model id' },
     { id: 'source', label: 'Source', plain: 'which tool', precise: 'acquisition route' },
 ];
 export function spendView() {
-    const range = signal('30d');
+    // The shared period (core/period.ts): choosing Today here moves the Metered claim above with it.
+    const range = period;
     const axis = signal('project');
     const data = signal(null);
     const error = signal(null);
@@ -50,10 +53,10 @@ export function spendView() {
             controller.abort();
         });
     });
-    return h('div', null, h('div', { class: 'view-head' }, h('div', { class: 'view-head-row' }, h('h1', { class: 'view-title', text: 'Metered' }), h('div', { class: 'rangebar', role: 'group', 'aria-label': 'Time range' }, ...RANGES.map((r) => h('button', {
+    return h('div', null, h('div', { class: 'view-head' }, h('div', { class: 'view-head-row' }, h('h1', { class: 'view-title', text: 'Spend' }), h('div', { class: 'rangebar', role: 'group', 'aria-label': 'Time range' }, ...RANGES.map((r) => h('button', {
         class: 'chip',
         'aria-pressed': () => (range() === r.id ? 'true' : 'false'),
-        onclick: () => range.set(r.id),
+        onclick: () => setPeriod(r.id),
         text: r.label,
         title: r.plain,
     })))), h('p', { class: 'view-plain', text: () => isPrecise()
@@ -65,8 +68,6 @@ export function spendView() {
         const d = data();
         if (!d)
             return h('div', { class: 'card' }, h('p', { class: 'drawer-muted', role: 'status', 'aria-live': 'polite', 'aria-busy': 'true', text: 'Reading the ledger…' }));
-        const rows = (axis() === 'project' ? d.byProject : axis() === 'model' ? d.byModel : d.bySource) ?? [];
-        const meta = AXES.find((a) => a.id === axis());
         // WHAT THE WINDOW LOST, BESIDE THE TOTAL IT LOST IT FROM (D-175). The
         // server's claim support already reports coverage `partial` and carries
         // the reason in its note, but that note lives in the Claim Inspector
@@ -78,9 +79,19 @@ export function spendView() {
         const lost = d.retention?.truncated === true ? d.retention : null;
         return h('div', null, d.demo ? demoBanner() : null, lost
             ? h('p', { class: 'drawer-error', role: 'status', text: () => (isPrecise()
-                    ? `retention deleted ${lost.rowsRemoved} request row(s) from before ${new Date(lost.prunedBeforeMs ?? 0).toISOString()}; this window covers what survived, not everything metered in it`
+                    ? `retention deleted ${lost.rowsRemoved} request row(s) from before ${typeof lost.prunedBeforeMs === 'number' && Number.isFinite(lost.prunedBeforeMs) && lost.prunedBeforeMs > 0 && lost.prunedBeforeMs <= 8.64e15 ? new Date(lost.prunedBeforeMs).toISOString() : 'unknown'}; this window covers what survived, not everything metered in it`
                     : 'Some requests in this range were deleted by your retention setting, so these totals cover what is left rather than everything we measured.') })
-            : null, h('div', { class: 'axisbar', role: 'group', 'aria-label': 'Break down by' }, h('span', { class: 'axisbar-label', text: 'Break down by' }), ...AXES.map((a) => h('button', {
+            : null);
+    }, 
+    // Its own read, outside the overview region, so an overview refresh does
+    // not throw away the session the reader has open.
+    workbench(), () => {
+        const d = data();
+        if (!d || error())
+            return null;
+        const rows = (axis() === 'project' ? d.byProject : axis() === 'model' ? d.byModel : d.bySource) ?? [];
+        const meta = AXES.find((a) => a.id === axis());
+        return h('section', { class: 'section' }, h('h2', { class: 'section-title', text: 'The whole range, broken down' }), h('div', { class: 'axisbar', role: 'group', 'aria-label': 'Break down by' }, h('span', { class: 'axisbar-label', text: 'Break down by' }), ...AXES.map((a) => h('button', {
             class: 'axis',
             'aria-pressed': () => (axis() === a.id ? 'true' : 'false'),
             onclick: () => axis.set(a.id),
@@ -89,25 +100,26 @@ export function spendView() {
     });
 }
 function demoBanner() {
-    return h('div', { class: 'banner banner-demo' }, h('span', { class: 'pill pill-demo', text: 'demo' }), h('p', null, h('strong', { text: 'Sample data. ' }), 'None of this was measured from your machine — import your real usage from Data to replace it.'));
+    return h('div', { class: 'banner banner-demo' }, h('span', { class: 'pill pill-demo', text: 'demo' }), h('p', null, h('strong', { text: 'Sample data. ' }), 'None of this was measured from your machine. To see your own usage, run the dashboard without --demo and import from Data.'));
 }
 /**
  * The breakdown, drawn as a ledger rather than a table of numbers: each row
  * carries its own proportion as a rule beneath it, so the shape of the spend is
- * legible before any figure is read. The bar is a proportion of the LARGEST row,
- * not of the total, because the question this answers is "what dominates".
+ * legible before any figure is read. The bar is the row's share of the TOTAL,
+ * the same number as the Share column beside it. It used to be scaled to the
+ * largest row, so a 57% row drew full width beside "57%" and readers took the
+ * bar and the column to disagree (critique 2026-10-12).
  */
 function ledger(rows, totalUsd) {
     if (rows.length === 0) {
         return h('div', { class: 'card' }, h('p', { class: 'drawer-muted', role: 'status', text: 'Nothing recorded in this window.' }));
     }
     const sorted = [...rows].sort((a, b) => b.costUsd - a.costUsd);
-    const max = sorted[0]?.costUsd ?? 0;
     const total = totalUsd > 0 ? totalUsd : sorted.reduce((s, r) => s + r.costUsd, 0);
-    return h('div', { class: 'ledger', role: 'table', 'aria-label': 'Metered spend breakdown' }, h('div', { class: 'ledger-head', role: 'row' }, h('span', { role: 'columnheader', text: 'Where it went' }), h('span', { class: 'num cell-calls', role: 'columnheader', text: () => (isPrecise() ? 'Requests' : 'Calls') }), h('span', { class: 'num cell-cost', role: 'columnheader', text: 'Cost' }), h('span', { class: 'num cell-share', role: 'columnheader', text: 'Share' })), ...sorted.map((row) => h('div', { class: 'ledger-row', role: 'row' }, h('span', { class: 'ledger-key', role: 'cell', text: row.label }), h('span', { class: 'num cell-calls', role: 'cell', text: count(row.requests) }), h('span', { class: 'num cell-cost ledger-cost', role: 'cell', text: usd(row.costUsd) }), h('span', { class: 'num cell-share', role: 'cell', text: total > 0 ? pct(row.costUsd / total, 0) : '—' }), h('span', {
+    return h('div', { class: 'ledger', role: 'table', 'aria-label': 'Metered spend breakdown' }, h('div', { class: 'ledger-head', role: 'row' }, h('span', { role: 'columnheader', text: 'Where it went' }), h('span', { class: 'num cell-calls', role: 'columnheader', text: () => (isPrecise() ? 'Requests' : 'Calls') }), h('span', { class: 'num cell-cost', role: 'columnheader', text: 'Cost' }), h('span', { class: 'num cell-share', role: 'columnheader', text: 'Share' })), ...sorted.map((row) => h('div', { class: 'ledger-row', role: 'row' }, h('span', { class: 'ledger-key', role: 'cell', text: row.label }), h('span', { class: 'num cell-calls', role: 'cell', text: count(row.requests) }), h('span', { class: 'num cell-cost ledger-cost', role: 'cell', text: usd(row.costUsd) }), h('span', { class: 'num cell-share', role: 'cell', text: total > 0 ? share(row.costUsd / total) : '—' }), h('span', {
         class: 'ledger-bar',
         'aria-hidden': 'true',
-        style: `--fill: ${max > 0 ? Math.max(0.5, (row.costUsd / max) * 100) : 0}%`,
+        style: `--fill: ${total > 0 ? Math.max(0.5, (row.costUsd / total) * 100) : 0}%`,
     }))));
 }
 /**
@@ -124,5 +136,8 @@ export function actionCard(id) {
         onclick: () => openAction(actionSpec(cap)),
     }, h('span', { class: 'action-label', text: cap.label }), h('span', { class: 'action-plain', text: cap.plain }), h('span', { class: 'action-meta' }, cap.consequence !== 'read'
         ? h('span', { class: `tag tag-${cap.consequence}`, text: cap.consequence })
-        : null, !hasRunner(cap) ? h('span', { class: 'tag tag-planned', text: 'CLI only' }) : null, () => (register() === 'precise' ? h('span', { class: 'tag', text: cap.command.replace(/^segreant /, '') }) : null)));
+        : null, 
+    // "CLI only" read as a dead end to a reader who never opens a terminal.
+    // The drawer still shows what this does and the exact command.
+    !hasRunner(cap) ? h('span', { class: 'tag tag-planned', text: () => (isPrecise() ? 'CLI only' : 'runs in the terminal for now') }) : null, () => (register() === 'precise' ? h('span', { class: 'tag', text: cap.command.replace(/^segreant /, '') }) : null)));
 }