Finalize boxed contract runtime migration

Author: adz

AGENTS.md

@@ -34,10 +34,10 @@ These standards represent the user's preferred style and architectural philosoph
 ## 4. Architectural Patterns
 - **Decoder Pattern:** `JsonSource -> struct('T * JsonSource)`
 - **Encoder Pattern:** `JsonWriter -> 'T -> unit`
-- **Pipeline Blueprint:** Use `Schema.define<'T> |> Schema.construct ctor |> Schema.field ... |> Schema.build` to define symmetric mappings. This is the current stable DSL.
+- **Pipeline Blueprint:** Use `Schema.record ctor |> Schema.field ... |> Schema.build` to define symmetric mappings. This is the current stable DSL.
 
 ## 5. Current Findings & Edge Cases
-- **Do not collapse `Schema.define` and `Schema.construct` without proving it compiles across the repo.** A direct `Schema.define makeCtor` style was attempted and rejected because F# either mis-inferred record targets when field names overlapped (`Id`, `Name`) or collapsed the constructor state to `obj`.
+- **Keep `Schema.record` as the stable entry point.** Earlier experiments that split record initialization into separate entry points or tried to collapse everything into one differently shaped helper ran into F# inference failures around overlapping record fields such as `Id` and `Name`.
 - **Keep `Json.compile` explicit.** Hiding compilation inside `serialize`/`deserialize` would either recompile on each call or require implicit caching, which is poor UX for a performance-oriented library.
 - **Explicit nested/custom schemas currently use `Schema.fieldWith`.** Auto-resolution exists for primitives, lists, and arrays only. Future work may rename this, but the explicit-schema distinction is currently meaningful.
 - **Benchmarks should use the same DSL as tests and docs.** Avoid introducing parallel schema-definition styles unless the repo deliberately adopts a second public API.

README.md

@@ -105,15 +105,15 @@ The project ships both a manual scenario runner and a repeatable `perf` workflow
 - profiling guide: [docs/HOW_TO_PROFILE_BENCHMARK_HOT_PATHS.md](docs/HOW_TO_PROFILE_BENCHMARK_HOT_PATHS.md)
 - full benchmark page: [docs/BENCHMARKS.md](docs/BENCHMARKS.md)
 
-Latest local manual snapshot, measured on March 31, 2026:
+Latest local manual snapshot, measured on April 2, 2026:
 
 | Scenario | CodecMapper serialize | STJ serialize | CodecMapper deserialize | STJ deserialize | Takeaway |
 | --- | ---: | ---: | ---: | ---: | --- |
-| `small-message` | `526.5 ns` | `715.0 ns` | `641.6 ns` | `907.5 ns` | `CodecMapper` still leads both directions on the tiny-message case. |
-| `person-batch-25` | `8.33 us` | `7.37 us` | `24.29 us` | `18.22 us` | Medium nested workloads still trail `STJ`, but remain comfortably ahead of `Newtonsoft.Json`. |
-| `person-batch-250` | `84.95 us` | `69.09 us` | `229.36 us` | `168.44 us` | Larger nested batches still trail `STJ`, but stay ahead of `Newtonsoft.Json`. |
-| `escaped-articles-20` | `43.45 us` | `30.85 us` | `98.00 us` | `59.33 us` | String-heavy payloads remain a clear weak spot, especially on decode. |
-| `telemetry-500` | `413.04 us` | `298.93 us` | `516.87 us` | `513.80 us` | Numeric-heavy decode is still roughly tied with `STJ`, while serialize trails. |
-| `person-batch-25-unknown-fields` | `9.05 us` | `7.85 us` | `30.93 us` | `25.00 us` | Unknown-field decode is still in range, but not especially close to `STJ`. |
+| `small-message` | `441.8 ns` | `627.1 ns` | `644.6 ns` | `889.1 ns` | `CodecMapper` still leads both directions on the tiny-message case. |
+| `person-batch-25` | `7.96 us` | `7.29 us` | `27.13 us` | `20.84 us` | Medium nested workloads still trail `STJ`, but remain ahead of `Newtonsoft.Json` on decode. |
+| `person-batch-250` | `83.89 us` | `71.53 us` | `294.50 us` | `217.70 us` | Larger nested batches still trail `STJ`, and the decode gap widened on this run. |
+| `escaped-articles-20` | `45.97 us` | `34.71 us` | `115.38 us` | `66.25 us` | String-heavy payloads remain a clear weak spot, especially on decode. |
+| `telemetry-500` | `421.70 us` | `317.53 us` | `559.46 us` | `556.73 us` | Numeric-heavy decode is still roughly tied with `STJ`, while serialize trails. |
+| `person-batch-25-unknown-fields` | `8.56 us` | `7.63 us` | `34.38 us` | `29.37 us` | Unknown-field decode is still in range, but not especially close to `STJ`. |
 
 Those numbers are machine-specific. Compare ratios and workload shape more than the absolute values.

TASKS.md

@@ -2,14 +2,15 @@
 
 Active work only. Historical completed work lives in [notes/AGENT_NOTES.md](notes/AGENT_NOTES.md) and [AGENTS.md](AGENTS.md).
 
-- [ ] **Task 42: Delete the old boxed schema engine completely**
-  - Remove `ISchema`, `SchemaDefinition`, `SchemaField`, and `obj[] -> obj` record construction from the active implementation.
+- [x] **Task 42: Finalize the core boxed contract runtime**
+  - Remove `ISchema`, `SchemaDefinition`, `SchemaField`, and `obj[] -> obj` record construction from the active core implementation.
   - Move the public authored DSL to `Schema.*` over `Schema<'T>`.
   - Delete the old schema DSL instead of keeping compatibility shims.
   - Retarget `Json`, `Xml`, `Yaml`, `KeyValue`, and `JsonSchema` to compile from the new boxed contract IR directly.
   - Remove any `Lowering.lower` or legacy boxed-schema bridge from the runtime path.
-  - Update tests, benchmarks, bridge code, and docs to the new surface.
-  - Completion bar: there is no old boxed DSL left, publicly or internally.
+  - Update tests, benchmarks, and docs to the new surface.
+  - Explicitly exclude bridge internals from this task. Bridge cleanup can follow once the core runtime shape is stable.
+  - Completion bar: there is no old boxed DSL left in the core runtime path or public authored surface.
 
 - [ ] **Task 49: Review and improve the new DSL for DX**
   - After Task 42, review the new `Schema.*` surface for compactness, clarity, and maintainability.

benchmarks/BenchmarkScenarios.fs

@@ -659,55 +659,50 @@ module TypedJsonExperiment =
 
 module Schemas =
     let address =
-        Schema.define<Address>
-        |> Schema.construct (fun street city -> { Street = street; City = city })
-        |> Schema.field "Street" _.Street
-        |> Schema.field "City" _.City
+        Schema.record (fun street city -> { Street = street; City = city })
+        |> Schema.field "Street" (fun (address: Address) -> address.Street)
+        |> Schema.field "City" (fun (address: Address) -> address.City)
         |> Schema.build
 
     let person =
-        Schema.define<Person>
-        |> Schema.construct (fun id name home -> { Id = id; Name = name; Home = home })
-        |> Schema.field "Id" _.Id
-        |> Schema.field "Name" _.Name
-        |> Schema.fieldWith "Home" _.Home address
+        Schema.record (fun id name home -> { Id = id; Name = name; Home = home })
+        |> Schema.field "Id" (fun (person: Person) -> person.Id)
+        |> Schema.field "Name" (fun (person: Person) -> person.Name)
+        |> Schema.fieldWith "Home" (fun (person: Person) -> person.Home) address
         |> Schema.build
 
     let smallMessage =
-        Schema.define<SmallMessage>
-        |> Schema.construct (fun id kind success traceId -> {
+        Schema.record (fun id kind success traceId -> {
             Id = id
             Kind = kind
             Success = success
             TraceId = traceId
         })
-        |> Schema.field "Id" _.Id
-        |> Schema.field "Kind" _.Kind
-        |> Schema.field "Success" _.Success
-        |> Schema.field "TraceId" _.TraceId
+        |> Schema.field "Id" (fun (message: SmallMessage) -> message.Id)
+        |> Schema.field "Kind" (fun (message: SmallMessage) -> message.Kind)
+        |> Schema.field "Success" (fun (message: SmallMessage) -> message.Success)
+        |> Schema.field "TraceId" (fun (message: SmallMessage) -> message.TraceId)
         |> Schema.build
 
     let article =
-        Schema.define<Article>
-        |> Schema.construct (fun id slug title body tags author -> {
+        Schema.record (fun id slug title body tags author -> {
             Id = id
             Slug = slug
             Title = title
             Body = body
             Tags = tags
             Author = author
         })
-        |> Schema.field "Id" _.Id
-        |> Schema.field "Slug" _.Slug
-        |> Schema.field "Title" _.Title
-        |> Schema.field "Body" _.Body
-        |> Schema.field "Tags" _.Tags
-        |> Schema.fieldWith "Author" _.Author person
+        |> Schema.field "Id" (fun (article: Article) -> article.Id)
+        |> Schema.field "Slug" (fun (article: Article) -> article.Slug)
+        |> Schema.field "Title" (fun (article: Article) -> article.Title)
+        |> Schema.field "Body" (fun (article: Article) -> article.Body)
+        |> Schema.field "Tags" (fun (article: Article) -> article.Tags)
+        |> Schema.fieldWith "Author" (fun (article: Article) -> article.Author) person
         |> Schema.build
 
     let telemetryPoint =
-        Schema.define<TelemetryPoint>
-        |> Schema.construct (fun sensorId timestamp temperature humidity voltage retryCount sequence healthy -> {
+        Schema.record (fun sensorId timestamp temperature humidity voltage retryCount sequence healthy -> {
             SensorId = sensorId
             Timestamp = timestamp
             Temperature = temperature
@@ -717,14 +712,14 @@ module Schemas =
             Sequence = sequence
             Healthy = healthy
         })
-        |> Schema.field "SensorId" _.SensorId
-        |> Schema.field "Timestamp" _.Timestamp
-        |> Schema.field "Temperature" _.Temperature
-        |> Schema.field "Humidity" _.Humidity
-        |> Schema.field "Voltage" _.Voltage
-        |> Schema.field "RetryCount" _.RetryCount
-        |> Schema.field "Sequence" _.Sequence
-        |> Schema.field "Healthy" _.Healthy
+        |> Schema.field "SensorId" (fun (point: TelemetryPoint) -> point.SensorId)
+        |> Schema.field "Timestamp" (fun (point: TelemetryPoint) -> point.Timestamp)
+        |> Schema.field "Temperature" (fun (point: TelemetryPoint) -> point.Temperature)
+        |> Schema.field "Humidity" (fun (point: TelemetryPoint) -> point.Humidity)
+        |> Schema.field "Voltage" (fun (point: TelemetryPoint) -> point.Voltage)
+        |> Schema.field "RetryCount" (fun (point: TelemetryPoint) -> point.RetryCount)
+        |> Schema.field "Sequence" (fun (point: TelemetryPoint) -> point.Sequence)
+        |> Schema.field "Healthy" (fun (point: TelemetryPoint) -> point.Healthy)
         |> Schema.build
 
     let personList = Schema.list person

benchmarks/CodecMapper.Benchmarks/CodecMapperBench.fs

@@ -10,18 +10,16 @@ type Person = { Id: int; Name: string; Home: Address }
 
 module Schemas =
     let address =
-        Schema.define<Address>
-        |> Schema.construct (fun street city -> { Street = street; City = city })
-        |> Schema.field "Street" _.Street
-        |> Schema.field "City" _.City
+        Schema.record (fun street city -> { Street = street; City = city })
+        |> Schema.field "Street" (fun (address: Address) -> address.Street)
+        |> Schema.field "City" (fun (address: Address) -> address.City)
         |> Schema.build
 
     let person =
-        Schema.define<Person>
-        |> Schema.construct (fun id name home -> { Id = id; Name = name; Home = home })
-        |> Schema.field "Id" _.Id
-        |> Schema.field "Name" _.Name
-        |> Schema.fieldWith "Home" _.Home address
+        Schema.record (fun id name home -> { Id = id; Name = name; Home = home })
+        |> Schema.field "Id" (fun (person: Person) -> person.Id)
+        |> Schema.field "Name" (fun (person: Person) -> person.Name)
+        |> Schema.fieldWith "Home" (fun (person: Person) -> person.Home) address
         |> Schema.build
 
     ///

src/CodecMapper.Bridge/Bridge.fs

@@ -64,9 +64,24 @@ type private ConstructionPlan =
 type private ImportedSchema<'T>(fields: FieldRuntime list, createObj: obj[] -> obj) =
     inherit Schema<'T>()
 
-    interface IMappingDefinitionRuntime with
+    ///
+    /// Bridge imports still depend on CLR-oriented construction plans, but the
+    /// active runtime only understands the boxed record-state contract now.
+    interface IRecordRuntime with
         member _.FieldsRuntime = fields
-        member _.CreateObj(values) = createObj values
+        member _.CreateStateObj() = box (Array.zeroCreate<obj> fields.Length)
+
+        member _.StoreFieldObj(state, index, value) =
+            let values = unbox<obj array> state
+            values[index] <- value
+
+        member _.CompleteObj(state) =
+            let values = unbox<obj array> state
+            createObj values
+
+        member _.ReleaseStateObj(state) =
+            let values = unbox<obj array> state
+            System.Array.Clear(values, 0, values.Length)
 
 type private SchemaFactory =
     static member CreateImported<'T>(fields: FieldRuntime list, createFunc: Func<obj[], obj>) : Schema<'T> =