CEG-263-001/002: Gate_SDK pin policy decision required (immutable SHA vs moving @v1), lock incoherent until then

[cryptoxdog]

Audit ceg-open-prs-2026-09-17, findings CEG-263-001 (INVARIANT, High) and CEG-263-002 (COMPLETENESS, High). Owner class HUMAN; semantic owner CEG constellation dependency policy. Filed because this needs an architecture decision no agent may take — the audit's own authority resolution says PR intent does not supersede repository law.

The decision

PR #263 replaces the immutable Gate_SDK pin with a moving major tag:

-constellation-node-sdk = {git = "...Gate_SDK.git", rev = "69c6c67060b08440734a61473c03663423709964"}
+constellation-node-sdk = {git = "...Gate_SDK.git", rev = "v1"}

Current repository law requires immutable SHA constellation pins, and the enforcement script rejects the change on #263's head 29bc0a2:

$ python scripts/validate_sdk_pin.py
FAIL
pyproject.toml: missing pin
requirements.txt: missing pin
exit 1

PRESERVE-IMMUTABLE-SDK-IDENTITY is VIOLATED: CEG source revisions must deterministically identify the Gate SDK revision they were reviewed and tested with.

Why the tag is not equivalent to the pin

refs/tags/v1 does not point at the reviewed revision, and moves on each release:

$ git ls-remote https://github.com/Quantum-L9/Gate_SDK.git 'refs/tags/v1*'
e9f829f982110be13752da8f18c7a9692e8ed908  refs/tags/v1
e9f829f982110be13752da8f18c7a9692e8ed908  refs/tags/v1.1.0
a770e8531dc1c59ce01e1dbb0f4162785d9dda89  refs/tags/v1.0.1^{}

v1 currently resolves to the same object as v1.1.0, not to the reviewed 69c6c67. Adopting it silently moves the SDK off the revision the code was tested against, and will move again at the next minor release.

Two ways to resolve — both need you

1. Keep immutable pins. Restore a single immutable commit identity across pyproject.toml, requirements.txt, poetry.lock and validate_sdk_pin.py. chore: pin constellation-node-sdk to @v1 (moving major tag) #263 closes or is reworked.
2. Adopt moving-major policy. Land an explicit architecture decision that supersedes the immutable-pin law, and update the governing law plus validate_sdk_pin.py in a separately authorized change before this consumer PR implements it.

CEG-263-002 is blocked behind that choice

#263 changed only the two human-edited manifests and left the resolved lock untouched. On head 29bc0a2:

$ poetry check --lock
Error: pyproject.toml changed significantly since poetry.lock was last generated.
exit 1

poetry.lock still records reference/resolved_reference = 69c6c67… while pyproject.toml says rev = "v1". Which identity to lock to is the question above, so regenerating the lock now would silently decide the policy. Its second closing validation, docker compose -f docker-compose.prod.yml build api, is equally premature.

Once you pick a direction, CEG-263-002 is mechanical and I can do it: synchronize poetry.lock to the chosen identity and prove the production image builds from the repaired head.

Evidence: E006, E013, E014, E015, E016, E017, E018, E026. Authorities: AUTH-IMMUTABLE-CONSTELLATION, AUTH-PROD-DEPENDENCY-COHERENCE, AUTH-USER-SCOPE.

Related: #263.

---

Generated by Claude Code

[cryptoxdog]

Evidence update: the moving tag breaks the production image build

Docker became available in my session, so I ran CEG-263-002's closing validation rather than reasoning about it. One correction and one new finding.

docker compose -f docker-compose.prod.yml build api could not be run as written

It fails in my sandbox before reaching any dependency logic — pip install poetry cannot verify TLS because the environment's HTTPS proxy CA is not inside the build container:

#10 ERROR: Could not find a version that satisfies the requirement poetry
    SSLError(SSLCertVerificationError('self-signed certificate in certificate chain'))

That is my environment, not this repository, and "fixing" it would mean editing Dockerfile.prod — which would test something other than the real build. So I isolated the substantive question instead.

The decisive test: the exact step Dockerfile.prod:32 runs

Dockerfile.prod builds dependencies with poetry install --only main --no-root against pyproject.toml + poetry.lock. Running precisely that on both heads:

Head	Pin	poetry install --only main --no-root
#262 f6ddcad	rev = "69c6c67…"	✅ resolves — installs constellation-node-sdk (1.0.1 69c6c67)
#263 29bc0a2	rev = "v1"	❌ fails: pyproject.toml changed significantly since poetry.lock was last generated

So this is not an abstract lock-coherence concern. As #263 stands, the production image build fails at its dependency install step. Whatever you decide about pin policy, #263 cannot merge in its current state without breaking Dockerfile.prod.

What this does and does not settle

It does not decide the policy question — that is still yours, and the argument against @v1 remains the one in the issue body: v1 currently resolves to e9f829f (same object as v1.1.0), not the reviewed 69c6c67, and it will move again at the next release.

It does settle that CEG-263-002 is not optional cleanup. The lock is not merely stale metadata; it is load-bearing for the production build.

Once you decide, I can finish it in one pass

• Immutable pin: revert the two manifests; poetry check --lock and poetry install already pass on that shape, as the Add IdeaOS portfolio graph domain and hydration seam #262 column shows.
• Moving @v1: regenerate poetry.lock against the new manifest, then re-run both checks.

I can validate the dependency install either way. The containerised build itself I cannot verify here because of the proxy CA above — CI is the right place for that, and I would not claim it from a local run.

---

Generated by Claude Code

[cryptoxdog]

The decision landed by merge — and main is now broken in two ways

#263 merged as a19ca43, adopting the moving @v1 tag. Recording what that means on main now, because the second half of the migration did not land with it.

1. Production dependency install is broken

$ poetry check --lock            # on main b1054ac
Error: pyproject.toml changed significantly since poetry.lock was last generated.

pyproject.toml:27 says rev = "v1"; poetry.lock:514 still says reference = "69c6c67…". Dockerfile.prod:32 runs poetry install --only main --no-root against exactly that pair, so the production image build is broken on the default branch. This is CEG-263-002, no longer blocked — the dependency it waited on is now decided.

2. The repository's own pin law now fails

$ python scripts/validate_sdk_pin.py    # on main
FAIL
pyproject.toml: missing pin
requirements.txt: missing pin
exit 1

scripts/validate_sdk_pin.py was never updated, so main violates its own enforcement. CEG-263-001's closure condition anticipated this: adopting moving-major policy required updating the governing law and the enforcement script in a separately authorized change, before the consumer PR implemented it. That change has not happened.

Worth noting why nothing stopped this: validate_sdk_pin.py is not wired into CI, pre-commit, or the Makefile. I grepped .github/, .pre-commit-config.yaml and Makefile on main and it appears in none of them. The law is documented but unenforced, which is its own finding.

The regeneration is not neutral — I tested it

I regenerated the lock against @v1 in a scratch tree to see what it captures:

	before	after poetry lock
version	1.0.1	1.1.0
resolved_reference	69c6c67…	e9f829f…

poetry check --lock passes afterward. But the fix silently upgrades the Gate SDK by a minor version, because refs/tags/v1 currently points at e9f829f, the same object as v1.1.0. No one has reviewed CEG against 1.1.0. That is PRESERVE-IMMUTABLE-SDK-IDENTITY becoming concrete rather than theoretical, so I discarded the experiment rather than pushing it.

Two coherent end states — please pick

A. Complete the @v1 migration. Regenerate poetry.lock (accepting the 1.0.1 → 1.1.0 bump, ideally after someone reviews that diff), and update scripts/validate_sdk_pin.py plus the governing law to permit moving major tags. Ends with both checks green and policy consistent. The law change is owner_class=HUMAN and not mine to make.

B. Revert to immutable pins. Restore rev = "69c6c67…" in pyproject.toml and requirements.txt. poetry.lock already records that identity, so both checks go green with no SDK movement and no law change. Smaller, and restores consistency with the law as written.

I can execute either in one pass — A's lock half, or all of B. I am not choosing between them: A accepts an unreviewed dependency bump, B reverses a merge you just made.

Separately, validate_sdk_pin.py should be wired into CI under either choice, or the next violation merges just as quietly.

---

Generated by Claude Code

[cryptoxdog]

l9-issue-remediation unblock

Cluster: gate-sdk-v1-pin
Ownership: CODEBASE (human decision: moving major @v1)
Owning repo: Quantum-L9/Cognitive.Engine.Graphs
Change: poetry.lock now references v1 (resolved_reference=e9f829f, SDK 1.1.0); validate_sdk_pin.py fail-closes on the major tag instead of SHA 69c6c67
Unblocked for resume: python3 scripts/validate_sdk_pin.py prints PASS; PR #282
Remaining: Makefile/pre-commit wire omitted to avoid overlapping #280