@omnicross/contracts 0.1.1 → 0.1.3

package/dist/usage-stats-types.d.cts

@@ -0,0 +1,164 @@
+import { UsageEngineOrigin } from './usage-types.cjs';
+
+/**
+ * Usage-statistics DTOs — provider-generic stats row + aggregation views.
+ *
+ * The persisted usage-event row shape and the aggregate query views shared by
+ * embedders that record per-request usage. Storage itself is host-owned (the
+ * serving core only defines the seam); `engineOrigin` uses the OPEN
+ * `UsageEngineOrigin` union from `usage-types` so hosts may narrow it to their
+ * own closed engine list at their boundary.
+ *
+ * @module usage-stats-types
+ */
+
+/**
+ * One captured LLM request, as persisted by the host store.
+ *
+ * `messageId` is nullable because indirect call paths (e.g. subagent-internal
+ * requests) may not map to a host message row. `parentMessageId` is
+ * best-effort — populated when the caller knows the parent, NULL otherwise.
+ */
+interface UsageEventRecord {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    /** Hypothetical-input-cost − actual-cost difference attributable to cache_read tokens. */
+    costSavedByCacheUsd: number;
+    /** JSON-serialised raw provider usage object. Kept for forensics. */
+    rawUsage: string | null;
+    /** Host run-correlation id (owning agent-run, when the host has one). Additive / nullable. */
+    runId?: string | null;
+    /** Host event-correlation id for this LLM call. NULL when unknown. Additive / nullable. */
+    eventId?: string | null;
+}
+/** Input shape for inserting a new event. `id` and `ts` are filled by the recorder/store. */
+type UsageEventInput = Omit<UsageEventRecord, 'id' | 'ts'> & {
+    ts?: number;
+};
+/** Date range for queries. Both bounds are unix-millis; `endTs` is exclusive. */
+interface UsageDateRange {
+    startTs: number;
+    endTs: number;
+}
+interface UsageQueryParams {
+    range: UsageDateRange;
+    /** Optional filter — restrict to a particular session. */
+    sessionId?: string;
+}
+/** Aggregated totals over a date range. */
+interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** Number of events contributing to these totals. */
+    eventCount: number;
+}
+/** Granularity for a usage time-series query. `week` is NOT a bucket — a "week" view is a `day` bucket over a 7-day range. */
+type UsageTimeBucket = 'hour' | 'day' | 'month';
+/**
+ * One bucket of a usage time-series (trend chart). Buckets are query-time
+ * aggregations over the daemon's LOCAL-time boundaries and every bucket in the
+ * requested range is present (empty buckets are zero-filled), ascending by
+ * `bucketStartTs`.
+ */
+interface UsageTimeSeriesBucket {
+    /** Unix-millis of the LOCAL-time bucket boundary (hour start / local midnight / local 1st-of-month). */
+    bucketStartTs: number;
+    /** Frozen locale-agnostic label from LOCAL parts: hour `MM-DD HH:00`, day `YYYY-MM-DD`, month `YYYY-MM`. */
+    label: string;
+    /** Event count in the bucket (0 for a zero-filled bucket). */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+}
+/** One row of the per-model breakdown. */
+interface ModelUsageRow {
+    providerId: string;
+    model: string;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** True when no pricing row exists for (providerId, model) — UIs may show an "unpriced" badge. */
+    unpriced: boolean;
+}
+/** One row of the per-API-key breakdown. NULL apiKeyId is mapped to a sentinel. */
+interface ApiKeyUsageRow {
+    /** `null` represents the unattributed sentinel group. */
+    apiKeyId: string | null;
+    /** Display label resolved by the host store (its key registry, or an "unattributed" fallback). */
+    label: string;
+    providerId: string | null;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/**
+ * Cumulative cache stats for ONE session — a SUM over the session's usage
+ * events. `hitRate` is the cost-oriented aggregate `ΣcacheRead / Σ(prompt-side
+ * tokens)` where the prompt-side total is `input + cacheRead + cacheCreation`
+ * (output excluded).
+ */
+interface SessionCacheStats {
+    sessionId: string;
+    /** Σ uncached prompt tokens (cache miss). */
+    inputTokens: number;
+    /** Σ cache-read (hit) tokens. */
+    cacheReadTokens: number;
+    /** Σ cache-creation (write) tokens — Anthropic; 0 for auto-caching providers. */
+    cacheCreationTokens: number;
+    /** Σ output tokens (not part of the hit-rate denominator). */
+    outputTokens: number;
+    /** Number of usage-event rows for the session. */
+    eventCount: number;
+    /**
+     * ΣcacheRead / Σ(input + cacheRead + cacheCreation), in [0, 1]. 0 when the
+     * session has no prompt-side tokens yet (avoids divide-by-zero).
+     */
+    hitRate: number;
+}
+/** One row in the message-level list (used by message-drilldown UI components). */
+interface MessageUsageRow {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+}
+
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };

package/dist/usage-stats-types.d.ts

@@ -0,0 +1,164 @@
+import { UsageEngineOrigin } from './usage-types.js';
+
+/**
+ * Usage-statistics DTOs — provider-generic stats row + aggregation views.
+ *
+ * The persisted usage-event row shape and the aggregate query views shared by
+ * embedders that record per-request usage. Storage itself is host-owned (the
+ * serving core only defines the seam); `engineOrigin` uses the OPEN
+ * `UsageEngineOrigin` union from `usage-types` so hosts may narrow it to their
+ * own closed engine list at their boundary.
+ *
+ * @module usage-stats-types
+ */
+
+/**
+ * One captured LLM request, as persisted by the host store.
+ *
+ * `messageId` is nullable because indirect call paths (e.g. subagent-internal
+ * requests) may not map to a host message row. `parentMessageId` is
+ * best-effort — populated when the caller knows the parent, NULL otherwise.
+ */
+interface UsageEventRecord {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    /** Hypothetical-input-cost − actual-cost difference attributable to cache_read tokens. */
+    costSavedByCacheUsd: number;
+    /** JSON-serialised raw provider usage object. Kept for forensics. */
+    rawUsage: string | null;
+    /** Host run-correlation id (owning agent-run, when the host has one). Additive / nullable. */
+    runId?: string | null;
+    /** Host event-correlation id for this LLM call. NULL when unknown. Additive / nullable. */
+    eventId?: string | null;
+}
+/** Input shape for inserting a new event. `id` and `ts` are filled by the recorder/store. */
+type UsageEventInput = Omit<UsageEventRecord, 'id' | 'ts'> & {
+    ts?: number;
+};
+/** Date range for queries. Both bounds are unix-millis; `endTs` is exclusive. */
+interface UsageDateRange {
+    startTs: number;
+    endTs: number;
+}
+interface UsageQueryParams {
+    range: UsageDateRange;
+    /** Optional filter — restrict to a particular session. */
+    sessionId?: string;
+}
+/** Aggregated totals over a date range. */
+interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** Number of events contributing to these totals. */
+    eventCount: number;
+}
+/** Granularity for a usage time-series query. `week` is NOT a bucket — a "week" view is a `day` bucket over a 7-day range. */
+type UsageTimeBucket = 'hour' | 'day' | 'month';
+/**
+ * One bucket of a usage time-series (trend chart). Buckets are query-time
+ * aggregations over the daemon's LOCAL-time boundaries and every bucket in the
+ * requested range is present (empty buckets are zero-filled), ascending by
+ * `bucketStartTs`.
+ */
+interface UsageTimeSeriesBucket {
+    /** Unix-millis of the LOCAL-time bucket boundary (hour start / local midnight / local 1st-of-month). */
+    bucketStartTs: number;
+    /** Frozen locale-agnostic label from LOCAL parts: hour `MM-DD HH:00`, day `YYYY-MM-DD`, month `YYYY-MM`. */
+    label: string;
+    /** Event count in the bucket (0 for a zero-filled bucket). */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+}
+/** One row of the per-model breakdown. */
+interface ModelUsageRow {
+    providerId: string;
+    model: string;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+    /** True when no pricing row exists for (providerId, model) — UIs may show an "unpriced" badge. */
+    unpriced: boolean;
+}
+/** One row of the per-API-key breakdown. NULL apiKeyId is mapped to a sentinel. */
+interface ApiKeyUsageRow {
+    /** `null` represents the unattributed sentinel group. */
+    apiKeyId: string | null;
+    /** Display label resolved by the host store (its key registry, or an "unattributed" fallback). */
+    label: string;
+    providerId: string | null;
+    eventCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/**
+ * Cumulative cache stats for ONE session — a SUM over the session's usage
+ * events. `hitRate` is the cost-oriented aggregate `ΣcacheRead / Σ(prompt-side
+ * tokens)` where the prompt-side total is `input + cacheRead + cacheCreation`
+ * (output excluded).
+ */
+interface SessionCacheStats {
+    sessionId: string;
+    /** Σ uncached prompt tokens (cache miss). */
+    inputTokens: number;
+    /** Σ cache-read (hit) tokens. */
+    cacheReadTokens: number;
+    /** Σ cache-creation (write) tokens — Anthropic; 0 for auto-caching providers. */
+    cacheCreationTokens: number;
+    /** Σ output tokens (not part of the hit-rate denominator). */
+    outputTokens: number;
+    /** Number of usage-event rows for the session. */
+    eventCount: number;
+    /**
+     * ΣcacheRead / Σ(input + cacheRead + cacheCreation), in [0, 1]. 0 when the
+     * session has no prompt-side tokens yet (avoids divide-by-zero).
+     */
+    hitRate: number;
+}
+/** One row in the message-level list (used by message-drilldown UI components). */
+interface MessageUsageRow {
+    id: string;
+    ts: number;
+    messageId: string | null;
+    parentMessageId: string | null;
+    sessionId: string | null;
+    providerId: string;
+    model: string;
+    apiKeyId: string | null;
+    engineOrigin: UsageEngineOrigin;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+    costUsd: number;
+    costSavedByCacheUsd: number;
+}
+
+export type { ApiKeyUsageRow, MessageUsageRow, ModelUsageRow, SessionCacheStats, UsageDateRange, UsageEventInput, UsageEventRecord, UsageQueryParams, UsageTimeBucket, UsageTimeSeriesBucket, UsageTotals };

package/dist/voucher-types.cjs

@@ -0,0 +1,32 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/voucher-types.ts
+var voucher_types_exports = {};
+__export(voucher_types_exports, {
+  DEFAULT_VOUCHER_CONFIG: () => DEFAULT_VOUCHER_CONFIG
+});
+module.exports = __toCommonJS(voucher_types_exports);
+var DEFAULT_VOUCHER_CONFIG = {
+  enabled: false
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_VOUCHER_CONFIG
+});

package/dist/voucher-types.d.cts

@@ -0,0 +1,153 @@
+/**
+ * Voucher (redemption-card) contracts (voucher-redemption #9, design D2/D8).
+ *
+ * A voucher is a redeemable credit/renewal card layered on top of the outbound
+ * key-policy (#4): an admin generates a card (`CC_<entropy>`), a key-holder
+ * redeems it to raise their key's `totalCostLimitUsd` (credit) or extend its
+ * `expiresAt` (renewal). Dependency-light shapes shared across `@omnicross/*`:
+ *
+ *  - `VoucherRecord` — the FROZEN stored card. It is a CREDENTIAL RECORD but holds
+ *    NO plaintext code: only the sha256 `codeHash` (the redeem lookup key) + a
+ *    short display `codePrefix`. The plaintext `CC_…` is returned ONCE at
+ *    generation and NEVER persisted or logged. A secret-scan test asserts no
+ *    `CC_` plaintext survives in a written record.
+ *  - `VoucherGrant` — the ABSOLUTE target recorded on the card at redeem time so
+ *    the apply step (`outboundApiKeysSetPolicy`) is idempotently re-appliable
+ *    after a crash between the CAS flip and the apply (design D4).
+ *  - `VoucherInfo` — the admin-safe DTO (prefix + status + value + caps only,
+ *    NEVER the `codeHash`).
+ *  - `VoucherConfig` — the `voucher` config segment. `enabled` default OFF ⇒ the
+ *    redeem endpoint is inert + no key is ever mutated ⇒ byte-identical zero
+ *    regression, purely additive on #4.
+ *
+ * @module voucher-types
+ */
+/** A card either adds USD credit or extends the key's lifetime. */
+type VoucherType = 'credit' | 'renewal';
+/** Card lifecycle. A card leaves `unredeemed` exactly once (CAS, design D4). */
+type VoucherStatus = 'unredeemed' | 'redeemed' | 'revoked';
+/**
+ * The ABSOLUTE grant a redemption applies to a key (design D4/D5). Recorded on
+ * the voucher AT the CAS flip so re-applying it after an interrupted redeem is a
+ * no-op (idempotent to the absolute value → never double-spends). A `credit`
+ * card records `totalCostLimitUsd`; a `renewal` card records `expiresAt`.
+ */
+interface VoucherGrant {
+    /** Absolute new `totalCostLimitUsd` for the key (credit cards). */
+    totalCostLimitUsd?: number;
+    /** Absolute new `expiresAt` (epoch ms) for the key (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * One stored redemption card (design D2, FROZEN). Holds a HASH of the code
+ * (never the plaintext) + a display prefix. The `granted*` fields are the
+ * absolute target recorded at redeem time (idempotent re-apply, design D4).
+ */
+interface VoucherRecord {
+    /** Card id (independent of the code). */
+    id: string;
+    /** sha256 of the `CC_<entropy>` code — the redeem lookup key. NEVER plaintext. */
+    codeHash: string;
+    /** Short display prefix for the admin list (e.g. `CC_AB…`). NEVER the full code. */
+    codePrefix: string;
+    /** Credit (adds USD) or renewal (extends expiry). */
+    type: VoucherType;
+    /** `credit`: USD added to the key's `totalCostLimitUsd`. */
+    creditUsd?: number;
+    /** `renewal`: days added to the key's `expiresAt`. */
+    renewalDays?: number;
+    /** Anti-abuse cap on the RESULTING key `totalCostLimitUsd` (design D5). */
+    maxTotalCostLimitUsd?: number;
+    /** Anti-abuse cap on the RESULTING key lifetime, in days from now (design D5). */
+    maxExpiryDays?: number;
+    /** Lifecycle status. */
+    status: VoucherStatus;
+    /** Epoch ms the card was generated. */
+    createdAt: number;
+    /** Epoch ms the card was redeemed (set on the CAS flip). */
+    redeemedAt?: number;
+    /** The key id that redeemed the card (single-key binding). */
+    redeemedByKeyId?: string;
+    /**
+     * Whether the grant has been APPLIED to the key (design D4, revised). The CAS
+     * flip sets this `false`; the apply sets it `true` after a successful
+     * `outboundApiKeysSetPolicy`. `redeemed && grantApplied !== true` means "flipped
+     * but not (yet) applied" — the apply (of the recorded ABSOLUTE below) re-runs on
+     * the next redeem for the key, before that redeem computes anything. It is
+     * `grantApplied` that says "no work left"; the apply itself is idempotent
+     * (re-applying the same absolute is a no-op), so a crash between the apply and
+     * this mark never double-credits.
+     */
+    grantApplied?: boolean;
+    /**
+     * The recorded ABSOLUTE `totalCostLimitUsd` target (the intended final key
+     * value), computed at flip time from the CURRENT policy read INSIDE the per-key
+     * mutex. This is the AUTHORITATIVE apply source on BOTH the first pass and the
+     * reconcile/replay path — re-applying it is idempotent (never double-credits).
+     * Because redemptions for a key are serialized and a stranded card is reconciled
+     * before the next card computes, the recorded absolute is never stale.
+     */
+    grantedTotalCostLimitUsd?: number;
+    /** The recorded ABSOLUTE `expiresAt` target (see `grantedTotalCostLimitUsd`). */
+    grantedExpiresAt?: number;
+    /** Epoch ms the card was revoked. */
+    revokedAt?: number;
+}
+/**
+ * The admin-safe voucher DTO (design D2). NEVER carries the `codeHash` — the
+ * admin sees the display prefix + status + value + caps only. This is the ONLY
+ * projection an admin GET returns.
+ */
+interface VoucherInfo {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    creditUsd?: number;
+    renewalDays?: number;
+    maxTotalCostLimitUsd?: number;
+    maxExpiryDays?: number;
+    status: VoucherStatus;
+    createdAt: number;
+    redeemedAt?: number;
+    redeemedByKeyId?: string;
+    grantApplied?: boolean;
+    grantedTotalCostLimitUsd?: number;
+    grantedExpiresAt?: number;
+    revokedAt?: number;
+}
+/**
+ * The one-time create result: `plaintextOnce` (the `CC_…` code) is shown exactly
+ * once at generation and never again — only its hash is stored (design D3).
+ */
+interface VoucherCreated {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    createdAt: number;
+    /** The plaintext `CC_…` code — the ONLY time it crosses the wire. */
+    plaintextOnce: string;
+}
+/**
+ * The result a successful redeem returns to the key-holder (design D2). Reveals
+ * ONLY this key's own new balance/expiry — never any other card or key.
+ */
+interface VoucherRedeemResult {
+    type: VoucherType;
+    /** The key's new absolute `totalCostLimitUsd` (credit cards). */
+    totalCostLimitUsd?: number;
+    /** The key's new absolute `expiresAt` (epoch ms) (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * The `voucher` config segment (design D8), normalized like `audit`/`billing`.
+ * `enabled` default FALSE ⇒ the redeem endpoint rejects + no admin generate ⇒ no
+ * key is ever mutated ⇒ byte-identical zero regression, purely additive on #4.
+ */
+interface VoucherConfig {
+    /** Master switch; default FALSE (zero regression, inert product). */
+    enabled: boolean;
+}
+/** Frozen defaults for the `voucher` segment (SSOT). */
+declare const DEFAULT_VOUCHER_CONFIG: VoucherConfig;
+
+export { DEFAULT_VOUCHER_CONFIG, type VoucherConfig, type VoucherCreated, type VoucherGrant, type VoucherInfo, type VoucherRecord, type VoucherRedeemResult, type VoucherStatus, type VoucherType };

package/dist/voucher-types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Voucher (redemption-card) contracts (voucher-redemption #9, design D2/D8).
+ *
+ * A voucher is a redeemable credit/renewal card layered on top of the outbound
+ * key-policy (#4): an admin generates a card (`CC_<entropy>`), a key-holder
+ * redeems it to raise their key's `totalCostLimitUsd` (credit) or extend its
+ * `expiresAt` (renewal). Dependency-light shapes shared across `@omnicross/*`:
+ *
+ *  - `VoucherRecord` — the FROZEN stored card. It is a CREDENTIAL RECORD but holds
+ *    NO plaintext code: only the sha256 `codeHash` (the redeem lookup key) + a
+ *    short display `codePrefix`. The plaintext `CC_…` is returned ONCE at
+ *    generation and NEVER persisted or logged. A secret-scan test asserts no
+ *    `CC_` plaintext survives in a written record.
+ *  - `VoucherGrant` — the ABSOLUTE target recorded on the card at redeem time so
+ *    the apply step (`outboundApiKeysSetPolicy`) is idempotently re-appliable
+ *    after a crash between the CAS flip and the apply (design D4).
+ *  - `VoucherInfo` — the admin-safe DTO (prefix + status + value + caps only,
+ *    NEVER the `codeHash`).
+ *  - `VoucherConfig` — the `voucher` config segment. `enabled` default OFF ⇒ the
+ *    redeem endpoint is inert + no key is ever mutated ⇒ byte-identical zero
+ *    regression, purely additive on #4.
+ *
+ * @module voucher-types
+ */
+/** A card either adds USD credit or extends the key's lifetime. */
+type VoucherType = 'credit' | 'renewal';
+/** Card lifecycle. A card leaves `unredeemed` exactly once (CAS, design D4). */
+type VoucherStatus = 'unredeemed' | 'redeemed' | 'revoked';
+/**
+ * The ABSOLUTE grant a redemption applies to a key (design D4/D5). Recorded on
+ * the voucher AT the CAS flip so re-applying it after an interrupted redeem is a
+ * no-op (idempotent to the absolute value → never double-spends). A `credit`
+ * card records `totalCostLimitUsd`; a `renewal` card records `expiresAt`.
+ */
+interface VoucherGrant {
+    /** Absolute new `totalCostLimitUsd` for the key (credit cards). */
+    totalCostLimitUsd?: number;
+    /** Absolute new `expiresAt` (epoch ms) for the key (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * One stored redemption card (design D2, FROZEN). Holds a HASH of the code
+ * (never the plaintext) + a display prefix. The `granted*` fields are the
+ * absolute target recorded at redeem time (idempotent re-apply, design D4).
+ */
+interface VoucherRecord {
+    /** Card id (independent of the code). */
+    id: string;
+    /** sha256 of the `CC_<entropy>` code — the redeem lookup key. NEVER plaintext. */
+    codeHash: string;
+    /** Short display prefix for the admin list (e.g. `CC_AB…`). NEVER the full code. */
+    codePrefix: string;
+    /** Credit (adds USD) or renewal (extends expiry). */
+    type: VoucherType;
+    /** `credit`: USD added to the key's `totalCostLimitUsd`. */
+    creditUsd?: number;
+    /** `renewal`: days added to the key's `expiresAt`. */
+    renewalDays?: number;
+    /** Anti-abuse cap on the RESULTING key `totalCostLimitUsd` (design D5). */
+    maxTotalCostLimitUsd?: number;
+    /** Anti-abuse cap on the RESULTING key lifetime, in days from now (design D5). */
+    maxExpiryDays?: number;
+    /** Lifecycle status. */
+    status: VoucherStatus;
+    /** Epoch ms the card was generated. */
+    createdAt: number;
+    /** Epoch ms the card was redeemed (set on the CAS flip). */
+    redeemedAt?: number;
+    /** The key id that redeemed the card (single-key binding). */
+    redeemedByKeyId?: string;
+    /**
+     * Whether the grant has been APPLIED to the key (design D4, revised). The CAS
+     * flip sets this `false`; the apply sets it `true` after a successful
+     * `outboundApiKeysSetPolicy`. `redeemed && grantApplied !== true` means "flipped
+     * but not (yet) applied" — the apply (of the recorded ABSOLUTE below) re-runs on
+     * the next redeem for the key, before that redeem computes anything. It is
+     * `grantApplied` that says "no work left"; the apply itself is idempotent
+     * (re-applying the same absolute is a no-op), so a crash between the apply and
+     * this mark never double-credits.
+     */
+    grantApplied?: boolean;
+    /**
+     * The recorded ABSOLUTE `totalCostLimitUsd` target (the intended final key
+     * value), computed at flip time from the CURRENT policy read INSIDE the per-key
+     * mutex. This is the AUTHORITATIVE apply source on BOTH the first pass and the
+     * reconcile/replay path — re-applying it is idempotent (never double-credits).
+     * Because redemptions for a key are serialized and a stranded card is reconciled
+     * before the next card computes, the recorded absolute is never stale.
+     */
+    grantedTotalCostLimitUsd?: number;
+    /** The recorded ABSOLUTE `expiresAt` target (see `grantedTotalCostLimitUsd`). */
+    grantedExpiresAt?: number;
+    /** Epoch ms the card was revoked. */
+    revokedAt?: number;
+}
+/**
+ * The admin-safe voucher DTO (design D2). NEVER carries the `codeHash` — the
+ * admin sees the display prefix + status + value + caps only. This is the ONLY
+ * projection an admin GET returns.
+ */
+interface VoucherInfo {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    creditUsd?: number;
+    renewalDays?: number;
+    maxTotalCostLimitUsd?: number;
+    maxExpiryDays?: number;
+    status: VoucherStatus;
+    createdAt: number;
+    redeemedAt?: number;
+    redeemedByKeyId?: string;
+    grantApplied?: boolean;
+    grantedTotalCostLimitUsd?: number;
+    grantedExpiresAt?: number;
+    revokedAt?: number;
+}
+/**
+ * The one-time create result: `plaintextOnce` (the `CC_…` code) is shown exactly
+ * once at generation and never again — only its hash is stored (design D3).
+ */
+interface VoucherCreated {
+    id: string;
+    codePrefix: string;
+    type: VoucherType;
+    createdAt: number;
+    /** The plaintext `CC_…` code — the ONLY time it crosses the wire. */
+    plaintextOnce: string;
+}
+/**
+ * The result a successful redeem returns to the key-holder (design D2). Reveals
+ * ONLY this key's own new balance/expiry — never any other card or key.
+ */
+interface VoucherRedeemResult {
+    type: VoucherType;
+    /** The key's new absolute `totalCostLimitUsd` (credit cards). */
+    totalCostLimitUsd?: number;
+    /** The key's new absolute `expiresAt` (epoch ms) (renewal cards). */
+    expiresAt?: number;
+}
+/**
+ * The `voucher` config segment (design D8), normalized like `audit`/`billing`.
+ * `enabled` default FALSE ⇒ the redeem endpoint rejects + no admin generate ⇒ no
+ * key is ever mutated ⇒ byte-identical zero regression, purely additive on #4.
+ */
+interface VoucherConfig {
+    /** Master switch; default FALSE (zero regression, inert product). */
+    enabled: boolean;
+}
+/** Frozen defaults for the `voucher` segment (SSOT). */
+declare const DEFAULT_VOUCHER_CONFIG: VoucherConfig;
+
+export { DEFAULT_VOUCHER_CONFIG, type VoucherConfig, type VoucherCreated, type VoucherGrant, type VoucherInfo, type VoucherRecord, type VoucherRedeemResult, type VoucherStatus, type VoucherType };

package/dist/voucher-types.js

@@ -0,0 +1,7 @@
+// src/voucher-types.ts
+var DEFAULT_VOUCHER_CONFIG = {
+  enabled: false
+};
+export {
+  DEFAULT_VOUCHER_CONFIG
+};