Merge remote-tracking branch 'origin/main' into claude/issue-10840-invisible-bare-root-worklist

Author: claude

.changeset/publish-error-headline-issues.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/spec': minor
+'@objectstack/metadata-protocol': patch
+'@objectstack/runtime': patch
+---
+
+Publish refusals no longer render each validation finding twice (#10524) — declare-then-trim.
+
+**Declared (spec, additive):** `PublishPackageDraftsResponseSchema.failed[]` elements now
+declare `issues[]` (the `RuntimeAuthoringIssueSchema` findings the producer has emitted
+since #8333 but no declared parse could carry), and `seedApplied` declares `issues[]`
+(`{ path, message, code? }`, the seed-body schema refusal's findings). Typed consumers —
+the SDK's `PublishPackageDraftsResponse`, any `parse` through the schema — can now read
+the structured findings back instead of having them silently stripped.
+
+**Trimmed (producers):** the #4463 author-time gate's 422 message and
+`seedRequestValidationError`'s message are one-sentence headlines — total count plus up to
+three `path [rule]` / `path [zod-code]` locators — instead of restating the issue prose
+that `issues[]` carries on the same response. Consumers that render only `error` (CLI,
+logs) keep what failed, where, under which rule, and how many; consumers that render both
+channels stop repeating themselves. The old `(+N more)` tail is subsumed by the leading
+count. Both catches that surface the seed refusal onto `seedApplied` now thread the
+structured findings beside the headline.
+
+Error `code`/`status` vocabularies, `advisories`, the DESTRUCTIVE_CHANGE (409) message,
+and `saveMetaItem`'s spec-validation 422 message are unchanged. Messages are not contract
+(the machine-readable channels are `code` and `issues[]`), so this is not a breaking
+change and registers no migration.

.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?"
@@ -549,11 +583,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,

content/docs/references/api/protocol.mdx

@@ -1248,7 +1248,7 @@ List packages response
 | **publishedCount** | `integer` | ✅ | Number of drafts promoted to active — `published.length`. 0 on every refusal path (the batch is all-or-nothing, ADR-0067 D2). |
 | **failedCount** | `integer` | ✅ | Number of items that did not publish — `failed.length`. On a rollback this counts the WHOLE batch: the causal item plus every sibling marked BATCH_ABORTED. |
 | **published** | `{ type: string; name: string; version: string; advisories?: object[] }[]` | ✅ | Every draft promoted to active, in publish order. Empty on every refusal path. |
-| **failed** | `{ type: string; name: string; error: string; code?: string }[]` | ✅ | Items that did not publish. Because the batch is all-or-nothing (ADR-0067 D2), a non-empty list means NOTHING landed: `published: []`, `publishedCount: 0`. |
+| **failed** | `{ type: string; name: string; error: string; code?: string; … }[]` | ✅ | Items that did not publish. Because the batch is all-or-nothing (ADR-0067 D2), a non-empty list means NOTHING landed: `published: []`, `publishedCount: 0`. |
 | **seedApplied** | `{ success: boolean; inserted?: integer; updated?: integer; error?: string; … }` | optional | Aggregate outcome of materializing EVERY published `seed` body in one multi-pass loader run (cross-seed references need the whole set). Present ONLY when the batch published at least one seed. Two producers, one key: the batch itself self-applies (`applySeedBodies`), and the REST door back-fills the same key for custom protocols that do not — never both (an externalId-less seed would double-insert). Best-effort: a seed problem is surfaced here, never thrown. |
 | **materializeApplied** | `{ success: boolean; inserted: integer; updated: integer; failures: object[] }` | optional | ADR-0086 P2 — aggregate result of publish-time materializers across the batch (e.g. `permission` → `sys_permission_set`), including side-effect failures surfaced by the per-item effects loop. Present ONLY when at least one published item had a registered materializer or a side-effect failure. Best-effort, same contract as `seedApplied`. |
 | **probes** | `any` | optional | ADR-0038 L3 post-publish runtime probe report — one real read per published artifact (seeded objects have rows, views are readable, widget dataset selections execute). DELIBERATELY OPAQUE in this contract (#9406): the key is declared and carried through verbatim, but its inner shape is intentionally not modeled until a consumer needs a field of it. Present only when something was publishable; probes never fail the publish. |

docs/audits/2026-07-unknown-key-strictness-ledger.counts.md

@@ -257,7 +257,7 @@ directory rather than per file.
 | Dir | Sites |
 |---|---|
 | `ai/` | 77 |
-| `api/` | 406 |
+| `api/` | 407 |
 | `cloud/` | 83 |
 | `identity/` | 32 |
 | `integration/` | 10 |

packages/adapters/hono/README.md

@@ -66,7 +66,7 @@ app.use('/api/*', objectStackMiddleware(kernel));
 ## Edge runtime notes
 
 - Hono adapter is the **preferred** adapter for Cloudflare Workers, Deno Deploy, Bun, and Vercel Edge.
-- Drivers differ by runtime: use [`@objectstack/driver-sql`](../../plugins/driver-sql) on Node. (Edge/multi-tenant turso driver ships in ObjectStack Cloud.)
+- Drivers differ by runtime: use [`@objectstack/driver-sql`](../../drivers/driver-sql) on Node. (Edge/multi-tenant turso driver ships in ObjectStack Cloud.)
 - Persist no long-lived state in module scope beyond the `kernel` instance.
 
 ## When to use

packages/metadata-protocol/src/protocol-publish-drafts-closure.test.ts

@@ -380,7 +380,14 @@ describe('publishPackageDrafts judges each draft against the BATCH closure (#103
         const causal = res.failed.find((f) => f.name === 'customer_dashboard')!;
         expect(causal.code).toBe('INVALID_METADATA');
         expect(causal.error).toMatch(/widget-dataset-unknown/);
-        expect(causal.error).toMatch(/no_such_dataset_xyz/);
+        // [#10524] `error` is a headline now (path + rule locators); the
+        // dataset NAME lives in the finding's message, once, on the
+        // structured channel the batch response declares (`failed[].issues`).
+        const unknownDs = (causal as any).issues.find(
+            (i: any) => i.rule === 'widget-dataset-unknown',
+        );
+        expect(unknownDs.message).toMatch(/no_such_dataset_xyz/);
+        expect(causal.error).not.toContain(unknownDs.message);
         // ADR-0067 D2 — all-or-nothing: the healthy sibling is aborted, not
         // published around the refusal.
         expect(res.failed.find((f) => f.name === 'shyx_customer_ds')?.code).toBe('BATCH_ABORTED');

packages/metadata-protocol/src/protocol.batch-verb-driver-code.test.ts

@@ -441,16 +441,20 @@ describe('[#8441] [GUARD] the Studio publish surface still gets the code it bran
         // WHICH DRAFT.
         expect(failure.type).toBe('flow');
         expect(failure.name).toBe('leave_approval');
-        // WHICH FIELD — the located path, in the human sentence (#8333's half).
+        // WHICH FIELD — the located path, in the human sentence (#8333's
+        // half). [#10524] The sentence is a HEADLINE: path and rule id stay
+        // in it, and the message prose lives once, in `issues[]` below.
         expect(failure.error).toContain('flows[0].nodes[1].config.approvers[0].value');
-        expect(failure.error).toContain('does not parse as CEL');
+        expect(failure.error).toContain('[approval-expression-invalid]');
+        expect(failure.error).not.toContain('does not parse as CEL');
         // …and the machine-readable halves the form highlights with. `code` is
         // THIS card's field: catalogued, so it passes through byte for byte.
         expect(failure.code).toBe('INVALID_METADATA');
         expectCataloged(failure.code);
         expect(Array.isArray(failure.issues)).toBe(true);
         expect(failure.issues[0].path).toBe('flows[0].nodes[1].config.approvers[0].value');
         expect(failure.issues[0].rule).toBe('approval-expression-invalid');
+        expect(failure.issues[0].message).toMatch(/does not parse as CEL/);
     });
 });