@uniweb/api 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "The client for a Uniweb site's own backend — session, records, entities — imported by a foundation the way it imports @uniweb/kit.",
   "type": "module",
   "exports": {
@@ -34,7 +34,7 @@
     "node": ">=20.19"
   },
   "dependencies": {
-    "@uniweb/core": "^0.27.0"
+    "@uniweb/core": "^0.29.0"
   },
   "peerDependencies": {
     "react": "^19.0.0"

package/src/mock/index.js

@@ -42,7 +42,12 @@ import { DEFAULT_SEED } from './seed.js'
  *        demo whose subject is the signed-in view. Development-only by construction, since
  *        this whole module is; throws if the username is not seeded.
  * @param {string} [options.prefix] - the path the API is mounted under (default `/api`)
- * @returns {{ fetch: (request: Request) => Promise<Response>, store: MockStore }}
+ * Supply `seed.schemas[model].sections` (the framework's LOWERED sections map) and
+ * item writes are shape-checked: a `many:` section is ENFORCED, everything else is
+ * recorded on `.diagnostics` and allowed — see `./schema-shape.js` for why that
+ * asymmetry is deliberate rather than lenient.
+ *
+ * @returns {{ fetch: (request: Request) => Promise<Response>, store: MockStore, diagnostics: object[] }}
  */
 export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/api', signedInAs = null } = {}) {
   const store = new MockStore(seed, { signedInAs })
@@ -181,6 +186,16 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/api', signed
 
   return {
     store,
+    /**
+     * Writes the mock shape-checked but did not refuse.
+     *
+     * ⛔ Each entry is a write whose storage mapping is an OPEN QUESTION
+     * (`./schema-shape.js`), not one that broke a rule and was let through. Empty
+     * is the good state; a long list is a map of what we are still guessing about.
+     */
+    get diagnostics() {
+      return store.diagnostics
+    },
     async fetch(request) {
       try {
         return await route(request)
@@ -195,3 +210,4 @@ export function createMockBackend({ seed = DEFAULT_SEED, prefix = '/api', signed
 
 export { MockStore } from './store.js'
 export { DEFAULT_SEED } from './seed.js'
+export { STORAGE, UNRESOLVED_REASON, ENFORCEMENT, OUTCOME } from './schema-shape.js'

package/src/mock/schema-shape.js

@@ -0,0 +1,374 @@
+/**
+ * Field-shape checking for writes, and an HONEST NAME for what we cannot check yet.
+ *
+ * ⭐ **Why this exists.** Until now the mock enforced exactly two things —
+ * `creatable_by` and `append_only` — and performed no field-shape validation at
+ * all. A demo could therefore write `{ minutes: "twelve" }` into a field the
+ * schema calls an int and find out at integration. This module closes that for
+ * the one storage shape we have evidence about, and refuses to guess about the
+ * rest.
+ *
+ * ## The evidence boundary — this is the whole design
+ *
+ * | shape | what we know | what we do |
+ * |---|---|---|
+ * | a `many:` (multi) section | **MEASURED** — stored as entity items | **ENFORCE** field shapes |
+ * | a single/`brief` section | ⛔ **OPEN** — see below | **DIAGNOSE**, never refuse |
+ * | a section the schema does not declare | ⛔ **OPEN** — same question | **DIAGNOSE**, never refuse |
+ * | the create-time entity `data` payload | ⛔ **OPEN** — same question | **DIAGNOSE**, never refuse |
+ *
+ * ⛔ **The open question (one question, three faces).** A schema written with flat
+ * `fields:` is lowered to exactly one `kind: 'single'`, `brief: true` section named
+ * after the model — MEASURED in `@uniweb/build@0.44.4`
+ * `src/uwx/data-schema.js::lowerFieldsForm`, which also notes "the registry's root
+ * is always `sections:`". Separately, this API's entity routes are
+ * list / read / readBatch / create / items / remove / removeBatch: entity `data` is
+ * supplied at creation and there is no route to update it, while items are mutable.
+ *
+ * So: **what is the intended backend representation for the fields of a
+ * single/brief section once the entity exists** — mutable entity data, an item, or
+ * another update mechanism? Nobody has answered that yet. It is why a real
+ * consumer (the Courses solution) keeps editable lesson fields in an item and
+ * overlays course metadata with a mutable item over create-time data.
+ *
+ * ⛔ **Do NOT read "diagnose" as a permanent mock semantic.** It is not a policy
+ * that writes of unknown shape are allowed; it is the absence of an answer, named.
+ * That is why the state is called `UNRESOLVED_STORAGE_MAPPING` rather than
+ * "warn" or "allow": when the question is answered, the fix is to change this
+ * model's entry in `ENFORCEMENT` (and, if the answer says so, teach
+ * `classifySection` the new mapping) — not to redesign the validator or hunt for
+ * the places that quietly let writes through.
+ */
+
+/** Where a written section lives, and therefore what we are entitled to do about it. */
+export const STORAGE = {
+  /**
+   * A section the schema declares — `single` or `multi` alike.
+   *
+   * ⭐ **RULED** *(Diego, 2026-09-11)*: sections ARE the storage model and hold
+   * items ("section => abstract, item => concrete"); a `single` section simply holds
+   * one. `brief: true` is an optional designation about what a card needs, **not** a
+   * storage class. So a declared section's records are checkable whatever its kind —
+   * which is why `single` no longer lives in the unresolved branch.
+   */
+  ITEMS: 'items',
+  /**
+   * ⛔ **Known divergence, on an explicit list — never a catch-all.**
+   *
+   * A `(model, section)` pair the site has declared as `migration_debt`: storage we
+   * know does not match its declaration, kept working while the thing that forced it
+   * is unwound. Two shapes qualify, and both are OUR debt, not the framework's:
+   *   • a section the schema does not declare at all (`@/course` `meta`), and
+   *   • a declared section whose records diverge (`@/quiz-key` `answers` holds one
+   *     record carrying a map, where the schema declares many).
+   *
+   * Both exist because `@uniweb/api` had no route to update entity data — an
+   * omission, per Diego, not a backend rule. They retire with that route.
+   */
+  MIGRATION_DEBT: 'migration-debt',
+  /**
+   * A section that is neither declared nor listed as debt. **A violation** — a typo
+   * or an accidental section, which must not be able to hide in the debt bucket.
+   */
+  UNDECLARED: 'undeclared-section',
+  /**
+   * ⛔ STILL OPEN. The create-time `data` payload: the one shape whose wire contract
+   * is genuinely unknown, pending the entity-update route.
+   */
+  UNRESOLVED: 'unresolved-storage-mapping',
+}
+
+/** Why a write was tolerated rather than judged. Reported; never changes what happens. */
+export const UNRESOLVED_REASON = {
+  /** On the site's `migration_debt` list: the schema declares no such section. */
+  UNDECLARED_SECTION: 'undeclared-section',
+  /** On the list: declared, but the records stored there do not match the declaration. */
+  DIVERGENT_SECTION: 'divergent-section',
+  /** The `data` supplied at creation. Awaiting the entity-update wire contract. */
+  ENTITY_DATA_PAYLOAD: 'entity-data-payload',
+}
+
+/**
+ * What to DO about each storage classification.
+ *
+ * ⭐ **This table is the resolution point.** Answering the open question means
+ * changing `UNRESOLVED` here (to `'enforce'`, or to whatever the answer implies),
+ * and nothing else in this file's callers moves.
+ */
+export const ENFORCEMENT = {
+  [STORAGE.ITEMS]: 'enforce',
+  [STORAGE.UNDECLARED]: 'enforce',
+  [STORAGE.MIGRATION_DEBT]: 'diagnose',
+  [STORAGE.UNRESOLVED]: 'diagnose',
+}
+
+/** Outcomes a check can produce. `VIOLATES` is the only one a caller may refuse on. */
+export const OUTCOME = {
+  CONFORMS: 'conforms',
+  VIOLATES: 'violates',
+  /** Shape problems found, but under a classification we do not enforce. */
+  DIAGNOSED: 'diagnosed',
+  /** No declaration to check against — the model is not described to the mock. */
+  UNCHECKED: 'unchecked',
+}
+
+/**
+ * ⚠️ **TWO LOWERED SPELLINGS, and this module accepts both.**
+ *
+ * The framework lowers a schema twice, and the two forms disagree on how they say
+ * "many" — MEASURED 2026-09-11 against `@uniweb/schemas@0.2.13` and
+ * `@uniweb/build@0.44.4`:
+ *
+ * | | a repeating section | a list field |
+ * |---|---|---|
+ * | `validateAndNormalizeSchema` | `kind: 'multi'` | `{ type: 'array', items: {…} }` |
+ * | `toDataSchemaDeclaration` (the **registry** form, what a backend is actually sent) | `multiple: true` | `{ type: 'string', multiple: true }` |
+ *
+ * ⛔ Reading only the first spelling is not a cosmetic bug: every multi section in a
+ * REGISTRY declaration would fall through to "single", so the mock would classify
+ * all of them as unresolved and enforce **nothing**, silently. Caught by feeding it
+ * real declarations rather than only hand-written fixtures.
+ */
+function isMultiSection(section) {
+  return section?.multiple === true || section?.kind === 'multi'
+}
+
+/** The element shape of a list field, in either spelling, or null if it is not a list. */
+function listElement(field) {
+  if (field?.multiple === true) return { type: field.type, fields: field.fields }
+  if (field?.type === 'array') return { type: field.items?.type, fields: field.items?.fields }
+  return null
+}
+
+/**
+ * Is this section a multi section of the model's declaration?
+ *
+ * `decl.sections` is the lowered sections map (`{ [name]: { kind, brief, fields } }`)
+ * as produced by the framework's own normalizer — the mock never parses schema
+ * source, so there is no second copy of the authoring format here to drift.
+ */
+export function classifySection(decl, section) {
+  const sections = decl?.sections
+  if (!sections || typeof sections !== 'object') return null
+  const found = sections[section]
+
+  // ⭐ The debt list is consulted FIRST and is an exact `(model, section)` match, so
+  // it can excuse a declared section whose records diverge as well as an undeclared
+  // one — but only ever the pairs the site named. Anything else falls through.
+  const isDebt = (decl.migration_debt || []).includes(section)
+  if (isDebt) {
+    return {
+      storage: STORAGE.MIGRATION_DEBT,
+      reason: found ? UNRESOLVED_REASON.DIVERGENT_SECTION : UNRESOLVED_REASON.UNDECLARED_SECTION,
+      section: found || null,
+    }
+  }
+
+  // ⛔ Not declared and not owned as debt: a typo or an accidental section. Refused,
+  // so it cannot disappear into the debt bucket — the reason the list is explicit.
+  if (!found) return { storage: STORAGE.UNDECLARED, section: null }
+
+  // Declared — single or multi alike. Sections hold items; `single` holds one.
+  return { storage: STORAGE.ITEMS, section: found }
+}
+
+// ── Field shapes ──────────────────────────────────────────────────────────────
+
+/**
+ * Does a value satisfy a lowered type?
+ *
+ * Returns `null` for a type this does not know. ⭐ Unknown is TOLERATED, not
+ * failed: the type vocabulary belongs to `@uniweb/schemas` and grows there, and a
+ * mock that rejected a type it had not heard of would fail writes the real store
+ * accepts — the expensive direction of a fidelity error.
+ */
+function satisfiesType(type, value) {
+  switch (type) {
+    case 'string':
+    case 'text':
+    case 'html':
+    case 'markdown':
+    case 'email':
+    case 'url':
+    case 'image':
+    case 'file':
+    case 'ref':
+      return typeof value === 'string'
+    case 'int':
+    case 'integer':
+      return typeof value === 'number' && Number.isInteger(value)
+    case 'number':
+    case 'decimal':
+      return typeof value === 'number' && Number.isFinite(value)
+    case 'bool':
+    case 'boolean':
+      return typeof value === 'boolean'
+    case 'date':
+    case 'datetime':
+      return typeof value === 'string' || value instanceof Date
+    case 'array':
+      return Array.isArray(value)
+    case 'object':
+    case 'json':
+    case 'group':
+      return typeof value === 'object' && value !== null
+    default:
+      return null
+  }
+}
+
+/**
+ * Check a record against a lowered `fields` map. Returns a list of violations.
+ *
+ * ⛔ **A key the schema does not declare is NOT a violation.** We have no evidence
+ * that the real store rejects extras, and inventing that rule here would refuse
+ * writes production accepts. Unknown keys are reported by the caller as
+ * diagnostics instead.
+ */
+export function checkFields(fields, data, path = '') {
+  const problems = []
+  if (!fields || typeof fields !== 'object') return problems
+  const record = data && typeof data === 'object' ? data : {}
+
+  for (const [name, field] of Object.entries(fields)) {
+    const at = path ? `${path}.${name}` : name
+    const value = record[name]
+    const missing = value === undefined || value === null
+
+    if (field.required && missing) {
+      problems.push({ field: at, rule: 'required', detail: `'${at}' is required` })
+      continue
+    }
+    if (missing) continue
+
+    // A list, in either spelling. The VALUE must be an array; each entry is then
+    // checked against the element shape, indexed the way `uniweb validate` names it
+    // (`outcomes[1]`), so one vocabulary covers both lanes.
+    const element = listElement(field)
+    if (element) {
+      if (!Array.isArray(value)) {
+        problems.push({ field: at, rule: 'type', detail: `'${at}' expects a list of ${element.type}` })
+        continue
+      }
+      value.forEach((entry, i) => {
+        const entryAt = `${at}[${i}]`
+        if (satisfiesType(element.type, entry) === false) {
+          problems.push({
+            field: entryAt,
+            rule: 'type',
+            detail: `'${entryAt}' expects ${element.type}, got ${Array.isArray(entry) ? 'array' : typeof entry}`,
+          })
+          return
+        }
+        if (element.fields) problems.push(...checkFields(element.fields, entry, entryAt))
+      })
+      continue
+    }
+
+    if (satisfiesType(field.type, value) === false) {
+      problems.push({
+        field: at,
+        rule: 'type',
+        detail: `'${at}' expects ${field.type}, got ${Array.isArray(value) ? 'array' : typeof value}`,
+      })
+      continue
+    }
+
+    if (Array.isArray(field.enum) && field.enum.length && !field.enum.includes(value)) {
+      problems.push({ field: at, rule: 'enum', detail: `'${at}' must be one of ${field.enum.join(', ')}` })
+      continue
+    }
+
+    if (field.fields) problems.push(...checkFields(field.fields, value, at))
+  }
+  return problems
+}
+
+/** Keys present in the write that the section does not declare. Diagnostic only — see checkFields. */
+function undeclaredKeys(fields, data) {
+  if (!fields || !data || typeof data !== 'object') return []
+  return Object.keys(data).filter((k) => !(k in fields))
+}
+
+// ── The two entry points the store calls ──────────────────────────────────────
+
+/**
+ * Check one item write (create or update) against the model's declaration.
+ *
+ * @returns {{outcome: string, storage?: string, reason?: string, problems: object[], undeclared: string[]}}
+ *   `outcome: 'violates'` is the ONLY result a caller may refuse on.
+ */
+export function checkItemWrite({ decl, section, data }) {
+  if (!decl?.sections) return { outcome: OUTCOME.UNCHECKED, problems: [], undeclared: [] }
+
+  const where = classifySection(decl, section)
+  if (!where) return { outcome: OUTCOME.UNCHECKED, problems: [], undeclared: [] }
+
+  // An undeclared section has no field set to conform to, so the violation is the
+  // section itself — stated here rather than falling out of an empty field check.
+  if (where.storage === STORAGE.UNDECLARED) {
+    return {
+      outcome: OUTCOME.VIOLATES,
+      storage: where.storage,
+      problems: [
+        {
+          field: section,
+          rule: 'undeclared-section',
+          detail: `'${section}' is not a section of this model`,
+        },
+      ],
+      undeclared: [],
+    }
+  }
+
+  const fields = where.section?.fields
+  const problems = fields ? checkFields(fields, data) : []
+  const undeclared = fields ? undeclaredKeys(fields, data) : []
+  const enforcement = ENFORCEMENT[where.storage]
+
+  if (enforcement === 'enforce') {
+    return {
+      outcome: problems.length ? OUTCOME.VIOLATES : OUTCOME.CONFORMS,
+      storage: where.storage,
+      problems,
+      undeclared,
+    }
+  }
+  // ⭐ ALWAYS diagnosed, even when the data looks fine and even when there were no
+  // fields to check it against. The finding is not "these values are wrong" — it is
+  // "this write's storage mapping is unanswered". A clean-looking write under an
+  // unresolved classification is still riding on the open question, and the whole
+  // value of the list is that it maps exactly which writes those are.
+  return {
+    outcome: OUTCOME.DIAGNOSED,
+    storage: where.storage,
+    reason: where.reason,
+    problems,
+    undeclared,
+  }
+}
+
+/**
+ * Check the `data` supplied at entity creation.
+ *
+ * ⛔ **Always the unresolved branch, by construction.** Whether this payload is the
+ * brief section's fields (and therefore checkable against them) is precisely the
+ * open question. We report what we see and refuse nothing.
+ */
+export function checkEntityDataWrite({ decl, data }) {
+  if (!decl?.sections) return { outcome: OUTCOME.UNCHECKED, problems: [], undeclared: [] }
+
+  const briefName = Object.keys(decl.sections).find((n) => decl.sections[n]?.brief)
+  const brief = briefName ? decl.sections[briefName] : null
+  const problems = brief?.fields ? checkFields(brief.fields, data) : []
+  const undeclared = brief?.fields ? undeclaredKeys(brief.fields, data) : []
+
+  // Always diagnosed, for the same reason as `checkItemWrite` — see there.
+  return {
+    outcome: OUTCOME.DIAGNOSED,
+    storage: STORAGE.UNRESOLVED,
+    reason: UNRESOLVED_REASON.ENTITY_DATA_PAYLOAD,
+    problems,
+    undeclared,
+  }
+}

package/src/mock/store.js

@@ -1,4 +1,5 @@
 import { FIELD, OP } from '../wire.js'
+import { checkItemWrite, checkEntityDataWrite, OUTCOME, STORAGE } from './schema-shape.js'
 
 /**
  * The mock's state — accounts, one session, entities and their items.
@@ -31,7 +32,14 @@ export class MockStore {
   /**
    * @param {object} seed
    * @param {object[]} [seed.accounts] - `{ username, password, handle, roles?, units? }`
-   * @param {object} [seed.schemas] - `{ '@/session': { creatable_by?, append_only? } }`
+   * @param {object} [seed.schemas] - `{ '@/session': { creatable_by?, append_only?, sections?, migration_debt? } }`.
+   *   `migration_debt` is a list of section names this site KNOWS diverge from the
+   *   declaration and is unwinding — tolerated and recorded, never silently passed.
+   *   Anything undeclared and NOT on that list is refused, so a typo cannot hide in it.
+   *   `sections` is the LOWERED sections map (`{ [name]: { kind, brief, fields } }`) as the
+   *   framework's own normalizer produces it — supply it and writes are shape-checked
+   *   (see `./schema-shape.js`). The mock never parses schema source itself, so there is
+   *   no second copy of the authoring format here to drift from the real one.
    * @param {object[]} [seed.entities] - `{ uuid?, model, data?, items? }`
    * @param {object} [options]
    * @param {string} [options.signedInAs] - start with this account already signed in.
@@ -46,9 +54,18 @@ export class MockStore {
       units: a.units || [],
       ...a,
     }))
-    // What the mock knows about a Model: only the two things it must ENFORCE.
-    // Everything else about a schema is the site's business, not the server's.
+    // What the mock knows about a Model: the two permission rules it must ENFORCE,
+    // and — when the seed supplies `sections` — the field shapes to check writes
+    // against. Everything else about a schema is the site's business.
     this.schemas = seed.schemas || {}
+    /**
+     * Shape findings the mock saw but did not refuse.
+     *
+     * ⛔ Every entry here is a write under `STORAGE.UNRESOLVED` — the open storage
+     * question in `./schema-shape.js`, not a lenient policy. Read it to see exactly
+     * which writes are riding on an unanswered question; `mock.diagnostics` exposes it.
+     */
+    this.diagnostics = []
     this.entities = new Map()
     for (const e of seed.entities || []) this.seedEntity(e)
     /** The one session. A mock serves one developer, so one is the honest number. */
@@ -168,6 +185,42 @@ export class MockStore {
     return false
   }
 
+  /**
+   * Record a shape finding the mock chose not to refuse.
+   *
+   * ⛔ Called ONLY for `STORAGE.UNRESOLVED` writes. A finding here is "we could not
+   * judge this because the storage mapping is an open question", never "this was
+   * wrong but allowed" — see `./schema-shape.js` for the question and for the one
+   * table that resolves it.
+   */
+  diagnose(model, where, result) {
+    // ⭐ Deduped by (model, op, section, reason) with a count, so the list stays a
+    // MAP of what is unresolved rather than a log of every keystroke. An editor
+    // saving a lesson every few seconds would otherwise bury the distinct findings
+    // under thousands of identical rows, and the distinct set is the whole point.
+    const key = `${model}|${where.op}|${where.section ?? ''}|${result.reason}`
+    // `storage` travels with the finding: migration debt and a still-open mapping
+    // read the same in a list otherwise, and they have different futures.
+    const seen = this.diagnostics.find((d) => d.key === key)
+    if (seen) {
+      seen.count += 1
+      seen.lastAt = now()
+      return
+    }
+    this.diagnostics.push({
+      key,
+      model,
+      ...where,
+      storage: result.storage,
+      reason: result.reason,
+      problems: result.problems,
+      undeclared: result.undeclared,
+      count: 1,
+      firstAt: now(),
+      lastAt: now(),
+    })
+  }
+
   /** Is this section insert-only? Existing items may not be edited or removed. */
   isAppendOnly(model, section) {
     const decl = this.schemas[model]?.append_only
@@ -207,6 +260,10 @@ export class MockStore {
   // ── Writes ──────────────────────────────────────────────────────────────────
 
   create(model, data) {
+    // ⛔ Never refused. Whether this payload is the brief section's fields — and so
+    // whether it is checkable against them at all — IS the open question.
+    const check = checkEntityDataWrite({ decl: this.schemas[model], data })
+    if (check.outcome === OUTCOME.DIAGNOSED) this.diagnose(model, { op: 'create-entity' }, check)
     const entity = this.seedEntity({ model, data, owner: this.account?.uuid ?? null })
     return this.hydrate(entity)
   }
@@ -215,6 +272,41 @@ export class MockStore {
     return this.entities.delete(uuid)
   }
 
+  /**
+   * Shape-check an item write. Returns a refusal to hand straight back, or `null`.
+   *
+   * ⭐ **Refuses a declared section whose data does not fit, and an undeclared
+   * section that nobody owns.** It tolerates exactly two things: a `(model, section)`
+   * the site listed as `migration_debt`, and the create-time `data` payload — the
+   * one shape whose wire contract is still unsettled. See `./schema-shape.js`.
+   *
+   * The debt list is an explicit allowlist rather than a mode precisely so a typo
+   * cannot hide in it: `moduels` is a 422, `modules` is recorded and allowed.
+   */
+  shapeGuard(model, section, data, itemId) {
+    const decl = this.schemas[model]
+    if (!decl?.sections) return null
+    const check = checkItemWrite({ decl, section, data })
+
+    if (check.outcome === OUTCOME.VIOLATES) {
+      const first = check.problems[0]
+      return {
+        ok: false,
+        problem: {
+          status: 422,
+          title: 'SchemaViolation',
+          detail: `section '${section}' of ${model}: ${first.detail}`,
+          violations: check.problems,
+          ...(itemId != null ? { [FIELD.item]: itemId } : {}),
+        },
+      }
+    }
+    if (check.outcome === OUTCOME.DIAGNOSED) {
+      this.diagnose(model, { op: itemId == null ? 'create-item' : 'update-item', section }, check)
+    }
+    return null
+  }
+
   /**
    * Apply one op. Returns `{ ok, result }` or `{ ok: false, problem }` — the caller
    * turns a problem into the response, so a batch can stop at the first one and
@@ -252,11 +344,15 @@ export class MockStore {
       if (!op[FIELD.section]) {
         return { ok: false, problem: { status: 400, title: 'Validation', detail: 'create needs a section' } }
       }
+      const refusal = this.shapeGuard(entity.model, op[FIELD.section], op.data, null)
+      if (refusal) return refusal
       const made = this.makeItem({ section: op[FIELD.section], data: op.data, parent: op[FIELD.parent] ?? null })
       this.place(entity, made, op.position)
       return { ok: true, result: { [FIELD.item]: made[FIELD.item], [FIELD.token]: made[FIELD.token] } }
     }
     if (kind === OP.update) {
+      const refusal = this.shapeGuard(entity.model, item.section, op.data, itemId)
+      if (refusal) return refusal
       // Whole-data replace, like the real write: round-trip what you do not edit.
       item.data = op.data ?? {}
       item[FIELD.token] = stamp()