segreant 0.1.0 → 0.2.0

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

@@ -1,24 +1,28 @@
 /**
- * Allocation — whose budget the money lands on, and what that number is not.
+ * Allocate — whose budget the money lands on, and what that number is not.
  *
  * Allocated cost is the third claim in the spine, and the one most often
  * mistaken for the first. It is a DERIVED split of local estimates: a rule said
  * this request belongs to that cost centre. It is not a provider bill, it is not
- * what anyone owes, and it is explicitly excluded from budget enforcement, RoI,
- * and model recommendations — because a showback split is not evidence about
- * value or about money actually charged.
+ * what anyone owes, and it is excluded from budget enforcement, RoI and model
+ * recommendations, because a showback split is not evidence about value or about
+ * money actually charged.
  *
- * So this view leads with the exclusions, not with a total. The payload states
- * its own basis (`showback_only`) and the list of things it must not feed; that
- * list is rendered as the first thing on the page rather than as a footnote,
- * because a reader who takes an allocation figure into a budget conversation has
- * already made the mistake the label exists to prevent.
+ * This page used to describe allocation and send you to the terminal to do it.
+ * It is now the job itself, in the order the engine needs it: cost centres, then
+ * rules, then a run. A run is previewed first and recorded only on a second,
+ * separate action, the GUI's form of the CLI's `--apply`. The basis and the
+ * exclusions stay at the top, in one strip, so the figure is never met without
+ * them.
  */
 import { h } from '../core/dom.js';
+import { slug } from '../core/slug.js';
+import { localMidnightIso, dayAfterIso, monthRange, REASON_WORDS } from '../core/periods.js';
 import { signal, scopedEffect } from '../core/signal.js';
 import { api } from '../core/api.js';
-import { isPrecise, relative, count } from '../core/fmt.js';
-import { actionCard } from './spend.js';
+import { isPrecise, relative, count, usdFromMicros, date, share as shareOf } from '../core/fmt.js';
+import { pageNotice, step, field, errorText, holdFocus } from '../components/workflow.js';
+import { ruleFields, describeRule } from '../components/ruleFields.js';
 /** The payload's `excludedFrom` ids, said in words an operator can act on. */
 const EXCLUSION_WORDS = {
     request_metered_spend: 'the metered spend figure',
@@ -29,62 +33,246 @@ const EXCLUSION_WORDS = {
 export function allocationView() {
     const data = signal(null);
     const error = signal(null);
+    const projects = signal([]);
+    const models = signal([]);
+    const reloads = signal(0);
+    const reload = () => reloads.set(reloads() + 1);
+    const { node: noticeNode, say } = pageNotice();
+    const reloadAll = () => {
+        reload();
+        // The spine above this page reads /api/allocation once. Without this it kept
+        // saying "no cost centres and no rules yet" under a page that had just saved both.
+        window.dispatchEvent(new CustomEvent('segreant:ledger-changed', { detail: { claim: 'allocation' } }));
+    };
     scopedEffect(() => {
+        reloads();
         void api.allocation()
-            .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: 'Allocated' }), h('p', { class: 'view-plain', text: () => isPrecise()
-            ? 'A derived split of locally estimated cost across cost centres, by recorded rule. Showback only — no settlement, no chargeback.'
-            : 'Which team or project each pound of AI spend gets attributed to. This is a split of our own estimate — not a bill, and not something anyone is charged.' })), () => {
+    // Project names to match on. A typo in a match makes a rule that claims
+    // nothing, and the run would only say "no rule claimed it" afterwards.
+    void api.overview('all')
+        .then((o) => {
+        projects.set(o.byProject.map((p) => p.label).filter((l) => l && l !== '(unattributed)'));
+        models.set([...new Set(o.byModel.map((m) => m.label).filter(Boolean))]);
+    })
+        .catch(() => { projects.set([]); models.set([]); });
+    const page = h('div', null, h('div', { class: 'view-head' }, h('h1', { class: 'view-title', text: 'Allocate' }), h('p', { class: 'view-plain', text: () => isPrecise()
+            ? 'A derived split of locally estimated cost across cost centres, by recorded rule. Showback only: no settlement, no chargeback.'
+            : 'Decide which team or budget each dollar of AI spend is attributed to. This splits our own estimate. It is not a bill, and nobody is charged.' })), 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…' }));
-        const centres = d.costCentres ?? [];
-        const rules = d.rules ?? [];
-        const runs = d.runs ?? [];
-        const configured = centres.length > 0 && rules.length > 0;
-        return h('div', null, 
-        // The exclusions come first, deliberately. See the module note above.
-        h('div', { class: 'card card-basis' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Basis and exclusions' : 'What this number is not') }), h('span', { class: 'pill pill-estimate', text: 'showback only' })), h('p', { text: () => (isPrecise()
-                ? 'kind: derived_cost_allocation · trust: derived_allocation_of_local_estimates'
-                : 'These figures are worked out by rules you wrote, applied to costs we estimated ourselves.') }), h('p', { class: 'excl-lede', text: () => (isPrecise() ? 'Deliberately excluded from:' : 'Segreant deliberately refuses to let this feed:') }), h('ul', { class: 'excl' }, ...(d.excludedFrom ?? []).map((id) => h('li', { text: EXCLUSION_WORDS[id] ?? id.replace(/_/g, ' ') }))), h('span', { class: 'basis', text: () => (isPrecise()
-                ? 'A showback split is not evidence of money charged, nor of value produced.'
-                : 'Splitting a cost does not make it a bill, and it does not prove the spend was worth it.') })), 
-        // The residual cross-reference. Allocation of a ledger nobody has checked
-        // against a provider bill is a confident split of an unverified total, and
-        // the operator should meet that fact here rather than infer it.
-        h('div', { class: 'card', style: 'margin-top: var(--s4)' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Underlying ledger' : 'What this is a split of') }), h('span', {
-            class: `pill ${d.reconciliation?.everRun ? 'pill-ok' : 'pill-unverified'}`,
-            text: d.reconciliation?.everRun ? 'checked' : 'unchecked',
-        })), d.reconciliation?.everRun
-            ? h('p', { text: () => (isPrecise()
-                    ? `The underlying ledger has been reconciled against provider billing; last run ${relative(d.reconciliation.latestComputedAtMs)}.`
-                    : `We have checked the underlying spend against a real provider bill — last time ${relative(d.reconciliation.latestComputedAtMs)}.`) })
-            : h('p', { text: () => (isPrecise()
-                    ? 'No reconciliation run recorded. Every figure below splits a total that has never been compared against provider billing, so the residual beneath it is unbounded.'
-                    : 'Nobody has checked the underlying spend against a real provider bill yet. The split below is exact arithmetic on a number we estimated ourselves.') })), configured
-            ? h('div', null, section(() => (isPrecise() ? 'Cost centres' : 'Who the money is attributed to'), h('div', { class: 'facts' }, ...centres.map((c) => h('div', { class: 'fact' }, h('span', { class: 'fact-key', text: c.label ?? c.name ?? c.id }), h('span', { class: 'fact-val', text: c.id }))))), section(() => (isPrecise() ? 'Allocation rules' : 'The rules that decide the split'), h('div', { class: 'facts' }, 
-            // A revoked rule is shown, not hidden: a past run was computed
-            // under it, and a reader comparing runs needs to see why the
-            // split changed rather than find a rule silently absent.
-            ...rules.map((r) => h('div', { class: `fact${r.revokedAtMs ? ' fact-off' : ''}` }, h('span', { class: 'fact-key', text: r.id }), h('span', { class: 'fact-val', text: r.revokedAtMs
-                    ? `revoked · was ${r.method} v${r.version}`
-                    : `${r.method} · v${r.version}` }))))), section(() => (isPrecise() ? 'Recorded runs' : 'Times this has been worked out'), runs.length > 0
-                ? h('p', { class: 'basis', text: () => (isPrecise()
-                        ? `${count(runs.length)} recorded run${runs.length === 1 ? '' : 's'}; each is a snapshot under the rule version in force at the time.`
-                        : `${count(runs.length)} saved result${runs.length === 1 ? '' : 's'}. Each one records the rules as they were on the day.`) })
-                : h('p', { class: 'drawer-muted', text: () => (isPrecise()
-                        ? 'Rules and centres exist, but no allocation run has been recorded.'
-                        : 'You have set the rules up, but never run the split.') })))
-            : h('div', { class: 'notyet', style: 'margin-top: var(--s5)' }, h('h2', { text: () => (isPrecise() ? 'No allocation model defined' : 'Nothing is being split yet') }), h('p', { text: () => (isPrecise()
-                    ? `${centres.length} cost centre${centres.length === 1 ? '' : 's'} and ${rules.length} rule${rules.length === 1 ? '' : 's'} recorded. Both are required before a run can produce a split.`
-                    : 'To split spend across teams or projects, Segreant needs at least one cost centre to attribute to, and one rule that decides what goes where.') })), section(() => (isPrecise() ? 'Actions on this layer' : 'Things you can do with this'), h('div', { class: 'actions' }, actionCard('alloc-centres'), actionCard('alloc-rules'), actionCard('alloc-run'), actionCard('project'))));
+            return h('div', { class: 'card' }, h('p', { class: 'drawer-muted', role: 'status', 'aria-busy': 'true', text: 'Loading…' }));
+        const open = d.costCentres.filter((c) => c.archivedAtMs == null);
+        // Any rule not revoked can claim spend in some period: a superseded version or
+        // one with an end date still governs the past it covered, which is exactly
+        // what a preview of an earlier period asks about.
+        const live = d.rules.filter((r) => r.revokedAtMs == null);
+        // People type names; the engine keys on ids. Show what they typed.
+        const names = new Map(d.costCentres.map((c) => [c.costCentreId, c.name]));
+        const nameOf = (id) => names.get(id) ?? id;
+        return h('div', null, basisStrip(d), d.demo
+            ? h('p', { class: 'section-note', role: 'note', text: 'This is sample data, so centres and rules cannot be saved here. You can still preview a run. Start Segreant without --demo to set up your own.' })
+            : null, step(1, () => (isPrecise() ? 'Cost centres' : 'Who carries the cost'), () => (isPrecise() ? 'Accounting positions that receive allocated spend.' : 'The teams, clients or budgets spend can be attributed to.'), centreList(d.costCentres, d.demo, reloadAll, say), d.demo ? null : centreForm(reloadAll, say)), step(2, () => (isPrecise() ? 'Rules' : 'What goes where'), () => (isPrecise() ? 'Priority-ordered; lower wins. Edits retain the old version and every recorded run. New previews follow effective dates.' : 'Each rule picks some spend and says which centre it belongs to. Changing a rule keeps old versions and recorded splits. A new preview follows the rule dates, so it can change an earlier period.'), ruleList(d.rules, d.demo, reloadAll, say, nameOf), d.demo ? null : open.length > 0
+            ? ruleForm(open, projects, models, reloadAll, say)
+            : h('p', { class: 'drawer-muted', text: 'Add a cost centre first. A rule needs somewhere to send spend.' })), step(3, () => (isPrecise() ? 'Run' : 'Work out the split'), () => (isPrecise() ? 'Preview computes; Record persists an immutable run.' : 'Preview the split for a month. Nothing is saved until you record it.'), live.length > 0 || d.demo
+            ? runPanel(d.demo, reloadAll, say, nameOf)
+            : h('p', { class: 'drawer-muted', text: 'Add a rule first. Without one, every dollar would show as unallocated.' })), history(d.runs));
     });
+    return page;
 }
-function section(title, ...body) {
-    return h('section', { class: 'section' }, h('h2', { class: 'section-title', text: title }), ...body);
+function basisStrip(d) {
+    const checked = d.reconciliation?.everRun;
+    return h('div', { class: 'card card-basis basis-strip' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Basis' : 'What this number is') }), h('span', { class: 'pill pill-estimate', text: 'showback only' }), h('span', { class: checked ? 'pill pill-unverified' : 'pill pill-empty', text: checked ? 'provider comparison on record' : 'no provider comparison on record' })), h('p', { text: () => (checked
+            ? `A split of our own cost estimate. A provider comparison is on record (${relative(d.reconciliation.latestComputedAtMs)}); it covers its own project and dates and does not verify the inputs to this allocation.`
+            : 'A split of our own cost estimate. No provider comparison is on record; this split is exact arithmetic on our estimate, not a verified bill.') }), h('p', { class: 'basis', text: () => `Never feeds ${(d.excludedFrom ?? []).map((id) => EXCLUSION_WORDS[id] ?? id.replace(/_/g, ' ')).join(', ')}.` }));
+}
+function centreList(centres, demo, reload, say) {
+    if (centres.length === 0)
+        return h('p', { class: 'drawer-muted', text: 'No cost centres yet.' });
+    return h('div', { class: 'facts' }, ...centres.map((c) => {
+        const archived = c.archivedAtMs != null;
+        return h('div', { class: `fact${archived ? ' fact-off' : ''}` }, h('span', { class: 'fact-key' }, h('span', { text: c.name }), c.owner ? h('span', { class: 'fact-sub', text: c.owner }) : null), h('span', { class: 'fact-val' }, h('span', { text: archived ? `archived · ${c.costCentreId}` : c.costCentreId }), !archived && !demo
+            ? h('button', {
+                class: 'link-btn',
+                'aria-label': `Archive ${c.name}`,
+                onclick: async () => {
+                    try {
+                        say(true, (await api.write.allocation({ op: 'archive', id: c.costCentreId })).message);
+                        reload();
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                },
+                text: 'Archive',
+            })
+            : null));
+    }));
+}
+function centreForm(reload, say) {
+    const name = signal('');
+    const owner = signal('');
+    const id = () => slug(name());
+    return h('form', {
+        class: 'inline-form',
+        onsubmit: async (event) => {
+            event.preventDefault();
+            if (!id())
+                return say(false, 'Give the cost centre a name with at least one letter or number.');
+            try {
+                const r = await api.write.allocation({ op: 'centre', id: id(), name: name().trim(), ...(owner().trim() ? { owner: owner().trim() } : {}) });
+                say(true, r.message);
+                name.set('');
+                owner.set('');
+                event.target.reset();
+                reload();
+            }
+            catch (e) {
+                say(false, errorText(e));
+            }
+        },
+    }, h('div', { class: 'form-row' }, field('centre-name', 'Name', h('input', { id: 'centre-name', class: 'drawer-input', required: true, maxlength: '120', placeholder: 'for example Engineering', autocomplete: 'off', oninput: (e) => name.set(e.target.value) })), field('centre-owner', 'Owner (optional)', h('input', { id: 'centre-owner', class: 'drawer-input', maxlength: '120', placeholder: 'who answers for it', autocomplete: 'off', oninput: (e) => owner.set(e.target.value) })), h('button', { class: 'btn-commit', type: 'submit', text: 'Add cost centre' })), h('p', { class: 'form-hint', text: () => (id() ? `Saved as "${id()}".` : '') }));
+}
+function ruleList(rules, demo, reload, say, nameOf) {
+    if (rules.length === 0)
+        return h('p', { class: 'drawer-muted', text: 'No rules yet.' });
+    return h('div', { class: 'facts' }, 
+    // A revoked or superseded version is shown, not hidden: a past run was
+    // computed under it, and a reader comparing runs needs to see why the split
+    // changed rather than find a rule silently absent.
+    ...rules.map((r) => {
+        // Superseded means a later version of the same rule exists. An end date the
+        // operator set is not supersession: `--until` and "Stops on" set it too, and
+        // calling those rules superseded misdescribed a rule that is still the
+        // current version.
+        const superseded = rules.some((o) => o.ruleId === r.ruleId && o.version > r.version);
+        const ended = !superseded && r.effectiveToMs != null && r.effectiveToMs <= Date.now();
+        const state = r.revokedAtMs != null ? 'revoked' : superseded ? 'superseded' : ended ? 'ended' : null;
+        const dates = [
+            r.effectiveFromMs > 0 ? `from ${date(r.effectiveFromMs)}` : '',
+            r.effectiveToMs != null && !superseded ? `${ended ? 'ended' : 'until'} ${date(r.effectiveToMs)}` : '',
+        ].filter(Boolean).join(' · ');
+        return h('div', { class: `fact${state ? ' fact-off' : ''}` }, h('span', { class: 'fact-key' }, h('span', { text: describeRule(r, nameOf) }), dates ? h('span', { class: 'fact-sub', text: dates }) : null), h('span', { class: 'fact-val' }, h('span', { text: `${r.ruleId} v${r.version}${state && state !== 'ended' ? ` · ${state}` : ` · p${r.priority}`}` }), !state && !demo
+            ? h('button', {
+                class: 'link-btn',
+                'aria-label': `Revoke rule ${r.ruleId}`,
+                onclick: async () => {
+                    try {
+                        say(true, (await api.write.allocation({ op: 'revoke', id: r.ruleId })).message);
+                        reload();
+                    }
+                    catch (e) {
+                        say(false, errorText(e));
+                    }
+                },
+                text: 'Revoke',
+            })
+            : null));
+    }));
+}
+function ruleForm(centres, projects, models, reload, say) {
+    const fields = ruleFields(centres, projects, models);
+    return h('form', {
+        class: 'inline-form',
+        onsubmit: async (event) => {
+            event.preventDefault();
+            const draft = fields.build();
+            if (typeof draft === 'string')
+                return say(false, draft);
+            try {
+                const r = await api.write.allocation(draft.body);
+                say(true, isPrecise() ? r.message : 'Rule saved. Recorded splits keep their results; preview again to see this rule\'s effect.');
+                reload();
+            }
+            catch (e) {
+                say(false, errorText(e));
+            }
+        },
+    }, ...fields.children, h('div', { class: 'form-actions' }, h('button', { class: 'btn-commit', type: 'submit', text: 'Save rule' })));
+}
+function runPanel(demo, reload, say, nameOf) {
+    const ranges = [monthRange(-1), monthRange(0)];
+    const CUSTOM = ranges.length;
+    const chosen = signal(0);
+    const customFrom = signal('');
+    const customThrough = signal('');
+    const preview = signal(null);
+    const busy = signal(false);
+    const run = async (apply) => {
+        let r;
+        if (chosen() === CUSTOM) {
+            if (!customFrom() || !customThrough())
+                return say(false, 'Choose both the first and the last day of the period.');
+            if (customThrough() < customFrom())
+                return say(false, 'The last day must not be before the first day.');
+            // Both days are included: the period ends at the local midnight after the last one.
+            r = { from: localMidnightIso(customFrom()), to: dayAfterIso(customThrough()) };
+        }
+        else
+            r = ranges[chosen()];
+        busy.set(true);
+        try {
+            const res = await api.write.allocation({ op: 'run', from: r.from, to: r.to, apply });
+            if (res.result)
+                preview.set(res.result);
+            // The preview panel is its own answer; a toast over it would cover the
+            // figures it announces. Only a write is confirmed.
+            if (apply)
+                say(true, 'Recorded. The split is saved and listed under Saved splits.');
+            if (apply) {
+                preview.set(null);
+                reload();
+            }
+        }
+        catch (e) {
+            say(false, errorText(e));
+        }
+        finally {
+            busy.set(false);
+        }
+    };
+    return h('div', { class: 'run-panel' }, h('div', { class: 'form-row run-row' }, field('run-period', 'Period', h('select', {
+        id: 'run-period', class: 'drawer-input',
+        onchange: (e) => { chosen.set(Number(e.target.value)); preview.set(null); },
+    }, ...ranges.map((r, i) => h('option', { value: String(i), text: r.label })), h('option', { value: String(CUSTOM), text: 'Choose dates…' }))), () => chosen() === CUSTOM
+        ? h('div', { class: 'form-row run-dates' }, field('run-from', 'First day', h('input', { id: 'run-from', class: 'drawer-input', type: 'date',
+            oninput: (e) => { customFrom.set(e.target.value); preview.set(null); } })), field('run-through', 'Last day', h('input', { id: 'run-through', class: 'drawer-input', type: 'date',
+            oninput: (e) => { customThrough.set(e.target.value); preview.set(null); } })))
+        : null, h('button', { class: 'btn-ghost', disabled: () => busy(), onclick: () => void run(false), text: () => (busy() ? 'Working…' : 'Preview split') })), () => {
+        const p = preview();
+        if (!p)
+            return null;
+        return h('div', { class: 'run-result' }, runTable(p, nameOf), p.retention?.truncated
+            ? h('p', { class: 'section-note', role: 'note', text: 'Some records in this period were deleted by retention. The split covers what remains, so the unallocated part may be understated.' })
+            : null, h('div', { class: 'form-actions' }, demo
+            ? h('p', { class: 'drawer-muted', text: 'Sample data: a run cannot be recorded here.' })
+            : h('button', { class: 'btn-commit', disabled: () => busy(), onclick: () => void run(true), text: 'Record this run' })));
+    });
+}
+function runTable(p, nameOf) {
+    const share = (m) => (p.totalMicros > 0 ? shareOf(m / p.totalMicros, 1) : '—');
+    return h('div', { class: 'table-wrap' }, h('table', null, h('caption', { class: 'sr-only', text: 'Allocation preview by cost centre' }), h('thead', null, h('tr', null, h('th', { text: 'Cost centre' }), h('th', { class: 'num', text: 'Amount' }), h('th', { class: 'num', text: 'Share' }), h('th', { class: 'num', text: 'Requests' }))), h('tbody', null, ...p.byCostCentre.map((c) => h('tr', null, h('td', { class: 'name-cell', text: nameOf(c.costCentreId) }), h('td', { class: 'num', text: usdFromMicros(c.allocatedMicros) }), h('td', { class: 'num', text: share(c.allocatedMicros) }), h('td', { class: 'num', text: count(c.requestCount) }))), ...p.unallocated.map((u) => h('tr', { class: 'row-unalloc' }, h('td', { class: 'name-cell' }, h('span', { text: `Unallocated: ${REASON_WORDS[u.reason] ?? u.reason.replace(/_/g, ' ')}` }), u.topProjects.length > 0
+        ? h('span', { class: 'fact-sub', text: `mostly ${u.topProjects.slice(0, 3).map((t) => t.project).join(', ')}` })
+        : null), h('td', { class: 'num', text: usdFromMicros(u.micros) }), h('td', { class: 'num', text: share(u.micros) }), h('td', { class: 'num', text: count(u.requestCount) })))), h('tfoot', null, h('tr', null, h('td', { text: 'Total estimated spend' }), h('td', { class: 'num', text: usdFromMicros(p.totalMicros) }), h('td', { class: 'num', text: p.totalMicros > 0 ? '100%' : '—' }), h('td', null)))));
+}
+function history(runs) {
+    return h('section', { class: 'section' }, h('h2', { class: 'section-title', text: () => (isPrecise() ? 'Recorded runs' : 'Saved splits') }), runs.length === 0
+        ? h('p', { class: 'drawer-muted', text: 'None recorded yet.' })
+        : h('div', { class: 'table-wrap' }, h('table', null, h('thead', null, h('tr', null, h('th', { text: 'Period' }), h('th', { class: 'num', text: 'Total' }), h('th', { class: 'num', text: 'Allocated' }), h('th', { text: 'Recorded' }))), h('tbody', null, ...runs.map((r) => {
+            const period = `${date(r.result.periodStartMs)} – ${date(r.result.periodEndMs)}`;
+            return h('tr', null, 
+            // The download sits with the run it names rather than in a
+            // column of its own, which pushed the table past a phone screen.
+            // It is the recorded run exactly as stored: every line and
+            // unallocated reason, adding up to the total to the microdollar.
+            h('td', null, h('span', { class: 'run-period', text: period }), h('a', {
+                class: 'run-download', href: api.allocationRunCsvHref(r.allocationRunId), download: '',
+                'aria-label': `Download the split for ${period} as CSV`, text: 'Export CSV',
+            })), h('td', { class: 'num', text: usdFromMicros(r.result.totalMicros) }), h('td', { class: 'num', text: r.result.totalMicros > 0 ? shareOf(r.result.allocatedMicros / r.result.totalMicros, 1) : '—' }), h('td', { text: relative(r.computedAtMs) }));
+        })))));
 }

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

@@ -32,6 +32,9 @@ import { signal, scopedEffect } from '../core/signal.js';
 import { api } from '../core/api.js';
 import { usd, count, pct, isPrecise } from '../core/fmt.js';
 import { actionCard } from './spend.js';
+import { capability } from '../core/registry.js';
+import { openAction } from '../components/drawer.js';
+import { actionSpec } from '../core/actions.js';
 export function controlView() {
     const settings = signal(null);
     const today = signal(null);
@@ -51,7 +54,7 @@ export function controlView() {
             }
         });
     });
-    return h('div', null, h('div', { class: 'view-head' }, h('h1', { class: 'view-title', text: 'Control' }), h('p', { class: 'view-plain', text: () => isPrecise()
+    return h('div', null, h('div', { class: 'view-head' }, h('h1', { class: 'view-title', text: 'Protect' }), h('p', { class: 'view-plain', text: () => isPrecise()
             ? 'Enforcement caps applied at the proxy, and the advisory recommendation derived from observed spend.'
             : 'The limits that stop AI spend before it happens — and how much of your spend they can actually reach.' })), () => {
         const err = error();
@@ -82,9 +85,16 @@ export function controlView() {
         // Live governance alerts, above the caps that produced them. The server
         // already computed these; until now no screen rendered them, so an
         // operator whose cap was exhausted had to infer it from a percentage.
-        alerts.length > 0 ? alertList(alerts) : null, h('div', { class: 'card card-basis' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Daily cap' : 'Your daily limit') }), h('span', {
-            class: `pill ${cap === null ? 'pill-unverified' : 'pill-ok'}`,
-            text: cap === null ? 'unlimited' : 'enforced in path',
+        alerts.length > 0 ? alertList(alerts) : null, h('div', { class: 'card card-basis' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Daily cap' : 'Your daily limit') }), 
+        // The action that changes this number sits on it. It was a card at
+        // the foot of a 2,200 px page (critique 2026-10-12).
+        budgetButton(), 
+        // Green "enforced" over a day already past its limit read as a
+        // contradiction (critique 2026-10-12). Past the limit, the badge
+        // says what the proxy is doing now.
+        h('span', {
+            class: `pill ${cap === null ? 'pill-unverified' : spentToday !== null && spentToday >= cap ? 'pill-warn' : 'pill-ok'}`,
+            text: cap === null ? 'unlimited' : spentToday !== null && spentToday >= cap ? 'limit reached · blocking' : 'enforced in path',
         })), cap === null
             ? h('div', null, h('div', { class: 'stat band-unset', text: 'no cap set' }), h('span', { class: 'basis', text: () => (isPrecise()
                     ? 'No daily cap is configured. Requests are never blocked on spend.'
@@ -95,7 +105,11 @@ export function controlView() {
                     style: `--fill: ${Math.min(100, cap > 0 ? (spentToday / cap) * 100 : 0)}%`,
                 })), h('span', { class: 'basis', text: () => (isPrecise()
                         ? `${usd(spentToday)} counted toward the cap today — ${pct(cap > 0 ? spentToday / cap : 0, 0)} of the cap`
-                        : `${usd(spentToday)} spent today, which is ${pct(cap > 0 ? spentToday / cap : 0, 0)} of your limit`) }), importedOutsideCap > 0
+                        : `${usd(spentToday)} spent today, which is ${pct(cap > 0 ? spentToday / cap : 0, 0)} of your limit`) }), spentToday >= cap
+                    ? h('span', { class: 'basis', text: () => (isPrecise()
+                            ? 'The guard blocks once the day\'s enforced total is at or over the cap. The request that crossed it and any already in flight complete, so a day can close above the cap.'
+                            : 'A limit stops new requests once the day\'s total reaches it. The request that crossed it, and any already running, still finish, so a day can end above its limit.') })
+                    : null, importedOutsideCap > 0
                     ? h('span', { class: 'basis', text: () => (isPrecise()
                             ? `${usd(importedOutsideCap)} imported today is excluded from the cap (it cannot be blocked).`
                             : `Plus ${usd(importedOutsideCap)} imported from your tools' logs today, which the limit doesn't count because it can't be stopped.`) })
@@ -164,6 +178,16 @@ function alertCoveragePanel(coverage, alertCount) {
  * with the figure that triggered it rather than as a bare warning. A warning an
  * operator cannot check is a warning they learn to dismiss.
  */
+function budgetButton() {
+    const cap = capability('budget');
+    if (!cap)
+        return null;
+    return h('button', {
+        class: 'btn-ghost card-action',
+        onclick: () => openAction(actionSpec(cap)),
+        text: () => (isPrecise() ? 'Set cap' : 'Change limit'),
+    });
+}
 function alertList(alerts) {
     const order = { critical: 0, warn: 1, info: 2 };
     const sorted = [...alerts].sort((a, b) => (order[a.severity] ?? 3) - (order[b.severity] ?? 3));
@@ -175,34 +199,51 @@ function alertList(alerts) {
  * from one recommended from a month of it, and the difference must be visible
  * before anyone acts on it.
  */
+/** A note that ends in a command ("...with: segreant budget --x on") shows it as code that does not wrap mid-flag. */
+function noteWithCommand(note) {
+    const at = note.lastIndexOf(': segreant ');
+    if (at < 0)
+        return h('li', { text: note });
+    return h('li', {}, note.slice(0, at + 2), h('code', { class: 'inline-code', text: note.slice(at + 2) }));
+}
 function recommendation(rec, currentCap) {
     const ready = rec.canApply === true;
     const value = rec.recommendedDailyUsd ?? null;
+    // Zero days on a proxy-only basis is not thin history: nothing the cap
+    // governs has run yet, whatever was imported. The rationale below says why.
+    const noProxied = rec.basisDays === 0 && rec.spendBasis === 'live_proxy';
     return h('div', { class: 'card', style: 'margin-top: var(--s4)' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Recommended cap' : 'What we would suggest') }), h('span', {
         class: `pill ${ready ? 'pill-ok' : 'pill-unverified'}`,
-        text: ready ? 'enough data' : 'not enough data',
+        text: ready ? 'enough data' : noProxied ? 'no proxied spend' : 'not enough data',
     })), value !== null
         ? h('div', { class: 'stat', text: usd(value) })
         : h('div', { class: 'stat band-unset', text: 'not established' }), h('span', { class: 'basis', text: () => (isPrecise()
             ? `derived from ${count(rec.basisDays)} day(s) of observed spend on a ${rec.spendBasis === 'live_proxy' ? 'live proxy' : 'all observed'} basis; minimum ${count(rec.minActiveDays)} active days`
-            : `worked out from ${count(rec.basisDays)} days of your actual spend`) }), !ready
+            : `worked out from ${count(rec.basisDays)} days of your actual spend`) }), !ready && noProxied
         ? h('p', { class: 'scope-note', text: () => (isPrecise()
-                ? 'Status is not review-ready: too few active days stand behind this to recommend acting on it.'
-                : 'There is not enough history yet for this to be a suggestion worth acting on.') })
-        : currentCap !== null && value !== null && Math.abs(currentCap - value) < 0.005
+                ? 'No proxied spend in this window: a cap governs requests through the proxy, and none have run.'
+                : 'Nothing has gone through the proxy yet, and that is the spend a limit controls.') })
+        : !ready
             ? h('p', { class: 'scope-note', text: () => (isPrecise()
-                    ? 'Your configured cap already matches this recommendation.'
-                    : 'Your current limit already matches this.') })
-            : null, rec.observed
+                    ? 'Status is not review-ready: too few active days stand behind this to recommend acting on it.'
+                    : 'There is not enough history yet for this to be a suggestion worth acting on.') })
+            : currentCap !== null && value !== null && Math.abs(currentCap - value) < 0.005
+                ? h('p', { class: 'scope-note', text: () => (isPrecise()
+                        ? 'Your configured cap already matches this recommendation.'
+                        : 'Your current limit already matches this.') })
+                : null, 
+    // With no basis day there is no typical, busy or worst day: zeros here
+    // would read as measured. The rationale says why instead.
+    rec.observed && (rec.basisDays ?? 0) > 0
         ? h('div', { class: 'facts' }, h('div', { class: 'fact' }, h('span', { class: 'fact-key', text: () => (isPrecise() ? 'median daily' : 'a typical day') }), h('span', { class: 'fact-val', text: usd(rec.observed.medianDaily) })), h('div', { class: 'fact' }, h('span', { class: 'fact-key', text: () => (isPrecise() ? 'p90 daily' : 'a busy day') }), h('span', { class: 'fact-val', text: usd(rec.observed.p90Daily) })), h('div', { class: 'fact' }, h('span', { class: 'fact-key', text: () => (isPrecise() ? 'max daily' : 'the worst day seen') }), h('span', { class: 'fact-val', text: usd(rec.observed.maxDaily) })))
         : null, 
     // Projected waste is the number worth acting on, so it is not buried in the
     // rationale list. It is explicitly a projection, and says so.
     typeof rec.projectedMonthlyWasteUsd === 'number' && rec.projectedMonthlyWasteUsd > 0
         ? h('div', { class: 'waste-call' }, h('span', { class: 'waste-fig', text: `${usd(rec.projectedMonthlyWasteUsd)}/mo` }), h('span', { class: 'waste-say', text: () => (isPrecise()
-                ? `projected spend not converting to kept outcomes, at the current realized-value rate (${pct(rec.realizedSpendShare, 0)})`
-                : `is heading for work that never gets used, if things carry on as they are`) }))
+                ? `projected spend not converting to realized outcomes, at the current realized-value rate (${pct(rec.realizedSpendShare, 0)})`
+                : `a month, at the current rate, goes to work that is not kept — a projection, not a measurement`) }))
         : null, rec.rationale?.length
-        ? h('ul', { class: 'drawer-notes' }, ...rec.rationale.map((r) => h('li', { text: r })))
+        ? h('ul', { class: 'drawer-notes' }, ...rec.rationale.map(noteWithCommand))
         : null);
 }

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

@@ -61,9 +61,9 @@ export function dataView() {
         const missing = list.filter((i) => !i.available);
         const o = overview();
         const isDemo = o?.demo === true;
-        const empty = (o?.summary.requests ?? 0) === 0;
+        const empty = o !== null && o.summary.requests === 0;
         return h('div', null, isDemo
-            ? h('div', { class: 'banner banner-demo' }, h('span', { class: 'pill pill-demo', text: 'demo' }), h('p', null, h('strong', { text: 'You are looking at sample data. ' }), 'Importing below replaces it with your own usage.'))
+            ? h('div', { class: 'banner banner-demo' }, h('span', { class: 'pill pill-demo', text: 'demo' }), h('p', null, h('strong', { text: 'You are looking at sample data. ' }), 'Imports are off while this is sample data, and nothing here writes into it. To bring in your own usage, run the dashboard without --demo.'))
             : empty
                 ? h('div', { class: 'banner' }, h('p', null, h('strong', { text: 'Nothing imported yet. ' }), 'Every other screen will stay empty until something here brings usage in.'))
                 : null, 
@@ -130,7 +130,7 @@ export function dataView() {
         }), o && !empty
             ? h('div', { class: 'card' }, h('div', { class: 'card-head' }, h('span', { class: 'card-title', text: () => (isPrecise() ? 'Currently held' : 'What Segreant has so far') })), h('div', { class: 'stat', text: count(o.summary.requests) }), h('span', { class: 'basis', text: () => (isPrecise()
                     ? `recorded requests totalling ${usd(o.summary.costUsd)} of metered cost`
-                    : `AI calls recorded, worth ${usd(o.summary.costUsd)} by our own measurement`) }))
-            : null, h('section', { class: 'section' }, h('h2', { class: 'section-title', text: () => (isPrecise() ? 'Actions on this layer' : 'Things you can do with this') }), h('div', { class: 'actions' }, actionCard('import'), actionCard('scan'), actionCard('connect'), actionCard('sources'), actionCard('baseline'), actionCard('demo'))));
+                    : `AI calls recorded, with ${usd(o.summary.costUsd)} of metered cost estimates`) }))
+            : null, h('section', { class: 'section' }, h('h2', { class: 'section-title', text: () => (isPrecise() ? 'Actions on this layer' : 'Things you can do with this') }), h('div', { class: 'actions' }, actionCard('import'), actionCard('scan'), actionCard('connect'), actionCard('sources'), actionCard('baseline'), actionCard('pricing-unknown'), actionCard('reprice'), actionCard('demo'))));
     });
 }