fix(objectql): carry an ADR-0112 envelope on the install-time namespace conflict refusal (#14474)

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class

.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.

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) {

packages/runtime/src/dispatcher-error-vocabulary.ts

@@ -570,6 +570,44 @@ export const UNREGISTERED_CODE_SITES: readonly UnregisteredCodeSite[] = [
  'that a live wire code is outside the vocabulary; it does not prescribe the remedy.',
  },
 
+ // ── pending registration [#14474]: an install-time refusal that GAINED an
+ // ── envelope, so the scan can see it for the first time ────────────────
+ // Not a widened scan and not a new producer: `NamespaceConflictError` has
+ // thrown from `SchemaRegistry.installPackage` since ADR-0048 Phase 1, but
+ // it carried no `code` at all, so there was no stamp for any pattern to
+ // match. #14474 gave it the ADR-0112 envelope its three install-time
+ // siblings already carried, which is what put a site here to classify.
+ // The door narrowing its `why` names is #9106's — the file header above
+ // carries it. The anchor lives here rather than in the string, because a
+ // runtime string reaches operators who cannot resolve a tracker id.
+ {
+ code: 'NAMESPACE_CONFLICT',
+ file: 'packages/objectql/src/registry.ts',
+ shape: 'classfield',
+ door: 'dispatcher',
+ verdict: 'pending-registration',
+ why:
+ 'ADR-0048 Phase 1 — the install-time namespace gate\'s refusal, 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). ⭐ Its reachability is what ' +
+ 'separates it from the three ADR-0130 install-time rows below, whose `door: none` turns on ' +
+ 'needing an artifact install SCOPE that no HTTP caller builds: this gate needs no scope, so the ' +
+ 'ordinary one-package install reaches it. MEASURED on a booted stack (`@objectstack/verify` ' +
+ '`bootStack`, dev admin, two `POST /api/v1/packages` installs declaring one namespace), not ' +
+ 'inferred from the call graph. Before the envelope the door answered `500` with ' +
+ '`code: INTERNAL_ERROR` — `packages/runtime/src/domains/packages.ts` catches and calls ' +
+ '`errorFromThrown(e, 500)`, and `resolveThrownHttpError` found neither `.status` nor `.code` to ' +
+ 'read, so the caller\'s fallback stood. With the envelope the SAME request answers `422` and ' +
+ 'the body carries `declaredCode: NAMESPACE_CONFLICT` beside `code: VALIDATION_ERROR` (the ' +
+ 'member 422 derives through `standardErrorCodeForHttpStatus`, which does not name 422 and ' +
+ 'buckets it as a client error). That demote is the door narrowing described in this file\'s ' +
+ 'header, and it is exactly what ' +
+ 'a `pending-registration` row records: the body PARSES, and what the producer loses instead is ' +
+ 'its semantic code, silently absent from `error.code` until a ledger row lands. ⛔ Registering ' +
+ 'it is the `packages/spec` lane\'s call and is NOT made here — this row is that batch\'s input, ' +
+ 'and registering the code is what ratchets the row out again.',
+ },
+
  // ── boot refusals: no HTTP boundary exists yet ─────────────────────────
  // [#9460] The four `MigrationJournalRefusal` codes below arrive through the
  // same code-carrying-helper shape as `owd_widening_forbidden` — a class