|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * [#14748] `POST /api/v1/packages` answers a namespace collision with |
| 5 | + * `error.code: NAMESPACE_CONFLICT` — the wire half of registering the code in |
| 6 | + * `ERROR_CODE_LEDGER`. |
| 7 | + * |
| 8 | + * ## What changed, and why a pin belongs here rather than beside the throw |
| 9 | + * |
| 10 | + * `NamespaceConflictError` (`packages/objectql/src/registry.ts`) has carried |
| 11 | + * the ADR-0112 envelope (`code` + `status: 422`) since #14474, and |
| 12 | + * `packages/objectql/src/registry-namespace-install-gate.test.ts` asserts both |
| 13 | + * fields ON THE THROW. That is a different claim from this one. Until the |
| 14 | + * ledger row landed, `NAMESPACE_CONFLICT` was not an `ErrorCode` member, so the |
| 15 | + * #9106 door narrowing DEMOTED the spelling onto the wire's open `declaredCode` |
| 16 | + * sibling and put `VALIDATION_ERROR` — the member 422 derives through |
| 17 | + * `standardErrorCodeForHttpStatus` — in the closed `error.code` slot: |
| 18 | + * |
| 19 | + * before: {"code":"VALIDATION_ERROR", "declaredCode":"NAMESPACE_CONFLICT", …} |
| 20 | + * after: {"code":"NAMESPACE_CONFLICT", …} ← `declaredCode` gone: nothing to demote |
| 21 | + * |
| 22 | + * So the throw's envelope and the wire's envelope were two different bodies, |
| 23 | + * and a suite asserting the first could not see the second. Registration is |
| 24 | + * what closes that gap, and the gap is invisible to every existing suite. This |
| 25 | + * file is the assertion that it stays closed. |
| 26 | + * |
| 27 | + * ⭐ It is also the permanent answer to the reachability claim the removed |
| 28 | + * `pending-registration` row asserted without pinning — the row's `door: |
| 29 | + * 'dispatcher'` verdict rested on a temporary probe test that was never in the |
| 30 | + * tree (#14745 residue 2). This suite makes the same claim by DRIVING the door. |
| 31 | + * |
| 32 | + * ## What is real here and what is doubled |
| 33 | + * |
| 34 | + * Real: `HttpDispatcher.handlePackages` (the shipped route), the terminal |
| 35 | + * `catch` that answers `errorFromThrown(e, 500)`, `resolveThrownHttpError`'s |
| 36 | + * registered/demoted decision, `buildApiError`, and the actual `SchemaRegistry` |
| 37 | + * — so the refusal under test is the one production raises, from the same |
| 38 | + * `installPackage` call, not a hand-built stand-in carrying the same fields. |
| 39 | + * |
| 40 | + * Doubled: only the kernel's service lookup, which hands the door that |
| 41 | + * registry. There is no protocol service, so the install takes the documented |
| 42 | + * fallback limb (`registry.installPackage(manifest, settings)`) — the same |
| 43 | + * primitive the protocol limb calls underneath. |
| 44 | + * |
| 45 | + * ## Reverse verification — direction predicted BEFORE running |
| 46 | + * |
| 47 | + * Removing `'NAMESPACE_CONFLICT'` from the `@objectstack/objectql` list in |
| 48 | + * `packages/spec/src/api/error-code-ledger.zod.ts` and rebuilding was predicted |
| 49 | + * to turn section 1 RED (`error.code` back to `VALIDATION_ERROR`, and |
| 50 | + * `declaredCode` reappearing) and section 2's registration assertion RED, while |
| 51 | + * leaving section 3 — an unregistered spelling at the same door — GREEN in both |
| 52 | + * directions, since nothing about that limb depends on this row. The measured |
| 53 | + * result is recorded in the PR body. |
| 54 | + * |
| 55 | + * ⛔ Never a bare `toThrow()` here: the door does not throw, it ANSWERS, and |
| 56 | + * the whole subject is what the answer carries. |
| 57 | + */ |
| 58 | + |
| 59 | +import { describe, it, expect } from 'vitest'; |
| 60 | +import { |
| 61 | + ApiErrorSchema, |
| 62 | + BaseResponseSchema, |
| 63 | + ErrorCode, |
| 64 | + envelopeViolations, |
| 65 | + standardErrorCodeForHttpStatus, |
| 66 | +} from '@objectstack/spec/api'; |
| 67 | +import { SchemaRegistry } from '@objectstack/objectql'; |
| 68 | +import { HttpDispatcher } from './http-dispatcher.js'; |
| 69 | + |
| 70 | +/** |
| 71 | + * [#7033 / #7023] `/packages` carries an anonymous-deny floor and every |
| 72 | + * state-changing route demands `manage_metadata`. Without a caller these cases |
| 73 | + * would stop at the 401 long before the install gate they are named after. |
| 74 | + */ |
| 75 | +const PKG_ADMIN = () => ({ |
| 76 | + request: {}, |
| 77 | + executionContext: { |
| 78 | + userId: 'u_pkg_admin', |
| 79 | + systemPermissions: ['manage_metadata', 'studio.access', 'setup.access'], |
| 80 | + }, |
| 81 | +}) as any; |
| 82 | + |
| 83 | +const manifest = (id: string, namespace: string) => ({ id, name: id, namespace, version: '1.0.0' }); |
| 84 | + |
| 85 | +/** |
| 86 | + * The door over a REAL registry. `collisionPolicy: 'error'` is the default |
| 87 | + * posture the gate refuses under; `OS_METADATA_COLLISION=warn` downgrades it, |
| 88 | + * which is `registry-namespace-install-gate.test.ts`'s territory, not this |
| 89 | + * file's. |
| 90 | + */ |
| 91 | +function makeDoor(registry: SchemaRegistry) { |
| 92 | + const kernel: any = { |
| 93 | + getService: (name: string) => |
| 94 | + name === 'objectql' ? Promise.resolve({ registry }) : null, |
| 95 | + context: { getService: () => null }, |
| 96 | + }; |
| 97 | + return new HttpDispatcher(kernel); |
| 98 | +} |
| 99 | + |
| 100 | +function freshRegistry(): SchemaRegistry { |
| 101 | + const registry = new SchemaRegistry({ multiTenant: false, collisionPolicy: 'error' }); |
| 102 | + (registry as any).logLevel = 'silent'; |
| 103 | + return registry; |
| 104 | +} |
| 105 | + |
| 106 | +/** `POST /api/v1/packages` with `manifest` as the body, exactly as the route reads it. */ |
| 107 | +const install = (dispatcher: HttpDispatcher, body: unknown) => |
| 108 | + dispatcher.handlePackages('', 'POST', body, {}, PKG_ADMIN()); |
| 109 | + |
| 110 | +/** Every assertion an error body must satisfy whatever produced it (mirrors the conformance suite). */ |
| 111 | +function expectConformantError(response: { status: number; body?: any } | undefined) { |
| 112 | + expect(response, 'the door produced no response').toBeTruthy(); |
| 113 | + const body = response!.body; |
| 114 | + expect(BaseResponseSchema.safeParse(body).success).toBe(true); |
| 115 | + expect(envelopeViolations(body), `not the declared envelope: ${JSON.stringify(body)}`).toEqual([]); |
| 116 | + expect(body.success).toBe(false); |
| 117 | + const parsed = ApiErrorSchema.safeParse(body.error); |
| 118 | + expect(parsed.error?.issues ?? []).toEqual([]); |
| 119 | + return body.error as Record<string, unknown>; |
| 120 | +} |
| 121 | + |
| 122 | +describe('#14748 — the install-time namespace refusal carries its own code on the wire', () => { |
| 123 | + it('section 1: a second package claiming an owned namespace answers 422 NAMESPACE_CONFLICT', async () => { |
| 124 | + const registry = freshRegistry(); |
| 125 | + const dispatcher = makeDoor(registry); |
| 126 | + |
| 127 | + const first = await install(dispatcher, manifest('com.acme.crm', 'crm')); |
| 128 | + expect(first.handled).toBe(true); |
| 129 | + expect(first.response?.status, 'the first install must SUCCEED, or the refusal below is vacuous').toBe(201); |
| 130 | + |
| 131 | + const refused = await install(dispatcher, manifest('com.beta.crm', 'crm')); |
| 132 | + expect(refused.handled).toBe(true); |
| 133 | + expect(refused.response?.status).toBe(422); |
| 134 | + |
| 135 | + const error = expectConformantError(refused.response); |
| 136 | + |
| 137 | + // ⭐ The one line this card exists for. |
| 138 | + expect(error.code).toBe('NAMESPACE_CONFLICT'); |
| 139 | + |
| 140 | + // And the demote is GONE, not merely joined: with the code registered |
| 141 | + // there is nothing left for `demotedDeclaredCode` to carry, so the |
| 142 | + // sibling field is absent rather than duplicating `code`. |
| 143 | + expect(error.declaredCode).toBeUndefined(); |
| 144 | + |
| 145 | + // The prose is unchanged by registration — this card added a ledger |
| 146 | + // row, it did not rewrite the sentence an operator reads. |
| 147 | + expect(error.message).toContain('Namespace conflict: namespace "crm"'); |
| 148 | + }); |
| 149 | + |
| 150 | + it('section 2: the code is a member of the closed vocabulary, and the status cannot have invented it', () => { |
| 151 | + // The registration itself, asserted against the union `ApiErrorSchema.code` |
| 152 | + // parses with — this is what section 1 depends on. |
| 153 | + expect(ErrorCode.safeParse('NAMESPACE_CONFLICT').success).toBe(true); |
| 154 | + |
| 155 | + // The control that makes section 1 discriminating: 422 does NOT derive |
| 156 | + // this member, so a body carrying it proves the PRODUCER's code was |
| 157 | + // carried through, never re-derived from the status. |
| 158 | + expect(standardErrorCodeForHttpStatus(422)).not.toBe('NAMESPACE_CONFLICT'); |
| 159 | + }); |
| 160 | + |
| 161 | + it('section 3: an UNREGISTERED spelling at the same door still demotes — the control', async () => { |
| 162 | + // Without this, section 1 would also be satisfied by a door that |
| 163 | + // carries every producer spelling verbatim, which is exactly the |
| 164 | + // pre-#9106 behaviour the narrowing removed. The registry is doubled |
| 165 | + // for this one case only: no shipped producer spells an unregistered |
| 166 | + // code at this door — the dispatcher-vocabulary gate exists to keep it |
| 167 | + // that way — so the limb has to be driven deliberately. |
| 168 | + const conflict = Object.assign(new Error('a tenant refusal'), { |
| 169 | + code: 'A_TENANT_SPELLING_NO_LEDGER_KNOWS', |
| 170 | + status: 422, |
| 171 | + }); |
| 172 | + const dispatcher = makeDoor({ |
| 173 | + installPackage: () => { throw conflict; }, |
| 174 | + getPackage: () => undefined, |
| 175 | + getAllPackages: () => [], |
| 176 | + } as unknown as SchemaRegistry); |
| 177 | + |
| 178 | + const refused = await install(dispatcher, manifest('com.gamma.crm', 'crm')); |
| 179 | + const error = expectConformantError(refused.response); |
| 180 | + |
| 181 | + expect(refused.response?.status).toBe(422); |
| 182 | + expect(error.code).toBe(standardErrorCodeForHttpStatus(422)); |
| 183 | + expect(error.code).not.toBe('A_TENANT_SPELLING_NO_LEDGER_KNOWS'); |
| 184 | + expect(error.declaredCode).toBe('A_TENANT_SPELLING_NO_LEDGER_KNOWS'); |
| 185 | + }); |
| 186 | +}); |
0 commit comments