Centralize scattered OQs into the tracker (OQ-004 through OQ-007)
Four open questions were scattered inline in builder.md and the POC findings doc. Moved them into the central OQ tracker under docs/architecture/questions/ and updated the index: - OQ-004: Discriminator::Field name type (&str vs String) — raised in builder.md during ADR-009 spec drafting - OQ-005: Union materialization shape (byte-offset vs field-name consistency) — raised in the POC findings - OQ-006: Builder spec Example 3 wrap Union in Struct — raised in the POC findings (doc fix; engine requires AlkType:Struct at top level) - OQ-007: Bytes materialization lossy UTF-8 — raised in the POC findings (blocks SFTP use case for validate_bytes) Index updates: - open-questions.md: new 'Schema Construction' and 'Validation' theme groups; new 'Open' section for active investigation targets (distinct from 'Deferred / Blocked' which holds scope-parked OQs) - README.md: OQ table extended with OQ-004 through OQ-007 - builder.md: inline OQ-004 replaced with a tracker reference - findings.md: inline OQ-005/006/007 replaced with tracker references Doc-only change; 369 tests pass.
This commit is contained in:
@@ -109,7 +109,8 @@ Either:
|
||||
- Document the constraint explicitly ("the engine requires a top-level
|
||||
`AlkType:Struct`; a `Union` is a field type within a struct").
|
||||
|
||||
This is a documentation fix, not an implementation change.
|
||||
This is a documentation fix, not an implementation change. Tracked as
|
||||
[OQ-006](../../../architecture/questions/006-builder-spec-example-3-wrap-union.md).
|
||||
|
||||
### 2. Builder field order is preserved as required
|
||||
|
||||
@@ -200,13 +201,16 @@ validator for JSON-only schemas".
|
||||
fields including the discriminator. The byte-offset discriminator
|
||||
pattern returns a `__discriminator`-tagged object. This asymmetry
|
||||
needs resolution before shipping (likely both should return the same
|
||||
shape — see Open Questions).
|
||||
shape — tracked as
|
||||
[OQ-005](../../../architecture/questions/005-union-materialization-shape.md)).
|
||||
3. **`Bytes` materialization** uses `String::from_utf8_lossy` to convert
|
||||
raw bytes to a JSON string (the validator expects a string for
|
||||
`AlkType:Bytes` — see schema-layer.md §TBytes). This is lossy for
|
||||
non-UTF-8 bytes; strict byte-preserving validation would need a
|
||||
different validator form. For the chunk header (no `Bytes` fields),
|
||||
this doesn't matter, but it's a follow-up for the SFTP use case.
|
||||
this doesn't matter, but it's a follow-up for the SFTP use case
|
||||
(tracked as
|
||||
[OQ-007](../../../architecture/questions/007-bytes-materialization-lossy-utf8.md)).
|
||||
4. **`encoding` setter** in the builder only handles the
|
||||
`OffsetIndirect` case (rewriting the boolean-true form to the object
|
||||
form with the `encoding` annotation). The `LengthPrefixed` case is
|
||||
@@ -217,19 +221,33 @@ validator for JSON-only schemas".
|
||||
|
||||
## Open Questions surfaced
|
||||
|
||||
- **OQ-005** (new): Should `Union` materialization return a consistent
|
||||
shape for byte-offset and field-name discriminators? The POC's byte-
|
||||
offset path returns `{ "__discriminator": <u32>, ...variant-fields }`;
|
||||
the field-name path returns the struct fields directly (the
|
||||
discriminator is just another field). For `validate_bytes` callers,
|
||||
the shape matters for how the validator dispatches. Resolve before
|
||||
shipping the next POC round (SFTP Packet `validate_bytes`).
|
||||
- **OQ-006** (new): Should the builder spec's Example 3 (SFTP Packet)
|
||||
wrap the `Union` in a `Struct`? Finding #1 above. Documentation fix,
|
||||
not implementation.
|
||||
- **OQ-007** (new): `Bytes` materialization — lossy UTF-8 conversion
|
||||
vs. a stricter byte-preserving validation form. Affects the SFTP use
|
||||
case (binary `handle` and `data` fields).
|
||||
Three new open questions raised during the POC, now tracked in the
|
||||
central OQ tracker ([open-questions.md](../../../architecture/open-questions.md)):
|
||||
|
||||
- **OQ-004** (open, low): `Discriminator::Field` name type — `&str` or
|
||||
`String`? Raised in [builder.md](../../../architecture/builder.md)
|
||||
§"Open Questions" during ADR-009 spec drafting. Doesn't block the
|
||||
chunk header POC; must be resolved before the SFTP Packet POC's
|
||||
field-name discriminator path. Full file:
|
||||
[OQ-004](../../../architecture/questions/004-discriminator-field-name-type.md).
|
||||
- **OQ-005** (open, medium): `Union` materialization shape —
|
||||
consistency between byte-offset and field-name discriminators.
|
||||
The POC's `materialize_union_packed` returns inconsistent shapes
|
||||
for the two kinds. Blocks the SFTP Packet `validate_bytes` POC (the
|
||||
natural next round). Full file:
|
||||
[OQ-005](../../../architecture/questions/005-union-materialization-shape.md).
|
||||
- **OQ-006** (open, low): Builder spec Example 3 — wrap the `Union`
|
||||
in a `Struct`. The spec example shows a top-level `Schema::union_(...)`
|
||||
which won't compile (`AlkTypeEngine::compile` requires
|
||||
`AlkType:Struct` at the top level — Finding #1 above). Documentation
|
||||
fix. Full file:
|
||||
[OQ-006](../../../architecture/questions/006-builder-spec-example-3-wrap-union.md).
|
||||
- **OQ-007** (open, medium, one-way door): `Bytes` materialization —
|
||||
lossy UTF-8 conversion. The current materializer uses
|
||||
`String::from_utf8_lossy`, which corrupts non-UTF-8 bytes. Blocks
|
||||
the SFTP use case for `validate_bytes` (binary `handle`/`data`
|
||||
fields). Full file:
|
||||
[OQ-007](../../../architecture/questions/007-bytes-materialization-lossy-utf8.md).
|
||||
|
||||
## Recommendation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user