Merge remote-tracking branch 'origin/main' into claude/issue-15769-stale-contract-prose-trio

Author: claude

.changeset/object-title-grade-provenance-caveat.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/spec": patch
+---
+
+`ObjectTitleCompleteness.status` now documents which INPUT each grade describes. No predicate, no grade computation and no accept set moves — the classification is unchanged and correct; what changes is what the declaration tells the reader it means.
+
+`explicit` was documented as "an explicit pointer (`nameField`/`displayNameField`) is set". That is accurate about the predicate, and that is what made it dangerous: on a body served by a `/meta` read exit a pointer is present whether or not the author wrote one, because the exit replays the registry's object-materialization seam (`materializeServedObjectOnto`, which runs `provisionPrimary` in designate-only mode). So `explicit` there means "a pointer is present", never "the author designated this" — and the old wording invited the second reading at every call site.
+
+The corrected declaration says three things the old one left to inference:
+
+- **Provenance decides the grade.** On a served body `explicit` carries no authorship information, and `derived` is unreachable except where that replay withheld the designation. On a body captured before the write seam — an authored definition as written, which is what `os build` / `os lint` hand this predicate through `@objectstack/lint`'s `validateRecordTitle` — `explicit` really does mean the author wrote a pointer.
+- **Authorship is not recoverable afterwards, deliberately.** The write-side inverse `stripProvisionedPrimaryFrom` removes the pointer exactly when it is byte-identical to what the derivation would produce, and says so in its own words: the two are indistinguishable by construction, the same bytes. Neither the served document nor the stored row can answer "did the author designate this?".
+- **The consequence for callers.** Never build a check on `explicit` that needs the authored answer without first proving the input is a pre-write body.
+
+`objectTitleCompleteness` itself carries the one-sentence form of the same warning, because a caller hovering the function is on a different path from a caller hovering the grade.
+
+The correct words already existed in this repo — on the WRITE seam, where nobody reading the grade goes. This moves their substance to the grade.

.changeset/refuse-create-at-hook-body-lowering.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/cli": patch
+"@objectstack/lint": patch
+---
+
+`objectstack build` now refuses to lower a hook/action body that calls `.create(`, and the shared write-pattern ledger stops advertising the verb. Three layers used to disagree about `ctx.api.object('x').create({ … })`, and the loudest one was wrong.
+
+- The spec contract `IScopedObjectRepository` (`packages/spec/src/contracts/scoped-context.ts`) declares `insert` and names `create` as measured-and-deliberately-excluded.
+- The QuickJS sandbox installs exactly `insert / update / delete / updateMany / deleteMany / upsert` as the `ctx.api.object()` write leaves — no `create`. An L2 body calling `.create()` therefore threw `TypeError: not a function` on its **first run**, and under a hook's default `onError: 'abort'` that throw aborted the triggering write, with a message naming no member.
+- The extractor ledger nonetheless advertised `.create({…})` as legal `api-crud-literal` syntax and mapped it in `API_WRITE_METHODS`, so `hook-body-write-unknown-field` graded the payload as a live write and stayed silent when the field existed — a clean bill of health for a call that cannot run. Build time said nothing at all.
+
+What changes:
+
+- **`@objectstack/cli`** — `.create(` joins `FORBIDDEN_PATTERNS` in the hook/action body extractor, beside `.sudo(` and for the same reason (a member real on the in-process `ScopedContext` / `ObjectRepository` and absent from the VM). The refusal names `.insert({ ... })` as the spelling the sandbox actually has. Behaviour is the `forbidden-token` fallback every other entry has: the callable is still registered and still shipped through the back-compat `.mjs` bundle, so a handler keeps running in-process where the host `create()` alias exists — `objectstack build` merely declines to *also* emit it as a body that cannot run. Under `--strict-body` it is a hard failure, correctly. The rule is receiver-loose like `.sudo(` (`const repo = ctx.api.object('x'); repo.create(…)` is refused too) with one carve-out: `Object.create()` is a real sandbox global and is **not** affected.
+- **`@objectstack/lint`** — `create` is withdrawn from `HOOK_BODY_WRITE_PATTERNS`' advertised `api-crud-literal` syntax and from `API_WRITE_METHODS`, on the hook and action surfaces alike. `hook-body-write-unknown-field` / `action-body-write-unknown-field` no longer grade a `.create()` payload; `hook-api-update-readonly-field` keeps its existing `create` exclusion, whose *reason* is updated — it is no longer "the call throws, so a silently-dropped finding would be false" but "the shape can no longer reach this rule at all".
+
+**Migration.** If a hook or action body calls `ctx.api.object('x').create({ … })`, spell it `ctx.api.object('x').insert({ … })` — the same host method, the one the sandbox installs and the only insert verb the contract declares. The host-side `ObjectRepository.create()` alias is untouched and stays reachable from in-process handlers and actions.

.changeset/value-domain-membership-off-vocabulary-refusal.md

@@ -0,0 +1,54 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): `isValueDomainMember` refuses an off-vocabulary domain instead of failing OPEN on `Object.prototype` names
+
+`DOMAIN_MEMBERSHIP` is an object literal, so it inherits `Object.prototype`, and
+`isValueDomainMember` indexed it with no own-property guard. Measured against the
+built artifact (`dist/shared/index.mjs`) on the repo's Node 22 baseline (v22.22.2),
+an off-vocabulary `domain` did one of two wrong things — and one of them was a
+membership FALSE POSITIVE out of a predicate whose whole job is to refuse
+non-members:
+
+| `domain` | before | after |
+|:--|:--|:--|
+| `iana_time_zone` (in vocabulary) | `true` for `UTC` | `true` for `UTC` — unmoved |
+| `toString` | `'[object Object]'` — a truthy **string** | `false` |
+| `valueOf` | a truthy **object** | `false` |
+| `constructor` | a truthy **object** | `false` |
+| `__proto__` | threw a `TypeError` | `false` |
+| `nope`, `''` | threw a `TypeError` | `false` |
+
+**Why it is reachable.** "Unreachable in-repo" is not "unreachable". The parameter
+is typed `ValueDomain` and every in-repo call site names a member, but
+`isValueDomainMember` is **published** on `@objectstack/spec/shared` (it is in
+`packages/spec/api-surface/shared.json`). A plain-JS consumer, or any caller
+handing over a domain string read from **metadata** rather than written in source,
+reaches it with no type checking at all — and metadata-sourced strings are exactly
+where `constructor` and `toString` show up.
+
+**This narrows and widens nothing, measured rather than asserted.** Every accepted
+`domain` is an own key of the record, so no value that was accepted before is
+refused now; the three real domains answer from their own definitions, unmoved.
+The change is one `Object.prototype.hasOwnProperty.call` guard — the same spelling
+the `iso_4217_currency` definition in the same module already uses — returning
+`false` for a domain that is not an own key. A **null-prototype record** was the
+other shape available and was not taken: it converts the truthy answers into
+throws rather than into `false`, and it costs the `Readonly<Record<ValueDomain, …>>`
+annotation that makes a vocabulary member added without a definition fail to
+compile.
+
+**Unknown domain answers `false`; it does not throw.** `false` is the narrowing
+reading — it refuses more and accepts nothing new — whereas a thrown refusal would
+change published behaviour for callers who today receive a truthy value. This is
+the same third branch a sister ruling settled for the same defect family: list
+reject / own-member value / prototype-resolvable ⇒ reject.
+
+The pin that existed did not cover this, and the fix is as much about its
+POPULATION as about the guard: the totality pin asserted the return `typeof` was
+`boolean` but iterated `ValueDomainSchema.options` **only** — exactly the domains
+that behave. The new pins put `toString`, `valueOf`, `constructor`,
+`hasOwnProperty`, `isPrototypeOf`, `propertyIsEnumerable`, `__proto__` and plainly
+absent words into the population, and a third pin holds that population honest by
+asserting every one of them is still outside the vocabulary.

content/docs/automation/hook-bodies.mdx

@@ -166,6 +166,7 @@ The CLI builder **rejects** any source that uses:
 - `process`, `globalThis`
 - `eval`, `new Function`
 - references to identifiers from value-only top-level imports
+- `.sudo(` and `.create(` — members that are real on the **in-process** `ScopedContext` / `ObjectRepository` and absent from the VM's `ctx.api`, so lowering them would ship a body that `TypeError`s on its first run. Write `.insert({ ... })` instead of `.create({ ... })` — it is the only insert verb the `IScopedObjectRepository` contract declares — and reach for [`runAs: 'system'`](/docs/automation/hooks#elevation--runas) instead of `.sudo()`. `Object.create()` is a real sandbox global and is **not** affected.
 
 Need outbound HTTP? Define a **Connector recipe** as metadata and call it via `ctx.connector(...)`. (Connector spec is tracked separately and ships after L1+L2 stabilises.)
 
@@ -185,7 +186,7 @@ Four literal write shapes are recognized, and only these:
 |---|---|---|
 | `ctx.input.<field> = …` / `ctx.input['<field>'] ⟨op⟩= …` (including `+=`, `??=`, …) | checked | not checked — an action's `ctx.input` is its **params bag**, not a record |
 | `Object.assign(ctx.input, { <field>: … })` | checked | not checked — same surface |
-| `ctx.api.object('<literal>').insert\|create\|update({ <field>: … })`, `.updateById(id, { <field>: … })` | checked | checked |
+| `ctx.api.object('<literal>').insert\|update({ <field>: … })`, `.updateById(id, { <field>: … })` | checked | checked |
 | `ctx.record.<field> = …` / `ctx.record['<field>'] ⟨op⟩= …` | n/a — a hook context has no `ctx.record` (the expression throws) | checked: warns as **discarded**, declared field or not |
 
 **A missing warning is not a clean bill of health.** The rule bails *silently* on everything it cannot resolve statically, deliberately preferring a missed finding to a false one — a false positive kills an advisory lint, while a miss just leaves the gap open a little longer:
@@ -270,7 +271,7 @@ The dropped case is the dangerous one: nothing fails, the step reports success,
 
 Which hooks these rules can *see* depends on the command, because every rule in this family opens on `body.language === 'js'`. A hook authored as an inline `handler` function carries no `body`, so it is judged only where the command has first lowered the handler to a metadata body: `objectstack build` always has (it lowers before it parses — see [How the build lowers a handler](#build-pipeline)), and since [#16095](https://github.com/objectstack-ai/objectstack/issues/16095) `objectstack lint` judges that same lowered view, so an author who runs only the pre-flight is told the same thing the build would refuse. Since [#16544](https://github.com/objectstack-ai/objectstack/issues/16544) `objectstack validate` lowers before it parses as well, so all three commands judge the same view of a handler-authored hook — a stack `objectstack validate` passes is one `objectstack build` does not refuse on this family. A handler the build cannot lower (a forbidden token, a module-scope identifier) has no body on any command and is reported by the lowering rules instead, never guessed at here.
 
-Only literal object names and literal payload keys are seen; a `sudo()` chain, a dynamic object name and an object this stack does not declare are all skipped, so the rule has no opinion on them. `.create()` is skipped too, for a reason about the **sandbox** rather than the engine: the VM-side `ctx.api.object()` installs `insert` / `update` / `delete` / `updateMany` / `deleteMany` / `upsert` and no `create` leaf, so a body calling `.create()` throws `TypeError: not a function` on its first run — a loud failure, not a silent drop — and the same payload spelled `.insert()` is what the rule judges. The flow surface has carried the same gate as `flow-update-readonly-field` since [#3425](https://github.com/objectstack-ai/objectstack/issues/3425), and since [#15394](https://github.com/objectstack-ai/objectstack/issues/15394) it reports a non-`runAs: 'system'` `create_record` node's static-`readonly` write at the same **error**, again with no conditional finding on a create.
+Only literal object names and literal payload keys are seen; a `sudo()` chain, a dynamic object name and an object this stack does not declare are all skipped, so the rule has no opinion on them. `.create()` is skipped too, and since [#16249](https://github.com/objectstack-ai/objectstack/issues/16249) it cannot even arrive: `objectstack build` refuses `.create(` at lowering, so a handler spelling it is bundled and never becomes a `body` these rules parse, and the write-shape ledger no longer advertises the verb. The reason behind that refusal is about the **sandbox** rather than the engine: the VM-side `ctx.api.object()` installs `insert` / `update` / `delete` / `updateMany` / `deleteMany` / `upsert` and no `create` leaf, and the `IScopedObjectRepository` contract declares `insert` only — so a body calling `.create()` threw `TypeError: not a function` on its first run, aborting the triggering write under the default `onError: 'abort'`. A loud failure, never a silent drop; the same payload spelled `.insert()` is what the rules judge. The flow surface has carried the same gate as `flow-update-readonly-field` since [#3425](https://github.com/objectstack-ai/objectstack/issues/3425), and since [#15394](https://github.com/objectstack-ai/objectstack/issues/15394) it reports a non-`runAs: 'system'` `create_record` node's static-`readonly` write at the same **error**, again with no conditional finding on a create.
 
 The table above is about a **hook** body. An **action** body is the one surface where the answer changes, so read this before you move a body from one to the other: an action body runs **elevated** — its `ctx.api` is built over the caller's envelope with `isSystem` set, which is the same trusted posture that lets an action bypass row and field permissions — and the static strip applies only to non-system callers. So `ctx.api.object('x').update({ someReadonlyField })` **lands** in an action, and there is no finding for it. Elevation does not waive the *conditional* lock, though, so that half does carry across: `action-api-update-readonly-when-field` — a **warning** — on an action body's literal `ctx.api` update to a `readonlyWhen` field ([#13770](https://github.com/objectstack-ai/objectstack/issues/13770)). Net effect when you move a body: a `readonly` write changes behaviour, a `readonlyWhen` write does not.
 
@@ -404,6 +405,8 @@ The extractor scans each body for known patterns and adds the matching capabilit
 | `ctx.log.info / warn / error / debug` | `log` |
 | `*.title(<argument>)` — the related-record form only; bare `ctx.title()` performs no read | `api.read` |
 
+The matcher is deliberately over-inclusive — it names spellings the VM does not install (`patch`, `remove`, `get`, `list`, `create`) because an over-inferred token costs nothing the sandbox ever checks, while an under-inferred one surfaces as a sandbox refusal far from its cause. `create` is listed only for that reason: a body spelling it is refused at lowering (see [What the sandbox forbids](#what-the-sandbox-forbids)) and never reaches inference at all.
+
 When inference does not derive what a body needs, declare the tokens yourself by
 supplying `body` on the hook or action instead of a `handler`:
 

packages/cli/src/utils/extract-hook-body.ts

@@ -14,8 +14,14 @@
  * For v1 we apply a deliberately simple **regex allow-list** over the
  * extracted body — full TypeScript AST analysis is deferred to v2. Anything
  * the regex rejects (top-level `import`, `require(` / esbuild's `__require(`,
- * `fetch(`, `process.*`, `globalThis.*`, `eval`, `new Function`, `.sudo(`) makes
- * extraction **throw**.
+ * `fetch(`, `process.*`, `globalThis.*`, `eval`, `new Function`, `.sudo(`,
+ * `.create(`) makes extraction **throw**.
+ *
+ * The last two are one family: a member that is REAL on the host
+ * `ScopedContext`/`ObjectRepository` and absent from the VM's `ctx.api`, so the
+ * same handler source passes an in-process test and TypeErrors the moment the
+ * build lowers it into a body. `.create(` carries one wrinkle `.sudo(` does not
+ * — see its entry in `FORBIDDEN_PATTERNS`.
  *
  * ⚠️ What that throw costs the BUILD depends on the flag, and the two outcomes
  * are not the same one. This header used to claim only the second (#10678):
@@ -213,6 +219,49 @@ const FORBIDDEN_PATTERNS: Array<{ rx: RegExp; reason: string }> = [
       + 'before-hook (`ctx.input.<field> = ...`), or leave this handler bundled so it runs in-process '
       + 'where `sudo()` exists',
   },
+  // [#16249] Same family as `.sudo(` above, one layer over: the host
+  // `ObjectRepository` aliases `create(data)` to `insert(data)`, the spec
+  // contract `IScopedObjectRepository` declares `insert` and NOT `create`
+  // (packages/spec/src/contracts/scoped-context.ts — `create` is listed there
+  // as measured and deliberately excluded), and the VM installs exactly
+  // `insert / update / delete / updateMany / deleteMany / upsert` as the
+  // `ctx.api.object()` write leaves (`installCtx`,
+  // runtime/src/sandbox/quickjs-runner.ts). So a lowered body's `.create()` is
+  // `TypeError: not a function` on its FIRST run, and under a hook's default
+  // `onError: 'abort'` that aborts the triggering write with a message naming
+  // no member — the blind message #14010 measured for `sudo()`.
+  //
+  // What made this worse than an omission: the extractor ledger
+  // (`HOOK_BODY_WRITE_PATTERNS`, packages/lint) ADVERTISED `.create({…})` as
+  // legal `api-crud-literal` syntax and graded its payload as a live write, so
+  // the one layer that actively told an author how to write it named a spelling
+  // that cannot run. That entry is withdrawn in the same change; refusing here
+  // is what makes build time say what the contract already said.
+  //
+  // ⛔ The alternative — installing a `create` leaf in `installCtx` — is
+  // rejected on purpose: it would have the SANDBOX ratify a verb the CONTRACT
+  // never declared, which is the wrong direction under contract-first.
+  //
+  // Receiver-loose like `.sudo(` (a local alias `const repo =
+  // ctx.api.object('x'); repo.create(…)` must not slip through), with ONE
+  // carve-out that `.sudo(` needs no equivalent of: `Object` is a real sandbox
+  // global (pinned in `SANDBOX_GLOBALS`), so `Object.create(null)` is working,
+  // lowerable code. Refusing it would turn a correct body into a bundled
+  // closure — and a hard failure under `--strict-body` — which is a false
+  // refusal, not the safe direction. The lookbehind excludes that ONE receiver
+  // and nothing else: `myObject.create(` still matches, because `\b` requires a
+  // word boundary before `Object`.
+  {
+    rx: /(?<!\bObject\s*)\.\s*create\s*\(/,
+    reason:
+      '`create()` is not reachable from a sandboxed body — the VM\'s `ctx.api.object()` installs '
+      + '`insert` / `update` / `delete` / `updateMany` / `deleteMany` / `upsert` and no `create` leaf, so '
+      + 'the call is a TypeError at run time (and under a hook\'s default `onError: \'abort\'` that aborts '
+      + 'the triggering write). Spell the same payload `.insert({ ... })`, which is the member the sandbox '
+      + 'actually has and the only insert verb the spec contract declares; `Object.create()` is unaffected. '
+      + 'Alternatively leave this handler bundled so it runs in-process, where the host repository\'s '
+      + '`create()` alias exists',
+  },
 ];
 
 const CAPABILITY_PATTERNS: Array<{ rx: RegExp; cap: 'api.read' | 'api.write' | 'crypto.uuid' | 'log' }> = [