Hecate EPU Persistence Golden-Path Reference

1. Purpose

HNC-1.2-G establishes the first deterministic end-to-end reference proving that Hecate can move from a canonical product-identity requirement to a complete, governed implementation-impact boundary without inventing physical architecture.

The reference uses EPU ExternalAlias persistence because the EPU architecture requires aliases to remain separate from canonical EPU identity while supporting source/issuer scope, effective dating, authority, provenance, conflict detection and resolution.

The golden path proves more than schema validity. It proves that a canonical requirement can generate a complete ArtifactImpactPlan, bind the concrete persistence and migration contracts into the EngineeringWorkOrder, strengthen validation/evidence requirements automatically, and still preserve the human approval boundary.

2. Canonical chain

Human Need
    ↓
ZAYAZ Docs — governed EPU ExternalAlias semantics
    ↓
HNC v1.1 canonical resolution
    ├── ImplementationPacket
    ├── ValidationPlan
    └── AgentContextPack
    ↓
HNC v1.2 Artifact Impact Resolver
    ├── ArtifactImpactPlan
    ├── PersistenceChange
    ├── MigrationPlan
    ├── RulesetImpact
    └── InfrastructureImpact
    ↓
Jira governed projection
    ↓
EngineeringWorkOrder — v1.2-impact-bound
    ↓
AI engineering boundary
    ↓
ImplementationEvidence
    ↓
Deterministic evidence assessment
    ↓
IMPLEMENTATION_READY_FOR_REVIEW
    ↓
Human completion approval remains required

3. Reference architecture

The underlying EPU architecture defines ExternalAlias as a governed mapping between external/source identifiers and EPU identity. It does not make the alias itself an EPU and it does not prescribe one physical database topology.

The machine-readable HNC reference therefore requires the following logical behavior:

• durable ExternalAlias persistence;
• source/authority-scoped uniqueness semantics;
• effective-dated history;
• provenance-bearing fields;
• referential integrity to EPU identity;
• tenant isolation and product-identity access policy;
• governed conflict handling;
• deployable migration capability;
• indexed identity resolution;
• implementation freedom for physical storage decomposition.

This preserves the constitutional rule:

Conceptual objects do not automatically imply physical tables.

Hecate derives required semantics and capabilities. The authorized engineering layer chooses the physical implementation within canonical platform policy.

4. Golden-path invariants

4.1 Need to canonical source

The reference must prove that:

• one Need identity is preserved;
• the exact canonical source document and section are bound;
• the current canonical Git commit is bound;
• the resolved source scope carries a SHA-256 hash;
• no implementation architecture is inferred outside the selected governed scope.

4.2 Canonical source to artifact impact

The Impact Resolver must derive exactly the governed reference impact set:

• one PersistenceChange for ExternalAlias;
• one required MigrationPlan;
• one governed alias-conflict RulesetImpact;
• one required persistence InfrastructureImpact capability;
• security impact for tenant/source-authority isolation;
• no unresolved impact.

The persistence contract must preserve effective dating and require tenant/security policy. The migration must reference the exact persistence change and remain non-destructive for this reference case.

4.3 Artifact impact to engineering authority

The EngineeringWorkOrder must be emitted in:

v1.2-impact-bound

mode and must bind:

• exact ArtifactImpactPlan identity;
• deterministic plan hash;
• required implementation artifact references;
• exact persistence-contract identity and hash;
• exact migration-contract identity and hash;
• exact ruleset-impact identity and hash;
• exact infrastructure-impact identity and hash;
• required evidence types;
• the prohibition on unresolved impacts.

An engineering agent must therefore be unable to receive a work order that silently omits a required migration or other governed concrete impact contract.

4.4 Validation strengthening

The v1.2 impact layer is allowed to strengthen, but never silently weaken, the v1.1 ValidationPlan.

For this reference, the final engineering gate set must contain all base gates plus the derived gates required by the artifact impacts, including:

MIGRATION_VALIDATION
SECURITY_VALIDATION
REGISTRY_VALIDATION
INFRASTRUCTURE_VALIDATION

The corresponding evidence requirements include migration, security, registry/validation and infrastructure evidence.

4.5 Evidence and human boundary

A successful simulated implementation evidence envelope must produce:

status: implementation_ready_for_review
machine_validation_passed: true
human_completion_approval_required: true
completion_declared: false

HNC therefore proves machine-verifiable implementation readiness without allowing the AI or validation layer to self-declare governed completion.

5. Negative-path requirements

The reference must fail closed when architecture-to-engineering lineage is incomplete.

At minimum:

1. omitting the required MigrationPlan from the engineering handoff must reject work-order creation;
2. introducing a blocking UNRESOLVED architecture impact must reject work-order creation before AI engineering begins.

These are architecture-boundary failures, not implementation warnings.

6. Executable reference

The deterministic executable test is:

tools/viroway-tools/tests/test_hnc_epu_persistence_golden_path.py

The test uses the real canonical HNC impact reference and current checked-out Git commit. Jira is represented through the deterministic Jira projection contract; implementation and CI remain schema-valid evidence envelopes so the test does not depend on external credentials or mutable infrastructure.

7. What HNC-1.2-G proves

A green reference demonstrates the governed chain:

canonical requirement
    ↓
resolved implementation intent
    ↓
concrete artifact impact
    ↓
engineering output contract
    ↓
validation/evidence obligations
    ↓
review readiness

It specifically proves that persistence and migration are no longer informal implementation assumptions. They are traceable governed artifacts between canonical architecture and engineering execution.

8. What remains outside the deterministic golden path

This reference does not claim live deployment. The following remain staging/runtime concerns:

• actual database migration execution in zayaz-platform;
• actual persistence technology selection under platform policy;
• live tenant-isolation verification;
• real GitHub Actions evidence capture;
• AWS infrastructure deployment;
• runtime telemetry and requirements-to-runtime correlation.

Those belong to HNC-1.2-H and subsequent operational/runtime governance work.

9. Acceptance state

HNC-1.2-G is test-validated only when the complete viroway-tools suite passes with the EPU persistence golden-path tests included.

The reference must never weaken these constitutional invariants:

Architecture defines required behavior. Hecate derives implementation impact. AI implements the authorized impact. Machines verify conformance. Humans approve governed boundaries and release.