@effect-app/infra 4.0.0-beta.324 → 4.0.0-beta.326

package/src/Store/Memory.ts

@@ -18,7 +18,7 @@ import * as Struct from "effect/Struct"
 import { InfraLogger } from "../logger.ts"
 import { annotateDb } from "../otel.ts"
 import { codeFilter, codeFilter3_ } from "./codeFilter.ts"
-import { makeJsonDocumentCodec } from "./jsonDocument.ts"
+import { makeJsonDocumentCodec, makeStoredDecode } from "./jsonDocument.ts"
 import { get, jsonifyFilter, type JsonLower, makeJsonLower, makeUpdateETag, toJsonQueryValue } from "./utils.ts"
 
 export { get } from "./utils.ts"
@@ -335,14 +335,16 @@ export function makeMemoryStoreInt<IdKey extends keyof Encoded, Encoded extends
   seed?: Effect.Effect<Iterable<Encoded>, E, R>,
   _defaultValues?: Partial<Encoded>,
   schema?: StoreConfig<Encoded>["schema"],
-  json?: JsonLower
+  json?: JsonLower,
+  jitM?: StoreConfig<Encoded>["jitM"]
 ) {
   type PM = PersistenceModelType<Encoded>
   return Effect.gen(function*() {
     const updateETag = makeUpdateETag(modelName)
     const codec = makeJsonDocumentCodec<Encoded>(schema)
     const encodeDoc = (e: Encoded | PM): PM => codec.encode({ _etag: undefined, ...e })
-    const decodeDoc = (e: PM): PM => codec.decode(e)
+    // read path: stored JSON -> jitM -> JSON→Encoded decode
+    const decodeDoc = makeStoredDecode<Encoded>(codec, jitM)
     const items_ = yield* seed ?? Effect.sync(() => [])
     const toJson = json?.toJson ?? toJsonQueryValue
     const lowerFilter = json?.jsonifyFilter ?? jsonifyFilter
@@ -546,7 +548,8 @@ export const makeMemoryStore = () => ({
       seed,
       config?.defaultValues,
       config?.schema,
-      json
+      json,
+      config?.jitM
     )
     const ctx = yield* Effect.context<R>()
     const stores = new Map([["primary", primary]])
@@ -566,7 +569,16 @@ export const makeMemoryStore = () => ({
         if (config?.allowNamespace && !config.allowNamespace(namespace)) {
           throw new Error(`Namespace ${namespace} not allowed!`)
         }
-        return makeMemoryStoreInt(modelName, idKey, namespace, seed, config?.defaultValues, config?.schema, json)
+        return makeMemoryStoreInt(
+          modelName,
+          idKey,
+          namespace,
+          seed,
+          config?.defaultValues,
+          config?.schema,
+          json,
+          config?.jitM
+        )
           .pipe(
             Effect.orDie,
             Effect.provide(ctx),

package/src/Store/SQL/Pg.ts

@@ -12,7 +12,7 @@ import { SqlClient } from "effect/unstable/sql"
 import { DatabaseError, OptimisticConcurrencyException } from "../../errors.ts"
 import { InfraLogger } from "../../logger.ts"
 import { annotateDb } from "../../otel.ts"
-import { makeJsonDocumentCodec } from "../jsonDocument.ts"
+import { makeJsonDocumentCodec, makeStoredDecode } from "../jsonDocument.ts"
 import { makeETag, makeJsonLower, toJsonQueryValue } from "../utils.ts"
 import { buildWhereSQLQuery, logQuery, pgDialect } from "./query.ts"
 
@@ -78,6 +78,8 @@ const makePgStore = Effect.fnUntraced(function*({ prefix }: StorageConfig) {
       const json = makeJsonLower(config)
       const defaultValues = json.toJson(config?.defaultValues ?? {}) as Partial<Encoded>
       const codec = makeJsonDocumentCodec<Encoded>(config?.schema)
+      // read path: stored JSON -> defaultValues -> jitM -> JSON→Encoded decode
+      const decodeStored = makeStoredDecode<Encoded>(codec, config?.jitM)
 
       const resolveNamespace = !config?.allowNamespace
         ? Effect.succeed("primary")
@@ -201,7 +203,7 @@ const makePgStore = Effect.fnUntraced(function*({ prefix }: StorageConfig) {
             return exec(sqlText, [ns])
               .pipe(
                 Effect.map((rows) =>
-                  (rows as any[]).map((r) => parseRow<Encoded>(r, idKey, defaultValues, codec.decode))
+                  (rows as any[]).map((r) => parseRow<Encoded>(r, idKey, defaultValues, decodeStored))
                 ),
                 annotateDb({
                   operation: "all",
@@ -224,7 +226,7 @@ const makePgStore = Effect.fnUntraced(function*({ prefix }: StorageConfig) {
                   Effect.map((rows) => {
                     const row = (rows as any[])[0]
                     return row
-                      ? Option.some(parseRow<Encoded>(row, idKey, defaultValues, codec.decode))
+                      ? Option.some(parseRow<Encoded>(row, idKey, defaultValues, decodeStored))
                       : Option.none()
                   }),
                   annotateDb({
@@ -298,7 +300,7 @@ const makePgStore = Effect.fnUntraced(function*({ prefix }: StorageConfig) {
                         })
                       }
                       return (rows as any[]).map((r) =>
-                        parseRow<Encoded>(r, idKey, defaultValues, codec.decode) as any as M
+                        parseRow<Encoded>(r, idKey, defaultValues, decodeStored) as any as M
                       )
                     })
                   )

package/src/Store/SQL.ts

@@ -15,7 +15,7 @@ import { SqlClient } from "effect/unstable/sql"
 import { DatabaseError, OptimisticConcurrencyException } from "../errors.ts"
 import { InfraLogger } from "../logger.ts"
 import { annotateDb, type DbSystem } from "../otel.ts"
-import { makeJsonDocumentCodec } from "./jsonDocument.ts"
+import { makeJsonDocumentCodec, makeStoredDecode } from "./jsonDocument.ts"
 import { buildWhereSQLQuery, logQuery, type SQLDialect, sqliteDialect } from "./SQL/query.ts"
 import { makeETag, makeJsonLower, toJsonQueryValue } from "./utils.ts"
 
@@ -94,6 +94,8 @@ function makeSQLStoreInt(system: DbSystem, dialect: SQLDialect, jsonColumnType:
         const json = makeJsonLower(config)
         const defaultValues = json.toJson(config?.defaultValues ?? {}) as Partial<Encoded>
         const codec = makeJsonDocumentCodec<Encoded>(config?.schema)
+        // read path: stored JSON -> defaultValues -> jitM -> JSON→Encoded decode
+        const decodeStored = makeStoredDecode<Encoded>(codec, config?.jitM)
 
         const resolveNamespace = !config?.allowNamespace
           ? Effect.succeed("primary")
@@ -217,7 +219,7 @@ function makeSQLStoreInt(system: DbSystem, dialect: SQLDialect, jsonColumnType:
               return exec(sqlText, [ns])
                 .pipe(
                   Effect.map((rows) =>
-                    (rows as any[]).map((r) => parseRow<Encoded>(r, idKey, defaultValues, codec.decode))
+                    (rows as any[]).map((r) => parseRow<Encoded>(r, idKey, defaultValues, decodeStored))
                   ),
                   annotateDb({
                     operation: "all",
@@ -240,7 +242,7 @@ function makeSQLStoreInt(system: DbSystem, dialect: SQLDialect, jsonColumnType:
                     Effect.map((rows) => {
                       const row = (rows as any[])[0]
                       return row
-                        ? Option.some(parseRow<Encoded>(row, idKey, defaultValues, codec.decode))
+                        ? Option.some(parseRow<Encoded>(row, idKey, defaultValues, decodeStored))
                         : Option.none()
                     }),
                     annotateDb({
@@ -314,7 +316,7 @@ function makeSQLStoreInt(system: DbSystem, dialect: SQLDialect, jsonColumnType:
                               })
                             }
                             return (rows as any[]).map((r) =>
-                              parseRow<Encoded>(r, idKey, defaultValues, codec.decode) as any as M
+                              parseRow<Encoded>(r, idKey, defaultValues, decodeStored) as any as M
                             )
                           })
                         )
@@ -433,6 +435,8 @@ function makeSQLiteStorePerNs(
       const json = makeJsonLower(config)
       const defaultValues = json.toJson(config?.defaultValues ?? {}) as Partial<Encoded>
       const codec = makeJsonDocumentCodec<Encoded>(config?.schema)
+      // read path: stored JSON -> defaultValues -> jitM -> JSON→Encoded decode
+      const decodeStored = makeStoredDecode<Encoded>(codec, config?.jitM)
 
       const resolveNamespace = !config?.allowNamespace
         ? Effect.succeed("primary")
@@ -564,7 +568,7 @@ function makeSQLiteStorePerNs(
           return exec(ns, sqlText)
             .pipe(
               Effect.map((rows) =>
-                (rows as any[]).map((r) => parseRow<Encoded>(r, idKey, defaultValues, codec.decode))
+                (rows as any[]).map((r) => parseRow<Encoded>(r, idKey, defaultValues, decodeStored))
               ),
               annotateDb({
                 operation: "all",
@@ -586,7 +590,7 @@ function makeSQLiteStorePerNs(
                   Effect.map((rows) => {
                     const row = (rows as any[])[0]
                     return row
-                      ? Option.some(parseRow<Encoded>(row, idKey, defaultValues, codec.decode))
+                      ? Option.some(parseRow<Encoded>(row, idKey, defaultValues, decodeStored))
                       : Option.none()
                   }),
                   annotateDb({
@@ -660,7 +664,7 @@ function makeSQLiteStorePerNs(
                             })
                           }
                           return (rows as any[]).map((r) =>
-                            parseRow<Encoded>(r, idKey, defaultValues, codec.decode) as any as M
+                            parseRow<Encoded>(r, idKey, defaultValues, decodeStored) as any as M
                           )
                         })
                       )

package/src/Store/jsonDocument.ts

@@ -1,6 +1,6 @@
 import type { FieldValues } from "effect-app/Model/filter/types"
 import * as S from "effect-app/Schema"
-import type { PersistenceModelType } from "effect-app/Store"
+import type { PersistenceModelType, StoreConfig } from "effect-app/Store"
 import { toJsonQueryValue } from "./utils.ts"
 
 export interface JsonDocumentCodec<E extends FieldValues> {
@@ -21,6 +21,19 @@ const joinEtag = <E extends FieldValues>(
 /**
  * Encoded document ↔ JSON document. Prefer `Schema.toCodecJson(toEncoded(schema))`
  * when the store has a schema; otherwise lower Date/Map/Set structurally.
+ *
+ * Both directions are **strict**: they run the whole-document codec, so a
+ * document that does not match the Encoded shape fails loudly rather than being
+ * read back half-decoded.
+ *
+ * Migrating a legacy-shaped document is therefore not this codec's job: the
+ * store applies `StoreConfig.jitM` to the raw JSON document *before* calling
+ * `decode` (see {@link makeStoredDecode}), which is the only place where a
+ * document can be repaired. A document `jitM` does not repair is a genuine
+ * failure and throws here.
+ *
+ * `_etag` is infrastructure metadata rather than part of the domain document,
+ * so it is split off before the codec runs and re-attached afterwards.
  */
 export const makeJsonDocumentCodec = <E extends FieldValues>(schema?: S.Top): JsonDocumentCodec<E> => {
   if (schema) {
@@ -41,3 +54,35 @@ export const makeJsonDocumentCodec = <E extends FieldValues>(schema?: S.Top): Js
     decode: (doc) => doc
   }
 }
+
+/**
+ * The store *read* boundary: apply `jitM` to the raw JSON document - after the
+ * adapter merged `defaultValues` into it - and only then decode JSON→Encoded
+ * with the strict {@link makeJsonDocumentCodec} codec.
+ *
+ * This is the one place a legacy-shaped document can be repaired, and why
+ * `jitM` can fix things no schema decode could - an explicit `null` where a
+ * `Date` is expected, a key added after the document was written. It runs
+ * before any schema decode sees the document; a document it does not repair
+ * still fails loudly in `codec.decode`.
+ *
+ * `_etag` is infrastructure metadata rather than part of the domain document,
+ * so it is split off first and `jitM` never sees it.
+ *
+ * Returns `codec.decode` unchanged when there is no `jitM`; the write path,
+ * which must not run migrations, keeps using `codec.decode` directly.
+ */
+export const makeStoredDecode = <E extends FieldValues>(
+  codec: JsonDocumentCodec<E>,
+  jitM: StoreConfig<E>["jitM"]
+): JsonDocumentCodec<E>["decode"] => {
+  if (jitM === undefined) return codec.decode
+  return (doc) => {
+    const { rest, _etag } = splitEtag(doc)
+    // adapters type the stored document as the Encoded persistence model, but
+    // at this point it is still the raw JSON document that `jitM` is written
+    // against - and `jitM` returns JSON, which is what `codec.decode` consumes.
+    const migrated = jitM(rest) as unknown as E
+    return codec.decode(joinEtag(migrated, _etag))
+  }
+}

package/test/arbs-magnitude.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "@effect/vitest"
+import * as S from "effect-app/Schema"
+import { generateFromSchema } from "../src/arbs.js"
+
+describe("generateFromSchema number magnitudes", () => {
+  it("keeps PositiveNumber and NonNegativeNumber samples realistic", () => {
+    const schema = S.Struct({ amount: S.PositiveNumber, weight: S.NonNegativeNumber })
+    for (let i = 0; i < 200; i++) {
+      const { amount, weight } = generateFromSchema(schema).value
+      expect(amount).toBeGreaterThan(0)
+      expect(weight).toBeGreaterThanOrEqual(0)
+      expect(Math.max(amount, weight)).toBeLessThanOrEqual(1_000_000)
+      expect(Number.isFinite(amount * weight)).toBe(true)
+    }
+  })
+
+  it("does not change the JSON Schema of the number schemas", () => {
+    expect(S.toJsonSchemaDocument(S.PositiveNumber).schema).not.toHaveProperty("maximum")
+    expect(S.toJsonSchemaDocument(S.NonNegativeNumber).schema).not.toHaveProperty("maximum")
+  })
+})

package/test/dist/arbs-magnitude.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbs-magnitude.test.d.ts","sourceRoot":"","sources":["../arbs-magnitude.test.ts"],"names":[],"mappings":""}

package/test/dist/repository-legacy-document.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository-legacy-document.test.d.ts","sourceRoot":"","sources":["../repository-legacy-document.test.ts"],"names":[],"mappings":""}

package/test/repository-legacy-document.test.ts

@@ -0,0 +1,329 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
+import { makeRepo } from "effect-app/Model/Repository"
+import { RepositoryRegistryLive } from "effect-app/Model/Repository/Registry"
+import * as Option from "effect-app/Option"
+import * as S from "effect-app/Schema"
+import { setupRequestContextFromCurrent } from "effect-app/setupRequest"
+import type { JsonRecord } from "effect-app/Store"
+import { StoreMaker } from "effect-app/Store"
+import { describe, expect, it } from "vitest"
+import { makeJsonDocumentCodec, makeStoredDecode } from "../src/Store/jsonDocument.js"
+import { makeMemoryStoreInt } from "../src/Store/Memory.js"
+import { makeJsonLower } from "../src/Store/utils.js"
+
+/**
+ * A Memory store seeded with *raw stored documents* instead of items encoded
+ * through the schema, so that a legacy-shaped document can reach the read path -
+ * exactly what Cosmos (`fromStored`) and SQL (`parseRow`) do in production.
+ *
+ * `MemoryStoreLive` cannot be used for this: it strictly `encode`s whatever it
+ * is seeded with, so a legacy document never makes it into the store. The inner
+ * store here is therefore schemaless (it may not validate what we seed), and
+ * the real store read boundary - `defaultValues` merged, then `jitM`, then the
+ * strict JSON→Encoded decode - is applied on top via {@link makeStoredDecode}.
+ */
+const LegacyDocStoreLive = (docs: readonly Record<string, unknown>[]) =>
+  StoreMaker.toLayer(Effect.sync(() => ({
+    make: ((modelName: string, idKey: any, _seed: any, config: any) =>
+      Effect.map(
+        makeMemoryStoreInt(
+          modelName,
+          idKey,
+          "primary",
+          Effect.succeed(docs as any),
+          config?.defaultValues,
+          undefined,
+          makeJsonLower(config)
+        ),
+        (store) => {
+          const decode = makeStoredDecode<any>(makeJsonDocumentCodec<any>(config?.schema), config?.jitM)
+          return {
+            ...store,
+            all: Effect.map(store.all, (rows) => rows.map(decode)),
+            find: (id: any) => Effect.map(store.find(id), Option.map(decode)),
+            filter: (f: any) => Effect.map(store.filter(f), (rows: any[]) => f.select ? rows : rows.map(decode))
+          }
+        }
+      )) as any
+  })))
+
+class Shop extends S.Class<Shop>("LegacyDocShop")({
+  id: S.String,
+  name: S.NonEmptyString255,
+  createdAt: S.Date,
+  updatedAt: S.Date,
+  vatRate: S.Number,
+  tags: S.ReadonlySet(S.String),
+  meta: S.ReadonlyMap({ key: S.String, value: S.String })
+}) {}
+
+// `vatRate` was added later; stored documents from before that do not have it.
+const jitM = (json: JsonRecord): JsonRecord => "vatRate" in json ? json : { ...json, vatRate: 19 }
+
+const legacyDoc = {
+  id: "shop-legacy",
+  name: "Legacy Shop",
+  createdAt: "2024-06-01T00:00:00.000Z",
+  updatedAt: "2024-06-03T00:00:00.000Z",
+  tags: ["a"],
+  meta: [["k", "v"]]
+}
+
+const currentDoc = {
+  id: "shop-current",
+  name: "Current Shop",
+  createdAt: "2024-06-02T00:00:00.000Z",
+  updatedAt: "2024-06-04T00:00:00.000Z",
+  vatRate: 7,
+  tags: ["b"],
+  meta: [["k2", "v2"]]
+}
+
+/** a legacy document that stored an explicit `null` where a Date is expected */
+const nullDoc = { ...legacyDoc, id: "shop-null", vatRate: 21, updatedAt: null }
+
+/** `vatRate` present but falsy, `updatedAt` an explicit null */
+const zeroDoc = { ...legacyDoc, id: "shop-zero", vatRate: 0, updatedAt: null }
+
+const TestLive = Layer.merge(LegacyDocStoreLive([legacyDoc, currentDoc]), RepositoryRegistryLive)
+const NullDocLive = Layer.merge(LegacyDocStoreLive([nullDoc]), RepositoryRegistryLive)
+const CurrentDocLive = Layer.merge(LegacyDocStoreLive([currentDoc]), RepositoryRegistryLive)
+const DefaultsLive = Layer.merge(LegacyDocStoreLive([legacyDoc, zeroDoc]), RepositoryRegistryLive)
+
+describe("repository reads of legacy documents", () => {
+  it("all: jitM fills the key the stored document is missing", () =>
+    Effect
+      .gen(function*() {
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM })
+
+        const items = yield* repo.all
+
+        expect(items).toHaveLength(2)
+        const legacy = items.find((_) => _.id === "shop-legacy")!
+        expect(legacy).toBeInstanceOf(Shop)
+        expect(legacy.vatRate).toBe(19)
+        expect(legacy.createdAt).toBeInstanceOf(Date)
+        expect(legacy.tags).toBeInstanceOf(Set)
+        expect([...legacy.tags]).toEqual(["a"])
+        expect(items.find((_) => _.id === "shop-current")!.vatRate).toBe(7)
+      })
+      .pipe(
+        Effect.provide(TestLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  it("find: a legacy document decodes through jitM", () =>
+    Effect
+      .gen(function*() {
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM })
+
+        const found = yield* repo.find("shop-legacy")
+
+        expect(Option.isSome(found)).toBe(true)
+        const shop = Option.getOrThrow(found)
+        expect(shop.vatRate).toBe(19)
+        expect(shop.name).toBe("Legacy Shop")
+        expect(shop.createdAt).toBeInstanceOf(Date)
+      })
+      .pipe(
+        Effect.provide(TestLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  it("validateSample: legacy documents validate because jitM runs at the store boundary", () =>
+    Effect
+      .gen(function*() {
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM })
+
+        const result = yield* repo.validateSample({ percentage: 1.0 })
+
+        expect(result.total).toBe(2)
+        expect(result.sampled).toBe(2)
+        expect(result.errors).toHaveLength(0)
+        expect(result.valid).toBe(2)
+      })
+      .pipe(
+        Effect.provide(TestLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  it("jitM repairs an explicit null, and the document decodes end-to-end", () =>
+    Effect
+      .gen(function*() {
+        // the case the store boundary exists for: `null` is not a valid
+        // `S.Date` encoding, so no schema decode could ever fix it
+        const repairNull = (json: JsonRecord): JsonRecord =>
+          json["updatedAt"] === null ? { ...json, updatedAt: "2024-06-05T00:00:00.000Z" } : json
+
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM: repairNull })
+
+        const shop = Option.getOrThrow(yield* repo.find("shop-null"))
+        expect(shop.updatedAt).toBeInstanceOf(Date)
+        expect(shop.updatedAt.toISOString()).toBe("2024-06-05T00:00:00.000Z")
+
+        const all = yield* repo.all
+        expect(all).toHaveLength(1)
+        expect(all[0]!.updatedAt.toISOString()).toBe("2024-06-05T00:00:00.000Z")
+      })
+      .pipe(
+        Effect.provide(NullDocLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  it("jitM receives the raw JSON document, and its JSON result is what the decode consumes", () =>
+    Effect
+      .gen(function*() {
+        const seen: JsonRecord[] = []
+        const observe = (json: JsonRecord): JsonRecord => {
+          seen.push(json)
+          // returning JSON - an ISO string, not a `Date` - is what decodes
+          return { ...json, updatedAt: "2024-06-09T00:00:00.000Z" }
+        }
+
+        const repo = yield* makeRepo("LegacyDocShop", Shop, { jitM: observe })
+
+        const shop = Option.getOrThrow(yield* repo.find("shop-current"))
+
+        expect(seen).toHaveLength(1)
+        const raw = seen[0]!
+        // a `Date` field arrives as an ISO string
+        expect(typeof raw["createdAt"]).toBe("string")
+        expect(raw["createdAt"]).toBe("2024-06-02T00:00:00.000Z")
+        // a `ReadonlySet` as an array, a `ReadonlyMap` as an array of pairs
+        expect(raw["tags"]).toEqual(["b"])
+        expect(raw["meta"]).toEqual([["k2", "v2"]])
+        // never native Encoded values
+        expect(raw["createdAt"]).not.toBeInstanceOf(Date)
+        expect(raw["meta"]).not.toBeInstanceOf(Map)
+        // `_etag` is infra metadata and is not part of the document
+        expect("_etag" in raw).toBe(false)
+
+        // the JSON the jitM returned was decoded to the native Encoded value
+        expect(shop.updatedAt).toBeInstanceOf(Date)
+        expect(shop.updatedAt.toISOString()).toBe("2024-06-09T00:00:00.000Z")
+        expect(shop.meta).toBeInstanceOf(Map)
+        expect([...shop.meta]).toEqual([["k2", "v2"]])
+      })
+      .pipe(
+        Effect.provide(CurrentDocLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  it("defaultValues only fill absent keys, and a stored null still reaches jitM", () =>
+    Effect
+      .gen(function*() {
+        const seen: JsonRecord[] = []
+        const repo = yield* makeRepo("LegacyDocShop", Shop, {
+          jitM: (json) => {
+            seen.push(json)
+            return json["updatedAt"] === null ? { ...json, updatedAt: "2024-06-08T00:00:00.000Z" } : json
+          },
+          config: {
+            defaultValues: {
+              vatRate: 19,
+              updatedAt: new Date("2024-01-01T00:00:00.000Z")
+            }
+          }
+        })
+
+        const items = yield* repo.all
+        expect(items).toHaveLength(2)
+
+        // absent key -> filled by defaultValues
+        const missing = items.find((_) => _.id === "shop-legacy")!
+        expect(missing.vatRate).toBe(19)
+        // present key -> the stored value wins, even when falsy
+        const present = items.find((_) => _.id === "shop-zero")!
+        expect(present.vatRate).toBe(0)
+
+        // defaultValues are merged *before* jitM runs
+        const filledSeen = seen.find((_) => _["id"] === "shop-legacy")!
+        expect(filledSeen["vatRate"]).toBe(19)
+        // ...but never overwrite a key the document has
+        expect(filledSeen["updatedAt"]).toBe("2024-06-03T00:00:00.000Z")
+
+        // a stored explicit `null` is NOT replaced by the default: it reaches jitM
+        const nullSeen = seen.find((_) => _["id"] === "shop-zero")!
+        expect(nullSeen["updatedAt"]).toBe(null)
+        expect(present.updatedAt.toISOString()).toBe("2024-06-08T00:00:00.000Z")
+      })
+      .pipe(
+        Effect.provide(DefaultsLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      ))
+
+  /**
+   * The store boundary decode is deliberately **strict**: `jitM` is the one and
+   * only place a legacy document can be repaired, and a document it does not
+   * repair must fail loudly rather than be read back half-decoded. This test
+   * pins that behaviour down on purpose - do not "fix" it by making the decode
+   * lenient.
+   */
+  it("a document jitM does not repair fails loudly at the store boundary", async () => {
+    const program = Effect
+      .gen(function*() {
+        // `vatRate` is still missing after this jitM ran: it only touches `updatedAt`
+        const repo = yield* makeRepo("LegacyDocShop", Shop, {
+          jitM: (json) => ({ ...json, updatedAt: json["updatedAt"] ?? "2024-06-03T00:00:00.000Z" })
+        })
+
+        return yield* repo.all
+      })
+      .pipe(
+        Effect.provide(TestLive),
+        setupRequestContextFromCurrent(),
+        Effect.scoped,
+        Effect.runPromise
+      )
+
+    let caught: unknown = undefined
+    try {
+      await program
+    } catch (e) {
+      caught = e
+    }
+
+    expect(caught).toBeDefined()
+    const message = caught instanceof Error ? caught.message : String(caught)
+    // the strict `toCodecJson(toEncoded(schema))` decode reports the key jitM
+    // failed to add, with the path to it
+    expect(message).toContain("Missing key")
+    expect(message).toContain("vatRate")
+  })
+
+  it("_etag is not visible to jitM and survives the round trip", () => {
+    const seen: JsonRecord[] = []
+    const decode = makeStoredDecode<any>(
+      makeJsonDocumentCodec<any>(Shop),
+      (json) => {
+        seen.push(json)
+        return { ...json, vatRate: 19 }
+      }
+    )
+
+    const decoded = decode({ ...legacyDoc, _etag: "etag-1" } as any)
+
+    // jitM sees the document without the infra metadata
+    expect(seen).toHaveLength(1)
+    expect("_etag" in seen[0]!).toBe(false)
+    // ...and the etag is re-attached to the decoded Encoded document
+    expect(decoded._etag).toBe("etag-1")
+    expect(decoded.vatRate).toBe(19)
+    expect(decoded.createdAt).toBeInstanceOf(Date)
+  })
+})