Merge remote-tracking branch 'origin/main' into claude/issue-16042-analytics-timezone

Author: claude

.changeset/scope-less-booted-row-attribution.md

@@ -0,0 +1,35 @@
+---
+"@objectstack/runtime": patch
+"@objectstack/metadata-protocol": patch
+---
+
+docs(runtime,metadata-protocol): correct the `writable` verdict's illustration — the scope-less booted row is a marketplace / offline import, never a multi-package artifact's module (#14803)
+
+Comment and prose only. No predicate, no assertion and no served shape changes;
+every pin behind the `writable` verdict stays green as written.
+
+The `writable` verdict shipped in 17.3.0 with a **false attribution** in its own
+explanation, and this corrects it at every site that repeated it. The claim was
+that the scope-less booted row `isWritablePackage` answers `false` for is *the
+`type: module` sub-package a multi-package artifact carries*. It is not, and it
+never was:
+
+- `defineStack` parses every `packages[]` entry through `ManifestSchema`
+  (`spec/src/stack.zod.ts`, `ArtifactPackageEntrySchema`), whose `scope` is
+  `.default('project')` (`spec/src/kernel/manifest.zod.ts`), so **no** package of
+  a compiled artifact is ever scope-less — `dist/objectstack.json` and both
+  served rows carry `scope: "project"`.
+- A genuinely scope-less row arises only where a manifest reaches the registry
+  **without** that parse, because `installPackage` stores a key-by-key copy that
+  applies no defaults: a marketplace install / offline file import
+  (`manifestService.register(rawBody)` to `ql.registerApp`) for the **booted,
+  read-only** half, and `POST /api/v1/packages` (`body.manifest || body` to
+  `installPackage`) for the **database base, writable** half.
+
+Measured: `ManifestSchema.parse` of the `app-multi-package` orders body turns an
+unauthored `scope` into `scope: "project"`, while `SchemaRegistry.installPackage`
+of the same unparsed body yields a record with no `scope` key at all.
+
+What stays, because it is true and load-bearing: a scope-less **booted** package
+is read-only while a scope-less **database base** is writable, and only
+`engine.manifests` tells them apart — which is why the server owns the verdict.

.github/workflows/lint.yml

@@ -2325,6 +2325,32 @@ jobs:
       # PR. The checklist is a QA ledger, not a code gate; keeping it out of the
       # per-PR path means an unrelated PR is never blocked by checklist drift.
       # Run it by hand: `pnpm check:platform-checklist`. See that dir's README.
+      # Its red does have a reporting channel now, and it is NOT this file:
+      # `.github/workflows/platform-checklist-watchdog.yml` runs the gate on `main`
+      # daily and files or refreshes one issue when it is red.
+
+      # ⛔ …and the step below is NOT that wiring. What runs here is the STATIC PIN
+      # over the watchdog workflow: it asserts the file exists, fires on
+      # `schedule:` + `workflow_dispatch:`, carries NO `merge_group:` /
+      # `pull_request_target:` trigger, that any `pull_request:` trigger is
+      # `paths`-filtered to the watchdog file ALONE, that no board write is
+      # reachable from a pull_request run, and that the gate is invoked through its
+      # package script rather than an inlined copy. Two file reads, no socket.
+      #
+      # The watchdog's own `pull_request:` trigger names only itself, so it fires on
+      # no unrelated PR — that filter is what keeps the decision above intact, and
+      # pinning it is most of this step's job. It has to live HERE rather than
+      # inside the watchdog for the other half: a PR DELETING the watchdog would
+      # silence any check that lived inside it, and this job is the only place where
+      # the absence of that file is observable before it merges.
+      #
+      # Invoked as `node scripts/…` rather than a `pnpm check:*` alias: see the GATE
+      # INVOCATION IDIOM note at the top of this file. The `--self-test` leg runs
+      # first because a checker whose own cases failed has no verdict worth printing.
+      - name: Platform-checklist watchdog workflow pin
+        run: |
+          node scripts/check-platform-checklist-watchdog.mjs --self-test
+          node scripts/check-platform-checklist-watchdog.mjs
 
       # #3280/#3290 org-identifier guard: `organizationId` is the blessed
       # developer-facing name for the caller's active org in hook/action bodies;

.github/workflows/platform-checklist-watchdog.yml

@@ -160,7 +160,7 @@ The largest single consumer — **17 of the 105 sites**.
 | 49 | Action `requiredPermissions` bypassed | runtime | Get: engine self-invocation runs any action | `action-execution.ts:401` |
 | 50 | `manage_metadata` bypassed on metadata writes | runtime, rest | Get: schema writes without the capability | `domains/meta.ts:471`, `:874`, `rest-server.ts:5231`, `:6657`, `:6905`, `:7336`, `:7529` |
 | 51 | The shared metadata-write verdict itself returns `allowed` | metadata-core | Get: the one function all of row 50's doors consult answers yes before any capability is examined | `meta-write-capability.ts:134` |
-| 52 | Anonymous-deny seam satisfied on the domain dispatchers and the package/federation routes | runtime, rest | Get: passes with no `userId` | `domains/actions.ts:421`, `domains/ai.ts:60`, `domains/automation.ts:989`, `domains/meta.ts:232`, `domains/security.ts:78`, `domains/packages.ts:535`, `external-datasource-routes.ts:302`, `package-routes.ts:97` |
+| 52 | Anonymous-deny seam satisfied on the domain dispatchers and the package/federation routes | runtime, rest | Get: passes with no `userId` | `domains/actions.ts:421`, `domains/ai.ts:60`, `domains/automation.ts:989`, `domains/meta.ts:232`, `domains/security.ts:78`, `domains/packages.ts:543`, `external-datasource-routes.ts:302`, `package-routes.ts:97` |
 | 53 | MCP principal check satisfied | runtime | Get: MCP surface reachable with no user | `domains/mcp.ts:61` |
 | 54 | Package REST route capability gate bypassed | rest | Get: package read/write over REST without `manage_metadata` / `studio.access` / `setup.access` | `package-routes.ts:102` |
 | 55 | Package domain capability gates bypassed | runtime | Get: package management and package-inventory reads without the capability | `domains/packages.ts:241`, `:274` |

content/docs/permissions/system-context.mdx

@@ -193,7 +193,8 @@ Why this shape:
   census and not a verdict). Adding anchors never reds; ⛔ lowering a floor is
   MAINTAINER-ONLY. ⚠️ Note what a red here reaches: `check:platform-checklist` is not
   CI-wired (see "Operating cadence"), so it reaches whoever runs the gate — **not every
-  PR**. #11730 holds that gap.
+  PR** — plus the daily `platform-checklist-watchdog` workflow, which files or refreshes
+  one issue when the gate is red.
 - **`why` is the debt marker.** A recipe exists because stock fixtures cannot demonstrate
   something — the same discipline as a coverage waiver. Landing the fixture in the
   showcase seeds proper retires the recipe; until then `why` says what is missing and
@@ -352,6 +353,12 @@ checklist drift. It runs on a **manual / periodic cadence** instead. Run
   dangling id or a forgotten `revision` bump in your own edit;
 - **alongside a `checklist-author`** (find gaps) **or `checklist-test`** (execute items).
 
+A red gate does have a reporting channel, and it is not this cadence:
+[`.github/workflows/platform-checklist-watchdog.yml`](../../../.github/workflows/platform-checklist-watchdog.yml)
+runs `pnpm check:platform-checklist` on `main` daily and files or refreshes one issue when
+it is red (⛔ and does nothing when it is green). That closes the visibility half only —
+the cadence above is still how the gate gets run *before* a red can matter.
+
 The trade-off of staying out of CI: a new capability kind or enum value that lands on
 `main` between runs is caught at the **next** manual run, not the moment it merged. The
 ratchets still detect it — they just aren't a blocking gate. If drift-catching latency

docs/qa/platform-checklist/README.md

@@ -11,6 +11,13 @@ build/runtime model incl. the vendored-console staleness trap (§2), and the
 anti-false-positive rule (§3). This file assumes it and adds the checklist-specific
 contract.
 
+**Who sees a red gate.** `pnpm check:platform-checklist` is not wired into per-PR CI (a
+standing maintainer decision — see the README's "Operating cadence"), so the channel that
+sees its red is
+[`.github/workflows/platform-checklist-watchdog.yml`](../../../.github/workflows/platform-checklist-watchdog.yml):
+it runs the gate on `main` daily, files or refreshes exactly one issue when the gate is red,
+and does nothing at all when it is green.
+
 ## Verdicts
 
 Per **clause** (each acceptance entry gets exactly one):

docs/qa/platform-checklist/RUNNER.md

@@ -88,7 +88,7 @@
     "check:adr-links": "node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs",
     "check:adr-symbol-anchors": "node scripts/symbol-anchors.mjs --self-test && node scripts/check-adr-symbol-anchors.mjs --self-test && node scripts/check-adr-symbol-anchors.mjs",
     "check:scripts-symbol-anchors": "node scripts/symbol-anchors.mjs --self-test && node scripts/check-scripts-symbol-anchors.mjs --self-test && node scripts/check-scripts-symbol-anchors.mjs",
-    "check:platform-checklist": "node scripts/checklist-select.mjs --self-test && node scripts/check-platform-checklist.mjs",
+    "check:platform-checklist": "node scripts/checklist-select.mjs --self-test && node scripts/check-platform-checklist.mjs --self-test && node scripts/check-platform-checklist.mjs",
     "check:org-identifier": "node scripts/check-org-identifier.mjs --self-test && node scripts/check-org-identifier.mjs",
     "check:runner-env-posture": "node scripts/check-runner-env-posture.mjs --self-test && node scripts/check-runner-env-posture.mjs",
     "check:cli-test-child-env": "node scripts/check-cli-test-child-env.mjs --self-test && node scripts/check-cli-test-child-env.mjs",

package.json

@@ -10,8 +10,13 @@
  * enforce — #8146's "one answer to 'is this package writable?'" applied to the
  * read side. It reads `engine.manifests` FIRST: a package booted from an
  * artifact through `registerApp` is read-only whatever its scope says, and a
- * scope-less `type: module` carried by a multi-package artifact lands there
- * too, while a scope-less Studio-created base does not. Only the server holds
+ * scope-less BOOTED package — a marketplace install / offline file import,
+ * which reaches the registry with no `ManifestSchema` parse — lands there
+ * too, while a scope-less Studio-created base (`POST /api/v1/packages`) does
+ * not. ⛔ Neither is a module carried by a multi-package artifact:
+ * `defineStack` parses every `packages[]` entry through `ManifestSchema`, whose
+ * `scope` is `.default('project')`, so no package of a compiled artifact is
+ * ever scope-less. Only the server holds
  * `engine.manifests`, which is why the client could never derive this.
  *
  * The engine is the same shape `meta-overlay-cache.test.ts` drives: the
@@ -24,7 +29,7 @@ import { ObjectStackProtocolImplementation } from './protocol.js';
 
 /** Booted code package, explicit `scope: 'project'`. */
 const CODE_PROJECT = 'app.acme.crm';
-/** Booted, SCOPE-LESS module — the multi-package-artifact sub-package. */
+/** Booted and SCOPE-LESS — a marketplace / offline import, registered unparsed. */
 const CODE_MODULE = 'app.acme.crm.billing';
 /** Platform / marketplace delivered. */
 const SYSTEM_SCOPED = 'com.objectstack.platform';
@@ -47,7 +52,9 @@ function make() {
         row(DB_BASE),
     ];
     const byId = new Map(records.map((r) => [r.manifest.id as string, r]));
-    // What `ObjectQL.registerApp` records for every package of a loaded artifact.
+    // What `ObjectQL.registerApp` records — for every package of a loaded artifact
+    // (CODE_PROJECT, parsed and therefore `scope: 'project'`) and for a
+    // marketplace / offline import (CODE_MODULE, unparsed and therefore scope-less).
     const manifests = new Map<string, unknown>([
         [CODE_PROJECT, byId.get(CODE_PROJECT)!.manifest],
         [CODE_MODULE, byId.get(CODE_MODULE)!.manifest],

packages/metadata-protocol/src/get-meta-items-package-writable.test.ts

@@ -6797,23 +6797,53 @@ export class ObjectStackProtocolImplementation implements
         // caller that already gates therefore sees no change, provided it gated
         // on the same type this line gates on. Every such caller does:
         //
-        //  • `packages/rest`'s `GET /meta/:type` list door — the only door
-        //    that both gates and reaches this method — computes
+        //  • `packages/rest`'s `GET /meta/:type` list door — one of TWO doors
+        //    that both gate and reach this method — computes
         //    `organizationIdForMetaRead(canonicalMetaUrlType(req.params.type),
         //    ctx?.tenantId)` and then passes `type: req.params.type`, the RAW
         //    segment. The first statement of this method folds that segment
         //    through {@link canonicalizeMetaRequestType}, which IS
         //    `canonicalMetaUrlType` — so `request.type` here is the identical
         //    STRING the door gated on, and the second application is the
         //    algebraic no-op above.
+        //  • `GET /meta/diagnostics?type=` — the SECOND such door, and the one
+        //    a caller-side grep cannot see. It gates the same way
+        //    (`organizationIdForMetaRead(canonicalMetaUrlType(diagnosticsType),
+        //    ctx?.tenantId)`) and then passes its own RAW segment on — but it
+        //    reaches this method TRANSITIVELY, through
+        //    {@link getMetaDiagnostics}, whose `?type=` arm sets `targetTypes =
+        //    [request.type]` and loops `getMetaItems({ type: t,
+        //    organizationId, … })` over it. So the door's segment still arrives
+        //    here as `request.type` and is still folded by the same first
+        //    statement: the identical STRING, the same algebraic no-op, one hop
+        //    further out. ⚠️ That hop is UNDECLARED — `getMetaDiagnostics` is
+        //    not a member of `MetadataProtocol`, neither required nor optional,
+        //    so the door reaches it through a `(p as any)` cast behind a 501
+        //    feature-detect. Real at runtime, invisible to the type system, and
+        //    therefore something a caller census must be TOLD rather than left
+        //    to derive.
         //  • the search sweep's page read below gates on `'page'` and passes
         //    `'page'`; `page` is non-overridable, so both readings are
         //    `undefined` whatever the session holds.
         //  • the four remaining `organizationIdForMetaRead` call sites in
         //    `rest-server.ts` (`/layers`, the by-name read, `/history`,
         //    `/diff`) reach `getMetaItemLayered` / `getMetaItem` /
-        //    `historyMetaItem` / `diffMetaItem` — never this method — so this
-        //    line cannot move them at all.
+        //    `historyMetaItem` / `diffMetaItem` — never this method, at any
+        //    depth — so this line cannot move them at all. Two doors named
+        //    above plus these four IS that file's whole set of SIX; the
+        //    enumeration that named one door and "four remaining" described
+        //    five, and the door it dropped was the one that reaches here.
+        //
+        // ⭐ Read this list from the CALLEE side, which is how it is now built.
+        // A grep for doors that invoke `getMetaItems` answers only its own
+        // question: it cannot see a door that arrives through something else,
+        // and that is exactly how the diagnostics door went unlisted. The
+        // closed form is the other direction — `this.getMetaItems(` has THREE
+        // callers in this file: {@link getMetaDiagnostics},
+        // {@link searchAll} and {@link findReferencesToMeta}. The third gates
+        // nothing, deliberately: its door spends the organization on the
+        // reference SOURCES while `req.params.type` is the TARGET, so it hands
+        // the tenant over RAW and is not a caller this paragraph is about.
         //
         // ⛔ Gate AFTER the fold, never before it. `declaresOrgOverride`
         // tolerates the MANIFEST plurals and not the URL-only ones
@@ -7290,9 +7320,14 @@ export class ObjectStackProtocolImplementation implements
         // package switcher reads that list; it used to derive "writable"
         // client-side from `manifest.scope` alone, which is not this server's
         // rule — ADR-0070 D2 (`isWritablePackage`) reads `engine.manifests`
-        // FIRST, so a scope-less module booted from a multi-package artifact is
-        // read-only while a scope-less Studio-created base is writable, and only
-        // the server can tell the two apart. Same predicate the authoring and
+        // FIRST, so a scope-less BOOTED package — a marketplace install / offline
+        // file import, which reaches the registry through `ql.registerApp` with no
+        // `ManifestSchema` parse — is read-only while a scope-less Studio-created
+        // base (`POST /api/v1/packages`) is writable, and only the server can tell
+        // the two apart. ⛔ Neither is a module carried by a multi-package
+        // artifact: `defineStack` parses every `packages[]` entry through
+        // `ManifestSchema`, whose `scope` is `.default('project')`, so no package
+        // of a compiled artifact is ever scope-less. Same predicate the authoring and
         // lifecycle gates use (#8146: one answer), computed on a spread COPY:
         // the registry record is never mutated and the verdict is never stored.
         // The runtime dispatcher door decorates its own read of the same