@suluk/cost 0.1.2 → 0.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 <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"><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>
@@ -24,11 +24,180 @@
 bun add @suluk/cost
 ```
 
-## The Suluk cycle
+`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`.
 
-`@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).
+## 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suluk/cost",
-  "version": "0.1.2",
+  "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.",
   "publishConfig": {
   "access": "public"
@@ -19,7 +19,7 @@
 ".": "./src/index.ts"
 },
 "dependencies": {
-"@suluk/core": "^0.1.7"
+"@suluk/core": "^0.1.13"
 },
 "peerDependencies": {
 "hono": "^4.0.0"
@@ -32,8 +32,8 @@
 "devDependencies": {
 "@types/bun": "latest",
 "hono": "^4.0.0",
-"@suluk/hono": "^0.1.2",
-"@suluk/openapi-compat": "^0.1.2",
+"@suluk/hono": "^0.1.5",
+"@suluk/openapi-compat": "^0.1.3",
 "zod": "^4.4.3"
 },
 "scripts": {

package/src/index.ts

@@ -11,7 +11,14 @@ export {
   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,

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

@@ -79,11 +79,32 @@ export interface CostModel {
   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;
 

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