Merge origin/main into claude/issue-8278-rest-published-overlay

Author: claude

.changeset/lucky-schools-smash.md

@@ -0,0 +1,48 @@
+---
+'@objectstack/service-package': minor
+'@objectstack/rest': patch
+---
+
+Package publish: a driver fault is answered as a server error, and its driver text no longer reaches the caller
+
+`POST /api/v1/packages/publish` answered **`400 PACKAGE_PUBLISH_FAILED`** when the
+`INSERT INTO sys_packages` statement itself failed, carrying the driver's own message as
+the caller-facing text. Measured on a real SQLite engine, that was literally:
+
+```
+400 {"success":false,"error":{"code":"PACKAGE_PUBLISH_FAILED",
+     "message":"no such table: sys_packages"}}
+400 {"success":false,"error":{"code":"PACKAGE_PUBLISH_FAILED",
+     "message":"NOT NULL constraint failed: sys_packages.tenant_ref"}}
+```
+
+Two defects in one line. The **status** was a client error for a fault the client had no
+part in — the mirror of the mislabelling fixed for the throw path, and it hid a real
+server fault from every dashboard that buckets by status. The **message** was raw driver
+text: a constraint dump naming physical tables and columns.
+
+Fixed at the producer, which is the only place that closes it. A 5xx message withhold
+already exists at this door, but it is applied when an error is *thrown*, and this
+failure was *returned* — so it never met the withhold at any status. Reclassifying alone
+would have moved the driver line from a 400 to a 500 and left it on the wire; that is
+measured, and it stays true against the widened leak predicate that now recognises this
+phrasing, because nothing on the returned path ever consults one.
+
+Now the driver's text goes to the log and nowhere else — it was already logged, so nothing
+an operator sees changes — and the caller gets a stable sentence that names what happened
+without quoting the driver.
+
+**Caller-facing 4xx messages are unchanged.** A missing manifest, an invalid manifest, and
+any coded refusal thrown from below `publish` all keep their own status, code and
+self-correcting message — a `409 DESTRUCTIVE_CHANGE` is still a 409.
+
+**BREAKING — the `PackageService.publish` return shape.** A bare `error` string could not
+say which side was at fault, so the door had one status for both and picked the wrong one.
+`publish` now reports a broken write as `{ success: false, driverFault: { message } }`;
+the `error` field is removed. If you only *call* `publish`, read
+`result.driverFault?.message` where you read `result.error`. If you *implement*
+`PackageService`, report a broken write through `driverFault` with a message safe to show
+a caller, and **throw** — rather than return — a refusal that carries its own `status`, so
+the door answers it with that status and code.
+
+<!-- adr-0087: not-required (no-migration-prescription) This change retires no authorable key and adds none. `PackageService` is a runtime TypeScript service interface in `packages/services/service-package`; it has no Zod schema, no `packages/spec` declaration, no metadata type and no stored representation. `packages/spec` is untouched by this PR. Nothing exists for `objectstack migrate meta` to rewrite, because nothing an author writes and nothing persisted in `sys_metadata` or `sys_packages` changes shape — the wire envelope is unchanged too (still ADR-0112 `{ success, error: { code, message } }`), and only the STATUS a driver fault selects and the TEXT the producer puts in it move. Nor is there a FROM/TO rule a ledger entry could state: the ledger's subject is metadata, and the only readers affected here are TypeScript callers of one in-process service — measured as three in-repo consumers (`@objectstack/rest`, `@objectstack/runtime`, `@objectstack/cli`), of which exactly one, `packages/rest/src/package-routes.ts`, reads the changed field. The channel that reaches an affected reader is strictly more precise than any ledger line: the compiler itself. Reading the removed field is a hard type error at the call site — verified by reinstating it, which fails as `error TS2339: Property 'error' does not exist on type 'PackagePublishResult'` — so no consumer can carry this change silently, and this changeset's CHANGELOG text carries the one-line repair for the reader who hits it. -->

.github/workflows/adr-merge-approval.yml

@@ -1,17 +1,28 @@
 name: ADR Merge Approval
 
-# Machine enforcement of the #6741 ruling (maintainer, verbatim):
-# 「adr 只能由维护者自己确认,人工合并,ai 不得擅自合并。」
+# Machine enforcement of the 2026-08-12 ruling (maintainer, verbatim):
+# 「门禁改成只要求「APPROVED review 存在」」/「不要指定具体的人」
 #
-# A PR whose diff touches docs/adr/** must carry an APPROVED review from the
-# maintainer's OWN account before it is mergeable; approvals from the shared
-# bot/agent identities deliberately do not count. Prose enforcement was
-# measured insufficient the day the ruling landed — two different AI-operated
-# seats merged docs/adr/** PRs within the following hour (#6671, #6732; the
-# full record and both replays live in scripts/check-adr-merge-approval.mjs
-# and its --self-test). Drafting ADR PRs stays open to every seat; only the
-# merge is reserved, and the maintainer's own approval + merge is the intended
-# zero-extra-friction green path.
+# A PR whose diff touches docs/adr/** must carry an APPROVED review before it
+# is mergeable. The gate does NOT check WHO approved: any account with review
+# rights on this repo — including an AI seat — satisfies it, which is the
+# accepted cost of the ruling and is stated in full in the two-clause table at
+# the head of scripts/check-adr-merge-approval.mjs. The approval must be
+# current: a later CHANGES_REQUESTED or DISMISSED revokes it.
+#
+# This supersedes the account-identity rule this workflow used to describe
+# (#6741 「adr 只能由维护者自己确认,人工合并,ai 不得擅自合并。」, enforced by
+# matching the maintainer's numeric account id). That proxy became
+# unsatisfiable once cloud sessions began authoring PRs under the maintainer's
+# own account, since GitHub forbids self-approval (#8161). #6741's two halves
+# survive as convention, not as anything this workflow can measure.
+#
+# Prose enforcement was measured insufficient the day #6741 landed — two
+# different AI-operated seats merged docs/adr/** PRs within the following hour
+# (#6671, #6732; the full record and both replays live in
+# scripts/check-adr-merge-approval.mjs and its --self-test). Both had ZERO
+# reviews of any kind, so both stay red under the widened rule too. Drafting
+# ADR PRs stays open to every seat; only the merge is gated.
 #
 # Deliberately NO `paths` filter, on either trigger — the same choice
 # changeset-presence.yml made in objectui (#3769) and for the same reason
@@ -30,9 +41,11 @@ on:
   pull_request:
     branches: [main]
   # An approval does not fire `pull_request`, so without this trigger the
-  # failed check would sit red after the maintainer approves until someone
-  # re-ran it by hand. Subscribing to reviews makes the maintainer's approval
-  # itself re-run the gate — the zero-friction green path the card requires.
+  # failed check would sit red after the approval lands until someone re-ran
+  # it by hand. Subscribing to reviews makes the approval itself re-run the
+  # gate — the zero-friction green path the card requires. `pull-requests:
+  # read` below covers listing reviews from ANY account, so the widened rule
+  # needs no extra permission or token scope.
   # (On non-ADR PRs a review re-runs the cheap clean path; harmless.)
   pull_request_review:
     types: [submitted, edited, dismissed]
@@ -55,6 +68,14 @@ permissions:
 
 jobs:
   adr-merge-approval:
+    # ⛔ Do NOT rename this job. Its name IS the required status-context string
+    # in the `main` ruleset (#7022), and it is registered under that exact
+    # spelling in scripts/check-required-contexts.mjs — renaming it here alone
+    # leaves the ruleset waiting for a context that never reports, which hangs
+    # the merge queue until the 60-minute timeout. The word "maintainer" now
+    # over-claims (see this file's header: any approver counts); correcting it
+    # is a settings action nobody in CI can perform, so it is tracked as
+    # follow-up work rather than done here.
     name: ADR maintainer approval
     runs-on: ubuntu-latest
     timeout-minutes: 5
@@ -77,7 +98,7 @@ jobs:
       # install, no build. The self-test runs first (repo convention), then
       # the gate. GITHUB_TOKEN is only read on the gated path (a docs/adr/**
       # diff needs the PR's review list); the clean path does zero lookups.
-      - name: Require the maintainer's own approval on docs/adr/** diffs
+      - name: Require an APPROVED review on docs/adr/** diffs
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: node scripts/check-adr-merge-approval.mjs --self-test && node scripts/check-adr-merge-approval.mjs

docs/adr/0001-withdrawn-metadata-service-architecture.md

@@ -0,0 +1,149 @@
+# ADR-0001: Withdrawn — this number is retired and must not be reused
+
+**Status**: **Withdrawn (2026-02-11)**. This file is a *tombstone*, not a decision: nothing in it is in force, and the number must never be reassigned.
+**Deciders**: ObjectStack Protocol Architects (recorded retroactively — see [How this differs from ADR-0107](#how-this-differs-from-adr-0107))
+**The record that held this number**: *"Metadata Service Architecture"* — `docs/adr/0001-metadata-service-architecture.md`, Status *Accepted (2026-02-10)*
+**Landed by**: `908d95c82`, 2026-02-10 09:14 UTC
+**Deleted by**: `9da8e3e72`, 2026-02-11 23:35 +0800, about thirty hours later — a 37-path documentation sweep, not an ADR decision
+**Tracking**: [#7329](https://github.com/objectstack-ai/objectstack/issues/7329) (the citation-resolution work that named this case), [#7866](https://github.com/objectstack-ai/objectstack/issues/7866) (this tombstone), [#6634](https://github.com/objectstack-ai/objectstack/issues/6634) (the squat failure mode both are written against)
+**Consumers**: none. No code is governed by this number, and none may be — see [Do not anchor to this number](#do-not-anchor-to-this-number).
+
+---
+
+## TL;DR
+
+A real record occupied ADR-0001 on `main` for about thirty hours in February 2026 and
+was then deleted. Unlike [ADR-0107](./0107-withdrawn-hook-body-write-set-static-gap.md),
+it was **not withdrawn on the merits** — it was swept away as collateral in a bulk
+documentation cleanup that took the entire `docs/adr/` registry with it, including its
+`README.md` and the ADR-0002 of that era.
+
+This file exists so the number resolves to that explanation instead of to nothing, and so
+it is never handed to an unrelated decision. Reassigning it would retroactively re-point
+every historical "ADR-0001" at a document its author never meant — the squat failure mode
+[#6634](https://github.com/objectstack-ai/objectstack/issues/6634) was filed for, where
+one number had silently accumulated 77 citations it did not resolve.
+
+**A new record takes the next free number. Not this one.**
+
+## What happened
+
+| When | What | Evidence |
+|---|---|---|
+| 2026-02-10 09:14 UTC | `docs/adr/0001-metadata-service-architecture.md` written and merged, Status *Accepted*, authored by an automated agent | `908d95c82` |
+| 2026-02-11 23:35 +0800 | Deleted, together with `docs/adr/0002-database-driven-metadata-storage.md` and `docs/adr/README.md`, inside a 37-path docs sweep | `9da8e3e72` |
+| 2026-08-08 | The bare number is grandfathered onto `check-adr-anchors`'s citation allowlist, pending this tombstone | [#6634](https://github.com/objectstack-ai/objectstack/issues/6634) |
+| 2026-08-11 | [PR #7838](https://github.com/objectstack-ai/objectstack/pull/7838) makes a tombstone refuse *anchors* while still resolving *citations*, and leaves this number open because it needs a file under `docs/adr/` | [#7329](https://github.com/objectstack-ai/objectstack/issues/7329) |
+
+The deleting commit's subject is *"feat(docs): add comprehensive analysis of Permission
+Protocol with AI-enhanced security controls and RLS implementation"*; its body is empty
+and it names no ADR. Alongside the registry it removed the whole `docs/METADATA_*`
+documentation family and the `examples/metadata-objectql` package. **No reasoning for
+retiring the decision was recorded anywhere**, which is the substantive difference from
+ADR-0107 and the reason this tombstone reconstructs the record from the tree rather than
+quoting a withdrawal.
+
+## Do not resurrect it
+
+Independently of how it was deleted, the record's substance is now **contradicted by
+shipped code**, so restoring the text would plant a false statement in the decision log.
+
+Its selected option was a **hybrid dual-provider** architecture: *both* `@objectstack/objectql`
+and `@objectstack/metadata` may provide the `metadata` service, MetadataPlugin taking
+precedence when loaded and **ObjectQL registering itself as the fallback provider** when
+it is not. That fallback is exactly what the code stopped doing:
+
+- **MetadataPlugin is the sole provider** of the `metadata` service — the one
+  `registerService('metadata', …)` in the tree is
+  [`packages/metadata/src/plugin.ts`](../../packages/metadata/src/plugin.ts).
+- **ObjectQL is a consumer, never a provider.**
+  [`packages/objectql/src/plugin.ts`](../../packages/objectql/src/plugin.ts) registers
+  `objectql`, `data`, `manifest` and `lifecycle` — and no longer `metadata`. It reads the
+  `metadata` service and degrades to its own internal registry when none is present,
+  which is not the same thing as claiming the slot.
+- **The shared-interface principle survived, as a spec contract**: `IMetadataService` in
+  [`packages/spec/src/contracts/metadata-service.ts`](../../packages/spec/src/contracts/metadata-service.ts).
+
+The live account of that surface is the "Metadata service architecture" section of
+[`ARCHITECTURE.md`](../../ARCHITECTURE.md). Read that, never this file, for what is true
+today. The withdrawn text is recoverable in full at
+`git show 908d95c82:docs/adr/0001-metadata-service-architecture.md` and is deliberately
+kept in history rather than reprinted here — a withdrawn record reprinted inside its own
+tombstone reads as a record.
+
+Note that the single-provider architecture which replaced it **has no ADR record of its
+own**. That gap is real and is not closed by this file; re-homing it is a maintainer call.
+
+## What ADR-0002 actually cites
+
+Recorded because it is the first thing a reader arriving from ADR-0002 will want, and
+because it was mis-stated in `check-adr-anchors.mjs` until this tombstone was written.
+
+[`0002-environment-database-isolation.md`](./0002-environment-database-isolation.md) says,
+of a rejected alternative: *"One global DB + tenant column. Was never on the table —
+already discarded in v3.4's ADR-0001."* That is **not** a reference to the record above.
+The record that held this number decided how the `metadata` *service* is registered and
+says nothing about tenancy or database topology.
+
+Two distinct things carry the string "ADR-0001" in this repository's past, and only one
+of them was ever a file here:
+
+- **The v3.4-era "ADR-0001" ADR-0002 is pointing at.** Nothing matching `*0001-*` was ever
+  added under any path, on any branch, other than the metadata-service record — see
+  [Archaeology](#archaeology). Today's ADR-0002 is itself dated 2026-04-19 and supersedes
+  the v3.4/v4.0 per-organization database model, so its "v3.4's ADR-0001" is a reference to
+  a pre-registry document that this repository has never contained.
+- **`docs/adr/0001-metadata-service-architecture.md`**, the record this tombstone retires.
+
+The citation is therefore historical narration rather than a pointer into `docs/adr/`, and
+this file is what it now resolves to. Correcting ADR-0002's wording is an edit to an
+accepted record and is deliberately not made here.
+
+## Do not anchor to this number
+
+`scripts/check-adr-anchors.mjs` requires every `ADR-NNNN` cited in a tracked file to name a
+record under `docs/adr/`. This tombstone satisfies that check — deliberately, because the
+citations below are legitimate references to a deleted record. It is **not** a licence to
+cite ADR-0001 as governing anything: an anchor entry must state the invariant its ADR
+decided, and this number decides nothing today.
+
+The citations that exist are all discussion of the deletion itself:
+
+- [`ARCHITECTURE.md`](../../ARCHITECTURE.md) — names the deleted path as plain text and
+  states the current single-provider architecture in its place;
+- [`0002-environment-database-isolation.md`](./0002-environment-database-isolation.md) —
+  the v3.4 reference dissected above;
+- `scripts/check-adr-anchors.mjs` — the gate, describing this case.
+
+## Archaeology
+
+Recorded so the next reader does not repeat it. Run against full history with the clone
+**unshallowed** — a shallow clone silently answers "never existed", and the default clone
+in this project's agent containers is 50 commits deep:
+
+```bash
+git fetch --unshallow
+git log --all --diff-filter=AD -- 'docs/adr/0001*'   # -> exactly 2 commits, both above
+git log --all --diff-filter=AD -- '*0001-*'          # -> the same 2 commits, any path
+git log --all --oneline -S'ADR-0001'                 # -> 10 commits, all accounted for
+```
+
+**Nothing else ever claimed this number**, on any branch, at any time: the second query
+widens the first from `docs/adr/` to the whole tree and returns the same two commits, so
+there is no second era of "ADR-0001" as a file and no lost content beyond the record named
+above.
+
+## How this differs from ADR-0107
+
+Both are tombstones and both are unreusable, but the two cases are not the same and the
+distinction is worth keeping:
+
+| | ADR-0107 | ADR-0001 |
+|---|---|---|
+| Why it left | Owner decision, reasoning stated in the withdrawing commit | Collateral in an unrelated 37-path docs sweep; no reasoning recorded |
+| Lifetime | Nine hours | About thirty hours |
+| Deciders line | The withdrawal was itself the decision | Reconstructed from the tree in 2026-08; nobody decided the number should retire at the time |
+| Why not resurrect | Substance reversed by later shipped code | Same — the fallback-provider half is contradicted by the code today |
+
+The shared conclusion is the one that matters: an ADR number that has ever named a record
+does not become free again by that record's removal, however the removal happened.