@suluk/cost 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,204 @@
+<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, plus a runtime meter for what every request actually cost — traced from the frontend action down to each third party.</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
+```
+
+`hono` is an **optional** peer dependency — needed only for the request-time middleware (`costMeter`,
+`recordUsage`). The contract, event, and ledger helpers have no runtime deps beyond `@suluk/core`.
+
+## What it does
+
+You can't price a user without knowing what they cost you. `@suluk/cost` makes cost a first-class,
+declared part of the contract — and then meters the real thing:
+
+- **Declare cost on the contract.** Attach a `CostModel` to each operation as the `x-suluk-cost`
+  vendor extension. Like every Suluk facet it bubbles: it survives the 3.1 downgrade (3.1 keeps
+  `x-*`), Scalar/Swagger render it, and a coverage **audit** can flag operations that never declared
+  a cost (unknown ≠ assumed zero).
+- **Meter the actual cost per request.** A Hono middleware records what each request *did* cost —
+  fixed (per-call) components plus metered third-party usage the handler reported — attributed all the
+  way down: frontend action → operation → per-source breakdown.
+- **Bill background events too.** A fired webhook / cron tick / queue message has no live caller, so a
+  separate Context-free path resolves **who pays** (a runtime attribution expression), dedupes
+  at-least-once delivery, and reconciles the declared estimate against the third party's *actual*
+  charge read from the event payload.
+- **Read the raw ledger.** Aggregate cost events by principal, operation, action, and source. All money
+  is integer **micro-USD** (1 USD = 1,000,000 µ$) — the rawest representation. We display it as-is and
+  let you build pricing on top.
+
+## When to reach for it
+
+- Any metered or usage-priced API — anything where a single user can cost you real money (LLM tokens,
+  egress, downstream third-party calls) and you need the per-user picture to price them.
+- When you want cost to be *auditable* in CI: `costAudit` is the coverage gate (every money-moving op
+  must declare what it costs).
+- Pairs with **`@suluk/stripe`** for the billing side — `@suluk/cost` produces the raw ledger; Stripe
+  turns it into invoices/metered subscriptions. This package never imposes pricing, margins, or limits.
+
+## Usage
+
+### 1. Declare cost as a contract facet
+
+```ts
+import { annotateCosts, costAudit, costTable, type CostModel } from "@suluk/cost";
+import { emitV4 } from "@suluk/hono";
+
+const ask: CostModel = {
+  components: [
+    { source: "compute", basis: "per-call", microUsd: 50 },
+    { source: "openai", basis: "per-1k-tokens", microUsd: 2000, description: "$0.002 / 1k tokens" },
+  ],
+  estimateMicroUsd: 1050, // typical total for display/tests before usage is known
+};
+
+const { document } = emitV4(/* operations… */);
+
+// Set x-suluk-cost on each named operation (returns a new doc; covers paths + webhooks).
+const annotated = annotateCosts(document, { ask });
+
+// Coverage audit — which operations never declared a cost (warns), plus background-cost disciplines.
+for (const f of costAudit(annotated)) console.warn(f.code, f.operation, f.message);
+
+// The declared costs, raw, for an admin/cockpit table.
+console.table(costTable(annotated)); // [{ operation, path, estimateMicroUsd, sources, trigger }]
+```
+
+### 2. Meter the actual cost at runtime (Hono)
+
+```ts
+import { costMeter, recordUsage, MemoryCostSink } from "@suluk/cost";
+import { Hono } from "hono";
+
+const sink = new MemoryCostSink(); // swap in D1 / a queue in production
+const app = new Hono<{ Variables: { operation: string; principal: string } }>();
+
+app.use("*", costMeter({
+  sink,
+  costs: { ask },                                 // operation name → declared CostModel
+  operationOf: (c) => c.get("operation"),         // resolve the op name for this request
+  principalOf: (c) => c.get("principal"),         // resolve the user id (optional)
+  // actionHeader defaults to "x-suluk-action"; now defaults to () => Date.now()
+}));
+
+app.post("/ask", (c) => {
+  recordUsage(c, "openai", 2000); // report MEASURED third-party usage for THIS request
+  return c.json({ answer: "42" });
+});
+// → records a CostEvent: { operation: "ask", principal, action, breakdown, totalMicroUsd }
+```
+
+`computeCost(model, usage)` is the pure core the meter uses — call it directly to get the
+`{ breakdown, totalMicroUsd }` for a model + measured usage, e.g. for previews or tests.
+
+### 3. Bill a background event (webhook / cron / queue)
+
+A fired event has no Hono `Context`, so it gets a Context-free path. The model declares **when** it
+fires (`trigger`), **who pays** (`attribution`), and how it **reconciles** with the actual charge:
+
+```ts
+import { recordEventCost, type CostModel } from "@suluk/cost";
+
+// Stripe fires payment_intent.succeeded → it charged you, attributed to the customer.
+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}",       // dedupe at-least-once delivery
+  reconciliationBasis: "payload-reconciled",
+  amountExpression: "{$event.body#/amount}", // read the ACTUAL charge from the payload…
+  amountUnit: "cents",                       // …in cents (Stripe) → ×10_000 into µ$
+};
+
+const event = { id: "evt_123", type: "payment_intent.succeeded", body: { customer: "cus_42", amount: 2900 } };
+const seen = new Set<string>(); // an in-memory dedupe store for dev; a durable KV/DO in prod
+
+// Resolves the principal, dedupes by idempotencyKey, and records — returns null on a redelivery.
+const recorded = await recordEventCost(
+  sink,
+  { operation: "stripeCharge", model: chargeModel, event, at: Date.now() },
+  seen,
+);
+```
+
+> Security: an `event-expression` off an **unverified** payload is attacker-controllable. Gate it
+> behind a verified webhook signature and set `trust: "verified"` — `costAudit` flags
+> `unverified-attribution` otherwise. A cost that resolves no principal bills to the `UNATTRIBUTED`
+> (`@unattributed`) sentinel — fail loud, never silent.
+
+### 4. Read the raw ledger
+
+```ts
+import { summarize, principalCost, formatMicroUsd } from "@suluk/cost";
+
+const events = sink.events();
+const totals = summarize(events);
+// { total, count, byPrincipal, byOperation, byAction, bySource } — all in µ$
+
+console.log("what did user_42 cost me?", formatMicroUsd(principalCost(events, "user_42").total));
+```
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `annotateCosts(doc, costs)` | Set `x-suluk-cost` on each named operation; returns a new doc. |
+| `costOf(req)` / `triggerOf(model)` / `isDeferredCost(model)` | Read a request's model; its trigger (default `synchronous`); whether the cost is a background event. |
+| `costAudit(doc)` | Coverage + discipline audit → `CostFinding[]` (no-cost-model, zero-cost, unattributed/unverified background cost, reconciliation-incomplete). |
+| `costTable(doc)` | The declared costs (paths + webhooks + jobs) as `CostRow[]` for display. |
+| `eachOperation(doc)` / `eachJob(doc)` | Walk every cost locus — path requests, webhooks, and C025 jobs. |
+| `computeCost(model, usage)` | Pure: `{ breakdown, totalMicroUsd }` from a model + measured usage. |
+| `costMeter(opts)` | Hono middleware that records a `CostEvent` per request. |
+| `recordUsage(c, source, units)` | A handler reports measured third-party usage for the current request. |
+| `MemoryCostSink` / `CostSink` | In-memory sink for dev/tests; the `record(event)` port you implement for prod. |
+| `resolveEventExpression(expr, event)` | Resolve a `{$event.…}` runtime-expression (top-level key or JSON-Pointer) against a fired event. |
+| `attributePrincipal(model, event, supplied?)` | Resolve who pays for a fired event; `@unattributed` when nothing resolves. |
+| `reconciledAmount(model, event)` | The actual charge (µ$) read from the payload when `payload-reconciled`. |
+| `eventCostEvent(input)` / `recordEventCost(sink, input, seen?)` | Build / record a background `CostEvent` (deduped by `idempotencyKey`). |
+| `summarize(events)` / `principalCost(events, principal)` | Aggregate the ledger; one principal's slice. |
+| `formatMicroUsd(µ$)` | Display µ$ as a `$` string (storage stays integer). |
+| `COST_EXT` / `UNATTRIBUTED` | The `x-suluk-cost` extension key; the no-principal sentinel. |
+
+The cost-model vocabulary: `CostBasis` (`per-call`, `per-unit`, `per-token`, `per-1k-tokens`,
+`per-second`, `per-request`, `per-mb`), `CostTrigger` (`synchronous`, `webhook-received`, `scheduled`,
+`queue-consumed`, `callback-completed`), `CostAttribution`, and `ReconciliationBasis` — three
+orthogonal axes: `basis` = HOW it meters, `trigger` = WHEN it fires, `attribution` = WHO pays.
+
+## Boundary
+
+This package **measures and displays** cost — it does not price, charge, or persist. It stays
+honestly raw on purpose:
+
+- **Inject the sink.** `costMeter`/`recordEventCost` write `CostEvent`s to a `CostSink` *you* provide.
+  `MemoryCostSink` is for dev/tests; production swaps in D1, a queue, or a Durable Object. The
+  package never opens a database.
+- **Inject the inputs.** Wall-clock (`now` / `at`), the principal resolver, the dedupe store (`seen`),
+  and the operation matcher are all passed in — so events are reproducible and testable, and nothing
+  reads ambient state.
+- **Pricing lives downstream.** Margins, plans, limits, and invoices are the consumer's to build —
+  typically via **`@suluk/stripe`**, which turns this ledger into metered billing. `@suluk/cost`
+  stops at the raw µ$ picture.
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,14 +1,25 @@
 {
   "name": "@suluk/cost",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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.13"
 },
 "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.5",
+"@suluk/openapi-compat": "^0.1.3",
 "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,27 @@
  */
 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,
+  // C044 — settlement: HOW the cost is recovered (credit | rate-limited | free).
+  type SettlementMethod, type CostSettlement,
 } from "./types";
+// C044 — settlement audit (every priced op names a lever) + the errors a request's facets imply.
+export {
+  settlementOf, settlementAudit, impliedErrorStatuses, settlementRollup,
+  type SettlementFinding, type SettlementSeverity, type SettlementRollup,
+} from "./settlement";
 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/settlement.ts

@@ -0,0 +1,93 @@
+/**
+ * Cost SETTLEMENT (C044) — how a declared cost is RECOVERED from the user. The fifth orthogonal cost axis. Promotes a
+ * real cowpath: toolfactory's governance gate already checks "every cost names a lever — credit | rate-limit | free";
+ * this makes that a first-class, Suluk-derived facet. Also derives the HTTP errors a request's facets IMPLY (the
+ * generic form of toolfactory's errors-gate). Pure functions of the declared facets — never a request value.
+ */
+import type { OpenAPIv4Document, Request } from "@suluk/core";
+import { eachOperation, costOf } from "./contract";
+import type { CostModel, CostSettlement } from "./types";
+
+const ext = (req: Request) => req as Request & Record<string, unknown>;
+
+/** The settlement declared on an operation's cost. */
+export function settlementOf(req: Request): CostSettlement | undefined {
+  return costOf(req)?.settlement;
+}
+
+const isPriced = (cost: CostModel | undefined): boolean =>
+  !!cost && (((cost.estimateMicroUsd ?? 0) > 0) || (cost.components ?? []).some((c) => (c.microUsd ?? 0) > 0));
+
+export type SettlementSeverity = "high" | "medium" | "low";
+export interface SettlementFinding {
+  rule: string;
+  severity: SettlementSeverity;
+  operation: string;
+  path: string;
+  message: string;
+  fix: string;
+}
+
+/**
+ * Audit that every PRICED operation names HOW it is settled, and that the named lever is coherent — the generic form of
+ * toolfactory's "cost names a lever" governance check.
+ */
+export function settlementAudit(doc: OpenAPIv4Document): SettlementFinding[] {
+  const findings: SettlementFinding[] = [];
+  for (const { path, name, req } of eachOperation(doc)) {
+    const cost = costOf(req);
+    const s = cost?.settlement;
+    const add = (rule: string, severity: SettlementSeverity, message: string, fix: string) => findings.push({ rule, severity, operation: name, path, message, fix });
+
+    if (isPriced(cost) && !s) {
+      add("cost-without-settlement", "medium", `priced op '${name}' does not name how its cost is paid`, "add x-suluk-cost.settlement: { method: 'credit' | 'rate-limited' | 'free' }");
+    }
+    if (s?.method === "rate-limited" && !ext(req)["x-suluk-ratelimit"]) {
+      add("rate-limited-without-cap", "high", `op '${name}' is settled by rate-limiting but declares no x-suluk-ratelimit — there is no cap to BE the payment`, "add an x-suluk-ratelimit (the free-tier cap), or change settlement.method");
+    }
+    if (s?.method === "credit" && s.credits == null && !cost?.estimateMicroUsd) {
+      add("credit-without-amount", "medium", `op '${name}' is settled by credit but declares neither settlement.credits nor an estimateMicroUsd to debit`, "set settlement.credits (or x-suluk-cost.estimateMicroUsd) so the runtime knows the debit");
+    }
+    if (s?.method === "free" && isPriced(cost)) {
+      add("free-but-priced", "low", `op '${name}' is settled as free yet declares a positive cost — the operator absorbs it`, "confirm intended, or change settlement.method to credit / rate-limited");
+    }
+  }
+  return findings;
+}
+
+/**
+ * The HTTP error statuses a request's FACETS imply (the generic form of toolfactory's errors-gate): a contract should
+ * declare these responses. credit→402 · authenticated/admin→401 · owner-scope→403 · rate-limit→429 · an upstream
+ * third-party call (a `per-request` cost component)→502. A pure function of the declared facets.
+ */
+export function impliedErrorStatuses(req: Request): number[] {
+  const out = new Set<number>();
+  const cost = costOf(req);
+  const access = ext(req)["x-suluk-access"] as { requires?: string; scope?: string } | undefined;
+  if (cost?.settlement?.method === "credit") out.add(402);
+  if (access?.requires === "authenticated" || access?.requires === "admin") out.add(401);
+  if (access?.scope) out.add(403);
+  if (ext(req)["x-suluk-ratelimit"]) out.add(429);
+  if ((cost?.components ?? []).some((c) => c.basis === "per-request")) out.add(502);
+  return [...out].sort((a, b) => a - b);
+}
+
+export interface SettlementRollup {
+  credit: number;
+  ["rate-limited"]: number;
+  free: number;
+  /** priced ops with NO settlement declared (the gap). */
+  unsettled: number;
+}
+
+/** A quick "how is this API monetized" tally — ops grouped by settlement method (+ priced-but-unsettled). */
+export function settlementRollup(doc: OpenAPIv4Document): SettlementRollup {
+  const r: SettlementRollup = { credit: 0, "rate-limited": 0, free: 0, unsettled: 0 };
+  for (const { req } of eachOperation(doc)) {
+    const cost = costOf(req);
+    const m = cost?.settlement?.method;
+    if (m) r[m]++;
+    else if (isPriced(cost)) r.unsettled++;
+  }
+  return r;
+}

package/src/types.ts

@@ -25,12 +25,89 @@ 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";
+  /** HOW the operator RECOVERS this cost (C044). The fifth orthogonal axis — basis=how-meters · trigger=when-fires ·
+   *  attribution=who-pays · reconciliation=declared-vs-actual · **settlement=how-recovered**. */
+  settlement?: CostSettlement;
 }
 
+/** 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";
+
+/**
+ * HOW a declared cost is RECOVERED from the user (C044). `rate-limited` ⇒ free to the user — the cost is "paid" by
+ * CAPPING usage, so the op's `x-suluk-ratelimit` IS the settlement (no money moves). `credit` ⇒ the user pays credits
+ * (a balance is debited). `free` ⇒ truly free (the operator absorbs any cost). A purely STATIC fact (an enum + an
+ * integer + names) — never a request value, so it rides the x-suluk-cost wall (matcher-invisible since C024).
+ */
+export type SettlementMethod = "credit" | "rate-limited" | "free";
+
+export interface CostSettlement {
+  method: SettlementMethod;
+  /** method:"credit" — the credits debited per call (a non-negative integer). Omitted ⇒ derived from
+   *  `estimateMicroUsd` × the operator's credit rate (a runtime concern, not declared here). */
+  credits?: number;
+  /** method:"rate-limited" — what happens when the free cap (`x-suluk-ratelimit`) is exhausted: refuse, or fall back
+   *  to charging credits. Advisory; the runtime enforces it. */
+  overflow?: "deny" | "credit";
+}
+
+/** 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 +124,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/settlement.test.ts

@@ -0,0 +1,91 @@
+import { test, expect, describe } from "bun:test";
+import { settlementOf, settlementAudit, impliedErrorStatuses, settlementRollup, type CostSettlement } from "../src/index";
+import type { OpenAPIv4Document, Request } from "@suluk/core";
+
+/**
+ * C044 — cost settlement (HOW a cost is recovered: credit | rate-limited | free). The fifth orthogonal cost axis.
+ * settlementAudit is the generic form of toolfactory's "cost names a lever" governance check; impliedErrorStatuses is
+ * the generic errors-gate. All pure functions of the declared facets — never a request value (rides the x-suluk-cost wall).
+ */
+const op = (cost: unknown, extra: Record<string, unknown> = {}): Request => ({ method: "post", "x-suluk-cost": cost, ...extra }) as unknown as Request;
+const doc = (requests: Record<string, Request>): OpenAPIv4Document => ({ openapi: "4.0.0-candidate", info: { title: "T" }, paths: { "/x": { requests } } }) as unknown as OpenAPIv4Document;
+
+describe("settlementOf", () => {
+  test("reads the settlement off the cost facet", () => {
+    expect(settlementOf(op({ estimateMicroUsd: 1000, settlement: { method: "credit", credits: 10 } }))).toEqual({ method: "credit", credits: 10 });
+    expect(settlementOf(op({ estimateMicroUsd: 1000 }))).toBeUndefined();
+  });
+});
+
+describe("settlementAudit — every priced op names a coherent lever", () => {
+  test("a priced op with no settlement is flagged", () => {
+    const f = settlementAudit(doc({ priced: op({ estimateMicroUsd: 200 }) }));
+    expect(f.map((x) => x.rule)).toContain("cost-without-settlement");
+  });
+
+  test("rate-limited WITHOUT an x-suluk-ratelimit is a high finding (no cap to be the payment)", () => {
+    const f = settlementAudit(doc({ bad: op({ estimateMicroUsd: 500, settlement: { method: "rate-limited" } }) }));
+    const hit = f.find((x) => x.rule === "rate-limited-without-cap");
+    expect(hit?.severity).toBe("high");
+  });
+
+  test("rate-limited WITH a cap is clean", () => {
+    const f = settlementAudit(doc({ ok: op({ estimateMicroUsd: 0, components: [], settlement: { method: "rate-limited" } }, { "x-suluk-ratelimit": { windowMs: 1000, maxRequests: 10, key: "ip" } }) }));
+    expect(f.some((x) => x.rule === "rate-limited-without-cap")).toBe(false);
+  });
+
+  test("credit with neither credits nor an estimate is flagged", () => {
+    const f = settlementAudit(doc({ c: op({ components: [{ source: "x", basis: "per-call", microUsd: 5 }], settlement: { method: "credit" } }) }));
+    expect(f.map((x) => x.rule)).toContain("credit-without-amount");
+  });
+
+  test("free-but-priced is a low finding (operator absorbs it)", () => {
+    const f = settlementAudit(doc({ f: op({ estimateMicroUsd: 300, settlement: { method: "free" } }) }));
+    const hit = f.find((x) => x.rule === "free-but-priced");
+    expect(hit?.severity).toBe("low");
+  });
+
+  test("a well-formed credit op raises nothing", () => {
+    const f = settlementAudit(doc({ good: op({ estimateMicroUsd: 1000, settlement: { method: "credit", credits: 10 } }) }));
+    expect(f).toEqual([]);
+  });
+});
+
+describe("impliedErrorStatuses — errors a request's facets imply", () => {
+  test("credit→402, authenticated→401, owner-scope→403, rate-limit→429", () => {
+    const r = op({ settlement: { method: "credit", credits: 5 } }, { "x-suluk-access": { requires: "authenticated", scope: "owner-only" }, "x-suluk-ratelimit": { windowMs: 1, maxRequests: 1, key: "ip" } });
+    expect(impliedErrorStatuses(r)).toEqual([401, 402, 403, 429]);
+  });
+
+  test("an upstream per-request cost component implies 502", () => {
+    expect(impliedErrorStatuses(op({ components: [{ source: "openai", basis: "per-request", microUsd: 100 }] }))).toEqual([502]);
+  });
+
+  test("a public, free op implies no error statuses", () => {
+    expect(impliedErrorStatuses(op({ settlement: { method: "free" } }))).toEqual([]);
+  });
+});
+
+describe("settlementRollup — how the API is monetized", () => {
+  test("tallies ops by method + counts priced-but-unsettled", () => {
+    const d = doc({
+      a: op({ estimateMicroUsd: 100, settlement: { method: "credit", credits: 1 } }),
+      b: op({ components: [], settlement: { method: "rate-limited" } }, { "x-suluk-ratelimit": { windowMs: 1, maxRequests: 1, key: "ip" } }),
+      c: op({ estimateMicroUsd: 50 }), // priced, no settlement
+    });
+    expect(settlementRollup(d)).toEqual({ credit: 1, "rate-limited": 1, free: 0, unsettled: 1 });
+  });
+});
+
+describe("D1 wall — settlement carries only STATIC facts, never a request-value selector", () => {
+  // TYPE-LINKED: every CostSettlement field classifies as an enum or a scalar — none extracts a request VALUE (no
+  // expression / pointer). Adding a value-extracting field fails to compile here until classified (the C037 discipline).
+  const KIND: Record<keyof CostSettlement, "enum" | "scalar"> = { method: "enum", credits: "scalar", overflow: "enum" };
+  test("no settlement field is a runtime value-expression/pointer", () => {
+    for (const k of Object.keys(KIND)) expect(["enum", "scalar"]).toContain(KIND[k as keyof CostSettlement]);
+    // a populated settlement holds an enum + an integer + an enum — nothing that points into a payload.
+    const full: CostSettlement = { method: "rate-limited", credits: 10, overflow: "credit" };
+    expect(typeof full.method).toBe("string");
+    expect(Number.isInteger(full.credits)).toBe(true);
+  });
+});

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 });
+  });
+});