Architecture & Foundation
Docs » Architecture & Foundation » Synthetic Constant Eradication & Code Readability Governance
Raw .md

Synthetic Constant Eradication & Code Readability Governance

Overview

This architecture document defines governance policies, invariant rules, and enforcement mechanisms against synthetic, auto-generated pseudo-constants (e.g., ConstMagic[0-9a-fA-F]{8}) across the ZQK codebase, resolving Technical Debt TDE-F-CQ-002.

Background & Problem Statement

Prior to this specification, automated refactoring and constant extraction tools populated over 3,500 synthetic pseudo-constants (such as ConstMagic437c4f93, ConstMagic129864b4, ConstMagicExtracted_*) across validation, storage, and CLI packages.

This mechanical indirection introduced severe architectural and maintainability detriments:

  1. Semantic Obfuscation: Constants with non-descriptive hash suffixes obscured the meaning and intent of error messages, regex patterns, and string literals.
  2. Impaired Grepability and Navigability: Developers and static analyzers could not grep for user-visible error strings, log formats, or enum values directly in the source code.
  3. AST Bloat and Compiler Overhead: 900+ line artificial constant tables (constants_internal.go, constants_internal_messages.go) inflated package graphs without providing abstraction benefits or multi-site reuse.
  4. False Abstraction: Single-use formatting strings and test assertion descriptions were separated from their call sites, harming local readability.

Architectural Governance: Inlining & Naming Policies

1. Inlining of Single-Use Literals

Single-use error messages, test failure descriptions, log format strings, and local regex patterns must remain as readable inline string literals or contextual format strings at their respective call sites.

2. Strict Criteria for Named Constants

Named constants are strictly reserved for:

  • Domain Enumerations: Defined status strings, kind names, and category values (e.g., pkg/objects, pkg/kindnames).
  • Standard Protocol Headers & Keys: HTTP headers, IPC message types, and metadata attributes.
  • Shared Configuration Keys: Configuration property names shared across multiple distinct subsystems.

Every named constant must have a clear, descriptive, and human-readable identifier conveying its domain purpose (e.g., MetricNameAsyncValidator, ErrMsgCreateCacheDir).

3. Absolute Prohibition of Opaque Identifiers

Identifiers matching the following synthetic patterns are strictly prohibited from entering the repository:

  • ConstMagic*
  • ConstMagicExtracted_*
  • Any variable, constant, or function name containing mechanical MD5/SHA hash segments or opaque hex fingerprints.

Automated Verification & Enforcement

The repository enforces synthetic constant eradication through a Three-Fold Proof:

  1. Static Floor (TestConstMagicEradication_StaticFloor): Scans all source and test files across the subsystem to assert zero occurrences of ConstMagic identifiers.
  2. Operational Proof (TestConstMagicEradication_OperationalProof): Validates that all inlined literals function correctly in runtime validation, diagnostics, and test suites.
  3. Negative Boundary (TestConstMagicEradication_NegativeBoundary & ASTAuditor): The AST structural auditor (pkg/validation/qa/ast_audit.go) inspects constant declarations and flags any synthetic pseudo-constant as a blocking code_quality_debt violation.