Merge remote-tracking branch 'origin/main' into claude/issue-24962-cbp-master-object-read

Author: claude

.changeset/24900-webhook-label-description-live.md

@@ -0,0 +1,9 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): `os lint` no longer tells authors to remove a declared webhook's `label` or `description`
+
+Clause-②: no (a liveness-ledger re-grade: no schema, accept set, served body or error code moves; only the advisory `liveness-dead-property` warning on these two keys stops)
+
+The shipped liveness ledger (`liveness/webhook.json`) graded a declared webhook's `label` and `description` `dead` once the boot seeder that copied them into a `sys_webhook` row retired, and the advisory lint warned "Remove it" on every webhook that authored them. They are read: the Studio metadata list and quick-find show both keys, read off `GET /api/v1/meta/webhook`. Both rows are now `live`, so a declared webhook may keep its `label` and `description` and no warning is printed for them. Nothing else changes: the dispatcher still delivers on the same props as before.

.changeset/24909-missing-driver-client-remedy.md

@@ -8,6 +8,6 @@ Clause-②: no
 
 - **What was wrong.** When a boot-critical datasource could not connect because a module could not be resolved, the refusal always ended on the unbuilt-workspace remedy: "The driver package could not be LOADED at all … That is a build precondition … Run `pnpm install && pnpm build`, then start again." That is right for a monorepo checkout whose driver build output is missing. It is wrong for a project that points at PostgreSQL or MySQL without installing the database client: `pg` and `mysql2` are optional peers of `@objectstack/driver-sql` (and `better-sqlite3` an optional dependency) that the project installs itself, so neither command adds them, and a reader who followed the advice was refused again with the same text.
 - **Now.** When the module that could not be resolved is one of those three clients (knex reports it as `Cannot find module 'pg'`), the refusal ends on the install of that client instead: `npm install pg` (with the `pnpm add` and `yarn add` spellings beside it), and no build step. It names no environment variable.
-- **Unchanged.** A driver package whose build output is missing, or an `@objectstack/…` driver package that is not installed, still ends on `pnpm install && pnpm build`. A refused connection, a wrong DSN or a rejected password still ends on the same sentence as before. When the boot is refused, the error type, the retained connection state and the `OS_ALLOW_DRIVER_CONNECT_FAILURE` degraded boot do not change: only the closing sentence of the refusal is different.
+- **Unchanged.** A driver package whose build output is missing, or a required `@objectstack/…` driver package that is not installed (any but the optional `@objectstack/driver-turso`, `@objectstack/driver-mongodb` and `@objectstack/driver-sqlite-wasm`), still ends on `pnpm install && pnpm build`. A refused connection, a wrong DSN or a rejected password still ends on the same sentence as before. When the boot is refused, the error type, the retained connection state and the `OS_ALLOW_DRIVER_CONNECT_FAILURE` degraded boot do not change: only the closing sentence of the refusal is different.
 
 What to do: install the client the refusal names next to the server that opens the datasource, then start again.

.changeset/24937-optional-driver-package-remedy.md

@@ -0,0 +1,13 @@
+---
+'@objectstack/service-datasource': patch
+---
+
+fix(service-datasource): a datasource whose optional driver package is not installed (`@objectstack/driver-turso`, `@objectstack/driver-mongodb`, `@objectstack/driver-sqlite-wasm`) is refused with that package's install alone, no longer followed by "Run `pnpm install && pnpm build`"
+
+Clause-②: no
+
+- **What was wrong.** A `turso`, `mongodb` or `sqlite-wasm` datasource whose driver package is not installed is refused at boot, and the refusal already says so and names the install (`npm install @objectstack/driver-turso`, with the `pnpm add` and `yarn add` spellings beside it). It then went on to end on the unbuilt-workspace remedy anyway: "… That is a build precondition … Run `pnpm install && pnpm build`, then start again." Those are two fixes that contradict each other, and the second does nothing for a project, which adds these optional packages itself. Measured on the published release with a declared `turso` datasource and no `@objectstack/driver-turso` installed.
+- **Now.** When the module that could not be resolved is one of those three packages, by its bare name (`Cannot find package '@objectstack/driver-turso'` under ESM, `Cannot find module '@objectstack/driver-turso'` under CJS), the refusal ends on one sentence that defers to the install named above it. It names no second command, no build step and no environment variable.
+- **Unchanged.** A driver package whose build output is missing (the error names a path into its `dist/`, which is what a monorepo checkout that has been installed but not built reports), or a required `@objectstack/…` package that is not installed, still ends on `pnpm install && pnpm build`. A missing `pg`, `mysql2` or `better-sqlite3` client still ends on the install of that client. A refused connection, a wrong DSN or a rejected password still ends on the same sentence as before. When the boot is refused, the error type, the retained connection state and the `OS_ALLOW_DRIVER_CONNECT_FAILURE` degraded boot do not change, and the driver factory's own messages are unchanged: only the closing sentence of the refusal is different.
+
+What to do: install the driver package the refusal names next to the server that opens the datasource, then start again.

content/docs/ai/skills-reference.mdx

@@ -18,17 +18,20 @@ The catalog ships as the npm package [`@objectstack/skills`](https://www.npmjs.c
 
 ```bash
 # 1 · the catalog, at the version of your installed @objectstack/spec
-npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+#   npm: npm install --save-dev "@objectstack/skills@…"   ·   yarn: yarn add -D "@objectstack/skills@…"
 
 # 2 · copy it from node_modules into your agent's skills directory
 npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
+Add the package with the manager that installed the project: in a pnpm project, `npm install --save-dev` exits `1` with `npm error Cannot read properties of null (reading 'edgesOut')`.
+
 Step 2 is the [skills CLI](https://www.npmjs.com/package/skills)'s sync from `node_modules`: it finds the skills under `node_modules/@objectstack/skills/dist/skills/`, copies each one into your agent's directory — for `claude-code`, real files in `.claude/skills/<skill>` and nowhere else — and records the source and version in `skills-lock.json`. Commit both with the project. Keep `--copy`: without it the sync writes links into `node_modules`, which is not committed, so a clone of the project gets dangling links and no skills. The CLI is pinned because `experimental_sync` is that tool's own unstable interface; `create-objectstack` runs the same version. Name your own runtime after `--agent` (`codex`, `cursor`, …), one runtime per run — never `--agent '*'`, which copies the catalog into dozens of agent directories at once. A bare `npm install --save-dev @objectstack/skills` installs whichever version the registry tags `latest`, not your spec's — keep the version in step 1.
 
 **Updating.** The catalog is versioned as **one bundle**, and it moves only with your ObjectStack version — you never track or update a skill on its own: bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the sync (step 2, same flags) and commit what it changed.
 
-**Which versions exist.** `@objectstack/skills` is published from `18.0.0-next.0` on; there is no 17.x release of it. A project on `@objectstack/spec` 17.x therefore has no catalog bound to its version: step 1 refuses with `ETARGET` (`No matching version found`), and moving it to 18 includes [a skills step](/docs/upgrading#moving-the-dependency-pins). One scaffolder is the exception to the next paragraph: `create-objectstack@18.0.0-next.0` still installed the skills from the repository's `main` with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add` and exits 0), so in a project it scaffolded run `npx skills remove --all` — or remove the `objectstack-*` skills by name, as the [upgrade step](/docs/upgrading#moving-the-dependency-pins) does, if you added others — and then steps 1 and 2.
+**Which versions exist.** `@objectstack/skills` is published from `18.0.0-next.0` on; there is no 17.x release of it. A project on `@objectstack/spec` 17.x therefore has no catalog bound to its version: step 1 refuses with `ERR_PNPM_NO_MATCHING_VERSION` (npm: `ETARGET`; both print `No matching version found`), and moving it to 18 includes [a skills step](/docs/upgrading#moving-the-dependency-pins). One scaffolder is the exception to the next paragraph: `create-objectstack@18.0.0-next.0` still installed the skills from the repository's `main` with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add` and exits 0), so in a project it scaffolded run `npx skills list` first, because `npx skills remove --all` removes every installed skill without asking; run that when the list shows only the `objectstack-*` skills — or remove those by name, as the [upgrade step](/docs/upgrading#moving-the-dependency-pins) does, if you added others — and then steps 1 and 2.
 
 **New projects.** `create-objectstack` runs both steps while it scaffolds: the `package.json` it writes depends on `@objectstack/skills` at the same version as `@objectstack/spec`, its dependency install puts the catalog in `node_modules`, and step 2 copies it for one agent runtime, into `.claude/skills/`. Its closing summary prints step 2 again — to re-run after an upgrade, and with another `--agent` for any other runtime you use.
 

content/docs/ai/skills.mdx

@@ -29,10 +29,13 @@ See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for
 Skills ship as the npm package `@objectstack/skills`, released with the other `@objectstack/*` packages at one shared version. Install it at your installed `@objectstack/spec`'s version — the catalog's version is then your spec's — and copy it from `node_modules` into your agent's directory, the two steps `create-objectstack` runs when it scaffolds a project:
 
 ```bash
-npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+#   npm: npm install --save-dev "@objectstack/skills@…"   ·   yarn: yarn add -D "@objectstack/skills@…"
 npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
+Add the package with the manager that installed the project: in a pnpm project, `npm install --save-dev` exits `1` with `npm error Cannot read properties of null (reading 'edgesOut')`.
+
 The skills land as real files in `.claude/skills/`; commit them with the project, and keep `--copy` — without it they are links into `node_modules`, which a clone does not have. Name your own runtime after `--agent` (`codex`, `cursor`, …). The catalog is versioned and updated as **one unit**, with ObjectStack itself: bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the sync. The package is published from `18.0.0-next.0` on (there is no 17.x release); for what the sync writes, the versions, the one scaffolder that is an exception and the `next` channel, see the [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
 
 ---

content/docs/upgrading.mdx

@@ -108,10 +108,14 @@ command for this move; it is four steps you run yourself.
    npx skills remove objectstack-ai objectstack-api objectstack-automation \
      objectstack-data objectstack-formula objectstack-i18n objectstack-platform \
      objectstack-pm-dispatch objectstack-query objectstack-ui objectstack-upgrade -y
-   npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+   pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+   #   npm: npm install --save-dev "@objectstack/skills@…"   ·   yarn: yarn add -D "@objectstack/skills@…"
    npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
    ```
 
+   Add the package with the manager that installed the project: in a pnpm
+   project, `npm install --save-dev` exits `1` with
+   `npm error Cannot read properties of null (reading 'edgesOut')`.
    The list names every skill the catalog carried during 17.x, and a name that
    is not installed is skipped; `npx skills remove --all` does the same when
    these are the only skills the project has. Run `npx skills list` first:

docs/qa/platform-checklist/areas/integration-system.json

@@ -642,7 +642,7 @@
       ],
       "source": [
         "packages/spec/src/automation/webhook.zod.ts#WebhookTriggerType (WebhookTriggerType enum + why undelete/api are absent; materialization contract; strict shape #4001)",
-        "packages/spec/liveness/webhook.json (9 props live on the registry read; label/description dead since the boot seeder retired)",
+        "packages/spec/liveness/webhook.json (9 props live on the registry read; label/description live on the Studio metadata list and quick-find, which read the declared item over GET /api/v1/meta/webhook)",
         "packages/plugins/plugin-webhooks/src/declared-webhooks.ts + auto-enqueuer.ts (the registry read and its remaps; trigger→event mapping incl. the #4639 bulk pair; #3196 unknown-trigger warn; the activation-ledger switch; an 18.0 database's seeded rows read beside the declaration)",
         "packages/services/service-messaging/src/http-outbox.ts#HttpRedeliverError (delivery statuses, attempts; HttpRedeliverError + assertHttpRedeliverable/assertRedeliverAllowed — terminal-only, the attempts===0 parked-row refusal, the fail-closed guard) + packages/services/service-messaging/src/http-signature-at-rest.integration.test.ts (redelivery replays the stored signature byte-for-byte)",
         "packages/plugins/plugin-webhooks/src/webhook-outbox-plugin.ts#session (POST /api/v1/webhooks/redeliver — session auth with NO capability gate by design ('every authenticated user counts'), #10740 activeOrganizationId threading, the 401/400/404/409/500 arms) + (the #8069 redeliver-guard install; its ABSENCE is an error-level log, not a silent pass)",

examples/app-showcase/src/automation/webhooks/index.ts

@@ -4,8 +4,10 @@ import { defineWebhook } from '@objectstack/spec/automation';
 
 /**
  * Outbound webhook — fans out task lifecycle events (create/update/delete)
- * to an external endpoint. No `label` / `description`: a declared webhook has
- * no Setup row to show them on, and the liveness ledger marks both dead.
+ * to an external endpoint. A declared webhook has no Setup row, but a `label` /
+ * `description` authored here is not inert: the liveness ledger grades both
+ * `live`, because the Studio metadata list and quick-find show them, read off
+ * `GET /api/v1/meta/webhook`.
  * Authored via `defineStack({ webhooks })`; the webhooks plugin's dispatcher
  * reads this declaration from the registry (ADR-0131 D2) — no `sys_webhook`
  * row is written for it.

packages/lint/src/lint-liveness-properties.test.ts

@@ -251,12 +251,13 @@ describe('lintLivenessProperties', () => {
   // #3494 PRUNED the aspirational dead props from the schema and the #3489
   // materializer bridge made every remaining prop live. ADR-0131 D2 then
   // retired that bridge: a declared webhook is read from the registry and has
-  // no Setup row, so the two display-only props, `label` and `description`,
-  // lost their only reader and the ledger marks them dead. Every delivery-
-  // bearing prop stays silent. Runs against the REAL webhook.json, so a ledger
-  // flip that is not carried to authors fails here.
+  // no Setup row. The two display-only props, `label` and `description`, stay
+  // live all the same: the Studio metadata list and quick-find draw them off
+  // `GET /api/v1/meta/webhook`, so the ledger grades them live and nothing
+  // warns. Runs against the REAL webhook.json, so a ledger flip that is not
+  // carried to authors fails here.
 
-  it('warns on a declared webhook\'s label and description only — every delivery-bearing prop is live', () => {
+  it('stays silent on a declared webhook that authors every prop, label and description included', () => {
     const findings = lintLivenessProperties({
       webhooks: [{
         name: 'showcase_task_changed',
@@ -272,14 +273,7 @@ describe('lintLivenessProperties', () => {
         description: 'Sends task lifecycle events to an external system.',
       }],
     });
-    expect(findings.map((f) => [f.rule, f.message.match(/`(\w+)`/)?.[1]])).toEqual([
-      ['liveness-dead-property', 'label'],
-      ['liveness-dead-property', 'description'],
-    ]);
-    for (const f of findings) {
-      expect(f.where).toBe("webhook 'showcase_task_changed'");
-      expect(f.hint).toContain('no Setup row');
-    }
+    expect(findings).toEqual([]);
   });
 
   it('stays silent on a declared webhook that authors only what is delivered on', () => {