Merge remote-tracking branch 'origin/main' into claude/sweet-ardinghelli-731802

# Conflicts:
#	.github/workflows/lint.yml

Author: os-zhuang

.changeset/metadata-register-notifies-watchers.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": patch
+"@objectstack/metadata": patch
+"@objectstack/objectql": patch
+---
+
+**`MetadataManager.register()` / `unregister()` now announce to `subscribe()` watchers.** Both updated the registry, persisted to writable loaders and published to realtime, but never fired the watch callbacks — so `subscribe()` looked like it covered every write while silently missing all of them. Only the `saveMetaItem` path (via the repository watch stream) and the filesystem watcher ever reached a subscriber. Runtime consumers that cache metadata — notably ObjectQL's SchemaRegistry bridge, the component that decides what is queryable — went stale on every other write until the process restarted.
+
+Announcing is now the **default**, so a new call site is correct without knowing this contract exists. This is a contract fix rather than a bug fix: the one live behavior change is that runtime datasource writes (`datasource-admin`) now reach the HMR SSE stream, which subscribes to every registered type. `unregisterPackage()` / `bulkUnregister()` also announce their deletes now — correct, but latent, since neither has a production caller today.
+
+Bulk ingest opts out explicitly with the new `MetadataWriteOptions` (`{ notify: false }`) — boot-time filesystem priming, artifact ingest, and ObjectQL's registry bridge, each of which either runs before consumers cache anything or announces the whole batch once (as the artifact reload path does via `metadata:reloaded`). The bridge in particular MUST stay silent: it copies objects out of the SchemaRegistry, and announcing would feed them back through a handler that re-registers under `_packageId ?? 'metadata-service'`, overwriting the true package provenance of every object whose body carries no `_packageId`.
+
+Additive only — `register(type, name, data)` and `unregister(type, name)` keep working unchanged.
+
+Fixes #3112.

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
     outputs:
       docs: ${{ steps.changes.outputs.docs }}
       core: ${{ steps.changes.outputs.core }}
-      skilldocs: ${{ steps.changes.outputs.skilldocs }}
+      generated: ${{ steps.changes.outputs.generated }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v7
@@ -38,10 +38,30 @@ jobs:
               - 'content/**'
               - 'pnpm-lock.yaml'
               - '.github/workflows/ci.yml'
-            skilldocs:
+            # Inputs AND outputs of every generated artifact checked by the
+            # `check-generated` job. A path missing here makes that gate dormant on
+            # exactly the PRs that can break it, so keep the two in lockstep.
+            generated:
+              # check:skill-docs — catalog source is skills/*/SKILL.md; the derived
+              # listings are skills/README.md + the reference page below. (That page
+              # was content/docs/guides/skills.mdx until #2584 moved it; this filter
+              # kept watching the old path, so hand-edits to the generated block went
+              # unchecked from then until now.)
               - 'skills/**'
-              - 'content/docs/guides/skills.mdx'
+              - 'content/docs/ai/skills-reference.mdx'
               - 'packages/spec/scripts/build-skill-docs.ts'
+              # check:spec-changes / check:upgrade-guide — derived from the ADR-0087
+              # registries and the protocol version, none of which the skills paths
+              # above cover. Both gates were dormant on spec-only PRs: a protocol bump
+              # or a new migration could not trigger the job that verifies them.
+              - 'packages/spec/scripts/build-spec-changes.ts'
+              - 'packages/spec/scripts/build-upgrade-guide.ts'
+              - 'packages/spec/src/migrations/**'
+              - 'packages/spec/src/conversions/**'
+              - 'packages/spec/src/kernel/protocol-version.ts'
+              - 'packages/spec/api-surface.json'
+              - 'packages/spec/spec-changes.json'
+              - 'docs/protocol-upgrade-guide.md'
               - '.github/workflows/ci.yml'
             core:
               - 'packages/**'
@@ -354,10 +374,18 @@ jobs:
       - name: Build Docs
         run: pnpm --filter @objectstack/docs build
 
-  check-skill-docs:
-    name: Check Skill Docs
+  # Generated artifacts that are committed to the tree: regenerate, fail on drift.
+  # Named for the class, not for skill docs alone — it has checked the ADR-0087
+  # protocol artifacts for a while, and a name that hid them is part of why their
+  # paths went missing from the filter above.
+  #
+  # The generated reference docs (content/docs/references/**) are deliberately NOT
+  # here: they need to gate spec-only PRs, and this whole job is filter-gated, so
+  # they live in lint.yml's required, unfiltered "TypeScript Type Check" job.
+  check-generated:
+    name: Check Generated Artifacts
     needs: filter
-    if: needs.filter.outputs.skilldocs == 'true'
+    if: needs.filter.outputs.generated == 'true'
     runs-on: ubuntu-latest
     permissions:
       contents: read

.github/workflows/lint.yml

@@ -50,6 +50,16 @@ jobs:
       - name: ESLint
         run: pnpm lint
 
+      # Raw NUL guard (#3127): one literal U+0000 byte makes grep/ripgrep treat
+      # the whole file as binary and silently return ZERO matches — the file drops
+      # out of code search and out of every grep-based lint, with no error saying
+      # so. Nothing else catches it: git sniffs only the first 8000 bytes to decide
+      # binary-ness, and protocol.ts carried its NUL at offset 147230, so it kept
+      # diffing as ordinary text through review. That blind spot let six files
+      # accumulate the same defect. Authors must write the unicode escape instead.
+      - name: Raw NUL byte guard
+        run: pnpm check:nul-bytes
+
       # Docs/skills authoring guard (#2035 / ADR-0059): TS code blocks in
       # Markdown/MDX are not type-checked or ESLinted, so skills/ and
       # content/docs/ can drift back to teaching the bare `: Page = {}` literal
@@ -119,24 +129,38 @@ jobs:
       - name: Type check (@objectstack/spec)
         run: pnpm --filter @objectstack/spec exec tsc --noEmit
 
-      # Generated-skill gate: skills/*/references/_index.md and the objectstack-ui
-      # react-blocks contract are generated from packages/spec/src and committed.
-      # Nothing regenerated them in CI, so they drifted — and unlike the reference
-      # docs these ship to third parties via `npx skills add objectstack-ai/framework`,
-      # so the drift is served straight to consumers' agents.
+      # Generated-docs gate: content/docs/references/** is generated from the spec
+      # by `gen:schema && gen:docs` and committed. Nothing regenerated it in CI, so
+      # it drifted silently — #3076 added RowCrudActionOverride to the spec and the
+      # public reference docs never learned the type existed. Regenerates and fails
+      # on any difference.
+      #
+      # Deliberately lives in this job, not in ci.yml's "Build Docs": that job is
+      # gated on a `docs` paths-filter that does not include packages/spec/**, so it
+      # skips exactly the spec-only PRs that cause this drift (#3076 was one). This
+      # job has no paths filter and is a required status check, so the gate cannot go
+      # dormant. It reads src/ + json-schema/ via tsx and needs no build, so it runs
+      # before the workspace build and fails in ~2s.
+      - name: Check generated reference docs are in sync with the spec
+        run: pnpm --filter @objectstack/spec check:docs
+
+      # Same class, same reasoning, different surface: skills/*/references/_index.md
+      # and the objectstack-ui react-blocks contract are generated from
+      # packages/spec/src and committed, and nothing regenerated them either. These
+      # ship to third parties via `npx skills add objectstack-ai/framework`, so the
+      # drift is served straight to consumers' agents — 6 of 113 schema pointers named
+      # files the spec had already deleted or renamed.
       #
-      # Deliberately here rather than in ci.yml's `check-generated` job: that job is
-      # paths-filtered on skills/** and the build-skill-docs.ts script, NOT on
-      # packages/spec/src/**, so it skips exactly the spec-only PRs that cause this
-      # drift — and it is not a required check either, so it could be merged past
-      # even when it does run. This job has no paths filter and IS required
-      # ("TypeScript Type Check"), so the gate can neither go dormant nor be bypassed.
+      # Not in ci.yml's `check-generated` job for the reason above: its `generated`
+      # filter lists specific spec paths (migrations/, conversions/, protocol-version)
+      # but no schema dirs, so a PR touching src/data/** or src/ui/** — exactly what
+      # drives these two artifacts — never triggers it. It is not required, either.
       #
-      # Both read packages/spec/src directly via tsx and need no build (verified with
-      # every workspace dist/ removed), so they run before the workspace build and
-      # fail in seconds. `check:skill-refs` also fails on a SKILL_MAP entry pointing
-      # at a file the spec no longer has — the silent skip that let the map keep
-      # naming data/dataset.zod.ts for a year after #1620 renamed it to data/seed.zod.ts.
+      # Both read packages/spec/src via tsx and need no build (verified with every
+      # workspace dist/ removed), so they run before the workspace build. check:skill-refs
+      # additionally fails on a SKILL_MAP entry naming a file the spec no longer has:
+      # that silent skip is what let the map keep pointing at data/dataset.zod.ts for a
+      # year after #1620 renamed it to data/seed.zod.ts.
       - name: Check generated skill references are in sync with the spec
         run: pnpm --filter @objectstack/spec check:skill-refs