GenesisCode .gc Module Boundaries v0.1

This document defines maintainability boundaries for source-of-truth .gc modules used by AI agents.

Scope

Applies to:

• all .gc paths resolved from policy gc_source_roots (directories scanned recursively):
  • prelude/modules
  • selfhost
  • prelude/prelude.gc

Generated artifacts are excluded:

• policy allowlist gc_generated_exclude_paths (currently prelude/prelude.gc)

Notes:

• selfhost/toolchain.gc remains a generated assembly artifact, but is now emitted in compact CoreForm form and stays within enforced .gc line budgets (no policy carve-out).
• gc_prelude bootstrap now assembles embedded prelude source from prelude/modules/manifest.toml at build time; runtime no longer consumes prelude/prelude.gc as its source of truth.

Boundary Rules

• Keep modules domain-focused and composable:
  • prelude/modules/00_* for core data/effect/protocol helpers
  • prelude/modules/10_* for gfx/compute wrappers and runtime traces
  • prelude/modules/20_* for editor/tasking surfaces
    • split into focused units (host-ops, vcs, ast, plugin, action orchestration) to avoid monolithic editor modules
  • prelude/modules/30_* for reusable high-level domain kits (service orchestration, data pipelines, network workflows, game-loop scaffolding, XR runtime orchestration, media asset pipelines)
  • selfhost/cli_* for CLI/runtime orchestration
  • selfhost/{parse,canon,printer,hash} for frontend core
  • selfhost/stage1_* and patch schema modules for optimization/rewrites
• Prefer adding a new module over extending an existing module past budget.
• Expose stable, small top-level entrypoints and keep helper internals local to each module.

Budget Enforcement

.gc source budgets are enforced by:

• scripts/check_gc_source_size_budget.sh
• policy file: policies/source_size_budget.toml

Current policy tracks:

• gc_max_lines
• gc_target_lines
• generated-artifact exclusions
• explicit target-debt allowlist (gc_target_exclude_paths)

For high-churn Rust files still above decomposition target, policy now requires explicit closure-plan rows in tracked_over_budget_rows (in policies/source_decomposition_progress.toml) with:

• module_path
• target_gc_modules
• parity_gate
• phase
• status
• optional notes
• required waiver metadata when status = "waived":
  • waiver_owner
  • waiver_scope (bounded ownership surface)
  • waiver_rationale
  • waiver_review_by (YYYY-MM-DD, must not precede the gate review date)

scripts/check_source_decomposition_progress.sh fails closed when any over-budget production file is neither decomposed nor represented by one of these explicit closure-plan rows. The check renders only to a private temporary path; use scripts/update_source_decomposition_progress_report.sh when a retained local E0 report is required.

scripts/check_source_decomposition_tracked_parity.sh executes every reviewed parity command and rejects expired waivers using the UTC review date. Override GENESIS_SOURCE_DECOMPOSITION_REVIEW_DATE only for deterministic historical replay. Retained command diagnostics canonicalize workspace, temporary, home, and platform drive roots so the E0 report does not disclose or depend on the producing host’s absolute paths. Retain the parity observation only with scripts/update_source_decomposition_tracked_parity_report.sh.

AI-First Rationale

• Smaller, domain-scoped modules improve agent planning and reduce edit conflicts.
• Stable boundaries reduce prompt context size and increase rewrite reliability.
• Budget gates prevent silent drift into monolithic files that are hard for both agents and humans to maintain.

Selfhost Migration Plan (High-Churn Rust -> GC)

Goal: track the presence and integration maturity of GC-authored routes beside high-churn Rust modules. This table is a decomposition plan, not semantic-ownership evidence. Only docs/spec/SEMANTIC_OWNERSHIP_LEDGER_v0.1.json may report H-levels or production authority.

Phase model:

• phase-0: extraction target is proposed; no route or parity claim exists.
• phase-1: target GC module and shared contract are present with a named parity gate.
• phase-2: a callable GC route or integration point is present and exercised by the named gate; Rust authority may remain fully reachable.
• phase-3: route/decomposition and parity surfaces are expanded enough to begin an authority-switch task; this phase still does not claim H1, H2, fallback removal, or Rust demotion.

route-present means only that the phase-specific integration evidence above is present. It must never be rendered or interpreted as “migrated,” self-hosted, production-authoritative, or bootstrapped.

Rust module	Target GC module(s)	Parity evidence gate	Phase	Status
crates/gc_cli_driver/src/cmd_selfhost.rs	selfhost/toolchain.gc, selfhost/toolchain_manifest.gc	bash scripts/check_selfhost_readiness_scorecard.sh	phase-2	route-present
crates/gc_cli_driver/src/pkg_workspace_ops.rs	prelude/modules/31_data_pipeline.gc	bash scripts/check_agent_reference_workflows.sh	phase-2	route-present
crates/gc_obligations/src/obligation_exec.rs	prelude/modules/30_service_orchestration.gc, prelude/modules/31_data_pipeline.gc	bash scripts/check_agent_generative_workloads.sh	phase-3	route-present
crates/gc_gfx/src/lib.rs	prelude/modules/33_game_loop.gc, prelude/modules/34_xr_workflow.gc	bash scripts/check_gfx_runtime_profile.sh	phase-2	route-present
crates/gc_prelude/src/prelude.rs	prelude/modules/manifest.toml	bash scripts/check_prelude_capability_coverage.sh	phase-2	route-present
crates/gc_types/src/infer.rs	prelude/modules/36_semantic_workspace.gc, selfhost/toolchain.gc	cargo test -p gc_types --lib --quiet	phase-3	route-present
crates/gc_cli_driver/src/semantic_workspace.rs	prelude/modules/36_semantic_workspace.gc, prelude/modules/32_network_workflow.gc	bash scripts/check_agent_reference_workflows.sh	phase-3	route-present
crates/gc_patches/src/lib.rs	prelude/modules/32_network_workflow.gc	bash scripts/check_task_concurrency_stress.sh	phase-3	route-present
crates/gc_types/src/lib.rs	prelude/modules/36_semantic_workspace.gc, selfhost/toolchain.gc	bash scripts/check_write_genesiscode_skill_conformance.sh	phase-3	route-present
crates/gc_kernel/src/eval.rs	selfhost/toolchain.gc, prelude/modules/00_core_media.gc	bash scripts/check_kernel_tcb_contract.sh	phase-3	route-present
crates/gc_cli_driver/src/cmd_vcs.rs	prelude/modules/32_network_workflow.gc	bash scripts/check_vcs_selfhost_contract.sh	phase-3	route-present
crates/gc_effects/src/runner_host_bridge.rs	prelude/modules/10_browser_host.gc, prelude/modules/10_xr_host.gc	bash scripts/check_host_bridge_fault_injection.sh	phase-2	route-present
crates/gc_registry/src/registry/client_impl/ping_and_store.rs	prelude/modules/32_network_workflow.gc	cargo test -p gc_registry --quiet	phase-2	route-present
crates/gc_vcs/src/policy.rs	prelude/modules/32_network_workflow.gc	cargo test -p gc_vcs --quiet	phase-3	route-present
crates/gc_opt/src/stage2_wasm/collections_lowering.rs	selfhost/toolchain.gc, prelude/modules/31_data_pipeline.gc	cargo test -p gc_opt --lib --quiet	phase-2	route-present
crates/gc_effects/src/runner_xr_host/advanced.rs	prelude/modules/10_xr_host.gc, prelude/modules/34_xr_workflow.gc	cargo test -p gc_effects --lib --quiet	phase-2	route-present
crates/gc_effects/src/runner_capability_dispatch/net.rs	prelude/modules/32_network_workflow.gc, prelude/modules/10_browser_host.gc	cargo test -p gc_effects --lib --quiet	phase-2	route-present
crates/gc_patches/src/patch_apply.rs	prelude/modules/36_semantic_workspace.gc, prelude/modules/31_data_pipeline.gc	cargo test -p gc_patches --quiet	phase-2	route-present
crates/gc_kernel/src/compiled.rs	selfhost/toolchain.gc, prelude/modules/00_core_media.gc	cargo test -p gc_kernel --quiet	phase-2	route-present
crates/gc_cli_driver/src/pkg_assurance_ops.rs	prelude/modules/31_data_pipeline.gc, prelude/modules/36_semantic_workspace.gc	cargo test -p gc_cli_driver --quiet	phase-2	route-present

Exit criteria:

1. Target GC module path and callable route/integration point exist.
2. The named parity/decomposition gate validates the row’s declared phase.
3. The row uses route-present; no H-level or Rust-authority conclusion is inferred.
4. Any later production-authority or fallback change is recorded first in the exact semantic-ownership ledger under its R4.2 task.
5. policies/source_decomposition_progress.toml is updated in the same change.