@uniweb/api 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "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.28.0"
+    "@uniweb/core": "^0.29.4"
   },
   "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()

package/src/wire.js

@@ -37,6 +37,55 @@
  * note to MEASURED and delete its entry — the test on that array makes the change
  * deliberate and visible rather than a quiet edit.
  *
+ * ## ⭐ THE ENTITY CONTENT MODEL — **MEASURED 2026-09-17**, and it corrects this package
+ *
+ * Backend read its own source and answered three questions we put to it. The answer
+ * to the third replaced a premise this package was built on, so it is recorded here
+ * first, before any route or field:
+ *
+ * ⛔ **THERE IS NO ENTITY-LEVEL DATA. Entity content is ALWAYS items.**
+ *
+ * An entity stores identity, ownership, flags, timestamps, and a `brief` /
+ * `sort_date` **the server maintains itself**. There is no separate data record, and
+ * therefore no route that updates one. Everything an author writes is an item in a
+ * section.
+ *
+ *   - **A `single` section — `brief: true` included — holds an ORDINARY ITEM**, with
+ *     its own `item_id`, updated through the same item route as any other. It takes
+ *     exactly ONE item: a second `create` into it is refused, so the shape is
+ *     create-once-then-update.
+ *   - **Never send `brief`.** The server rebuilds `brief` and `sort_date` after a
+ *     write to the brief section. It is output, not input.
+ *   - ⚠️ **Two spellings for one flag:** `brief: true` is how a model *file* is
+ *     written; a schema *read* returns **`is_brief`**.
+ *   - **Creating with content puts items under `items`, addressed BY NAME:**
+ *     `POST /entities?model=…` · `{ items: [ { section: 'profile', data: {…} } ] }`.
+ *     Entity and items commit in one transaction. A nested section uses a
+ *     parent/child path.
+ *   - **After creation, item ops address a section by NUMERIC `section_id`** — not by
+ *     name (see `FIELD.section`).
+ *   - Site content, folder and deployment entities answer **409** on the item route;
+ *     they are written through `/api/sites/…` and `/api/folders/…`. That is the same
+ *     boundary the RULED lane below draws, enforced from the other side.
+ *   - A batch runs in one transaction, but **an op may not reference an item created
+ *     earlier in the same batch.**
+ *
+ * ⛔ **WHAT THIS PACKAGE GETS WRONG TODAY — do not read the code as the contract.**
+ * `createEntity({ schema, data })` sends content as a **top-level `data` key**, which
+ * the create route does not accept. The create body **does not reject unknown keys**,
+ * so that payload is *silently dropped*: **201, and an empty entity, with no error.**
+ * Our own mock accepts the same shape, so the fiction is symmetrical and nothing in
+ * this repo currently fails because of it. Correcting the client is a separate change
+ * (it touches behaviour); this module's job is to make sure the contract is written
+ * down before that happens.
+ *
+ * ⚠️ **Provenance of the above: MEASURED BY BACKEND, reading backend's own source —
+ * not observed on the wire by us, and the ignored-`data` behaviour was explicitly
+ * described as read-not-tested.** That is stronger than anything else we have on this
+ * lane and weaker than a response we have held in our hands. It earns MEASURED under
+ * the table above ("or in backend's own source"); the untested corner is flagged
+ * where it matters rather than promoted.
+ *
  * @module @uniweb/api/wire
  */
 
@@ -122,11 +171,16 @@ export const PARAM = {
  * mismatch is `409` with `current_updated_at`; a gone item is `404`; an absent
  * token is last-writer-wins, guarded same-transaction.
  *
- * ⛔ **`move` is ASSUMED.** It is in scope as a product requirement — an operator
- * arranging authored content by hand, where order is a stored fact and not a sort
- * key — but it was read off the **site** lane, and this lane's own documentation
- * names only `update` and `delete` as token-carrying. Whether `move` exists here at
- * all is unconfirmed.
+ * ✅ **`move` is MEASURED (2026-09-17).** It exists on this lane, carries a
+ * precondition, and takes `{ item_id, parent_item_id, position, if_unmodified_since }`.
+ * **Position is decided server-side** — `"first"`, `"last"` or `{ after: <item_id> }` —
+ * and the client never computes an order number. Both assumptions that stood here are
+ * retired. *(It had been read off the site lane, whose documentation names only
+ * `update` and `delete` as token-carrying; the doubt was reasonable and wrong.)*
+ *
+ * ⚠️ **Batch caveat, MEASURED:** an array of ops runs in ONE transaction — all commit
+ * or none — but **an op may not reference an item created earlier in the same batch.**
+ * A create-then-position sequence is therefore two round trips, not one batch.
  */
 export const OP = {
   create: 'create',
@@ -141,13 +195,24 @@ export const GUARDED_OPS = new Set([OP.update, OP.delete, OP.move])
 /**
  * Field names on an op and on a write response.
  *
- * ⛔ **ASSUMED, all of them.** These were read off `POST /api/sites/{id}/content/items`
- * — a *different route* of the same binary — because the working client of *our*
- * route returns its responses unnormalized and so reveals no names at all.
+ * ✅ **MEASURED 2026-09-17** — backend confirmed these against its own source, and the
+ * four assumptions that stood here are retired (see `ASSUMPTIONS`). Three of the four
+ * names held exactly: `item_id`, `parent_item_id`, `if_unmodified_since`.
  *
- * The shapes are very likely identical: both are `…/items` routes with the same op
- * vocabulary, and this lane's documentation says its concurrency is "aligned with
- * the sites lane". **Likely is not measured**, and this comment is the difference.
+ * ⛔ **The fourth did not.** `section` is wrong for the item route — see `section`
+ * below, where the divergence is documented in full. It is left wrong deliberately:
+ * correcting it changes behaviour, which is a separate change.
+ *
+ * A write answers `{ entity, item_id, item_uuid, item_updated_at }`, and
+ * **`item_uuid` is set on `create` only** — a field this module does not yet name.
+ * `item_updated_at` is the token to send back as `if_unmodified_since` on the next
+ * write to that item; omitting it is last-writer-wins, and the check is per item, so
+ * two people editing different sections do not collide.
+ *
+ * *(Historical: these were originally read off `POST /api/sites/{id}/content/items` —
+ * a different route of the same binary — because the working client of our route
+ * returns responses unnormalized and reveals no names. The guess was right on three
+ * of four, which is roughly the hit rate this file exists to make visible.)*
  */
 export const FIELD = {
   /** Names the target item on an op, and the affected item on a response. */
@@ -162,6 +227,32 @@ export const FIELD = {
    * `append_only`, a field set — simply does not apply to an item that landed in
    * another. A create with no section is accepted, stored somewhere, and every
    * guarantee the author declared is quietly not in force.
+   *
+   * ⛔ **DIVERGENT FROM THE BACKEND — MEASURED 2026-09-17. This value is wrong for
+   * the item route, and is left wrong on purpose until the client change lands.**
+   *
+   * The backend takes a section **two different ways, on two different routes**:
+   *
+   * | route | how a section is named |
+   * |---|---|
+   * | `POST /entities` (create with content) | **by NAME** — `{ items: [{ section: 'profile', … }] }` |
+   * | `POST /entities/{uuid}/items` (everything after) | **by NUMERIC `section_id`** |
+   *
+   * We send `section: '<name>'` on the item route, where the backend wants
+   * `section_id: <number>`.
+   *
+   * ⚠️ **And the cost is larger than the field name**, because the id is needed to
+   * *find* an item as well as to create one. An entity read returns `items[]` with
+   * `id`, `section_id` and `updated_at` — **no section name at all**. Code that
+   * locates an item by name (`items.find(i => i.section === 'content')`) works only
+   * against a mock that invents the name, and against the real backend returns
+   * `undefined`: the update silently never happens, or a duplicate is created.
+   *
+   * ⇒ A client needs **`GET /api/models/{scope}/{name}`** — `sections[]` with `id`,
+   * `name`, `kind`, `is_brief`, `parent_section_id` — to resolve a name, plus a
+   * path-aware resolver for nested sections. That route is **not in `ROUTES`**: it is
+   * outside the `/entities` lane this module pins, so adding it is a deliberate
+   * change, not a drive-by.
    */
   section: 'section',
   /** The precondition an op carries. */
@@ -203,31 +294,25 @@ export const LIST = {
  * edit here plus a moved comment above; `tests/wire.test.js` pins the set so the
  * change cannot be quiet.
  */
+/**
+ * ⭐ **Four entries were RETIRED on 2026-09-17** — backend confirmed them against its
+ * own source, and the rule above is to move the note to MEASURED and delete the entry:
+ *
+ * | retired | confirmed as |
+ * |---|---|
+ * | `write-response-fields` | a write answers `{ entity, item_id, item_uuid, item_updated_at }`; `item_uuid` is set on **create only** |
+ * | `move-exists` | `move` is an op here and carries a precondition |
+ * | `move-position` | positioned server-side — `"first"` \| `"last"` \| `{ after }`; the client never computes an order |
+ * | `op-field-names` | `item_id`, `parent_item_id`, `if_unmodified_since` all confirmed — **but the section field is NOT**, and that is now a recorded DIVERGENCE on `FIELD.section`, not an open question |
+ *
+ * ⛔ `op-field-names` left this list by being **answered, not by being right**. Three
+ * of its four names held; the fourth is wrong and is documented where the wrong value
+ * lives. An assumption that turns out false is not an assumption any more — it is a
+ * defect, and hiding it in a list of open questions is how it stays unfixed.
+ *
+ * What remains below is genuinely unconfirmed.
+ */
 export const ASSUMPTIONS = [
-  {
-    id: 'write-response-fields',
-    we: `a write response names its item as '${FIELD.item}' and its next token as '${FIELD.token}'`,
-    from: 'the site-editor lane, which is a different route',
-    breaks: 'the ledger records nothing, so every second write on an item goes out unguarded — last-writer-wins instead of a 409',
-  },
-  {
-    id: 'op-field-names',
-    we: `an op names its target '${FIELD.item}', its placement '${FIELD.parent}', and its precondition '${FIELD.precondition}'`,
-    from: 'the site-editor lane, which is a different route',
-    breaks: 'writes are refused, loudly — the cheapest of these to be wrong about',
-  },
-  {
-    id: 'move-exists',
-    we: `'${OP.move}' is an op on this lane, and carries a precondition`,
-    from: 'the site-editor lane; this lane documents only update and delete as token-carrying',
-    breaks: 'an operator cannot reorder authored content, which is half of what makes an app an app rather than a CMS',
-  },
-  {
-    id: 'move-position',
-    we: 'a move is positioned server-side — "first" | "last" | { after } — and the client never computes an order number',
-    from: 'the site-editor lane',
-    breaks: 'reordering writes the wrong sequence, or needs a client-side order the store does not want',
-  },
   {
     id: 'viewer-unit-signal',
     we: "read a viewer's unit membership from `acting_unit_id` on /auth/me, surfaced as `viewer.actingUnitId`",