Merge remote-tracking branch 'origin/main' into claude/zen-wilson-dde758

# Conflicts:
#	packages/create-objectstack/src/template-consistency.test.ts

Author: os-zhuang

.changeset/cli-strip-arg-separator.md

@@ -0,0 +1,30 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): tolerate the `--` separator pnpm injects when forwarding script args (#3114)
+
+The AGENTS.md-documented backend-debug flow `pnpm dev -- --fresh -p <port>` failed at
+the repo root with an opaque `Unexpected arguments: -p, 44637` (exit 2 + a help dump).
+
+pnpm appends forwarded args to a script **verbatim, including the `--`**, and each
+nested `pnpm --filter` hop preserves it, so the showcase's `objectstack dev
+--seed-admin` ran as `objectstack dev --seed-admin -- --fresh -p 44637`. oclif reads
+`--` as POSIX end-of-flags, so everything after it became positional: `--fresh` was
+silently swallowed as the `package` arg and `-p 44637` overflowed the arg list. Every
+flag the user asked for was dropped — the failure was opaque precisely because the
+`--` looks inert.
+
+A `preparse` hook now drops `--` separators before oclif parses argv, so the
+npm-style `-- <flags>` form and the bare form behave identically, for every command
+and both bins (`run.js`, `run-dev.js`). No `os` command takes passthrough args (none
+sets `strict = false`, none reads raw argv), so a `--` carries no meaning here and is
+always a package-manager artifact.
+
+Note this is not fixable via oclif's `'--': false` parser option: that keeps
+flag-parsing on past the separator but re-appends the `--` into argv, so strict
+commands fail with `Unexpected argument: --` instead.
+
+Tradeoff: a `-`-prefixed token can no longer be forced to parse as a positional
+value. Every `os` positional is a config path, a metadata / datasource / package
+name, or an id — none start with `-`.

.changeset/i18n-inline-label-default-locale.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): treat an inline `label:` as the default-locale source in i18n coverage
+
+A fresh `npm create objectstack` scaffold reported 4 `i18n/missing-object` /
+`i18n/missing-field` errors for its own `<ns>_note` object, even though the
+template authors `label: 'Note'`, `pluralLabel: 'Notes'`, `label: 'Title'` and
+`label: 'Body'` inline. The only way to silence them was to commit an `en`
+bundle restating strings the metadata already carries.
+
+The inline `label:` *is* the default-locale text: the runtime resolver falls
+back to it when a bundle has no entry (`translateObject`), and `os i18n
+extract` seeds bundles from it. Coverage now honours that contract — an inline
+label satisfies the default locale, and a bundle is what *other* locales need.
+Keys with no source string anywhere are no longer reported as i18n gaps; a
+missing label is already `required/label`'s finding.
+
+Non-default locales are unaffected: they still warn for every untranslated key
+(`os lint` on `examples/app-todo` reports the same 79 warnings as before, with
+its 39 default-locale errors gone). `os lint --include-platform` drops the
+platform baseline's default-locale errors for the same reason — the platform
+ships English labels inline — while keeping its non-default-locale warnings.

.changeset/scaffold-pnpm11-build-approvals.md

@@ -0,0 +1,35 @@
+---
+"create-objectstack": patch
+---
+
+fix(create-objectstack): the blank scaffold declares pnpm build approvals, so a fresh `pnpm install` no longer exits 1 on pnpm 11
+
+pnpm 11 turned an unapproved dependency build script from a warning into a hard
+error. The blank template declared no build approvals, so the very first command
+a new user runs failed on any current pnpm:
+
+```
+npx create-objectstack myapp && cd myapp && pnpm install
+# [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: better-sqlite3@12.11.1, esbuild@0.28.1
+# exit 1
+```
+
+The scaffold now ships a `pnpm-workspace.yaml` approving the two packages it
+actually depends on building — `better-sqlite3` (the native sqlite driver behind
+`@objectstack/driver-sql`) and `esbuild` (compiles `objectstack.config.ts`).
+
+Both approval keys are present because pnpm reads them by version, and neither
+alone covers the supported range:
+
+- `allowBuilds` (a package → boolean map) — the only key pnpm 11 honors, and
+  understood back to pnpm 10.31. `onlyBuiltDependencies` alone still errors.
+- `onlyBuiltDependencies` (a list) — pnpm 10.0–10.30, which ignore `allowBuilds`.
+
+npm and yarn ignore the file, so the npm install path is unaffected. Both
+packages ship prebuilt binaries, so this was an install-time hard stop rather
+than a runtime defect — the project ran fine once installed.
+
+This is the #3091 failure class (in-repo settings masking what users resolve)
+and was caught by the publish smoke gate added in #3100, which installs the
+release candidate the way a user does — on whatever pnpm corepack hands a fresh
+machine.

.changeset/server-timing-perf-spans-2408.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/observability": patch
+"@objectstack/driver-sql": patch
+"@objectstack/runtime": patch
+"@objectstack/plugin-hono-server": patch
+---
+
+feat(observability): decompose `Server-Timing` into auth / db / hooks / serialize spans (perf-tuning mode)
+
+The opt-in `Server-Timing` header now breaks a request's server time into the phases that actually explain it, so an operator can open DevTools → Network → Timing and see where the time went without standing up an external tracing backend:
+
+- **`db`** — total SQL time with a **query count**. The SQL driver wires knex's `query` / `query-response` events (keyed by `__knexQueryUid`) and folds each query into one aggregate member (`db;dur=210;desc="6 queries"`) — the query count is the number most useful for spotting N sequential round-trips. Timing is attributed to the originating request via `AsyncLocalStorage`, so it is correct under concurrency and never cross-attributes. SQL text is never emitted, only durations and a count.
+- **`auth`** — identity / session resolution in the dispatcher, the prime suspect for unexplained data-API overhead.
+- **`hooks`** — total business-hook execution time with a hook count, fed through the engine's existing `HookMetricsRecorder` seam (wired from the runtime, so `@objectstack/objectql`'s lean `core` tier stays observability-free).
+- **`serialize`** — response JSON encoding in the HTTP adapter.
+
+Adds `countServerTiming(name, dur, unit)` (and `PerfTiming.count`) to fold high-frequency phases into a single aggregate member instead of flooding the header. Every phase is a no-op when perf-tuning is off (`serverTiming: true` / `OS_SERVER_TIMING=true`), so there is zero measurable overhead on the normal path.
+
+Closes #2408.

.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,6 +129,21 @@ jobs:
       - name: Type check (@objectstack/spec)
         run: pnpm --filter @objectstack/spec exec tsc --noEmit
 
+      # 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
+
       # Example apps are AI-authoring reference templates; a red typecheck is a
       # bad signal to copy from. tsup transpiles them without a full typecheck,
       # so build alone will not catch type drift — typecheck them explicitly.