@nomosprotocol/sdk 1.3.3 → 1.4.0

package/dist/index.d.cts

@@ -128,7 +128,10 @@ interface CanResult {
     }>;
     /** RECOMMENDED maximum seconds to hold this verdict before re-querying or re-checking the
      *  issuer's revocation list (NOMOS-SPEC-006 §6.2). Advisory; absent when the artifact isn't
-     *  structurally revocable on this deployment — treat absence as "unknown," not "safe forever." */
+     *  structurally revocable on this deployment — treat absence as "unknown," not "safe forever."
+     *  Disclosed gap: only ever set on the public authority rail today — client.can() and the
+     *  presented-artifact rail don't emit it yet, so apply the same "don't hold a stale verdict
+     *  across a meaningful delay" discipline manually on those two until that's closed. */
     max_age?: number;
     /** Present only when your own authenticated artifact answered — that rail's own provenance
      *  (a hash you can store for compliance), not a permanent public transcript like `query_id`. */
@@ -143,8 +146,74 @@ interface CanResult {
     revoked?: boolean;
     /** Present only alongside `revoked: true` — the issuer's stated reason. */
     revocation_reason?: string;
+    /** NOMOS-SPEC-007 §5.5 — chain-of-trust rail only. How confidently the chain's own KEY
+     *  revocation was checked: `"live"` (checked against a real revocation source — always the
+     *  case on this hosted deployment), `"staple"` (a presenter-supplied freshness staple was
+     *  used instead — never happens here, since this endpoint always holds its own list), or
+     *  `"unchecked"` (neither — e.g. the pinned root, which nothing else can vouch for). Omitted
+     *  (not a guess) on the Exchange/private-artifact rails, where this concept doesn't apply. */
+    revocation_checked?: 'live' | 'staple' | 'unchecked';
+}
+interface ConservedStateInfo {
+    artifact_id: string;
+    scope: string;
+    limit_amount: number;
+    consumed: number;
+    reserved: number;
+    available: number;
+    /** The raw ledger fact to pass into `can()` as `consumed_before` — already consumed+reserved
+     *  (outstanding reservations count as spoken-for), not consumed alone. */
+    consumed_before: number;
+    version: number;
+    state_digest: string;
+}
+/** Reserve against a ledger using a real `can()` decision. */
+interface ReserveByQueryParams {
+    artifact_id: string;
+    scope: string;
+    amount: number;
+    /** The `query_id` from a real `can()`/`nomos.can()` call that returned AUTHORIZED.
+     *  `reserve()` looks that decision up itself and derives its own binding from it — this is a
+     *  lookup key, not a claim you're asserting, and a made-up or already-used one is rejected. */
+    query_id: string;
+    action: string;
+    /** Optimistic-concurrency check: reject unless the ledger's state still matches what you last
+     *  read via `conservedState.get()`. Omit only when you have no prior read to compare against. */
+    expected_state_digest?: string;
+    ttl_seconds?: number;
+}
+/** Reserve against a ledger using a NOMOS-SPEC-008 Act: the ledger verifies the Act itself (its
+ *  own pinned root and audience id, its own `consumed_before`, single-use nonce) and holds exactly
+ *  `act.action.params.amount` for `act.action.type === 'conserved_state.reserve'`, or nothing. */
+interface ReserveByActParams {
+    artifact_id: string;
+    scope: string;
+    act: Record<string, unknown>;
+    ttl_seconds?: number;
+}
+type ReserveParams = ReserveByQueryParams | ReserveByActParams;
+/** The cryptographically-bound reservation object — R-12 §5. */
+interface Reservation {
+    reservation_id: string;
+    authority_seal: string;
+    decision_digest: string;
+    agent: string;
+    action: string;
+    scope: string;
+    amount: number;
+    state_digest: string;
+    expires_at: string;
+    status: 'held' | 'settled' | 'released' | 'expired';
 }
-type ChainVerdictDecision = 'ALLOWED' | 'ISSUER_NOT_RECOGNIZED' | 'KEY_REVOKED' | 'SEAL_INVALID' | 'MALFORMED';
+interface ConservedStateReceipt {
+    reservation_id: string;
+    outcome: 'settled' | 'released';
+    amount: number;
+    ledger_key: string;
+    resolved_at: string;
+    reference?: string;
+}
+type ChainVerdictDecision = 'ALLOWED' | 'ISSUER_NOT_RECOGNIZED' | 'KEY_REVOKED' | 'CERTIFICATE_REVOKED' | 'OUT_OF_SCOPE' | 'SEAL_INVALID' | 'MALFORMED';
 interface KeyCertificate {
     parent_kid: string;
     child_kid: string;
@@ -179,6 +248,15 @@ interface VerifyChainResult {
     reason?: string;
     /** Present only when decision === 'KEY_REVOKED'. */
     revoked_kid?: string;
+    /** Present only when decision === 'CERTIFICATE_REVOKED'. */
+    revoked_fingerprint?: string;
+    /** Present only when decision === 'OUT_OF_SCOPE' — which scope dimension failed. */
+    dimension?: string;
+    /** Present on ALLOWED and OUT_OF_SCOPE — the resolved chain's accumulated scope. */
+    effective_scope?: string;
+    /** Present only when decision === 'ALLOWED' (NOMOS-SPEC-007 §5.5). See CanResult's field of
+     *  the same name for the full tri-state explanation. */
+    revocation_checked?: 'live' | 'staple' | 'unchecked';
     /** Human-readable detail for any non-ALLOWED decision. */
     detail?: string;
 }
@@ -509,32 +587,107 @@ declare class Webhooks {
     verifySignature(payload: string | Uint8Array, signature: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
 }
 
+/**
+ * The state layer for a conserved (depleting) budget — R-12, a design in progress
+ * (docs/design-notes/conserved-state-authority.md in the platform repo; public mirror:
+ * computableauthority.com/research/conserved-state-authority). PROTOTYPE, not a numbered spec.
+ *
+ * `can()` stays exactly what it always was: pure, stateless, given facts and returning a
+ * verdict. Nothing here changes that. This resource is what a caller consults BEFORE calling
+ * `can()` (to build the `consumed_before` fact) and commits to AFTER `can()` returns AUTHORIZED
+ * and the caller has actually decided to act — never at `can()` time itself (repeatedly calling
+ * `can()` while deciding must never itself burn the budget).
+ *
+ * @example
+ * const state = await client.conservedState.get('supplier-budget-2026', 'supplier:acme');
+ * const verdict = await client.can({ artifact_id: 'supplier-budget-2026', consumed_before: state.consumed_before });
+ * if (verdict.allowed) {
+ *   const reservation = await client.conservedState.reserve({
+ *     artifact_id: 'supplier-budget-2026', scope: 'supplier:acme',
+ *     amount: 5000, query_id: verdict.query_id!, action: 'payments.transfer',
+ *   });
+ *   try {
+ *     // ... perform the real action ...
+ *     await client.conservedState.settle(reservation.reservation_id);
+ *   } catch {
+ *     await client.conservedState.release(reservation.reservation_id);
+ *   }
+ * }
+ */
+declare class ConservedState {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Read a ledger's current balance — no auth required, same posture as `can()`'s own keyless
+     * rail (reading how much budget remains is no more sensitive than reading a verdict).
+     */
+    get(artifactId: string, scope: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateInfo>>;
+    /**
+     * Commit capacity against a REAL, AUTHORIZED `can()` decision. Authenticated — unlike `can()`,
+     * spending against a shared budget requires an API key or session; `agent` on the returned
+     * reservation traces to that authenticated identity, never a value you pass in.
+     *
+     * Throws (via the SDK's standard NomosError hierarchy; `err.details?.code` carries the
+     * server's own code): `DECISION_NOT_FOUND` (the query_id names no real query), `DECISION_NOT
+     * _AUTHORIZED` (that decision didn't verdict AUTHORIZED for this artifact), `DECISION_ALREADY
+     * _USED` (already bound to a reservation — one decision authorizes one, ever), `STATE_CONFLICT`
+     * (a stale `expected_state_digest`), `INSUFFICIENT_CAPACITY` (`err.details.requested`/
+     * `.available` carry the numbers), or `NO_LEDGER` (nobody has declared this budget yet).
+     *
+     * Passing `{ artifact_id, scope, act }` instead authorizes the hold with a NOMOS-SPEC-008 Act.
+     * Extra codes: `ACT_NOT_ACCEPTED` (the ledger has no Act binding) and `ACT_REJECTED`, with the
+     * verifier's full answer in `err.details.result` — for `INCOMPLETE` it names the open rules and
+     * the facts whose testimony would decide them.
+     */
+    reserve(params: ReserveParams, opts?: RequestOptions): Promise<WithLastResponse<Reservation>>;
+    /**
+     * The reserved action succeeded — moves the hold into real, settled spend. Idempotent when
+     * you pass the same `reference` again for a retry (e.g. after a network timeout): you get the
+     * ORIGINAL receipt back, never a double-charge.
+     */
+    settle(reservationId: string, reference?: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateReceipt>>;
+    /**
+     * The reserved action failed, or you decided not to act — gives the hold's capacity back
+     * without ever touching what's actually been spent.
+     */
+    release(reservationId: string, reference?: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateReceipt>>;
+}
+
 type NomosErrorCode = 'authentication_error' | 'authorization_error' | 'rate_limit_error' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'webhook_signature_error' | 'payment_required' | 'issuer_not_trusted';
 declare class NomosError extends Error {
     readonly code: NomosErrorCode;
     readonly status?: number;
     readonly requestId?: string;
-    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string);
+    /** The full parsed JSON response body, when the server sent one — every field it put there
+     *  (its own `code`, and anything endpoint-specific like `requested`/`available` on a
+     *  conserved-state capacity rejection, or `price_usd`/`purchase_url` before those got a
+     *  dedicated error class). `NomosError`'s own `code` above is the SDK's fixed HTTP-status
+     *  taxonomy; `details?.code` is the SERVER's own, finer-grained application code — the two
+     *  are deliberately not conflated into one field. */
+    readonly details?: unknown;
+    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string, details?: unknown);
 }
 declare class NomosAuthenticationError extends NomosError {
-    constructor(message?: string, requestId?: string);
+    constructor(message?: string, requestId?: string, details?: unknown);
 }
 declare class NomosAuthorizationError extends NomosError {
-    constructor(message?: string, requestId?: string);
+    constructor(message?: string, requestId?: string, details?: unknown);
 }
 declare class NomosRateLimitError extends NomosError {
     readonly retryAfter?: number;
-    constructor(message?: string, retryAfter?: number, requestId?: string);
+    constructor(message?: string, retryAfter?: number, requestId?: string, details?: unknown);
 }
+/** `details` is the parsed response body — kept as its own constructor param (rather than just
+ *  relying on the base class field) since it long predates NomosError.details and every caller
+ *  already passes it positionally in this slot; unchanged for backward compatibility. */
 declare class NomosValidationError extends NomosError {
-    readonly details?: unknown;
     constructor(message: string, details?: unknown, requestId?: string);
 }
 declare class NomosNotFoundError extends NomosError {
-    constructor(message: string, requestId?: string);
+    constructor(message: string, requestId?: string, details?: unknown);
 }
 declare class NomosAPIError extends NomosError {
-    constructor(message: string, status: number, requestId?: string);
+    constructor(message: string, status: number, requestId?: string, details?: unknown);
 }
 declare class NomosNetworkError extends NomosError {
     constructor(message: string);
@@ -551,14 +704,22 @@ declare class NomosPaymentRequiredError extends NomosError {
     readonly purchaseUrl: string;
     constructor(message: string, priceUsd: number, purchaseUrl: string, requestId?: string);
 }
-/** can()'s chain-of-trust rail couldn't establish that the presented artifact is trustworthy —
- *  an unrecognized issuer, a revoked key, a tampered seal, or a malformed presentation. This is
- *  deliberately NOT a DENIED verdict: "the rules say no" and "we never got far enough to ask the
- *  rules anything" are different claims, and collapsing them would tell the caller the wrong
- *  thing to do next (re-presenting a better chain can fix the first case; it can never fix a
- *  genuinely tampered artifact). `reason` is the underlying chain decision
- *  (ISSUER_NOT_RECOGNIZED / KEY_REVOKED / SEAL_INVALID / MALFORMED) for callers that need to
- *  distinguish them. */
+/** can()'s chain-of-trust rail could not establish that the presented artifact carries authority
+ *  it is entitled to — an unrecognized issuer, a revoked key, a delegation that never covered
+ *  this artifact, a tampered seal, or a malformed presentation. This is deliberately NOT a DENIED
+ *  verdict: "the rules say no" and "we never got far enough to ask the rules anything" are
+ *  different claims, and collapsing them would tell the caller the wrong thing to do next.
+ *
+ *  `reason` carries the underlying chain decision so callers can distinguish them, because the
+ *  right next action genuinely differs:
+ *    ISSUER_NOT_RECOGNIZED — presenting a more complete chain may fix this
+ *    KEY_REVOKED           — that key is dead; a different, unrevoked chain might work
+ *    CERTIFICATE_REVOKED   — one delegation was withdrawn; another certificate for the same
+ *                            key may still resolve
+ *    OUT_OF_SCOPE          — the issuer IS recognized but was not delegated authority over this
+ *                            artifact; only a broader (validly issued) delegation fixes it
+ *    SEAL_INVALID          — the artifact itself was altered; nothing about presentation helps
+ *    MALFORMED             — the request shape was wrong (a client-side bug) */
 declare class NomosIssuerNotTrustedError extends NomosError {
     readonly reason: string;
     constructor(message: string, reason: string, requestId?: string);
@@ -596,6 +757,9 @@ declare class Nomos {
     readonly artifacts: Artifacts;
     readonly governance: Governance;
     readonly webhooks: Webhooks;
+    /** The R-12 conserved-state (depleting-budget) state layer — PROTOTYPE, not a numbered spec.
+     *  See resources/conserved-state.ts for the full reserve/settle/release lifecycle. */
+    readonly conservedState: ConservedState;
     /** Whether this instance is using a live or test API key. */
     readonly mode: 'live' | 'test';
     static readonly errors: typeof errors;
@@ -645,4 +809,4 @@ declare const nomos: {
  */
 declare function verifyChain(params: VerifyChainParams, opts?: VerifyChainOptions): Promise<VerifyChainResult>;
 
-export { type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type CanOptions, type CanParams, type CanResult, type CanVerdict, type ChainVerdictDecision, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type KeyCertificate, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos, verifyChain };
+export { type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type CanOptions, type CanParams, type CanResult, type CanVerdict, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type KeyCertificate, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos, verifyChain };

package/dist/index.d.ts

@@ -128,7 +128,10 @@ interface CanResult {
     }>;
     /** RECOMMENDED maximum seconds to hold this verdict before re-querying or re-checking the
      *  issuer's revocation list (NOMOS-SPEC-006 §6.2). Advisory; absent when the artifact isn't
-     *  structurally revocable on this deployment — treat absence as "unknown," not "safe forever." */
+     *  structurally revocable on this deployment — treat absence as "unknown," not "safe forever."
+     *  Disclosed gap: only ever set on the public authority rail today — client.can() and the
+     *  presented-artifact rail don't emit it yet, so apply the same "don't hold a stale verdict
+     *  across a meaningful delay" discipline manually on those two until that's closed. */
     max_age?: number;
     /** Present only when your own authenticated artifact answered — that rail's own provenance
      *  (a hash you can store for compliance), not a permanent public transcript like `query_id`. */
@@ -143,8 +146,74 @@ interface CanResult {
     revoked?: boolean;
     /** Present only alongside `revoked: true` — the issuer's stated reason. */
     revocation_reason?: string;
+    /** NOMOS-SPEC-007 §5.5 — chain-of-trust rail only. How confidently the chain's own KEY
+     *  revocation was checked: `"live"` (checked against a real revocation source — always the
+     *  case on this hosted deployment), `"staple"` (a presenter-supplied freshness staple was
+     *  used instead — never happens here, since this endpoint always holds its own list), or
+     *  `"unchecked"` (neither — e.g. the pinned root, which nothing else can vouch for). Omitted
+     *  (not a guess) on the Exchange/private-artifact rails, where this concept doesn't apply. */
+    revocation_checked?: 'live' | 'staple' | 'unchecked';
+}
+interface ConservedStateInfo {
+    artifact_id: string;
+    scope: string;
+    limit_amount: number;
+    consumed: number;
+    reserved: number;
+    available: number;
+    /** The raw ledger fact to pass into `can()` as `consumed_before` — already consumed+reserved
+     *  (outstanding reservations count as spoken-for), not consumed alone. */
+    consumed_before: number;
+    version: number;
+    state_digest: string;
+}
+/** Reserve against a ledger using a real `can()` decision. */
+interface ReserveByQueryParams {
+    artifact_id: string;
+    scope: string;
+    amount: number;
+    /** The `query_id` from a real `can()`/`nomos.can()` call that returned AUTHORIZED.
+     *  `reserve()` looks that decision up itself and derives its own binding from it — this is a
+     *  lookup key, not a claim you're asserting, and a made-up or already-used one is rejected. */
+    query_id: string;
+    action: string;
+    /** Optimistic-concurrency check: reject unless the ledger's state still matches what you last
+     *  read via `conservedState.get()`. Omit only when you have no prior read to compare against. */
+    expected_state_digest?: string;
+    ttl_seconds?: number;
+}
+/** Reserve against a ledger using a NOMOS-SPEC-008 Act: the ledger verifies the Act itself (its
+ *  own pinned root and audience id, its own `consumed_before`, single-use nonce) and holds exactly
+ *  `act.action.params.amount` for `act.action.type === 'conserved_state.reserve'`, or nothing. */
+interface ReserveByActParams {
+    artifact_id: string;
+    scope: string;
+    act: Record<string, unknown>;
+    ttl_seconds?: number;
+}
+type ReserveParams = ReserveByQueryParams | ReserveByActParams;
+/** The cryptographically-bound reservation object — R-12 §5. */
+interface Reservation {
+    reservation_id: string;
+    authority_seal: string;
+    decision_digest: string;
+    agent: string;
+    action: string;
+    scope: string;
+    amount: number;
+    state_digest: string;
+    expires_at: string;
+    status: 'held' | 'settled' | 'released' | 'expired';
 }
-type ChainVerdictDecision = 'ALLOWED' | 'ISSUER_NOT_RECOGNIZED' | 'KEY_REVOKED' | 'SEAL_INVALID' | 'MALFORMED';
+interface ConservedStateReceipt {
+    reservation_id: string;
+    outcome: 'settled' | 'released';
+    amount: number;
+    ledger_key: string;
+    resolved_at: string;
+    reference?: string;
+}
+type ChainVerdictDecision = 'ALLOWED' | 'ISSUER_NOT_RECOGNIZED' | 'KEY_REVOKED' | 'CERTIFICATE_REVOKED' | 'OUT_OF_SCOPE' | 'SEAL_INVALID' | 'MALFORMED';
 interface KeyCertificate {
     parent_kid: string;
     child_kid: string;
@@ -179,6 +248,15 @@ interface VerifyChainResult {
     reason?: string;
     /** Present only when decision === 'KEY_REVOKED'. */
     revoked_kid?: string;
+    /** Present only when decision === 'CERTIFICATE_REVOKED'. */
+    revoked_fingerprint?: string;
+    /** Present only when decision === 'OUT_OF_SCOPE' — which scope dimension failed. */
+    dimension?: string;
+    /** Present on ALLOWED and OUT_OF_SCOPE — the resolved chain's accumulated scope. */
+    effective_scope?: string;
+    /** Present only when decision === 'ALLOWED' (NOMOS-SPEC-007 §5.5). See CanResult's field of
+     *  the same name for the full tri-state explanation. */
+    revocation_checked?: 'live' | 'staple' | 'unchecked';
     /** Human-readable detail for any non-ALLOWED decision. */
     detail?: string;
 }
@@ -509,32 +587,107 @@ declare class Webhooks {
     verifySignature(payload: string | Uint8Array, signature: string, secret: string, toleranceSeconds?: number): Promise<boolean>;
 }
 
+/**
+ * The state layer for a conserved (depleting) budget — R-12, a design in progress
+ * (docs/design-notes/conserved-state-authority.md in the platform repo; public mirror:
+ * computableauthority.com/research/conserved-state-authority). PROTOTYPE, not a numbered spec.
+ *
+ * `can()` stays exactly what it always was: pure, stateless, given facts and returning a
+ * verdict. Nothing here changes that. This resource is what a caller consults BEFORE calling
+ * `can()` (to build the `consumed_before` fact) and commits to AFTER `can()` returns AUTHORIZED
+ * and the caller has actually decided to act — never at `can()` time itself (repeatedly calling
+ * `can()` while deciding must never itself burn the budget).
+ *
+ * @example
+ * const state = await client.conservedState.get('supplier-budget-2026', 'supplier:acme');
+ * const verdict = await client.can({ artifact_id: 'supplier-budget-2026', consumed_before: state.consumed_before });
+ * if (verdict.allowed) {
+ *   const reservation = await client.conservedState.reserve({
+ *     artifact_id: 'supplier-budget-2026', scope: 'supplier:acme',
+ *     amount: 5000, query_id: verdict.query_id!, action: 'payments.transfer',
+ *   });
+ *   try {
+ *     // ... perform the real action ...
+ *     await client.conservedState.settle(reservation.reservation_id);
+ *   } catch {
+ *     await client.conservedState.release(reservation.reservation_id);
+ *   }
+ * }
+ */
+declare class ConservedState {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Read a ledger's current balance — no auth required, same posture as `can()`'s own keyless
+     * rail (reading how much budget remains is no more sensitive than reading a verdict).
+     */
+    get(artifactId: string, scope: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateInfo>>;
+    /**
+     * Commit capacity against a REAL, AUTHORIZED `can()` decision. Authenticated — unlike `can()`,
+     * spending against a shared budget requires an API key or session; `agent` on the returned
+     * reservation traces to that authenticated identity, never a value you pass in.
+     *
+     * Throws (via the SDK's standard NomosError hierarchy; `err.details?.code` carries the
+     * server's own code): `DECISION_NOT_FOUND` (the query_id names no real query), `DECISION_NOT
+     * _AUTHORIZED` (that decision didn't verdict AUTHORIZED for this artifact), `DECISION_ALREADY
+     * _USED` (already bound to a reservation — one decision authorizes one, ever), `STATE_CONFLICT`
+     * (a stale `expected_state_digest`), `INSUFFICIENT_CAPACITY` (`err.details.requested`/
+     * `.available` carry the numbers), or `NO_LEDGER` (nobody has declared this budget yet).
+     *
+     * Passing `{ artifact_id, scope, act }` instead authorizes the hold with a NOMOS-SPEC-008 Act.
+     * Extra codes: `ACT_NOT_ACCEPTED` (the ledger has no Act binding) and `ACT_REJECTED`, with the
+     * verifier's full answer in `err.details.result` — for `INCOMPLETE` it names the open rules and
+     * the facts whose testimony would decide them.
+     */
+    reserve(params: ReserveParams, opts?: RequestOptions): Promise<WithLastResponse<Reservation>>;
+    /**
+     * The reserved action succeeded — moves the hold into real, settled spend. Idempotent when
+     * you pass the same `reference` again for a retry (e.g. after a network timeout): you get the
+     * ORIGINAL receipt back, never a double-charge.
+     */
+    settle(reservationId: string, reference?: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateReceipt>>;
+    /**
+     * The reserved action failed, or you decided not to act — gives the hold's capacity back
+     * without ever touching what's actually been spent.
+     */
+    release(reservationId: string, reference?: string, opts?: RequestOptions): Promise<WithLastResponse<ConservedStateReceipt>>;
+}
+
 type NomosErrorCode = 'authentication_error' | 'authorization_error' | 'rate_limit_error' | 'validation_error' | 'not_found' | 'api_error' | 'network_error' | 'webhook_signature_error' | 'payment_required' | 'issuer_not_trusted';
 declare class NomosError extends Error {
     readonly code: NomosErrorCode;
     readonly status?: number;
     readonly requestId?: string;
-    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string);
+    /** The full parsed JSON response body, when the server sent one — every field it put there
+     *  (its own `code`, and anything endpoint-specific like `requested`/`available` on a
+     *  conserved-state capacity rejection, or `price_usd`/`purchase_url` before those got a
+     *  dedicated error class). `NomosError`'s own `code` above is the SDK's fixed HTTP-status
+     *  taxonomy; `details?.code` is the SERVER's own, finer-grained application code — the two
+     *  are deliberately not conflated into one field. */
+    readonly details?: unknown;
+    constructor(message: string, code: NomosErrorCode, status?: number, requestId?: string, details?: unknown);
 }
 declare class NomosAuthenticationError extends NomosError {
-    constructor(message?: string, requestId?: string);
+    constructor(message?: string, requestId?: string, details?: unknown);
 }
 declare class NomosAuthorizationError extends NomosError {
-    constructor(message?: string, requestId?: string);
+    constructor(message?: string, requestId?: string, details?: unknown);
 }
 declare class NomosRateLimitError extends NomosError {
     readonly retryAfter?: number;
-    constructor(message?: string, retryAfter?: number, requestId?: string);
+    constructor(message?: string, retryAfter?: number, requestId?: string, details?: unknown);
 }
+/** `details` is the parsed response body — kept as its own constructor param (rather than just
+ *  relying on the base class field) since it long predates NomosError.details and every caller
+ *  already passes it positionally in this slot; unchanged for backward compatibility. */
 declare class NomosValidationError extends NomosError {
-    readonly details?: unknown;
     constructor(message: string, details?: unknown, requestId?: string);
 }
 declare class NomosNotFoundError extends NomosError {
-    constructor(message: string, requestId?: string);
+    constructor(message: string, requestId?: string, details?: unknown);
 }
 declare class NomosAPIError extends NomosError {
-    constructor(message: string, status: number, requestId?: string);
+    constructor(message: string, status: number, requestId?: string, details?: unknown);
 }
 declare class NomosNetworkError extends NomosError {
     constructor(message: string);
@@ -551,14 +704,22 @@ declare class NomosPaymentRequiredError extends NomosError {
     readonly purchaseUrl: string;
     constructor(message: string, priceUsd: number, purchaseUrl: string, requestId?: string);
 }
-/** can()'s chain-of-trust rail couldn't establish that the presented artifact is trustworthy —
- *  an unrecognized issuer, a revoked key, a tampered seal, or a malformed presentation. This is
- *  deliberately NOT a DENIED verdict: "the rules say no" and "we never got far enough to ask the
- *  rules anything" are different claims, and collapsing them would tell the caller the wrong
- *  thing to do next (re-presenting a better chain can fix the first case; it can never fix a
- *  genuinely tampered artifact). `reason` is the underlying chain decision
- *  (ISSUER_NOT_RECOGNIZED / KEY_REVOKED / SEAL_INVALID / MALFORMED) for callers that need to
- *  distinguish them. */
+/** can()'s chain-of-trust rail could not establish that the presented artifact carries authority
+ *  it is entitled to — an unrecognized issuer, a revoked key, a delegation that never covered
+ *  this artifact, a tampered seal, or a malformed presentation. This is deliberately NOT a DENIED
+ *  verdict: "the rules say no" and "we never got far enough to ask the rules anything" are
+ *  different claims, and collapsing them would tell the caller the wrong thing to do next.
+ *
+ *  `reason` carries the underlying chain decision so callers can distinguish them, because the
+ *  right next action genuinely differs:
+ *    ISSUER_NOT_RECOGNIZED — presenting a more complete chain may fix this
+ *    KEY_REVOKED           — that key is dead; a different, unrevoked chain might work
+ *    CERTIFICATE_REVOKED   — one delegation was withdrawn; another certificate for the same
+ *                            key may still resolve
+ *    OUT_OF_SCOPE          — the issuer IS recognized but was not delegated authority over this
+ *                            artifact; only a broader (validly issued) delegation fixes it
+ *    SEAL_INVALID          — the artifact itself was altered; nothing about presentation helps
+ *    MALFORMED             — the request shape was wrong (a client-side bug) */
 declare class NomosIssuerNotTrustedError extends NomosError {
     readonly reason: string;
     constructor(message: string, reason: string, requestId?: string);
@@ -596,6 +757,9 @@ declare class Nomos {
     readonly artifacts: Artifacts;
     readonly governance: Governance;
     readonly webhooks: Webhooks;
+    /** The R-12 conserved-state (depleting-budget) state layer — PROTOTYPE, not a numbered spec.
+     *  See resources/conserved-state.ts for the full reserve/settle/release lifecycle. */
+    readonly conservedState: ConservedState;
     /** Whether this instance is using a live or test API key. */
     readonly mode: 'live' | 'test';
     static readonly errors: typeof errors;
@@ -645,4 +809,4 @@ declare const nomos: {
  */
 declare function verifyChain(params: VerifyChainParams, opts?: VerifyChainOptions): Promise<VerifyChainResult>;
 
-export { type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type CanOptions, type CanParams, type CanResult, type CanVerdict, type ChainVerdictDecision, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type KeyCertificate, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos, verifyChain };
+export { type Artifact, type ArtifactList, type ArtifactSchema, type ArtifactSchemaField, type AttestationInfo, type CanOptions, type CanParams, type CanResult, type CanVerdict, type ChainVerdictDecision, type ConservedStateInfo, type ConservedStateReceipt, type Contradiction, type DetectContradictionsParams, type DetectContradictionsResult, type GenerateGovernanceParams, type GenerateGovernanceResult, type KeyCertificate, type ListArtifactsParams, Nomos, NomosAPIError, NomosAuthenticationError, NomosAuthorizationError, type NomosConfig, NomosError, type NomosErrorCode, NomosIssuerNotTrustedError, NomosNetworkError, NomosNotFoundError, NomosPaymentRequiredError, NomosRateLimitError, type NomosRawResponse, NomosValidationError, type NomosWebhookEvent, type NomosWebhookEventType, NomosWebhookSignatureError, type RequestOptions, type Reservation, type ReserveByActParams, type ReserveByQueryParams, type ReserveParams, type Verdict, type VerifyChainOptions, type VerifyChainParams, type VerifyChainResult, type VerifyDecisionParams, type VerifyDecisionResult, type WithLastResponse, can, nomos, verifyChain };