Merge origin/main: resolve the #9633 couplings now that #9635 and #9646 landed

Merged rather than rebased: rebasing a pushed branch needs a force-push, which
the dev contract forbids outright. Same outcome, no forced history.

Both blockers are now on main (#9635 at c07d6e8, #9646 at 73010f1), so the
three points this card was holding are resolved here:

1. Field JSDoc — the clause naming replay as an exception is gone. Not a
   mechanical delete: it left "Two things are unaffected either way" counting
   wrong, so the sentence is rewritten to say `false` writes no rows at all,
   replay included, with the sys_job counters as the one exception.
2. Class JSDoc — the "one row it does not govern" sentence is gone. The bullet
   keeps its single {@link DbJobAdapterOptions.recordRuns} pointer rather than
   paraphrasing the flag a second time, per the constraint #9631 was built on.
3. #9646's fifth test case, which pinned "replay writes anyway", is deleted.
   It carried a comment saying it would change together with the class JSDoc if
   this card ruled the carve-out shut. It did. A note stands where it was.

Test-file conflict was add/add — both describe blocks appended at the end. Both
are kept; they cover different paths (#9631's the wrap() path, this card's the
replay() path).

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

Author: claude

.changeset/plugin-audit-readme-audit-service-link.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/plugin-audit": patch
+---
+
+Published README points at the `services.audit` reference again, in the form a published reader can follow (#9589)
+
+PR #9531 dropped this README's "See Also" pointer to the runtime-services audit
+page because the page was measured wrong — it documented `record()` /
+`'set' | 'reset'` (the settings sink) as if that were the `audit` slot. PR #9587
+rewrote the page around the real slot, so the reason for the omission has stopped
+holding, and the link is restored.
+
+It is restored because the page carries three things this README deliberately
+does not, each verified against the page as it stands on `main` rather than
+against the PR title that rewrote it:
+
+- **the failure posture of the slot itself** — `recordAuthEvent` never throws; a
+  failed ledger insert is reported at `error` level once per process and then
+  drops to `debug`, the row is lost and nothing retries it, and the call silently
+  no-ops when no data engine resolves or when `userId` is absent. This README
+  documents the *record-view batcher's* two failure postures, which are a
+  different code path; it says nothing about this one.
+- **the event's field-by-field shape** — that `userId` must be a real `sys_user`
+  id, that `sessionId` lands on `record_id` with `object_name` fixed to
+  `sys_session`, that `organizationId` stamps the tenant columns and an unstamped
+  row is one non-administrator members can never see, and that `context` is
+  serialized into `metadata`. This README states the slot's interface and its
+  closed `'login' | 'logout'` action union, and deliberately stops there.
+- **the settings-sink disambiguation** — that `SettingsAuditSink.record()` is
+  never registered as or resolved from this slot, and that
+  `getService('audit').record({ ... })` therefore fails with a `TypeError`.
+
+The restored line is **not** the line #9531 removed. That one read
+`[Audit Logging Best Practices](/content/docs/kernel/runtime-services/audit-service.mdx)`
+— a label describing a best-practices guide the page has never been, and a
+repo-path-rooted URL that resolves for neither of this README's published
+audiences. A README in the package's `files` array is rendered on npm and on
+GitHub, where a root-relative href resolves against `npmjs.com` / `github.com`,
+not against the docs site. The replacement uses the absolute
+`https://docs.objectstack.ai/docs/...` form that `create-objectstack`'s published
+READMEs already use, and its annotation states what the page adds — so the next
+author weighing the same omission can check the justification instead of
+reconstructing it.
+
+The one pre-existing site-root-relative docs link in this same file
+(`/docs/permissions/permission-sets#access-depth...`, added by the same PR) is
+converted to the same absolute form. Its target page and heading anchor both
+exist; only the spelling was unfollowable off the docs site.

.changeset/register-flow-conversion-conflict.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/spec": patch
+---
+
+Register `FLOW_CONVERSION_CONFLICT` (409) in the ADR-0112 error-code ledger under
+`@objectstack/metadata-protocol` (#9567). The code was already live on the wire —
+`saveMetaItem`'s flow-conversion rename guard (`protocol.ts`) has thrown it since
+ADR-0078 landed, already SCREAMING_SNAKE — but was invisible to
+`check:dispatcher-error-vocabulary`'s scan because the site stamps it through a
+cast (`(err as any).code = 'FLOW_CONVERSION_CONFLICT'`) rather than the bare-
+identifier `assign` shape the scan matched at the time. This is an ordinary,
+additive admission: no accept/reject behavior, no producer, and no wire shape
+changes.

.changeset/service-job-class-jsdoc-recordruns.md

@@ -0,0 +1,26 @@
+---
+"@objectstack/service-job": patch
+---
+
+fix(services): the `DbJobAdapter` class JSDoc stops promising a `sys_job_run` row that `recordRuns: false` never writes (#9631)
+
+`tsup` emits this comment into `packages/services/service-job/dist/index.d.ts`, so it is
+the class-level editor tooltip an npm consumer of `@objectstack/service-job` reads. Its
+third "persisted side effects" bullet said **every execution writes a `sys_job_run` row**;
+`wrap()` gates that insert on `recordRuns`, which defaults to `true` but writes nothing at
+all when set to `false`. The same emitted `index.d.ts` states the truthful field-level rule
+for `recordRuns` sixty lines above, so the published declaration disagreed with itself
+about one flag — a reader hovering either one got a different answer.
+
+No runtime behaviour changes. This is a patch because the entire deliverable is text inside
+a published package's `.d.ts`: with no version bump the corrected tooltip never reaches npm
+and the fix is unmet in the only channel it is about.
+
+The corrected bullet defers to `DbJobAdapterOptions.recordRuns` via `{@link}` rather than
+restating the rule, so the two cannot drift apart again, and it names the one row the flag
+does not govern — `replay()`'s synthetic `trigger: 'replay'` row, written either way. The
+fourth bullet gains the matching negative: the `sys_job` counters are bumped
+unconditionally, `recordRuns` gating only the per-attempt rows.
+
+Five cases now pin the flag in both directions. Nothing in this package referenced
+`recordRuns` before, so both corrected sentences were accurate but unenforced.

.changeset/service-jsdoc-declared-equals-actual.md

@@ -0,0 +1,52 @@
+---
+"@objectstack/service-cache": patch
+"@objectstack/service-job": patch
+---
+
+fix(services): two published `.d.ts` JSDoc comments stop describing behaviour their code does not have — `MemoryCacheAdapter` eviction is FIFO, not LRU, and `recordRuns` is an on/off switch, not a retention cap (#9611)
+
+Both comments are emitted by `tsup` into each package's built `index.d.ts`, so they
+are **the editor tooltip an npm consumer sees** — the same "published documentation
+asserting behaviour the runtime does not have" class as #9517 and #9532, in a third
+channel that no gate reads. No runtime behaviour changes in either package; this is a
+patch because the corrected text only reaches consumers through a release.
+
+**1. `MemoryCacheAdapter` — "LRU-style eviction" was never LRU.**
+
+The class comment advertised `TTL-based expiry and LRU-style eviction`. The eviction
+path takes `this.store.keys().next().value` — the first key in `Map` insertion order —
+and `get()` returns `entry.value` without ever deleting and re-setting the key, so a
+read does not move an entry back. Nor does an overwrite: `Map.set` on a key already
+present keeps its original insertion slot. Eviction has therefore always been
+**oldest-inserted (FIFO)**, which is a materially different hit-rate profile from the
+one the tooltip promised anyone sizing a cache.
+
+The comment was corrected rather than the code, deliberately: `maxSize` defaults to `0`
+(unlimited), so the eviction path is off by default and nothing shipped is getting FIFO
+where it expected LRU, and there is no measured pull for LRU. Minting a real behaviour
+change to make a stale sentence true inverts the fix — the defect is that the
+documentation lies, not that the cache is wrong. (A real LRU already exists in the repo,
+`packages/metadata/src/utils/lru-cache.ts`, for the callers that need one.)
+
+Four tests now pin the corrected sentence so it stops being an unenforced claim. Each is
+written as a **discriminator against LRU**: it reads (or overwrites) the oldest entry
+before overflowing the cache and then asserts that entry was evicted anyway — a hot key
+dies on age, an untouched newer key survives. The pre-existing eviction tests could not
+tell the two policies apart, which is how the wrong comment sat green.
+
+**2. `DbJobAdapterOptions.recordRuns` — the comment described a different field.**
+
+`/** Soft cap on sys_job_run rows recorded per job (defaults to none — handled by
+retention jobs) */` made three claims and the code contradicts all three: the field is a
+`boolean`, not a count; it defaults to `true`, not "none" (`args.options?.recordRuns ??
+true`); and it gates whether a `sys_job_run` row is written at all, rather than being
+trimmed later by retention. The sentence reads as if it belongs to the numeric
+`JobRunRetention` knob that ADR-0057 retired — a copy-paste that outlived its source.
+
+The consequence the new wording keeps in sight: **a reader who sets `recordRuns: false`
+expecting "no cap" gets run history switched off.** The replacement states the real
+meaning (one row per attempt, inserted at start and updated on settle, default `true`)
+and both things that are *not* affected by the flag — the `sys_job` row's own
+`last_status` / `run_count` / `failure_count` counters, which `bumpJob` updates
+regardless, and `replay()`, which writes its synthetic `trigger: 'replay'` row without
+consulting the flag at all.

.changeset/spec-prompts-real-exports-9545.md

@@ -0,0 +1,32 @@
+---
+'@objectstack/spec': patch
+---
+
+Published agent-authoring prompts now reference real exports.
+
+`prompts/create-new-project.md`, `prompts/implement-objectql.md` and
+`prompts/implement-objectos.md` told agents to import five symbols that
+`@objectstack/spec` does not export. Four failed loudly. The fifth did not:
+`import { Object } from '@objectstack/spec/data'` does not resolve, so the
+annotation in `export const AccountObject: Object = { ... }` bound to the
+**JavaScript global** `Object` instead — metadata authored from that prompt
+type-checked against a type that constrains nothing.
+
+- Object definitions now use the house authoring convention measured in the
+  example apps, `ObjectSchema.create({ ... })`, which genuinely validates.
+  Correcting it exposed that the prompt's own example set `enable.audit` /
+  `enable.workflow`, neither of which exists; they are now `trackHistory` /
+  `files`, the pair the schema's own docstring uses.
+- `implement-objectql.md` keeps the real `Field` and `QuerySchema` imports and
+  derives the object metadata type as `z.infer<typeof ObjectSchema>`, matching
+  both `prompts/instructions.md` ("interfaces must be inferred from Zod") and
+  spec's own `src/contracts/schema-driver.ts`.
+- `ManifestSchema` becomes `ObjectStackDefinitionSchema` from the package root:
+  the prompt's subject is `objectstack.config.ts`, which is neither of the
+  `/system` manifests.
+- `IdentitySchema` / `PolicySchema` have no bare referent; Rule #2 now names
+  `RLSUserContextSchema` and `RowLevelSecurityPolicySchema` from
+  `@objectstack/spec/security`.
+- The three non-existent "Key Files to Watch" paths
+  (`system/{manifest,identity,events}.zod.ts`) now point at `stack.zod.ts`,
+  `security/rls.zod.ts` and `kernel/events.zod.ts`.

.github/workflows/lint.yml

@@ -486,6 +486,21 @@ jobs:
       - name: Quick-reference section counts match their tables
         run: pnpm check:quick-reference-counts
 
+      # #9604: the runtime-services chapter's pages are enumerated in three
+      # hand-written places (meta.json "pages", the chapter list in
+      # runtime-services/index.mdx, the services.* table in kernel/index.mdx) and
+      # nothing read any of them -- check:docs-audit-scope derives WHICH pages the
+      # accuracy audit covers, never whether an index enumerates them. #9604 found
+      # services.sms with a page, a meta.json entry, a registered slot and a
+      # canonical-source row, missing from BOTH index lists; #9588 was the same
+      # page drifting on a different line. The pages on disk are the source of
+      # truth and the gate holds all three enumerations (and the chapter list's
+      # order) to them. It lives in this job with the other docs guards: the edit
+      # that breaks it is a docs edit, so a packages/** paths filter would blind
+      # it to its own failure mode.
+      - name: Runtime-services indexes enumerate the chapter's real pages
+        run: pnpm check:runtime-services-index
+
       # #3723 ADR anchors: code an accepted ADR governs must keep naming it.
       # That incident reversed three accepted ADRs with a patch-level changeset,
       # and the mechanism was simply that the edited file never mentioned them —

content/docs/api/data-api.mdx

@@ -222,6 +222,14 @@ Delete a record.
 
 **Response**: `{ object: "account", id: "1", success: true }`
 
+Every relation pointing at the deleted record honours its own `deleteBehavior`
+(`cascade` / `set_null` / `restrict`). On a `multiple: true` reference, `set_null`
+removes just the deleted id from the array and keeps the rest, and a reference set
+emptied that way reads back as `[]` — never `null`, so a client that branches on
+`null` for "no link" misses the emptied case (the `multiple` doc block in
+`packages/spec/src/data/field.zod.ts`, rendered in the
+[Field reference](/docs/references/data/field)).
+
 ---
 
 ## Batch Operations

content/docs/data-modeling/field-types.mdx

@@ -315,7 +315,7 @@ Reference to a record in another object (foreign key).
 |:---|:---|:---|:---|
 | `reference` | `string` | **required** | Target object name (snake_case) |
 | `referenceFilters` | `string[]` | — | **Removed** (#2377, ADR-0049) — no longer a recognized field property (unknown keys are stripped by the schema). Use structured `lookupFilters` + `dependsOn` instead; see [Relationships](/docs/data-modeling/relationships) |
-| `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'set_null'` | Behavior when referenced record is deleted (a *required* lookup left at the default `set_null` is escalated to `restrict`, since a NOT NULL foreign key cannot be cleared) |
+| `deleteBehavior` | `'restrict' \| 'cascade' \| 'set_null'` | `'set_null'` | Behavior when referenced record is deleted (a *required* lookup left at the default `set_null` is escalated to `restrict`, since a NOT NULL foreign key cannot be cleared). On a `multiple: true` lookup `set_null` removes only the deleted **member** — the other members are kept, and a set emptied that way is stored as `[]`, never `null` |
 
 ```typescript
 { name: 'company', label: 'Company', type: 'lookup', reference: 'account' }
@@ -655,7 +655,7 @@ These properties are available on **all** field types:
 | `type` | `FieldType` | **required** | One of the supported field types |
 | `required` | `boolean` | `false` | Whether the field is required |
 | `unique` | `boolean` | `false` | Enforce uniqueness |
-| `multiple` | `boolean` | `false` | Allow array of values |
+| `multiple` | `boolean` | `false` | Allow array of values (multi-record lookup, multi-select, multi-file). An emptied multi-value lookup reads back as `[]`, never `null` — the `multiple` doc block in [`FieldSchema`](/docs/references/data/field) |
 | `searchable` | `boolean` | `false` | Include in search index |
 | `sortable` | `boolean` | `true` | Allow sorting by this field |
 | `hidden` | `boolean` | `false` | Hide from default views |

content/docs/data-modeling/fields.mdx

@@ -189,9 +189,13 @@ rejected with `400 VALIDATION_FAILED` and a `fields[]` entry whose `code` is
 `reference_not_found` (see the [error catalog](/docs/api/error-catalog)). The
 same check runs on bulk updates.
 
-Clearing a relationship is not a dangling reference: `null`, `""` and `[]` mean
-"no link" — exactly what `deleteBehavior: 'set_null'` writes when the parent
-goes away.
+Clearing a relationship is not a dangling reference: `null`, `""` and `[]` all mean
+"no link". Which of them `deleteBehavior: 'set_null'` writes when the referenced
+record goes away depends on the field: a single-value lookup is set to `null`, while
+a `multiple: true` lookup keeps its other members and loses only the deleted one —
+and a set emptied that way is written as `[]`, never `null` (the `multiple` doc block
+in `packages/spec/src/data/field.zod.ts`, rendered in the
+[Field reference](/docs/references/data/field)).
 
 <Callout type="info">
 `deleteBehavior` governs what happens to *this* record when the **referenced**

content/docs/data-modeling/validation-rules.mdx

@@ -244,10 +244,26 @@ These properties apply to **all** field types and are validated by the base `Fie
 | `reference` | `string` | — | **Required.** Target object name |
 | `referenceFilters` | `string[]` | — | **Removed** (#2377, ADR-0049) — no longer part of the `Field` schema; use `lookupFilters` + `dependsOn` instead |
 | `deleteBehavior` | `enum` | `set_null` | `set_null`, `cascade`, or `restrict` |
-| `multiple` | `boolean` | `false` | Allow multiple references |
+| `multiple` | `boolean` | `false` | Allow multiple references; the value is validated as an array of ids |
 
 **Default constraints:** Validates that referenced record exists. Foreign key integrity enforced.
 
+**Multi-value lookups (`multiple: true`).** The empty set is representable: an emptied
+multi-value lookup is stored and read back as `[]`, never `null` — including when
+`deleteBehavior: 'set_null'` removes the last remaining member. The declared contract
+lives in the `multiple` and `required` doc blocks of
+`packages/spec/src/data/field.zod.ts` (rendered in the
+[Field reference](/docs/references/data/field)), and it makes `required` on a
+multi-value lookup mean **non-empty array**.
+
+<Callout type="warn">
+The `required`-means-non-empty half is **declared but not yet enforced** by the record
+validator: today `[]` passes the required check on both insert and update, because the
+check treats only `undefined`, `null` and blank strings as missing. Validate emptiness
+in application code until that lands (tracked in #9476). The representation guarantee
+above (`[]`, never `null`) is live.
+</Callout>
+
 ### `master_detail`
 
 | Property | Type | Default | Validation Behavior |