@secondlayer/shared 6.41.1 → 6.41.2

package/dist/src/db/index.d.ts

@@ -752,6 +752,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/chain-reorgs.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/contracts.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/integrity.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/subgraph-gaps.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/subgraph-operations.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/subgraphs.d.ts

@@ -735,6 +735,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/queries/subscriptions.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/db/schema.d.ts

@@ -733,6 +733,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/index.d.ts

@@ -733,6 +733,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/dist/src/node/local-client.d.ts

@@ -734,6 +734,11 @@ interface X402PaymentsTable {
 	/** USD-micros to credit on confirmation, for deposit rows the reconciler
 	*  settles asynchronously. NULL for per-call settles (credit nothing). */
 	credit_usd_micros: string | null;
+	/** Idempotency key: stamped exactly once when this row's credit is applied.
+	*  NULL means never credited (or not a credit-bearing row). Pre-migration
+	*  non-pending deposit rows are backfilled to a non-null sentinel so the
+	*  reconciler's heal path can never double-credit them. */
+	credited_at: Generated<Date> | null;
 }
 type TenantStatus = "provisioning" | "active" | "limit_warning" | "paused_limit" | "suspended" | "error" | "deleted";
 interface TenantsTable {

package/migrations/0108_x402_payments_credited_at.ts

@@ -0,0 +1,41 @@
+import { type Kysely, sql } from "kysely";
+import { onControlPlane } from "../src/db/migration-role.ts";
+
+// `credited_at` is the idempotency key for deposit crediting: stamped exactly
+// once, whenever a deposit's balance credit is applied. Only a row where it's
+// NULL is eligible for the reconciler's heal path (f069).
+//
+// THE TRAP: right after ADD COLUMN, every existing row (including historical
+// `confirmed` deposits the old route-handler path already credited) has
+// credited_at = NULL. If the reconciler treated NULL as "never credited" for
+// those rows, it would DOUBLE-CREDIT every already-credited historical
+// deposit. So we backfill all pre-existing non-pending deposit rows to a
+// non-null sentinel (`updated_at`) — their true credit state is unknowable
+// from ledger data alone, so healing must never touch them. `pending` rows
+// stay NULL (not yet credited, still eligible once they confirm) and
+// non-deposit rows stay NULL (they never carry a credit). Only rows created
+// AFTER this migration are ever heal-eligible. Back-crediting truly-stranded
+// historical rows is a separate founder payout decision, OUT OF SCOPE here.
+export async function up(db: Kysely<unknown>): Promise<void> {
+	await sql`SET lock_timeout = '30s'`.execute(db);
+	await onControlPlane(async () => {
+		await sql`
+			ALTER TABLE x402_payments
+				ADD COLUMN IF NOT EXISTS credited_at TIMESTAMPTZ
+		`.execute(db);
+		await sql`
+			UPDATE x402_payments
+				SET credited_at = updated_at
+				WHERE kind = 'deposit' AND state <> 'pending' AND credited_at IS NULL
+		`.execute(db);
+	});
+}
+
+export async function down(db: Kysely<unknown>): Promise<void> {
+	await onControlPlane(async () => {
+		await sql`
+			ALTER TABLE x402_payments
+				DROP COLUMN IF EXISTS credited_at
+		`.execute(db);
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/shared",
-	"version": "6.41.1",
+	"version": "6.41.2",
 	"license": "MIT",
 	"repository": {
 		"type": "git",