@nomosprotocol/sdk 1.3.4 → 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`. */
@@ -151,6 +154,65 @@ interface CanResult {
      *  (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';
+}
+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;
@@ -525,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);
@@ -620,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;
@@ -669,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`. */
@@ -151,6 +154,65 @@ interface CanResult {
      *  (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';
+}
+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;
@@ -525,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);
@@ -620,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;
@@ -669,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.js

@@ -20,49 +20,49 @@ __export(errors_exports, {
   NomosWebhookSignatureError: () => NomosWebhookSignatureError
 });
 var NomosError = class extends Error {
-  constructor(message, code, status, requestId) {
+  constructor(message, code, status, requestId, details) {
     super(message);
     this.name = "NomosError";
     this.code = code;
     this.status = status;
     this.requestId = requestId;
+    this.details = details;
   }
 };
 var NomosAuthenticationError = class extends NomosError {
-  constructor(message = "Invalid API key", requestId) {
-    super(message, "authentication_error", 401, requestId);
+  constructor(message = "Invalid API key", requestId, details) {
+    super(message, "authentication_error", 401, requestId, details);
     this.name = "NomosAuthenticationError";
   }
 };
 var NomosAuthorizationError = class extends NomosError {
-  constructor(message = "Access denied", requestId) {
-    super(message, "authorization_error", 403, requestId);
+  constructor(message = "Access denied", requestId, details) {
+    super(message, "authorization_error", 403, requestId, details);
     this.name = "NomosAuthorizationError";
   }
 };
 var NomosRateLimitError = class extends NomosError {
-  constructor(message = "Rate limit exceeded", retryAfter, requestId) {
-    super(message, "rate_limit_error", 429, requestId);
+  constructor(message = "Rate limit exceeded", retryAfter, requestId, details) {
+    super(message, "rate_limit_error", 429, requestId, details);
     this.name = "NomosRateLimitError";
     this.retryAfter = retryAfter;
   }
 };
 var NomosValidationError = class extends NomosError {
   constructor(message, details, requestId) {
-    super(message, "validation_error", 400, requestId);
+    super(message, "validation_error", 400, requestId, details);
     this.name = "NomosValidationError";
-    this.details = details;
   }
 };
 var NomosNotFoundError = class extends NomosError {
-  constructor(message, requestId) {
-    super(message, "not_found", 404, requestId);
+  constructor(message, requestId, details) {
+    super(message, "not_found", 404, requestId, details);
     this.name = "NomosNotFoundError";
   }
 };
 var NomosAPIError = class extends NomosError {
-  constructor(message, status, requestId) {
-    super(message, "api_error", status, requestId);
+  constructor(message, status, requestId, details) {
+    super(message, "api_error", status, requestId, details);
     this.name = "NomosAPIError";
   }
 };
@@ -179,22 +179,27 @@ var HttpClient = class {
     const message = errBody?.error ?? errBody?.message ?? res.statusText;
     switch (res.status) {
       case 401:
-        throw new NomosAuthenticationError(message, requestId);
+        throw new NomosAuthenticationError(message, requestId, errBody);
       case 403:
-        throw new NomosAuthorizationError(message, requestId);
+        throw new NomosAuthorizationError(message, requestId, errBody);
       case 404:
-        throw new NomosNotFoundError(message, requestId);
+        throw new NomosNotFoundError(message, requestId, errBody);
       case 422:
       case 400:
-        throw new NomosValidationError(message, errBody?.details, requestId);
+        throw new NomosValidationError(message, errBody?.details ?? errBody, requestId);
       case 429:
         throw new NomosRateLimitError(
           message,
           res.headers.get("retry-after") ? parseInt(res.headers.get("retry-after"), 10) : void 0,
-          requestId
+          requestId,
+          errBody
         );
+      // No case for 409 (conflict) specifically — several endpoints use it for distinct
+      // application-level rejections (e.g. conserved-state capacity/conflict/already-used);
+      // `errBody` (this default branch's `details`) is what lets a caller tell those apart via
+      // `err.details?.code`, not a status-code switch that would have to keep growing per feature.
       default:
-        throw new NomosAPIError(message, res.status, requestId);
+        throw new NomosAPIError(message, res.status, requestId, errBody);
     }
   }
 };
@@ -512,6 +517,71 @@ var Webhooks = class {
   }
 };
 
+// src/resources/conserved-state.ts
+var ConservedState = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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).
+   */
+  async get(artifactId, scope, opts) {
+    const qs = new URLSearchParams({ artifact_id: artifactId, scope });
+    const { data, lastResponse } = await this.http.get(
+      `/api/v1/conserved-state?${qs.toString()}`,
+      opts
+    );
+    return { ...data, lastResponse };
+  }
+  /**
+   * 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.
+   */
+  async reserve(params, opts) {
+    const { data, lastResponse } = await this.http.post("/api/v1/reserve", params, opts);
+    return { ...data, lastResponse };
+  }
+  /**
+   * 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.
+   */
+  async settle(reservationId, reference, opts) {
+    const { data, lastResponse } = await this.http.post(
+      "/api/v1/settle",
+      { reservation_id: reservationId, reference },
+      opts
+    );
+    return { ...data, lastResponse };
+  }
+  /**
+   * The reserved action failed, or you decided not to act — gives the hold's capacity back
+   * without ever touching what's actually been spent.
+   */
+  async release(reservationId, reference, opts) {
+    const { data, lastResponse } = await this.http.post(
+      "/api/v1/release",
+      { reservation_id: reservationId, reference },
+      opts
+    );
+    return { ...data, lastResponse };
+  }
+};
+
 // src/can.ts
 var CHAIN_PROTOCOL_VERSION = "1";
 var DEFAULT_EXCHANGE_BASE = "https://www.nomosprotocol.com";
@@ -726,6 +796,7 @@ var Nomos = class {
     this.artifacts = new Artifacts(this.http);
     this.governance = new Governance(this.http);
     this.webhooks = new Webhooks();
+    this.conservedState = new ConservedState(this.http);
   }
   /**
    * "Can I do this?" — the one verb, now covering your own artifacts too. Pass `authority` for a