@dvmkit/sdk 0.1.0-rc.1 → 0.1.0-rc.2

package/dist/{job-store-C5n6bhap.d.ts → job-store-6gR4pZRP.d.ts}

@@ -739,7 +739,12 @@ type NonChannelBitcoinRail = (typeof NON_CHANNEL_BITCOIN_RAILS)[number];
  * bought, with however much of that micro is still unspent.
  *
  * `remainingMicro` is depleted FIFO by settled draws and by reclaims, so the
- * sum of a credit's lots tracks `credits.balance_micro` exactly.
+ * sum of a credit's lots tracks `credits.balance_micro` exactly — with one
+ * deliberate exception: an expiry release (internal-review) zeroes the balance and
+ * leaves the lots standing, because a revival restores that balance and its
+ * in-kind basis has to still be there. A released credit is excluded from the
+ * sweep floor by `BITCOIN_CREDIT_PREDICATE`'s own `balance_micro > 0`, so the
+ * over-coverage is never counted as sats the builder owes back.
  */
 interface FundingLot {
     lotId: string;
@@ -855,6 +860,14 @@ interface CreditDepositPayload {
         /** 32-byte channel id, `0x`-prefixed and lowercased. */
         channelId: string;
     };
+    /**
+     * Set by the blocked-invoice repair (internal-review): this deposit is a paid
+     * Lightning invoice the builder's agent reconciled onto a credit. The money
+     * landed in the receive wallet at payment time and this deposit is the one
+     * row it gets, so the settlements table types it `repair` off this flag
+     * rather than off a second row.
+     */
+    repaired?: boolean;
 }
 /**
  * JSON wire shape POSTed to the platform's `/_internal/credit-draw-release`
@@ -944,6 +957,64 @@ type CreditDrawReleaseEnqueue = (tx: RevenueReporterQuerier, payload: CreditDraw
  * it before committing the status CAS that moved the money.
  */
 type CreditDrainEnqueue = (tx: RevenueReporterQuerier, payload: CreditDrainPayload) => Promise<void>;
+/**
+ * JSON wire shape POSTed to the platform's `/_internal/credit-expiry-release`
+ * endpoint (internal-review). A prepaid credit that reaches its TTL with an undrawn
+ * remainder RELEASES that remainder to the builder: on cashu, Lightning and
+ * x402 the funding value reached builder custody at funding time or on the
+ * settlement cycle, so expiry extinguishes the caller's remaining claim.
+ * Reported so committed value nets to
+ * `deposited − drawn − drained − released`; without it an expired credit is
+ * owed forever on paper, exactly like an unreported drain.
+ *
+ * Never sent for a Tempo credit. Tempo balances are channel-backed and undrawn
+ * channel value returns to the *caller* at exit, so no release exists on that
+ * rail — the sweep skips them and the platform refuses one outright.
+ *
+ * Two reports share this shape, distinguished only by `reversedAt`:
+ *
+ * - **The release**, written by the expiry sweep with `reversedAt` absent.
+ * - **The reversal**, written when a later funding revives the credit
+ *   (`CreditLedger.fund` overwrites `expiry_ms`, so the recorded remainder is
+ *   no longer final). It repeats the whole payload rather than sending a
+ *   reference, because the retry loop can deliver the two out of order and the
+ *   platform's upsert must be able to land either one first.
+ *
+ * Idempotent on `(dvmId, creditId, releaseId)`, so the shared retry loop can
+ * redeliver freely.
+ */
+interface CreditExpiryReleasePayload {
+    /** Required. Platform DVM record ID (`dvms.id`); must match the bearer token's DVM. */
+    dvmId: string;
+    /** Required. Credit whose remainder expired. */
+    creditId: string;
+    /** Required. Per-expiry-episode key; the platform idempotency key with DVM and credit. */
+    releaseId: string;
+    /** Required. Caller whose claim on the remainder ended. */
+    callerPubkey: string;
+    /** Funding rail. `null` on a credit funded before the basis became mandatory. */
+    rail: string | null;
+    /** Required. Fiat micro released — the liability this expiry extinguishes. */
+    amountMicro: number;
+    /** Required. Currency `amountMicro` is 1e-6 of. */
+    creditCurrency: string;
+    /** Required. When the credit's TTL ran out (epoch ms) — when the liability ended. */
+    expiryMs: number;
+    /** Required. When the sweep observed the expiry (epoch ms). */
+    releasedAt: number;
+    /** Set only on the reversal report: when the revival funding landed (epoch ms). */
+    reversedAt?: number | null;
+}
+/**
+ * Transactional expiry-release outbox seam, threaded through the sweep's insert
+ * and through the funding that reverses a release (internal-review).
+ *
+ * Implemented by {@link RevenueReporter.enqueueCreditExpiryRelease}; callers
+ * must await it before committing the write that made the release (or its
+ * reversal) true, for the same reason the drain seam does — a report lost
+ * between the two overstates or understates committed value forever.
+ */
+type CreditExpiryReleaseEnqueue = (tx: RevenueReporterQuerier, payload: CreditExpiryReleasePayload) => Promise<void>;
 /** Distinct causes for a settled credit draw that could not book revenue. */
 type RevenueSkippedNoRailReason = "credit_rail_null" | "credit_rail_unrecognized" | "job_rail_missing" | "ledger_not_configured";
 /**
@@ -1451,6 +1522,7 @@ declare class CreditLedger {
      */
     readonly durable = true;
     private x402Settlements?;
+    private expiryReleaseOutbox?;
     constructor(pool: CreditLedgerPool, tempoSessionStore?: TempoSessionSettlementStore | undefined);
     /**
      * Bind the durable x402 settlement state this ledger gates spending on
@@ -1462,6 +1534,22 @@ declare class CreditLedger {
      * channel storage, where no settlement row can exist to wedge.
      */
     useX402SettlementGate(gate: X402RefundSettlementGate): void;
+    /**
+     * Bind the durable outbox that reports credit-expiry releases and their
+     * revivals to the platform (internal-review).
+     *
+     * Held on the ledger rather than threaded through {@link fund} for the same
+     * reason as the gate above: the revival half fires from *every* funding path
+     * — Cashu commit, x402 exact and channel, Tempo, the Lightning invoice
+     * settle, the implicit N=1 per-call payment — and a seam each of those has to
+     * remember to pass is a seam one of them will eventually forget.
+     *
+     * Unbound (a `dvmctl dev` server, a self-hosted builder, a test host) the
+     * sweep and the reversal still run and still write the ledger's own rows;
+     * only the platform report is skipped. Reporting is bookkeeping and must
+     * never gate the ledger.
+     */
+    useCreditExpiryReleaseOutbox(outbox: CreditExpiryReleaseOutbox): void;
     /** Create the `credits` / `credit_draws` tables if absent. Call once at SDK boot. */
     init(): Promise<void>;
     /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
@@ -1499,9 +1587,15 @@ declare class CreditLedger {
      *
      * Pass `tx` (a client inside a caller-owned `BEGIN`) to commit the rail
      * receive and the ledger credit atomically (spec condition 3 — the internal-review
-     * verifier does this). The ledger issues **no** transaction control on `tx`;
-     * the upsert is a single statement, so without `tx` it is equally atomic on
-     * the pool.
+     * verifier does this). The ledger issues **no** transaction control on `tx`.
+     *
+     * Without `tx` it opens one of its own, because a funding is no longer a
+     * single statement: it upserts the credit, records its funding lot
+     * (internal-review), and reverses any standing expiry release (internal-review) — and that
+     * last leg restores balance and queues a report. A crash between the upsert
+     * and the reversal would leave a revived credit whose release still stands,
+     * which the sweep's own exclusion then makes permanent: `balance_micro > 0`
+     * but a standing release means it is neither drainable nor re-releasable.
      *
      * `basis` records the rail value behind the fiat (internal-review) so each draw can
      * be allocated its share of the rail-native amount actually received. A
@@ -1538,21 +1632,110 @@ declare class CreditLedger {
      * below. This method is the authority on that rule, as it is on the binding
      * rules above; every door preflights it where a refusal is still free.
      */
-    fund(args: {
-        /** Omit to mint a fresh credit id; provide to top up (or idempotently create). */
-        creditId?: string;
-        callerPubkey: string;
-        /** The DVM's pricing currency; `amountMicro` is 1e-6 of it. */
-        currency: string;
-        amountMicro: number;
-        /** Absolute expiry, ms since epoch. Overwrites the previous value on top-up. */
-        expiryMs: number;
-        /** Rail-value basis this funding contributes (internal-review, required by internal-review). */
-        basis: CreditFundingBasis;
-        /** External transaction handle — caller owns BEGIN/COMMIT (spec condition 3). */
-        tx?: CreditLedgerQuerier;
+    fund(args: CreditFundArgs): Promise<CreditSnapshot>;
+    /**
+     * The funding itself, on whichever handle {@link fund} chose. Every refusal
+     * it raises is the caller's to see unchanged; a self-opened transaction rolls
+     * back around it.
+     */
+    private fundOn;
+    /**
+     * Undo any expiry release this credit still carries, because a funding just
+     * landed on it (internal-review — the revival rule), restoring the balance the
+     * release took.
+     *
+     * A release records the credit's **final** undrawn remainder and zeroes it
+     * (see {@link releaseExpiredCreditLocked}). Funding adds to the balance and
+     * overwrites `expiry_ms` (spec §5 carry-forward: the credit is a rolling
+     * buffer), so the moment money arrives the recorded remainder is no longer
+     * final: the release stops counting and its micro come back.
+     *
+     * Deliberately unconditional on the incoming expiry rather than gated on
+     * `expiryMs > nowMs`. A release exists only for a credit that had already
+     * lapsed, so any funding that reaches one is money the release did not
+     * account for — and a funding that arrives with an already-past expiry leaves
+     * a credit the very next sweep re-releases at its new, larger remainder. One
+     * rule, self-healing in both directions, and it never needs to read the
+     * pre-funding expiry the upsert has already overwritten.
+     *
+     * Runs on the funding's own handle — which {@link fund} now guarantees is a
+     * transaction — so the reversal, the restored balance and the report commit
+     * with the money or not at all. A reversal that committed without its report
+     * would be unrecoverable: `WHERE reversed_at IS NULL` means no later pass
+     * re-derives it.
+     *
+     * @returns the credit row as the restore left it, or undefined when there was
+     *   nothing to reverse. The caller reads its snapshot off this rather than off
+     *   the funding upsert's `RETURNING`, which predates the restore.
+     */
+    private reverseExpiryReleases;
+    /**
+     * Release the undrawn remainder of every credit whose TTL has run out
+     * (internal-review). Returns the releases this pass recorded.
+     *
+     * **What is released.** The credit's whole `balance_micro`. Expiry ends
+     * spending but never ownership of the record, so the balance stays readable;
+     * what ends is the caller's claim on it, and on the prepaid rails the value
+     * behind it is already in builder custody.
+     *
+     * **Tempo is excluded**, at both of its markers (`tempo_channel_id` and a
+     * `tempo` rail). A Tempo credit is channel-backed and its undrawn value
+     * returns to the *caller* at channel exit, so releasing it would book the
+     * builder money the chain is about to hand back.
+     *
+     * **A credit with a pending hold is skipped, not partially released.** A draw
+     * placed before expiry stays settleable afterwards (`draw`'s replay lookup
+     * runs above the expiry check, so a lost response is still recoverable), so
+     * the remainder is not final while a hold is outstanding. Skipping costs one
+     * sweep interval and keeps the released figure exactly "what nothing bought";
+     * holds do resolve — the orphan-draw watchdog (internal-review) is what guarantees
+     * a stranded one still reaches a terminal state.
+     *
+     * **Idempotent** two ways. `release_id` is derived from the expiry instant,
+     * so a re-sweep after a crash between the insert and its report collides on
+     * the same primary key instead of writing a second row; and the candidate
+     * scan excludes any credit that already has an un-reversed release.
+     *
+     * Each candidate is re-checked under the credit row lock every
+     * `credit_draws` write is taken under, so a draw racing the sweep either
+     * loses the race (its credit is already released and it would have been
+     * refused `credit_expired` anyway) or wins it and leaves a pending hold the
+     * locked re-check sees.
+     */
+    sweepExpiredCredits(args?: {
         nowMs?: number;
-    }): Promise<CreditSnapshot>;
+        /** Credits released per pass. Bounds the work a long-idle DVM does at boot. */
+        limit?: number;
+    }): Promise<{
+        released: CreditExpiryRelease[];
+    }>;
+    /**
+     * Write one credit's expiry release under its row lock, zero the balance it
+     * released, and re-assert every condition the unlocked candidate scan tested.
+     * Returns undefined when the credit no longer qualifies — funded, drawn
+     * against, or already released between the scan and the lock.
+     *
+     * **Zeroing the balance is what makes the release real**, and it is the whole
+     * reason this runs under the lock rather than as a bare INSERT. The row alone
+     * records that the caller's claim ended; it does not *end* it. `requestDrain`
+     * has no expiry check by design (expiry gates new draws, not reclaims), so a
+     * credit whose remainder had been released and reported was still fully
+     * drainable: the DVM would pay out money the platform had already booked as
+     * the builder's, and `deposited - drawn - drained - released` would go
+     * negative on the same micro. With the balance at zero, `requestDrain`'s
+     * existing `availableMicro <= 0` guard refuses with `nothing_to_drain` and no
+     * new check is needed anywhere. {@link reverseExpiryReleases} puts the
+     * balance back when a funding revives the credit.
+     *
+     * `status` deliberately stays `active`: a released credit must remain
+     * fundable, or the revival rule has nothing to revive.
+     *
+     * The zeroed balance also takes the credit out of `BITCOIN_CREDIT_PREDICATE`
+     * (`balance_micro > 0`), so the in-kind sweep floor stops counting sats the
+     * builder no longer owes back — and counts them again after a revival, with
+     * the credit's funding lots untouched throughout.
+     */
+    private releaseExpiredCreditLocked;
     /**
      * Record this funding's in-kind basis as a lot (internal-review).
      *
@@ -2054,7 +2237,15 @@ declare class CreditLedger {
     listTempoCreditLosses(args?: {
         limit?: number;
     }): Promise<TempoCreditLoss[]>;
-    /** Retire the active credit bound to a chain-proven empty x402 channel. */
+    /**
+     * Reconcile the credit bound to a chain-proven empty x402 channel.
+     *
+     * A channel with no unclaimed backing makes every remaining customer
+     * liability unsafe, so those credits become terminal. A fully settled credit
+     * has neither a balance nor an unfinished drain and is safe to retain for a
+     * later deposit. This also repairs a zero-liability row an older build
+     * terminalized from the same observation.
+     */
     terminalizeX402Credit(evidence: X402CreditLossEvidence, tx?: CreditLedgerQuerier): Promise<X402CreditLoss[]>;
     private terminalizeX402CreditLocked;
     /** List terminal x402 credit losses, newest observation first. */
@@ -2386,6 +2577,27 @@ interface CreditLedgerLike {
      * {@link CreditLedger.useX402SettlementGate}.
      */
     useX402SettlementGate?(gate: X402RefundSettlementGate): void;
+    /**
+     * Bind the outbox that reports credit-expiry releases and their revivals
+     * (internal-review).
+     *
+     * Optional, and absent on `MemoryCreditLedger`: an expiry release is a
+     * durable liability fact, and a ledger whose balances do not survive a
+     * restart has none to report. A host on a non-durable ledger simply never
+     * sweeps. See {@link CreditLedger.useCreditExpiryReleaseOutbox}.
+     */
+    useCreditExpiryReleaseOutbox?(outbox: CreditExpiryReleaseOutbox): void;
+    /**
+     * Release the undrawn remainder of every credit past its TTL (internal-review).
+     * Optional on the same terms as the binder above. See
+     * {@link CreditLedger.sweepExpiredCredits}.
+     */
+    sweepExpiredCredits?(args?: {
+        nowMs?: number;
+        limit?: number;
+    }): Promise<{
+        released: CreditExpiryRelease[];
+    }>;
     /**
      * Ask that gate directly, so a route can refuse a wedged channel **before**
      * the rail moves anything (internal-review). Optional on the same terms as the
@@ -2641,6 +2853,38 @@ interface CreditDrawReleaseOutbox {
     /** Reporter-owned insert executed through the ledger transaction. */
     enqueue: CreditDrawReleaseEnqueue;
 }
+/** Reporter seam for credit-expiry releases and the revivals that reverse them (internal-review). */
+interface CreditExpiryReleaseOutbox {
+    /** Platform DVM record ID bound into the report. */
+    dvmId: string;
+    /** Reporter-owned insert executed through the ledger transaction. */
+    enqueue: CreditExpiryReleaseEnqueue;
+}
+/**
+ * One recorded expiry episode: a credit's undrawn remainder passing to the
+ * builder when its TTL ran out (internal-review).
+ *
+ * `reversedAt` is set when a later funding revived the credit, at which point
+ * the release stops counting against committed value — the row stays as the
+ * record that it once did.
+ */
+interface CreditExpiryRelease {
+    creditId: string;
+    /** Per-expiry-episode key, derived from {@link CreditExpiryRelease.expiryMs}. */
+    releaseId: string;
+    callerPubkey: string;
+    currency: string;
+    /** Funding rail, or `null` on a credit funded before the basis was mandatory. */
+    rail: string | null;
+    /** Fiat micro released, 1e-6 of `currency`. */
+    amountMicro: number;
+    /** When the credit's TTL ran out — when the liability ended. */
+    expiryMs: number;
+    /** When the sweep observed the expiry. */
+    releasedAt: number;
+    /** When a funding revived the credit and undid this release. */
+    reversedAt: number | null;
+}
 /** Pool-shaped handle (`query` + `connect`). Required for the locked write paths. */
 type CreditLedgerPool = Pick<Pool, "query" | "connect">;
 /**
@@ -3059,6 +3303,22 @@ interface CreditFundingBasis {
         maxClaimableAmount: string;
     };
 }
+/** What {@link CreditLedger.fund} takes. Named so the private body can share the shape. */
+interface CreditFundArgs {
+    /** Omit to mint a fresh credit id; provide to top up (or idempotently create). */
+    creditId?: string;
+    callerPubkey: string;
+    /** The DVM's pricing currency; `amountMicro` is 1e-6 of it. */
+    currency: string;
+    amountMicro: number;
+    /** Absolute expiry, ms since epoch. Overwrites the previous value on top-up. */
+    expiryMs: number;
+    /** Rail-value basis this funding contributes (internal-review, required by internal-review). */
+    basis: CreditFundingBasis;
+    /** External transaction handle — caller owns BEGIN/COMMIT (spec condition 3). */
+    tx?: CreditLedgerQuerier;
+    nowMs?: number;
+}
 /**
  * Allocate a draw's share of a credit's unspent rail value (internal-review). Pure —
  * shared by the Postgres and in-memory ledgers so the two can't drift.

package/dist/{memory-credit-ledger-7TTZDSRS.js → memory-credit-ledger-I2G64DDK.js}

@@ -1,7 +1,7 @@
 import {
   MemoryCreditLedger
-} from "./chunk-NTK5DJ6R.js";
-import "./chunk-RPXHKMYE.js";
+} from "./chunk-OJ5WFIB2.js";
+import "./chunk-365P52XQ.js";
 import "./chunk-H25M54MI.js";
 import "./chunk-S3XAHZQY.js";
 export {