Merge remote-tracking branch 'origin/main' into claude/issue-14787-user-writable-locale

Author: claude

.changeset/rest-server-config-dead-keys-retired.md

@@ -0,0 +1,83 @@
+---
+"@objectstack/spec": minor
+"@objectstack/rest": minor
+---
+
+feat(spec): retire the ten inert `RestServerConfig` keys the liveness ledger recorded as `dead` (#14691, ADR-0049 enforce-or-remove)
+
+<!-- adr-0087: registered rest-server-config-dead-keys-retired -->
+
+**BREAKING** accept-set narrowing, landing after the v17.0.0 cut (the lockstep
+launch-window convention ships it as `minor`; the prescription is registered
+under protocol major 18, where `os migrate meta` users will look).
+
+#14369 enrolled the four `RestServerConfig` sub-objects (`crud`, `metadata`,
+`batch`, `routes`) in the spec liveness ledger and found 15 of their 32 rows
+`dead`: parsed, defaulted and normalized into the REST server's config by
+`normalizeConfig` (#11984) and never read back. This change is the
+enforce-or-remove call on every one of them, taken per family, and every
+family resolved to REMOVE — each promised capability either already exists at
+its proper seat or would contradict a fixed contract. The closed-set cloud
+sweep (#14796, `objectstack-ai/cloud` @ `9b6abe0f2fd5`) returned zero hits,
+structurally: cloud never authors a `RestServerConfig`.
+
+**What is refused:** authoring any of the ten keys below. Each is a
+`retiredKey()` tombstone (all four sub-schemas are non-strict `z.object()`s,
+so a plain deletion would have silently stripped the key), so authoring it is
+a `tsc` error and a parse error carrying the prescription — and, because
+`RestServer` parses these sub-objects at construction (#11984),
+`new RestServer(...)` / `createRestApiPlugin().start()` now refuse a config
+that carries one, naming the sub-object, the key and the declaring schema.
+
+**FROM → TO** (delete the key in every case; none ever had an effect to preserve):
+
+- `crud.patterns` → the mounted CRUD paths are the contract the client SDK, the
+  discovery document and the served `/openapi.json` all describe; `crud.dataPrefix`
+  moves them deployment-wide. An endpoint on a custom path or method is a
+  declarative `api` endpoint (`type: 'object_operation'`). Its value schema
+  `CrudEndpointPatternSchema` / type `CrudEndpointPattern` are removed with it
+  (no other consumer; `CrudOperation` stays — `GeneratedEndpoint.operation` reads it).
+- `crud.objectParamStyle` → the object name is always a path segment.
+- `metadata.cacheTtl` → `metadata.enableCache` is the live switch (it selects the
+  protocol's `getMetaItemCached` path, which takes no TTL); a declarative `api`
+  endpoint's `cacheTtl` is the key that reaches the wire. The unbounded negative
+  TTL this key accepted goes with it.
+- `metadata.endpoints.schema` → gated `GET /meta/:type/:name/schema`, which does
+  not exist; `endpoints.types` / `items` / `item` gate real mounts and stay.
+- `batch.operations.upsertMany` → gated `POST /data/:object/upsertMany`, which
+  was never built; upsert is an operation type of the generic
+  `POST /data/:object/batch` endpoint (`BatchOperationType` `'upsert'`), gated
+  by `batch.enableBatchEndpoint`.
+- `batch.defaultAtomic` → atomicity is the per-request `options.atomic`
+  (ADR-0119 D4, opt-in); a server-side default that flipped it silently would
+  change the failure semantics of callers who send nothing, which that ADR
+  refused. Callers that need all-or-nothing send `options: { atomic: true }`.
+- `routes.includeObjects` / `routes.excludeObjects` / `routes.overrides`
+  (`enabled` / `basePath` / `operations`) → per-object API exposure is declared
+  ON the object and enforced by the REST data surface: `enable.apiEnabled: false`
+  hides it (404), `enable.apiMethods` whitelists its operations (405). The data
+  base path is deployment-wide (`crud.dataPrefix`).
+- `routes.nameTransform` → the object `name` is the canonical id on every
+  surface, the REST path segment included; there is no URL transform to configure.
+
+**What stays, byte-identical:** every live key of the four sub-objects —
+`crud.operations.*`, `crud.dataPrefix`, `metadata.prefix` / `enableCache` /
+`maskObjectFields` / `endpoints.types|items|item`, `batch.maxBatchSize` /
+`enableBatchEndpoint` / `operations.createMany|updateMany|deleteMany` — with
+its default and its mount. The mounted REST surface does not change: none of
+the ten keys ever reached it. `@objectstack/rest`'s normalized config no longer
+carries the retired keys (they were written and never read), and the #11984
+pins of their accept/reject behaviour are reversed to refusal pins, by design.
+
+The retirement kit: `retiredKey()` tombstones on the four sub-schemas;
+`RestServerConfigSchema`'s `@example` no longer advertises
+`routes: { excludeObjects: [...] }`; ledger rows kept `dead` with a REMOVED
+note and `evidenceScope: cross-repo` (the two container rows collapse into one
+each, since their child keys left the walked shape); `RETIRED_KEYS_BY_MAJOR[18]`
+× 10 and `RETIRED_DEFS_BY_MAJOR[18]` `api/CrudEndpointPattern`; D3 semantic
+entry `rest-server-config-dead-keys-retired`. No D2 conversion: a
+`RestServerConfig` is plugin TS configuration (REST plugin constructor /
+`plugin-hono-server` `restConfig`), never a stack collection member or a
+`sys_metadata` row (the `openApi31` precedent, #4579), so there is no source
+for the chain to rewrite and the prescription carries no `os migrate meta`
+sentence.

.changeset/run-dev-stderr-blocking-write-hang.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/cli": patch
+---
+
+fix(cli): `run-dev.js` can no longer freeze in the kernel when its stderr reader stops reading
+
+Over an unbuilt workspace with the read end of its output alive but not being
+drained, the dev entry point is contracted to give up and exit 2 rather than
+wait. Intermittently it did neither: it stayed alive past every ceiling and
+ended only when something killed it — 27 of 30 runs on a cold `tsx` transform
+cache, against 1 of 90 on a warm one.
+
+The bound that was supposed to stop it (`STDERR_DRAIN_STALL_MS`, polled by a
+50 ms `setInterval`) was not late; it was unreachable. Sampled from outside the
+process, the main thread was parked inside `write(2)` on fd 2 with `O_NONBLOCK`
+clear on that file description, so the event loop was not running and no timer,
+callback or promise in the file could fire. No ceiling of any size separates
+that from a wait, which is why raising and re-deriving one never helped.
+
+The flag is not stable and nothing in this repo clears it: node sets
+`O_NONBLOCK` when it opens the pipe, and libuv clears it again in the pre-exec
+of any child spawned with inherited stdio — and because inheriting is `dup2`,
+the flag lives on an open file description the spawner shares, so the spawner
+loses it too. Under `tsx` that child is the esbuild service, started when a
+module has to be transformed, which is why a fresh CI checkout hits this and a
+warm developer box almost never does. Measured on one run: `O_NONBLOCK` true at
+102 ms, false at 1132 ms in the same sample the esbuild service appears in, main
+thread in `write(2)` from 2730 ms and never out of it.
+
+`bin/run-dev.js` now re-asserts non-blocking mode on the write path before each
+stderr write, which cannot be outrun by a later spawn the way a one-shot at
+startup can. This is the inverse of the `setBlocking(true)` both this file and
+`src/utils/format.ts` refuse: it is what keeps their shared premise — that a
+write to a pipe gets buffered rather than parking the thread — true.
+
+`bin/` is not named in this package's `files`, so only `bin/run.js` (the `bin`
+target) is packed: no published byte changes here.

.changeset/service-job-lease-window-docblock.md

@@ -0,0 +1,33 @@
+---
+'@objectstack/service-job': patch
+---
+
+docs(service-job): state the scheduler leader-election guarantee with its window (#14619)
+
+Documentation only — no runtime change, no type change, no accept/reject
+behaviour moves. It ships as a patch because the docblocks are **published
+bytes**: `tsup`'s declaration rollup carries `CronJobAdapter.runScheduled`'s
+docblock and `DbJobAdapter.schedule`'s routing docblock into `dist/index.d.ts`
+/ `dist/index.d.cts` (measured: with all comments stripped, the before/after
+declaration files are byte-identical — no exported symbol moved, no signature
+changed).
+
+`CronJobAdapter.runScheduled()` holds its cluster lock for the duration of a
+scheduled fire (acquired, then released in `finally`), not for the scheduling
+deadline. The two docblocks stated the guarantee — "only the node that
+acquires the per-job lock runs the handler" — without that window, which reads
+as exactly-once per deadline. It is exactly-once only when replica clocks
+agree to within the handler's runtime (the normal case on an NTP-synced
+deployment); a replica whose clock lags past that window finds the lock
+already released and reruns the job. `once` schedules are the sharpest case,
+since a one-shot has no later tick during which a business-level
+de-duplication marker could self-correct that away. The multi-node section of
+[Self-Hosted Deployment](/docs/deployment/self-hosting) states the same
+caveat.
+
+⛔ The mechanism is deliberately unchanged: holding the lease keyed to the
+deadline (plus takeover semantics for a leader that dies mid-fire) is a
+distributed-design item with zero measured pull and no measured
+skew-to-runtime ratio — this is bookkeeping, not closure. If a real
+duplicate-fire incident is measured on a `once` schedule, that remedy returns
+as its own card.

.changeset/system-write-sharing-materialization.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/plugin-sharing": patch
+---
+
+fix(plugin-sharing): let system writes materialize sharing rules — drop the `isSystem` skips in `bindRuleHooks` (#13533)
+
+A criteria sharing rule declares a promise: `status == "approved"` means the
+named recipients can see the record. `bindRuleHooks` did not keep that promise
+when the platform was the writer. Its `afterInsert` and `afterUpdate` hooks
+returned early on `ctx.session.isSystem`, so a system-context write that moved a
+record INTO a rule's criteria materialized no `sys_record_share` row at all.
+
+The path that made this a real outage rather than a boot-time curiosity is
+approval write-back. An approval node with `lockRecord: true` mirrors the
+decision onto the subject record under a system context — that is the only write
+that can land while the record is locked — so a manager approving a leave
+request produced exactly the skip above. A teammate who relied on the rule could
+not see the record, and nothing repaired it until somebody ran
+`POST /api/v1/sharing/rules/:id/evaluate` or restarted the server. The failure
+was invisible from a manager or admin view, which reads through the profile's
+`viewAllRecords` grant and never consults a sharing rule at all.
+
+**What changes.** A system write now materializes exactly as a user write does —
+grants on the way into a rule's criteria, revokes on the way out, per record,
+synchronously with the write. Three early returns are gone: the two on
+`afterInsert` / `afterUpdate`, and the one on the `beforeUpdate` / `beforeDelete`
+row-set stash they depended on (without that stash an `after` hook reads the row
+set as *unbounded*, which would have turned every single-row system update into
+an object-wide revoke plus an asynchronous re-grant). The INFO line that
+announced the skip — `[sharing-rule] sharing materialisation skipped for isSystem
+writes; re-evaluate rules or restart to backfill` — is retired with it, along
+with the `SYSTEM_WRITE_SKIP_NOTICE` constant, which was not exported from the
+package entry point. Operationally this means seed- and import-time system writes
+on rule-covered objects now pay per-record sharing evaluation at write time — the
+cost a user write of the same shape has always paid, with the
+`kernel:bootstrapped` backfill still reconciling behind it.
+
+**What does not change.** `afterDelete` still skips system writes, on separate
+grounds: what it skips is revocation, and `record-share-cascade.ts` delivers that
+on every sharing-capable object, stashing for system writes on its own account.
+The `kernel:bootstrapped` boot backfill still runs and is still needed — it
+reaches rows no hook saw, and it is the only pass that purges a deactivated
+rule's grants. No new option, flag or declarative switch: the fix is the removal.
+
+No published export moves; `SYSTEM_WRITE_SKIP_NOTICE` was never re-exported from
+the package entry point.

.github/workflows/validate-deps.yml

@@ -18,8 +18,11 @@ on:
       # exercised on the PR that introduces them.
       - '.github/workflows/validate-deps.yml'
   schedule:
-    # Run weekly on Monday at 03:00 UTC
-    - cron: '0 3 * * 1'
+    # Run daily at 03:00 UTC — narrows the discovery window for a new OSV
+    # advisory from up to six days (weekly) to one, so the scheduled scan
+    # is more likely to surface a red before an unrelated PR's blocking
+    # trigger collides with it (#14645).
+    - cron: '0 3 * * *'
   workflow_dispatch:
 
 jobs:

content/docs/data-modeling/field-types.mdx

@@ -652,7 +652,7 @@ These properties are available on **all** field types:
 | `description` | `string` | — | Field description / help text |
 | `type` | `FieldType` | **required** | One of the supported field types |
 | `required` | `boolean` | `false` | Whether the field is required |
-| `unique` | `boolean` | `false` | Enforce uniqueness |
+| `unique` | `boolean \| 'global' \| 'organization'` | `false` | Unique constraint **and its scope** (ADR-0120). `'organization'` = one holder per organization; `true` = that same per-organization scope (positional synonym — prefer the explicit spelling in new code); `'global'` = one holder across the whole installation; `false` = no constraint. `'tenant'`/`'org'` are rejected — the word is `'organization'`. Full rule in the `unique` doc block in [`FieldSchema`](/docs/references/data/field) |
 | `multiple` | `boolean` | `false` | Allow array of values (multi-record lookup, multi-select, multi-file). An emptied multi-value lookup reads back as `[]`, never `null` — the `multiple` doc block in [`FieldSchema`](/docs/references/data/field) |
 | `searchable` | `boolean` | `false` | Include in search index |
 | `sortable` | `boolean` | `true` | Allow sorting by this field |

content/docs/deployment/self-hosting.mdx

@@ -402,6 +402,15 @@ decrypt each other's secrets. All replicas must share the same
 `OS_SECRET_KEY`, `OS_AUTH_SECRET`, and database. See
 [Cluster](/docs/kernel/cluster).
 
+**Scheduled jobs' leader election has a window, not a deadline.** `cron` /
+`interval` / `once` schedules dedupe across replicas by holding a lock for
+the duration of each fire — the mutual-exclusion window is the handler's
+runtime, not the scheduling deadline. Exactly-once per deadline holds only
+when replica clocks agree to within that window, which an NTP-synced
+deployment gives you. A replica whose clock lags past the window finds the
+lock already released and reruns the job; `once` schedules are the sharpest
+case, since a one-shot has no later tick to self-correct on.
+
 ## First boot: create the admin
 
 How the first administrator is created depends on the deployment's