Merge remote-tracking branch 'origin/main' into claude/issue-14577-suggest-copies-consolidation

Author: claude

.changeset/registry-namespace-conflict-refusal-envelope.md

@@ -0,0 +1,19 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/runtime": patch
+---
+
+fix(objectql): the ADR-0048 install-time namespace gate's refusal carries an ADR-0112 envelope, so `POST /packages` answers 422 instead of 500 (#14474)
+
+`NamespaceConflictError` — raised by `SchemaRegistry.installPackage` when a package's `manifest.namespace` is already owned by an installed package that is not a co-owner of it (ADR-0130 D1) — carried `namespace` / `existingPackageId` / `incomingPackageId` but no `code` and no `status`. It now carries `code: 'NAMESPACE_CONFLICT'` and `status: 422`, the same three-field envelope shape as its sibling `ArtifactObjectNameConflictError` in the same file. The message text is byte-for-byte unchanged: the prose was already correct and specific, and this change adds fields rather than rewriting a sentence.
+
+Why it matters, measured rather than read: unlike its three install-time siblings, this refusal is reachable from a wire. `POST /api/v1/packages` calls `installPackage` with no artifact scope — which this gate, unlike the ADR-0130 D3 object-name one, does not need — and the domain's terminal catch answers `errorFromThrown(e, 500)`. `resolveThrownHttpError` reads `.status` / `.code` off the throw and falls to the caller's fallback when it finds neither. Observed on a booted stack, two installs declaring one namespace:
+
+- before: `500` with `error.code: INTERNAL_ERROR`, carrying the refusal's prose
+- after: `422` with `error.code: VALIDATION_ERROR` and `error.declaredCode: NAMESPACE_CONFLICT`
+
+A refusal the platform decided is a client-side conflict was telling operators the server had broken, which invites a retry instead of a rename.
+
+Not narrowed, not widened: no accept-set changes, no export changes, and no ledger registration. `NAMESPACE_CONFLICT` is not an `ErrorCode` member, so the door's narrowing demotes it off `error.code` onto the wire's open `declaredCode` sibling and `error.code` stays the closed member 422 derives.
+
+`@objectstack/runtime` carries the classification row for the new code in the dispatcher error-code vocabulary (verdict `pending-registration`, door `dispatcher` — the measured verdict, not the expected one). That row is the input to a ledger-registration batch in the `packages/spec` lane; registering the code is what ratchets the row back out and what would let `error.code` carry the semantic spelling.

.github/workflows/merge-queue-triage.yml

@@ -550,13 +550,118 @@ jobs:
             };
 
             const ANCHOR_LABEL = 'finding';
+            // The anchor's IDENTITY label, and the only label the lookup keys on.
+            // `finding` is a TRIAGE-STATE label: first-touch grading takes it off by
+            // definition, so a lookup keyed on `finding` stops seeing an anchor the
+            // moment a human triages it and files a fresh one on the next ejection.
+            // This label is the machine's, is never graded off, and is what keeps
+            // the anchor findable for the rest of its life, open or closed.
+            const ANCHOR_IDENTITY_LABEL = 'queue-flake-anchor';
             const MAX_ANCHOR_PAGES = 3;
             const anchorNotes = [];
             for (const a of aggregated.slice(0, 3)) {
               const anchorMarker = `<!-- queue-signature-anchor:${a.key} -->`;
               // Stable across refreshes — the victim count lives in the body, so
               // a growing count cannot make the anchor unfindable by title.
               const title = `Queue-flake anchor: ${a.key}`;
+
+              // ── Anchor lookup ─────────────────────────────────────────────
+              // The anchor's identity is the FILE KEY, carried by the body marker
+              // with the exact title as a second way in (a body is the one channel
+              // GitHub is known to rewrite). It is NOT the `finding` label and NOT
+              // `open`:
+              //   - `finding` comes off the moment the anchor is graded, which is
+              //     what first-touch grading MEANS. Keying on it made a properly
+              //     triaged anchor invisible and turned every further ejection into
+              //     a new anchor.
+              //   - a CLOSED anchor is still evidence about this key: closed as a
+              //     duplicate says the conversation moved; closed on its own merits
+              //     says the next ejection is a REGRESSION, not a continuation.
+              const isThisAnchor = (i) => !i.pull_request
+                && (String(i.body ?? '').includes(anchorMarker) || i.title === title);
+              const labelNames = (i) => (i.labels ?? []).map((l) => (typeof l === 'string' ? l : l?.name));
+
+              // The passes, in order. `firstMatchWins` says whether a pass may stop
+              // at its first hit: the identity pass may NOT, because the resolution
+              // order below needs this key's CLOSED anchors as well as its open one.
+              // `adopts` marks the transitional pass — a bounded scan of OPEN issues
+              // that finds anchors filed before the identity label existed (a graded
+              // one carries neither label) and puts the identity label on them, so
+              // the first pass owns them from the next ejection on.
+              const ANCHOR_QUERIES = [
+                { state: 'all', labels: ANCHOR_IDENTITY_LABEL, firstMatchWins: false, adopts: false },
+                { state: 'open', firstMatchWins: true, adopts: true },
+              ];
+
+              const candidates = [];
+              let adopted = null;
+              let scanComplete = true;
+              let refusal = null;
+              for (const [qi, q] of ANCHOR_QUERIES.entries()) {
+                // A later pass is skipped only once an OPEN anchor is in hand.
+                // Closed candidates are not enough to stop: a key can have a
+                // labelled closed duplicate and an UNLABELLED open survivor at the
+                // same time — that is exactly what a half-migrated key looks like
+                // — and stopping there would read the survivor as absent.
+                if (candidates.some((i) => i.state !== 'closed')) break;
+                const { firstMatchWins = false, adopts = false, ...params } = q;
+                const found = [];
+                let complete = true;
+                try {
+                  for (let p = 1; p <= MAX_ANCHOR_PAGES; p++) {
+                    const res = await github.rest.issues.listForRepo({
+                      owner, repo, ...params,
+                      sort: 'created', direction: 'desc', per_page: 100, page: p,
+                    });
+                    found.push(...res.data.filter(isThisAnchor));
+                    if ((firstMatchWins && found.length > 0) || res.data.length < 100) break;
+                    if (p === MAX_ANCHOR_PAGES) complete = false;
+                  }
+                } catch (error) {
+                  complete = false;
+                  refusal = describe(error);
+                }
+                // Completeness is the IDENTITY pass's argument — it is the bounded,
+                // label-keyed one. A truncated adoption pass is a missed migration,
+                // not an unestablished absence, and must not block a first anchor.
+                if (qi === 0) scanComplete = complete;
+                if (adopts && found.length > 0) adopted = found[0];
+                for (const i of found) {
+                  if (!candidates.some((c) => c.number === i.number)) candidates.push(i);
+                }
+              }
+
+              if (adopted && !labelNames(adopted).includes(ANCHOR_IDENTITY_LABEL)) {
+                try {
+                  await github.rest.issues.addLabels({
+                    owner, repo, issue_number: adopted.number, labels: [ANCHOR_IDENTITY_LABEL],
+                  });
+                } catch (error) {
+                  core.warning(`Could not put the identity label on the existing anchor #${adopted.number} for ${a.key} (${describe(error)}); it is refreshed anyway and adoption retries next run.`,
+                    { title: 'Queue-signature anchor not adopted' });
+                }
+              }
+
+              // Resolution order. OPEN beats closed, and the OLDEST open anchor
+              // beats a newer one: that is the issue the duplicates were closed
+              // against.
+              const openAnchors = candidates.filter((i) => i.state !== 'closed')
+                .sort((x, y) => x.number - y.number);
+              const closedAnchors = candidates.filter((i) => i.state === 'closed')
+                .sort((x, y) => y.number - x.number);
+              const existing = openAnchors[0] ?? null;
+              const closedAsDuplicate = !existing && closedAnchors[0]?.state_reason === 'duplicate'
+                ? closedAnchors[0]
+                : null;
+              // A closed anchor that was NOT closed as a duplicate is a RESOLVED
+              // one: the flake was answered once and this key is ejecting PRs
+              // again. A new anchor is legitimate there, but it has to say which
+              // issue it regressed from or the previous answer is lost.
+              const resolvedBefore = closedAnchors.find((i) => i.state_reason !== 'duplicate') ?? null;
+              const priorAnchor = resolvedBefore && (!existing || existing.number > resolvedBefore.number)
+                ? resolvedBefore
+                : null;
+
               const prRows = [...a.prs.entries()].sort((x, y) => x[0] - y[0]).map(([pr, runs]) => {
                 const s = a.stackOf.get(pr);
                 const cell = !s || s.size < 2
@@ -572,6 +677,13 @@ jobs:
                 'that conversation; it is refreshed by the merge-queue-triage workflow on every',
                 'further ejection.',
                 '',
+                ...(priorAnchor
+                  ? [
+                    `⚠️ 同签名的上一个汇总 issue #${priorAnchor.number} 已经关闭（不是作为重复关闭的），`,
+                    '之后这个文件又开始弹出 PR ⇒ 这是一次**回归**，上一轮的结论在那张 issue 里。',
+                    '',
+                  ]
+                  : []),
                 '| PR | stack | queue build |',
                 '|---|---|---|',
                 ...prRows,
@@ -616,29 +728,6 @@ jobs:
                 anchorMarker,
               ].join('\n');
 
-              let existing = null;
-              let scanComplete = true;
-              let refusal = null;
-              try {
-                for (let p = 1; p <= MAX_ANCHOR_PAGES; p++) {
-                  const res = await github.rest.issues.listForRepo({
-                    owner, repo, state: 'open', labels: ANCHOR_LABEL,
-                    sort: 'created', direction: 'desc', per_page: 100, page: p,
-                  });
-                  // Identity is the body marker; the exact title is a second
-                  // way in, because a body is the one channel GitHub is known
-                  // to rewrite and an anchor that cannot be found is an anchor
-                  // that gets duplicated.
-                  existing = res.data.find((i) => !i.pull_request
-                    && (String(i.body ?? '').includes(anchorMarker) || i.title === title)) ?? null;
-                  if (existing || res.data.length < 100) break;
-                  if (p === MAX_ANCHOR_PAGES) scanComplete = false;
-                }
-              } catch (error) {
-                scanComplete = false;
-                refusal = describe(error);
-              }
-
               if (existing) {
                 try {
                   await github.rest.issues.update({
@@ -664,11 +753,25 @@ jobs:
                 continue;
               }
 
+              if (closedAsDuplicate) {
+                // The newest anchor for this key was closed AS A DUPLICATE and no
+                // open anchor is left. Filing a fresh one here is exactly what
+                // feeds the loop — it would be closed as a duplicate in turn.
+                // GitHub's issue payload does not carry a duplicate's TARGET (only
+                // `state_reason: duplicate`), so the canonical cannot be followed
+                // from here; this says where the conversation was sent instead of
+                // guessing at a new home for it.
+                anchorNotes.push(`- \`${a.key}\` — ${victimPhrase(a)}。⚠️ 同签名的汇总 issue #${closedAsDuplicate.number} 已作为**重复**关闭，且没有仍然打开的同签名汇总 issue ⇒ 本次不新建（新建只会再被判重）。请到它指向的那张 issue 上谈，或重开 #${closedAsDuplicate.number}。`);
+                core.warning(`The newest anchor for ${a.key} (#${closedAsDuplicate.number}) was closed as a duplicate and no open anchor is left; not filing another one.`,
+                  { title: 'Queue-signature anchor not created' });
+                continue;
+              }
+
               try {
                 const created = await github.rest.issues.create({
-                  owner, repo, title, body, labels: [ANCHOR_LABEL],
+                  owner, repo, title, body, labels: [ANCHOR_LABEL, ANCHOR_IDENTITY_LABEL],
                 });
-                anchorNotes.push(`- \`${a.key}\` — ${victimPhrase(a)}。汇总 issue：#${created.data.number}（新建）`);
+                anchorNotes.push(`- \`${a.key}\` — ${victimPhrase(a)}。汇总 issue：#${created.data.number}（${priorAnchor ? `新建，回归自已关闭的 #${priorAnchor.number}` : '新建'}）`);
               } catch (error) {
                 anchorNotes.push(`- \`${a.key}\` — ${victimPhrase(a)}。⚠️ 汇总 issue 新建失败（${describe(error)}），上面的名单就是全部事实。`);
                 core.warning(`Could not file the anchor issue for ${a.key} (${describe(error)}).`,

packages/objectql/src/registry-artifact-co-ownership.test.ts

@@ -199,6 +199,13 @@ describe('ADR-0130 D1 + D3 — the gate relaxation and the object-name check are
     expect(err.namespace).toBe('crm');
     expect(err.existingPackageId).toBe('com.acme.crm');
     expect(err.incomingPackageId).toBe('com.acme.crm.billing');
+    // [#14474] The ADR-0112 envelope, asserted the same way this file already
+    // asserts its D3 sibling's (`caught?.code` / `caught?.status` below). The
+    // instance check above is NOT a substitute: it stayed green through every
+    // year this class carried no `code` and no `status` at all, which is
+    // precisely how the refusal reached `POST /api/v1/packages` as a 500.
+    expect((refused as Envelope).code).toBe('NAMESPACE_CONFLICT');
+    expect((refused as Envelope).status).toBe(422);
     // Nothing half-applied: the refused package is not recorded.
     expect(engineOf(kernel).registry.getPackage('com.acme.crm.billing')).toBeUndefined();
   });

packages/objectql/src/registry-namespace-install-gate.test.ts

@@ -56,6 +56,29 @@ describe('SchemaRegistry — namespace install gate (ADR-0048 Phase 1)', () => {
     expect(registry.getNamespaceOwners('crm')).toEqual(['com.acme.crm']);
   });
 
+  it('carries the ADR-0112 envelope: code NAMESPACE_CONFLICT + status 422', () => {
+    // [#14474] The assertion the instance checks above cannot make, and the
+    // reason this defect survived: `toThrowError(NamespaceConflictError)` and
+    // `toBeInstanceOf(NamespaceConflictError)` are TRUE of a class carrying no
+    // `code` and no `status`, so both stayed green while `POST /api/v1/packages`
+    // answered this refusal as `500 INTERNAL_ERROR`. Measured on a booted stack
+    // before the envelope landed; `422` with `declaredCode: NAMESPACE_CONFLICT`
+    // after it. `resolveThrownHttpError` reads exactly these two fields off the
+    // throw, so they are what the door's answer is MADE of — asserting the
+    // class instead asserts something the wire never sees.
+    registry.installPackage(manifest('com.acme.crm', 'crm') as any);
+    let caught: (Error & { code?: string; status?: number }) | undefined;
+    try {
+      registry.installPackage(manifest('com.beta.crm', 'crm') as any);
+    } catch (e) { caught = e as Error & { code?: string; status?: number }; }
+
+    expect(caught?.code).toBe('NAMESPACE_CONFLICT');
+    expect(caught?.status).toBe(422);
+    // The prose is unchanged by the envelope — this card added fields, it did
+    // not rewrite a sentence. Its first clause is what an operator reads.
+    expect(caught?.message).toContain('Namespace conflict: namespace "crm"');
+  });
+
   it('allows the same package to reinstall/reload its own namespace', () => {
     registry.installPackage(manifest('com.acme.crm', 'crm') as any);
     expect(() =>

packages/objectql/src/registry.ts

@@ -1252,10 +1252,29 @@ function toRecordManifest(manifest: ObjectStackManifest): ObjectStackManifest {
  * install up front with an actionable error, instead of letting a half-applied
  * install blow up later at table creation. Shareable platform namespaces
  * (`base`/`system`/`sys`) are exempt.
+ *
+ * [#14474] Carries the ADR-0112 envelope (`code` + `status`), like its sibling
+ * {@link ArtifactObjectNameConflictError} below. Unlike that sibling, this
+ * refusal IS reachable from a wire: `POST /api/v1/packages`
+ * (`packages/runtime/src/domains/packages.ts`) calls `installPackage` with no
+ * artifact scope — which this gate, unlike the D3 object-name one, does not
+ * need — and the domain's terminal catch answers `errorFromThrown(e, 500)`.
+ * `resolveThrownHttpError` reads `.status`/`.code` off the throw, so with no
+ * envelope the door fell through to that `500` fallback. Measured on a booted
+ * stack before this change: `500 INTERNAL_ERROR` carrying this refusal's prose,
+ * which tells an operator "the server broke" when the truth is "your package's
+ * namespace is already taken" — it invites a retry instead of a rename. With
+ * the envelope the same door answers `422`. The message is unchanged: it was
+ * already correct and specific.
  */
 export class NamespaceConflictError extends Error {
+  readonly code = 'NAMESPACE_CONFLICT';
+  readonly status = 422;
+  /** The namespace both packages claim. */
   readonly namespace: string;
+  /** The installed package that already owns the namespace. */
   readonly existingPackageId: string;
+  /** The package whose install this refusal stopped. */
   readonly incomingPackageId: string;
 
   constructor(namespace: string, existingPackageId: string, incomingPackageId: string) {