aios/docs/implementation-baseline-1.1/RELEASE_LINEAGE_REPORT.md

Release and Lineage Implementation Report

Delivered authority boundaries

aios_baseline.lineage.LineageLedger is a SQLite relationship authority. It does not own Task or Job state. Its constructor requires Task and Job authorities, and every link_task resolves the real Task before writing. The returned Task must carry the requested tenant and subject in its issuer or baseline metadata; mission, component, and Grant metadata must also match. Every link_effect resolves the durable Job and verifies its tenant, subject, mission, Grant, Task, and effect binding before recording the relationship.

Opaque Task, effect, Job, Release, deployment, and acceptance IDs are unique within a tenant. The same opaque ID may exist in another tenant. Composite foreign keys also bind subject, mission, component, Grant, Release artifact, and deployment at the SQLite layer. The API treats an exact replay as idempotent and rejects any attempt to rebind:

• a Task to another subject, mission, Grant, or source Task;
• an effect to another Task or Job;
• a Job to another effect/Task;
• a release-producing effect to a second Release;
• a Deployment to another Release, artifact, target revision, or environment;
• an Acceptance to another Deployment, Release, artifact, tenant, or subject.

explain(tenant_id, subject_id, mission_id) uses equality predicates for all three scope fields. It returns Tasks, effects/Jobs, Releases, Deployments, and Acceptances only for that exact mission.

aios_baseline.release.ReleaseLedger owns dynamic EnvironmentDeploymentTarget records. A target is never written into a RuntimeContract. One target row exists per (tenant, component, environment); the subject is the authenticated actor recorded for audit. Every target action passes through a configured resolver with tenant, subject, component, environment, and action. Multiple authorized subjects therefore share one CAS revision instead of creating conflicting desired state. set_target uses an expected-revision CAS; None creates revision 1 and later writes require the exact current revision. A STAGED target records source and observed-main revisions independently, so main being ahead of the staged source is valid. A ROLLBACK_STAGED target is admitted only when the current record has an explicit compatible rollback Release and exact artifact binding. The outer artifact object rejects recursive self-hash fields.

Recipes and their canonical SHA-256 identities are immutable. A saga persists its recipe identity, component and source Task/effect/Grant, stable per-stage effect ID, effect intent, raw receiver receipt state, typed verified receipt binding, deployment facts, target revision, and CAS revision. The adapter must first create or resolve a real Job via prepare; only then does the lineage authority link the effect. An operation exception leaves EFFECT_UNKNOWN. Recovery calls adapter readback, and missing readback fails with RECONCILIATION_REQUIRED without repeating the effect. A returned but unverified receipt is persisted as RECEIPT_UNVERIFIED; it is reverified rather than causing the effect to be issued again. Only an injected verifier returning VerifiedReceipt with the exact component, Task, source effect, Grant, Job, effect, operation, tenant, subject, Deployment, Release, and artifact can advance a stage. Acceptance follows the same pattern through VerifiedAcceptanceEvidence and includes an explicit acceptance_id.

Public interfaces

LineageLedger(path, task_authority, job_authority)
ledger.link_task(tenant_id, subject_id, mission_id, grant_id, task_id,
                 source_task_id=None, metadata=None)
ledger.link_effect(tenant_id, subject_id, mission_id, task_id, effect_id,
                   job_id, source_effect_id=None, metadata=None)
ledger.link_release(tenant_id, subject_id, mission_id, effect_id, release_id,
                    artifact, metadata=None)
ledger.link_deployment(tenant_id, subject_id, mission_id, release_id,
                       deployment_id, component_id, environment, target_revision, artifact,
                       metadata=None)
ledger.record_acceptance(tenant_id, subject_id, mission_id, component_id, acceptance_id,
                         deployment_id, release_id, artifact, accepted,
                         evidence=raw_evidence, verifier=trusted_verifier)
ledger.explain(tenant_id, subject_id, mission_id)

ReleaseLedger(path, lineage=ledger, receipt_verifier=trusted_verifier,
              target_authorizer=authorization_resolver)
releases.register_recipe(recipe_id, stages)
releases.set_target(tenant_id, subject_id, component_id, environment, release_id, artifact,
                    expected_revision=revision_or_none, stage="STAGED", ...)
releases.start_saga(tenant_id, subject_id, mission_id, component_id, saga_id, release_id,
                    deployment_id, environment, artifact, recipe_id,
                    expected_target_revision=revision)
releases.advance_saga(tenant_id, subject_id, saga_id, expected_revision,
                      governed_operation_adapter)
releases.get_saga(tenant_id, subject_id, saga_id)
releases.deployment_facts(tenant_id, subject_id, component_id, deployment_id)

An artifact argument may be a non-empty string or canonical JSON object. The object is compared by canonical JSON identity; outer self-hash fields such as manifest_sha256 are forbidden.

Existing Bridge and governance audit

The existing loopback Bridge exposes /v2/release/artifact, /v2/release/execute, /v2/release/consistency, and /v2/release/acceptance. These endpoints use the historical static tuple version, target_oid, evidence_closure_oid, and approval_plan_id (plus execute where applicable). Static source review found that this protocol is not a conforming ReleaseLedger operation receiver:

1. The Bridge allowlist rejects the new tenant, subject, mission, component, Grant, Task, Job, effect, Deployment, target-revision, and idempotency fields.
2. Release routes are outside the Bridge's TaskPrincipal-protected mutating operation set. They therefore cannot demonstrate the new Grant/Task/Job authorization chain.
3. Historical release responses are unsigned and are not bound to the stable saga effect ID, Deployment ID, Release ID, subject, or canonical artifact. A status, accepted, or ACTIVE_VERIFIED field is not verifier authority.
4. The trusted-plan executor deliberately rejects production execution with PRODUCTION_EXECUTION_REQUIRES_APPROVED_RELEASE_EXECUTOR. The legacy path invokes its pre-existing privileged production adapter, but it is not routed through the new Grant/Job/effect protocol and must not be repurposed as that protocol.
5. The Bridge has no effect-keyed readback endpoint that can reconcile an unknown ReleaseLedger stage after response loss.
6. Historical acceptance is not bound to an explicit acceptance and Deployment identity and does not return verifier-authenticated evidence for the new ledger.

Configured Ed25519 verification

aios_baseline.verifiers provides verification-only factories. Trusted public keys are supplied by local configuration when the factory is built and copied into an immutable map. A request cannot add or replace a key. Values may be an Ed25519PublicKey, 32 raw public-key bytes, or an unpadded base64url public key.

from aios_baseline.release import ReleaseLedger
from aios_baseline.verifiers import (
    ed25519_acceptance_evidence_verifier,
    ed25519_release_receipt_verifier,
)

trusted_release_receivers = {
    "staging-receiver-2026": configured_ed25519_public_key,
}
trusted_acceptance_observers = {
    "staging-observer-2026": configured_acceptance_public_key,
}

releases = ReleaseLedger(
    state_path,
    lineage=lineage,
    receipt_verifier=ed25519_release_receipt_verifier(
        trusted_release_receivers
    ),
    target_authorizer=configured_component_target_authorizer,
)
acceptance_verifier = ed25519_acceptance_evidence_verifier(
    trusted_acceptance_observers
)

Operation receipts use envelope schema aios.release-operation-receipt-envelope.v1 and signature domain aios.release-operation-receipt.v1. Acceptance evidence uses envelope schema aios.release-acceptance-evidence-envelope.v1 and the separate signature domain aios.release-acceptance-evidence.v1. The signature input is the ASCII domain, a zero byte, and strict canonical JSON for the payload. The verifier rejects unknown envelope/payload fields, unknown key IDs, caller-provided public-key fields, cross-domain signatures, a non-SUCCEEDED operation outcome, a non-Boolean acceptance decision, and any component/Task/Grant/Job/effect/ Deployment/Release/artifact binding mismatch. This key set and both domains are separate from the diagnostic evidence.ReceiptSigner.

For that reason, this package does not add a loopback HTTP writer around the historical endpoints. Such a wrapper would create a governance bypass while appearing to satisfy the new contract. The currently safe, observation-only projection is:

{
  "transport": "loopback-http",
  "base_url": "http://127.0.0.1:18892",
  "operations": {
    "release.consistency.observe": {
      "method": "POST",
      "path": "/v2/release/consistency",
      "request_projection": [
        "version",
        "target_oid",
        "evidence_closure_oid",
        "approval_plan_id"
      ],
      "receipt_use": "diagnostic-only-unverified"
    }
  },
  "mutating_operations": {},
  "verified_receipt_operations": {}
}

A future conforming receiver must admit a new OperationalEpoch/TaskPrincipal, create or reuse the authoritative Job before the effect, fence idempotency by effect_id, expose effect-keyed readback, and return a signature-verified receipt over all ReleaseLedger binding fields. That receiver belongs at the existing Job and approved-release authority boundary, not in this relationship ledger.

Verification and honest status

Failure-first execution initially failed at import because the modules did not exist. After implementation:

• test_release_lineage.py: 15 passed. This uses a local SQLite file and reopens both ledgers across simulated process boundaries. Task authority and receipt verifiers are controlled callback fixtures; the operation callback is a fake configured sink used only to test fencing and verification. Two additional tests use real Ed25519 keys and cryptographic verification for valid signatures, signature tampering, cross-domain replay, caller key injection, decision mismatch, and Deployment mismatch. The valid signed acceptance is also persisted through the real SQLite ledger path.
• Candidate-schema tests verify independent targets for two components in one environment, one shared CAS across authorized subjects, denial of an unauthorized subject, cross-component receipt rejection, refusal to repeat an unknown effect without readback, and fail-closed rejection of an unversioned candidate database. These schemas have not been released, so no implicit legacy migration is provided.
• A targeted local loop test passed with the real TaskPlaneStore and JobStore.read authorities, including parsing the durable Job's request_json.binding and checking tenant/subject/mission/Grant/Task/effect.

No Bridge server, remote Git authority, production executor, production health endpoint, or installed signing identity was exercised. Remote deployment and acceptance are NOT_VERIFIED. No production success or live activation is claimed.