@passioncode-ai/fabric-agent-adapter 0.6.3 → 0.8.1

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/usage.md

@@ -0,0 +1,63 @@
+# Usage report — what the agent spent (DEC-0021)
+
+Fabric Agent Contract DEC-0021, `docs/specification/service.md` → *Usage report*, schema
+`schemas/service-usage.schema.json`. Optional. A service that calls paid models or tools should
+offer it, so Fabric Dashboards (Spend, MCP `spend`) and Fabric can show each agent's spend beside
+its health without knowing any provider.
+
+## What to record
+
+One **receipt per model call**, built from the numbers the provider returned:
+
+```python
+receipt = fs.make_usage_receipt("anthropic", "claude-sonnet-5-5",
+                                input_tokens=u.input_tokens, output_tokens=u.output_tokens,
+                                cache_read_tokens=u.cache_read_input_tokens or 0,
+                                cost_usd=charged, cost_basis="provider")   # or "price-list"
+ledger.record(receipt)                     # fs.JsonlUsageLedger(data / "usage.jsonl")
+```
+
+```js
+ledger.record(k.makeUsageReceipt('openrouter', model, { inputTokens, outputTokens, costUsd: usage.cost ?? null }));
+```
+
+- **The provider's own numbers.** Take tokens from the response's usage block, not from a local
+  estimate. The cost is `provider` when the provider reported the charge (OpenRouter `usage.cost`,
+  a billing API) and `price-list` when you computed it from a published price list.
+- **Unknown is `None`/`null`, never `0`.** A local model, or a provider that reports no price,
+  records `cost_usd=None`. The report counts it in `unpricedCalls`, and a host shows a lower bound
+  («≥ $x») or «unknown». A call that is really free (a template, a cached answer) records
+  `cost_usd=0.0` with `price-list`.
+- **No content.** A receipt carries no prompt, output, caller or user id. The kits accept only the
+  fields above.
+- If the service already keeps a ledger (a jobs table with token counts), build the receipts from
+  it and pass them to `usage_report(...)`. That avoids a second store.
+
+## What to answer
+
+Declare the surface in the well-known document and serve the report behind the service token:
+
+```python
+surfaces={..., "usage": {"path": fs.USAGE_PATH}}          # "/fabric/v1/usage"
+# GET /fabric/v1/usage, token required:
+return send(200, ledger.report(service_id=ID, instance=INSTANCE, budget={"period": "month", "limitUsd": 100}))
+```
+
+`usage_report` / `usageReport` give the last 31 UTC days, oldest first, per provider and model,
+with day totals that are the sums of the model rows (`FAC-SEM-025`). Days without calls are
+left out.
+
+**Budget.** Pass `budget` only if the service **enforces** that limit itself. The report states
+it, and the host only shows it.
+
+Call `ledger.prune()` at start (or daily) to keep the file at the reported window (LC-12).
+
+`JsonlUsageLedger` appends 0600 JSON lines. A line torn by a killed writer is skipped, and the
+next receipt never glues onto it.
+
+## Verify
+
+`check_service.py <id>` reads a declared report: `usage.requires-token` (401 without the token)
+and `usage.report` (identity, USD, dates forward, null for all-unpriced rows, sums). The
+`sample_service.py` serves one. Fabric Dashboards → **Spend** shows it within a minute of opening
+the page.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py

@@ -324,6 +324,42 @@ class Probe:
         self.add("events.page", "FAIL" if bad else "PASS",
                  ("bad events: " + ", ".join(bad)) if bad else "%d event(s), cursor %r" % (len(events), page["cursor"]))
 
+    def usage_rules(self) -> None:
+        """DEC-0021: a declared usage report requires the token and adds up (FAC-SEM-025)."""
+        usage = ((self.wk or {}).get("surfaces") or {}).get("usage")
+        if not usage:
+            self.add("usage.report", "NOT_RUN", "surfaces.usage not declared (optional; a service that calls paid models should offer it)")
+            return
+        path = str(usage.get("path", ""))
+        if not path.startswith("/") or path.startswith("//"):
+            self.add("usage.report", "FAIL", "surfaces.usage.path %r is not a path on the origin" % path)
+            return
+        try:
+            status, _, _ = self.request("GET", path)
+            self.add("usage.requires-token", "PASS" if status == 401 else "FAIL", "HTTP %d without a token" % status)
+        except OSError as exc:
+            self.add("usage.requires-token", "NOT_RUN", str(exc))
+        if not self.token:
+            self.add("usage.report", "NOT_RUN", "no readable token")
+            return
+        try:
+            status, _, body = self.request("GET", path, self.auth_headers())
+        except OSError as exc:
+            self.add("usage.report", "NOT_RUN", str(exc))
+            return
+        if status != 200:
+            self.add("usage.report", "FAIL", "HTTP %d with the token" % status)
+            return
+        try:
+            report = json.loads(body)
+        except ValueError:
+            self.add("usage.report", "FAIL", "not JSON")
+            return
+        problems = usage_problems(report, str(self.d.get("id")), str(self.d.get("instance", "default")))
+        days = report.get("days") if isinstance(report, dict) else None
+        self.add("usage.report", "FAIL" if problems else "PASS",
+                 "; ".join(problems[:5]) if problems else "%d day(s), unknown cost kept null" % len(days or []))
+
     def login_rules(self) -> None:
         dashboard = ((self.wk or {}).get("surfaces") or {}).get("dashboard")
         if not dashboard or not dashboard.get("login"):
@@ -360,7 +396,7 @@ class Probe:
         body["_meta"] = {"io.modelcontextprotocol/protocolVersion": fi.MCP_REVISION,
                          "io.modelcontextprotocol/clientCapabilities": {}, "traceparent": self.sent_traceparent}
         headers = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream",
-                   "MCP-Protocol-Version": fi.MCP_REVISION}
+                   **fi.mcp_request_headers(method, params)}
         headers.update(self.auth_headers())
         message = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": body}).encode()
         status, resp_headers, raw = self.request("POST", path, headers, message)
@@ -412,9 +448,24 @@ class Probe:
             extra = sorted(set(listed) - names)
             self.add("interop.well-known-capabilities", "FAIL" if extra else "PASS",
                      ("listed but not in the manifest: " + ", ".join(extra)) if extra else "%d listed, all in the manifest" % len(listed))
-        if not mcp_surface or not self.token:
+        own = bool(mcp_surface) and mcp_surface.get("auth") == "own"
+        if own and self.token:
+            # DEC-0024: the MCP surface has credentials of its own and must refuse the host's token.
+            try:
+                self.mcp_call("tools/list", {})
+                self.add("interop.mcp-own-auth", "FAIL", "surfaces.mcp.auth is own, yet the MCP surface accepted the descriptor's token")
+            except OSError as exc:
+                refused = any(code in str(exc) for code in ("HTTP 401", "HTTP 403"))
+                self.add("interop.mcp-own-auth", "PASS" if refused else "NOT_RUN",
+                         ("the MCP surface refuses the host's token (%s), as auth: own says" % exc) if refused else str(exc))
+            except ValueError as exc:
+                self.add("interop.mcp-own-auth", "NOT_RUN", str(exc))
+        if not mcp_surface or not self.token or own:
+            reason = ("no MCP surface" if not mcp_surface
+                      else "surfaces.mcp.auth is own: the MCP surface takes its callers' credentials, not the host's token (DEC-0024)" if own
+                      else "no readable token")
             for rule in ("interop.output-schema-object", "interop.tools-match", "interop.job-tools", "interop.unknown-job", "interop.trace-propagation"):
-                self.add(rule, "NOT_RUN", "no MCP surface" if not mcp_surface else "no readable token")
+                self.add(rule, "NOT_RUN", reason)
         else:
             try:
                 listing = self.mcp_call("tools/list", {})
@@ -621,12 +672,64 @@ class Probe:
         if self.wk is not None:
             self.network_rules()
             self.auth_rules()
+            self.usage_rules()
             self.login_rules()
             self.interop_rules()
         self.lifecycle_rules()
         return self.results
 
 
+def usage_problems(report: Any, service_id: str, instance: str) -> List[str]:
+    """What makes this not a DEC-0021 usage report of the service: shape, identity and the sums of
+    FAC-SEM-025. An unknown cost must be null; a day's totals are the sums of its models."""
+    if not isinstance(report, dict):
+        return ["not an object"]
+    out: List[str] = []
+    if report.get("protocol") != fs.PROTOCOL:
+        out.append("protocol is %r" % report.get("protocol"))
+    if report.get("service") != {"id": service_id, "instance": instance}:
+        out.append("reports for %r, not %s.%s" % (report.get("service"), service_id, instance))
+    if report.get("currency") != "USD":
+        out.append("currency is not USD")
+    days = report.get("days")
+    if not isinstance(days, list) or len(days) > fs.USAGE_DAYS:
+        return out + ["days is not a list of at most 31"]
+    fields = ("calls", "unpricedCalls", "inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens")
+
+    def priced(row: Dict[str, Any], at: str) -> None:
+        calls, unpriced, cost = row.get("calls", 0), row.get("unpricedCalls", 0), row.get("costUsd")
+        if unpriced > calls:
+            out.append("%s: more unpriced calls than calls" % at)
+        if calls and unpriced == calls and cost is not None:
+            out.append("%s: every call is unpriced, so the cost must be null, not %r" % (at, cost))
+        if unpriced < calls and cost is None:
+            out.append("%s: priced calls carry a cost" % at)
+        if cost is not None and (not isinstance(cost, (int, float)) or cost < 0):
+            out.append("%s: costUsd is not a non-negative number" % at)
+
+    previous = ""
+    for i, day in enumerate(days):
+        at = "days[%d]" % i
+        date = str(day.get("date", "")) if isinstance(day, dict) else ""
+        if not re.match(r"^\d{4}-\d{2}-\d{2}$", date) or date <= previous:
+            out.append("%s: dates must run forward" % at)
+        previous = date
+        priced(day, at)
+        models = day.get("byModel") if isinstance(day, dict) else None
+        if not isinstance(models, list):
+            out.append("%s: byModel missing" % at)
+            continue
+        for j, m in enumerate(models):
+            priced(m, "%s.byModel[%d]" % (at, j))
+        for f in fields:
+            if day.get(f, 0) != sum(m.get(f, 0) for m in models):
+                out.append("%s: %s is not the sum of its models" % (at, f))
+        known = sum(m["costUsd"] for m in models if isinstance(m.get("costUsd"), (int, float)))
+        if isinstance(day.get("costUsd"), (int, float)) and abs(day["costUsd"] - known) > 1e-6:
+            out.append("%s: costUsd is not the sum of its models' known costs" % at)
+    return out
+
+
 def same_repository(a: str, b: str) -> bool:
     """git@github.com:o/r.git, https://github.com/o/r and github.com/o/r are one repository."""
     def norm(u: str) -> str:

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-interop.mjs

@@ -220,3 +220,80 @@ export class JobStore {
   cancel(jobId) { return this.transition(jobId, 'cancelled'); }
 }
 // #endregion interop-kit-node
+
+// --- MCP 2026-07-28 standard headers ------------------------------------------------------
+
+export const NAMED_METHODS = { 'tools/call': 'name', 'prompts/get': 'name', 'resources/read': 'uri' };
+export const HEADER_MISMATCH = -32020; // the code the official 2026-07-28 server SDK answers a header/body mismatch with
+
+const SENTINEL = ['=?base64?', '?='];
+
+/**
+ * A body value as an HTTP header value, by MCP 2026-07-28 Streamable HTTP "Value Encoding": as it
+ * is when it is printable ASCII without leading or trailing whitespace, otherwise — and for a plain
+ * value that itself looks like the sentinel — `=?base64?<base64 of its UTF-8>?=`.
+ */
+export function encodeHeaderValue(value) {
+  const s = String(value);
+  const plain = /^[\x20-\x7e]*$/.test(s) && s === s.replace(/^ +| +$/g, '') && !(s.startsWith(SENTINEL[0]) && s.endsWith(SENTINEL[1]));
+  if (plain) return s;
+  let binary = '';
+  for (const byte of new TextEncoder().encode(s)) binary += String.fromCharCode(byte);
+  return SENTINEL[0] + btoa(binary) + SENTINEL[1];
+}
+
+/** The body value a header carries, decoding the Base64 sentinel; null for invalid characters or a
+ *  sentinel that is not valid Base64 of UTF-8 (a server rejects both). */
+export function decodeHeaderValue(value) {
+  const s = String(value);
+  if (s.startsWith(SENTINEL[0]) && s.endsWith(SENTINEL[1]) && s.length >= SENTINEL[0].length + SENTINEL[1].length) {
+    const body = s.slice(SENTINEL[0].length, -SENTINEL[1].length);
+    if (body.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(body)) return null;
+    try {
+      const bytes = Uint8Array.from(atob(body), (c) => c.charCodeAt(0));
+      return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    } catch { return null; }
+  }
+  return /^[\x20-\x7e\t]*$/.test(s) ? s : null;
+}
+
+/**
+ * MCP 2026-07-28 Streamable HTTP mirrors the body in `Mcp-Method` (every request and
+ * notification) and `Mcp-Name` (`params.name` or `params.uri` of tools/call, prompts/get,
+ * resources/read). A server MUST reject a mismatch; a request that declares 2026-07-28 must carry
+ * them. Returns the problem as a sentence, or null. `headers` is a plain object (any case) or a
+ * Headers instance.
+ */
+export function mcpHeaderProblem(message, headers) {
+  if (!message || typeof message !== 'object' || !headers) return null;
+  const header = (name) => {
+    if (typeof headers.get === 'function') return headers.get(name) ?? null;
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === name.toLowerCase());
+    const value = key === undefined ? undefined : headers[key];
+    return value === undefined ? null : String(Array.isArray(value) ? value[0] : value);
+  };
+  const declared = header('MCP-Protocol-Version') === MCP_REVISION;
+  const { method } = message;
+  const sent = header('Mcp-Method');
+  if (sent === null && declared) return `the body names method ${method} but the required Mcp-Method header is absent`;
+  if (sent !== null && sent !== method) return `Mcp-Method ${sent} disagrees with the body's method ${method}`;
+  const field = NAMED_METHODS[method];
+  if (field) {
+    const named = header('Mcp-Name');
+    if (named === null && declared) return `the body carries params.${field} but the required Mcp-Name header is absent`;
+    if (named !== null) {
+      const decoded = decodeHeaderValue(named);
+      if (decoded === null) return 'Mcp-Name is malformed: invalid characters or a broken =?base64?…?= value';
+      if (decoded !== String(message.params?.[field])) return `Mcp-Name disagrees with the body's params.${field}`;
+    }
+  }
+  return null;
+}
+
+/** The standard headers a 2026-07-28 client sends with one request. */
+export function mcpRequestHeaders(method, params = {}) {
+  const out = { 'MCP-Protocol-Version': MCP_REVISION, 'Mcp-Method': method };
+  const field = NAMED_METHODS[method];
+  if (field && params[field] !== undefined && params[field] !== null) out['Mcp-Name'] = encodeHeaderValue(params[field]);
+  return out;
+}

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/fabric-service.mjs

@@ -1,7 +1,7 @@
 // Reference kit for the fabric-service/0.1 local service extension — Node.js 20+, no dependencies.
 // The Node twin of fabric_service.py: same rules, same file formats, interoperable locks.
 // Normative source: fabric-agent-contract docs/specification/service.md (DEC-0015; the remote
-// placement — an online agent or dashboard at an https origin — DEC-0019).
+// placement — an online agent or dashboard at an https origin — DEC-0019; the usage report DEC-0021).
 
 import crypto from 'node:crypto';
 import fs from 'node:fs';
@@ -12,6 +12,19 @@ import path from 'node:path';
 export const PROTOCOL = 'fabric-service/0.1';
 export const EXTENSION_KEY = 'https://fabric.passioncode.ai/agent-contract/extensions/service/0.1';
 export const EXIT_ALREADY_RUNNING = 75;
+// Lifecycle contract (fabric-workspace knowledge/lifecycle.md), the same values as fabric_service.py.
+// A launchd-supervised copy that finds the lock held backs off in-process before its exit 75 (LC-03).
+export const SUPERVISOR_ENV = 'FABRIC_SERVICE_SUPERVISOR';
+export const LOCK_WAIT_SUPERVISED_SECONDS = 300;
+export const LOCK_BACKOFF_FIRST_SECONDS = 0.5;
+export const LOCK_BACKOFF_MAX_SECONDS = 30;
+// LC-01: SIGTERM reaches exit in at most 10 s with work in flight — drain 8 s, hard exit 2 s later.
+export const DRAIN_SECONDS = 8;
+export const DRAIN_GRACE_SECONDS = 2;
+export const EXIT_HARD_STOP = 70;
+// LC-12: logs rotate by size, 5 x 5 MB by default.
+export const LOG_MAX_BYTES = 5 * 1024 * 1024;
+export const LOG_BACKUPS = 5;
 export const LEVELS = ['info', 'notice', 'warning', 'error'];
 export const STATUSES = ['starting', 'ready', 'degraded', 'stopping'];
 export const EVENTS_DEFAULT_LIMIT = 50;
@@ -151,13 +164,42 @@ function readPid(file) {
   }
 }
 
-export async function holdSingleInstance(dataDir) {
-  try {
-    return await new InstanceLock(dataDir).acquire();
-  } catch (error) {
-    if (!(error instanceof AlreadyRunning)) throw error;
-    process.stderr.write(`${error.message}\n`);
-    process.exit(EXIT_ALREADY_RUNNING);
+/** True when launchd started this process from a plist that says so (FABRIC_SERVICE_SUPERVISOR=launchd). */
+export const supervisedByLaunchd = () => process.env[SUPERVISOR_ENV] === 'launchd';
+
+const sleepSeconds = (s) => new Promise((resolve) => setTimeout(resolve, s * 1000));
+
+/**
+ * Take the lock or exit 75 with one sentence naming the holder. Started by hand, a held lock exits
+ * 75 at once. Under launchd (KeepAlive) an immediate exit is a respawn every ThrottleInterval,
+ * forever; so a supervised copy first backs off in-process (0.5 s doubling to 30 s,
+ * LOCK_WAIT_SUPERVISED_SECONDS in all), takes over if the holder leaves, and exits 75 only when
+ * the wait runs out. `waitSeconds` overrides the choice (0 = never wait).
+ */
+export async function holdSingleInstance(dataDir, {
+  waitSeconds, sleep = sleepSeconds, clock = () => performance.now() / 1000, exit = (code) => process.exit(code),
+} = {}) {
+  const wait = waitSeconds ?? (supervisedByLaunchd() ? LOCK_WAIT_SUPERVISED_SECONDS : 0);
+  const deadline = clock() + Math.max(0, wait);
+  let delay = LOCK_BACKOFF_FIRST_SECONDS;
+  let announced = false;
+  for (;;) {
+    try {
+      return await new InstanceLock(dataDir).acquire();
+    } catch (error) {
+      if (!(error instanceof AlreadyRunning)) throw error;
+      const remaining = deadline - clock();
+      if (remaining <= 0) {
+        process.stderr.write(`${error.message}\n`);
+        return exit(EXIT_ALREADY_RUNNING);
+      }
+      if (!announced) {
+        process.stderr.write(`${error.message} Waiting up to ${Math.round(remaining)} s for it to exit.\n`);
+        announced = true;
+      }
+      await sleep(Math.min(delay, remaining));
+      delay = Math.min(delay * 2, LOCK_BACKOFF_MAX_SECONDS);
+    }
   }
 }
 
@@ -346,6 +388,273 @@ export async function eventsPage(fetch, after, limit) {
   return { events, cursor: events.length ? events.at(-1).id : (after ?? null) };
 }
 
+// --- usage report (DEC-0021) -------------------------------------------------------------
+
+export const USAGE_PATH = '/fabric/v1/usage';
+export const USAGE_DAYS = 31;
+export const COST_BASES = ['provider', 'price-list', 'unknown'];
+const PROVIDER = /^[a-z][a-z0-9._-]{0,63}$/;
+const COUNTS = ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'];
+
+/**
+ * One model call, from the provider's own usage numbers. No prompt, output or caller.
+ * `costUsd` null means it cannot be priced: the report counts it as unpriced, never as $0.
+ */
+export function makeUsageReceipt(provider, model, { inputTokens, outputTokens, cacheReadTokens = 0, cacheWriteTokens = 0, costUsd = null, costBasis, at } = {}) {
+  if (!PROVIDER.test(provider ?? '')) throw new ServiceError('provider must be a lowercase name such as anthropic or openrouter.');
+  model = String(model ?? '').trim();
+  if (!model || model.length > 128) throw new ServiceError('model must be 1 to 128 characters.');
+  const counts = { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens };
+  for (const [name, value] of Object.entries(counts)) if (!Number.isInteger(value) || value < 0) throw new ServiceError(`${name} must be a non-negative integer.`);
+  if (costUsd !== null && (typeof costUsd !== 'number' || !Number.isFinite(costUsd) || costUsd < 0)) throw new ServiceError('costUsd must be a non-negative number or null.');
+  const basis = costBasis ?? (costUsd === null ? 'unknown' : 'provider');
+  if (!COST_BASES.includes(basis) || (costUsd === null) !== (basis === 'unknown')) throw new ServiceError('costBasis is provider or price-list with a cost, unknown without one.');
+  return { at: at ?? nowIso(), provider, model, ...counts, costUsd, costBasis: basis };
+}
+
+const utcDate = (ms) => new Date(ms).toISOString().slice(0, 10);
+const emptyRow = (extra = {}) => ({ ...extra, calls: 0, unpricedCalls: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, cost: 0 });
+function closeRow(row) {
+  const { cost, ...rest } = row;
+  return { ...rest, costUsd: rest.calls && rest.unpricedCalls === rest.calls ? null : Math.round(cost * 1e6) / 1e6 };
+}
+
+/**
+ * The service-usage.schema.json answer: the last 31 UTC days, oldest first, per provider and
+ * model; days without calls are omitted. A row whose calls are all unpriced costs null; totals
+ * are the sums of the model rows (FAC-SEM-025).
+ */
+export function usageReport(receipts, { id, instance = 'default', now = Date.now(), budget } = {}) {
+  const first = utcDate(now - (USAGE_DAYS - 1) * 86_400_000), last = utcDate(now);
+  const days = new Map();
+  for (const r of receipts) {
+    const date = String(r.at ?? '').slice(0, 10);
+    if (date < first || date > last) continue;
+    const rows = days.get(date) ?? new Map();
+    days.set(date, rows);
+    const k = `${r.provider}\u0000${r.model}`;
+    const row = rows.get(k) ?? emptyRow({ provider: r.provider, model: r.model, bases: new Set() });
+    rows.set(k, row);
+    row.calls += 1;
+    for (const c of COUNTS) row[c] += Number(r[c] ?? 0);
+    if (r.costUsd === null || r.costUsd === undefined) row.unpricedCalls += 1; else row.cost += r.costUsd;
+    row.bases.add(r.costBasis ?? 'unknown');
+  }
+  const outDays = [...days.keys()].sort().map((date) => {
+    const models = [...days.get(date).values()]
+      .map(({ bases, ...row }) => closeRow({ ...row, costBasis: bases.size === 1 ? [...bases][0] : 'mixed' }))
+      .sort((a, b) => (a.provider + a.model < b.provider + b.model ? -1 : 1));
+    const day = emptyRow({ date });
+    for (const m of models) {
+      for (const c of ['calls', 'unpricedCalls', ...COUNTS]) day[c] += m[c];
+      day.cost += m.costUsd ?? 0;
+    }
+    return { ...closeRow(day), byModel: models };
+  });
+  const report = { protocol: PROTOCOL, service: { id, instance }, generatedAt: new Date(now).toISOString().replace(/\.\d{3}Z$/, 'Z'), currency: 'USD', days: outDays };
+  if (budget !== undefined) {
+    if (!['day', 'month'].includes(budget?.period) || typeof budget.limitUsd !== 'number' || !(budget.limitUsd > 0)) throw new ServiceError('budget is {period: day|month, limitUsd > 0}.');
+    const prefix = budget.period === 'day' ? last : last.slice(0, 7);
+    const window = outDays.filter((d) => d.date.startsWith(prefix));
+    const unknown = window.length > 0 && window.every((d) => d.costUsd === null);
+    report.budget = { period: budget.period, limitUsd: budget.limitUsd, spentUsd: unknown ? null : Math.round(window.reduce((n, d) => n + (d.costUsd ?? 0), 0) * 1e6) / 1e6 };
+  }
+  return report;
+}
+
+/** Usage receipts for services that keep none yet: append-only JSON lines, 0600, pruned to the window (LC-12).
+ *  One writer process (the service holds its instance lock); every method is synchronous, so calls never interleave. */
+export class JsonlUsageLedger {
+  constructor(file) { this.file = file; }
+
+  record(receipt) {
+    ensurePrivateDir(path.dirname(this.file));
+    const fd = fs.openSync(this.file, 'a+', 0o600);
+    try {
+      const { size } = fs.fstatSync(fd);
+      const last = Buffer.alloc(1);
+      // A killed writer left a torn line: never glue a receipt to it.
+      const lead = size && fs.readSync(fd, last, 0, 1, size - 1) === 1 && last[0] !== 0x0a ? '\n' : '';
+      fs.writeSync(fd, lead + JSON.stringify(receipt) + '\n');
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+
+  receipts() {
+    if (!fs.existsSync(this.file)) return [];
+    const out = [];
+    for (const line of fs.readFileSync(this.file, 'utf8').split('\n')) {
+      if (!line) continue;
+      try { out.push(JSON.parse(line)); } catch { /* a torn last line from a killed writer is skipped */ }
+    }
+    return out;
+  }
+
+  prune(now = Date.now()) {
+    const first = utcDate(now - (USAGE_DAYS - 1) * 86_400_000);
+    const all = this.receipts();
+    const kept = all.filter((r) => String(r.at ?? '').slice(0, 10) >= first);
+    if (kept.length !== all.length) atomicWrite(this.file, kept.map((r) => JSON.stringify(r) + '\n').join(''));
+    return all.length - kept.length;
+  }
+
+  report(options) { return usageReport(this.receipts(), options); }
+}
+
+// --- logs (LC-12) ------------------------------------------------------------------------
+
+/**
+ * One structured log: JSON lines rotated by size (5 x 5 MB by default), files 0600 in a 0700
+ * directory. `service.jsonl` -> `.1` ... `.<backups>`; the oldest falls off. Never pass a token,
+ * a cookie, a login code or a request body that may carry one.
+ */
+export class RotatingLog {
+  constructor(file, { maxBytes = LOG_MAX_BYTES, backups = LOG_BACKUPS } = {}) {
+    if (maxBytes < 256 || backups < 1) throw new ServiceError('A rotating log needs maxBytes >= 256 and at least one backup.');
+    this.file = file;
+    this.maxBytes = maxBytes;
+    this.backups = backups;
+  }
+
+  line(record) {
+    let data = Buffer.from(`${JSON.stringify(record)}\n`);
+    if (data.length <= this.maxBytes) return data;
+    const cut = { ...record, truncated: true };
+    let message = String(record.message ?? '');
+    while (message) {
+      message = message.slice(0, Math.floor(message.length / 2));
+      cut.message = message;
+      data = Buffer.from(`${JSON.stringify(cut)}\n`);
+      if (data.length <= this.maxBytes) return data;
+    }
+    return Buffer.from(`${JSON.stringify({ at: record.at, level: record.level, message: '', truncated: true })}\n`);
+  }
+
+  write(level, message, fields = {}) {
+    const data = this.line({ at: nowIso(), level: String(level), message: String(message), ...fields });
+    ensurePrivateDir(path.dirname(this.file));
+    let size = 0;
+    try { size = fs.statSync(this.file).size; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    if (size && size + data.length > this.maxBytes) this.rotate();
+    const fd = fs.openSync(this.file, 'a', 0o600);
+    try { fs.writeSync(fd, data); } finally { fs.closeSync(fd); }
+  }
+
+  rotate() {
+    for (let i = this.backups - 1; i > 0; i -= 1) {
+      if (fs.existsSync(`${this.file}.${i}`)) fs.renameSync(`${this.file}.${i}`, `${this.file}.${i + 1}`);
+    }
+    fs.renameSync(this.file, `${this.file}.1`);
+  }
+}
+
+/**
+ * Call once at start: a launchd stdout file over `maxBytes` is copied to `<file>.1` and truncated
+ * in place (launchd holds it open for append, so a rename would leave it writing to the old name).
+ */
+export function capStdoutLog(file, maxBytes = LOG_MAX_BYTES) {
+  let size;
+  try { size = fs.statSync(file).size; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+  if (size <= maxBytes) return false;
+  fs.copyFileSync(file, `${file}.1`);
+  fs.chmodSync(`${file}.1`, 0o600);
+  fs.truncateSync(file, 0);
+  return true;
+}
+
+// --- shutdown (LC-01) ----------------------------------------------------------------------
+
+export class Stopping extends ServiceError {}
+
+/**
+ * SIGTERM/SIGINT: stop taking new work, drain in-flight work until `deadline` seconds, then hand
+ * over with `onStop(drained)`. A hand-over that never settles is cut by a hard exit
+ * (EXIT_HARD_STOP) `grace` seconds later.
+ *
+ *   const drain = new Drain().install((drained) => server.close(() => process.exit(0)),
+ *     { onStopping: () => log.append('service.stopping', 'info', 'Stopping.') });
+ *   await drain.work(async () => { ... });   // rejects with Stopping once a stop has begun
+ */
+export class Drain {
+  constructor({ deadline = DRAIN_SECONDS, grace = DRAIN_GRACE_SECONDS } = {}) {
+    this.deadline = deadline;
+    this.grace = grace;
+    this.inflight = 0;
+    this.stopping = false;
+    this.waiters = new Set();
+  }
+
+  async work(fn) {
+    if (this.stopping) throw new Stopping('The service is stopping and takes no new work.');
+    this.inflight += 1;
+    try {
+      return await fn();
+    } finally {
+      this.inflight -= 1;
+      if (this.inflight === 0) for (const wake of this.waiters) wake();
+    }
+  }
+
+  /** Refuse new work from now on; false when a stop had already begun. */
+  requestStop() {
+    if (this.stopping) return false;
+    this.stopping = true;
+    return true;
+  }
+
+  /** Resolves true when in-flight work finished inside `timeoutSeconds`, false otherwise. */
+  wait(timeoutSeconds) {
+    if (this.inflight === 0) return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const wake = () => { clearTimeout(timer); this.waiters.delete(wake); resolve(true); };
+      const timer = setTimeout(() => { this.waiters.delete(wake); resolve(false); }, timeoutSeconds * 1000);
+      this.waiters.add(wake);
+    });
+  }
+
+  install(onStop, { onStopping, signals = ['SIGTERM', 'SIGINT'] } = {}) {
+    const handler = () => {
+      if (!this.requestStop()) return; // a second signal changes nothing: the hard exit holds the deadline
+      setTimeout(() => process.exit(EXIT_HARD_STOP), (this.deadline + this.grace) * 1000).unref();
+      (async () => {
+        try { await onStopping?.(); } catch (error) { process.stderr.write(`${error?.stack ?? error}\n`); }
+        await onStop(await this.wait(this.deadline));
+      })();
+    };
+    for (const signal of signals) process.on(signal, handler);
+    return this;
+  }
+}
+
+// --- releases (LC-11, LC-15) -----------------------------------------------------------------
+
+/**
+ * Keep the release the job runs and the one before it; remove older release directories, newest
+ * first by modification time. `current` (a release or a symlink to one) is never removed, even
+ * after a rollback. Symlinks and files are left alone. Returns the removed paths.
+ */
+export function pruneReleases(releasesDir, { keep = 2, current } = {}) {
+  if (keep < 2) throw new ServiceError('keep at least the current release and the one before it (keep >= 2).');
+  if (!fs.existsSync(releasesDir)) return [];
+  const releases = fs.readdirSync(releasesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && !e.isSymbolicLink())
+    .map((e) => path.join(releasesDir, e.name))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  const keepers = [];
+  if (current) {
+    const resolved = fs.realpathSync(current);
+    keepers.push(...releases.filter((p) => fs.realpathSync(p) === resolved));
+  }
+  for (const release of releases) {
+    if (keepers.length >= keep) break;
+    if (!keepers.includes(release)) keepers.push(release);
+  }
+  const removed = releases.filter((p) => !keepers.includes(p));
+  for (const release of removed) fs.rmSync(release, { recursive: true, force: true });
+  return removed;
+}
+
 // --- operator login -------------------------------------------------------------------
 
 export class LoginCodes {