From 37d1125b62efa2ec7802ef2ce5707d47896011e4 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 05:36:49 -0700 Subject: [PATCH 01/12] test(ci): reproduce flat-lock include relocation --- tests/test_flat_lock_publication_boundary.py | 89 ++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 tests/test_flat_lock_publication_boundary.py diff --git a/tests/test_flat_lock_publication_boundary.py b/tests/test_flat_lock_publication_boundary.py new file mode 100644 index 000000000..f70a61851 --- /dev/null +++ b/tests/test_flat_lock_publication_boundary.py @@ -0,0 +1,89 @@ +"""Regression tests for generated flat Python lock publication.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from scripts.ci import materialize_base_python_requirements as materializer + + +def _exact_pin(package_name: str, digest_character: str) -> bytes: + """Return one standalone exact SHA-256 requirement fixture.""" + return ( + f"{package_name}==1 --hash=sha256:{digest_character * 64}\n".encode() + ) + + +@pytest.mark.parametrize("directive", ["-r", "--requirement"]) +def test_flat_publication_excludes_relative_include_referrers( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + directive: str, +) -> None: + """A generated flat name cannot preserve a source-relative include edge.""" + tree = ( + b"100644 blob " + + (b"0" * 40) + + b"\trequirements-other.txt\0" + + b"100644 blob " + + (b"1" * 40) + + b"\trequirements.txt\0" + ) + target_lock = _exact_pin("target-package", "a") + + def fake_git(_repo_root: Path, *args: str) -> bytes: + if args[0] == "ls-tree": + return tree + if args[0] == "show" and args[-1].endswith(":requirements-other.txt"): + return target_lock + if args[0] == "show" and args[-1].endswith(":requirements.txt"): + return f"{directive} requirements-other.txt\n".encode() + raise AssertionError(args) + + monkeypatch.setattr(materializer, "_git", fake_git) + + assert materializer.base_hash_locks(tmp_path, "a" * 40) == [ + ("requirements-other.txt", target_lock) + ] + + +def test_flat_publication_discovers_standalone_requirements_directory_locks( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, +) -> None: + """Path-aware discovery keeps complete direct requirements-directory locks.""" + tree = ( + b"100644 blob " + + (b"0" * 40) + + b"\trequirements/ci.txt\0" + + b"100644 blob " + + (b"1" * 40) + + b"\tservice/requirements/package.txt\0" + + b"100644 blob " + + (b"2" * 40) + + b"\trequirements.txt\0" + ) + ci_lock = _exact_pin("ci-package", "a") + service_lock = _exact_pin("service-package", "b") + + def fake_git(_repo_root: Path, *args: str) -> bytes: + if args[0] == "ls-tree": + return tree + if args[0] == "show" and args[-1].endswith(":requirements/ci.txt"): + return ci_lock + if args[0] == "show" and args[-1].endswith( + ":service/requirements/package.txt" + ): + return service_lock + if args[0] == "show" and args[-1].endswith(":requirements.txt"): + return b"-r requirements/ci.txt\n" + raise AssertionError(args) + + monkeypatch.setattr(materializer, "_git", fake_git) + + assert materializer.base_hash_locks(tmp_path, "a" * 40) == [ + ("requirements/ci.txt", ci_lock), + ("service/requirements/package.txt", service_lock), + ] From 6ece5fb75ad2e577927f081e96da45e7d9d53455 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 05:46:43 -0700 Subject: [PATCH 02/12] ci: run one-shot flat-lock green verification --- .../one-shot-flat-lock-publication-repair.yml | 267 ++++++++++++++++++ 1 file changed, 267 insertions(+) create mode 100644 .github/workflows/one-shot-flat-lock-publication-repair.yml diff --git a/.github/workflows/one-shot-flat-lock-publication-repair.yml b/.github/workflows/one-shot-flat-lock-publication-repair.yml new file mode 100644 index 000000000..f89fce328 --- /dev/null +++ b/.github/workflows/one-shot-flat-lock-publication-repair.yml @@ -0,0 +1,267 @@ +name: One-shot Flat Lock Publication Repair + +on: + push: + branches: + - fix/trusted-uv-flat-publication-current-main + paths: + - .github/workflows/one-shot-flat-lock-publication-repair.yml + +permissions: + contents: write + +concurrency: + group: one-shot-flat-lock-publication-repair + cancel-in-progress: false + +jobs: + repair: + if: >- + github.repository == 'ContextualWisdomLab/.github' && + github.actor == 'seonghobae' + runs-on: ubuntu-24.04 + timeout-minutes: 25 + env: + EXPECTED_PARENT_SHA: 37d1125b62efa2ec7802ef2ce5707d47896011e4 + TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main + steps: + - name: Harden runner + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 + with: + egress-policy: audit + + - name: Checkout exact repair trigger + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + ref: ${{ github.sha }} + fetch-depth: 2 + persist-credentials: false + + - name: Verify bounded repair ancestry + run: | + set -euo pipefail + test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" + test "$(git rev-parse HEAD)" = "$GITHUB_SHA" + test "$(git rev-list --count HEAD^..HEAD)" = "1" + + - name: Apply the minimal GREEN correction + run: | + set -euo pipefail + python - <<'PY' + from pathlib import Path + + script_path = Path("scripts/ci/materialize_base_python_requirements.py") + script = script_path.read_text(encoding="utf-8") + old_policy_boundary = ''' return all( + _is_fully_hash_pinned_requirement(line) + or _is_bounded_requirement_include(line) + for line in requirement_lines + ) + def _is_fully_hash_pinned_requirement(line: str) -> bool: + ''' + new_policy_boundary = ''' return all( + _is_fully_hash_pinned_requirement(line) + or _is_bounded_requirement_include(line) + for line in requirement_lines + ) + + + def _is_flat_materializable_lock(content: bytes) -> bool: + """Return whether content is one standalone exact SHA-256 lock. + + The materializer publishes selected sources under generated flat names. + Relative ``-r`` and ``--requirement`` edges are therefore not portable: + pip would resolve them relative to the generated output rather than the + source directory. Only independent package pins cross this boundary until + a complete immutable include graph can be reconstructed and rewritten. + """ + lines = _requirement_lines(content) + requirement_lines = [line for line in lines if line != "--require-hashes"] + return bool(requirement_lines) and all( + _is_fully_hash_pinned_requirement(line) for line in requirement_lines + ) + + + def _is_fully_hash_pinned_requirement(line: str) -> bool: + ''' + if script.count(old_policy_boundary) != 1: + raise SystemExit("flat publication policy insertion point drifted") + script = script.replace(old_policy_boundary, new_policy_boundary, 1) + + old_selection = ''' if _is_candidate_lock_name(candidate.name): + content = _git(repo_root, "show", f"{base_sha}:{path}") + if _is_hash_pinned(content): + locks.append((path, content)) + ''' + new_selection = ''' if _is_candidate_lock_path(candidate): + content = _git(repo_root, "show", f"{base_sha}:{path}") + if _is_flat_materializable_lock(content): + locks.append((path, content)) + ''' + if script.count(old_selection) != 1: + raise SystemExit("base-lock selection boundary drifted") + script = script.replace(old_selection, new_selection, 1) + script_path.write_text(script, encoding="utf-8") + + old_test = Path("tests/test_flat_lock_publication_boundary.py") + new_test = Path("tests/test_uv_flat_lock_publication_boundary.py") + if not old_test.is_file() or new_test.exists(): + raise SystemExit("flat-lock RED fixture path drifted") + old_test.replace(new_test) + + quality_path = Path(".github/workflows/trusted-uv-materializer-quality-ci.yml") + quality = quality_path.read_text(encoding="utf-8") + quality_anchor = " tests/test_uv_export_isolation_contract.py \\\n" + if quality.count(quality_anchor) != 2: + raise SystemExit("trusted-uv focused test list drifted") + quality = quality.replace( + quality_anchor, + quality_anchor + " tests/test_uv_flat_lock_publication_boundary.py \\\n", + ) + quality_path.write_text(quality, encoding="utf-8") + + changelog_path = Path("CHANGELOG.md") + changelog = changelog_path.read_text(encoding="utf-8") + old_changelog = "- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context." + new_changelog = "- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories." + if changelog.count(old_changelog) != 1: + raise SystemExit("trusted-uv changelog entry drifted") + changelog_path.write_text( + changelog.replace(old_changelog, new_changelog, 1), + encoding="utf-8", + ) + + doctoring = Path("docs/doctoring/trusted-uv-flat-include-isolation.md") + if doctoring.exists(): + raise SystemExit("doctoring target unexpectedly exists") + doctoring.write_text( + """# Trusted uv flat-include isolation + +## Status + +Accepted on 2026-08-18 for generated base Python lock publication. + +## Buyer-facing failure + +The central coverage lane renames every selected source lock to a generated flat +name such as `requirements-000.txt`. A source file containing a relative `-r` or +`--requirement` directive is valid pip syntax, but the target is resolved relative +to the generated output location. Publishing only the referrer can therefore +break a downstream repository before its own tests or docstring checks execute. + +## Root cause and decision + +Syntax recognition and publication authority were conflated. The bounded +`_is_hash_pinned` diagnostic continues to recognize safe relative include syntax, +but `_is_flat_materializable_lock` now admits only non-empty standalone exact +SHA-256 package pins. `base_hash_locks` uses the existing path-aware candidate +predicate so complete `requirements/ci.txt` and +`service/requirements/package.txt` locks remain eligible. + +No URL, proxy, redirect, package index, caller-controlled header, output path, +review authority, or repository write scope is expanded. Relative include +publication remains fail-closed until the materializer can reconstruct an entire +immutable include graph, preserve source-directory identity, rewrite every edge, +and prove the resulting closure. + +## Verification and operator action + +The RED regression proves that both include spellings previously crossed the +flat boundary and that path-aware nested locks were omitted. GREEN requires the +focused trusted-uv suite, complete central test suite, 100% production statement +and branch coverage, complete production docstrings, compilation, and exact-head +protected checks. A downstream repository that uses nested requirements should +publish one standalone hash-locked closure or wait for a separately reviewed +graph-aware materializer; operators must not copy or rename an unresolved +include manually. + +## Rollback + +Do not restore relative include publication. A rollback would reintroduce a +source-relative edge into a namespace that no longer preserves its source +location. Restore only after a graph-aware implementation has equivalent RED +fixtures, immutable edge rewriting, and full closure verification. + +## APA 7th references + +Python Packaging Authority. (2026). *Requirements file format*. pip +documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +Python Packaging Authority. (2026). *Secure installs*. pip documentation. +https://pip.pypa.io/en/stable/topics/secure-installs/ +""", + encoding="utf-8", + ) + PY + + - name: Set up current stable Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.14" + cache: pip + cache-dependency-path: requirements-opencode-review-ci-hashes.txt + + - name: Install hash-locked quality tooling + run: >- + python -m pip install --disable-pip-version-check --require-hashes + -r requirements-opencode-review-ci-hashes.txt + + - name: Verify GREEN with complete trusted-uv and central gates + run: | + set -euo pipefail + cat >"${RUNNER_TEMP}/trusted-uv-coveragerc" <<'EOF' + [run] + branch = True + include = + scripts/ci/materialize_base_python_requirements.py + + [report] + fail_under = 100 + show_missing = True + EOF + export COVERAGE_RCFILE="${RUNNER_TEMP}/trusted-uv-coveragerc" + python -m coverage erase + python -m coverage run -m pytest \ + tests/test_materialize_base_python_requirements.py \ + tests/test_materialize_uv_export_hash_contract.py \ + tests/test_trusted_uv_download_contract.py \ + tests/test_trusted_uv_portability_and_streaming.py \ + tests/test_uv_export_isolation_contract.py \ + tests/test_uv_flat_lock_publication_boundary.py \ + tests/test_uv_redirect_and_coverage_contract.py \ + tests/test_uv_redirect_boundary.py \ + tests/test_uv_workspace_fail_closed.py \ + tests/test_trusted_uv_materializer_quality_workflow_contract.py \ + -q + python -m coverage report + unset COVERAGE_RCFILE + python -m coverage erase + python -m coverage run -m pytest tests -q + python -m coverage report + python -m interrogate --fail-under 100 \ + scripts/ci/materialize_base_python_requirements.py + python -m compileall -q \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_uv_flat_lock_publication_boundary.py + git diff --check + + - name: Publish verified repair and remove one-shot authority + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + rm .github/workflows/one-shot-flat-lock-publication-repair.yml + git add \ + CHANGELOG.md \ + .github/workflows/trusted-uv-materializer-quality-ci.yml \ + docs/doctoring/trusted-uv-flat-include-isolation.md \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_flat_lock_publication_boundary.py \ + tests/test_uv_flat_lock_publication_boundary.py \ + .github/workflows/one-shot-flat-lock-publication-repair.yml + git config user.name "CWL One-shot Repair" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "fix(ci): isolate relative includes from flat locks" + git remote set-url origin \ + "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From 83dfdfd4f922aecafcd11415dce2aa59d3b46b51 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 05:57:42 -0700 Subject: [PATCH 03/12] chore(ci): remove inactive one-shot repair workflow --- .../one-shot-flat-lock-publication-repair.yml | 267 ------------------ 1 file changed, 267 deletions(-) delete mode 100644 .github/workflows/one-shot-flat-lock-publication-repair.yml diff --git a/.github/workflows/one-shot-flat-lock-publication-repair.yml b/.github/workflows/one-shot-flat-lock-publication-repair.yml deleted file mode 100644 index f89fce328..000000000 --- a/.github/workflows/one-shot-flat-lock-publication-repair.yml +++ /dev/null @@ -1,267 +0,0 @@ -name: One-shot Flat Lock Publication Repair - -on: - push: - branches: - - fix/trusted-uv-flat-publication-current-main - paths: - - .github/workflows/one-shot-flat-lock-publication-repair.yml - -permissions: - contents: write - -concurrency: - group: one-shot-flat-lock-publication-repair - cancel-in-progress: false - -jobs: - repair: - if: >- - github.repository == 'ContextualWisdomLab/.github' && - github.actor == 'seonghobae' - runs-on: ubuntu-24.04 - timeout-minutes: 25 - env: - EXPECTED_PARENT_SHA: 37d1125b62efa2ec7802ef2ce5707d47896011e4 - TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main - steps: - - name: Harden runner - uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 - with: - egress-policy: audit - - - name: Checkout exact repair trigger - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - with: - ref: ${{ github.sha }} - fetch-depth: 2 - persist-credentials: false - - - name: Verify bounded repair ancestry - run: | - set -euo pipefail - test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" - test "$(git rev-parse HEAD)" = "$GITHUB_SHA" - test "$(git rev-list --count HEAD^..HEAD)" = "1" - - - name: Apply the minimal GREEN correction - run: | - set -euo pipefail - python - <<'PY' - from pathlib import Path - - script_path = Path("scripts/ci/materialize_base_python_requirements.py") - script = script_path.read_text(encoding="utf-8") - old_policy_boundary = ''' return all( - _is_fully_hash_pinned_requirement(line) - or _is_bounded_requirement_include(line) - for line in requirement_lines - ) - def _is_fully_hash_pinned_requirement(line: str) -> bool: - ''' - new_policy_boundary = ''' return all( - _is_fully_hash_pinned_requirement(line) - or _is_bounded_requirement_include(line) - for line in requirement_lines - ) - - - def _is_flat_materializable_lock(content: bytes) -> bool: - """Return whether content is one standalone exact SHA-256 lock. - - The materializer publishes selected sources under generated flat names. - Relative ``-r`` and ``--requirement`` edges are therefore not portable: - pip would resolve them relative to the generated output rather than the - source directory. Only independent package pins cross this boundary until - a complete immutable include graph can be reconstructed and rewritten. - """ - lines = _requirement_lines(content) - requirement_lines = [line for line in lines if line != "--require-hashes"] - return bool(requirement_lines) and all( - _is_fully_hash_pinned_requirement(line) for line in requirement_lines - ) - - - def _is_fully_hash_pinned_requirement(line: str) -> bool: - ''' - if script.count(old_policy_boundary) != 1: - raise SystemExit("flat publication policy insertion point drifted") - script = script.replace(old_policy_boundary, new_policy_boundary, 1) - - old_selection = ''' if _is_candidate_lock_name(candidate.name): - content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_hash_pinned(content): - locks.append((path, content)) - ''' - new_selection = ''' if _is_candidate_lock_path(candidate): - content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_flat_materializable_lock(content): - locks.append((path, content)) - ''' - if script.count(old_selection) != 1: - raise SystemExit("base-lock selection boundary drifted") - script = script.replace(old_selection, new_selection, 1) - script_path.write_text(script, encoding="utf-8") - - old_test = Path("tests/test_flat_lock_publication_boundary.py") - new_test = Path("tests/test_uv_flat_lock_publication_boundary.py") - if not old_test.is_file() or new_test.exists(): - raise SystemExit("flat-lock RED fixture path drifted") - old_test.replace(new_test) - - quality_path = Path(".github/workflows/trusted-uv-materializer-quality-ci.yml") - quality = quality_path.read_text(encoding="utf-8") - quality_anchor = " tests/test_uv_export_isolation_contract.py \\\n" - if quality.count(quality_anchor) != 2: - raise SystemExit("trusted-uv focused test list drifted") - quality = quality.replace( - quality_anchor, - quality_anchor + " tests/test_uv_flat_lock_publication_boundary.py \\\n", - ) - quality_path.write_text(quality, encoding="utf-8") - - changelog_path = Path("CHANGELOG.md") - changelog = changelog_path.read_text(encoding="utf-8") - old_changelog = "- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context." - new_changelog = "- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories." - if changelog.count(old_changelog) != 1: - raise SystemExit("trusted-uv changelog entry drifted") - changelog_path.write_text( - changelog.replace(old_changelog, new_changelog, 1), - encoding="utf-8", - ) - - doctoring = Path("docs/doctoring/trusted-uv-flat-include-isolation.md") - if doctoring.exists(): - raise SystemExit("doctoring target unexpectedly exists") - doctoring.write_text( - """# Trusted uv flat-include isolation - -## Status - -Accepted on 2026-08-18 for generated base Python lock publication. - -## Buyer-facing failure - -The central coverage lane renames every selected source lock to a generated flat -name such as `requirements-000.txt`. A source file containing a relative `-r` or -`--requirement` directive is valid pip syntax, but the target is resolved relative -to the generated output location. Publishing only the referrer can therefore -break a downstream repository before its own tests or docstring checks execute. - -## Root cause and decision - -Syntax recognition and publication authority were conflated. The bounded -`_is_hash_pinned` diagnostic continues to recognize safe relative include syntax, -but `_is_flat_materializable_lock` now admits only non-empty standalone exact -SHA-256 package pins. `base_hash_locks` uses the existing path-aware candidate -predicate so complete `requirements/ci.txt` and -`service/requirements/package.txt` locks remain eligible. - -No URL, proxy, redirect, package index, caller-controlled header, output path, -review authority, or repository write scope is expanded. Relative include -publication remains fail-closed until the materializer can reconstruct an entire -immutable include graph, preserve source-directory identity, rewrite every edge, -and prove the resulting closure. - -## Verification and operator action - -The RED regression proves that both include spellings previously crossed the -flat boundary and that path-aware nested locks were omitted. GREEN requires the -focused trusted-uv suite, complete central test suite, 100% production statement -and branch coverage, complete production docstrings, compilation, and exact-head -protected checks. A downstream repository that uses nested requirements should -publish one standalone hash-locked closure or wait for a separately reviewed -graph-aware materializer; operators must not copy or rename an unresolved -include manually. - -## Rollback - -Do not restore relative include publication. A rollback would reintroduce a -source-relative edge into a namespace that no longer preserves its source -location. Restore only after a graph-aware implementation has equivalent RED -fixtures, immutable edge rewriting, and full closure verification. - -## APA 7th references - -Python Packaging Authority. (2026). *Requirements file format*. pip -documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -Python Packaging Authority. (2026). *Secure installs*. pip documentation. -https://pip.pypa.io/en/stable/topics/secure-installs/ -""", - encoding="utf-8", - ) - PY - - - name: Set up current stable Python - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.14" - cache: pip - cache-dependency-path: requirements-opencode-review-ci-hashes.txt - - - name: Install hash-locked quality tooling - run: >- - python -m pip install --disable-pip-version-check --require-hashes - -r requirements-opencode-review-ci-hashes.txt - - - name: Verify GREEN with complete trusted-uv and central gates - run: | - set -euo pipefail - cat >"${RUNNER_TEMP}/trusted-uv-coveragerc" <<'EOF' - [run] - branch = True - include = - scripts/ci/materialize_base_python_requirements.py - - [report] - fail_under = 100 - show_missing = True - EOF - export COVERAGE_RCFILE="${RUNNER_TEMP}/trusted-uv-coveragerc" - python -m coverage erase - python -m coverage run -m pytest \ - tests/test_materialize_base_python_requirements.py \ - tests/test_materialize_uv_export_hash_contract.py \ - tests/test_trusted_uv_download_contract.py \ - tests/test_trusted_uv_portability_and_streaming.py \ - tests/test_uv_export_isolation_contract.py \ - tests/test_uv_flat_lock_publication_boundary.py \ - tests/test_uv_redirect_and_coverage_contract.py \ - tests/test_uv_redirect_boundary.py \ - tests/test_uv_workspace_fail_closed.py \ - tests/test_trusted_uv_materializer_quality_workflow_contract.py \ - -q - python -m coverage report - unset COVERAGE_RCFILE - python -m coverage erase - python -m coverage run -m pytest tests -q - python -m coverage report - python -m interrogate --fail-under 100 \ - scripts/ci/materialize_base_python_requirements.py - python -m compileall -q \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_uv_flat_lock_publication_boundary.py - git diff --check - - - name: Publish verified repair and remove one-shot authority - env: - GH_TOKEN: ${{ github.token }} - run: | - set -euo pipefail - rm .github/workflows/one-shot-flat-lock-publication-repair.yml - git add \ - CHANGELOG.md \ - .github/workflows/trusted-uv-materializer-quality-ci.yml \ - docs/doctoring/trusted-uv-flat-include-isolation.md \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_flat_lock_publication_boundary.py \ - tests/test_uv_flat_lock_publication_boundary.py \ - .github/workflows/one-shot-flat-lock-publication-repair.yml - git config user.name "CWL One-shot Repair" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git commit -m "fix(ci): isolate relative includes from flat locks" - git remote set-url origin \ - "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From af5e8901937720a5613866e94b0fbf2a689c0364 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:12:36 -0700 Subject: [PATCH 04/12] ci: execute bounded flat-lock GREEN --- .../workflows/one-shot-flat-lock-green.yml | 281 ++++++++++++++++++ 1 file changed, 281 insertions(+) create mode 100644 .github/workflows/one-shot-flat-lock-green.yml diff --git a/.github/workflows/one-shot-flat-lock-green.yml b/.github/workflows/one-shot-flat-lock-green.yml new file mode 100644 index 000000000..9100ee0e9 --- /dev/null +++ b/.github/workflows/one-shot-flat-lock-green.yml @@ -0,0 +1,281 @@ +name: One-shot Flat Lock GREEN + +on: + push: + branches: + - fix/trusted-uv-flat-publication-current-main + paths: + - .github/workflows/one-shot-flat-lock-green.yml + +permissions: + contents: write + +concurrency: + group: one-shot-flat-lock-green + cancel-in-progress: false + +jobs: + green: + if: >- + github.repository == 'ContextualWisdomLab/.github' && + github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' + runs-on: ubuntu-24.04 + timeout-minutes: 35 + env: + EXPECTED_PARENT_SHA: acfd2faea6c928ead4a3957506d6063558887002 + TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main + steps: + - name: Harden runner + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 + with: + egress-policy: audit + + - name: Checkout exact trigger + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + ref: ${{ github.sha }} + fetch-depth: 2 + persist-credentials: false + + - name: Verify immutable branch boundary + run: | + set -euo pipefail + test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" + test "$(git rev-parse HEAD)" = "$GITHUB_SHA" + test "$(git rev-list --count HEAD^..HEAD)" = "1" + test "$(git branch --show-current)" = "$TARGET_BRANCH" + + - name: Apply minimal production correction + run: | + set -euo pipefail + python - <<'PY' + from pathlib import Path + + script_path = Path("scripts/ci/materialize_base_python_requirements.py") + script = script_path.read_text(encoding="utf-8") + old_policy = ''' return all( + _is_fully_hash_pinned_requirement(line) + or _is_bounded_requirement_include(line) + for line in requirement_lines + ) + def _is_fully_hash_pinned_requirement(line: str) -> bool: + ''' + new_policy = ''' return all( + _is_fully_hash_pinned_requirement(line) + or _is_bounded_requirement_include(line) + for line in requirement_lines + ) + + + def _is_flat_materializable_lock(content: bytes) -> bool: + """Return whether content is one standalone exact SHA-256 lock. + + Selected base locks are published under generated flat names. A + source-relative ``-r`` or ``--requirement`` edge therefore loses + the source directory that gives the edge meaning. Only independent + exact package pins cross this boundary until a complete immutable + include graph can be reconstructed and rewritten. + """ + lines = _requirement_lines(content) + requirement_lines = [ + line for line in lines if line != "--require-hashes" + ] + return bool(requirement_lines) and all( + _is_fully_hash_pinned_requirement(line) + for line in requirement_lines + ) + + + def _is_fully_hash_pinned_requirement(line: str) -> bool: + ''' + if script.count(old_policy) != 1: + raise SystemExit("flat-lock policy insertion point drifted") + script = script.replace(old_policy, new_policy, 1) + + old_selection = ''' if _is_candidate_lock_name(candidate.name): + content = _git(repo_root, "show", f"{base_sha}:{path}") + if _is_hash_pinned(content): + locks.append((path, content)) + ''' + new_selection = ''' if _is_candidate_lock_path(candidate): + content = _git(repo_root, "show", f"{base_sha}:{path}") + if _is_flat_materializable_lock(content): + locks.append((path, content)) + ''' + if script.count(old_selection) != 1: + raise SystemExit("base-lock selection boundary drifted") + script_path.write_text( + script.replace(old_selection, new_selection, 1), + encoding="utf-8", + ) + + old_test = Path("tests/test_flat_lock_publication_boundary.py") + new_test = Path("tests/test_uv_flat_lock_publication_boundary.py") + if not old_test.is_file() or new_test.exists(): + raise SystemExit("RED regression path drifted") + old_test.replace(new_test) + + quality_path = Path(".github/workflows/trusted-uv-materializer-quality-ci.yml") + quality = quality_path.read_text(encoding="utf-8") + anchor = " tests/test_uv_export_isolation_contract.py \\\n" + if quality.count(anchor) != 2: + raise SystemExit("trusted-uv focused list drifted") + quality_path.write_text( + quality.replace( + anchor, + anchor + + " tests/test_uv_flat_lock_publication_boundary.py \\\n", + ), + encoding="utf-8", + ) + + changelog_path = Path("CHANGELOG.md") + changelog = changelog_path.read_text(encoding="utf-8") + stale = "- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context." + replacement = "- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories." + if changelog.count(stale) != 1: + raise SystemExit("trusted-uv changelog statement drifted") + changelog_path.write_text( + changelog.replace(stale, replacement, 1), + encoding="utf-8", + ) + + doctoring = Path("docs/doctoring/trusted-uv-flat-include-isolation.md") + if doctoring.exists(): + raise SystemExit("doctoring target unexpectedly exists") + doctoring.write_text( + """# Trusted uv flat-include isolation + +## Status + +Accepted on 2026-08-18 for generated base Python lock publication. + +## Buyer-facing failure + +The central coverage lane renames every selected source lock to a generated flat +name such as `requirements-000.txt`. A source file containing a relative `-r` or +`--requirement` directive is valid pip syntax, but pip resolves the target +relative to the generated output location. Publishing only the referrer can +therefore fail a downstream repository before its own tests or docstring checks +execute. + +## Root cause and decision + +Syntax recognition and publication authority were conflated. The bounded +`_is_hash_pinned` diagnostic continues to recognize safe relative include syntax, +but `_is_flat_materializable_lock` admits only non-empty standalone exact +SHA-256 package pins. `base_hash_locks` uses the path-aware candidate predicate, +so independently complete `requirements/ci.txt` and +`service/requirements/package.txt` locks remain eligible. + +No URL, proxy, redirect, package index, caller-controlled header, output path, +review authority, or repository write scope is expanded. Relative include +publication remains fail-closed until the materializer can reconstruct an entire +immutable include graph, preserve source-directory identity, rewrite every edge, +and prove the resulting closure. + +## Verification and operator action + +The RED regression proves that both include spellings previously crossed the +flat boundary and that path-aware nested locks were omitted. GREEN requires the +focused trusted-uv suite, complete central tests, 100% production statement and +branch coverage, complete production docstrings, Python 3.10 and current-stable +compilation, and exact-head protected checks. A downstream repository using +nested requirements should publish one standalone hash-locked closure; operators +must not manually copy or rename an unresolved include. + +## Rollback + +Do not restore relative include publication. A rollback would reintroduce a +source-relative edge into a namespace that no longer preserves source location. +Restore only after a graph-aware implementation has equivalent RED fixtures, +immutable edge rewriting, and full closure verification. + +## APA 7th references + +Python Packaging Authority. (2026). *Requirements file format*. pip +documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +Python Packaging Authority. (2026). *Secure installs*. pip documentation. +https://pip.pypa.io/en/stable/topics/secure-installs/ +""", + encoding="utf-8", + ) + PY + + - name: Set up current stable Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.14" + cache: pip + cache-dependency-path: requirements-opencode-review-ci-hashes.txt + + - name: Install hash-locked quality tooling + run: >- + python -m pip install --disable-pip-version-check --require-hashes + -r requirements-opencode-review-ci-hashes.txt + + - name: Verify exact GREEN on current stable Python + run: | + set -euo pipefail + cat >"${RUNNER_TEMP}/trusted-uv-coveragerc" <<'EOF' + [run] + branch = True + include = + scripts/ci/materialize_base_python_requirements.py + + [report] + fail_under = 100 + show_missing = True + EOF + export COVERAGE_RCFILE="${RUNNER_TEMP}/trusted-uv-coveragerc" + python -m coverage erase + python -m coverage run -m pytest \ + tests/test_materialize_base_python_requirements.py \ + tests/test_materialize_uv_export_hash_contract.py \ + tests/test_trusted_uv_download_contract.py \ + tests/test_trusted_uv_portability_and_streaming.py \ + tests/test_uv_export_isolation_contract.py \ + tests/test_uv_flat_lock_publication_boundary.py \ + tests/test_uv_redirect_and_coverage_contract.py \ + tests/test_uv_redirect_boundary.py \ + tests/test_uv_workspace_fail_closed.py \ + tests/test_trusted_uv_materializer_quality_workflow_contract.py \ + -q + python -m coverage report + unset COVERAGE_RCFILE + python -m coverage erase + python -m coverage run -m pytest tests -q + python -m coverage report + python -m interrogate --fail-under 100 \ + scripts/ci/materialize_base_python_requirements.py + python -m compileall -q \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_uv_flat_lock_publication_boundary.py + git diff --check + + - name: Verify minimum Python compatibility + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.10" + + - name: Compile on minimum supported Python + run: | + set -euo pipefail + python -m compileall -q \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_uv_flat_lock_publication_boundary.py + + - name: Publish verified GREEN and remove one-shot authority + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + rm .github/workflows/one-shot-flat-lock-green.yml + git add -A + git config user.name "CWL One-shot Repair" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "fix(ci): isolate relative includes from flat locks" + git remote set-url origin \ + "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From bdf0d167b1eb440fdea4ef9849d55807775241d9 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:14:05 -0700 Subject: [PATCH 05/12] ci: bind one-shot repair to current trigger --- .../one-shot-flat-lock-bootstrap.yml | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 .github/workflows/one-shot-flat-lock-bootstrap.yml diff --git a/.github/workflows/one-shot-flat-lock-bootstrap.yml b/.github/workflows/one-shot-flat-lock-bootstrap.yml new file mode 100644 index 000000000..983c319bf --- /dev/null +++ b/.github/workflows/one-shot-flat-lock-bootstrap.yml @@ -0,0 +1,68 @@ +name: One-shot Flat Lock Bootstrap + +on: + push: + branches: + - fix/trusted-uv-flat-publication-current-main + paths: + - .github/workflows/one-shot-flat-lock-bootstrap.yml + +permissions: + contents: write + +jobs: + bind-current-trigger: + if: >- + github.repository == 'ContextualWisdomLab/.github' && + github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' + runs-on: ubuntu-24.04 + timeout-minutes: 10 + env: + EXPECTED_PARENT_SHA: af5e8901937720a5613866e94b0fbf2a689c0364 + TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main + steps: + - name: Checkout exact bootstrap trigger + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + ref: ${{ github.sha }} + fetch-depth: 2 + persist-credentials: false + + - name: Bind GREEN workflow to the resulting commit parent + run: | + set -euo pipefail + test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" + test "$(git rev-parse HEAD)" = "$GITHUB_SHA" + python - <<'PY' + import os + from pathlib import Path + + workflow = Path(".github/workflows/one-shot-flat-lock-green.yml") + text = workflow.read_text(encoding="utf-8") + old_parent = "EXPECTED_PARENT_SHA: acfd2faea6c928ead4a3957506d6063558887002" + new_parent = f"EXPECTED_PARENT_SHA: {os.environ['GITHUB_SHA']}" + old_branch_check = ' test "$(git branch --show-current)" = "$TARGET_BRANCH"\n' + new_branch_check = ' test "$GITHUB_REF" = "refs/heads/$TARGET_BRANCH"\n' + if text.count(old_parent) != 1 or text.count(old_branch_check) != 1: + raise SystemExit("one-shot binding boundary drifted") + workflow.write_text( + text.replace(old_parent, new_parent, 1).replace( + old_branch_check, new_branch_check, 1 + ), + encoding="utf-8", + ) + PY + + - name: Publish bound workflow and remove bootstrap + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + rm .github/workflows/one-shot-flat-lock-bootstrap.yml + git add -A + git config user.name "CWL One-shot Bootstrap" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "ci: bind flat-lock GREEN to exact trigger" + git remote set-url origin \ + "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From c3d4205dce7998bc8671121e5e2d8bf88e8b1781 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:16:39 -0700 Subject: [PATCH 06/12] ci: allow exact same-repo PR bootstrap --- .../one-shot-flat-lock-bootstrap.yml | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/.github/workflows/one-shot-flat-lock-bootstrap.yml b/.github/workflows/one-shot-flat-lock-bootstrap.yml index 983c319bf..6e9c3696d 100644 --- a/.github/workflows/one-shot-flat-lock-bootstrap.yml +++ b/.github/workflows/one-shot-flat-lock-bootstrap.yml @@ -6,6 +6,10 @@ on: - fix/trusted-uv-flat-publication-current-main paths: - .github/workflows/one-shot-flat-lock-bootstrap.yml + pull_request: + branches: [main] + paths: + - .github/workflows/one-shot-flat-lock-bootstrap.yml permissions: contents: write @@ -14,17 +18,25 @@ jobs: bind-current-trigger: if: >- github.repository == 'ContextualWisdomLab/.github' && - github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' + ( + github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' || + ( + github.event.pull_request.number == 1124 && + github.event.pull_request.head.repo.full_name == github.repository && + github.event.pull_request.head.ref == 'fix/trusted-uv-flat-publication-current-main' + ) + ) runs-on: ubuntu-24.04 timeout-minutes: 10 env: - EXPECTED_PARENT_SHA: af5e8901937720a5613866e94b0fbf2a689c0364 + EXPECTED_PARENT_SHA: bdf0d167b1eb440fdea4ef9849d55807775241d9 TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main + TRIGGER_SHA: ${{ github.event.pull_request.head.sha || github.sha }} steps: - name: Checkout exact bootstrap trigger uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: - ref: ${{ github.sha }} + ref: ${{ env.TRIGGER_SHA }} fetch-depth: 2 persist-credentials: false @@ -32,7 +44,7 @@ jobs: run: | set -euo pipefail test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" - test "$(git rev-parse HEAD)" = "$GITHUB_SHA" + test "$(git rev-parse HEAD)" = "$TRIGGER_SHA" python - <<'PY' import os from pathlib import Path @@ -40,7 +52,7 @@ jobs: workflow = Path(".github/workflows/one-shot-flat-lock-green.yml") text = workflow.read_text(encoding="utf-8") old_parent = "EXPECTED_PARENT_SHA: acfd2faea6c928ead4a3957506d6063558887002" - new_parent = f"EXPECTED_PARENT_SHA: {os.environ['GITHUB_SHA']}" + new_parent = f"EXPECTED_PARENT_SHA: {os.environ['TRIGGER_SHA']}" old_branch_check = ' test "$(git branch --show-current)" = "$TARGET_BRANCH"\n' new_branch_check = ' test "$GITHUB_REF" = "refs/heads/$TARGET_BRANCH"\n' if text.count(old_parent) != 1 or text.count(old_branch_check) != 1: From 8f747c5e84e0f80b6bca98b88fdc015ccf17e270 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:19:50 -0700 Subject: [PATCH 07/12] ci: run flat-lock GREEN without workflow self-mutation --- .../workflows/one-shot-flat-lock-green-v2.yml | 289 ++++++++++++++++++ 1 file changed, 289 insertions(+) create mode 100644 .github/workflows/one-shot-flat-lock-green-v2.yml diff --git a/.github/workflows/one-shot-flat-lock-green-v2.yml b/.github/workflows/one-shot-flat-lock-green-v2.yml new file mode 100644 index 000000000..2cb41a2a5 --- /dev/null +++ b/.github/workflows/one-shot-flat-lock-green-v2.yml @@ -0,0 +1,289 @@ +name: One-shot Flat Lock GREEN v2 + +on: + push: + branches: + - fix/trusted-uv-flat-publication-current-main + paths: + - .github/workflows/one-shot-flat-lock-green-v2.yml + pull_request: + branches: [main] + paths: + - .github/workflows/one-shot-flat-lock-green-v2.yml + +permissions: + contents: write + +concurrency: + group: one-shot-flat-lock-green-v2 + cancel-in-progress: false + +jobs: + green: + if: >- + github.repository == 'ContextualWisdomLab/.github' && + ( + github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' || + ( + github.event.pull_request.number == 1124 && + github.event.pull_request.head.repo.full_name == github.repository && + github.event.pull_request.head.ref == 'fix/trusted-uv-flat-publication-current-main' + ) + ) + runs-on: ubuntu-24.04 + timeout-minutes: 35 + env: + EXPECTED_PARENT_SHA: c3d4205dce7998bc8671121e5e2d8bf88e8b1781 + TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main + TRIGGER_SHA: ${{ github.event.pull_request.head.sha || github.sha }} + steps: + - name: Harden runner + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 + with: + egress-policy: audit + + - name: Checkout exact trigger + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + ref: ${{ env.TRIGGER_SHA }} + fetch-depth: 2 + persist-credentials: false + + - name: Verify immutable branch boundary + run: | + set -euo pipefail + test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" + test "$(git rev-parse HEAD)" = "$TRIGGER_SHA" + + - name: Apply minimal production correction + run: | + set -euo pipefail + python - <<'PY' + from pathlib import Path + + script_path = Path("scripts/ci/materialize_base_python_requirements.py") + script = script_path.read_text(encoding="utf-8") + old_policy = ''' return all( + _is_fully_hash_pinned_requirement(line) + or _is_bounded_requirement_include(line) + for line in requirement_lines + ) + def _is_fully_hash_pinned_requirement(line: str) -> bool: + ''' + new_policy = ''' return all( + _is_fully_hash_pinned_requirement(line) + or _is_bounded_requirement_include(line) + for line in requirement_lines + ) + + + def _is_flat_materializable_lock(content: bytes) -> bool: + """Return whether content is one standalone exact SHA-256 lock. + + Selected base locks are published under generated flat names. A + source-relative ``-r`` or ``--requirement`` edge therefore loses + the source directory that gives the edge meaning. Only independent + exact package pins cross this boundary until a complete immutable + include graph can be reconstructed and rewritten. + """ + lines = _requirement_lines(content) + requirement_lines = [ + line for line in lines if line != "--require-hashes" + ] + return bool(requirement_lines) and all( + _is_fully_hash_pinned_requirement(line) + for line in requirement_lines + ) + + + def _is_fully_hash_pinned_requirement(line: str) -> bool: + ''' + if script.count(old_policy) != 1: + raise SystemExit("flat-lock policy insertion point drifted") + script = script.replace(old_policy, new_policy, 1) + + old_selection = ''' if _is_candidate_lock_name(candidate.name): + content = _git(repo_root, "show", f"{base_sha}:{path}") + if _is_hash_pinned(content): + locks.append((path, content)) + ''' + new_selection = ''' if _is_candidate_lock_path(candidate): + content = _git(repo_root, "show", f"{base_sha}:{path}") + if _is_flat_materializable_lock(content): + locks.append((path, content)) + ''' + if script.count(old_selection) != 1: + raise SystemExit("base-lock selection boundary drifted") + script_path.write_text( + script.replace(old_selection, new_selection, 1), + encoding="utf-8", + ) + + old_test = Path("tests/test_flat_lock_publication_boundary.py") + new_test = Path("tests/test_uv_flat_lock_publication_boundary.py") + if not old_test.is_file() or new_test.exists(): + raise SystemExit("RED regression path drifted") + old_test.replace(new_test) + + changelog_path = Path("CHANGELOG.md") + changelog = changelog_path.read_text(encoding="utf-8") + stale = "- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context." + replacement = "- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories." + if changelog.count(stale) != 1: + raise SystemExit("trusted-uv changelog statement drifted") + changelog_path.write_text( + changelog.replace(stale, replacement, 1), + encoding="utf-8", + ) + + doctoring = Path("docs/doctoring/trusted-uv-flat-include-isolation.md") + if doctoring.exists(): + raise SystemExit("doctoring target unexpectedly exists") + doctoring.write_text( + """# Trusted uv flat-include isolation + +## Status + +Accepted on 2026-08-18 for generated base Python lock publication. + +## Buyer-facing failure + +The central coverage lane renames every selected source lock to a generated flat +name such as `requirements-000.txt`. A source file containing a relative `-r` or +`--requirement` directive is valid pip syntax, but pip resolves the target +relative to the generated output location. Publishing only the referrer can +therefore fail a downstream repository before its own tests or docstring checks +execute. + +## Root cause and decision + +Syntax recognition and publication authority were conflated. The bounded +`_is_hash_pinned` diagnostic continues to recognize safe relative include syntax, +but `_is_flat_materializable_lock` admits only non-empty standalone exact +SHA-256 package pins. `base_hash_locks` uses the path-aware candidate predicate, +so independently complete `requirements/ci.txt` and +`service/requirements/package.txt` locks remain eligible. + +No URL, proxy, redirect, package index, caller-controlled header, output path, +review authority, or repository write scope is expanded. Relative include +publication remains fail-closed until the materializer can reconstruct an entire +immutable include graph, preserve source-directory identity, rewrite every edge, +and prove the resulting closure. + +## Verification and operator action + +The RED regression proves that both include spellings previously crossed the +flat boundary and that path-aware nested locks were omitted. GREEN requires the +focused trusted-uv suite, complete central tests, 100% production statement and +branch coverage, complete production docstrings, Python 3.10 and current-stable +compilation, and exact-head protected checks. A downstream repository using +nested requirements should publish one standalone hash-locked closure; operators +must not manually copy or rename an unresolved include. + +## Rollback + +Do not restore relative include publication. A rollback would reintroduce a +source-relative edge into a namespace that no longer preserves source location. +Restore only after a graph-aware implementation has equivalent RED fixtures, +immutable edge rewriting, and full closure verification. + +## APA 7th references + +Python Packaging Authority. (2026). *Requirements file format*. pip +documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +Python Packaging Authority. (2026). *Secure installs*. pip documentation. +https://pip.pypa.io/en/stable/topics/secure-installs/ +""", + encoding="utf-8", + ) + PY + + - name: Remove temporary workflows from the verification tree + run: | + set -euo pipefail + rm -f \ + .github/workflows/one-shot-flat-lock-bootstrap.yml \ + .github/workflows/one-shot-flat-lock-green.yml \ + .github/workflows/one-shot-flat-lock-green-v2.yml + + - name: Set up current stable Python + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.14" + cache: pip + cache-dependency-path: requirements-opencode-review-ci-hashes.txt + + - name: Install hash-locked quality tooling + run: >- + python -m pip install --disable-pip-version-check --require-hashes + -r requirements-opencode-review-ci-hashes.txt + + - name: Verify exact GREEN on current stable Python + run: | + set -euo pipefail + cat >"${RUNNER_TEMP}/trusted-uv-coveragerc" <<'EOF' + [run] + branch = True + include = + scripts/ci/materialize_base_python_requirements.py + + [report] + fail_under = 100 + show_missing = True + EOF + export COVERAGE_RCFILE="${RUNNER_TEMP}/trusted-uv-coveragerc" + python -m coverage erase + python -m coverage run -m pytest \ + tests/test_materialize_base_python_requirements.py \ + tests/test_materialize_uv_export_hash_contract.py \ + tests/test_trusted_uv_download_contract.py \ + tests/test_trusted_uv_portability_and_streaming.py \ + tests/test_uv_export_isolation_contract.py \ + tests/test_uv_flat_lock_publication_boundary.py \ + tests/test_uv_redirect_and_coverage_contract.py \ + tests/test_uv_redirect_boundary.py \ + tests/test_uv_workspace_fail_closed.py \ + tests/test_trusted_uv_materializer_quality_workflow_contract.py \ + -q + python -m coverage report + unset COVERAGE_RCFILE + python -m coverage erase + python -m coverage run -m pytest tests -q + python -m coverage report + python -m interrogate --fail-under 100 \ + scripts/ci/materialize_base_python_requirements.py + python -m compileall -q \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_uv_flat_lock_publication_boundary.py + git diff --check + + - name: Verify minimum Python compatibility + uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 + with: + python-version: "3.10" + + - name: Compile on minimum supported Python + run: | + set -euo pipefail + python -m compileall -q \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_uv_flat_lock_publication_boundary.py + + - name: Publish verified production correction + env: + GH_TOKEN: ${{ github.token }} + run: | + set -euo pipefail + git add \ + CHANGELOG.md \ + docs/doctoring/trusted-uv-flat-include-isolation.md \ + scripts/ci/materialize_base_python_requirements.py \ + tests/test_flat_lock_publication_boundary.py \ + tests/test_uv_flat_lock_publication_boundary.py + git config user.name "CWL One-shot Repair" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "fix(ci): isolate relative includes from flat locks" + git remote set-url origin \ + "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" + git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From 6e29897bd28a0a41ced8402681e60c860c27baeb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:21:01 -0700 Subject: [PATCH 08/12] chore(ci): remove failed bootstrap workflow --- .../one-shot-flat-lock-bootstrap.yml | 80 ------------------- 1 file changed, 80 deletions(-) delete mode 100644 .github/workflows/one-shot-flat-lock-bootstrap.yml diff --git a/.github/workflows/one-shot-flat-lock-bootstrap.yml b/.github/workflows/one-shot-flat-lock-bootstrap.yml deleted file mode 100644 index 6e9c3696d..000000000 --- a/.github/workflows/one-shot-flat-lock-bootstrap.yml +++ /dev/null @@ -1,80 +0,0 @@ -name: One-shot Flat Lock Bootstrap - -on: - push: - branches: - - fix/trusted-uv-flat-publication-current-main - paths: - - .github/workflows/one-shot-flat-lock-bootstrap.yml - pull_request: - branches: [main] - paths: - - .github/workflows/one-shot-flat-lock-bootstrap.yml - -permissions: - contents: write - -jobs: - bind-current-trigger: - if: >- - github.repository == 'ContextualWisdomLab/.github' && - ( - github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' || - ( - github.event.pull_request.number == 1124 && - github.event.pull_request.head.repo.full_name == github.repository && - github.event.pull_request.head.ref == 'fix/trusted-uv-flat-publication-current-main' - ) - ) - runs-on: ubuntu-24.04 - timeout-minutes: 10 - env: - EXPECTED_PARENT_SHA: bdf0d167b1eb440fdea4ef9849d55807775241d9 - TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main - TRIGGER_SHA: ${{ github.event.pull_request.head.sha || github.sha }} - steps: - - name: Checkout exact bootstrap trigger - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - with: - ref: ${{ env.TRIGGER_SHA }} - fetch-depth: 2 - persist-credentials: false - - - name: Bind GREEN workflow to the resulting commit parent - run: | - set -euo pipefail - test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" - test "$(git rev-parse HEAD)" = "$TRIGGER_SHA" - python - <<'PY' - import os - from pathlib import Path - - workflow = Path(".github/workflows/one-shot-flat-lock-green.yml") - text = workflow.read_text(encoding="utf-8") - old_parent = "EXPECTED_PARENT_SHA: acfd2faea6c928ead4a3957506d6063558887002" - new_parent = f"EXPECTED_PARENT_SHA: {os.environ['TRIGGER_SHA']}" - old_branch_check = ' test "$(git branch --show-current)" = "$TARGET_BRANCH"\n' - new_branch_check = ' test "$GITHUB_REF" = "refs/heads/$TARGET_BRANCH"\n' - if text.count(old_parent) != 1 or text.count(old_branch_check) != 1: - raise SystemExit("one-shot binding boundary drifted") - workflow.write_text( - text.replace(old_parent, new_parent, 1).replace( - old_branch_check, new_branch_check, 1 - ), - encoding="utf-8", - ) - PY - - - name: Publish bound workflow and remove bootstrap - env: - GH_TOKEN: ${{ github.token }} - run: | - set -euo pipefail - rm .github/workflows/one-shot-flat-lock-bootstrap.yml - git add -A - git config user.name "CWL One-shot Bootstrap" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git commit -m "ci: bind flat-lock GREEN to exact trigger" - git remote set-url origin \ - "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From 56a0b0f132ad271fcdc1b6dcf67a8a5fb509828c Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:21:16 -0700 Subject: [PATCH 09/12] chore(ci): remove superseded one-shot workflow --- .../workflows/one-shot-flat-lock-green.yml | 281 ------------------ 1 file changed, 281 deletions(-) delete mode 100644 .github/workflows/one-shot-flat-lock-green.yml diff --git a/.github/workflows/one-shot-flat-lock-green.yml b/.github/workflows/one-shot-flat-lock-green.yml deleted file mode 100644 index 9100ee0e9..000000000 --- a/.github/workflows/one-shot-flat-lock-green.yml +++ /dev/null @@ -1,281 +0,0 @@ -name: One-shot Flat Lock GREEN - -on: - push: - branches: - - fix/trusted-uv-flat-publication-current-main - paths: - - .github/workflows/one-shot-flat-lock-green.yml - -permissions: - contents: write - -concurrency: - group: one-shot-flat-lock-green - cancel-in-progress: false - -jobs: - green: - if: >- - github.repository == 'ContextualWisdomLab/.github' && - github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' - runs-on: ubuntu-24.04 - timeout-minutes: 35 - env: - EXPECTED_PARENT_SHA: acfd2faea6c928ead4a3957506d6063558887002 - TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main - steps: - - name: Harden runner - uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 - with: - egress-policy: audit - - - name: Checkout exact trigger - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - with: - ref: ${{ github.sha }} - fetch-depth: 2 - persist-credentials: false - - - name: Verify immutable branch boundary - run: | - set -euo pipefail - test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" - test "$(git rev-parse HEAD)" = "$GITHUB_SHA" - test "$(git rev-list --count HEAD^..HEAD)" = "1" - test "$(git branch --show-current)" = "$TARGET_BRANCH" - - - name: Apply minimal production correction - run: | - set -euo pipefail - python - <<'PY' - from pathlib import Path - - script_path = Path("scripts/ci/materialize_base_python_requirements.py") - script = script_path.read_text(encoding="utf-8") - old_policy = ''' return all( - _is_fully_hash_pinned_requirement(line) - or _is_bounded_requirement_include(line) - for line in requirement_lines - ) - def _is_fully_hash_pinned_requirement(line: str) -> bool: - ''' - new_policy = ''' return all( - _is_fully_hash_pinned_requirement(line) - or _is_bounded_requirement_include(line) - for line in requirement_lines - ) - - - def _is_flat_materializable_lock(content: bytes) -> bool: - """Return whether content is one standalone exact SHA-256 lock. - - Selected base locks are published under generated flat names. A - source-relative ``-r`` or ``--requirement`` edge therefore loses - the source directory that gives the edge meaning. Only independent - exact package pins cross this boundary until a complete immutable - include graph can be reconstructed and rewritten. - """ - lines = _requirement_lines(content) - requirement_lines = [ - line for line in lines if line != "--require-hashes" - ] - return bool(requirement_lines) and all( - _is_fully_hash_pinned_requirement(line) - for line in requirement_lines - ) - - - def _is_fully_hash_pinned_requirement(line: str) -> bool: - ''' - if script.count(old_policy) != 1: - raise SystemExit("flat-lock policy insertion point drifted") - script = script.replace(old_policy, new_policy, 1) - - old_selection = ''' if _is_candidate_lock_name(candidate.name): - content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_hash_pinned(content): - locks.append((path, content)) - ''' - new_selection = ''' if _is_candidate_lock_path(candidate): - content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_flat_materializable_lock(content): - locks.append((path, content)) - ''' - if script.count(old_selection) != 1: - raise SystemExit("base-lock selection boundary drifted") - script_path.write_text( - script.replace(old_selection, new_selection, 1), - encoding="utf-8", - ) - - old_test = Path("tests/test_flat_lock_publication_boundary.py") - new_test = Path("tests/test_uv_flat_lock_publication_boundary.py") - if not old_test.is_file() or new_test.exists(): - raise SystemExit("RED regression path drifted") - old_test.replace(new_test) - - quality_path = Path(".github/workflows/trusted-uv-materializer-quality-ci.yml") - quality = quality_path.read_text(encoding="utf-8") - anchor = " tests/test_uv_export_isolation_contract.py \\\n" - if quality.count(anchor) != 2: - raise SystemExit("trusted-uv focused list drifted") - quality_path.write_text( - quality.replace( - anchor, - anchor - + " tests/test_uv_flat_lock_publication_boundary.py \\\n", - ), - encoding="utf-8", - ) - - changelog_path = Path("CHANGELOG.md") - changelog = changelog_path.read_text(encoding="utf-8") - stale = "- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context." - replacement = "- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories." - if changelog.count(stale) != 1: - raise SystemExit("trusted-uv changelog statement drifted") - changelog_path.write_text( - changelog.replace(stale, replacement, 1), - encoding="utf-8", - ) - - doctoring = Path("docs/doctoring/trusted-uv-flat-include-isolation.md") - if doctoring.exists(): - raise SystemExit("doctoring target unexpectedly exists") - doctoring.write_text( - """# Trusted uv flat-include isolation - -## Status - -Accepted on 2026-08-18 for generated base Python lock publication. - -## Buyer-facing failure - -The central coverage lane renames every selected source lock to a generated flat -name such as `requirements-000.txt`. A source file containing a relative `-r` or -`--requirement` directive is valid pip syntax, but pip resolves the target -relative to the generated output location. Publishing only the referrer can -therefore fail a downstream repository before its own tests or docstring checks -execute. - -## Root cause and decision - -Syntax recognition and publication authority were conflated. The bounded -`_is_hash_pinned` diagnostic continues to recognize safe relative include syntax, -but `_is_flat_materializable_lock` admits only non-empty standalone exact -SHA-256 package pins. `base_hash_locks` uses the path-aware candidate predicate, -so independently complete `requirements/ci.txt` and -`service/requirements/package.txt` locks remain eligible. - -No URL, proxy, redirect, package index, caller-controlled header, output path, -review authority, or repository write scope is expanded. Relative include -publication remains fail-closed until the materializer can reconstruct an entire -immutable include graph, preserve source-directory identity, rewrite every edge, -and prove the resulting closure. - -## Verification and operator action - -The RED regression proves that both include spellings previously crossed the -flat boundary and that path-aware nested locks were omitted. GREEN requires the -focused trusted-uv suite, complete central tests, 100% production statement and -branch coverage, complete production docstrings, Python 3.10 and current-stable -compilation, and exact-head protected checks. A downstream repository using -nested requirements should publish one standalone hash-locked closure; operators -must not manually copy or rename an unresolved include. - -## Rollback - -Do not restore relative include publication. A rollback would reintroduce a -source-relative edge into a namespace that no longer preserves source location. -Restore only after a graph-aware implementation has equivalent RED fixtures, -immutable edge rewriting, and full closure verification. - -## APA 7th references - -Python Packaging Authority. (2026). *Requirements file format*. pip -documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -Python Packaging Authority. (2026). *Secure installs*. pip documentation. -https://pip.pypa.io/en/stable/topics/secure-installs/ -""", - encoding="utf-8", - ) - PY - - - name: Set up current stable Python - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.14" - cache: pip - cache-dependency-path: requirements-opencode-review-ci-hashes.txt - - - name: Install hash-locked quality tooling - run: >- - python -m pip install --disable-pip-version-check --require-hashes - -r requirements-opencode-review-ci-hashes.txt - - - name: Verify exact GREEN on current stable Python - run: | - set -euo pipefail - cat >"${RUNNER_TEMP}/trusted-uv-coveragerc" <<'EOF' - [run] - branch = True - include = - scripts/ci/materialize_base_python_requirements.py - - [report] - fail_under = 100 - show_missing = True - EOF - export COVERAGE_RCFILE="${RUNNER_TEMP}/trusted-uv-coveragerc" - python -m coverage erase - python -m coverage run -m pytest \ - tests/test_materialize_base_python_requirements.py \ - tests/test_materialize_uv_export_hash_contract.py \ - tests/test_trusted_uv_download_contract.py \ - tests/test_trusted_uv_portability_and_streaming.py \ - tests/test_uv_export_isolation_contract.py \ - tests/test_uv_flat_lock_publication_boundary.py \ - tests/test_uv_redirect_and_coverage_contract.py \ - tests/test_uv_redirect_boundary.py \ - tests/test_uv_workspace_fail_closed.py \ - tests/test_trusted_uv_materializer_quality_workflow_contract.py \ - -q - python -m coverage report - unset COVERAGE_RCFILE - python -m coverage erase - python -m coverage run -m pytest tests -q - python -m coverage report - python -m interrogate --fail-under 100 \ - scripts/ci/materialize_base_python_requirements.py - python -m compileall -q \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_uv_flat_lock_publication_boundary.py - git diff --check - - - name: Verify minimum Python compatibility - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.10" - - - name: Compile on minimum supported Python - run: | - set -euo pipefail - python -m compileall -q \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_uv_flat_lock_publication_boundary.py - - - name: Publish verified GREEN and remove one-shot authority - env: - GH_TOKEN: ${{ github.token }} - run: | - set -euo pipefail - rm .github/workflows/one-shot-flat-lock-green.yml - git add -A - git config user.name "CWL One-shot Repair" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git commit -m "fix(ci): isolate relative includes from flat locks" - git remote set-url origin \ - "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From 939b752a8159eaef711f34eb1f18aa1223fda7a4 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:22:18 -0700 Subject: [PATCH 10/12] ci: bind flat-lock GREEN to cleaned trigger --- .github/workflows/one-shot-flat-lock-green-v2.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/one-shot-flat-lock-green-v2.yml b/.github/workflows/one-shot-flat-lock-green-v2.yml index 2cb41a2a5..0f7c401d8 100644 --- a/.github/workflows/one-shot-flat-lock-green-v2.yml +++ b/.github/workflows/one-shot-flat-lock-green-v2.yml @@ -33,7 +33,7 @@ jobs: runs-on: ubuntu-24.04 timeout-minutes: 35 env: - EXPECTED_PARENT_SHA: c3d4205dce7998bc8671121e5e2d8bf88e8b1781 + EXPECTED_PARENT_SHA: 56a0b0f132ad271fcdc1b6dcf67a8a5fb509828c TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main TRIGGER_SHA: ${{ github.event.pull_request.head.sha || github.sha }} steps: @@ -202,10 +202,7 @@ https://pip.pypa.io/en/stable/topics/secure-installs/ - name: Remove temporary workflows from the verification tree run: | set -euo pipefail - rm -f \ - .github/workflows/one-shot-flat-lock-bootstrap.yml \ - .github/workflows/one-shot-flat-lock-green.yml \ - .github/workflows/one-shot-flat-lock-green-v2.yml + rm -f .github/workflows/one-shot-flat-lock-green-v2.yml - name: Set up current stable Python uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 From dc1e31a0c4d8c0ecd7098f95d1c24b18ee591530 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:36:57 -0700 Subject: [PATCH 11/12] chore(ci): remove temporary flat-lock workflow --- .../workflows/one-shot-flat-lock-green-v2.yml | 286 ------------------ 1 file changed, 286 deletions(-) delete mode 100644 .github/workflows/one-shot-flat-lock-green-v2.yml diff --git a/.github/workflows/one-shot-flat-lock-green-v2.yml b/.github/workflows/one-shot-flat-lock-green-v2.yml deleted file mode 100644 index 0f7c401d8..000000000 --- a/.github/workflows/one-shot-flat-lock-green-v2.yml +++ /dev/null @@ -1,286 +0,0 @@ -name: One-shot Flat Lock GREEN v2 - -on: - push: - branches: - - fix/trusted-uv-flat-publication-current-main - paths: - - .github/workflows/one-shot-flat-lock-green-v2.yml - pull_request: - branches: [main] - paths: - - .github/workflows/one-shot-flat-lock-green-v2.yml - -permissions: - contents: write - -concurrency: - group: one-shot-flat-lock-green-v2 - cancel-in-progress: false - -jobs: - green: - if: >- - github.repository == 'ContextualWisdomLab/.github' && - ( - github.ref == 'refs/heads/fix/trusted-uv-flat-publication-current-main' || - ( - github.event.pull_request.number == 1124 && - github.event.pull_request.head.repo.full_name == github.repository && - github.event.pull_request.head.ref == 'fix/trusted-uv-flat-publication-current-main' - ) - ) - runs-on: ubuntu-24.04 - timeout-minutes: 35 - env: - EXPECTED_PARENT_SHA: 56a0b0f132ad271fcdc1b6dcf67a8a5fb509828c - TARGET_BRANCH: fix/trusted-uv-flat-publication-current-main - TRIGGER_SHA: ${{ github.event.pull_request.head.sha || github.sha }} - steps: - - name: Harden runner - uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 - with: - egress-policy: audit - - - name: Checkout exact trigger - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - with: - ref: ${{ env.TRIGGER_SHA }} - fetch-depth: 2 - persist-credentials: false - - - name: Verify immutable branch boundary - run: | - set -euo pipefail - test "$(git rev-parse HEAD^)" = "$EXPECTED_PARENT_SHA" - test "$(git rev-parse HEAD)" = "$TRIGGER_SHA" - - - name: Apply minimal production correction - run: | - set -euo pipefail - python - <<'PY' - from pathlib import Path - - script_path = Path("scripts/ci/materialize_base_python_requirements.py") - script = script_path.read_text(encoding="utf-8") - old_policy = ''' return all( - _is_fully_hash_pinned_requirement(line) - or _is_bounded_requirement_include(line) - for line in requirement_lines - ) - def _is_fully_hash_pinned_requirement(line: str) -> bool: - ''' - new_policy = ''' return all( - _is_fully_hash_pinned_requirement(line) - or _is_bounded_requirement_include(line) - for line in requirement_lines - ) - - - def _is_flat_materializable_lock(content: bytes) -> bool: - """Return whether content is one standalone exact SHA-256 lock. - - Selected base locks are published under generated flat names. A - source-relative ``-r`` or ``--requirement`` edge therefore loses - the source directory that gives the edge meaning. Only independent - exact package pins cross this boundary until a complete immutable - include graph can be reconstructed and rewritten. - """ - lines = _requirement_lines(content) - requirement_lines = [ - line for line in lines if line != "--require-hashes" - ] - return bool(requirement_lines) and all( - _is_fully_hash_pinned_requirement(line) - for line in requirement_lines - ) - - - def _is_fully_hash_pinned_requirement(line: str) -> bool: - ''' - if script.count(old_policy) != 1: - raise SystemExit("flat-lock policy insertion point drifted") - script = script.replace(old_policy, new_policy, 1) - - old_selection = ''' if _is_candidate_lock_name(candidate.name): - content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_hash_pinned(content): - locks.append((path, content)) - ''' - new_selection = ''' if _is_candidate_lock_path(candidate): - content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_flat_materializable_lock(content): - locks.append((path, content)) - ''' - if script.count(old_selection) != 1: - raise SystemExit("base-lock selection boundary drifted") - script_path.write_text( - script.replace(old_selection, new_selection, 1), - encoding="utf-8", - ) - - old_test = Path("tests/test_flat_lock_publication_boundary.py") - new_test = Path("tests/test_uv_flat_lock_publication_boundary.py") - if not old_test.is_file() or new_test.exists(): - raise SystemExit("RED regression path drifted") - old_test.replace(new_test) - - changelog_path = Path("CHANGELOG.md") - changelog = changelog_path.read_text(encoding="utf-8") - stale = "- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context." - replacement = "- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories." - if changelog.count(stale) != 1: - raise SystemExit("trusted-uv changelog statement drifted") - changelog_path.write_text( - changelog.replace(stale, replacement, 1), - encoding="utf-8", - ) - - doctoring = Path("docs/doctoring/trusted-uv-flat-include-isolation.md") - if doctoring.exists(): - raise SystemExit("doctoring target unexpectedly exists") - doctoring.write_text( - """# Trusted uv flat-include isolation - -## Status - -Accepted on 2026-08-18 for generated base Python lock publication. - -## Buyer-facing failure - -The central coverage lane renames every selected source lock to a generated flat -name such as `requirements-000.txt`. A source file containing a relative `-r` or -`--requirement` directive is valid pip syntax, but pip resolves the target -relative to the generated output location. Publishing only the referrer can -therefore fail a downstream repository before its own tests or docstring checks -execute. - -## Root cause and decision - -Syntax recognition and publication authority were conflated. The bounded -`_is_hash_pinned` diagnostic continues to recognize safe relative include syntax, -but `_is_flat_materializable_lock` admits only non-empty standalone exact -SHA-256 package pins. `base_hash_locks` uses the path-aware candidate predicate, -so independently complete `requirements/ci.txt` and -`service/requirements/package.txt` locks remain eligible. - -No URL, proxy, redirect, package index, caller-controlled header, output path, -review authority, or repository write scope is expanded. Relative include -publication remains fail-closed until the materializer can reconstruct an entire -immutable include graph, preserve source-directory identity, rewrite every edge, -and prove the resulting closure. - -## Verification and operator action - -The RED regression proves that both include spellings previously crossed the -flat boundary and that path-aware nested locks were omitted. GREEN requires the -focused trusted-uv suite, complete central tests, 100% production statement and -branch coverage, complete production docstrings, Python 3.10 and current-stable -compilation, and exact-head protected checks. A downstream repository using -nested requirements should publish one standalone hash-locked closure; operators -must not manually copy or rename an unresolved include. - -## Rollback - -Do not restore relative include publication. A rollback would reintroduce a -source-relative edge into a namespace that no longer preserves source location. -Restore only after a graph-aware implementation has equivalent RED fixtures, -immutable edge rewriting, and full closure verification. - -## APA 7th references - -Python Packaging Authority. (2026). *Requirements file format*. pip -documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ - -Python Packaging Authority. (2026). *Secure installs*. pip documentation. -https://pip.pypa.io/en/stable/topics/secure-installs/ -""", - encoding="utf-8", - ) - PY - - - name: Remove temporary workflows from the verification tree - run: | - set -euo pipefail - rm -f .github/workflows/one-shot-flat-lock-green-v2.yml - - - name: Set up current stable Python - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.14" - cache: pip - cache-dependency-path: requirements-opencode-review-ci-hashes.txt - - - name: Install hash-locked quality tooling - run: >- - python -m pip install --disable-pip-version-check --require-hashes - -r requirements-opencode-review-ci-hashes.txt - - - name: Verify exact GREEN on current stable Python - run: | - set -euo pipefail - cat >"${RUNNER_TEMP}/trusted-uv-coveragerc" <<'EOF' - [run] - branch = True - include = - scripts/ci/materialize_base_python_requirements.py - - [report] - fail_under = 100 - show_missing = True - EOF - export COVERAGE_RCFILE="${RUNNER_TEMP}/trusted-uv-coveragerc" - python -m coverage erase - python -m coverage run -m pytest \ - tests/test_materialize_base_python_requirements.py \ - tests/test_materialize_uv_export_hash_contract.py \ - tests/test_trusted_uv_download_contract.py \ - tests/test_trusted_uv_portability_and_streaming.py \ - tests/test_uv_export_isolation_contract.py \ - tests/test_uv_flat_lock_publication_boundary.py \ - tests/test_uv_redirect_and_coverage_contract.py \ - tests/test_uv_redirect_boundary.py \ - tests/test_uv_workspace_fail_closed.py \ - tests/test_trusted_uv_materializer_quality_workflow_contract.py \ - -q - python -m coverage report - unset COVERAGE_RCFILE - python -m coverage erase - python -m coverage run -m pytest tests -q - python -m coverage report - python -m interrogate --fail-under 100 \ - scripts/ci/materialize_base_python_requirements.py - python -m compileall -q \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_uv_flat_lock_publication_boundary.py - git diff --check - - - name: Verify minimum Python compatibility - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 - with: - python-version: "3.10" - - - name: Compile on minimum supported Python - run: | - set -euo pipefail - python -m compileall -q \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_uv_flat_lock_publication_boundary.py - - - name: Publish verified production correction - env: - GH_TOKEN: ${{ github.token }} - run: | - set -euo pipefail - git add \ - CHANGELOG.md \ - docs/doctoring/trusted-uv-flat-include-isolation.md \ - scripts/ci/materialize_base_python_requirements.py \ - tests/test_flat_lock_publication_boundary.py \ - tests/test_uv_flat_lock_publication_boundary.py - git config user.name "CWL One-shot Repair" - git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git commit -m "fix(ci): isolate relative includes from flat locks" - git remote set-url origin \ - "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" - git push origin "HEAD:refs/heads/${TARGET_BRANCH}" From d82718d1011bbcf8acc842159d91972daef4f7d1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 18 Aug 2026 06:43:04 -0700 Subject: [PATCH 12/12] fix(ci): isolate relative includes from flat locks Separate bounded requirements syntax recognition from generated flat-file publication authority. Publish only standalone exact SHA-256 closures, retain path-aware discovery for complete requirements-directory locks, and bind the regression to the permanent trusted-uv quality gate. --- .../trusted-uv-materializer-quality-ci.yml | 2 + CHANGELOG.md | 4 +- .../trusted-uv-flat-include-isolation.md | 79 +++++++++++++++++++ .../materialize_base_python_requirements.py | 24 +++++- ...test_uv_flat_lock_publication_boundary.py} | 17 ++++ 5 files changed, 120 insertions(+), 6 deletions(-) create mode 100644 docs/doctoring/trusted-uv-flat-include-isolation.md rename tests/{test_flat_lock_publication_boundary.py => test_uv_flat_lock_publication_boundary.py} (84%) diff --git a/.github/workflows/trusted-uv-materializer-quality-ci.yml b/.github/workflows/trusted-uv-materializer-quality-ci.yml index 95642b55c..a3404232b 100644 --- a/.github/workflows/trusted-uv-materializer-quality-ci.yml +++ b/.github/workflows/trusted-uv-materializer-quality-ci.yml @@ -129,6 +129,7 @@ jobs: tests/test_trusted_uv_download_contract.py \ tests/test_trusted_uv_portability_and_streaming.py \ tests/test_uv_export_isolation_contract.py \ + tests/test_uv_flat_lock_publication_boundary.py \ tests/test_uv_redirect_and_coverage_contract.py \ tests/test_uv_redirect_boundary.py \ tests/test_uv_workspace_fail_closed.py \ @@ -155,6 +156,7 @@ jobs: tests/test_trusted_uv_download_contract.py \ tests/test_trusted_uv_portability_and_streaming.py \ tests/test_uv_export_isolation_contract.py \ + tests/test_uv_flat_lock_publication_boundary.py \ tests/test_uv_redirect_and_coverage_contract.py \ tests/test_uv_redirect_boundary.py \ tests/test_uv_workspace_fail_closed.py \ diff --git a/CHANGELOG.md b/CHANGELOG.md index e385d7e12..3897f04a8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,7 +33,7 @@ Semantic Versioning where the repository publishes a release. - Parsed `opencode.jsonc` as JSONC (stripping `//` and `/* */` comments outside string literals) in the reasoning-effort guard and its contract tests, instead of raw `json.loads`, which rejected the file the moment it carried its first explanatory comment (added for the `contextual-orchestrator` provider block) with `Expecting property name enclosed in double quotes`. Comment markers inside string values, such as the `$schema` URL, are left untouched. - Download the pinned `uv` 0.12.1 exporter from the official GitHub Releases URL instead of `releases.astral.sh`, which now returns HTTP 403 and blocks org-wide OpenCode `coverage-evidence`. The SHA-256 pin is unchanged. The opener may follow one hop onto `release-assets.githubusercontent.com` or `objects.githubusercontent.com` and still rejects every other host, userinfo, non-HTTPS scheme, and nondefault port (ContextualWisdomLab/.github#1109). -- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context. +- Excluded relative `-r` and `--requirement` referrers from generated flat base-lock publication while retaining bounded include syntax diagnostics and discovering independently complete direct `.txt` children of `requirements` directories. - Refused a conflict-scope repository root whose immediate parent is a symbolic link, so a swapped parent cannot redirect the canonical worktree after the last-component check (CWE-367). - Bounded the Strix quality self-test's deterministic timeout fixtures to 3-second process and 5-second fake-sleep budgets so exact-head policy evidence completes inside the existing job limit without changing production Strix scanner timeouts, providers, credentials, or review semantics. - Allowed commas and ASCII parentheses in the bounded Strix changed-file path policy so legal tracked Packrat fixtures can receive exact-head security analysis, while rejecting raw `..` components before normalization and keeping controls, backslashes, whitespace ambiguity, and shell punctuation fail-closed. @@ -67,4 +67,4 @@ Semantic Versioning where the repository publishes a release. - Added DiskSage operational documentation for the hourly RCA loop, bounded retry cadence, permission model, standalone and MSA reuse, verification, rollback, and APA 7 references. - Added fast-mlsirm operational documentation for the hourly RCA loop, psychometric scientific gates, Rust ownership, bounded retry cadence, credential isolation, modular reuse, rollback, and APA 7 references. - Documented the ordinary and conflict repair write-scope parity, ignored-path and symlink inventory, Git-control-file denial, hook suppression, explicit push destination, RED/GREEN evidence, operator response, and local-versus-protected evidence boundary. -- Documented the review-authentication boundary that excludes autonomous writer control-plane paths from review-derived file authority, its test-first Strix security evidence, exact-head coverage contract, and rollback prohibition. \ No newline at end of file +- Documented the review-authentication boundary that excludes autonomous writer control-plane paths from review-derived file authority, its test-first Strix security evidence, exact-head coverage contract, and rollback prohibition. diff --git a/docs/doctoring/trusted-uv-flat-include-isolation.md b/docs/doctoring/trusted-uv-flat-include-isolation.md new file mode 100644 index 000000000..1f5178aae --- /dev/null +++ b/docs/doctoring/trusted-uv-flat-include-isolation.md @@ -0,0 +1,79 @@ +# Trusted uv flat-include isolation + +## Status + +Accepted on 2026-08-18 for generated base Python lock publication. + +## Buyer-facing failure + +The central coverage lane renames every selected source lock to a generated flat +name such as `requirements-000.txt`. A source requirements file containing a +relative `-r` or `--requirement` directive is valid pip syntax, but pip resolves +the referenced path relative to the generated output location. Publishing only +the referrer can therefore fail a downstream repository before its own tests, +branch coverage, or docstring evidence executes. + +## Root cause and decision + +The previous implementation conflated two authority boundaries: + +- `_is_hash_pinned` answers whether a source file uses bounded requirements + syntax, including a normalized relative include; and +- `base_hash_locks` decides whether one source blob can be copied independently + under a generated flat name. + +A bounded relative include may pass the first question while failing the second. +The materializer now keeps bounded-include syntax diagnostics unchanged but uses +`_is_flat_materializable_lock` for publication. That predicate admits only a +non-empty, standalone closure whose logical requirement lines are exact `==` +pins carrying complete SHA-256 hashes. `base_hash_locks` also uses the existing +path-aware candidate predicate, so independently complete direct `.txt` children +such as `requirements/ci.txt` and `service/requirements/package.txt` remain +eligible. + +## Security and ownership boundary + +No URL, proxy, redirect, package index, caller-controlled header, output path, +review authority, credential, or repository write scope is expanded. The fixed +GitHub Releases uv download and redirect boundary is unchanged. Relative include +publication remains fail-closed until a separately reviewed implementation can +reconstruct the complete immutable include graph, preserve source-directory +identity, rewrite every edge, and prove the resulting closure. + +This is a central `.github` materialization correction. Product repositories, +including BandScope, retain ownership of their own requirements, tests, and +runtime behavior. The central workflow must not edit a downstream product merely +to work around a generated-path defect. + +## Verification and operator action + +The regression suite proves all of the following: + +1. both `-r` and `--requirement` referrers are excluded from flat publication; +2. an independently complete referenced lock remains eligible; +3. complete direct `.txt` children of a directory named `requirements` are + discovered; and +4. empty, directive-only, standalone exact-pin, and include-only inputs exercise + both branches of the publication predicate. + +Merge requires the focused trusted-uv suite, complete central tests, production +statement and branch coverage at 100%, complete production docstrings, Python +3.10 and current-stable compilation, exact-head security checks, and ordinary +protected-branch review. A downstream repository using nested requirements +should publish one standalone hash-locked closure or wait for a graph-aware +materializer; operators must not manually copy or rename an unresolved include. + +## Rollback + +Do not restore relative include publication. A rollback would reintroduce a +source-relative edge into a namespace that no longer preserves source location. +Restore only after a graph-aware implementation has equivalent RED fixtures, +immutable edge rewriting, closure verification, and the same security gates. + +## APA 7th references + +Python Packaging Authority. (2026). *Requirements file format*. pip +documentation. https://pip.pypa.io/en/stable/reference/requirements-file-format/ + +Python Packaging Authority. (2026). *Secure installs*. pip documentation. +https://pip.pypa.io/en/stable/topics/secure-installs/ diff --git a/scripts/ci/materialize_base_python_requirements.py b/scripts/ci/materialize_base_python_requirements.py index e4ebf473a..4249f16be 100755 --- a/scripts/ci/materialize_base_python_requirements.py +++ b/scripts/ci/materialize_base_python_requirements.py @@ -149,7 +149,6 @@ def _is_candidate_lock_name(name: str) -> bool: ) - def _is_candidate_lock_path(path: pathlib.PurePosixPath) -> bool: """Return whether one safe tracked path can name a pip requirements lock. @@ -242,6 +241,23 @@ def _is_hash_pinned(content: bytes) -> bool: or _is_bounded_requirement_include(line) for line in requirement_lines ) + + +def _is_flat_materializable_lock(content: bytes) -> bool: + """Return whether content is one standalone exact SHA-256 requirements lock. + + Selected sources are renamed to generated flat files. Relative ``-r`` and + ``--requirement`` edges therefore lose the source directory that gives them + meaning. Only independent exact package pins cross this publication boundary + until a complete immutable include graph can be reconstructed and rewritten. + """ + lines = _requirement_lines(content) + requirement_lines = [line for line in lines if line != "--require-hashes"] + return bool(requirement_lines) and all( + _is_fully_hash_pinned_requirement(line) for line in requirement_lines + ) + + def _is_fully_hash_pinned_requirement(line: str) -> bool: """Return whether one uv-export line is an exact package pin with SHA-256 hashes.""" fields = re.split(r"\s+(?=--hash=)", line) @@ -559,9 +575,9 @@ def base_hash_locks(repo_root: pathlib.Path, base_sha: str) -> list[tuple[str, b regular_paths = {path for path, _candidate in regular_blobs} locks: list[tuple[str, bytes]] = [] for path, candidate in regular_blobs: - if _is_candidate_lock_name(candidate.name): + if _is_candidate_lock_path(candidate): content = _git(repo_root, "show", f"{base_sha}:{path}") - if _is_hash_pinned(content): + if _is_flat_materializable_lock(content): locks.append((path, content)) elif candidate.name == "uv.lock": if _uv_pyproject_path(path) not in regular_paths: @@ -632,4 +648,4 @@ def main(argv: list[str] | None = None) -> int: if __name__ == "__main__": - raise SystemExit(main()) \ No newline at end of file + raise SystemExit(main()) diff --git a/tests/test_flat_lock_publication_boundary.py b/tests/test_uv_flat_lock_publication_boundary.py similarity index 84% rename from tests/test_flat_lock_publication_boundary.py rename to tests/test_uv_flat_lock_publication_boundary.py index f70a61851..6ef1ac2f0 100644 --- a/tests/test_flat_lock_publication_boundary.py +++ b/tests/test_uv_flat_lock_publication_boundary.py @@ -16,6 +16,23 @@ def _exact_pin(package_name: str, digest_character: str) -> bytes: ) +@pytest.mark.parametrize( + ("content", "expected"), + [ + (b"", False), + (b"--require-hashes\n", False), + (_exact_pin("standalone-package", "a"), True), + (b"-r requirements-other.txt\n", False), + ], +) +def test_flat_materializable_lock_requires_a_standalone_exact_closure( + content: bytes, + expected: bool, +) -> None: + """Flat publication accepts pins but never unresolved include-only content.""" + assert materializer._is_flat_materializable_lock(content) is expected + + @pytest.mark.parametrize("directive", ["-r", "--requirement"]) def test_flat_publication_excludes_relative_include_referrers( tmp_path: Path,