@suluk/cost 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@suluk/cost",
+  "version": "0.1.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"
+},
+"dependencies": {
+"@suluk/core": "0.1.0"
+},
+"peerDependencies": {
+"hono": "^4.0.0"
+},
+"peerDependenciesMeta": {
+"hono": {
+"optional": true
+}
+},
+"devDependencies": {
+"@types/bun": "latest",
+"hono": "^4.0.0",
+"@suluk/hono": "0.1.0",
+"@suluk/openapi-compat": "0.1.0",
+"zod": "^4.4.3"
+},
+"scripts": {
+"test": "bun test",
+"typecheck": "tsc --noEmit -p ."
+}
+}

package/src/contract.ts

@@ -0,0 +1,91 @@
+/**
+ * Cost as a CONTRACT FACET. A cost model is attached to each operation as the `x-suluk-cost` vendor
+ * extension on its Request — so it bubbles like everything else: 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.
+ * 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";
+
+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. */
+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;
+    }
+  }
+  return out;
+}
+
+/** Read the cost model declared on an operation (if any). */
+export function costOf(req: Request): CostModel | undefined {
+  return (req as Request & Record<string, unknown>)[COST_EXT] as CostModel | undefined;
+}
+
+export interface CostFinding {
+  code: "no-cost-model" | "zero-cost";
+  severity: "warn" | "info";
+  path: string;
+  operation: string;
+  message: string;
+}
+
+/**
+ * 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.
+ */
+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)" });
+      }
+    }
+  }
+  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))] });
+    }
+  }
+  return rows;
+}
+
+/**
+ * Compute the actual µ$ a request cost, from its declared model + the usage the handler reported. Fixed
+ * (per-call) components always count; variable components count their reported units × unit cost. Returns
+ * the per-source breakdown + total — raw, for the meter to record.
+ */
+export function computeCost(model: CostModel | undefined, usage: UsageReport[] = []): { breakdown: { source: string; microUsd: number }[]; totalMicroUsd: number } {
+  const bySource = new Map<string, number>();
+  const add = (source: string, micro: number) => bySource.set(source, (bySource.get(source) ?? 0) + micro);
+  const usageBySource = new Map<string, number>();
+  for (const u of usage) usageBySource.set(u.source, (usageBySource.get(u.source) ?? 0) + u.units);
+
+  for (const c of model?.components ?? []) {
+    if (c.basis === "per-call") add(c.source, c.microUsd);
+    else {
+      const units = usageBySource.get(c.source) ?? 0;
+      const per = c.basis === "per-1k-tokens" ? c.microUsd / 1000 : c.microUsd;
+      add(c.source, Math.round(per * units));
+    }
+  }
+  const breakdown = [...bySource.entries()].map(([source, microUsd]) => ({ source, microUsd }));
+  return { breakdown, totalMicroUsd: breakdown.reduce((s, b) => s + b.microUsd, 0) };
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @suluk/cost — cost as a contract facet + runtime metering. You can't price a user without knowing what
+ * they cost you. So: declare per-operation cost (incl. third-party usage) on the contract — it bubbles into
+ * the v4 doc, Scalar, and the audit; meter the ACTUAL cost per request at runtime, traced from the frontend
+ * action down to each third party; and read the raw per-user picture from the ledger. We display the data as
+ * it is and let you build pricing on top (Stripe via @suluk/stripe). CANDIDATE tooling — NOT official OAS.
+ */
+export {
+  type CostBasis, type CostComponent, type CostModel, type UsageReport, type CostEvent, formatMicroUsd,
+} from "./types";
+export {
+  COST_EXT, annotateCosts, costOf, costAudit, costTable, computeCost, type CostFinding,
+} from "./contract";
+export {
+  costMeter, recordUsage, MemoryCostSink, type CostSink, type CostMeterOptions,
+} from "./meter";
+export { summarize, principalCost, type CostSummary } from "./ledger";

package/src/ledger.ts

@@ -0,0 +1,37 @@
+/**
+ * The ledger — aggregate cost events into the raw picture: total, and breakdowns by principal (what each
+ * USER cost you), by operation, by frontend action, and by source (which third party). We display these AS
+ * THEY ARE; pricing, margins, and limits are something the consumer builds on top — not something we impose.
+ */
+import type { CostEvent } from "./types";
+
+export interface CostSummary {
+  total: number;
+  count: number;
+  byPrincipal: Record<string, number>;
+  byOperation: Record<string, number>;
+  byAction: Record<string, number>;
+  bySource: Record<string, number>;
+}
+
+function bump(rec: Record<string, number>, key: string | undefined, micro: number): void {
+  if (!key) return;
+  rec[key] = (rec[key] ?? 0) + micro;
+}
+
+export function summarize(events: CostEvent[]): CostSummary {
+  const s: CostSummary = { total: 0, count: events.length, byPrincipal: {}, byOperation: {}, byAction: {}, bySource: {} };
+  for (const e of events) {
+    s.total += e.totalMicroUsd;
+    bump(s.byPrincipal, e.principal, e.totalMicroUsd);
+    bump(s.byOperation, e.operation, e.totalMicroUsd);
+    bump(s.byAction, e.action, e.totalMicroUsd);
+    for (const b of e.breakdown) bump(s.bySource, b.source, b.microUsd);
+  }
+  return s;
+}
+
+/** What ONE principal cost you (the question that lets you price them) — and the trace by operation + action. */
+export function principalCost(events: CostEvent[], principal: string): CostSummary {
+  return summarize(events.filter((e) => e.principal === principal));
+}

package/src/meter.ts

@@ -0,0 +1,65 @@
+/**
+ * The runtime meter — records what each request ACTUALLY cost, attributed all the way down: the frontend
+ * action (a header the client sets) → the operation → the per-source breakdown (declared model + the
+ * third-party usage the handler reported). Records go to a pluggable sink; we display them raw.
+ */
+import type { Context, MiddlewareHandler } from "hono";
+import type { CostModel, CostEvent, UsageReport } from "./types";
+import { computeCost } from "./contract";
+
+export interface CostSink {
+  record(event: CostEvent): void | Promise<void>;
+}
+
+/** A simple in-memory sink (for the demo / tests). Production swaps in D1, a queue, etc. */
+export class MemoryCostSink implements CostSink {
+  private _events: CostEvent[] = [];
+  record(e: CostEvent): void { this._events.push(e); }
+  events(): CostEvent[] { return this._events.slice(); }
+  clear(): void { this._events = []; }
+}
+
+const USAGE_KEY = "suluk-cost-usage";
+
+/** A handler calls this to report MEASURED third-party usage for the current request (e.g. tokens used). */
+export function recordUsage(c: Context, source: string, units: number): void {
+  const arr = (c.get(USAGE_KEY) as UsageReport[] | undefined) ?? [];
+  arr.push({ source, units });
+  c.set(USAGE_KEY, arr);
+}
+
+export interface CostMeterOptions {
+  sink: CostSink;
+  /** operation name → its declared cost model. */
+  costs: Record<string, CostModel>;
+  /** Resolve the operation name for a request (e.g. c.get("operation"), or a matcher). */
+  operationOf: (c: Context) => string | undefined;
+  /** Resolve the principal/user id (default: none). */
+  principalOf?: (c: Context) => string | undefined;
+  /** Header carrying the frontend action id (default "x-suluk-action"). */
+  actionHeader?: string;
+  /** Wall-clock now (ms). Pass `() => Date.now()` in production; a fixed fn in tests for reproducibility. */
+  now?: () => number;
+}
+
+/** Hono middleware: after the handler runs, record what the request cost (declared model + reported usage). */
+export function costMeter(opts: CostMeterOptions): MiddlewareHandler {
+  const actionHeader = opts.actionHeader ?? "x-suluk-action";
+  const now = opts.now ?? (() => Date.now());
+  return async (c, next) => {
+    await next();
+    const operation = opts.operationOf(c);
+    if (!operation) return;
+    const usage = (c.get(USAGE_KEY) as UsageReport[] | undefined) ?? [];
+    const { breakdown, totalMicroUsd } = computeCost(opts.costs[operation], usage);
+    const event: CostEvent = {
+      at: now(),
+      operation,
+      principal: opts.principalOf?.(c),
+      action: c.req.header(actionHeader) || undefined,
+      breakdown,
+      totalMicroUsd,
+    };
+    await opts.sink.record(event);
+  };
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+/**
+ * The cost model — what an operation declares it costs you, and what a single request actually cost.
+ *
+ * All money is integer **micro-USD** (1 USD = 1_000_000 µ$). Integers avoid float drift and are the rawest
+ * possible representation — we display the data AS IT IS and let consumers build pricing on top. A cost has
+ * COMPONENTS, each tied to a source (a third party, compute, egress, …) and a basis (per-call vs per-unit),
+ * so the actual cost of a request is the fixed components plus the metered usage of the variable ones.
+ */
+
+export type CostBasis =
+  | "per-call" // a flat cost each time the operation runs
+  | "per-unit" // generic metered unit (you report how many)
+  | "per-token"
+  | "per-1k-tokens"
+  | "per-second"
+  | "per-request" // to a third party (e.g. one downstream API call)
+  | "per-mb";
+
+export interface CostComponent {
+  /** Where the money goes: "openai", "compute", "egress", "twilio", … (free-form, your taxonomy). */
+  source: string;
+  basis: CostBasis;
+  /** Cost per one unit of `basis`, in micro-USD. */
+  microUsd: number;
+  description?: string;
+}
+
+export interface CostModel {
+  components: CostComponent[];
+  /** Optional typical total for one call (µ$), for display + tests when usage isn't yet known. */
+  estimateMicroUsd?: number;
+}
+
+/** A measured usage report for one variable component during a request (e.g. {source:"openai", units: 1350}). */
+export interface UsageReport {
+  source: string;
+  units: number;
+}
+
+/** What a single request actually cost — the rawest record, attributed all the way down. */
+export interface CostEvent {
+  /** Wall-clock ms (an input, never read ambiently — pass it in, so events are reproducible/testable). */
+  at: number;
+  /** Who incurred it (the principal/user id), if known. */
+  principal?: string;
+  /** Which operation (the v4 by-name handle). */
+  operation: string;
+  /** The frontend action that triggered it (a button-click id), if the client tagged the request. */
+  action?: string;
+  /** Per-source breakdown (µ$). */
+  breakdown: { source: string; microUsd: number }[];
+  /** Total µ$ for the request. */
+  totalMicroUsd: number;
+}
+
+/** Format micro-USD as a display string (we store raw integers; this is only for humans). */
+export function formatMicroUsd(microUsd: number): string {
+  return `$${(microUsd / 1_000_000).toFixed(6).replace(/0+$/, "").replace(/\.$/, "")}`;
+}

package/test/cost.test.ts

@@ -0,0 +1,105 @@
+import { test, expect, describe } from "bun:test";
+import { Hono } from "hono";
+import * as z from "zod";
+import { emitV4 } from "@suluk/hono";
+import { validateDocument } from "@suluk/core";
+import { downgrade, validate31 } from "@suluk/openapi-compat";
+import {
+  annotateCosts, costOf, costAudit, costTable, computeCost, COST_EXT,
+  costMeter, recordUsage, MemoryCostSink, summarize, principalCost, formatMicroUsd,
+  type CostModel,
+} from "../src/index";
+
+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,
+};
+
+describe("computeCost — fixed + metered, raw µ$", () => {
+  test("per-call component always counts; per-1k-tokens scales with reported usage", () => {
+    const r = computeCost(ASK, [{ source: "openai", units: 1500 }]);
+    // compute: 50 ; openai: 2000/1000 * 1500 = 3000
+    expect(r.totalMicroUsd).toBe(3050);
+    expect(r.breakdown).toEqual([{ source: "compute", microUsd: 50 }, { source: "openai", microUsd: 3000 }]);
+  });
+  test("no usage → only the fixed components", () => {
+    expect(computeCost(ASK).totalMicroUsd).toBe(50);
+  });
+  test("formatMicroUsd shows it as it is", () => {
+    expect(formatMicroUsd(3050)).toBe("$0.00305");
+  });
+});
+
+describe("cost as a contract facet — bubbles into v4, Scalar, and the audit", () => {
+  const { document } = emitV4([
+    { method: "post", path: "/ask", name: "ask", summary: "Ask the model", request: { json: z.object({ q: z.string() }) }, responses: [{ status: 200, description: "ok", schema: z.object({ answer: z.string() }) }] },
+    { method: "get", path: "/ping", name: "ping", summary: "Ping", responses: [{ status: 200, description: "ok" }] },
+  ], { info: { title: "AI", version: "1" } });
+  const annotated = annotateCosts(document, { ask: ASK });
+
+  test("x-suluk-cost lands on the operation and the doc still validates", () => {
+    const req = (annotated.paths["ask"].requests.ask as unknown as Record<string, unknown>)[COST_EXT];
+    expect(req).toEqual(ASK as unknown as Record<string, unknown>);
+    expect(validateDocument(annotated).valid).toBe(true);
+  });
+  test("it survives the 3.1 downgrade — so Scalar/Swagger show it", () => {
+    const down = downgrade(annotated).document as any;
+    expect(validate31(down).valid).toBe(true);
+    expect(down.paths["/ask"].post[COST_EXT]).toEqual(ASK);
+  });
+  test("costAudit flags operations with NO declared cost (not assumed zero)", () => {
+    const findings = costAudit(annotated);
+    expect(findings.map((f) => f.operation)).toContain("ping"); // ping declared no cost
+    expect(findings.map((f) => f.operation)).not.toContain("ask");
+  });
+  test("costTable surfaces the declared costs for display", () => {
+    const rows = costTable(annotated);
+    expect(rows.find((r) => r.operation === "ask")!.sources.sort()).toEqual(["compute", "openai"]);
+  });
+});
+
+describe("runtime meter — actual cost, traced from the frontend action down", () => {
+  test("records what a request cost, attributed to principal + action + source", async () => {
+    const sink = new MemoryCostSink();
+    const app = new Hono<{ Variables: { operation: string; principal: string } }>();
+    app.use("*", async (c, next) => { c.set("operation", "ask"); c.set("principal", "user_42"); await next(); });
+    app.use("*", costMeter({
+      sink, costs: { ask: ASK },
+      operationOf: (c) => (c as { get(k: string): string }).get("operation"),
+      principalOf: (c) => (c as { get(k: string): string }).get("principal"),
+      now: () => 1000,
+    }));
+    app.post("/ask", (c) => { recordUsage(c, "openai", 2000); return c.json({ answer: "42" }); });
+
+    await app.request("/ask", { method: "POST", headers: { "content-type": "application/json", "x-suluk-action": "ask-button" }, body: "{}" });
+    const events = sink.events();
+    expect(events.length).toBe(1);
+    const e = events[0];
+    expect(e.operation).toBe("ask");
+    expect(e.principal).toBe("user_42");
+    expect(e.action).toBe("ask-button");          // traced from the frontend button
+    expect(e.totalMicroUsd).toBe(50 + 4000);       // compute 50 + openai 2000/1000*2000
+    expect(e.at).toBe(1000);
+  });
+});
+
+describe("ledger — the raw per-user picture you price on", () => {
+  const events = [
+    { at: 1, principal: "a", operation: "ask", action: "btn1", breakdown: [{ source: "openai", microUsd: 3000 }], totalMicroUsd: 3000 },
+    { at: 2, principal: "a", operation: "ask", action: "btn2", breakdown: [{ source: "openai", microUsd: 1000 }], totalMicroUsd: 1000 },
+    { at: 3, principal: "b", operation: "list", action: "btn1", breakdown: [{ source: "compute", microUsd: 50 }], totalMicroUsd: 50 },
+  ];
+  test("summarize aggregates by principal / operation / action / source", () => {
+    const s = summarize(events);
+    expect(s.total).toBe(4050);
+    expect(s.byPrincipal).toEqual({ a: 4000, b: 50 });
+    expect(s.bySource).toEqual({ openai: 4000, compute: 50 });
+    expect(s.byAction.btn1).toBe(3050);
+  });
+  test("principalCost answers 'what did user a cost me?'", () => {
+    expect(principalCost(events, "a").total).toBe(4000);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }