Merge origin/main into claude/issue-22870-p2-service-mailbox

system-context.mdx: main's page taken, then the inbound-mail gates' row re-inserted as row 47 and the later rows, the prose references and the census ledger re-derived by the census gate (gen:system-context-census).

Claude-Session: https://claude.ai/code/session_013tMiyVNzCwaUhgfUe6gg8y
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/15204-walled-catalog-package-verbs.md

@@ -0,0 +1,34 @@
+---
+'@objectstack/runtime': minor
+'@objectstack/spec': minor
+---
+
+Under a walled posture the `/packages` verbs that publish, discard, roll back, revert, duplicate or adopt security catalog items are the platform operator's
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: registered walled-catalog-package-verbs-retired -->
+
+**BREAKING** accept-set narrowing, shipped as `minor` under the repo's launch-window convention for breaking changes (ADR-0131 D3: "Shared-DB multi-tenant (`group` / `isolated`): tenant admins cannot create or edit catalog items; the operator defines the catalog for every tenant").
+
+**Why.** A package's positions and permission sets are environment-wide, and every organization resolves them by name. Measured on a booted `isolated` and `group` stack: the operator published a permission set in a writable package, and another organization's member held it. An organization owner granted `manage_metadata` inside their own organization (never the platform operator) then:
+- published the operator's pending draft adding `manage_users`, and that member's next resolution carried it;
+- rolled the package back, and the member lost it;
+- reverted the operator's commit, and the member lost it;
+- copied the set, under the same name, into a package of their own, and `GET /meta` then served their copy;
+- discarded the operator's pending draft (through `revert`, and `discard-drafts` is the same discard by a second door);
+- adopted the environment's catalog rows into their own package.
+
+**FROM → TO**, on a `group` or `isolated` deployment, for a caller below the platform operator (the `PLATFORM_ADMIN` rung: the deployment's declared `OS_PLATFORM_OWNER_EMAIL` owner). Every door is on the runtime dispatcher, and each **FROM** is: admitted to any `manage_metadata` holder. Each **TO** is `403 PERMISSION_DENIED`, naming the posture, before the verb runs:
+
+- `POST /api/v1/packages/:id/publish-drafts`, when the package has a pending position, permission-set or capability draft.
+- `POST /api/v1/packages/:id/revert`, when the package has such a draft.
+- `POST /api/v1/packages/:id/discard-drafts`, when the package has such a draft.
+- `POST /api/v1/packages/:id/rollback`, when a commit it would undo touched a position, permission set or capability.
+- `POST /api/v1/packages/:id/commits/:commitId/revert`, when that commit touched one. The commit's own items are judged: the verb takes the commit id alone, so the URL's package segment changes nothing.
+- `POST /api/v1/packages/:id/duplicate`, when the source package's published environment rows (the ones it copies) hold one.
+- `POST /api/v1/packages/:id/adopt-orphans`, when the environment's orphaned rows include one.
+
+**Unchanged.** A package whose drafts, commits or rows carry no catalog item is handled as before, for the same callers. The platform operator runs every verb as before. Under `single` (and with no `tenancy` service) nothing changes, and no extra read happens: the verdict is asked before the items are read.
+
+**The remedy.** The platform operator publishes, discards, rolls back, reverts, duplicates and adopts catalog-carrying packages. `@objectstack/spec` registers the change as the ADR-0087 semantic entry `walled-catalog-package-verbs-retired`. Every door asks the one predicate the catalog's other write doors ask, `walledCatalogWriteVerdict` (`@objectstack/metadata-core`), through the same helper as the package delete.

.changeset/15953-verify-delete-behavior-family.md

@@ -0,0 +1,37 @@
+---
+'@objectstack/verify': minor
+'@objectstack/cli': minor
+---
+
+feat(verify): the delete-behaviour family — every `deleteBehavior` a reference field declares is what a delete of the referenced record does, runnable as `os verify --delete-behaviors` (#15953)
+
+Clause-②: yes
+
+A fourth derived proof family beside `runCrudVerification`, `runRlsProofs` and `runReferenceShapeProofs`. It needs no hand-written test: from the app's own objects it takes every field whose type is in `REFERENCE_VALUE_TYPES` (`lookup`, `master_detail`, `user`, `tree`) and reads what the declaration states through the spec's own parse of the field (`FieldSchema`), which is the value a built artifact carries: a `lookup` or `tree` that authors nothing states `set_null`, an authored value is kept, and a bare `master_detail` states none. For each field it creates a fresh target record and a holder referencing it, deletes the target by id, and reads back what the engine left, through two doors: the REST data route as the signed-in caller, and the engine's own delete as the system principal.
+
+- `cascade` holds when the holder is gone with the target.
+- `set_null` holds when the holder survives and no longer references the deleted record.
+- `restrict` holds when the delete is refused with `DELETE_RESTRICTED` naming the holder's object, and both records are still there.
+- In every case a second holder, referencing another record of the same target object, must be untouched.
+
+A refusal for any other reason (a hook's veto, a validation rule, a permission) is `unattributed`, so an engine that refused every delete would not read as a proven `restrict`. A field is `proven`, `contradicted` (a delete did something else), `failed` (a door faulted), `inconclusive` (an unattributed refusal, or a fixture the app refused; the report says why), `excluded` or `not-derivable`. `contradicted + failed` is the report's `hardFailures`.
+
+Two shapes are `excluded` rather than given an expectation, because an engine rule decides what a delete does to them, not the declaration: a `set_null` on a required reference (it cannot be cleared), and a field whose parse carries no `deleteBehavior` (a bare `master_detail`, a `user`). A field is `not-derivable` when no fixture can be built from the app's metadata: its target is not an object the app declares (such as `sys_user`), it is `readonly` or `system`, or the CRUD derivation cannot synthesize its holder or target. Only by-id deletes are asked; a predicate or multi-row delete is outside the family.
+
+**`@objectstack/verify` — new exports.**
+
+- `runDeleteBehaviorProofs(stack, token, config, { doors? })` → `DeleteBehaviorReport`. Run it on a fresh stack of its own: every `restrict` probe leaves its records behind.
+- `deriveDeleteBehaviorCases(config)`, `formatDeleteBehaviorReport(report)`.
+- Types: `DeclaredDeleteBehavior`, `DeleteBehaviorCase`, `DeleteBehaviorDoor`, `DeleteBehaviorAnswer`, `DeleteBehaviorProbeResult`, `DeleteBehaviorFieldStatus`, `DeleteBehaviorFieldResult`, `DeleteBehaviorReport`, `DeleteBehaviorProofOptions`.
+
+```ts
+import { bootStack, runDeleteBehaviorProofs, formatDeleteBehaviorReport } from '@objectstack/verify';
+
+const stack = await bootStack(myApp);
+const report = await runDeleteBehaviorProofs(stack, await stack.signIn(), myApp);
+console.log(formatDeleteBehaviorReport(report));
+expect(report.summary.hardFailures).toBe(0);
+await stack.stop();
+```
+
+**`@objectstack/cli` — `os verify --delete-behaviors`.** Opt-in, like `--reference-shapes`, on a fresh boot of its own. A contradicted declaration, or a door that faulted, counts in `hardFailures` and fails the run. A `tree` field's delete is not honoured today (deleting the parent leaves the child's reference in place), so an app that declares one fails the run with the flag. The `--json` document carries the report as `deleteBehaviors` when the flag is given; without the flag the run and its document are unchanged.

.changeset/22934-stack-collection-duplicate-entry-refused.md

@@ -0,0 +1,49 @@
+---
+'@objectstack/spec': minor
+'@objectstack/metadata': patch
+---
+
+feat(spec)!: `defineStack` refuses two entries of one named collection under one identity, naming the collection, the identity and every index — for 27 collections (#22934)
+
+Clause-②: no (narrowing)
+
+<!-- adr-0087: registered stack-collection-duplicate-entry-refused -->
+
+**BREAKING**: an accept-set narrowing on a published authoring surface, shipped as `minor` under the launch-window convention for breaking changes.
+
+The runtime registers the entries of these collections under one identity each, and a stack could author two entries under one identity with nothing refusing it: `defineStack` and `objectstack validate` accepted the pair (exit 0, `valid: true`, no finding naming it). Measured on a source boot (`objectstack serve`, no build) and on `objectstack build` followed by an artifact-backed boot:
+
+- `objects`, `pages`, `dashboards`, `reports`, `datasets`, `flows`, `jobs`, `emailTemplates`, `books`, `positions`, `permissions`, `capabilities`, `sharingRules`, `webhooks`, `mappings`, `analyticsCubes`, `connectors`, `picklists`, `tools`, `skills`, `views`, `apis`, `apps` and `objectExtensions` kept only the LAST entry on both paths, with no notice at the default log level (for `apis`, the first entry's path answered 404);
+- `datasources`: the metadata described the last entry while the driver connected with the first one's configuration;
+- `hooks`: the metadata listed one hook while both handlers were bound and ran;
+- `docs`: `objectstack validate` and `objectstack build` refused the pair (`docs/duplicate-name`), while a source boot kept the last.
+
+**What is refused.** `defineStack`'s cross-reference pass refuses the stack with its existing envelope (`STACK_CROSS_REFERENCE_INVALID`, status 422, `defineStack cross-reference validation failed (N issues):`), one finding per collision, naming the collection, the identity and every index:
+
+```text
+✗ Datasource 'crm_external' is declared twice in `datasources`: stack.datasources[0] and stack.datasources[1]. …
+```
+
+The identity is what the runtime keys an entry by: its `name`; the `(name, locale)` pair for `emailTemplates` (one name across several locales is an i18n bundle, and an entry with no `locale` counts as `en-US`); the extended object (`extend`) for `objectExtensions`; and for `views` the object a container binds to (`object`, else `list.data.object`, else `form.data.object`, else its `name`). The check runs in an object-less stack too, and every entry counts, byte-identical twins included. `objectstack validate`, `objectstack build` and a source boot all load the config through `defineStack`, so all three refuse it at load. Like every cross-reference check it is skipped under `defineStack(…, { strict: false })`. On an `app` package, two apps under one name now get this refusal, which runs before the single-app count.
+
+**Unchanged.** Distinct identities; an email-template i18n bundle (one name, one entry per locale); the map form under distinct keys (two keys whose entries spell one explicit `name` are one identity, and are refused); the same name reused by another package of a multi-package project (`composeStacks(…, { manifest: 'preserve' })` keeps each package's collections in its own `packages[i]` body, which this check does not read); `plugins` (last-one-wins with a warning is the kernel's declared contract), `agents` (withdrawn for app packages) and `picklistExtensions` (merged by option value); and the existing `actions` and `functions` refusals.
+
+## FROM → TO
+
+| you wrote | write instead |
+|:--|:--|
+| `pages: [{ name: 'home', … }, { name: 'home', … }]` (any of the 24 name-keyed collections) | one entry per name: rename one (`home_admin`) and every reference that meant it, or merge the two into one entry |
+| `emailTemplates: [{ name: 'acme.welcome', … }, { name: 'acme.welcome', locale: 'en-US', … }]` | one entry per name and locale: give the second its own `locale` (`zh-CN`), or merge the two |
+| `datasources: [{ name: 'ext', config: a }, { name: 'ext', config: b }]` | one datasource per name — the driver used to connect `a` while the metadata described `b` |
+| `hooks: [{ name: 'audit', object: 'a', … }, { name: 'audit', object: 'b', … }]` | one hook with `object: ['a', 'b']`, or two hooks with two names |
+| `apis: [{ name: 'feed', path: '/api/v1/apps/x/a' }, { name: 'feed', path: '/api/v1/apps/x/b' }]` | give each endpoint its own name |
+| `views: [defineView({ object: 'task', list }), defineView({ object: 'task', form })]` | one container per object: `defineView({ object: 'task', list, form })` (named views go in `listViews` / `formViews`) |
+| `objectExtensions: [{ extend: 'task', fields: { a } }, { extend: 'task', fields: { b } }]` | one extension per target: `{ extend: 'task', fields: { a, b } }` |
+
+**The one-line fix: give each entry of a collection its own identity, or merge the duplicates into one entry.**
+
+No D2 conversion rewrites it: which entry keeps the identity, and what the other one becomes, is the author's call. Its D3 record is the semantic entry `stack-collection-duplicate-entry-refused` (protocol 18).
+
+**`@objectstack/metadata`.** `deriveViewContainerObject` — the "which object does a `views` container bind to" derivation the registrars file containers by — moved into `@objectstack/spec` (exported from its root and `./ui`), because the stack contract now judges the same slot. `@objectstack/metadata` re-exports that one declaration under the same name, from its root and from `@objectstack/metadata/view-container`; behaviour is unchanged. That subpath used to import nothing and now loads the `@objectstack/spec` root entry, which every in-repo importer of it already loads.
+
+**Who is affected, measured.** The four example apps (`examples/app-crm`, `app-todo`, `app-showcase`, `app-multi-package`) carry no duplicate under these identities. Deployed metadata and other repositories were not measured.

.github/workflows/lint.yml

@@ -7019,8 +7019,76 @@ jobs:
       # comment): the nested group dirs and apps/ (docs) need their own globs.
       # Examples and the downstream contract keep their dedicated steps below —
       # they are distinct gates, not bulk coverage.
+      #
+      # ── WHICH PACKAGES, PER EVENT (#23017) ──
+      # The three filters are the UNIVERSE. `schedule`, `push`,
+      # `workflow_dispatch` and any other event type-check all of it (the full
+      # battery, #22998). `pull_request` / `merge_group` type-check what their
+      # diff affects, plus dependents, through ci.yml Test Core's selector
+      # (same diff base, same cross-package test union, same fall-back to the
+      # full list), intersected with the universe. Not the cache alone: the
+      # restore above already reaches main's seed, but nearly every package
+      # depends on spec, so one spec commit between seed and run moves nearly
+      # every typecheck hash (PR run 38239402273 replayed 138 of 139 tasks; its
+      # merge group 38242582445, 0 of 74 typecheck tasks).
+      # ⛔ A changed repo-root file (Markdown excepted), or a `scripts/` file a
+      # package.json script runs, means the whole universe: `turbo ls
+      # --affected` selects ZERO packages for a root package.json,
+      # pnpm-workspace.yaml, .npmrc or root-importer lockfile change (turbo
+      # 2.11.5). ⛔ An empty selection exits here: `turbo run typecheck` with no
+      # `--filter` runs the whole workspace. Selection decides which packages
+      # run; the package-local turbo cache still decides which execute.
       - name: Type check workspace packages
-        run: pnpm exec turbo run typecheck --filter='./packages/*' --filter='./packages/*/*' --filter='./apps/*'
+        env:
+          OS_SHARD_EVENT_NAME: ${{ github.event_name }}
+          OS_SHARD_PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+          OS_SHARD_PR_PINNED_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          OS_SHARD_MERGE_GROUP_BASE_SHA: ${{ github.event.merge_group.base_sha }}
+        run: |
+          set -euo pipefail
+          UNIVERSE=(--filter='./packages/*' --filter='./packages/*/*' --filter='./apps/*')
+          WHOLE=''
+          case "$OS_SHARD_EVENT_NAME" in
+            pull_request|merge_group) ;;
+            *) WHOLE="the '$OS_SHARD_EVENT_NAME' event carries the full battery" ;;
+          esac
+          if [ -z "$WHOLE" ]; then
+            rm -f "$RUNNER_TEMP/turbo-ls.json" "$RUNNER_TEMP/changed-files.txt"
+            bash scripts/ci/select-shard-packages.sh
+            if [ ! -s "$RUNNER_TEMP/changed-files.txt" ]; then
+              WHOLE='the selector left no changed-file list (missing or empty), so the root-level rule cannot be judged'
+            else
+              { git grep -h -o -E '(\.\./)+scripts/[A-Za-z0-9._/-]+' -- \
+                  'packages/*/package.json' 'packages/*/*/package.json' 'apps/*/package.json' || true; } \
+                | sed -E 's#^(\.\./)+##' | sort -u > "$RUNNER_TEMP/package-script-tools.txt"
+              ROOT_FILE=$(grep -m1 -v -e / -e '\.md$' "$RUNNER_TEMP/changed-files.txt" || true)
+              TOOL_FILE=$(grep -m1 -Fx -f "$RUNNER_TEMP/package-script-tools.txt" "$RUNNER_TEMP/changed-files.txt" || true)
+              if [ -n "$ROOT_FILE" ]; then
+                WHOLE="root-level change: $ROOT_FILE"
+              elif [ -n "$TOOL_FILE" ]; then
+                WHOLE="a script the packages' own package.json scripts run changed: $TOOL_FILE"
+              fi
+            fi
+          fi
+          if [ -n "$WHOLE" ]; then
+            echo "Type-checking the whole workspace -- $WHOLE."
+            pnpm exec turbo run typecheck "${UNIVERSE[@]}"
+            exit 0
+          fi
+          pnpm exec turbo ls "${UNIVERSE[@]}" --output=json > "$RUNNER_TEMP/typecheck-universe.json"
+          jq -r --slurpfile sel "$RUNNER_TEMP/turbo-ls.json" \
+            '($sel[0].packages.items | map(.name)) as $s | .packages.items[].name | select(. as $n | any($s[]; . == $n))' \
+            "$RUNNER_TEMP/typecheck-universe.json" > "$RUNNER_TEMP/typecheck-selected.txt"
+          mapfile -t SELECTED < "$RUNNER_TEMP/typecheck-selected.txt"
+          if [ "${#SELECTED[@]}" -eq 0 ]; then
+            echo "No workspace package is affected by this diff -- nothing to type-check."
+            exit 0
+          fi
+          echo "Type-checking ${#SELECTED[@]} affected package(s) of the universe:"
+          printf '  %s\n' "${SELECTED[@]}"
+          FILTERS=()
+          for P in "${SELECTED[@]}"; do FILTERS+=("--filter=$P"); done
+          pnpm exec turbo run typecheck "${FILTERS[@]}"
 
       # Seed the shared Turbo cache from main only (see the restore step above).
       #

content/docs/api/metadata-api.mdx

@@ -127,6 +127,19 @@ Uninstall a package. Under a `group` or `isolated` tenancy posture, a package
 holding positions or permission sets is the platform operator's to delete: any
 other caller is refused `403 PERMISSION_DENIED` (ADR-0131 D3).
 
+The package's other write verbs follow the same rule under a wall, judged by
+the items each one acts on:
+- `POST /packages/:id/publish-drafts`, `POST /packages/:id/discard-drafts` and
+  `POST /packages/:id/revert`, by the package's pending drafts;
+- `POST /packages/:id/rollback`, by the commits it would undo;
+- `POST /packages/:id/commits/:commitId/revert`, by that commit's own items,
+  whatever package the URL names;
+- `POST /packages/:id/duplicate`, by the source's published items it copies;
+- `POST /packages/:id/adopt-orphans`, by the environment's orphaned rows.
+
+When those items include a position, a permission set or a capability, only the platform
+operator may run the verb.
+
 ### `PATCH /packages/:id/enable`
 
 Enable a disabled package.