Merge remote-tracking branch 'origin/main' into claude/issue-4610-notification-dual-source

Author: claude

.changeset/adr-0118-non-user-actor-contract.md

@@ -0,0 +1,4 @@
+---
+---
+
+ADR-0118（非用户 actor 的平台契约）— docs-only，不发布任何包。执行项 #4556 / #2991 / #4560 / #3166 的实施 PR 各自携带真正的 changeset。

.changeset/datasource-capabilities-retired.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/spec": major
+"@objectstack/example-crm": patch
+---
+
+feat(spec)!: retire `datasource.capabilities` — eleven flags nothing read, one of them a safety claim (#4583)
+
+`DatasourceCapabilities` declared eleven booleans — `transactions`, seven `query*`
+flags, `joins`, `fullTextSearch`, `readOnly`, `dynamicSchema` — all strict-guarded,
+all read by nothing. Pushdown is decided by the runtime driver's own `supports.*`
+object, a different mechanism entirely, so a datasource declaring
+`queryAggregations: false` never once changed which engine path ran. The block is
+removed rather than bridged: there was nothing on the other side to connect it to.
+
+**`readOnly` is why this is not tidy-up.** It reads as a safety property and was
+authored as one — the shipped CRM example labelled a datasource "CRM Analytics Read
+Replica" on the strength of it, while the datasource accepted writes exactly like the
+primary. The key had already been MOVED twice toward somewhere it might be enforced,
+out of `config` in #4410 and into `capabilities` in #4465, and was inert at every
+address. This removes it instead of moving it a third time.
+
+**Removing it does not hand you a working replacement, and the rejection says so.**
+The one enforced datasource-wide write gate is `external.allowWrites: false`, and it
+applies only to a FEDERATED datasource — `assertWriteAllowed` returns early for a
+`managed` (or unset-`schemaMode`) datasource, so that key would be equally inert for a
+local database. **A managed datasource has no read-only gate at all**; that gap is
+#4584, deliberately not invented here. Until it is answered, enforce read-only where
+it is real: grant the connection SELECT-only at the database.
+
+FROM → TO:
+
+```ts
+// before — parsed cleanly, changed nothing
+defineDatasource({
+  name: 'analytics', driver: 'sqlite', config: { filename: ':memory:' },
+  capabilities: { readOnly: true, queryAggregations: true },
+})
+
+// after — delete the block; for a FEDERATED datasource the enforced gate is:
+defineDatasource({
+  name: 'warehouse', driver: 'postgres', config: { … },
+  schemaMode: 'external',
+  external: { allowWrites: false },
+})
+```
+
+`os migrate meta --from 16` rewrites it automatically (ADR-0087 conversion
+`datasource-capabilities-removed`). Both `DatasourceSchema` and
+`DriverDefinitionSchema` are `.strict()`, so a leftover key is a loud rejection
+carrying the prescription — never a silent strip.
+
+Also fixed: `READ_ONLY_BELONGS_ON_DATASOURCE`, the prescription every SQL driver
+shares for a `readOnly` written inside `config`, was still sending authors *to* the
+removed key. It now names the enforced gate and states plainly where that gate does
+not apply — a prescription that lands on an inert key manufactures exactly the belief
+it was meant to correct.
+
+The `datasource` liveness ledger drops from 20 dead properties to 9 (remaining:
+`healthCheck` ×3, `retryPolicy` ×4, `external` ×2 — batches B/C/D of #4583).

.changeset/docs-extend-faq-reversed-rot.md

@@ -0,0 +1,27 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(docs): the schema-extension FAQ rotted in reverse — `.extend()` works on `FieldSchema` again since protocol 17
+
+The #3890 fix taught that `FieldSchema` / `ObjectSchema` / `ActionSchema` are all
+`ZodPipe`s and that `FieldSchema.extend` throws. True when written; protocol 17
+(#3855) then retired the deprecated aliases whose lowering was the whole reason
+for the field/object transforms, the pipes collapsed to plain `ZodObject`s, and
+both prose claims inverted within days: `.extend` works, and the recommended
+`FieldSchema.in` is now `undefined` — following the FAQ was once again the only
+way to hit an error. Only `ActionSchema` (whose `requiresFeature` → `visible`
+lowering is still live) remains a pipe.
+
+The example gate never noticed because the checked block used only `.parse()` —
+deliberately shape-agnostic after CI rejected the first #3890 attempt. That made
+the code durable and left the PROSE as the only load-bearing surface, which is
+where the rot settled.
+
+So the rewrite moves the claim into the checked block: it now calls
+`FieldSchema.extend({ … })` directly, so if the schema ever grows a transform
+again the gate goes red instead of the prose going quietly wrong. Composition
+stays as the shape-agnostic default, `ActionSchema` is documented as the pipe
+case with the `.in.extend` caveat, and the FAQ teaches the one-line probe
+(`typeof SomeSchema.extend === 'function'`) instead of a table of shapes that
+history says will not stay true.

.changeset/pm-dispatch-triage-lessons.md

@@ -0,0 +1,4 @@
+---
+---
+
+Internal agent tooling only (`.claude/` pm-dispatch backlog-sweep duty + stale-premise checks + process discipline) — releases nothing.

.claude/agents/os-dev.md

@@ -49,6 +49,11 @@ build/test runs OOM it.** Binding rules:
 4. **Clean up when done**: after the PR is up, remove your worktree
    (`git worktree remove <path> --force`) — leftover `node_modules` trees
    exhaust the container's disk, which fails as confusingly as OOM.
+5. **Never kill by process name.** `pkill -f vitest` (or any name-matched
+   kill) can take down a parallel agent's run — AGENTS.md's server rule,
+   applied to every process. Record the PID of what you start and operate
+   on that PID only (`kill $PID`, liveness via `kill -0 $PID` — a
+   `pgrep -f` pattern can match your own watcher and never terminate).
 
 Definition of done, in order:
 

.claude/skills/pm-dispatch/SKILL.md

@@ -114,10 +114,45 @@ shared files, and the merge queue is one lane regardless. Scaling order:
 2. When one PM genuinely can't keep up: a second session takes a **whole
    repo** as its shard (`/pm-dispatch repo:objectstack-ai/objectui`) —
    file universes are disjoint by construction. A sharded PM states its
-   shard in every claim comment and **never claims outside it**; cross-repo
-   parent/sub-issue chains stay with the main-backlog PM.
+   shard in every claim comment and **never claims outside it**.
 3. Multiple PMs on the SAME queue: prohibited — all cost, no throughput.
 
+**Shard ownership is registered, never assumed.** A registry issue in the
+main backlog (`[PM] 分片分工登记表`) records which session owns which
+shard; a PM taking over a shard comments there as its FIRST action, and
+comments again when handing off. An unowned shard may be **caretaken** by
+the main-backlog PM (triage + dispatch), but the moment a shard is
+registered to another session, the caretaker stops dispatching into it —
+in-flight claimed tasks finish under whoever claimed them (the claim
+protocol makes the handoff collision-free), and everything else belongs to
+the new owner. State the mode in claim comments (「cloud 分片,主 PM 代管」
+vs a registered shard PM's own tag) so the registry and the claims never
+disagree silently.
+
+**Cross-shard transfer protocol — work crosses shard lines, PMs never
+do.** When a sharded PM's task (or a sub-task of its parent issue) needs a
+change in another shard's repo:
+
+- **Transfer via the target queue**: file the piece as an issue in the
+  target repo with `pm:queue` and a source line (`Part of
+  <owner/repo>#<n>`). The target shard's PM picks it up through its own
+  backlog sweep — the queue label IS the inter-PM channel; PMs never need
+  to talk directly, and never dispatch into a repo whose in-flight batch
+  they cannot see (that is the same collision the same-queue ban exists
+  for).
+- **Dependencies via `Blocked-by:`** on the waiting side; the waiting PM's
+  batch selection skips it until the upstream merges.
+- **Follow-up chores belong to the consuming shard**: when the upstream
+  change lands (say spec gained a key), the dependent-repo adaptation issue
+  is filed by the PM of the repo that consumes it — it knows its surfaces.
+- **Shared contract surfaces have one owner**: anything touching
+  `packages/spec` transfers to the main-backlog (objectstack) PM
+  regardless of who needs it — only that PM sees the repo's in-flight
+  batch and generated-baseline collisions.
+- Cross-repo parent/sub-issue chains as a whole stay coordinated by the
+  main-backlog PM; sharded PMs coordinate only chains fully inside their
+  shard.
+
 **5. One board, no second tracker.** The pm labels above are the state
 machine; an org-level GitHub Project pulling issues/PRs from all three repos
 gives the maintainer a single view (filter by `repo:*` and `pm:*`). The PM
@@ -126,13 +161,43 @@ the loop resumable and the board honest.
 
 ## The round loop
 
+### 0. Backlog sweep — classification is a standing duty, not a request
+
+The maintainer does not pre-sort the backlog. On every round (and every
+idle check-in), sweep issues that carry no `pm:*` / `needs-user-decision`
+label and classify each:
+
+- **Auto-queue (`pm:queue`)**: a concrete defect with a named location or
+  repro; a scoped tooling/gate fix; a restore-invariant finding; a
+  test-only pin. Nothing to ask — label it and it becomes dispatchable.
+- **Maintainer confirm (`needs-user-decision`)**: design cards, feature/
+  contract-shape proposals, multi-week programs needing appetite and
+  sequencing, anything touching stored-data migration shape or removing a
+  shipped capability. The label alone is the inbox entry; the deep two-axis
+  analysis is written when the card is actually taken up.
+- **Repair first**: a body truncated by GitHub's sanitizer (bare `<x>`
+  swallows the rest at rest) cannot be dispatched — comment the repair
+  instruction and move on.
+
 ### 1. Fetch candidates
 
 List open issues matching the filter, excluding anything assigned or labeled
 `needs-user-decision`. **Open sub-issues of a matching parent are candidates
 too** — they inherit the parent's queue membership and need no label of their
-own. Read each candidate's full body — triage, batch selection (steps 2–3)
-and the dispatch prompt all need it.
+own. Read each candidate's full body **and its comments** — a comment may
+record that half the work already shipped (#4075's step 1 had been merged
+for three days; the claim went out without reading the comment that said
+so). Triage, batch selection (steps 2–3) and the dispatch prompt all need
+the full picture.
+
+**Stale-premise check before every dispatch.** Issues describe the repo as
+of their filing date; main moves ~18 merges a day. Before dispatching,
+check the named files/subsystem against recent main history (`git log
+--oneline -20 -- <paths>`, or search merged PRs referencing the issue's
+keywords). Three same-day cases: #4525 (spec key landed 3 days before
+filing), #4379 (fix merged via #4459 with the exact proposed sketch),
+#4075 (step 1 shipped via objectui#3032). A dispatch that starts with "is
+this still true?" costs minutes; one that doesn't costs an agent-run.
 
 ### 2. Triage — routing is the PM's job, never the maintainer's
 

content/docs/deployment/troubleshooting.mdx

@@ -364,34 +364,44 @@ Yes. All schemas work with plain JavaScript. You lose compile-time type checking
 
 ### How do I extend a built-in schema?
 
-**Not with `.extend()` on the schema itself.** Several built-in schemas —
-`FieldSchema`, `ObjectSchema`, `ActionSchema` — carry a `.transform()` that lowers
-author-facing sugar at parse time, which makes the exported value a **`ZodPipe`,
-not a `ZodObject`**. `FieldSchema.extend` is `undefined`, so calling it throws
-`is not a function`.
-
-Compose instead: parse with the built-in schema, and validate your additions
-alongside it. This keeps the transform running, which `.extend()` would discard.
+It depends on whether the schema you are extending carries a parse-time
+`.transform()`. A plain schema (`FieldSchema`, `ObjectSchema` since protocol 17
+retired their alias-lowering transforms, #3855) is a `ZodObject` and takes
+`.extend()` directly. The composition form works in **either** case, and is the
+safe default when you don't want to track which is which:
 
 {/* os:check */}
 ```typescript
 import { z } from 'zod';
 import { FieldSchema } from '@objectstack/spec/data';
 
-const CustomProps = z.object({ customProperty: z.string().optional() });
+// Plain object schema: .extend() works directly. (This line is what pins the
+// claim — if FieldSchema ever grows a transform again and becomes a ZodPipe,
+// .extend vanishes and this example fails CI instead of the prose going stale.)
+const CustomFieldSchema = FieldSchema.extend({
+  customProperty: z.string().optional(),
+});
+CustomFieldSchema.parse({ name: 'code', type: 'text', customProperty: 'x' });
 
+// Composition: parse with the built-in schema, validate additions alongside.
+// Shape-agnostic — works for plain schemas AND transform-carrying pipes.
+const CustomProps = z.object({ customProperty: z.string().optional() });
 function parseCustomField(input: unknown) {
   return { ...FieldSchema.parse(input), ...CustomProps.parse(input) };
 }
-
 parseCustomField({ name: 'code', type: 'text', customProperty: 'x' });
 ```
 
-If you genuinely need one merged schema object, `FieldSchema.in` is the
-`ZodObject` the pipe wraps, so `FieldSchema.in.extend({ … })` builds one — but
-the result **skips the transform**, so author-facing sugar the pipe would have
-lowered stays raw. Prefer the composition above unless you specifically want the
-untransformed shape.
+A schema that still lowers author-facing sugar at parse time — `ActionSchema`
+(its `requiresFeature` → `visible` lowering) is one, as of protocol 17 — is a
+**`ZodPipe`**, where `.extend` does not exist: prefer the composition form.
+Reaching the inner object via `.in.extend({ … })` builds a merged schema but
+**skips the transform**, so the sugar the pipe would have lowered stays raw.
+
+A quick check when unsure: `typeof SomeSchema.extend === 'function'` — a pipe
+reports `undefined`. This page once asserted the shapes the other way around;
+the schemas moved under it within days (#3890 → #3855), which is why the
+load-bearing claim above now lives in a CI-checked block rather than prose.
 
 ### Where are the JSON Schemas for IDE autocomplete?
 

content/docs/getting-started/quick-reference.mdx

@@ -23,7 +23,7 @@ Core business logic and data modeling schemas.
 | **[Query](/docs/references/data/query)** | `query.zod.ts` | Query, QueryAST | Query AST with joins, aggregations |
 | **[Filter](/docs/references/data/filter)** | `filter.zod.ts` | QueryFilter, FilterCondition | Advanced filtering operators |
 | **[Validation](/docs/references/data/validation)** | `validation.zod.ts` | ValidationRule | Business validation rules |
-| **[Datasource](/docs/references/data/datasource)** | `datasource.zod.ts` | Datasource, DatasourceCapabilities | Database connection configs |
+| **[Datasource](/docs/references/data/datasource)** | `datasource.zod.ts` | Datasource, DriverDefinition | Database connection configs |
 | **[Analytics](/docs/references/data/analytics)** | `analytics.zod.ts` | Analytics | Data analytics and aggregation |
 | **[Mapping](/docs/references/data/mapping)** | `mapping.zod.ts` | FieldMapping | Field transformation mappings |
 | **[Hook](/docs/references/data/hook)** | `hook.zod.ts` | Hook, HookEvent | Lifecycle event hooks |

content/docs/references/data/datasource.mdx

@@ -16,7 +16,7 @@ Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowf
 ## TypeScript Usage
 
 ```typescript
-import { DatasourceSchema, DatasourceCapabilities, DriverDefinitionSchema, DriverType, ExternalDatasourceSettingsSchema } from '@objectstack/spec/data';
+import { DatasourceSchema, DriverDefinitionSchema, DriverType, ExternalDatasourceSettingsSchema } from '@objectstack/spec/data';
 import type { Datasource, DriverDefinition, ExternalDatasourceSettings } from '@objectstack/spec/data';
 
 // Validate data
@@ -36,7 +36,6 @@ const result = DatasourceSchema.parse(data);
 | **driver** | `string` | ✅ | Underlying driver type |
 | **config** | `Record<string, any>` | ✅ | Driver specific configuration |
 | **pool** | `{ min: number; max: number; idleTimeoutMillis: number; connectionTimeoutMillis: number }` | optional | Connection pool settings |
-| **capabilities** | `{ transactions: boolean; queryFilters: boolean; queryAggregations: boolean; querySorting: boolean; … }` | optional | Capability overrides |
 | **healthCheck** | `{ enabled: boolean; intervalMs: number; timeoutMs: number }` | optional | Datasource health check configuration |
 | **ssl** | `{ enabled: boolean; rejectUnauthorized: boolean; ca?: string; cert?: string; … }` | optional | SSL/TLS configuration for secure database connections |
 | **retryPolicy** | `{ maxRetries: number; baseDelayMs: number; maxDelayMs: number; backoffMultiplier: number }` | optional | Connection retry policy for transient failures |
@@ -55,27 +54,6 @@ const result = DatasourceSchema.parse(data);
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 
 
----
-
-## DatasourceCapabilities
-
-### Properties
-
-| Property | Type | Required | Description |
-| :--- | :--- | :--- | :--- |
-| **transactions** | `boolean` | ✅ |  |
-| **queryFilters** | `boolean` | ✅ |  |
-| **queryAggregations** | `boolean` | ✅ |  |
-| **querySorting** | `boolean` | ✅ |  |
-| **queryPagination** | `boolean` | ✅ |  |
-| **queryWindowFunctions** | `boolean` | ✅ |  |
-| **querySubqueries** | `boolean` | ✅ |  |
-| **joins** | `boolean` | ✅ |  |
-| **fullTextSearch** | `boolean` | ✅ |  |
-| **readOnly** | `boolean` | ✅ |  |
-| **dynamicSchema** | `boolean` | ✅ |  |
-
-
 ---
 
 ## DriverDefinition
@@ -89,7 +67,6 @@ const result = DatasourceSchema.parse(data);
 | **description** | `string` | optional |  |
 | **icon** | `string` | optional |  |
 | **configSchema** | `Record<string, any>` | ✅ | JSON Schema for connection configuration |
-| **capabilities** | `{ transactions: boolean; queryFilters: boolean; queryAggregations: boolean; querySorting: boolean; … }` | optional |  |
 
 
 ---