Merge remote-tracking branch 'origin/main' into claude/issue-10853-filter-zero-match-guard

Author: claude

.changeset/published-readme-relative-target-existence.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/runtime": patch
+"@objectstack/hono": patch
+"@objectstack/plugin-security": patch
+"@objectstack/service-package": patch
+---
+
+docs: repair the dead repo-relative targets in four published READMEs (#10813)
+
+A published README ships inside the npm tarball, so a dead relative link in one
+is shipped to every reader who installs the package. Nine of them were measured
+across four packages, and nothing read them: `check:published-readme-links`
+checked docs-site URLs, `check:published-readme-exports` checked fenced import
+lines, and the lychee lane never sees `packages/**/README.md`.
+
+`@objectstack/runtime` carried six dead targets. Each was traced to where the
+content actually went rather than deleted:
+
+- `MINI_KERNEL_GUIDE.md`, `MINI_KERNEL_ARCHITECTURE.md` and
+  `MINI_KERNEL_IMPLEMENTATION.md` were deleted from the repo root in January as
+  "redundant markdown files" (d709ecce68 — 14 files, 5051 deletions, nothing
+  added). The kernel reference they described is the docs site now, so the
+  Documentation section is the same footer eight sibling READMEs already use.
+- `examples/host/` was renamed to `examples/app-host`, then `apps/server`, then
+  `apps/objectos`, and finally split out to `objectstack-ai/cloud`. In-repo, an
+  HTTP server in front of the runtime is `@objectstack/plugin-hono-server` plus
+  the `@objectstack/hono` adapter, so the bullet points there.
+- `examples/msw-react-crud/` became `examples/app-react-crud`, then
+  `apps/console`, and now ships as `@object-ui/console` from another repo.
+- `test-mini-kernel.ts` was a root-level scratch script; this package's suite is
+  179 test files under `src/`.
+- The section also ended on a truncated bullet with an unterminated backtick
+  (`` - `packages/runtime/src/ ``), which is now a real pointer to that suite.
+
+The other three packages: `@objectstack/hono` and `@objectstack/service-package`
+still spelled `@objectstack/driver-sql` as `../../plugins/driver-sql`, stale
+since the driver moved to `packages/drivers/` (#5618). `@objectstack/plugin-security`
+and `@objectstack/service-package` linked three packages that are in no directory
+of this repo (`plugin-org-scoping`, `service-tenant`, `service-marketplace`);
+those links are dropped and the names kept as code spans, which is the spelling
+those same files already use for a package they cannot point at in-tree. Whether
+those three packages exist at all is a separate question, filed separately.

.github/workflows/lint.yml

@@ -184,11 +184,45 @@ jobs:
       # `ts-parse` spawns ~20 real node children (~10 s measured, and the spawns
       # are the point — they pin that a caller's try/catch cannot swallow the
       # refusal); the other two are in-process fixtures, ~0.5 s combined.
+      #
+      # ⭐ Collected rather than sequenced, for the reason spelled out at the
+      # `Shallow-history guard self-tests` step below (#10814): under `bash -e` a
+      # bare sequence stops at the first failure, so a red `ts-parse` would leave
+      # the entry-predicate and comment-mask self-tests UNRUN while the log shows
+      # only the one failure. `ts-parse` is both the slowest of the three and the
+      # one that spawns real children, so it is the likeliest to be red —
+      # precisely the masking direction. The three modules are independent of one
+      # another, so collecting loses nothing.
       - name: scripts/ shared-module self-tests (parse · entry predicate · comment mask)
         run: |
-          node scripts/ts-parse.mjs --self-test
-          node scripts/invoked-as.mjs --self-test
-          node scripts/js-comment-mask.mjs --self-test
+          # Tolerate-and-collect (#10814) — see the note above this step. Each
+          # self-test runs unconditionally and prints its own verdict; the step
+          # still FAILS when any of them does, naming every one that failed.
+          # ⛔ Never let the collector swallow the exit code — a green step over
+          # a red self-test looks identical to success. Both directions are pinned
+          # by `node scripts/check-step-collectors.mjs --self-test`, which extracts
+          # THIS block from THIS file and drives it under `bash -e` with stubs.
+          failed=""
+          run_self_test() {
+            echo "-- $*"
+            if "$@"; then
+              echo "PASS  $*"
+            else
+              echo "FAIL  $*"
+              failed="${failed}  $*"$'\n'
+            fi
+            return 0
+          }
+          run_self_test node scripts/ts-parse.mjs --self-test
+          run_self_test node scripts/invoked-as.mjs --self-test
+          run_self_test node scripts/js-comment-mask.mjs --self-test
+          if [ -n "$failed" ]; then
+            echo ""
+            echo "scripts/ shared-module self-tests — the following FAILED:"
+            printf "%s" "$failed"
+            exit 1
+          fi
+          echo "scripts/ shared-module self-tests — all three ran and passed"
 
       # Every `scripts/**` entry guard goes through ONE predicate (#10086).
       # The hand-typed forms of "did node run me, or did someone import me?"
@@ -527,11 +561,116 @@ jobs:
       # (`check-governed-merges.mjs`'s own cases run in the
       # `pnpm check:pm-governed-merges` step above, which is already its
       # self-test.)
+      #
+      # ⭐ The three run through a COLLECTOR rather than as a bare sequence
+      # (#10814). A `run:` block is executed by `bash -e`, so the first non-zero
+      # exit aborts the STEP and every command after it is never reached —
+      # neither green nor red, and nothing in the log tells those apart. Not
+      # hypothetical here: while `git-history.mjs --self-test` was red on `main`
+      # for ~10 h on 2026-08-21 (#10807), the two self-tests listed after it did
+      # not execute in CI once — on the step that gates every PR. Both were
+      # green, so that time the mask hid nothing; the compounding shape is that a
+      # SECOND regression can land unnoticed while the first is red, and then
+      # reads as though the fix broke it. #4690 one level up: a partial result
+      # that reads like a complete one.
+      #
+      # These three are INDEPENDENT — none is a precondition for reading the
+      # next — which is what makes collecting correct HERE and
+      # abort-on-first-failure correct in this job's many
+      # `<gate> --self-test` + `<gate>` steps, where the self-test IS the
+      # precondition for trusting the run after it. The census behind that
+      # distinction: of 200 `run:` steps in lint.yml + ci.yml, 21 hold two or
+      # more substantive commands, and exactly two were independent self-tests
+      # sequenced together — this step and the `scripts/` shared-module step
+      # above. Every other one is a precondition or a dependency, where the
+      # abort is the correct semantics.
+      #
+      # ⛔ Not one step per self-test: a plain step split does not fix this at
+      # all — Actions skips a job's remaining steps once a step fails, so the
+      # mask survives the split verbatim. Restoring it would take an `if:` on
+      # each gate step, and a condition is a way for a PR to arrange that a gate
+      # does not run on it (the reason the required-context pin step carries
+      # none). Both gates that read step structure were checked and would
+      # TOLERATE a split — `check-shard-attestation` scans ci.yml only, and
+      # `check-required-contexts` pins job-level properties plus the one
+      # `check:required-contexts` step — so this is a choice on the merits,
+      # not a constraint.
       - name: Shallow-history guard self-tests
         run: |
-          node scripts/pm/git-history.mjs --self-test
-          node scripts/check-engine-split-ratio.mjs --self-test
-          bash scripts/collect-release-notes.sh --self-test
+          # Tolerate-and-collect (#10814) — see the note above this step. Each
+          # self-test runs unconditionally and prints its own verdict; the step
+          # still FAILS when any of them does, naming every one that failed.
+          # ⛔ Never let the collector swallow the exit code — a green step over
+          # a red self-test looks identical to success. Both directions are pinned
+          # by `node scripts/check-step-collectors.mjs --self-test`, which extracts
+          # THIS block from THIS file and drives it under `bash -e` with stubs.
+          failed=""
+          run_self_test() {
+            echo "-- $*"
+            if "$@"; then
+              echo "PASS  $*"
+            else
+              echo "FAIL  $*"
+              failed="${failed}  $*"$'\n'
+            fi
+            return 0
+          }
+          run_self_test node scripts/pm/git-history.mjs --self-test
+          run_self_test node scripts/check-engine-split-ratio.mjs --self-test
+          run_self_test bash scripts/collect-release-notes.sh --self-test
+          if [ -n "$failed" ]; then
+            echo ""
+            echo "Shallow-history guard self-tests — the following FAILED:"
+            printf "%s" "$failed"
+            exit 1
+          fi
+          echo "Shallow-history guard self-tests — all three ran and passed"
+
+      # Step-collector gate (#10814) — the guard over the two steps above, and
+      # over any step that grows their shape later. It has a static half and a
+      # dynamic half, and the dynamic one is the load-bearing part:
+      #
+      # STATIC: one `run:` block invoking `--self-test` on TWO OR MORE DISTINCT
+      # scripts must route them through a collector. Distinct scripts testing
+      # themselves are independent by construction, so there is no reading under
+      # which a failure in one should skip the others. Deliberately narrow: it
+      # does NOT flag `<gate> --self-test` + `<gate>`, this job's dominant shape,
+      # where the abort IS the point (a checker whose self-test failed has no
+      # verdict worth printing), nor ci.yml's `mkdir -p` / `psql ALTER SYSTEM`
+      # dependency sequences. Swept when it was written: 343 `run:` steps across
+      # 26 workflows, exactly 2 matched, both of them above.
+      #
+      # DYNAMIC: nothing static can tell a collector that PROPAGATES the exit
+      # code from one that swallows it, and the swallowing kind is worse than
+      # the masking it replaces — a green step over a red self-test, which from
+      # outside is indistinguishable from success. So `--self-test` extracts each
+      # live block out of THIS file and runs it as `bash -e <file>` — the same
+      # invocation Actions uses — against stubs with controlled exit codes, and
+      # reads "did this command run" from the STUB's own side effect rather than
+      # from the block's output, so the block cannot vouch for itself. Both
+      # directions are pinned in every position, and the same command list is
+      # also driven through the PRE-FIX bare sequence, which must mask — 1 of 3
+      # commands executing when the first fails, 3 of 3 when none does. A harness
+      # that cannot reproduce the defect cannot certify the fix.
+      #
+      # Invoked as `node scripts/…` rather than through a `pnpm check:*` alias,
+      # on the precedent this job already sets: several gate steps here are
+      # invoked directly, and dispatch-gates.mjs derives gate families from
+      # either spelling, so the direct form loses no discovery and adds no key
+      # to the root manifest.
+      #
+      # ⚠️ NOT because root package.json is off limits. The #9465 changeset lane
+      # fences that file's `@changesets/cli` range and its `version` script — the
+      # parenthetical in the issue body is scoping, not illustrative — and not
+      # the file, so a `check:step-collectors` key would have been allowed. Said
+      # plainly because the over-broad reading is easy to acquire and then
+      # propagates as a constraint nobody actually has, which is this step's own
+      # defect class wearing a different hat: a claim that reads as verified.
+      # Temp-dir fixtures, no network, ~1 s.
+      - name: Step-collector gate (self-tests that mask each other)
+        run: |
+          node scripts/check-step-collectors.mjs --self-test
+          node scripts/check-step-collectors.mjs
 
       # Verify-lock entry-point self-test (#9661). `scripts/pm/os-verify-lock.sh`
       # is the ONE way an agent takes the container's shared heavy-verify lock,

docs/qa/platform-checklist/areas/records-forms.json

@@ -8,7 +8,7 @@
       "title": "Create → read → update → delete a record through the console UI",
       "since": "v15",
       "status": "active",
-      "revision": 5,
+      "revision": 6,
       "priority": "P0",
       "surface": "browser",
       "personas": [
@@ -20,7 +20,7 @@
           "showcase_account — writable standard object (sharingModel public_read_write), required name + status, format validations tax_id_format / billing_email_format (examples/app-showcase/src/data/objects/account.object.ts)"
         ],
         "knownGaps": [
-          "Clause 7 (clone is RLS-gated) cannot be scored on showcase_account, the object every other clause here drives: it is public_read_write, so there is no persona for whom a source row is invisible. It needs showcase_invoice plus a contributor-bound member — the recipe qa-contributor-bound-member in areas/search.json. ⚠️ The recipe mechanism is AREA-SCOPED (provisioning.use must name a key in this area's own fixtures block, README.md; unresolved by the validator either way, deferred at #7716 / tracked #7720), so this item cross-references the recipe by name rather than opting in. Replay it from there; do not fork a second copy into this area."
+          "Clause 7 (clone is RLS-gated) cannot be scored on showcase_account, the object every other clause here drives: it is public_read_write, so there is no persona for whom a source row is invisible. It needs showcase_invoice plus a contributor-bound member — the recipe qa-contributor-bound-member in areas/search.json. ⚠️ The recipe mechanism is AREA-SCOPED (provisioning.use must name a key in this area's own fixtures block, README.md) and the validator now ENFORCES that scoping (#10593): a same-area `use` RESOLVES, and a `use` naming another area's recipe key FAILS check:platform-checklist as a dangling pointer, naming the item and the key that resolved to nothing. ⛔ So this reference cannot be spelled as `use` today — no cross-area spelling exists that the tooling accepts, and giving that pointer one is the open half of #10593 — and this item cross-references the recipe by name rather than opting in. Replay it from there; do not fork a second copy into this area."
         ]
       },
       "steps": [
@@ -129,6 +129,12 @@
           "date": "2026-08-21",
           "change": "named the object and persona clause 7 actually needs, and separated its refusal from the one next to it. The clause asks for a clone of a row the caller cannot SEE to be refused 404 RECORD_NOT_FOUND, but every other clause in this item drives showcase_account, which is public_read_write — no persona can fail to read a row there, so the clause was unscoreable on its own item's object. The 17.1.0 sweep hit this directly: cloning showcase_account as a seeded demo persona produced 403 PERMISSION_DENIED (a missing CREATE grant), a different gate that a status-only reading would have scored as the RLS refusal. Clause 7 now names showcase_invoice + INV-1003 + a contributor-bound member (recipe qa-contributor-bound-member, areas/search.json), requires the code and not just the status, requires the invisibility premise to be read first, and states the 404-vs-403 discriminator. A knownGap records the cross-area recipe reference and why `use` is not available here (#10236 B1)",
           "ref": "#10236"
+        },
+        {
+          "revision": 6,
+          "date": "2026-08-21",
+          "change": "corrected a knownGap that had gone from stale FACT to stale PERMISSION. Clause 7's cross-area note said `provisioning.use` was 'unresolved by the validator either way' — true when written (deferred at #7716 / tracked #7720), false since the area-scoped resolve landed at #10593: a same-area `use` now resolves and a cross-area one FAILS check:platform-checklist, naming the item. The prose therefore invited exactly the edit the gate rejects. The note now states what is enforced today; the cross-area SPELLING is still undecided (the open half of #10593) and is deliberately NOT predicted here, so this correction cannot itself become the next stale permission. Item substance, steps, personas, fixtures and all acceptance clauses are unchanged — no run verdict is invalidated by this revision",
+          "ref": "#10809"
         }
       ]
     },