segreant 0.0.0-stage → 0.2.0

package/dist/alerts/notify.js

@@ -0,0 +1,66 @@
+/**
+ * Alert delivery — the "notify" half of governance.
+ *
+ * Detecting a budget breach is only useful if someone hears about it when they
+ * aren't staring at the dashboard. This POSTs alert metadata to a user-configured
+ * webhook (their own Slack/Teams/PagerDuty endpoint).
+ *
+ * Privacy boundary, enforced by construction: the payload is built ONLY from the
+ * Alert fields (id, severity, title, detail, metric). There is no code path here
+ * that can read a prompt, a response body, source code, or an API key — so the
+ * "no prompt or code leaves your device" promise holds even with delivery on.
+ */
+import { discardResponseBody, egressFetch, EgressError } from '../egress/transport.js';
+const SEV_RANK = { info: 0, warn: 1, critical: 2 };
+/** Build the exact payload that would be sent. Pure — used in tests to prove the boundary. */
+export function buildWebhookPayload(alerts, minSeverity = 'warn', now = Date.now()) {
+    const min = SEV_RANK[minSeverity];
+    return {
+        source: 'segreant',
+        generatedAt: new Date(now).toISOString(),
+        alerts: alerts
+            .filter((a) => SEV_RANK[a.severity] >= min)
+            .map((a) => ({ id: a.id, severity: a.severity, title: a.title, detail: a.detail, metric: a.metric })),
+    };
+}
+function egressRepairAction(code) {
+    if (code === 'receipt_integrity_failed' || code === 'receipt_persistence_failed') {
+        return 'restore or repair the local egress receipt history, then retry; if a lock is stale, confirm no Segreant writer owns it and remove only that lock';
+    }
+    return undefined;
+}
+/**
+ * POST the alert metadata to `url`. Fire-and-forget with a timeout; a failed
+ * delivery never throws (governance must not depend on a reachable webhook).
+ */
+export async function notifyWebhook(url, alerts, opts = {}) {
+    const payload = buildWebhookPayload(alerts, opts.minSeverity ?? 'warn', opts.now);
+    if (payload.alerts.length === 0)
+        return { delivered: false, posted: 0 };
+    try {
+        const res = await egressFetch(url, {
+            purpose: 'alert_delivery',
+            dataClass: 'alert_metadata',
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(payload),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 4000),
+        });
+        const delivered = res.ok;
+        const status = res.status;
+        await discardResponseBody(res);
+        return { delivered, posted: payload.alerts.length, status };
+    }
+    catch (e) {
+        if (e instanceof EgressError) {
+            return {
+                delivered: false,
+                posted: payload.alerts.length,
+                error: e.message,
+                failureCode: e.code,
+                action: egressRepairAction(e.code),
+            };
+        }
+        return { delivered: false, posted: payload.alerts.length, error: String(e), failureCode: 'network_error' };
+    }
+}

package/dist/alloc/epistemic.js

@@ -0,0 +1,154 @@
+/**
+ * Exact allocation-to-kernel issuance adapter.
+ *
+ * ISSUANCE CLASS: canonical — see `src/epistemic/issuance-map.ts`.
+ */
+import { claim } from '../epistemic/claim.js';
+import { evidence } from '../epistemic/evidence.js';
+import { grain } from '../epistemic/grain.js';
+import { scope } from '../epistemic/scope.js';
+import { instant, interval } from '../epistemic/time.js';
+import { canonicalPeriod } from '../economics/close.js';
+import { ECONOMIC_BASES } from '../economics/money.js';
+import { exactAllocationClaimProfile, exactAllocationToJson, serializeExactAllocationRun, validateExactAllocationResult } from './exact.js';
+const ALLOCATION_ASSUMPTIONS = Object.freeze([
+    'Allocation is a derived local showback projection, not provider settlement, chargeback, or causal attribution.',
+    'The exact input event set and its pricing bases are retained in the allocation result; unresolved legacy requests remain outside the exact rows.',
+]);
+function computedAt(value) {
+    if (!Number.isSafeInteger(value))
+        throw new Error('exact allocation computedAt must be a safe integer timestamp');
+    const iso = new Date(value).toISOString();
+    if (Date.parse(iso) !== value)
+        throw new Error('exact allocation computedAt is outside the supported timestamp range');
+    return instant(iso);
+}
+/**
+ * A MONETARY BASIS THAT OMITS ITS UNIT IS NOT A BASIS (WP-C03 / D-200).
+ *
+ * `sourceBases` is a basis-only summary, so a run holding USD 10.00 and
+ * EUR 90.00 — both at the `effective` basis — collapses to exactly one entry
+ * and this declared `monetaryBasis: 'effective'` for a kernel Evidence record
+ * spanning two currencies. The allocation figures underneath were never wrong:
+ * `applyExactAllocation` partitions every bucket and line by currency+basis
+ * identity and never sums across them. What was wrong is the one field a reader
+ * consults to learn what unit the claim is in.
+ *
+ * The honest answer for a multi-currency run is that there is no single
+ * monetary basis, which is what `null` already means here for a multi-basis
+ * run. Normalizing instead would require a target currency and an as-of
+ * boundary that an allocation run does not have — and choosing a rate without
+ * one is the failure the effective-FX read model exists to prevent. The
+ * per-identity totals remain in the payload, so nothing is withheld except the
+ * false summary.
+ */
+function sourceBasis(result) {
+    if (result.sourceBases.length !== 1)
+        return null;
+    if (new Set(result.totalByIdentity.map((bucket) => bucket.currency)).size > 1)
+        return null;
+    const basis = result.sourceBases[0];
+    if (basis === undefined || !ECONOMIC_BASES.includes(basis))
+        throw new Error(`exact allocation source basis is invalid: ${String(basis)}`);
+    return basis;
+}
+function validateRecord(allocationRunId, result) {
+    if (typeof allocationRunId !== 'string' || allocationRunId.trim().length === 0)
+        throw new Error('exact allocation run ID is required');
+    validateExactAllocationResult(result);
+    const serialized = serializeExactAllocationRun(result);
+    const expectedId = `economic:allocation:${serialized.digest.slice('sha256:'.length)}`;
+    if (allocationRunId !== expectedId)
+        throw new Error('exact allocation run ID does not match its canonical result digest');
+    const period = canonicalPeriod(result.periodStartMs, result.periodEndMs);
+    return { period, serialized, observedAt: computedAt(result.runAtMs), recordedAt: computedAt(result.runAtMs) };
+}
+/** Build immutable kernel Evidence/Claim records for one persisted exact run. */
+export function buildExactAllocationKernelIssuance(allocationRunId, result, computedAtMs) {
+    const { period, serialized, recordedAt } = validateRecord(allocationRunId, result);
+    const computed = computedAt(computedAtMs);
+    const validTime = interval(period.start, period.end);
+    const allocationScope = scope({ ledger: 'segreant-economic', period: period.subject, allocationRunId });
+    const allocationJson = exactAllocationToJson(result);
+    const payload = {
+        allocationRunId,
+        periodStartMs: period.startMs,
+        periodEndMs: period.endMs,
+        runAtMs: result.runAtMs,
+        computedAtMs,
+        result: allocationJson,
+        resultDigest: serialized.digest,
+    };
+    const coverage = result.complete ? 'complete' : 'partial';
+    const evidenceValue = evidence({
+        id: `evidence:economic:allocation:${allocationRunId}`,
+        evidenceType: 'economic.allocation',
+        sourceIdentity: 'segreant:economic-allocation',
+        sourceClass: 'segreant_local_exact_allocation_projection',
+        payload,
+        scope: allocationScope,
+        grain: grain(['economic_period', 'cost_centre']),
+        occurredAt: period.end,
+        validTime,
+        observedAt: recordedAt,
+        recordedAt: computed,
+        assertedAt: computed,
+        finalizedAt: null,
+        integrity: 'verified',
+        authenticity: 'self_asserted',
+        completeness: {
+            status: coverage,
+            method: 'exact_allocation_projection',
+            coveredEventTypes: ['economic_event', 'economic_allocation'],
+            coveredScope: allocationScope,
+            coveredTime: validTime,
+        },
+        measurementModelRef: null,
+        monetaryBasis: sourceBasis(result),
+        assumptions: ALLOCATION_ASSUMPTIONS,
+        supersedes: [],
+        supersededBy: null,
+        revocation: null,
+        schemaVersion: 1,
+        sensitivity: 'internal',
+        redaction: 'none',
+    });
+    const claimValue = {
+        allocationRunId,
+        periodStartMs: period.startMs,
+        periodEndMs: period.endMs,
+        resultDigest: serialized.digest,
+        complete: result.complete,
+        conserves: result.conserves,
+        sourceBases: [...result.sourceBases],
+        unresolvedRequestIds: [...result.unresolvedRequestIds],
+        result: allocationJson,
+    };
+    const claimValueRecord = claim({
+        id: `claim:economic:allocation:${allocationRunId}`,
+        proposition: { predicate: 'economic.allocation_recorded', value: claimValue },
+        subject: allocationRunId,
+        scope: allocationScope,
+        grain: grain(['economic_period', 'cost_centre']),
+        time: { validTime, asOf: computed },
+        epistemic: 'supported',
+        // The same profile the run's `excludedFrom` was derived from (D-228).
+        profile: exactAllocationClaimProfile(result.complete),
+        measurementModelRef: null,
+        evidenceIds: [evidenceValue.id],
+        derivationRule: 'economic.allocation.v1',
+        derivationVersion: 1,
+        assumptions: ALLOCATION_ASSUMPTIONS,
+        uncertainty: { kind: 'qualitative', description: 'Exact arithmetic and source lineage are verified; allocation is a local derived showback, not provider billing or causal value.' },
+        causalStatus: 'none',
+        monetaryBasis: 'allocated',
+        finality: 'provisional',
+        issuedAt: computed,
+        supersedes: [],
+        supersededBy: null,
+        revocation: null,
+        decisionCertificateIds: [],
+        schemaVersion: 1,
+    });
+    return Object.freeze({ evidence: evidenceValue, claim: claimValueRecord });
+}