alkgen/docs/architecture/open-questions.md

status, last_updated

status	last_updated
reviewed	2026-11-06

alkgen Architecture: Open Questions

Centralized tracker. Phase-0 questions carried forward note their legacy IDs (OQ-GN-NN in docs/research/phase-0.md) so traceability survives the renumbering. Spec documents reference OQs by number.

Status taxonomy: open marks a question that is decidable now and resolves when its owning spec or decision is written (typically a phase-1/branch-detail artifact). deferred(scope) marks one waiting on an external condition (a consumer, a crate spec); each follows the two-half convention from docs/sdd_process.md, naming its unblocking condition here and pairing with an external-trigger tracker task under tasks/architecture/. Re-triage between the two statuses is an architect action, not a default.

Theme: Emit (code branches)

OQ-01: File partitioning policy for posture-A artifacts

• Origin: emit.md (phase-0 OQ-GN-01 residue)
• Status: deferred(scope)
• Door type: two-way
• Priority: low
• Impacts: blocks only the branch-1 detailed spec's file-layout section; nothing in v1, since bast-rust-codecs activation is queued behind ssr-html and wgsl-jit (2026-11-06 consumer steer).
• Blocked on: bast-rust-codecs activation (branch-1 detailed spec being written) together with the alkcall channels consumer's integration story: source tree, OUT_DIR, or both (tracker task architecture/oq-01-file-partitioning).
• Resolution: Not yet decidable, and deliberately per-target. Emit policy is not core policy (ADR-001): the core renders text and never touches the filesystem (ADR-003, wasm-clean; convention 4), so file layout is a template-set plus emit-layer decision made with its consumer. Recorded analysis inputs from the 2026-11-06 session, for whoever picks this up: emit.md already fixes the output unit ("one document produces one or more self-contained modules"); the reader POC emitted one file per render with trivial consumer inclusion; and generated reader/writer/validator share type definitions, which favors co-location or a per-document shared types module. Note that hand-editable targets (call-handlers, per OQ-04 and the 2026-11-06 consumer steer) may want a different layout than check-in BAST codecs, so a posture-A-wide rule is likely wrong.
• Cross-references: OQ-02, OQ-03, emit.md posture A, ADR-001, ADR-003, ADR-007

OQ-02: Regeneration posture for posture-A artifacts

• Origin: emit.md (phase-0 OQ-GN-01 residue)
• Status: deferred(scope)
• Door type: two-way
• Priority: low
• Impacts: blocks nothing active; the final shape of OQ-01's answer (regen follows partitioning), plus the consumer hand-edit story for hand-editable targets.
• Blocked on: bast-rust-codecs activation, same as OQ-01; decided with the consumer's regeneration workflow (tracker task architecture/oq-02-regen-posture).
• Resolution: Not yet decidable, per-target by design. Wholesale overwrite is the presumed landing for bast-rust-codecs: deterministic rendering (ADR-003) makes it diff-quiet, and the DO-NOT-EDIT banner forbids the hand-editing that would motivate partial regeneration (AGENTS.md convention 8). The 2026-11-06 consumer steer named the counter-case: OpenAPI-derived handler code (OQ-04's target) may be hand-edited or completed by consumers, which wholesale overwrite would destroy on regen; such targets likely need generate-once or a hooks pattern, decided per target with its own ADR at activation.
• Cross-references: OQ-01, OQ-04, ADR-003, emit.md posture A

Theme: Generated validation

OQ-03: Full BAST validation strategy for generated validators

• Origin: targets.md (phase-0 OQ-GN-07; reader POC follow-up 5)
• Status: deferred(scope)
• Door type: two-way
• Priority: medium
• Impacts: blocks the branch-1 validator template arm set and, further out, the call-handlers validation story; nothing in v1.
• Blocked on: bast-rust-codecs activation (branch-1 detailed spec) deciding this target's answer; call-handlers activation (OQ-04) for the OpenAPI-derived answer (tracker task architecture/oq-03-validation-strategy).
• Resolution: Not yet decidable, per-target by design. Materially informed twice (2026-09-08 POC; 2026-11-06 re-validation and consumer steer). For bast-rust-codecs specifically, ADR-007's zero-dependency contract already rules out external validator dependencies, and typed direct decode structurally enforces most of alktype's ValidationPlan arms (ValidNode in alktype/src/validation_plan.rs): integer range checks are the Rust types' own domains, enum and union dispatch bounds are decode-time errors, and array count equality plus Str/Bytes max_len caps are decode-time errors per reader POC finding F-2. The residual value-domain checks (float finiteness, which raw bytes can violate, with a mirror check on the encode side for in-memory values) would be native template-generated code under the parity discipline, never a jsonschema dependency. That answer is target-local: OpenAPI-derived handler targets may genuinely need jsonschema, so validation strategy cannot be a posture-A-wide or core rule.
• Cross-references: targets.md bast-rust-codecs, ADR-007, OQ-04

Theme: bast-rust-codecs detail

OQ-09: plan-to-context projection, generated-error shape, writer survey

• Origin: targets.md (bast-rust-codecs remaining phase-1 residue, consolidated from inline items 2026-11-06)
• Status: deferred(scope)
• Door type: two-way
• Priority: medium
• Impacts: blocks only the branch-1 detailed spec when its target activates: the exact plan-to-context projection (which alktype plan structures become which context shapes), the concrete shape of the generated code's error type (ADR-007 fixes the constraints: error-returning end to end, zero dependencies; the concrete per-arm error taxonomy is the residue), and the writer-side plan survey. Nothing in v1, since bast-rust-codecs activation is queued behind ssr-html and wgsl-jit (2026-11-06 consumer steer).
• Blocked on: bast-rust-codecs activation (branch-1 detailed spec being written), which needs the alkcall channels consumer's integration story; same trigger as OQ-01 (tracker task architecture/oq-09-bast-codec-spec-residue).
• Resolution: Not yet decidable, per ADR-001 (emit and projection policy is per-target, not core policy); the content is consumer-readable only from the branch-1 detailed spec session, with the reader POC's parity findings (F-1, F-2, F-6) as the recorded analysis inputs.
• Cross-references: targets.md bast-rust-codecs, ADR-001, ADR-004, ADR-007, OQ-01, OQ-03

Theme: Future targets

OQ-04: call-handlers template set scope

• Origin: targets.md (phase-0 branch 2)
• Status: deferred(scope)
• Door type: two-way
• Priority: medium
• Impacts: blocks nothing currently active; the branch-2 consumers arrive after branch 1. Adds a template set and possibly an input path (JSON Schema/OpenAPI) beyond BAST when it activates.
• Blocked on: branch-1 convergence plus a concrete consumer ask naming the protocol surfaces to generate (tracker task architecture/oq-04-call-handlers-scope).
• Resolution: Not yet decidable. The adapter precedent (alkhttp/src/adapters) frames the shape; no concrete protocol use cases exist to design against.
• Cross-references: targets.md call-handlers, ADR-001, ADR-009

OQ-05: wgsl template set requirements

• Origin: targets.md (phase-0 branch 3; alkjs codegen need)
• Status: deferred(scope)
• Door type: two-way
• Priority: high
• Impacts: blocks only the wgsl template set itself (shader inventory, context shape, feature name); the alkjs GPU end builds on the existing alkgen core, so nothing the core needs is deferred here. Second in the activation queue per the 2026-11-06 consumer steer (ssr-html, then wgsl-jit).
• Blocked on: alkjs's GPU-layer work naming the shaders, parameters, and compile-cache shape it needs (tracker task architecture/oq-05-wgsl-requirements). alkgen does not wait on this: the sequencing runs alkgen v1 (needed by alkforge now, in scope) before alkjs, never the reverse.
• Resolution: Not yet decidable, but honestly narrowed. Ownership is decided now by applying ADR-008 to a third code target: the wgsl template set is engine-owned and ships in alkgen, feature-gated (ADR-009), consumed through posture C's render-then-compile feed. What remains is the consumer-readable content, read from alkjs's GPU-layer work when it starts. The earlier blocked-on (an alkjs crate spec arriving first) was circularly framed: alkjs's GPU end cannot exist until alkgen does, so its requirements emerge from building on the core, not before it. alkminer-v1's ShaderBuilder remains the structural precedent.
• Cross-references: targets.md wgsl-jit, emit.md posture C, ADR-002, ADR-003, ADR-008, ADR-009, OQ-06

OQ-06: template-JIT core requirements

• Origin: targets.md (phase-0 branch 3, JIT core)
• Status: deferred(scope)
• Door type: two-way
• Priority: low
• Impacts: blocks the render-then-compile cache concept (branch 3) only. Everything v1 needed from it is already decided and built in: first-class partials, pure sync deterministic rendering (ADR-002, ADR-003), wasm-clean (ADR-003).
• Blocked on: concrete alkjs runtime integration (wgpu pipeline caching needs) plus a measured motivation that the v1 render-entry-point shape obstructs JIT use (tracker task architecture/oq-06-jit-core-requirements). The sequencing runs one way: alkgen v1 lands first (in scope for alkforge), and alkjs's runtime integrates on top of it, so this is a downstream integration question, never a blocker on the core.
• Resolution: Not yet decidable. v1's posture is designed so that no retroactive core change is expected (first-class partials, pure sync deterministic rendering, ADR-002 and ADR-003); the OQ exists to keep the shape falsifiable against real wgpu caching needs, not to gate anything.
• Cross-references: targets.md wgsl-jit, emit.md posture C, ADR-002, ADR-003

Theme: Shared core

OQ-07: Generic HTML layout primitives in alkgen

• Origin: emit.md posture B, targets.md ssr-html
• Status: deferred(scope)
• Door type: two-way
• Priority: low
• Impacts: blocks nothing in v1; only relevant if a demonstrated shared need emerges across SSR consumers.
• Blocked on: alkforge's SSR experience demonstrating a concrete shared need for engine-owned layout primitives (tracker task architecture/oq-07-html-primitives).
• Resolution: Not yet decidable. ADR-008 puts all page templates in the consumer; whether a shared need for alkgen-owned generic primitives (base layouts, form partials) exists is exactly what the consumer experience would show. If it arrives, alkforge files it upstream (family ADR-002 no-deformation rule) and the decision becomes an ADR plus a new engine-owned feature.
• Cross-references: targets.md ssr-html, ADR-006, ADR-008

OQ-08: Target-language scope for v1 template sets

• Origin: phase-0 OQ-GN-04; dispositioned by adoption in Phase 1
• Status: resolved (2026-11-06, by Phase-1 adoption)
• Priority: n/a (resolved)
• Resolution: The core is target-language-agnostic by construction (ADR-001, ADR-004: contexts are language-neutral, kind mapping lives in builders), and v1 template sets are written per consumer need with no second-language template work speculatively: ssr-html (HTML) first, bast-rust-codecs (Rust) second, wgsl-jit deferred (OQ-05). The SSR branch arriving with no core change is the hunch's predicted data point. Revisiting costs are low while ADR-004 holds.
• Cross-references: ADR-001, ADR-004, OQ-05