Merge remote-tracking branch 'origin/main' into claude/issue-14917-driver-mongodb-test-layer-typecheck

Author: claude

.changeset/reference-page-block-tag-payload-render.md

@@ -0,0 +1,34 @@
+---
+"@objectstack/spec": patch
+---
+
+Reference pages no longer print `@example` and `@category` tag lines as literal text.
+
+A module docblock is JSDoc, so its header carries block tags, and the reference-docs
+renderer emitted a tag written on a prose line verbatim — 18 such lines reached 14
+customer-facing pages, as `@example Basic field mapping` above a code fence and
+`@category Security` at the foot of four `system/` pages. `#13796` removed `@module`
+from the page and left these two open, because a blanket `^@\w+` line filter would
+have taken reader prose off the page and orphaned the fences below it.
+
+The verdict is per tag, and the axis is the payload rather than the spelling:
+
+- **`@example CAPTION` is REWRITTEN** into that caption, in bold, above the block it
+  captions — the shape `@see` already had (`See also: …`). 12 lines across 10 pages.
+  Bold rather than a heading because heading renumbering has already run by then, so
+  an emitted heading would carry a level chosen blind of the page, add entries to the
+  pages' tables of contents, and put a caption in reach of `check:docs-single-h1`.
+- **A bare `@example` is DROPPED.** With no payload it is the `@module` case exactly,
+  and the fence beneath it is visibly an example without a line announcing one. 2
+  lines (`studio/plugin`, `studio/object-designer`), both sitting against the
+  `check:skill-examples` opt-in marker that was already dropped there.
+- **`@category VALUE` is DROPPED.** 4 lines, all reading `Security`, on four pages that
+  already sit under a `system/` section saying as much — and nothing in the repo reads
+  the tag: no typedoc or api-extractor (neither is used here), no search index, no
+  gate. Routing it into page frontmatter instead would publish a field with no
+  consumer. The tag stays in the source, where it is a legitimate JSDoc tag; only the
+  rendered page drops it.
+
+No schema behavior changes. The pins assert on the rendered fragment rather than on the
+emitted `.mdx`, because `check:docs` compares the artifact against the source and
+reproduced all 18 tag lines faithfully.

.changeset/sandbox-writeback-entry-snapshot-normalised.md

@@ -0,0 +1,30 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime): a sandboxed hook body no longer launders an untouched `readonly` field onto the row
+
+A `beforeUpdate`/`beforeInsert` body running in the sandbox made the engine believe it had
+written payload keys it never named, and a `readonly` field the caller supplied then survived
+the readonly strip and landed. Measured end to end: with `locked_at` declared
+`{ type: 'datetime', readonly: true }` and seeded to `2020-01-01`, a caller sending
+`locked_at: new Date('2099-12-31…')` alongside a body whose whole source is
+`ctx.input.touched_by = 'hook'` stored the caller's 2099 value — while the same object's
+readonly `text` field was correctly stripped in the same request.
+
+The cause was a comparison of unlike things. The write-back decides whether a body wrote
+*through* an object-valued key by comparing the host payload value against the VM's exit dump,
+and the dump has been through `JSON.stringify`/`JSON.parse` while the host value has not. A
+`Date` therefore never compared equal to its own ISO projection, took the documented
+"cannot prove equal ⇒ carry it back" path, and was re-asserted onto the proxy that records
+which keys a hook wrote. The class was every object-valued value a JSON round-trip cannot
+prove equal — an object carrying an `undefined` member included, a `Date` being only its most
+reachable member.
+
+The entry value is now normalised through the same round-trip the VM saw before it is
+compared. The same change ends a fidelity loss on non-readonly fields: an untouched key is no
+longer carried at all, so a host `Date` is no longer replaced by an ISO string on its way to
+the driver.
+
+Fail-open behaviour is unchanged for values the round-trip genuinely cannot evaluate: a cyclic
+or bigint-bearing payload value is still reported as changed and still carried, per key.

content/docs/references/api/automation-api.mdx

@@ -12,7 +12,7 @@ triggering executions, and querying execution history.
 
 Base path: /api/automation
 
-@example Endpoints
+**Endpoints**
 GET    /api/automation                         — List flows
 GET    /api/automation/:name                   — Get flow
 POST   /api/automation                         — Create flow

content/docs/references/api/documentation.mdx

@@ -22,7 +22,7 @@ Architecture Alignment:
 - Postman: API testing collections
 - Redoc: Documentation rendering
 
-@example Documentation Config
+**Documentation Config**
 ```typescript
 const docConfig: ApiDocumentationConfig = {
   enabled: true,

content/docs/references/api/odata.mdx

@@ -42,7 +42,7 @@ See also: https://www.odata.org/documentation/
 
 See also: https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html
 
-@example OData Query
+**OData Query**
 ```
 GET /api/odata/customers?
   $select=name,email&
@@ -54,7 +54,7 @@ GET /api/odata/customers?
   $count=true
 ```
 
-@example Programmatic Use
+**Programmatic Use**
 ```typescript
 const query: ODataQuery = {
   select: ['name', 'email'],

content/docs/references/api/package-api.mdx

@@ -11,7 +11,7 @@ REST API endpoint schemas for package lifecycle management.
 
 Base path: /api/v1/packages
 
-@example Endpoints
+**Endpoints**
 POST   /api/v1/packages/install              — Install a package
 POST   /api/v1/packages/upgrade              — Upgrade a package
 POST   /api/v1/packages/resolve-dependencies — Resolve dependencies

content/docs/references/api/plugin-rest-api.mdx

@@ -28,7 +28,7 @@ Architecture Alignment:
 - Microsoft Dynamics: Web API with entity operations
 - Strapi: Auto-generated REST endpoints from schemas
 
-@example Serving routes from a plugin (imperative `http.server` mount)
+**Serving routes from a plugin (imperative `http.server` mount)**
 ```typescript
 // Routes are mounted in CODE — resolve the `http.server` service from the
 // plugin context and register handlers on `kernel:ready` (the service is

content/docs/references/automation/time-relative-trigger.mdx

@@ -30,7 +30,7 @@ automation context (so `{record.<field>}` interpolation and the start-node
 `condition` gate work exactly as they do for record-change flows). The
 descriptor is carried on the flow's start node as `config.timeRelative`.
 
-@example T-minus renewal reminders (fires on the day a contract is 60/30/7 days out)
+**T-minus renewal reminders (fires on the day a contract is 60/30/7 days out)**
 ```ts
 // flow start node
 config: {
@@ -45,14 +45,14 @@ config: {
 }
 ```
 
-@example "Expiring soon" range (fires every day a document is within 30 days of expiry)
+**"Expiring soon" range (fires every day a document is within 30 days of expiry)**
 ```ts
 config: {
   timeRelative: { object: 'hr_document', dateField: 'expires_on', withinDays: 30 },
 }
 ```
 
-@example Overdue sweep (fires for POs up to 14 days past due)
+**Overdue sweep (fires for POs up to 14 days past due)**
 ```ts
 config: {
   timeRelative: { object: 'purchase_order', dateField: 'due_date', withinDays: -14, filter: { status: 'open' } },

content/docs/references/shared/mapping.mdx

@@ -18,15 +18,15 @@ ObjectStack for data synchronization.
   this base too, until the whole external-lookup family was retired in
   #8075 — ADR-0049, zero consumers.)
 
-@example Basic field mapping
+**Basic field mapping**
 ```typescript
 const mapping: FieldMapping = {
   source: 'external_user_id',
   target: 'user_id',
 };
 ```
 
-@example With a fallback for missing source values
+**With a fallback for missing source values**
 ```typescript
 const mapping: FieldMapping = {
   source: 'user_name',

content/docs/references/studio/object-designer.mdx

@@ -38,7 +38,6 @@ The Object Designer is composed of four interconnected panels:
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-@example
 ```typescript
 import {
   ObjectDesignerConfigSchema,