docs(engine): state the ruled readonly-on-INSERT contract at the seven non-published prose sites (#17020)

* docs(engine): state the ruled readonly-on-INSERT contract at the seven non-published prose sites

The 2026-09-03 maintainer ruling (option C, #14147) put the static `readonly`
strip inside `engine.insert` under the same `isSystem` gate as `engine.update`
and deleted the metadata-protocol ingress copy. PR #15395 fixed every site that
reached a published artefact; the 2026-09-05 E3 ruling carded the rest.

These seven prose sites still stated the superseded contract in the present
tense — that a non-system INSERT is exempt from the static strip, or that the
strip lives at the DataProtocol create ingress. Each is rewritten to the ruled
state, following the R3/R4 corrections in rest-server.ts, settings-service.ts
and crud-nodes.ts:

- objectql/src/readonly-strict-errors.ts — the module docblock's account of
  what the refusal union contains on INSERT (the `operation` TSDoc 190 lines
  below was already corrected in R4 and disagreed with it).
- service-settings settings-secret-rotation.test.ts (header + a helper) and
  sys-secret-orphan-report.test.ts (a helper) — sys_setting's INSERT is still
  outside the strip, but by the platform-object carve-out in
  staticReadonlyInsertSubject (#15719), not by #3413.
- rest/src/rest-batch-endpoint.test.ts — the create-ingress-parity comment; the
  routing it pins is unchanged, only the stated reason was superseded.
- service-automation crud-dropped-fields.test.ts — the "future insert-side
  strip" is live.
- spec/scripts/liveness/proof-registry.mts — the provenance comment on the
  readonly-static-write proof, which covers both write paths.

Comments only: no behaviour change, no test deleted, skipped or reassigned, no
exported symbol and no published payload key touched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ADLdAs2pVcH17h9tZKWMBg

* chore: add the patch changeset the readonly-INSERT prose diff was measured to need

Measured, not assumed: the five touched packages were built before and after
the edit and every dist file hashed, with `npm pack --dry-run` read for what
ships. Two released packages publish changed bytes — @objectstack/objectql
(4 sourcemaps) and @objectstack/rest (2 sourcemaps, because its bundle inlines
objectql's source and the comment moves its line numbers). Every emitted .js /
.mjs / .cjs and every .d.ts / .d.mts / .d.cts is byte-identical.

skip-changeset is for a diff that publishes nothing from any released package,
so it does not apply here.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ADLdAs2pVcH17h9tZKWMBg

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-musk

.changeset/readonly-insert-superseded-prose.md

@@ -0,0 +1,10 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/rest": patch
+---
+
+Documentation only: seven in-source prose sites that still stated the superseded readonly-on-INSERT contract as live now state the ruled one.
+
+The 2026-09-03 maintainer ruling (option C, #14147) put the static `readonly` strip inside `engine.insert` under the same `isSystem` gate as `engine.update`, and deleted the metadata-protocol create-ingress copy. Comments and test headers written before that ruling still said, in the present tense, that a non-system INSERT is exempt from the static strip, or that the strip lives at the DataProtocol create ingress. Each now states the ruled contract, and the superseded sentence is kept only as history, marked as superseded.
+
+No behaviour changes and no test was deleted, skipped or re-scoped — the diff is comments only. It is a `patch` rather than `skip-changeset` because it was measured to publish: `@objectstack/objectql`'s comment edit moves source line numbers, so `dist/{index,core}.{js,mjs}.map` change, and `@objectstack/rest` inlines that same objectql source into its bundle, so `dist/index.{js,cjs}.map` change with it. Every emitted `.js` / `.mjs` / `.cjs` and every `.d.ts` / `.d.mts` / `.d.cts` is byte-identical before and after, and all six maps ship inside the published tarballs.

packages/objectql/src/readonly-strict-errors.ts

@@ -18,13 +18,16 @@ import type { DroppedFieldsEvent } from '@objectstack/spec/data';
  * static `readonly` (#2948), a TRUE `readonlyWhen` predicate (#3042), the
  * implicitly-readonly runtime-owned types (#5503), and the `primary_key` strip
  * of a payload `id` the update dispatch ruled is not an identifier (#6437); on
- * INSERT only the runtime-owned ones, because a create is deliberately exempt
- * from the author-declared strips (#3413). One error names everything wrong
- * with the payload instead of forcing a round-trip per field. `drops`
- * keeps the per-reason breakdown (the same `DroppedFieldsEvent` shape
- * `onFieldsDropped` would have received, had the write been allowed to
- * complete), so a caller can tell a schema-level lock from a state-dependent
- * one without parsing the message.
+ * INSERT the runtime-owned ones and, since the 2026-09-03 ruling (#14147)
+ * superseded the create-side exemption #3413 had granted, static `readonly`
+ * too — judged over `staticReadonlyInsertSubject`, which leaves a
+ * `sys_`-prefixed or `managedBy` object to its own guards (#15719), while
+ * `readonlyWhen` still locks nothing on a create (a conditional lock needs a
+ * prior record). One error names everything wrong with the payload instead of
+ * forcing a round-trip per field. `drops` keeps the per-reason breakdown (the
+ * same `DroppedFieldsEvent` shape `onFieldsDropped` would have received, had
+ * the write been allowed to complete), so a caller can tell a schema-level
+ * lock from a state-dependent one without parsing the message.
  *
  * ## The message is composed from `drops`, not from the error's name (#6437)
  *

packages/rest/src/rest-batch-endpoint.test.ts

@@ -305,11 +305,17 @@ describe('POST {basePath}/batch — cross-object transactional batch', () => {
 
   // ── create ingress parity (#3835) ─────────────────────────────────────────
   //
-  // The engine's INSERT path is static-`readonly`-exempt by design (#3413), so
-  // the #3043 strip that stops a non-system caller from seeding a read-only
-  // column lives at the protocol's create ingress. This route used to call
-  // `ql.insert` directly and skip it, so `readonly` meant two different things
-  // depending on which create endpoint you used.
+  // When this was written the #3043 strip that stops a non-system caller from
+  // seeding a read-only column lived at the protocol's create ingress, because
+  // the engine's INSERT path was static-`readonly`-exempt (#3413). This route
+  // used to call `ql.insert` directly and skip that ingress, so `readonly`
+  // meant two different things depending on which create endpoint you used.
+  // Since the maintainer ruling of 2026-09-03 (option C, #14147) the strip
+  // runs inside `engine.insert` for every non-system caller and the ingress
+  // copy is deleted, so both create routes are stripped identically. The
+  // routing pinned below stands on what the ingress still owns: the #3770
+  // object-existence gate, the #7823 `internal: true` response strip and the
+  // `droppedFields` relay — one create ingress, one response contract.
 
   it('routes create ops through the protocol create ingress, not ql.insert', async () => {
     const ql = makeQl();

packages/services/service-automation/src/builtin/crud-dropped-fields.test.ts

@@ -142,9 +142,14 @@ describe('update_record surfaces silently-stripped write fields (#3407)', () =>
 });
 
 describe('create_record is wired symmetrically (#3407)', () => {
-    // Today ObjectQL's insert path strips nothing (INSERT is readonly-exempt,
-    // FLS write denial throws) — but the node listens anyway, so a future
-    // insert-side strip surfaces instead of going silent.
+    // #3407 wired this listener against an insert path that stripped nothing
+    // (INSERT was readonly-exempt; FLS write denial throws), i.e. for a signal
+    // it could not then receive. The maintainer ruling of 2026-09-03 (#14147)
+    // put the static-`readonly` strip inside `engine.insert` under an
+    // `isSystem` gate, so the signal is live: `crud-nodes.ts` relays it and
+    // `create-record-readonly-drop.test.ts` drives it end to end. The cases
+    // below feed the channel a synthetic drop, so they pin the node's relay
+    // independently of which strips the engine runs.
     it('surfaces insert-side drop events as step warnings, keeping success', async () => {
         const engine = new AutomationEngine(makeLogger());
         const { data } = fakeDataWithDrops([

packages/services/service-settings/src/settings-secret-rotation.test.ts

@@ -9,8 +9,13 @@
  * (`packages/platform-objects/src/system/sys-setting.object.ts`), and the
  * engine strips author-declared read-only columns from a **non-system**
  * caller's UPDATE payload (`stripReadonlyFields`, gated on
- * `if (!opCtx.context?.isSystem)` in `packages/objectql/src/engine.ts`). The
- * INSERT path is deliberately exempt (#3413).
+ * `if (!opCtx.context?.isSystem)` in `packages/objectql/src/engine.ts`). On
+ * THIS object the INSERT path is outside that strip — not by the 2026-07-24
+ * "INSERT exempt" row (superseded by the 2026-09-03 ruling, #14147:
+ * `engine.insert` runs the same strip for a non-system caller) but because
+ * `sys_setting` is `sys_`-prefixed and `managedBy: 'engine-owned'`, which
+ * `staticReadonlyInsertSubject` leaves to the platform object's own guards
+ * while the UPDATE path applies no such carve-out (#15719).
  *
  * `SettingsService` wrote its rows through a plain, un-elevated
  * `engine.update`, so:
@@ -186,9 +191,14 @@ function makeMemoryDriver() {
  * That single omission is the whole hazard — `sys_setting.value_enc` is
  * declared `readonly: true` and the engine strips author-declared read-only
  * columns from a NON-system caller's UPDATE (`stripReadonlyFields`, gated on
- * `context.isSystem`), while the INSERT path is exempt (#3413). It is a
- * documented extension point, so the population that reaches it is real:
- * third-party adapter authors, who have no other discovery path.
+ * `context.isSystem`), while on THIS object the INSERT path is outside that
+ * strip — not by the superseded #3413 exemption (the 2026-09-03 ruling,
+ * #14147, put the same strip inside `engine.insert` for every non-system
+ * caller) but because `sys_setting` is `sys_`-prefixed and
+ * `managedBy: 'engine-owned'`, which `staticReadonlyInsertSubject` leaves to
+ * the platform object's own guards (#15719). It is a documented extension
+ * point, so the population that reaches it is real: third-party adapter
+ * authors, who have no other discovery path.
  */
 function wrapEngineDroppingContext(engine: any): SettingsEngine {
   const real = wrapEngineAsSettingsEngine(engine);

packages/services/service-settings/src/sys-secret-orphan-report.test.ts

@@ -187,10 +187,15 @@ function makeMemoryDriver() {
  * That single omission is the whole defect — `sys_setting.value_enc` is
  * declared `readonly: true` and the engine strips author-declared read-only
  * columns from a NON-system caller's UPDATE (`stripReadonlyFields`, gated on
- * `context.isSystem`), while the INSERT path is exempt (#3413). It is also
- * exactly the breakage `SettingsEngine`'s doc comment warns an adapter author
- * about ("⛔ An adapter over `IDataEngine` MUST forward this"), so reproducing
- * the orphan mechanism and pinning that warning are the same measurement.
+ * `context.isSystem`), while on THIS object the INSERT path is outside that
+ * strip — not by the superseded #3413 exemption (the 2026-09-03 ruling,
+ * #14147, put the same strip inside `engine.insert` for every non-system
+ * caller) but because `sys_setting` is `sys_`-prefixed and
+ * `managedBy: 'engine-owned'`, which `staticReadonlyInsertSubject` leaves to
+ * the platform object's own guards (#15719). It is also exactly the breakage
+ * `SettingsEngine`'s doc comment warns an adapter author about ("⛔ An adapter
+ * over `IDataEngine` MUST forward this"), so reproducing the orphan mechanism
+ * and pinning that warning are the same measurement.
  */
 function wrapEngineDroppingContext(engine: any): SettingsEngine {
   const real = wrapEngineAsSettingsEngine(engine);

packages/spec/scripts/liveness/proof-registry.mts

@@ -153,7 +153,11 @@ export const HIGH_RISK_CLASSES: HighRiskClass[] = [
     bound: true,
     // `readonly` was renderer-only until #2948 — declared ≠ enforced is exactly
     // the false-compliance class ADR-0049 closes. The proof pins the server-side
-    // strip (forge dropped, sibling edit lands, insert exempt) over real HTTP.
+    // strip over real HTTP on BOTH write paths — a forged create is dropped, a
+    // forged PATCH is dropped, the sibling edit lands. Since the maintainer
+    // ruling of 2026-09-03 (option C, #14147) `engine.insert` runs the same
+    // `stripReadonlyFields` under the same `isSystem` gate as UPDATE, and the
+    // #3043 protocol-ingress copy is deleted.
     ledgerBindings: [{ type: 'field', path: 'readonly' }],
   },
   {