From c53b621b8502e694e6d06a4939278fb6f7bff5dc Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 16 Jun 2026 18:27:10 -0400 Subject: [PATCH] docs: mark native-typed JSON feature complete; update Component-Commons codec note NJ-6: full solution builds 0/0; feature-targeted tests green (Commons codec 38, TemplateEngine InstanceService 17, ConfigDB normalizer 8, Transport serializer 12, SiteRuntime InstanceActor 47). Component-Commons now describes the native-typed List encoding + read-both decode + the three normalization paths. #93/M3 folded in. --- .../plans/2026-06-16-native-typed-json-design.md | 2 +- .../2026-06-16-native-typed-json.md.tasks.json | 16 +++++++++------- docs/requirements/Component-Commons.md | 2 +- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/plans/2026-06-16-native-typed-json-design.md b/docs/plans/2026-06-16-native-typed-json-design.md index 07573fc3..edc9a9e3 100644 --- a/docs/plans/2026-06-16-native-typed-json-design.md +++ b/docs/plans/2026-06-16-native-typed-json-design.md @@ -1,7 +1,7 @@ # Native-Typed JSON for List Attribute Values — Design **Date:** 2026-06-16 -**Status:** Approved (brainstorming) — ready for implementation plan +**Status:** Implemented (NJ-1 … NJ-6, branch `feature/native-typed-json`) — full solution builds 0/0; feature-targeted tests green across Commons, TemplateEngine, ConfigurationDatabase, SiteRuntime, and Transport. Follow-up **#93/M3** (populate `InstanceAttributeOverride.ElementDataType` on write) was folded into NJ-2 so the central normalizer can read the override element type directly. **Branch:** `feature/native-typed-json` ## Problem diff --git a/docs/plans/2026-06-16-native-typed-json.md.tasks.json b/docs/plans/2026-06-16-native-typed-json.md.tasks.json index 90dcdf72..ac42df4f 100644 --- a/docs/plans/2026-06-16-native-typed-json.md.tasks.json +++ b/docs/plans/2026-06-16-native-typed-json.md.tasks.json @@ -2,13 +2,15 @@ "planPath": "docs/plans/2026-06-16-native-typed-json.md", "designDoc": "docs/plans/2026-06-16-native-typed-json-design.md", "branch": "feature/native-typed-json", + "status": "complete", "tasks": [ - {"id": 96, "ref": "NJ-1", "subject": "Codec — native-typed Encode + read-both Decode", "class": "high-risk", "status": "pending"}, - {"id": 97, "ref": "NJ-2", "subject": "Stamp ElementDataType on instance-override writes", "class": "small", "status": "pending"}, - {"id": 98, "ref": "NJ-3", "subject": "Central MS SQL idempotent startup normalizer", "class": "high-risk", "status": "pending", "blockedBy": [96, 97]}, - {"id": 99, "ref": "NJ-4", "subject": "Site SQLite active normalization on override load", "class": "high-risk", "status": "pending", "blockedBy": [96]}, - {"id": 100, "ref": "NJ-5", "subject": "Normalize List values on bundle import", "class": "standard", "status": "pending", "blockedBy": [96]}, - {"id": 101, "ref": "NJ-6", "subject": "Integration verification + docs", "class": "standard", "status": "pending", "blockedBy": [96, 97, 98, 99, 100]} + {"id": 96, "ref": "NJ-1", "subject": "Codec — native-typed Encode + read-both Decode", "class": "high-risk", "status": "completed", "commits": ["180d554", "bf80ca1"]}, + {"id": 97, "ref": "NJ-2", "subject": "Stamp ElementDataType on instance-override writes (folds in #93/M3)", "class": "small", "status": "completed", "commits": ["abe8832"]}, + {"id": 98, "ref": "NJ-3", "subject": "Central MS SQL idempotent startup normalizer", "class": "high-risk", "status": "completed", "commits": ["f4b101b", "feeae13"]}, + {"id": 99, "ref": "NJ-4", "subject": "Site SQLite active normalization on override load", "class": "high-risk", "status": "completed", "commits": ["5841cec", "feeae13"]}, + {"id": 100, "ref": "NJ-5", "subject": "Normalize List values on bundle import", "class": "standard", "status": "completed", "commits": ["e3d804a", "feeae13"]}, + {"id": 101, "ref": "NJ-6", "subject": "Integration verification + docs", "class": "standard", "status": "completed"} ], - "lastUpdated": "2026-06-16" + "lastUpdated": "2026-06-16", + "note": "feature/native-typed-json was reset off these commits during concurrent other-window git work and restored to f4b101b (the NJ-1..NJ-5 tip) via reflog; NJ-3/4/5 review fixes committed as feeae13 + NJ-6 docs on top." } diff --git a/docs/requirements/Component-Commons.md b/docs/requirements/Component-Commons.md index 87853db4..929b31b7 100644 --- a/docs/requirements/Component-Commons.md +++ b/docs/requirements/Component-Commons.md @@ -26,7 +26,7 @@ Referenced by all component libraries and the Host. Commons must define shared primitive and utility types used across multiple components, including but not limited to: -- **`DataType` enum**: Enumerates the data types supported by the system: Boolean, Int32, Float, Double, String, DateTime, Binary, and **List** (a homogeneous multi-value attribute). A `List` attribute carries a companion `ElementDataType` (one of the scalar types — String, Int32, Float, Double, Boolean, DateTime; not Binary, not nested List) on `TemplateAttribute` / `InstanceAttributeOverride` and the flattened `ResolvedAttribute`. List values are stored and transmitted as a canonical JSON array via the `AttributeValueCodec` helper (scalars keep their historical invariant-culture string form); the `ElementDataType` is fixed by the defining level and cannot be changed on a derived template or instance override. +- **`DataType` enum**: Enumerates the data types supported by the system: Boolean, Int32, Float, Double, String, DateTime, Binary, and **List** (a homogeneous multi-value attribute). A `List` attribute carries a companion `ElementDataType` (one of the scalar types — String, Int32, Float, Double, Boolean, DateTime; not Binary, not nested List) on `TemplateAttribute` / `InstanceAttributeOverride` and the flattened `ResolvedAttribute`. List values are stored and transmitted as a canonical **native-typed** JSON array via the `AttributeValueCodec` helper — numbers and booleans unquoted, strings quoted, `DateTime` as ISO-8601 (e.g. `[10,20]`, `[true,false]`, `["2026-06-16T00:00:00Z"]`); scalars keep their historical invariant-culture string form. `AttributeValueCodec.Decode` is backward compatible: it reads both the native form and the earlier array-of-strings form (`["10","20"]`). Already-persisted old-form values are normalized to native on the fly — an idempotent central startup normalizer (`ListValueNormalizer`, run after migrations) rewrites MS SQL rows, the `InstanceActor` re-persists site SQLite overrides on load, and bundle import re-encodes List values. The `ElementDataType` is fixed by the defining level and cannot be changed on a derived template or instance override. - **`RetryPolicy`**: A record or immutable class describing retry behavior (max retries, fixed delay between retries). - **`Result`**: A discriminated result type that represents either a success value or an error, enabling consistent error handling across component boundaries without exceptions. - **`InstanceState` enum**: Enabled, Disabled.