[codex] Structure persistence error correlation

apps/server/src/persistence/AuthPairingLinks.ts

@@ -11,6 +11,7 @@ import { AuthEnvironmentScopes } from "@t3tools/contracts";
 import {
   type AuthPairingLinkRepositoryError,
   PersistenceDecodeError,
+  type PersistenceErrorCorrelation,
   PersistenceSqlError,
 } from "./Errors.ts";
 
@@ -66,6 +67,22 @@ export const GetAuthPairingLinkByCredentialInput = Schema.Struct({
 });
 export type GetAuthPairingLinkByCredentialInput = typeof GetAuthPairingLinkByCredentialInput.Type;
 
+const AuthPairingLinkRawDbRow = Schema.Struct({
+  id: Schema.String,
+  credential: Schema.Unknown,
+  method: Schema.Unknown,
+  scopes: Schema.Unknown,
+  subject: Schema.Unknown,
+  label: Schema.Unknown,
+  proofKeyThumbprint: Schema.Unknown,
+  createdAt: Schema.Unknown,
+  expiresAt: Schema.Unknown,
+  consumedAt: Schema.Unknown,
+  revokedAt: Schema.Unknown,
+});
+
+const decodeAuthPairingLinkDbRow = Schema.decodeUnknownEffect(AuthPairingLinkRecord);
+
 export class AuthPairingLinkRepository extends Context.Service<
   AuthPairingLinkRepository,
   {
@@ -87,11 +104,19 @@ export class AuthPairingLinkRepository extends Context.Service<
   }
 >()("t3/persistence/AuthPairingLinks/AuthPairingLinkRepository") {}
 
-function toPersistenceSqlOrDecodeError(sqlOperation: string, decodeOperation: string) {
+function toPersistenceSqlOrDecodeError(
+  sqlOperation: string,
+  decodeOperation: string,
+  correlation?: PersistenceErrorCorrelation,
+) {
   return (cause: unknown): AuthPairingLinkRepositoryError =>
     Schema.isSchemaError(cause)
-      ? PersistenceDecodeError.fromSchemaError(decodeOperation, cause)
-      : new PersistenceSqlError({ operation: sqlOperation, cause });
+      ? PersistenceDecodeError.fromSchemaError(decodeOperation, cause, correlation)
+      : new PersistenceSqlError({
+          operation: sqlOperation,
+          ...(correlation === undefined ? {} : { correlation }),
+          cause,
+        });
 }
 
 export const make = Effect.gen(function* () {
@@ -132,7 +157,7 @@ export const make = Effect.gen(function* () {
 
   const consumeAvailablePairingLinkRow = SqlSchema.findOneOption({
     Request: ConsumeAuthPairingLinkInput,
-    Result: AuthPairingLinkRecord,
+    Result: AuthPairingLinkRawDbRow,
     execute: ({ credential, proofKeyThumbprint, consumedAt, now }) =>
       sql`
         UPDATE auth_pairing_links
@@ -162,7 +187,7 @@ export const make = Effect.gen(function* () {
 
   const listActivePairingLinkRows = SqlSchema.findAll({
     Request: ListActiveAuthPairingLinksInput,
-    Result: AuthPairingLinkRecord,
+    Result: AuthPairingLinkRawDbRow,
     execute: ({ now }) =>
       sql`
         SELECT
@@ -201,7 +226,7 @@ export const make = Effect.gen(function* () {
 
   const getPairingLinkRowByCredential = SqlSchema.findOneOption({
     Request: GetAuthPairingLinkByCredentialInput,
-    Result: AuthPairingLinkRecord,
+    Result: AuthPairingLinkRawDbRow,
     execute: ({ credential }) =>
       sql`
         SELECT
@@ -227,6 +252,7 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthPairingLinkRepository.create:query",
           "AuthPairingLinkRepository.create:encodeRequest",
+          { pairingLinkId: input.id },
         ),
       ),
     );
@@ -239,6 +265,22 @@ export const make = Effect.gen(function* () {
           "AuthPairingLinkRepository.consumeAvailable:decodeRow",
         ),
       ),
+      Effect.flatMap((rowOption) =>
+        Option.match(rowOption, {
+          onNone: () => Effect.succeed(Option.none()),
+          onSome: (row) =>
+            decodeAuthPairingLinkDbRow(row).pipe(
+              Effect.mapError((cause) =>
+                PersistenceDecodeError.fromSchemaError(
+                  "AuthPairingLinkRepository.consumeAvailable:decodeRow",
+                  cause,
+                  { pairingLinkId: row.id },
+                ),
+              ),
+              Effect.map(Option.some),
+            ),
+        }),
+      ),
     );
 
   const listActive: AuthPairingLinkRepository["Service"]["listActive"] = (input) =>
@@ -249,6 +291,19 @@ export const make = Effect.gen(function* () {
           "AuthPairingLinkRepository.listActive:decodeRows",
         ),
       ),
+      Effect.flatMap((rows) =>
+        Effect.forEach(rows, (row) =>
+          decodeAuthPairingLinkDbRow(row).pipe(
+            Effect.mapError((cause) =>
+              PersistenceDecodeError.fromSchemaError(
+                "AuthPairingLinkRepository.listActive:decodeRows",
+                cause,
+                { pairingLinkId: row.id },
+              ),
+            ),
+          ),
+        ),
+      ),
     );
 
   const revoke: AuthPairingLinkRepository["Service"]["revoke"] = (input) =>
@@ -257,6 +312,7 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthPairingLinkRepository.revoke:query",
           "AuthPairingLinkRepository.revoke:decodeRows",
+          { pairingLinkId: input.id },
         ),
       ),
       Effect.map((rows) => rows.length > 0),
@@ -270,6 +326,22 @@ export const make = Effect.gen(function* () {
           "AuthPairingLinkRepository.getByCredential:decodeRow",
         ),
       ),
+      Effect.flatMap((rowOption) =>
+        Option.match(rowOption, {
+          onNone: () => Effect.succeed(Option.none()),
+          onSome: (row) =>
+            decodeAuthPairingLinkDbRow(row).pipe(
+              Effect.mapError((cause) =>
+                PersistenceDecodeError.fromSchemaError(
+                  "AuthPairingLinkRepository.getByCredential:decodeRow",
+                  cause,
+                  { pairingLinkId: row.id },
+                ),
+              ),
+              Effect.map(Option.some),
+            ),
+        }),
+      ),
     );
 
   return {

apps/server/src/persistence/AuthSessions.ts

@@ -16,6 +16,7 @@ import {
 import {
   type AuthSessionRepositoryError,
   PersistenceDecodeError,
+  type PersistenceErrorCorrelation,
   PersistenceSqlError,
 } from "./Errors.ts";
 
@@ -122,6 +123,25 @@ const AuthSessionDbRow = Schema.Struct({
   revokedAt: Schema.NullOr(Schema.DateTimeUtcFromString),
 });
 
+const AuthSessionRawDbRow = Schema.Struct({
+  sessionId: Schema.String,
+  subject: Schema.Unknown,
+  scopes: Schema.Unknown,
+  method: Schema.Unknown,
+  clientLabel: Schema.Unknown,
+  clientIpAddress: Schema.Unknown,
+  clientUserAgent: Schema.Unknown,
+  clientDeviceType: Schema.Unknown,
+  clientOs: Schema.Unknown,
+  clientBrowser: Schema.Unknown,
+  issuedAt: Schema.Unknown,
+  expiresAt: Schema.Unknown,
+  lastConnectedAt: Schema.Unknown,
+  revokedAt: Schema.Unknown,
+});
+
+const decodeAuthSessionDbRow = Schema.decodeUnknownEffect(AuthSessionDbRow);
+
 function toAuthSessionRecord(row: typeof AuthSessionDbRow.Type): AuthSessionRecord {
   return {
     sessionId: row.sessionId,
@@ -143,11 +163,19 @@ function toAuthSessionRecord(row: typeof AuthSessionDbRow.Type): AuthSessionReco
   };
 }
 
-function toPersistenceSqlOrDecodeError(sqlOperation: string, decodeOperation: string) {
+function toPersistenceSqlOrDecodeError(
+  sqlOperation: string,
+  decodeOperation: string,
+  correlation?: PersistenceErrorCorrelation,
+) {
   return (cause: unknown): AuthSessionRepositoryError =>
     Schema.isSchemaError(cause)
-      ? PersistenceDecodeError.fromSchemaError(decodeOperation, cause)
-      : new PersistenceSqlError({ operation: sqlOperation, cause });
+      ? PersistenceDecodeError.fromSchemaError(decodeOperation, cause, correlation)
+      : new PersistenceSqlError({
+          operation: sqlOperation,
+          ...(correlation === undefined ? {} : { correlation }),
+          cause,
+        });
 }
 
 export const make = Effect.gen(function* () {
@@ -192,7 +220,7 @@ export const make = Effect.gen(function* () {
 
   const getSessionRowById = SqlSchema.findOneOption({
     Request: GetAuthSessionByIdInput,
-    Result: AuthSessionDbRow,
+    Result: AuthSessionRawDbRow,
     execute: ({ sessionId }) =>
       sql`
         SELECT
@@ -217,7 +245,7 @@ export const make = Effect.gen(function* () {
 
   const listActiveSessionRows = SqlSchema.findAll({
     Request: ListActiveAuthSessionsInput,
-    Result: AuthSessionDbRow,
+    Result: AuthSessionRawDbRow,
     execute: ({ now }) =>
       sql`
         SELECT
@@ -285,6 +313,7 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthSessionRepository.create:query",
           "AuthSessionRepository.create:encodeRequest",
+          { sessionId: input.sessionId },
         ),
       ),
     );
@@ -295,12 +324,23 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthSessionRepository.getById:query",
           "AuthSessionRepository.getById:decodeRow",
+          { sessionId: input.sessionId },
         ),
       ),
       Effect.flatMap((rowOption) =>
         Option.match(rowOption, {
           onNone: () => Effect.succeed(Option.none()),
-          onSome: (row) => Effect.succeed(Option.some(toAuthSessionRecord(row))),
+          onSome: (row) =>
+            decodeAuthSessionDbRow(row).pipe(
+              Effect.mapError((cause) =>
+                PersistenceDecodeError.fromSchemaError(
+                  "AuthSessionRepository.getById:decodeRow",
+                  cause,
+                  { sessionId: input.sessionId },
+                ),
+              ),
+              Effect.map((decodedRow) => Option.some(toAuthSessionRecord(decodedRow))),
+            ),
         }),
       ),
     );
@@ -313,7 +353,20 @@ export const make = Effect.gen(function* () {
           "AuthSessionRepository.listActive:decodeRows",
         ),
       ),
-      Effect.flatMap((rows) => Effect.succeed(rows.map((row) => toAuthSessionRecord(row)))),
+      Effect.flatMap((rows) =>
+        Effect.forEach(rows, (row) =>
+          decodeAuthSessionDbRow(row).pipe(
+            Effect.mapError((cause) =>
+              PersistenceDecodeError.fromSchemaError(
+                "AuthSessionRepository.listActive:decodeRows",
+                cause,
+                { sessionId: row.sessionId },
+              ),
+            ),
+            Effect.map(toAuthSessionRecord),
+          ),
+        ),
+      ),
     );
 
   const revoke: AuthSessionRepository["Service"]["revoke"] = (input) =>
@@ -322,6 +375,7 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthSessionRepository.revoke:query",
           "AuthSessionRepository.revoke:decodeRows",
+          { sessionId: input.sessionId },
         ),
       ),
       Effect.map((rows) => rows.length > 0),
@@ -333,6 +387,7 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthSessionRepository.revokeAllExcept:query",
           "AuthSessionRepository.revokeAllExcept:decodeRows",
+          { currentSessionId: input.currentSessionId },
         ),
       ),
       Effect.map((rows) => rows.map((row) => row.sessionId)),
@@ -344,6 +399,7 @@ export const make = Effect.gen(function* () {
         toPersistenceSqlOrDecodeError(
           "AuthSessionRepository.setLastConnectedAt:query",
           "AuthSessionRepository.setLastConnectedAt:encodeRequest",
+          { sessionId: input.sessionId },
         ),
       ),
     );

apps/server/src/persistence/Errors.ts

@@ -19,11 +19,20 @@ function summarizeSchemaIssue(issue: SchemaIssue.Issue): string {
 // Core Persistence Errors
 // ===============================
 
+export const PersistenceErrorCorrelation = Schema.Union([
+  Schema.Struct({ sessionId: Schema.String }),
+  Schema.Struct({ currentSessionId: Schema.String }),
+  Schema.Struct({ pairingLinkId: Schema.String }),
+  Schema.Struct({ threadId: Schema.String }),
+]);
+export type PersistenceErrorCorrelation = typeof PersistenceErrorCorrelation.Type;
+
 export class PersistenceSqlError extends Schema.TaggedErrorClass<PersistenceSqlError>()(
   "PersistenceSqlError",
   {
     operation: Schema.String,
     detail: Schema.optional(Schema.String),
+    correlation: Schema.optional(PersistenceErrorCorrelation),
     cause: Schema.optional(Schema.Defect()),
   },
 ) {
@@ -39,13 +48,19 @@ export class PersistenceDecodeError extends Schema.TaggedErrorClass<PersistenceD
   {
     operation: Schema.String,
     issue: Schema.String,
+    correlation: Schema.optional(PersistenceErrorCorrelation),
     cause: Schema.optional(Schema.Defect()),
   },
 ) {
-  static fromSchemaError(operation: string, cause: Schema.SchemaError): PersistenceDecodeError {
+  static fromSchemaError(
+    operation: string,
+    cause: Schema.SchemaError,
+    correlation?: PersistenceErrorCorrelation,
+  ): PersistenceDecodeError {
     return new PersistenceDecodeError({
       operation,
       issue: summarizeSchemaIssue(cause.issue),
+      ...(correlation === undefined ? {} : { correlation }),
       cause,
     });
   }