Skip to content

feat(tin-2423): substrate-boundary conformance validator (ledger item 30)#442

Merged
Jesssullivan merged 3 commits into
mainfrom
feat/tin-2423-substrate-boundary
Jul 3, 2026
Merged

feat(tin-2423): substrate-boundary conformance validator (ledger item 30)#442
Jesssullivan merged 3 commits into
mainfrom
feat/tin-2423-substrate-boundary

Conversation

@Jesssullivan

@Jesssullivan Jesssullivan commented Jul 3, 2026

Copy link
Copy Markdown
Owner

Summary

Fans out the substrate-boundary conformance validator to this repo, per TIN-2423 and
operator-ratified ledger item 30. Reference implementation: GF PR #1016
(feat/tin-2423-substrate-boundary on tinyland-inc/GloriousFlywheel).

Asserts ADR-008 "logical replaceability" as a checked invariant instead of prose: this
repo's code surfaces may reach the blahaj substrate only through named interfaces recorded
(with provenance) in config/substrate-boundary-allowlist.json. Docs (*.md) stay exempt.

Correction (adversarial-verify REWORK — fixed)

The version of scripts/validate-substrate-boundary.py originally pushed on this branch
(74a104c) predated the SELF-exclusion fix that landed on GF main (6fb1f50). Because
CODE_GLOBS includes scripts/**, and the validator's own source contains the literal
detection strings (tinyland-inc/blahaj, ../blahaj, ~/git/blahaj, key = "blahaj/) in
its regex definitions and self_test() fixtures, the un-fixed script flagged itself.
Confirmed by re-running the validator against 74a104c directly: 8 un-allowlisted
violations, exit 1
(the 2 real named-interface hits below were present too, but buried
under self-inflicted noise) — not the "0 violations" this PR originally (and incorrectly)
reported below. That prior claim was stale evidence, not a real passing run.

Fixed by porting the identical GF-main fix: added
SELF = Path(__file__).resolve().relative_to(REPO) right after REPO, and excluded it in
tracked_code_files()'s filter (Path(p) != SELF). Nothing else in the script changed.

Scan result: NAMED-INTERFACE (not a bleed) — re-verified post-fix, post git add -A

$ python3 scripts/validate-substrate-boundary.py --self-test
substrate-boundary self-test passed

$ python3 scripts/validate-substrate-boundary.py
allowed [repo-ref] scripts/lane-dispatch.py:127: parser.add_argument("--blahaj-repo", default="tinyland-inc/blahaj")
allowed [repo-ref] tinyland.repo.json:39: "gitops_receiver": "tinyland-inc/blahaj",
substrate-boundary validation passed (2 allowlisted hit(s), 0 violations)

Both are the generic ADR-007 receiver dispatch, not an ad-hoc bypass:

  • scripts/lane-dispatch.py constructs and (optionally) POSTs the <spoke>-lane-env
    repository_dispatch payload — the canonical shape is
    docs/schemas/blahaj-dispatch.schema.json (event_type pattern
    ^[a-z][a-z0-9-]+-lane-env$). It's invoked via just lane-dispatch / just lane-reap
    and by .github/workflows/lane-env.yml
    (tinyland-inc/ci-templates/.github/workflows/spoke-lane-env.yml@v2).
  • tinyland.repo.json's gitops_receiver field is the manifest-level declaration of that
    same named receiver (docs/CI-SCHEMA.md §4/§9 — "the wire, not blahaj's implementation").

Both are allowlisted with provenance in config/substrate-boundary-allowlist.json.

No path-reach or state-key hits: infra/tofu's module source resolves to
git::https://github.com/tinyland-inc/GloriousFlywheel.git//tofu/modules
(GF-reach, not blahaj-reach — a distinct repo from blahaj), and
infra/tofu/backend.hcl's state key (darkmap-tinyland-dev/terraform.tfstate) carries no
blahaj/ prefix.

What changed

  • scripts/validate-substrate-boundary.py — byte-identical to the GF reference except
    CODE_GLOBS, adapted to this repo's layout (infra/tofu/** + infra/kustomize/**
    instead of GF's tofu/**/deploy/**, plus tinyland.repo.json); plus the
    SELF-exclusion fix (see Correction above).
  • config/substrate-boundary-allowlist.json — two named-interface entries, both with
    provenance (ledger item 30 + blahaj ADR-007 generic receiver contract).
  • scripts/check-conformance.sh — new checklist item 13, matching the existing
    ok/no/man idiom.
  • Justfile — new substrate-boundary-check recipe.
  • .github/workflows/ci.yml — new just substrate-boundary-check step in the
    build-and-test job. (This repo's just conformance checklist isn't itself wired into
    CI yet — pre-existing, out of scope here — so the narrow check is wired directly instead
    of riding along on an unwired recipe.)

Test plan

  • python3 scripts/validate-substrate-boundary.py --self-test passes
  • python3 scripts/validate-substrate-boundary.py passes (2 allowlisted hits,
    0 violations) — re-verified after git add -A, verbatim output above
  • bash scripts/check-conformance.sh passes with new item 13 green
  • CI green on this PR (main loop merges on green per house rules — not merging here)

Committed with --no-verify -c commit.gpgsign=false per the TIN-2423 fanout task's stated
house rules for this batch.

… 30)

Port the GF substrate-boundary conformance validator (scripts/validate-substrate-boundary.py,
reference: tinyland-inc/GloriousFlywheel PR #1016, feat/tin-2423-substrate-boundary) to this
repo. Asserts ADR-008 logical replaceability as a checked invariant: code surfaces may only
reach the blahaj substrate through named, provenance-carrying interfaces recorded in
config/substrate-boundary-allowlist.json; docs (*.md) stay exempt.

Scan result: NAMED-INTERFACE, not a bleed. Two un-allowlisted repo-ref hits before the
allowlist:

  [repo-ref] scripts/lane-dispatch.py:127: default="tinyland-inc/blahaj" (--blahaj-repo arg)
  [repo-ref] tinyland.repo.json:39: "gitops_receiver": "tinyland-inc/blahaj"

Both are the generic ADR-007 receiver dispatch: scripts/lane-dispatch.py constructs +
dispatches the `<spoke>-lane-env` repository_dispatch payload (schema:
docs/schemas/blahaj-dispatch.schema.json) via `just lane-dispatch` / `just lane-reap` and
.github/workflows/lane-env.yml (tinyland-inc/ci-templates/.github/workflows/spoke-lane-env.yml@v2).
tinyland.repo.json's gitops_receiver field is the manifest-level declaration of the same
named receiver (docs/CI-SCHEMA.md §4/§9). Neither is an ad-hoc bypass of the generic
contract — both are allowlisted with provenance in config/substrate-boundary-allowlist.json.

No path-reach or state-key hits found (infra/tofu module source resolves to
tinyland-inc/GloriousFlywheel, not blahaj — GF-reach, not blahaj-reach; infra/tofu/backend.hcl
state key has no blahaj/ prefix).

Wired into scripts/check-conformance.sh as checklist item 13 (own summary/exit-code
aggregation, matching this repo's existing conformance idiom), exposed via
`just substrate-boundary-check`, and added as an explicit step in the build-and-test job of
.github/workflows/ci.yml (this repo's `just conformance` checklist is not itself CI-wired
yet, so the narrow check is wired directly rather than piggybacking on an unwired recipe).

Committed with -c commit.gpgsign=false --no-verify per TIN-2423 fanout house rules
(spokes-A lane).
@github-actions

github-actions Bot commented Jul 3, 2026

Copy link
Copy Markdown

tofu plan blocked before RustFS init

The PR did not run tofu plan because no repository-visible,
cluster-capable runner matched the selected Tofu labels.

This is a routing/configuration blocker, not a Terraform/OpenTofu
diff result. Bind the repo to the selected runner class or update
TOFU_LINUX_RUNNER_LABELS_JSON to a RustFS/backend-reachable class.

Ports the SELF-exclusion fix from GloriousFlywheel main (6fb1f50): the
validator was scanning its own source under scripts/**, which contains
the blahaj repo-ref/path-reach/state-key regex literals used for
detection and self-testing, producing false-positive violations against
itself. SELF is now resolved and excluded in tracked_code_files().
@Jesssullivan

Copy link
Copy Markdown
Owner Author

TIN-2423 code path is green, but this PR remains blocked by the external browser-rbe-proof latch, not by the substrate-boundary change.\n\nObserved on rerun of failed job in run 28686824972:\n- repo-local checks pass: build-and-test, bazel-graph, secrets-scan, route preflight\n- browser-rbe-proof dispatches GF proof runs, but all attempts cancel before job assignment\n- latest GF proof run: tinyland-inc/GloriousFlywheel#28687099525, conclusion=cancelled, jobs=0\n- darkmap job ends: "GloriousFlywheel proof run 28687099525 ended with conclusion=cancelled, jobs=0"\n\nNo darkmap code edit is indicated from this failure. Leaving the PR unmerged until the required proof lane clears or is reclassified by the GF/Codex lane.

@Jesssullivan
Jesssullivan merged commit a0ca098 into main Jul 3, 2026
8 of 10 checks passed
@Jesssullivan
Jesssullivan deleted the feat/tin-2423-substrate-boundary branch July 3, 2026 23:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant