SpecBuilder Code Generation & AST Optimization Architecture

1. Executive Summary & Design Rationale

The ZQK SpecBuilder pipeline compiles declarative schema specifications (.zqk/specs/) into high-performance, strongly-typed Go builders, validators, and domain enumerations.

Early code generation architectures generated discrete micro-packages for every schema entity and status type (e.g. bldr_enum_v1/shared_agent_instructions, bldr_enum_v1/policies, bldr_enum_v1/roles). While conceptually decoupled, this granular strategy introduced severe compiler and runtime overhead:

1. Compiler Symbol Table Inflation: Hundreds of micro-packages saturated the Go compiler's package graph, resulting in excessive AST allocations, slow type-checking passes, and lengthened CI compilation times.
2. Epistemic Divergence: Having separate micro-packages for every status created dual sources of truth against canonical strings declared in pkg/objects.
3. Namespace Duplication: Divergent singular and plural packages emerged without clean boundary definitions.

To solve this, ZQK adopts a Consolidated Domain Architecture for generated enums, builders, and AST pruning, maintaining zero runtime overhead while enforcing strict compile-time type safety.

---

2. Domain Partitioning Architecture

Rather than generating an isolated package for every entity or schema kind, code generation groups enums into cohesive, domain-scoped packages under pkg/specbuilder/bldr_enum_v1/:

graph TD
    Specs[".zqk/specs/ Object & Lifecycle Metaschemas"] --> Generator["SpecBuilder Generator Pipeline"]
    Generator --> KernelDomain["pkg/specbuilder/bldr_enum_v1/domain_kernel"]
    Generator --> PlatformDomain["pkg/specbuilder/bldr_enum_v1/domain_platform"]
    Generator --> WorkDomain["pkg/specbuilder/bldr_enum_v1/domain_work"]

    KernelDomain --> KD1["Lifecycle Planes (Draft, Promoted)"]
    KernelDomain --> KD2["Priority Tiers (P0 - P3)"]
    KernelDomain --> KD3["Account & Session Lifecycles"]

    PlatformDomain --> PD1["Audit & Telemetry Statuses"]
    PlatformDomain --> PD2["Policy & Rule Governance"]
    PlatformDomain --> PD3["Scheduler Job States"]

Core Domain Groupings:

• domain_kernel: Houses core kernel lifecycle, state, priority, and session enums:

• PlaneDraft, PlanePromoted

• PriorityTierP0 through PriorityTierP3
• AccountStatusActive, AccountStatusSuspended
• SessionStatusActive, SessionStatusArchived, SessionStatusCompleted

• domain_platform: Houses platform operational, governance, and audit enums:

• AuditStatusActive, AuditStatusArchived

• PolicyStatusActive, PolicyStatusInactive
• RuleStatusImplemented, RuleStatusDraft
• SchedulerJobStatusActive, SchedulerJobStatusPending

Each domain package exports strongly-typed enums backed by primitive Go types (string), annotated with serialization helpers and validated against canonical definitions in pkg/objects.

---

3. AST Pruning & Architectural Guardrails

To prevent package bloat from recurring, automated verification in pkg/testkit/enum_consolidation_test.go enforces structural ceilings on generated packages:

// Enforces a strict ceiling on bldr_enum_v1 directory count.
func TestEnumConsolidation_DirectoryCount_StaticFloor(t *testing.T) {
    ...
    assert.LessOrEqual(t, dirCount, 140, "bldr_enum_v1 package count must not exceed static ceiling")
}

Fail-Closed Validation Invariant

All domain enums implement fail-closed boundary checking. Any unmapped or unrecognized status string coerced to a domain enum type is rejected by validation assertions, preventing silent data corruption across subsystem boundaries:

func TestEnumConsolidation_InvalidEnumRejection_NegativeBoundary(t *testing.T) {
    ...
    for _, invalid := range invalidStatuses {
        coerced := domain_kernel.ZqkSessionStatus(invalid)
        assert.False(t, validSessionStatuses[coerced], "invalid status %q must be rejected by domain enum validator", invalid)
    }
}

---

4. Migration & Evolution Principles

1. Cohesive Domain Boundaries: New schema enums must be mapped into their existing domain package (domain_kernel, domain_platform, or domain-specific packs) rather than creating new standalone micro-packages.
2. Canonical Correspondence: All enum string literals must correspond 1:1 with lifecycle definitions in .zqk/specs/lifecycles/ and object metaschemas in .zqk/specs/objects/.
3. Continuous AST Compaction: Builders and enum sets must be verified against make lint and zqk-vet to prevent code duplication or unnecessary symbol exports.