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:
@@ -8,9 +8,11 @@ last_updated: 2026-08-11
|
||||
Each open question lives in its own file under [`questions/`](questions/),
|
||||
named `NNN-slug.md` (mirroring the ADR convention). This file is the index:
|
||||
theme-grouped tables for scannability, plus a cross-theme
|
||||
[Open](#open) section (active investigation targets) and a
|
||||
[Deferred / Blocked](#deferred--blocked) section that surfaces the
|
||||
safe-exit deferrals with their blocking conditions inline — so "what's
|
||||
currently parked and why" is answerable at a glance.
|
||||
currently on the architect's desk" and "what's currently parked and why"
|
||||
are each answerable at a glance.
|
||||
|
||||
**Status values**:
|
||||
- `open` — Needs to be resolved now. Has a clear path to resolution.
|
||||
@@ -60,6 +62,70 @@ Door type is separate from whether a decision is made. A two-way door is a decis
|
||||
| OQ | Title | Status | Door | Pri |
|
||||
|----|-------|--------|------|-----|
|
||||
| [OQ-003](questions/003-builder-api-for-schema-construction.md) | Builder API for Schema Construction | resolved (ADR-009) | two | med |
|
||||
| [OQ-004](questions/004-discriminator-field-name-type.md) | `Discriminator::Field` name — `&str` or `String` | open | two | low |
|
||||
| [OQ-006](questions/006-builder-spec-example-3-wrap-union.md) | Builder spec Example 3 — wrap `Union` in a `Struct` | open | two | low |
|
||||
|
||||
### Validation
|
||||
|
||||
| OQ | Title | Status | Door | Pri |
|
||||
|----|-------|--------|------|-----|
|
||||
| [OQ-005](questions/005-union-materialization-shape.md) | `Union` materialization shape — byte-offset vs field-name consistency | open | two | med |
|
||||
| [OQ-007](questions/007-bytes-materialization-lossy-utf8.md) | `Bytes` materialization — lossy UTF-8 conversion | open | one | med |
|
||||
|
||||
## Open
|
||||
|
||||
Active investigation targets — questions with a clear path to resolution
|
||||
that need to be worked through, not waited on. Each has a concrete
|
||||
investigation target. This section exists so "what's currently on the
|
||||
architect's desk" is answerable at a glance.
|
||||
|
||||
### OQ-004: `Discriminator::Field` name — `&str` or `String`
|
||||
|
||||
- **Investigation target**: Decide whether `Discriminator::Field { name }`
|
||||
should borrow (`&str`) or own (`String`). The builder consumes `Self`
|
||||
on setters, so `&str` would require a lifetime parameter on
|
||||
`Discriminator` (and transitively `Schema::union_`). Likely `String`
|
||||
for ownership simplicity.
|
||||
- **Priority**: low (doesn't block the chunk header POC; must be
|
||||
resolved before the SFTP Packet POC's field-name discriminator path)
|
||||
- **Full file**: [OQ-004](questions/004-discriminator-field-name-type.md)
|
||||
|
||||
### OQ-005: `Union` materialization shape — byte-offset vs field-name consistency
|
||||
|
||||
- **Investigation target**: The current `materialize_union_packed`
|
||||
returns inconsistent shapes for the two discriminator kinds (byte-
|
||||
offset produces `{ "__discriminator": <u32>, ...fields }`; field-name
|
||||
produces the struct fields directly). Decide on one consistent shape.
|
||||
Work through the SFTP Packet `validate_bytes` example to surface what
|
||||
the `jsonschema` validator needs to see for a `AlkType:Union` field.
|
||||
- **Priority**: medium (blocks the SFTP Packet `validate_bytes` POC,
|
||||
the natural next round)
|
||||
- **Full file**: [OQ-005](questions/005-union-materialization-shape.md)
|
||||
|
||||
### OQ-006: Builder spec Example 3 — wrap `Union` in a `Struct`
|
||||
|
||||
- **Investigation target**: Update builder.md Example 3 (SFTP Packet)
|
||||
to wrap the `Union` in a `Struct` — the engine requires
|
||||
`AlkType:Struct` at the top level (ADR-002), and the wrapped shape
|
||||
matches SFTP's actual wire format (`[length][type][payload]`). The
|
||||
POC already uses the wrapped shape; the spec example just hasn't
|
||||
been updated.
|
||||
- **Priority**: low (documentation fix; doesn't block any implementation)
|
||||
- **Full file**: [OQ-006](questions/006-builder-spec-example-3-wrap-union.md)
|
||||
|
||||
### OQ-007: `Bytes` materialization — lossy UTF-8 conversion
|
||||
|
||||
- **Investigation target**: The current materializer uses
|
||||
`String::from_utf8_lossy` for `AlkType:Bytes` fields, which corrupts
|
||||
non-UTF-8 bytes. Decide on a round-trippable form (base64 with a
|
||||
`format` constraint, or `Value::Array` of u8 with a validator that
|
||||
accepts arrays). Work through SFTP's binary `handle`/`data` fields
|
||||
to surface what `validate_bytes` callers actually need.
|
||||
- **Priority**: medium (blocks the SFTP use case for `validate_bytes`;
|
||||
does not block the chunk header or call input schema)
|
||||
- **Door type**: one-way (changing what the validator sees is a
|
||||
semantic break for consumers that depend on the shape)
|
||||
- **Full file**: [OQ-007](questions/007-bytes-materialization-lossy-utf8.md)
|
||||
|
||||
## Deferred / Blocked
|
||||
|
||||
|
||||
Reference in New Issue
Block a user