@suluk/cost 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,35 @@
+<p align="center">
+  <a href="https://github.com/MahmoodKhalil57/suluk">
+    <img src="https://raw.githubusercontent.com/MahmoodKhalil57/suluk/main/branding/export/wordmark.png" alt="Suluk" width="360" />
+  </a>
+</p>
+
+<h1 align="center">@suluk/cost</h1>
+
+<p align="center"><b>Cost as a contract facet: declare per-operation cost (incl. third-party usage), bubble it into the v4 doc/Scalar/tests, and meter the ACTUAL per-user cost at runtime (frontend action -> operation -> third-party). Display as-is.</b></p>
+
+<p align="center">
+  <em>Part of <a href="https://github.com/MahmoodKhalil57/suluk">Suluk</a> — one typed OpenAPI v4 contract projecting into every full-stack layer.</em>
+</p>
+
+---
+
+> **CANDIDATE tooling — not official OpenAPI.** Suluk is a single-contributor candidate for
+> OpenAPI Specification v4.0 ("Moonwalk"), unaffiliated with the OpenAPI Initiative and unable
+> to ratify anything on the SIG's behalf.
+
+## Install
+
+```sh
+bun add @suluk/cost
+```
+
+## The Suluk cycle
+
+`@suluk/cost` is one station on the Suluk walk — author one v4 source, then **validate · audit ·
+preview · generate · deploy** the whole stack from it. Explore the full toolchain in the
+[main repository](https://github.com/MahmoodKhalil57/suluk) or drive it from the [VS Code cockpit](https://marketplace.visualstudio.com/items?itemName=MahmoodKhalil.suluk-vscode).
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@suluk/cost",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Cost as a contract facet: declare per-operation cost (incl. third-party usage), bubble it into the v4 doc/Scalar/tests, and meter the ACTUAL per-user cost at runtime (frontend action -> operation -> third-party). Display as-is. CANDIDATE tooling.",
-  "type": "module",
-  "main": "src/index.ts",
-  "exports": {
-  ".": "./src/index.ts"
+  "publishConfig": {
+  "access": "public"
+},
+"license": "Apache-2.0",
+"repository": {
+  "type": "git",
+  "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+  "directory": "tooling/ts/packages/cost"
+},
+"homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+"bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+"type": "module",
+"main": "src/index.ts",
+"exports": {
+".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "0.1.0"
+"@suluk/core": "^0.1.7"
 },
 "peerDependencies": {
 "hono": "^4.0.0"
@@ -21,8 +32,8 @@
 "devDependencies": {
 "@types/bun": "latest",
 "hono": "^4.0.0",
-"@suluk/hono": "0.1.0",
-"@suluk/openapi-compat": "0.1.0",
+"@suluk/hono": "^0.1.2",
+"@suluk/openapi-compat": "^0.1.2",
 "zod": "^4.4.3"
 },
 "scripts": {

package/src/contract.ts

@@ -4,19 +4,45 @@
  * `x-*`), Scalar/Swagger render it, and a coverage audit can flag operations that never declared a cost.
  * The contract tells you what an operation *should* cost; the runtime meter tells you what it *did*.
  */
-import type { OpenAPIv4Document, PathItem, Request } from "@suluk/core";
-import type { CostModel, UsageReport } from "./types";
+import type { OpenAPIv4Document, PathItem, Request, SulukJob } from "@suluk/core";
+import { UNATTRIBUTED, type CostModel, type CostTrigger, type UsageReport } from "./types";
 
 export const COST_EXT = "x-suluk-cost";
 
-/** Annotate a v4 document in place-safe (returns a new doc): set x-suluk-cost on each named operation. */
+/** Every background JOB (C025) on the document, as {path, name, job} — non-HTTP cron/queue work. */
+export function eachJob(doc: OpenAPIv4Document): { path: string; name: string; job: SulukJob }[] {
+  const jobs = (doc as { ["x-suluk-jobs"]?: Record<string, SulukJob> })["x-suluk-jobs"] ?? {};
+  return Object.entries(jobs).map(([name, job]) => ({ path: `jobs/${name}`, name, job }));
+}
+
+/** Every cost LOCUS in the document — path requests, C018 webhooks, AND C025 jobs — with its declared model. */
+function costLoci(doc: OpenAPIv4Document): { path: string; name: string; model: CostModel | undefined }[] {
+  const out = eachOperation(doc).map(({ path, name, req }) => ({ path, name, model: costOf(req) }));
+  for (const { path, name, job } of eachJob(doc)) out.push({ path, name, model: (job as unknown as Record<string, unknown>)[COST_EXT] as CostModel | undefined });
+  return out;
+}
+
+/**
+ * Every named operation in the document — path requests AND C018 webhooks (which are Requests carrying facets) —
+ * as {path, name, req}. Background-event cost lives on a webhook op, so every cost reader walks this, not just paths.
+ */
+export function eachOperation(doc: OpenAPIv4Document): { path: string; name: string; req: Request }[] {
+  const out: { path: string; name: string; req: Request }[] = [];
+  for (const [path, piRaw] of Object.entries(doc.paths ?? {})) {
+    for (const [name, req] of Object.entries((piRaw as PathItem).requests ?? {})) out.push({ path, name, req: req as Request });
+  }
+  for (const [name, req] of Object.entries((doc as { webhooks?: Record<string, Request> }).webhooks ?? {})) {
+    out.push({ path: `webhooks/${name}`, name, req: req as Request });
+  }
+  return out;
+}
+
+/** Annotate a v4 document in place-safe (returns a new doc): set x-suluk-cost on each named operation (incl. webhooks). */
 export function annotateCosts(doc: OpenAPIv4Document, costs: Record<string, CostModel>): OpenAPIv4Document {
   const out: OpenAPIv4Document = structuredClone(doc);
-  for (const pi of Object.values(out.paths ?? {})) {
-    for (const [name, req] of Object.entries((pi as PathItem).requests ?? {})) {
-      const model = costs[name];
-      if (model) (req as Request & Record<string, unknown>)[COST_EXT] = model;
-    }
+  for (const { name, req } of eachOperation(out)) {
+    const model = costs[name];
+    if (model) (req as Request & Record<string, unknown>)[COST_EXT] = model;
   }
   return out;
 }
@@ -26,8 +52,18 @@ export function costOf(req: Request): CostModel | undefined {
   return (req as Request & Record<string, unknown>)[COST_EXT] as CostModel | undefined;
 }
 
+/** The trigger an operation's cost declares (C024; default "synchronous"). */
+export function triggerOf(model: CostModel | undefined): CostTrigger {
+  return model?.trigger ?? "synchronous";
+}
+
+/** Does this cost accrue on a BACKGROUND event (a non-synchronous trigger) rather than the declaring op's own run? */
+export function isDeferredCost(model: CostModel | undefined): boolean {
+  return !!model && triggerOf(model) !== "synchronous";
+}
+
 export interface CostFinding {
-  code: "no-cost-model" | "zero-cost";
+  code: "no-cost-model" | "zero-cost" | "unattributed-background-cost" | "unverified-attribution" | "reconciliation-incomplete";
   severity: "warn" | "info";
   path: string;
   operation: string;
@@ -35,34 +71,46 @@ export interface CostFinding {
 }
 
 /**
- * Cost-coverage audit: which operations have NOT declared what they cost. This is the same ceiling-side
- * discipline as the documentation audit — an undeclared cost is a blind spot, surfaced, never assumed zero.
+ * Cost-coverage audit: which operations have NOT declared what they cost — plus (C024) the background-cost
+ * disciplines: a deferred cost that resolves no principal would bill to @unattributed (fail LOUD, never silent),
+ * and an attribution read off an UNVERIFIED event payload is attacker-controllable. Walks paths AND webhooks.
  */
 export function costAudit(doc: OpenAPIv4Document): CostFinding[] {
   const findings: CostFinding[] = [];
-  for (const [path, piRaw] of Object.entries(doc.paths ?? {})) {
-    for (const [name, reqRaw] of Object.entries((piRaw as PathItem).requests ?? {})) {
-      const model = costOf(reqRaw as Request);
-      if (!model) {
-        findings.push({ code: "no-cost-model", severity: "warn", path, operation: name, message: "operation declares no cost — its cost to you is unknown (not assumed zero)" });
-      } else if (!model.components.length) {
-        findings.push({ code: "zero-cost", severity: "info", path, operation: name, message: "operation declares an empty cost model (explicitly free)" });
+  for (const { path, name, model } of costLoci(doc)) {
+    if (!model) {
+      findings.push({ code: "no-cost-model", severity: "warn", path, operation: name, message: "operation declares no cost — its cost to you is unknown (not assumed zero)" });
+      continue;
+    }
+    if (!model.components.length) {
+      findings.push({ code: "zero-cost", severity: "info", path, operation: name, message: "operation declares an empty cost model (explicitly free)" });
+    }
+    if (isDeferredCost(model)) {
+      const attr = model.attribution;
+      const unattributed = !attr || (attr.strategy === "event-expression" && !attr.expression);
+      if (unattributed) {
+        findings.push({ code: "unattributed-background-cost", severity: "warn", path, operation: name, message: `${triggerOf(model)} cost declares no resolvable principal — it would bill to ${UNATTRIBUTED}` });
+      } else if (attr.strategy === "event-expression" && attr.trust !== "verified") {
+        findings.push({ code: "unverified-attribution", severity: "warn", path, operation: name, message: "attribution reads an UNVERIFIED event payload (attacker-controllable) — require a verified signature" });
       }
     }
+    // C026: a cost that claims to reconcile against the actual charge but can't read it falls back to the estimate.
+    if (model.reconciliationBasis === "payload-reconciled" && !model.amountExpression) {
+      findings.push({ code: "reconciliation-incomplete", severity: "warn", path, operation: name, message: "declares payload-reconciled but no amountExpression — the actual charge can't be read; it falls back to the estimate" });
+    }
   }
   return findings;
 }
 
-/** The declared costs across the document, for display (the cockpit/admin show this raw). */
-export function costTable(doc: OpenAPIv4Document): { operation: string; path: string; estimateMicroUsd: number; sources: string[] }[] {
-  const rows: { operation: string; path: string; estimateMicroUsd: number; sources: string[] }[] = [];
-  for (const [path, piRaw] of Object.entries(doc.paths ?? {})) {
-    for (const [name, reqRaw] of Object.entries((piRaw as PathItem).requests ?? {})) {
-      const model = costOf(reqRaw as Request);
-      if (!model) continue;
-      const fixed = model.components.filter((c) => c.basis === "per-call").reduce((s, c) => s + c.microUsd, 0);
-      rows.push({ operation: name, path, estimateMicroUsd: model.estimateMicroUsd ?? fixed, sources: [...new Set(model.components.map((c) => c.source))] });
-    }
+export interface CostRow { operation: string; path: string; estimateMicroUsd: number; sources: string[]; trigger: CostTrigger }
+
+/** The declared costs across the document (paths + webhooks + jobs), for display (the cockpit/admin show this raw). */
+export function costTable(doc: OpenAPIv4Document): CostRow[] {
+  const rows: CostRow[] = [];
+  for (const { path, name, model } of costLoci(doc)) {
+    if (!model) continue;
+    const fixed = model.components.filter((c) => c.basis === "per-call").reduce((s, c) => s + c.microUsd, 0);
+    rows.push({ operation: name, path, estimateMicroUsd: model.estimateMicroUsd ?? fixed, sources: [...new Set(model.components.map((c) => c.source))], trigger: triggerOf(model) });
   }
   return rows;
 }

package/src/event.ts

@@ -0,0 +1,112 @@
+/**
+ * Background-event cost (C024 runtime counterpart). The request meter (meter.ts) is Hono-Context-bound —
+ * `principalOf(c: Context)` reads a live caller. A FIRED event (a Stripe webhook, a cron tick, a queue message)
+ * has NO such Context, so this is the separate Context-free path the council flagged: given the fired event payload
+ * + the operation's declared cost model (with its `trigger` / `attribution` / `idempotencyKey`), it resolves WHO
+ * pays (the runtime attribution expression — never the static matcher) and a DEDUPE key, and builds the CostEvent.
+ *
+ * Pure + reproducible: `at` is passed in, the event payload is the only input, nothing reads ambient state.
+ */
+import { computeCost } from "./contract";
+import { UNATTRIBUTED, type CostModel, type CostEvent, type UsageReport } from "./types";
+import type { CostSink } from "./meter";
+
+/**
+ * Resolve a C018 runtime-expression against a fired event. Supports `{$event.id}`, `{$event.<key>}`, and a
+ * JSON-Pointer tail `{$event.body#/customer}` / `{$event.body#/data/object/customer}`. Returns the stringified
+ * value, or undefined when it doesn't resolve. Pure; never throws (an unresolvable expression is undefined, not an error).
+ */
+export function resolveEventExpression(expression: string, event: Record<string, unknown>): string | undefined {
+  const m = /^\{\$event\.([^}]+)\}$/.exec(expression.trim());
+  if (!m) return undefined;
+  const [base, pointer] = m[1].split("#");
+  let node: unknown = base ? (event as Record<string, unknown>)[base] : event;
+  if (pointer) {
+    for (const raw of pointer.split("/").filter(Boolean)) {
+      const seg = raw.replace(/~1/g, "/").replace(/~0/g, "~"); // JSON-Pointer unescape
+      if (node && typeof node === "object") node = (node as Record<string, unknown>)[seg];
+      else return undefined;
+    }
+  }
+  return node == null ? undefined : String(node);
+}
+
+/**
+ * Resolve the principal charged for a fired event per the model's attribution strategy. Returns the `@unattributed`
+ * sentinel (never silent) when nothing resolves: `session`/`job-stamped` use the supplied principal; `event-expression`
+ * reads it from the payload. NOTE: an `event-expression` with `trust !== "verified"` is attacker-controllable — the
+ * caller MUST gate it behind a verified webhook signature before trusting the result for billing.
+ */
+export function attributePrincipal(model: CostModel, event: Record<string, unknown>, suppliedPrincipal?: string): string {
+  const attr = model.attribution;
+  if (!attr || attr.strategy === "session" || attr.strategy === "job-stamped") return suppliedPrincipal ?? UNATTRIBUTED;
+  if (attr.strategy === "event-expression" && attr.expression) return resolveEventExpression(attr.expression, event) ?? UNATTRIBUTED;
+  return UNATTRIBUTED;
+}
+
+export interface EventCostInput {
+  /** the operation name whose cost fired (the webhook/op by-name handle). */
+  operation: string;
+  /** its declared cost model (carrying trigger / attribution / idempotencyKey). */
+  model: CostModel;
+  /** the fired event payload. */
+  event: Record<string, unknown>;
+  /** wall-clock ms (passed in — reproducible). */
+  at: number;
+  /** any metered third-party usage the handler measured. */
+  usage?: UsageReport[];
+  /** for `session`/`job-stamped` attribution: the principal the job/session carries. */
+  suppliedPrincipal?: string;
+}
+
+/**
+ * Resolve the ACTUAL charged amount (in µ$) from the event when the model is `payload-reconciled` (C026), else
+ * undefined. Reads the runtime amount-expression (e.g. the Stripe event amount) and converts from its declared unit
+ * — so the recorded cost is the third party's real invoice line, not the operator's declared estimate.
+ */
+export function reconciledAmount(model: CostModel, event: Record<string, unknown>): number | undefined {
+  if (model.reconciliationBasis !== "payload-reconciled" || !model.amountExpression) return undefined;
+  const raw = resolveEventExpression(model.amountExpression, event);
+  const n = raw == null ? NaN : Number(raw);
+  if (!Number.isFinite(n)) return undefined;
+  const unit = model.amountUnit ?? "micro-usd";
+  return Math.round(unit === "cents" ? n * 10_000 : unit === "usd" ? n * 1_000_000 : n);
+}
+
+/** Build the CostEvent for a FIRED background event — pure. Stamps the trigger, resolves principal + dedupeKey,
+ *  and (C026) uses the payload-reconciled amount as the authoritative total when the model declares one. */
+export function eventCostEvent(input: EventCostInput): CostEvent {
+  let { breakdown, totalMicroUsd } = computeCost(input.model, input.usage ?? []);
+  const reconciled = reconciledAmount(input.model, input.event);
+  if (reconciled !== undefined) {
+    const source = input.model.components[0]?.source ?? "reconciled";
+    breakdown = [{ source, microUsd: reconciled }]; // the actual charge replaces the estimate
+    totalMicroUsd = reconciled;
+  }
+  const dedupeKey = input.model.idempotencyKey ? resolveEventExpression(input.model.idempotencyKey, input.event) : undefined;
+  return {
+    at: input.at,
+    operation: input.operation,
+    principal: attributePrincipal(input.model, input.event, input.suppliedPrincipal),
+    trigger: input.model.trigger ?? "synchronous",
+    ...(dedupeKey ? { dedupeKey } : {}),
+    ...(reconciled !== undefined ? { reconciled: true } : {}),
+    breakdown,
+    totalMicroUsd,
+  };
+}
+
+/**
+ * Record a fired event's cost into a sink, deduped by its `dedupeKey` against `seen` (so at-least-once delivery
+ * can't double-charge). Returns the recorded event, or null when it was a duplicate. `seen` is the app's dedup
+ * store (an in-memory Set for dev; a durable KV/DO for prod).
+ */
+export async function recordEventCost(sink: CostSink, input: EventCostInput, seen?: Set<string>): Promise<CostEvent | null> {
+  const event = eventCostEvent(input);
+  if (event.dedupeKey && seen) {
+    if (seen.has(event.dedupeKey)) return null; // already recorded — at-least-once delivery
+    seen.add(event.dedupeKey);
+  }
+  await sink.record(event);
+  return event;
+}

package/src/index.ts

@@ -7,11 +7,20 @@
  */
 export {
   type CostBasis, type CostComponent, type CostModel, type UsageReport, type CostEvent, formatMicroUsd,
+  // C024 — background-event cost: WHEN it fires (trigger) + WHO pays (attribution), orthogonal to basis (HOW it meters).
+  type CostTrigger, type CostAttribution, UNATTRIBUTED,
+  // C026 — reconciliation: declared-estimate vs the third party's actual (payload-reconciled) charge.
+  type ReconciliationBasis,
 } from "./types";
 export {
   COST_EXT, annotateCosts, costOf, costAudit, costTable, computeCost, type CostFinding,
+  eachOperation, eachJob, triggerOf, isDeferredCost, type CostRow,
 } from "./contract";
 export {
   costMeter, recordUsage, MemoryCostSink, type CostSink, type CostMeterOptions,
 } from "./meter";
+// C024 — the Context-free background-event cost path (a fired webhook/cron/queue event, no live caller).
+export {
+  resolveEventExpression, attributePrincipal, eventCostEvent, recordEventCost, reconciledAmount, type EventCostInput,
+} from "./event";
 export { summarize, principalCost, type CostSummary } from "./ledger";

package/src/types.ts

@@ -25,12 +25,68 @@ export interface CostComponent {
   description?: string;
 }
 
+/**
+ * WHEN/WHAT fires a cost (C024) — a STATIC, locally-decidable enum (the same KIND as {@link CostBasis}). Default
+ * "synchronous" ⇒ every existing declaration is unchanged (zero migration). Strictly DESCRIPTIVE: it names where the
+ * cost accrues, asserting NO event-channel / delivery-protocol semantics — the fence that keeps it orthogonal to
+ * C018's deliberately-deferred async scope. Three axes stay orthogonal: `basis` = HOW it meters, `trigger` = WHEN it
+ * fires, `attribution` = WHO pays.
+ */
+export type CostTrigger =
+  | "synchronous"        // accrues when this operation's own route runs (default; backwards-compatible)
+  | "webhook-received"   // accrues when an incoming webhook (C018) fires
+  | "scheduled"          // accrues when a scheduled / cron job runs
+  | "queue-consumed"     // accrues when a queue consumer processes a message
+  | "callback-completed"; // accrues when an out-of-band callback (C018) completes
+
+/**
+ * WHO is charged when a third party fires the event with no live session (C024) — a declared STRATEGY the runtime
+ * resolves a concrete principal from, modeled on `SulukRateLimit.key`. The `expression` is RUNTIME-ONLY: a C018
+ * runtime-expression that NEVER enters the static matcher (D1-consistent, exactly as C018 walls its callback keys).
+ */
+export interface CostAttribution {
+  /** session = the live caller (the existing path); event-expression = read the principal from the event payload at
+   *  runtime; job-stamped = the job carries its own principal. */
+  strategy: "session" | "event-expression" | "job-stamped";
+  /** for event-expression: a C018 runtime-expression (e.g. "{$event.body#/customer}"). Runtime-resolved only. */
+  expression?: string;
+  /** is the attribution input authentic? An event-expression off an UNVERIFIED webhook payload is attacker-controlled
+   *  — honor it as authoritative only when "verified" (a signature/secret check the runtime performs). */
+  trust?: "verified" | "unverified-payload";
+}
+
 export interface CostModel {
   components: CostComponent[];
   /** Optional typical total for one call (µ$), for display + tests when usage isn't yet known. */
   estimateMicroUsd?: number;
+  /** WHEN/WHAT fires this cost (C024; default "synchronous"). STATIC — decouples accrual-time from the declaring op. */
+  trigger?: CostTrigger;
+  /** the by-name handle (C009) of the webhook/callback/op whose firing accrues this cost (for a non-sync trigger). */
+  triggerRef?: string;
+  /** WHO is charged when there is no live session (runtime strategy; the expression never enters the static matcher). */
+  attribution?: CostAttribution;
+  /** a runtime-expression yielding a stable id to DEDUPE at-least-once delivery (e.g. "{$event.id}") — prevents
+   *  double-counting a cost charged on both the receipt op and the triggered op. Runtime-only. */
+  idempotencyKey?: string;
+  /**
+   * How the amount RECONCILES with the third party's actual charge (C026; default "declared-estimate"). A declared
+   * estimate is a guess; "payload-reconciled" reads the ACTUAL charged amount from the event at runtime (the real
+   * invoice line — proration/tax/refund included), so the recorded cost is authoritative, not an approximation.
+   */
+  reconciliationBasis?: ReconciliationBasis;
+  /** for "payload-reconciled": a runtime-expression yielding the ACTUAL amount (e.g. "{$event.body#/amount}").
+   *  Runtime-only — never the static matcher. Interpreted in `amountUnit`. */
+  amountExpression?: string;
+  /** the unit `amountExpression` yields (default "micro-usd"). "cents" (Stripe) → ×10_000; "usd" → ×1_000_000. */
+  amountUnit?: "micro-usd" | "cents" | "usd";
 }
 
+/** Whether a cost's amount is a declared guess or read from the event payload at runtime (C026). */
+export type ReconciliationBasis = "declared-estimate" | "payload-reconciled";
+
+/** The principal sentinel for a background cost that resolved to NO principal — billed to nobody, but never silent. */
+export const UNATTRIBUTED = "@unattributed" as const;
+
 /** A measured usage report for one variable component during a request (e.g. {source:"openai", units: 1350}). */
 export interface UsageReport {
   source: string;
@@ -47,6 +103,12 @@ export interface CostEvent {
   operation: string;
   /** The frontend action that triggered it (a button-click id), if the client tagged the request. */
   action?: string;
+  /** How this cost fired (C024; default "synchronous"). A non-sync value marks a background charge. */
+  trigger?: CostTrigger;
+  /** Dedupe id for at-least-once event delivery — two events with the same key are the SAME charge (C024). */
+  dedupeKey?: string;
+  /** true ⇒ totalMicroUsd is the third party's ACTUAL charge read from the event (C026), not a declared estimate. */
+  reconciled?: boolean;
   /** Per-source breakdown (µ$). */
   breakdown: { source: string; microUsd: number }[];
   /** Total µ$ for the request. */

package/test/event.test.ts

@@ -0,0 +1,59 @@
+import { test, expect, describe } from "bun:test";
+import {
+  resolveEventExpression, attributePrincipal, eventCostEvent, recordEventCost,
+  MemoryCostSink, UNATTRIBUTED, type CostModel,
+} from "../src/index";
+
+// the motivating case: Stripe fires payment_intent.succeeded → it charges you, attributed to the customer.
+const stripeEvent = { id: "evt_123", type: "payment_intent.succeeded", body: { customer: "cus_42", amount: 2900 } };
+const chargeModel: CostModel = {
+  components: [{ source: "stripe", basis: "per-call", microUsd: 2900 }],
+  trigger: "webhook-received",
+  attribution: { strategy: "event-expression", expression: "{$event.body#/customer}", trust: "verified" },
+  idempotencyKey: "{$event.id}",
+};
+
+describe("C024 runtime — resolve a C018 runtime-expression against a fired event", () => {
+  test("body JSON-pointer, top-level key, and an unresolvable expression", () => {
+    expect(resolveEventExpression("{$event.body#/customer}", stripeEvent)).toBe("cus_42");
+    expect(resolveEventExpression("{$event.id}", stripeEvent)).toBe("evt_123");
+    expect(resolveEventExpression("{$event.body#/missing}", stripeEvent)).toBeUndefined();
+    expect(resolveEventExpression("not-an-expression", stripeEvent)).toBeUndefined();
+  });
+});
+
+describe("C024 runtime — attribute the principal (fail to @unattributed, never silent)", () => {
+  test("event-expression reads the principal from the payload", () => {
+    expect(attributePrincipal(chargeModel, stripeEvent)).toBe("cus_42");
+  });
+  test("session/job-stamped use the supplied principal; missing → @unattributed", () => {
+    expect(attributePrincipal({ components: [], attribution: { strategy: "session" } }, stripeEvent, "u1")).toBe("u1");
+    expect(attributePrincipal({ components: [], attribution: { strategy: "session" } }, stripeEvent)).toBe(UNATTRIBUTED);
+    expect(attributePrincipal({ components: [], attribution: { strategy: "event-expression" } }, stripeEvent)).toBe(UNATTRIBUTED); // no expression
+  });
+});
+
+describe("C024 runtime — build + record the background CostEvent", () => {
+  test("eventCostEvent stamps the trigger, principal, dedupeKey, and the computed total", () => {
+    const e = eventCostEvent({ operation: "stripeCharge", model: chargeModel, event: stripeEvent, at: 1000 });
+    expect(e).toMatchObject({ operation: "stripeCharge", principal: "cus_42", trigger: "webhook-received", dedupeKey: "evt_123", totalMicroUsd: 2900 });
+  });
+
+  test("recordEventCost dedupes at-least-once delivery (the same event id records ONCE)", async () => {
+    const sink = new MemoryCostSink();
+    const seen = new Set<string>();
+    const a = await recordEventCost(sink, { operation: "stripeCharge", model: chargeModel, event: stripeEvent, at: 1000 }, seen);
+    const b = await recordEventCost(sink, { operation: "stripeCharge", model: chargeModel, event: stripeEvent, at: 1001 }, seen); // redelivery
+    expect(a).not.toBeNull();
+    expect(b).toBeNull();                 // deduped — not double-charged
+    expect(sink.events()).toHaveLength(1);
+    expect(sink.events()[0].principal).toBe("cus_42");
+  });
+
+  test("a cost that can't attribute records to @unattributed (visible, not lost)", async () => {
+    const sink = new MemoryCostSink();
+    const orphan: CostModel = { components: [{ source: "stripe", basis: "per-call", microUsd: 500 }], trigger: "webhook-received" };
+    await recordEventCost(sink, { operation: "x", model: orphan, event: stripeEvent, at: 1 });
+    expect(sink.events()[0].principal).toBe(UNATTRIBUTED);
+  });
+});

package/test/jobs.test.ts

@@ -0,0 +1,39 @@
+import { test, expect, describe } from "bun:test";
+import { eachJob, costAudit, costTable } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+// C025: cron + queue jobs have NO inbound Request, so they live in the x-suluk-jobs vendor map (not paths/webhooks).
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "t", version: "1" },
+  paths: {},
+  "x-suluk-jobs": {
+    nightlyRollup: {
+      trigger: "scheduled", schedule: "0 0 * * *",
+      "x-suluk-cost": { components: [{ source: "compute", basis: "per-call", microUsd: 500 }], trigger: "scheduled", attribution: { strategy: "job-stamped" } },
+    },
+    drainEmailQueue: {
+      trigger: "queue-consumed", queue: "emails",
+      "x-suluk-cost": { components: [{ source: "resend", basis: "per-call", microUsd: 100 }], trigger: "queue-consumed" }, // no attribution
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+describe("C025 — x-suluk-jobs: cron/queue cost gets a first-class home", () => {
+  test("eachJob enumerates the jobs map", () => {
+    expect(eachJob(doc).map((j) => j.name).sort()).toEqual(["drainEmailQueue", "nightlyRollup"]);
+    expect(eachJob(doc).find((j) => j.name === "nightlyRollup")?.job.schedule).toBe("0 0 * * *");
+  });
+
+  test("costTable includes job rows with their non-synchronous trigger", () => {
+    const rows = costTable(doc);
+    expect(rows.find((r) => r.operation === "nightlyRollup")).toMatchObject({ path: "jobs/nightlyRollup", trigger: "scheduled", estimateMicroUsd: 500 });
+    expect(rows.find((r) => r.operation === "drainEmailQueue")?.trigger).toBe("queue-consumed");
+  });
+
+  test("costAudit applies the same fail-loud discipline to jobs: a job-stamped job is clean, an unattributed one is flagged", () => {
+    const findings = costAudit(doc);
+    expect(findings.find((f) => f.operation === "nightlyRollup" && f.code === "unattributed-background-cost")).toBeUndefined(); // job-stamped declares its principal
+    expect(findings.find((f) => f.operation === "drainEmailQueue")?.code).toBe("unattributed-background-cost");                 // no attribution → fail loud
+  });
+});

package/test/reconciliation.test.ts

@@ -0,0 +1,42 @@
+import { test, expect, describe } from "bun:test";
+import { eventCostEvent, reconciledAmount, costAudit, annotateCosts, type CostModel } from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+// Stripe fires payment_intent.succeeded with the REAL amount (cents) — reconcile against it, not the estimate.
+const stripeEvent = { id: "evt_1", body: { customer: "cus_9", amount: 3175 } }; // $31.75 actual (incl. tax/proration)
+const reconciledModel: CostModel = {
+  components: [{ source: "stripe", basis: "per-call", microUsd: 29_000_000 }], // declared estimate: $29
+  estimateMicroUsd: 29_000_000,
+  trigger: "webhook-received",
+  reconciliationBasis: "payload-reconciled",
+  amountExpression: "{$event.body#/amount}",
+  amountUnit: "cents",
+  attribution: { strategy: "event-expression", expression: "{$event.body#/customer}", trust: "verified" },
+};
+
+describe("C026 — reconciliation: record the third party's ACTUAL charge, not the estimate", () => {
+  test("reconciledAmount reads the payload amount and converts cents → µ$", () => {
+    expect(reconciledAmount(reconciledModel, stripeEvent)).toBe(31_750_000); // 3175 cents × 10_000
+    expect(reconciledAmount({ ...reconciledModel, amountUnit: "usd" }, { body: { amount: 31.75 } } as never)).toBe(31_750_000);
+    expect(reconciledAmount({ components: [] }, stripeEvent)).toBeUndefined(); // not payload-reconciled
+  });
+
+  test("eventCostEvent uses the reconciled amount as the authoritative total + flags reconciled", () => {
+    const e = eventCostEvent({ operation: "stripeCharge", model: reconciledModel, event: stripeEvent, at: 1 });
+    expect(e.totalMicroUsd).toBe(31_750_000);          // the ACTUAL $31.75, not the declared $29
+    expect(e.reconciled).toBe(true);
+    expect(e.breakdown).toEqual([{ source: "stripe", microUsd: 31_750_000 }]);
+  });
+
+  test("a declared-estimate cost is unchanged (the existing path; no reconciliation)", () => {
+    const e = eventCostEvent({ operation: "x", model: { components: [{ source: "compute", basis: "per-call", microUsd: 500 }], trigger: "scheduled" }, event: stripeEvent, at: 1 });
+    expect(e.totalMicroUsd).toBe(500);
+    expect(e.reconciled).toBeUndefined();
+  });
+
+  test("costAudit flags a payload-reconciled cost that can't read the amount (incomplete)", () => {
+    const doc = { openapi: "4.0.0-candidate", info: { title: "t", version: "1" }, paths: { p: { requests: { op: { method: "post", responses: {} } } } } } as unknown as OpenAPIv4Document;
+    const annotated = annotateCosts(doc, { op: { components: [{ source: "stripe", basis: "per-call", microUsd: 1 }], reconciliationBasis: "payload-reconciled" } }); // no amountExpression
+    expect(costAudit(annotated).find((f) => f.operation === "op" && f.code === "reconciliation-incomplete")).toBeDefined();
+  });
+});

package/test/trigger.test.ts

@@ -0,0 +1,80 @@
+import { test, expect, describe } from "bun:test";
+import {
+  annotateCosts, costAudit, costTable, eachOperation, triggerOf, isDeferredCost, costOf, UNATTRIBUTED,
+  type CostModel,
+} from "../src/index";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+// a doc with a path op + a C018 webhook op
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "t", version: "1" },
+  paths: { order: { requests: { createOrder: { method: "post", responses: {} } } } },
+  webhooks: { stripeCharge: { method: "post", responses: {} } },
+} as unknown as OpenAPIv4Document;
+
+describe("C024 — background-event cost: the three orthogonal axes", () => {
+  test("triggerOf defaults to synchronous; isDeferredCost flags a non-sync trigger", () => {
+    expect(triggerOf(undefined)).toBe("synchronous");
+    expect(triggerOf({ components: [] })).toBe("synchronous");
+    expect(isDeferredCost({ components: [], trigger: "webhook-received" })).toBe(true);
+    expect(isDeferredCost({ components: [] })).toBe(false);
+  });
+
+  test("eachOperation walks paths AND webhooks (the background-cost locus)", () => {
+    expect(eachOperation(doc).map((o) => o.name).sort()).toEqual(["createOrder", "stripeCharge"]);
+    expect(eachOperation(doc).find((o) => o.name === "stripeCharge")?.path).toBe("webhooks/stripeCharge");
+  });
+
+  test("annotateCosts annotates a webhook op; the cost reads back with its trigger", () => {
+    const charge: CostModel = {
+      components: [{ source: "stripe", basis: "per-call", microUsd: 2900 }],
+      trigger: "webhook-received",
+      triggerRef: "stripeCharge",
+      attribution: { strategy: "event-expression", expression: "{$event.body#/customer}", trust: "verified" },
+    };
+    const annotated = annotateCosts(doc, { stripeCharge: charge });
+    const webhook = (annotated as unknown as { webhooks: Record<string, unknown> }).webhooks.stripeCharge;
+    expect(costOf(webhook as never)?.trigger).toBe("webhook-received");
+    // basis is UNCHANGED — the metering axis stays orthogonal to the trigger
+    expect(costOf(webhook as never)?.components[0].basis).toBe("per-call");
+  });
+});
+
+describe("C024 — the fail-loud attribution disciplines (audit)", () => {
+  test("a deferred cost with NO attribution → unattributed-background-cost (warn, never silent)", () => {
+    const annotated = annotateCosts(doc, { stripeCharge: { components: [{ source: "stripe", basis: "per-call", microUsd: 2900 }], trigger: "webhook-received" } });
+    const f = costAudit(annotated).find((x) => x.operation === "stripeCharge");
+    expect(f?.code).toBe("unattributed-background-cost");
+    expect(f?.message).toContain(UNATTRIBUTED);
+  });
+
+  test("a deferred cost reading an UNVERIFIED payload → unverified-attribution (attacker-controllable)", () => {
+    const annotated = annotateCosts(doc, { stripeCharge: { components: [{ source: "stripe", basis: "per-call", microUsd: 2900 }], trigger: "webhook-received", attribution: { strategy: "event-expression", expression: "{$event.body#/customer}" } } });
+    expect(costAudit(annotated).find((x) => x.operation === "stripeCharge")?.code).toBe("unverified-attribution");
+  });
+
+  test("a deferred cost with a VERIFIED event attribution is clean (no background finding)", () => {
+    const annotated = annotateCosts(doc, { stripeCharge: { components: [{ source: "stripe", basis: "per-call", microUsd: 2900 }], trigger: "webhook-received", attribution: { strategy: "event-expression", expression: "{$event.body#/customer}", trust: "verified" } } });
+    const codes = costAudit(annotated).filter((x) => x.operation === "stripeCharge").map((x) => x.code);
+    expect(codes).not.toContain("unattributed-background-cost");
+    expect(codes).not.toContain("unverified-attribution");
+  });
+
+  test("a SYNCHRONOUS op is never flagged for attribution (the default path is unchanged)", () => {
+    const annotated = annotateCosts(doc, { createOrder: { components: [{ source: "compute", basis: "per-call", microUsd: 10 }] } });
+    expect(costAudit(annotated).filter((x) => x.operation === "createOrder").map((x) => x.code)).not.toContain("unattributed-background-cost");
+  });
+});
+
+describe("C024 — costTable surfaces the trigger across paths + webhooks", () => {
+  test("the table includes the webhook row with its trigger", () => {
+    const annotated = annotateCosts(doc, {
+      createOrder: { components: [{ source: "compute", basis: "per-call", microUsd: 10 }] },
+      stripeCharge: { components: [{ source: "stripe", basis: "per-call", microUsd: 2900 }], trigger: "webhook-received" },
+    });
+    const rows = costTable(annotated);
+    expect(rows.find((r) => r.operation === "createOrder")?.trigger).toBe("synchronous");
+    expect(rows.find((r) => r.operation === "stripeCharge")).toMatchObject({ trigger: "webhook-received", estimateMicroUsd: 2900 });
+  });
+});