Tracking source compatibility: worker RESULT evidence

Task: 0bff1b12-2ccd-4ea0-87ee-0e6bd11d89fc, frozen version 2. Execution: 2624ace8-f87f-4abc-a027-f141744a2ec3, 2026-10-11. Repository: h8v6/heyaira; origin: [email protected]:h8v6/heyaira.git. Branch: heyaira/0bff1b12. Source and starting HEAD: 5948e9641867746b2f65724c46f0cda7cc200c47. Starting parent: 5f2eb52f25e0f4f4002d6267cc691cb0057de946. Initial git status --short was empty; there was no carried candidate. Working directory for all commands: /Users/jablonskib/HeyAira-agents/.heyaira-worktrees/heyaira/0bff1b12-worker. Tests ran on the implementation above the starting HEAD, before the new local commit containing this file. The task_result receipt records the resulting SHA.

server_identity matched the supplied resource, instance, project and execution principal. task_get read exact v2 before editing. Execution-scoped tools expose neither continuity_context nor claiming/task-update tools. This worker follows docs/agents/skills/deliver-bridge-task.md; Bridge owns independent verification. No push, PR, merge, install, deployment or production mutation was performed. Only the authorized RESULT/receipt is written through MCP.

Cause, change and confidence

Migration 056 permits a tracking source's stored SHA to be null. The source list previously returned that null to deployed clients requiring a string, and did not include the branch. The list now excludes tracking rows in SQL before pagination unless include_tracking=true. Only tracking rows gain tracking_ref; pinned fields and response envelope remain unchanged. Bootstrap tracking references also name their branch, preserving pinned fields. Branch resolution now maps a missing installation argument to the same provider_unconfigured error as get_file.

Confidence is high for the tested HTTP/MCP handler and PostgreSQL behavior. Authentication and GitHub responses are synthetic; production GitHub transport and a listening MCP server were not exercised. No schema or dispatch changes are needed. Independent acceptance remains Bridge's responsibility.

Intended files: src/heyaira/server.py, src/heyaira/git_provider.py, tests/test_tracking_sources_compat.py, tests/test_tracking_git_provider.py, docs/BRIDGE_PROTOCOL.md, docs/GIT_DOCUMENT_ACCESS.md, and this evidence.

Audit of every document-source SHA reader

Audit command: rg -n 'commit_sha|document_source' src/heyaira (exit 0). The criterion's literal grep -n commit_sha src/heyaira exits 2 with grep: src/heyaira: Is a directory; the recursive ripgrep command above is the equivalent successful directory audit. Spot-checks include bootstrap and read_document, with dedicated regressions, and the existing catalog/dispatch tracking suites. Locations and disposition:

• server.py: _document_source and _load_document_source already preserve nullable SHA and tracking_ref, with project/revocation fencing. Changed bridge_sources to filter tracking by default and identify opted-in rows. Changed runtime_bootstrap_get's shared reference serializer (runtime refs, project-config refs and allowed documents) to identify tracking rows. git_document_get delegates to the pinned-only validation below; no head resolution occurs. github_ci_status's optional SHA filters workflow runs, not document sources, so it is unrelated and unchanged.
• documents.py: DocumentSource already allows null SHA and tracking ref. validate_commit_sha explicitly rejects null. read_document validates before provider reads, cursor decoding/encoding or output; standalone tracking reads fail invalid_commit. CursorCodec binds and serializes the validated/resolved immutable SHA. Existing client formats are unchanged.
• task_execution.py: send_task explicitly resolves tracking sources to task base commit or one cached branch head, validates full SHAs and passes resolved provenance. Pinned sources retain their stored SHA. Unchanged.
• catalog_workflow.py: SourcePin requires a full SHA. dispatch_catalog requires server-resolved provenance for tracking, substitutes the resolved SHA before read_document, and freezes immutable SHA plus resolved_from. validate_catalog_contract explicitly checks pinned versus tracking origins and registry revocation/changes. Unchanged.
• admin.py: _add_document_source already validates optional pinned SHA, chooses the tracking or pinned uniqueness key, stores the exclusive mode, and returns a source ID rather than nullable SHA. Unchanged.
• git_provider.py: get_file receives a validated immutable SHA via read_document. Only the branch token-argument error mapping changed; exact-head lookup and dispatch resolution are unchanged.

No other commit_sha or document_source matches exist under src/heyaira.

Actual checks

All pytest commands below used the existing Python 3.12.7 and supplied TMPDIR; no dependencies were installed. PostgreSQL used the supplied isolated test admin database via Unix socket, not a production DSN. No DSN or token is saved.

Baseline, with new tests but production code still exactly at 5948e96:

PYTHONPATH=src python3.12 -m pytest -q -p no:cacheprovider \
  tests/test_tracking_sources_compat.py \
  tests/test_tracking_git_provider.py::test_tracking_provider_missing_installation_matches_get_file

Exit 1; first run 4 failed in 3.93s. Repeated to retain output, again exit 1:

FAILED tests/test_tracking_sources_compat.py::test_sources_default_preserves_pinned_client_format
FAILED tests/test_tracking_sources_compat.py::test_sources_include_tracking_preserves_filters_and_pagination
FAILED tests/test_tracking_sources_compat.py::test_bootstrap_tracking_references_name_branch_without_changing_pinned_format
FAILED tests/test_tracking_git_provider.py::test_tracking_provider_missing_installation_matches_get_file
4 failed in 3.33s

Observed failures: default list included the tracking ID before pinned IDs; opt-in and bootstrap raised KeyError: 'tracking_ref'; branch resolution raised TypeError: ...token_provider() missing 1 required positional argument: 'installation_id'. Same command after the fix, exit 0: 4 passed in 3.06s.

Named regressions after the fix (exit 0):

PYTHONPATH=src python3.12 -m pytest -q -p no:cacheprovider \
  tests/test_tracking_sources_compat.py::test_sources_default_preserves_pinned_client_format \
  tests/test_tracking_sources_compat.py::test_sources_include_tracking_preserves_filters_and_pagination \
  tests/test_tracking_sources_compat.py::test_bootstrap_tracking_references_name_branch_without_changing_pinned_format \
  tests/test_tracking_git_provider.py::test_tracking_provider_missing_installation_matches_get_file

....                                                                     [100%]
4 passed in 3.31s

Existing and new tracking suites (exit 0):

PYTHONPATH=src python3.12 -m pytest -q -p no:cacheprovider \
  tests/test_tracking_document_sources.py tests/test_tracking_git_provider.py \
  tests/test_tracking_sources_compat.py

.......................................................                  [100%]
55 passed in 17.37s

Dedicated PostgreSQL acceptance runner for the same selection (exit 0):

PYTHONPATH=src python3.12 scripts/test_postgres.py \
  tests/test_tracking_sources_compat.py tests/test_tracking_document_sources.py \
  tests/test_tracking_git_provider.py

.......................................................                  [100%]
55 passed in 9.96s
postgres_acceptance=passed: selected tests, zero skipped tests

Related checks (exit 0), separate from required acceptance:

PYTHONPATH=src python3.12 -m pytest -q -p no:cacheprovider \
  tests/test_documents.py tests/test_git_provider.py tests/test_catalog_workflow.py \
  tests/test_mcp_runtime_contract.py tests/test_docs_contract.py

SKIPPED [1] tests/test_catalog_workflow.py:18: set HEYAIRA_EXECUTION_E2E_DATABASE_URL to an isolated PostgreSQL database
55 passed, 1 skipped in 3.23s

The optional listener-based catalog E2E was not run; the required tracking handler/PostgreSQL tests ran without skips. Full suite and production canaries were not run.

Static checks (each exit 0):

• PYTHONPATH=src python3.12 scripts/export_mcp_contract.py --check: MCP contract is up to date.
• PYTHONPATH=src python3.12 scripts/check_docs_contract.py: documentation contract passed: 46 MCP tools covered.
• git diff --check: no whitespace errors.
• git diff --quiet 5948e9641867746b2f65724c46f0cda7cc200c47 -- migrations/056_tracking_document_sources.sql src/heyaira/task_execution.py src/heyaira/catalog_workflow.py ios: no changes to the forbidden paths.

Frozen criterion checklist

criterion_id: compat-default method: Run the new regression test by name (PostgreSQL); it fails on 5948e96 and passes on the candidate. outcome: pass evidence_path: docs/agent-work/0bff1b12-evidence.md feedback: Named default regression failed on the base and passed after the fix; full pinned fields and 40-hex SHAs asserted with tracking present; PostgreSQL acceptance exit 0, zero skips.

criterion_id: opt-in method: Run the new test by name; read the documentation paragraph. outcome: pass evidence_path: docs/agent-work/0bff1b12-evidence.md feedback: Named opt-in regression failed on the base and passed after the fix; null SHA, branch, pagination, authorized filter, foreign-project refusal and invalid pagination asserted; docs/BRIDGE_PROTOCOL.md documents the parameter.

criterion_id: other-readers method: grep -n commit_sha src/heyaira; compare with the list in RESULT; spot-check two. outcome: pass evidence_path: docs/agent-work/0bff1b12-evidence.md feedback: Directory grep syntax failure retained; equivalent recursive rg audit completed and every reader listed above. Bootstrap tracking-reference regression and existing standalone-read/catalog resolution regressions passed.

criterion_id: provider-error method: Run the new git_provider test by name. outcome: pass evidence_path: docs/agent-work/0bff1b12-evidence.md feedback: Named provider regression reproduced TypeError on the base; passes with provider_unconfigured matching get_file and no GitHub request.

criterion_id: scope method: git diff --stat 5948e9641867746b2f65724c46f0cda7cc200c47..HEAD; run tests/test_tracking_document_sources.py and tests/test_tracking_git_provider.py. outcome: pass evidence_path: docs/agent-work/0bff1b12-evidence.md feedback: Seven intended files only; forbidden-path diff empty. Required tracking suites and compatibility regressions passed (55 tests), also passed the PostgreSQL zero-skip gate. Final commit/stat/clean-tree confirmation is recorded in the task_result receipt.