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

Truth and Operation Contracts Report

Scope

Implemented Task 3 and the adjacent C01 trusted-snapshot correction without live calls or production access.

Files changed for this work:

• active-runtime/app/aios_baseline/runtime_contract.py
• active-runtime/app/aios_baseline/operations.py
• active-runtime/app/reconciliation_controller.py
• active-runtime/app/aios_chatgpt_bridge_v2_server.py
• deploy/systemd/aios-chatgpt-bridge-v2-staging.service
• tests/baseline_v1_1/test_contracts.py
• tests/test_completed_replay_reconciliation_v7.py
• tests/test_isolated_writer_exact_path_policy.py
• tests/test_r7_atomic_recovery_and_bridge_sandbox.py
• docs/implementation-baseline-1.1/CONTRACTS_REPORT.md

No package __init__.py was changed by Task 3. No arbitrary command executor, production trust root, live call, deployment, or Git commit was created.

Public functions and payload schemas

validate_contract(document: Mapping[str, Any]) -> dict[str, Any]

Required stable contract fields:

{
  "contract_schema": "aios.runtime-contract.v1",
  "contract_revision": 1,
  "component_id": "sample",
  "environment": "staging",
  "tenant_scope": "tenant-a",
  "lifecycle": "active",
  "entrypoints": {
    "host": {
      "component_id": "sample",
      "environment": "staging",
      "resolver_ref": "service://sample/status"
    }
  },
  "bindings": {},
  "resource_refs": {},
  "credential_refs": {},
  "operations": ["service-status"]
}

lifecycle is one of active, candidate, legacy, or example. Reference groups are mappings and may be empty. A reference value may be a symbolic string, which is normalized with the contract's component and environment, or an object containing matching component_id and environment plus exactly one of resolver_ref, path_ref, or credential_ref. If a reference object supplies tenant_scope, it must match the contract.

path_ref must be relative and cannot contain traversal, backslashes, or NUL. Credential references accept credential://, secret://, and systemd-credential: references; raw /run/credentials/... paths and inline secret fields are rejected. The keys desired, desired_commit, desired_release, desired_target, and desired_targets are rejected at every depth because release targets are separate objects.

evaluate_deployment(contract, target, observation, provenance, now) -> dict[str, Any]

Target payload:

{
  "component_id": "sample",
  "environment": "staging",
  "release_id": "release-17",
  "deployment_id": "deployment-22",
  "artifact_digest": "sha256:<64 lowercase or uppercase hex characters>",
  "revision": 4
}

Observation payload:

{
  "observed_at": "2026-09-07T11:59:30Z",
  "max_age_seconds": 60,
  "source": "systemd-readback.v1",
  "actual_artifact_digest": "sha256:<64 hex characters>",
  "healthy": true,
  "component_id": "sample",
  "environment": "staging",
  "deployment_id": "deployment-22",
  "revision": 4
}

max_age is accepted as an alias for max_age_seconds; actual_artifact and artifact_digest are accepted aliases for actual_artifact_digest. The final four binding fields are optional, but when present they must be well typed and match the target. healthy is nullable at the source boundary, but null is evaluated as UNKNOWN, never healthy.

Provenance payload:

{
  "artifact_digest": "sha256:<64 hex characters>",
  "source_digest": "sha256:<64 hex characters>",
  "builder_digest": "sha256:<64 hex characters>"
}

artifact_hash, source_hash, and builder_hash are accepted aliases. now accepts a timezone-aware datetime or ISO-8601 string and is injected by tests. Missing, malformed, future, stale, or nullable evidence returns status/state/verification = UNKNOWN. A complete incompatible target returns DRIFT. Matching contract, target, observation, and provenance returns status = VERIFIED, state = CONVERGED, and converged = true. A repository's current HEAD is deliberately ignored.

OperationDefinition.from_dict(data)

Operation definition payload:

{
  "operation_id": "service-status",
  "version": 1,
  "effect_class": "READ_ONLY",
  "handler_ref": "host.service_status",
  "input_schema": "aios.operation.service-status.input.v1",
  "required_permissions": ["service-status"],
  "timeout_seconds": 10,
  "readback": {"mode": "NONE", "required": false},
  "retry": {"mode": "SAFE", "max_attempts": 2},
  "reconcile": {"mode": "NONE"},
  "rollback": {"mode": "NONE"},
  "owner_boundary": {"mode": "WITHIN_GRANT"}
}

permissions is accepted as an alias for required_permissions. Primary effect classes are READ_ONLY, IDEMPOTENT, CONDITIONAL, RECONCILABLE, and IRREVERSIBLE. Retry modes are NEVER, SAFE, AFTER_READBACK, and RECONCILE_FIRST. Readback, retry, reconcile, rollback, and owner-boundary data remain separate mappings rather than being inferred from the effect class. A service restart must declare required EXACT readback and reconciliation. Top-level command, shell, argv, executable, and script fields are rejected, and handler references cannot contain shell syntax.

Registry and operation helpers

• OperationRegistry(definitions).get(operation_id) -> OperationDefinition performs lookup only and raises KeyError for an unregistered ID.
• OperationRegistry.definitions -> tuple[OperationDefinition, ...] exposes immutable registration order.
• operation_timeout_action(definition, outcome="AMBIGUOUS", attempts=1) -> str returns RETRY, RECONCILE, or STOP. It never retries an irreversible effect and requires reconciliation for an ambiguous mutating outcome when reconciliation/readback exists.
• verify_service_restart(before, after) -> dict requires a changed instance identity and a later start timestamp. An active state without restart identity returns UNKNOWN.
• load_production_observation(path, now=None) -> dict reads a bounded, regular, non-group/world-writable production-observation.json bundle with exact keys contract, target, observation, and provenance. It projects ACTIVE only after evaluate_deployment returns VERIFIED; otherwise it projects UNKNOWN without a baseline version or target OID.

Reconciliation and snapshot corrections

ReconciliationController.reconcile now treats absent, null, wrong-type, or empty evidence as drift requiring reconciliation. This fixes the root cause where every missing pair compared as None == None and an empty mapping returned healthy.

GovernedRuntime.snapshot no longer embeds V2R1C7, c7adece1cc8beffe7c718d53c775898b45d6c7f8, or ACTIVE. It reads <state_root>/production-observation.json; absent or unverified evidence retains the existing three-field production response shape with deployment_state: UNKNOWN.

The staging unit now projects the existing encrypted credential ID directly for its own service:

LoadCredentialEncrypted=gitea-governance-executor-token:/etc/credstore.encrypted/gitea-governance-executor-token
Environment=AIOS_GITEA_TOKEN_FILE=%d/gitea-governance-executor-token

The legacy bridge sandbox test now parses both directives and asserts that the projected credential name, encrypted-file basename, and consumer %d basename are identical. It also rejects any reference to the governance executor's runtime credential directory.

Failure-first and verification evidence

Initial Task 3 collection before implementation:

ERROR tests/baseline_v1_1/test_contracts.py
ModuleNotFoundError: No module named 'aios_baseline'
1 error in 0.15s

The empty optional groups and permissions-alias tests failed before their implementation:

FAILED test_structural_contract_allows_empty_optional_reference_groups
FAILED test_read_only_definition_accepts_permissions_alias_and_registry_lists_definitions
2 failed, 39 passed in 0.20s

The trusted snapshot tests failed before C01 implementation:

ImportError: cannot import name 'load_production_observation'
1 error in 0.28s

Focused Task 3, C01, and legacy reconciliation command:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/workspace/scratch/63950cb15f5c/test_deps:$PWD/active-runtime/app python3 -m pytest -q tests/baseline_v1_1/test_contracts.py tests/test_autonomy_v1_components.py
....................................................................     [100%]
68 passed in 0.30s

Existing Bridge/control-plane compatibility command:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/workspace/scratch/63950cb15f5c/test_deps:$PWD/active-runtime/app python3 -m pytest -q tests/test_action_contract_regressions.py tests/test_bridge_v2_governed_http_bootstrap.py tests/test_control_plane_convergence_contract.py tests/test_canonical_task_projection_recovery.py
............................................                             [100%]
44 passed in 0.99s

The standalone completed-replay HTTP test originally returned 423 with body error TASK_PRINCIPAL_WRITES_DISABLED. Its mutating-operation adapter exposed no getRuntimeStatus, and the fixture provided neither the required TaskPrincipal verifier nor an authorization header. The fixture now supplies the exact ready gate facts and authenticated verifier; no production gate was relaxed:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/workspace/scratch/63950cb15f5c/test_deps:$PWD/active-runtime/app python3 -m pytest -q tests/test_completed_replay_reconciliation_v7.py
...........                                                              [100%]
11 passed in 0.60s

Fresh final scoped verification across Task 3, C01, Bridge/control-plane compatibility, completed replay, and isolated-writer fixtures:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/workspace/scratch/63950cb15f5c/test_deps:$PWD/active-runtime/app python3 -m pytest -q tests/baseline_v1_1/test_contracts.py tests/test_autonomy_v1_components.py tests/test_action_contract_regressions.py tests/test_bridge_v2_governed_http_bootstrap.py tests/test_control_plane_convergence_contract.py tests/test_canonical_task_projection_recovery.py tests/test_completed_replay_reconciliation_v7.py tests/test_isolated_writer_exact_path_policy.py tests/test_isolated_writer_policy.py
........................................................................ [ 47%]
................................................................................ [100%]
152 passed, 64 subtests passed in 1.87s

git diff --check completed with no output for all files in this report.

The isolated-writer legacy subset initially had two pristine-baseline negative-fixture failures. The audience and branch tests did not establish the required gitops group lookup, so the unchanged production guard correctly stopped at isolated_writer_path_policy_group_rejected before either intended assertion. The fixtures now supply only that valid prerequisite; production guard order and strictness are unchanged:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/workspace/scratch/63950cb15f5c/test_deps:$PWD/active-runtime/app python3 -m pytest -q tests/test_isolated_writer_exact_path_policy.py tests/test_isolated_writer_policy.py
........................ [ 82%]
.....                                                    [100%]
29 passed, 64 subtests passed in 0.40s

Focused legacy systemd assertion:

PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/workspace/scratch/63950cb15f5c/test_deps:$PWD/active-runtime/app python3 -m pytest -q tests/test_r7_atomic_recovery_and_bridge_sandbox.py
..                                                                       [100%]
2 passed in 0.04s