Action Contract Regression Remediation — 2026-08-25

Scope

Governed task: fix-action-contracts-20260825-1407 Base: 3244f0f17f8845592ac94d585f5ebd65693c9f29 Target branch: agent/fix-action-contracts-20260825-1407

Verified regressions

getReleaseConsistency and runReleaseAcceptance fail before evaluation with: Gitea API URL must be HTTP(S). V2R2C1 release evidence at a8b906d1bc24088c19647e98de6a679268f6d0a2 proves Gitea API readback passed for target 998d30304787e31e5ae607c0bd86b5edb2b0e5ad. Therefore current staging/contract overlay configuration has regressed.
getReleaseSaga fails with: Permission denied: '/var/lib/aios-gitops/silent-release'. Runtime service identity must have read/traverse access to the durable release state root. Fix ownership/group/ACL at deployment time; do not broaden to world-writable permissions.
getTagPublicationStatus rejects the authoritative approved version V2R2C1 as invalid release version, while getGovernedWriteCapabilities returns the same version as the approved release scope. The two Action contracts are internally inconsistent. Release-version validation must accept the canonical AIOS ^V[0-9]+R[0-9]+C[0-9]+$ namespace (or, preferably, use one shared validator for all release Actions).
commitFilesGoverned is unusable from the published Action schema. Runtime capability metadata declares required fields: task_id, repository, expected_branch_oid, target_branch, generation, idempotency_key, files, message, but the exposed tool contract has no files input. Regenerate/publish the Action schema from the same operation contract source and add a contract-parity test.
reconcileGitOpsJob returned DURABLE_BINDING_INVALID for a completed governed single-file job that was otherwise read back as COMPLETED. Reconciliation of a valid terminal job should be idempotent/read-only and must not require a stale or absent active lease. Add a regression case for terminal completed jobs.
getDiff returns ResponseTooLargeError / GIT_OUTPUT_LIMIT_EXCEEDED for large diffs. Add server-side bounded output: path/stat summary plus truncation metadata, or pagination. The Action must never fail merely because a valid repository diff is large.

Required implementation changes

Centralize release-version parsing and reuse it in tag status, candidate, consistency, and acceptance.
Validate/normalize Gitea API URL at service startup and fail health checks with a configuration-specific diagnostic.
Ensure the deployment unit projects a valid HTTP(S) Gitea API base URL into the staging overlay.
Correct durable release-state directory ownership/ACL for the runtime service account.
Generate the external Action schema from the runtime operation contract; parity-test required fields.
Make terminal reconciliation idempotent and independent of expired active writer leases.
Bound diff output and return truncated=true with deterministic metadata rather than transport failure.

Acceptance gates

All must pass on the same deployed overlay:

getReleaseConsistency(V2R2C1, 998d303..., a8b906d..., approved_plan) returns a structured result, not URL error.
runReleaseAcceptance(...) reaches policy evaluation, not URL error.
getTagPublicationStatus("V2R2C1") returns structured publication state.
getReleaseSaga(nonexistent_candidate) returns NOT_FOUND/empty-state semantics, never filesystem permission failure.
Published commitFilesGoverned schema exposes files and a two-file isolated branch commit succeeds.
Reconcile of a completed governed job is idempotent.
Large diff returns bounded/truncated data rather than transport exception.
Existing protected-ref controls remain unchanged: no direct main/tag/baseline/production write.

Proven stable reference

V2R2C1 evidence closure (a8b906d1bc24088c19647e98de6a679268f6d0a2) records:

Gitea Git/API readback PASS
staging runtime PASS
restart recovery PASS
59 mandatory tests passed / 0 failed

This evidence should be used as the compatibility baseline when repairing the current contract-overlay-v2 / scheme-a-323b615b... staging layer.

4.1 KiB Raw Blame History