segreant 0.1.0 → 0.2.0

package/dist/demo/seed.js

@@ -21,11 +21,13 @@
  * writer. The demo therefore exercises the production value pipeline, not a
  * parallel fake; only the inputs are synthetic, and every surface stays DEMO.
  */
-import { computeCost, syntheticPricingEvidence, unpricedPricingEvidence } from '../cost/pricing.js';
+import { computeCost, withoutDeclaredPrices, syntheticPricingEvidence, unpricedPricingEvidence, notSentPricingEvidence } from '../cost/pricing.js';
 import { startOfLocalDay } from '../budget/guard.js';
 import { GATE_LADDER, gateResultFromVerdict, scoreFunnel } from '../value/gates.js';
 import { classifyTaskType } from '../value/taskType.js';
 import { boundedLift } from '../value/lift.js';
+import { parseBillingImportText } from '../billing/importer.js';
+import { isOnDeclaredRoute } from '../billing/reconcile.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const HOUR_MS = 60 * 60 * 1000;
 /**
@@ -107,7 +109,7 @@ function addRequest(ctx, spec) {
             cacheWriteTokens,
             cacheReadTokens,
         });
-    const cost = calculated ?? { costUsd: 0, estimated: false, pricing: unpricedPricingEvidence() };
+    const cost = calculated ?? { costUsd: 0, estimated: false, pricing: notSentPricingEvidence() };
     // The route dictates every field that would have to agree in a real row, so a
     // seeded row cannot depict a combination the product could never produce.
     const route = ROUTES[spec.route ?? 'proxy_declared'];
@@ -141,6 +143,11 @@ function addRequest(ctx, spec) {
         durationMs: blocked ? 2 : int(ctx.rng, 600, 9000),
         user: spec.user,
         source: route.source ?? spec.source ?? null,
+        // Proxied OpenAI traffic is captured on the declared route, as a real proxy
+        // marks it, so the sample bill has local rows to be compared against.
+        ...(ctx.openAiScopeId !== null && spec.model.provider === 'openai' && route.via === 'proxy'
+            ? { scopeCaptureStatus: 'declared_unverified', providerScopeDeclarationId: ctx.openAiScopeId }
+            : {}),
     };
     ctx.store.insertRequest(row);
     ctx.requests += 1;
@@ -190,18 +197,20 @@ function addProposal(ctx, idx, sessionId, project, tsEpochMs) {
  * enrich the spend + acceptance surfaces; the realized-value picture is seeded
  * separately as persisted work units (see seedRealizationUnits).
  */
-function codingSession(ctx, idx, startMs) {
+function codingSession(ctx, idx, made) {
     const sessionId = `demo-sess-code-${idx}`;
-    const project = pick(ctx.rng, PROJECTS);
+    pick(ctx.rng, PROJECTS); // drawn and set aside: the commit names the project, and every later draw stays where it was
+    const project = made.project;
     const user = pick(ctx.rng, NAMED_USERS);
     const source = pick(ctx.rng, ['opencode', 'cursor']);
-    ctx.store.upsertSession(sessionId, project, source, startMs);
-    ctx.sessions += 1;
+    // Drawn in the original order, then laid out so the session ends a few
+    // minutes before the commit it made, as a real session's log would show.
     const calls = int(ctx.rng, 6, 12);
-    let t = startMs;
+    const specs = [];
+    let offset = 0;
     for (let i = 0; i < calls; i++) {
-        addRequest(ctx, {
-            tsEpochMs: t,
+        specs.push({
+            offsetMs: offset,
             model: pick(ctx.rng, [OPUS, SONNET, SONNET]),
             project,
             user,
@@ -212,9 +221,24 @@ function codingSession(ctx, idx, startMs) {
             cacheWriteTokens: i === 0 ? int(ctx.rng, 8_000, 30_000) : 0,
             cacheReadTokens: i === 0 ? 0 : int(ctx.rng, 10_000, 80_000),
         });
-        t += int(ctx.rng, 2 * 60 * 1000, 25 * 60 * 1000);
+        offset += int(ctx.rng, 2 * 60 * 1000, 25 * 60 * 1000);
     }
+    // A session's cached context only grows as the conversation does, so the
+    // cache reads already drawn are handed out in rising order.
+    const reads = specs.slice(1).map((r) => r.cacheReadTokens ?? 0).sort((a, b) => a - b);
+    specs.slice(1).forEach((r, i) => { r.cacheReadTokens = reads[i]; });
+    const lastOffset = specs[specs.length - 1].offsetMs;
+    const startMs = made.tsEpochMs - 3 * 60 * 1000 - lastOffset;
+    ctx.store.upsertSession(sessionId, project, source, startMs);
+    ctx.sessions += 1;
+    for (const { offsetMs, ...spec } of specs)
+        addRequest(ctx, { ...spec, tsEpochMs: startMs + offsetMs });
     addProposal(ctx, idx, sessionId, project, startMs + 1000);
+    // The commit as the session's own log reports it: the only link the
+    // Workbench draws between spend and a commit.
+    ctx.store.recordObservedCommit({
+        source, sessionId, shortSha: made.hash, branch: 'main', subject: made.subject, tsEpochMs: made.tsEpochMs, cwd: null,
+    });
 }
 /**
  * A non-coding session (chat / research / drafting): a short burst with no
@@ -319,6 +343,98 @@ const REALIZATION_ROSTER = [
     { project: 'backend-api', model: 'claude-opus-4-8', subject: 'feat: per-context frontier', daysAgo: 5, costUsd: 1.95, linesAdded: 175, acceptance: 0.83, arch: 'maturing' },
     { project: 'data-pipeline', model: 'gpt-4o', subject: 'refactor: store-backed realization', daysAgo: 3, costUsd: 0.8, linesAdded: 120, acceptance: 0.60, arch: 'maturing' },
 ];
+const DEMO_OPENAI_PROJECT = 'proj_demo_sample';
+/**
+ * A provider bill for the sample's OpenAI route, imported, adopted and compared
+ * through the same store calls as `segreant billing import`, `openai-costs
+ * adopt` and `reconcile`. The bill is built from the route's own daily list
+ * cost, with most days billed a few percent above it: the gap a real
+ * comparison finds when some usage (a playground, a teammate's key) never
+ * passed through Segreant. It is synthetic and filed as an operator export.
+ */
+function seedBillComparison(ctx, now, days) {
+    const scopeId = ctx.openAiScopeId;
+    if (scopeId === null)
+        return;
+    // Whole UTC days ending at least 48 hours ago: the comparison refuses a
+    // period the provider may still be adding charges to, as it should.
+    const end = Math.floor((now - 2 * DAY_MS) / DAY_MS) * DAY_MS;
+    const start = end - (days - 1) * DAY_MS;
+    const perDay = new Map();
+    for (const r of ctx.store.requestsInRange(start, end)) {
+        if (!isOnDeclaredRoute(r, scopeId))
+            continue;
+        const day = Math.floor(r.tsEpochMs / DAY_MS) * DAY_MS;
+        perDay.set(day, (perDay.get(day) ?? 0) + Math.round(r.costUsd * 1e6));
+    }
+    const records = [];
+    for (let day = start; day < end; day += DAY_MS) {
+        const local = perDay.get(day) ?? 0;
+        if (local === 0)
+            continue;
+        const uplift = ctx.rng() < 0.7 ? 1 + int(ctx.rng, 1, 7) / 100 : 1;
+        const micros = Math.round(local * uplift);
+        records.push({
+            sourceRecordId: `demo-line-${day}`,
+            chargePeriodStart: new Date(day).toISOString(),
+            chargePeriodEnd: new Date(day + DAY_MS).toISOString(),
+            observedAt: new Date(day + DAY_MS).toISOString(),
+            providerProjectRef: DEMO_OPENAI_PROJECT,
+            chargeType: 'usage', currency: 'USD', amount: (micros / 1e6).toFixed(6), sku: 'model-usage',
+            service: 'api', model: 'mixed', region: null, usageUnit: 'tokens', usageQuantity: '0',
+        });
+    }
+    if (records.length === 0)
+        return;
+    const file = Buffer.from(JSON.stringify({
+        schemaVersion: 1,
+        source: {
+            system: 'operator-export', provider: 'openai', exportId: `demo-export-${start}`,
+            billingAccountRef: 'org_demo_sample', exportedAt: new Date(now).toISOString(),
+            periodStart: new Date(start).toISOString(), periodEnd: new Date(end).toISOString(), coverage: 'complete',
+        },
+        records,
+    }), 'utf8');
+    const imported = ctx.store.applyBillingImport(parseBillingImportText(file, 'openai-costs-sample.segreant.json').input, now);
+    ctx.store.issueBillingImportToKernel(imported.run.importId);
+    const plan = ctx.store.planOpenAiCostsAdoption({ importId: imported.run.importId, declaredScopeId: scopeId, providerProjectRef: DEMO_OPENAI_PROJECT });
+    if (!plan.adoptable)
+        throw new Error(`demo seed: the sample bill could not be adopted (${plan.refusal})`);
+    ctx.store.adoptOpenAiCostsFromImport(plan, now);
+    const result = ctx.store.reconcileOpenAiCosts({ now });
+    if (!result || result.status === 'refused')
+        throw new Error(`demo seed: the sample bill could not be compared (${result ? `${result.refusal}: ${result.detail}` : 'not reconcilable'})`);
+    const runId = ctx.store.saveReconciliationRun(result);
+    if (result.coverage.providerDays > 0)
+        ctx.store.issueOpenAiReconciliationToKernel(runId);
+}
+/**
+ * Three cost centres, one direct rule per project, and one recorded split of
+ * the fortnight, through the same calls as `segreant alloc`. Traffic that
+ * never declared a project matches no rule and stays unallocated, which is
+ * the gap the Allocate page exists to show.
+ */
+function seedCostCentres(ctx, now, days) {
+    const centres = [
+        ['platform', 'Platform', 'carol@team', 'backend-api'],
+        ['product', 'Product', 'alice@team', 'web-frontend'],
+        ['data', 'Data', 'bob@team', 'data-pipeline'],
+    ];
+    const at = now - days * DAY_MS;
+    for (const [id, name, owner, project] of centres) {
+        ctx.store.upsertCostCentre({ costCentreId: id, name, owner, createdAtMs: at });
+        ctx.store.saveAllocationRule({
+            ruleId: `${id}-direct`, method: 'direct', match: { project }, targets: [{ costCentreId: id, ratio: 1 }],
+            priority: 100, effectiveFromMs: 0, effectiveToMs: null, revokedAtMs: null, owner, note: `All ${project} spend`, createdAtMs: at,
+        });
+    }
+    const result = ctx.store.allocatePeriod(now - days * DAY_MS, now, now);
+    if (!result.conserves)
+        throw new Error('demo seed: the sample split did not conserve its input');
+    ctx.store.saveAllocationRun(result, now);
+}
+/** The roster commits the sample's coding sessions made, by subject. */
+const CODING_COMMITS = ['feat: alerts banner rework', 'fix: dark-mode contrast', 'fix: chart axis labels', 'feat: per-context frontier'];
 function makeRealizationUnit(ctx, now, spec, hash) {
     const arch = ARCHETYPES[spec.arch];
     const tsEpochMs = now - Math.floor(spec.daysAgo * DAY_MS);
@@ -347,6 +463,9 @@ function makeRealizationUnit(ctx, now, spec, hash) {
         costPerHundredLines: spec.linesAdded > 0 ? (spec.costUsd / spec.linesAdded) * 100 : null,
         ageDays: spec.daysAgo,
         maturing: arch.maturing,
+        // The sample is synthesised with the default window; saying so keeps it
+        // from reading as an old measurement that never recorded its own.
+        checkWindowDays: 14,
         survivalRatio: arch.survival,
         reverted: arch.verdicts.clean === 'fail',
         hadProposal: spec.acceptance !== null,
@@ -485,9 +604,20 @@ function seedImportedTail(ctx, now, days) {
  * the deterministic ids collision-free).
  */
 export function seedDemo(store, opts = {}) {
+    // Sample data is priced from the card alone, whatever the user declared.
+    return withoutDeclaredPrices(() => seedDemoFromCard(store, opts));
+}
+function seedDemoFromCard(store, opts) {
     const now = opts.now ?? Date.now();
     const days = opts.days ?? 14;
-    const ctx = { store, rng: mulberry32(0xae915f10), n: 0, requests: 0, blocked: 0, sessions: 0, proposals: 0, signals: 0, cost: 0 };
+    const ctx = { store, rng: mulberry32(0xae915f10), n: 0, requests: 0, blocked: 0, sessions: 0, proposals: 0, signals: 0, cost: 0, openAiScopeId: null };
+    // Declared before any traffic, so the whole fortnight's proxied OpenAI rows
+    // fall on the route. No random draw is taken here: every later figure stays put.
+    const declaredAtMs = now - (days + 1) * DAY_MS;
+    ctx.openAiScopeId = store.setOpenAiScope({
+        billingAccountRef: 'org_demo_sample', providerProjectRef: DEMO_OPENAI_PROJECT,
+        upstreamBase: 'https://api.openai.com', declaredAtMs, activatedAtMs: declaredAtMs,
+    }).declarationId;
     // Each prior day of the fortnight: light background chatter plus a real block
     // of opus/sonnet work. This establishes a believable active-day baseline (a
     // few dollars a day) so today's runaway reads as a credible multiple of a
@@ -519,9 +649,15 @@ export function seedDemo(store, opts = {}) {
             });
         }
     }
-    // Scattered work sessions over the period.
-    const codingStarts = [11, 9, 7, 4].map((d) => now - d * DAY_MS + 10 * HOUR_MS);
-    codingStarts.forEach((startMs, i) => codingSession(ctx, i + 1, startMs));
+    // Four work sessions, each ending in a commit from the measured roster: one
+    // kept, one not kept, two still too new to judge.
+    CODING_COMMITS.forEach((subject, i) => {
+        const at = REALIZATION_ROSTER.findIndex((u) => u.subject === subject);
+        const spec = REALIZATION_ROSTER[at];
+        codingSession(ctx, i + 1, {
+            hash: `demo-commit-${at + 1}`, subject, project: spec.project, tsEpochMs: now - Math.floor(spec.daysAgo * DAY_MS),
+        });
+    });
     // Non-coding sessions, seeded per-user so the per-user VALUE distribution is
     // real: a spread of extraction across the team (some extract nearly all their
     // spend, some little), which drives dispersion + coaching headroom in
@@ -589,6 +725,9 @@ export function seedDemo(store, opts = {}) {
     }
     seedImportedTail(ctx, now, days);
     const realizationUnits = seedRealizationUnits(ctx, now);
+    // Last, so their random draws come after every other figure's.
+    seedBillComparison(ctx, now, days);
+    seedCostCentres(ctx, now, days);
     return {
         requests: ctx.requests,
         blocked: ctx.blocked,

package/dist/economics/ledger.js

@@ -32,7 +32,7 @@ function canonicalBoundary(value) {
 // Verification (parse, canonicalize, digest, identity) is a pure function of
 // the stored row's bytes and yields a deeply frozen event, so a row whose every
 // stored column is unchanged reuses it; any byte difference re-verifies.
-const VERIFIED_EVENT_CACHE_MAX = 20_000;
+const VERIFIED_EVENT_CACHE_MAX = 150_000;
 const verifiedEvents = new Map();
 function sameStoredRow(a, b) {
     return a.event_json === b.event_json && a.event_digest === b.event_digest && a.event_kind === b.event_kind

package/dist/egress/policy.js

@@ -1,5 +1,123 @@
+/**
+ * Pure, exact policy for Segreant-process HTTP(S) egress. Socket creation lives
+ * only in transport.ts, so a feature cannot silently make its own network path.
+ */
+import { createHash } from 'node:crypto';
 import { EGRESS_DATA_CLASSES, EGRESS_PURPOSES, canonicalAuthorizationPath, canonicalOrigin, normalizePathPrefix, validateEgressRule, } from './ruleValidation.js';
 export { EGRESS_DATA_CLASSES, EGRESS_PURPOSES, validateEgressRule };
+/**
+ * Segreant's own self-maintenance downloads: fixed public files, fetched with a
+ * plain GET that carries nothing about the user. With the providers' official
+ * APIs (below), they are the built-in exceptions to
+ * local_locked, because a rate card that can never update prices every new
+ * model by a guess (claude-haiku-5-5 at $3/$15 against a $0.10/$0.50 list
+ * price). The match is exact: purpose, data class, GET, and the full URL with no
+ * query or fragment, so no caller can reach any other address through it. The
+ * DNS answer must still be public and every attempt is in the receipt chain.
+ * Like the providers' official APIs it holds in every mode, controlled_cloud
+ * included (PR #148). `segreant pricing --auto off` stops Segreant
+ * asking on its own; a manual `segreant pricing --refresh` is the user asking.
+ */
+export const DEFAULT_PRICE_LIST_URL = 'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
+export const MAINTENANCE_RULE_ID = 'segreant-builtin-price-list';
+const MAINTENANCE_TARGETS = [
+    { purpose: 'pricing_refresh', dataClass: 'pricing_manifest', href: DEFAULT_PRICE_LIST_URL },
+];
+function maintenanceTarget(target, intent, method) {
+    if (method !== 'GET' || target.protocol !== 'https:' || target.search !== '' || target.hash !== '')
+        return false;
+    return MAINTENANCE_TARGETS.some((m) => m.purpose === intent.purpose && m.dataClass === intent.dataClass && m.href === target.href);
+}
+/**
+ * The providers' own APIs. A request the user's tool sends to its provider is
+ * the user's traffic, already going there before Segreant existed; Segreant only
+ * meters it on the way through. Locking it by default made a fresh install
+ * refuse every request with a 403 until two egress commands were run, which
+ * protected nothing (the owner's call, 2026-10-18). What stays locked is
+ * everything that would send Segreant's own data somewhere new: webhooks, team
+ * rollups, hosted judging. The match is exact: provider purpose and data class,
+ * GET or POST, HTTPS, the official origin, under /v1/. A custom upstream (a
+ * gateway, a self-hosted model) is the user's to allow with its own rule.
+ */
+export const PROVIDER_RULE_ID_PREFIX = 'segreant-builtin-provider-';
+const PROVIDER_TARGETS = [
+    { id: 'anthropic', origin: 'https://api.anthropic.com', pathPrefix: '/v1/' },
+    { id: 'openai', origin: 'https://api.openai.com', pathPrefix: '/v1/' },
+];
+function providerTarget(target, intent, method) {
+    if (intent.purpose !== 'provider_inference' || intent.dataClass !== 'provider_request')
+        return null;
+    if ((method !== 'POST' && method !== 'GET') || target.protocol !== 'https:')
+        return null;
+    const match = PROVIDER_TARGETS.find((p) => p.origin === target.origin && pathMatchesPrefix(target.pathname, p.pathPrefix));
+    return match ? PROVIDER_RULE_ID_PREFIX + match.id : null;
+}
+/** Whether requests to this upstream go out with no rule: it is one of the providers' official APIs. */
+export function isBuiltInProviderUpstream(url) {
+    try {
+        const target = new URL(url);
+        return PROVIDER_TARGETS.some((p) => p.origin === target.origin);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A rule id the egress command accepts (a lowercase letter, then 2-63 of
+ * a-z, 0-9, _ or -). The hostname alone was printed before, and its dots made
+ * the printed command fail with "Rule refused" (PR #148 review).
+ */
+export function providerRuleId(origin, method = 'POST') {
+    // Rules are replaced by id, so the id must be unique per origin and method:
+    // the method keeps a GET and a POST rule for one host apart, and a short hash
+    // of the full canonical origin (scheme, host and port) keeps apart hosts whose
+    // slugs collide (api.foo-bar.com / api.foo.bar.com), share a truncated
+    // prefix, or differ only by port (PR #148 review). The slug is the hostname,
+    // for a readable id.
+    let canonical;
+    try {
+        canonical = new URL(origin.includes('://') ? origin : `https://${origin}`);
+    }
+    catch {
+        canonical = new URL('https://invalid.invalid');
+    }
+    const host = canonical.hostname.toLowerCase();
+    const verb = method.toLowerCase().replace(/[^a-z]/g, '');
+    const tag = createHash('sha256').update(canonical.origin).digest('hex').slice(0, 8);
+    const slug = host.replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    const head = `provider-${slug}`.slice(0, 64 - tag.length - verb.length - 2).replace(/-+$/, '');
+    return `${head}-${tag}-${verb}`;
+}
+const RULE_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD']);
+/** The one command that lets Segreant forward to an upstream that is not built in (a gateway, a hosted model). */
+export function providerRuleCommand(url, method = 'POST') {
+    let origin;
+    try {
+        origin = new URL(new URL(url).origin);
+    }
+    catch {
+        return null;
+    }
+    if (origin.protocol !== 'https:')
+        return null;
+    // Only methods a rule can name: printing `--method OPTIONS` would hand the
+    // user a command the rule validator refuses (PR #148 review).
+    if (!RULE_METHODS.has(method.toUpperCase()))
+        return null;
+    return `segreant egress apply --apply --mode controlled_cloud --id ${providerRuleId(origin.origin, method)} --purpose provider_inference --data-class provider_request --method ${method.toUpperCase()} --origin ${origin.origin} --path-prefix /`;
+}
+/** Built-in routes, the same in every mode: an operator who adds a webhook rule keeps their provider and their price list. */
+function builtInRoute(target, intent, method) {
+    if (maintenanceTarget(target, intent, method)) {
+        // Same transport checks as a cloud rule: the address must resolve public.
+        return { allowed: true, target, targetClass: 'controlled_cloud', ruleId: MAINTENANCE_RULE_ID, reason: "Segreant's built-in public price list (GET only)" };
+    }
+    const provider = providerTarget(target, intent, method);
+    if (provider) {
+        return { allowed: true, target, targetClass: 'controlled_cloud', ruleId: provider, reason: "your request to the provider's official API (built in)" };
+    }
+    return null;
+}
 function literalLoopback(hostname) {
     const host = hostname.replace(/(^\[|\]$)/g, '').toLowerCase();
     return host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '::ffff:127.0.0.1';
@@ -26,7 +144,8 @@ function matches(rule, target, intent) {
         && pathMatchesPrefix(target.pathname, rule.pathPrefix);
 }
 /**
- * Decides before DNS. Local locked mode permits only literal loopback, so it
+ * Decides before DNS. Local locked mode permits literal loopback and the exact
+ * built-in routes (price list, official provider APIs) only, so it
  * never resolves a potential cloud host before rejecting it.
  */
 export function evaluateEgressPolicy(config, intent) {
@@ -46,12 +165,17 @@ export function evaluateEgressPolicy(config, intent) {
         return { allowed: false, target, reason: 'method is not supported' };
     if (literalLoopback(target.hostname))
         return { allowed: true, target, targetClass: 'loopback', reason: 'literal loopback target is permitted' };
-    if (config.mode === 'local_locked') {
-        return { allowed: false, target, reason: 'local_locked permits only literal loopback; no non-loopback DNS lookup or dial occurs' };
-    }
-    if (config.mode !== 'controlled_cloud' || !Array.isArray(config.rules)) {
+    // A malformed persisted section (mode `invalid`) or any unknown shape refuses
+    // before the built-in routes: a typo never lets provider traffic through.
+    if (config.mode !== 'local_locked' && (config.mode !== 'controlled_cloud' || !Array.isArray(config.rules))) {
         return { allowed: false, target, reason: 'unknown or malformed egress mode/config is fail-closed; only local_locked or controlled_cloud is supported' };
     }
+    const builtIn = builtInRoute(target, intent, method);
+    if (builtIn)
+        return builtIn;
+    if (config.mode === 'local_locked') {
+        return { allowed: false, target, reason: "local_locked permits only literal loopback, the built-in public price list and the providers' official APIs; no other DNS lookup or dial occurs" };
+    }
     if (target.protocol !== 'https:')
         return { allowed: false, target, reason: 'controlled_cloud refuses plaintext HTTP outside literal loopback' };
     const matching = config.rules.filter((rule) => matches(rule, target, { ...intent, method }));

package/dist/export/allocationCsv.js

@@ -0,0 +1,70 @@
+/**
+ * One recorded allocation run as a spreadsheet a budget owner can hand on.
+ *
+ * Built from the run exactly as it was recorded, never recomputed: a fresh
+ * computation under today's rules could disagree with the split someone
+ * already reviewed. Every money row is a part of the run's total, so the
+ * amount column adds up to the total to the microdollar and summing it is
+ * safe. The total itself is stated in the first row's note rather than given
+ * a row of its own, which would double any column sum.
+ *
+ * This is showback: a split of Segreant's own cost estimate. It is not a
+ * provider bill and is never added to metered or billed figures.
+ */
+import { toCsv } from './csv.js';
+export const ALLOCATION_CSV_COLUMNS = [
+    'section', 'costCentre', 'costCentreId', 'ruleId', 'ruleVersion', 'method', 'shareOfRule',
+    'amountUsd', 'amountMicros', 'requests', 'basis', 'periodStartUtc', 'periodEndUtc',
+    'runId', 'recordedAtUtc', 'note',
+];
+const BASIS = 'showback split of the local estimate';
+const REASONS = {
+    no_matching_rule: 'no rule claimed it',
+    no_driver_for_proportional_pool: 'a shared pool with nothing directly allocated to split it by',
+    target_cost_centre_archived: 'its cost centre was archived',
+};
+const METHODS = {
+    direct: 'all to one centre',
+    fixed_split: 'fixed shares',
+    proportional_to_direct: 'in proportion to direct spend',
+};
+const iso = (ms) => new Date(ms).toISOString();
+/** Exact decimal dollars from integer microdollars, with no float in between. */
+export function microsToUsd(micros) {
+    const sign = micros < 0 ? '-' : '';
+    const abs = Math.abs(micros);
+    return `${sign}${Math.trunc(abs / 1_000_000)}.${String(abs % 1_000_000).padStart(6, '0')}`;
+}
+export function allocationRunToCsv(run, nameOf, demo) {
+    const r = run.result;
+    const own = [iso(r.periodStartMs), iso(r.periodEndMs), run.allocationRunId, iso(run.computedAtMs)];
+    const notes = [
+        `Total estimated spend in the period: $${microsToUsd(r.totalMicros)}. The rows below add up to it exactly.`,
+        'Showback: a split of Segreant\'s own cost estimate, not a provider bill. Do not add it to metered or billed figures.',
+    ];
+    if (demo)
+        notes.push('Sample data, not measured.');
+    if (r.retention === undefined)
+        notes.push('Recorded before retention was tracked: whether rows were deleted from this period is unknown.');
+    else if (r.retention.truncated)
+        notes.push('Retention deleted request rows from inside this period; the split covers what survived, so the unallocated part may be understated.');
+    if (!r.conserves)
+        notes.push('This run did not conserve: allocated plus unallocated differs from the total. Do not rely on it.');
+    const rows = [];
+    rows.push(['run', '', '', '', '', '', '', '', '', '', BASIS, ...own, notes.join(' ')]);
+    for (const line of r.lines) {
+        rows.push(['allocated', nameOf(line.costCentreId), line.costCentreId, line.ruleId, line.ruleVersion,
+            METHODS[line.method] ?? line.method, (line.ratioParts / 1_000_000).toFixed(6),
+            microsToUsd(line.allocatedMicros), line.allocatedMicros, line.requestCount,
+            `${BASIS}; underlying cost basis ${line.sourceBasis}`, ...own, '']);
+    }
+    for (const u of r.unallocated) {
+        const top = u.topProjects.length > 0
+            ? `mostly ${u.topProjects.map((p) => `${p.project} ($${microsToUsd(p.micros)})`).join(', ')}`
+            : '';
+        rows.push(['unallocated', '', '', '', '', '', '', microsToUsd(u.micros), u.micros, u.requestCount,
+            `${BASIS}; underlying cost basis ${u.sourceBasis}`, ...own,
+            [`not allocated: ${REASONS[u.reason] ?? u.reason.replace(/_/g, ' ')}`, top].filter(Boolean).join('; ')]);
+    }
+    return toCsv([...ALLOCATION_CSV_COLUMNS], rows);
+}

package/dist/export/billingCsv.js

@@ -17,8 +17,11 @@ const COLUMNS = [
     'costBasis', 'trust',
 ];
 /** This export is separate from request-ledger CSV and never adds provider totals to metered estimates. */
-export function billingEvidenceToCsv(rows) {
-    const lines = [COLUMNS.map((column) => cell(column)).join(',')];
+export function billingEvidenceToCsv(rows, demo = false) {
+    // Sample data adds one last column, so a generated bill cannot be mistaken
+    // for a real one once the file leaves the terminal. A real export keeps its
+    // schema unchanged.
+    const lines = [[...COLUMNS, ...(demo ? ['sample'] : [])].map((column) => cell(column)).join(',')];
     for (const row of rows) {
         lines.push([
             row.sourceSystem, row.billingAccountRef, row.sourceRecordId, row.sourceRecordSha256, row.firstImportId,
@@ -26,6 +29,7 @@ export function billingEvidenceToCsv(rows) {
             new Date(row.observedAtMs).toISOString(), new Date(row.chargePeriodStartMs).toISOString(),
             new Date(row.chargePeriodEndMs).toISOString(), row.chargeType, row.currency, formatUsdMicros(row.amountMicros),
             row.amountMicros, row.usageUnit, row.usageQuantity, row.costBasis, row.trust,
+            ...(demo ? ['generated sample data, not a provider bill'] : []),
         ].map((value, index) => cell(value, ![12, 13, 14, 17, 18].includes(index))).join(','));
     }
     return lines.join('\r\n') + '\r\n';

package/dist/export/csv.js

@@ -5,11 +5,19 @@
  * who own the budget. This serializes the request ledger to CSV (spreadsheet-
  * native) or leaves it as JSON. Pure string building, no dependencies.
  */
-/** RFC-4180-ish cell: quote when it contains a comma, quote, or newline; double internal quotes. */
+const NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+/**
+ * RFC-4180-ish cell: quote when it contains a comma, quote, or newline; double
+ * internal quotes. Labels come from tool logs and folder names, so text that a
+ * spreadsheet would read as a formula is prefixed with an apostrophe. Numbers,
+ * including negative amounts carried as strings, are left as numbers.
+ */
 function cell(v) {
     if (v === null || v === undefined)
         return '';
-    const s = String(v);
+    let s = String(v);
+    if (typeof v === 'string' && /^[=+\-@\t\r]/.test(s) && !NUMBER.test(s))
+        s = `'${s}`;
     return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
 }
 export function toCsv(headers, rows) {

package/dist/export/economic.js

@@ -76,14 +76,18 @@ const ECONOMIC_COLUMNS = [
 export function economicRequestsToJson(rows) {
     if (!Array.isArray(rows))
         throw new Error('economic export rows must be an array');
-    return `${canonicalJson(rows.map((row) => ({
+    // The canonical serializer bounds one record. Each row is bounded on its own;
+    // the number of rows is the ledger's history, so it is not. The joined form is
+    // byte-identical to canonicalising the array whole.
+    const parts = rows.map((row) => canonicalJson({
         ...row,
         sourceMoney: row.sourceMoney === null ? null : { ...row.sourceMoney },
         effectiveMoney: row.effectiveMoney === null ? null : { ...row.effectiveMoney },
         sourceBases: [...row.sourceBases],
         sourceEventIds: [...row.sourceEventIds],
         correctionEventIds: [...row.correctionEventIds],
-    })))}\n`;
+    }));
+    return `[${parts.join(',')}]\n`;
 }
 /** CSV exact export with compatibility dollars explicitly labelled as such. */
 export function economicRequestsToCsv(rows) {