@openwop/openwop-conformance 1.0.0

package/src/scenarios/orchestratorTermination.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Multi-Agent Shift Phase 5 — orchestrator terminate decision (CO-3).
+ *
+ * Verifies that when an `core.orchestrator.supervisor` emits a decision
+ * with `kind: 'terminate'`:
+ *   1. `runOrchestrator.decided` event carries the terminate decision.
+ *   2. `run.completed` follows (NOT `run.failed`).
+ *   3. No further `runOrchestrator.decided` events are emitted (CO-3).
+ *
+ * Capability-gated: skips when host doesn't advertise
+ * `capabilities.agents.orchestrator: true`. Fixture-gated: requires
+ * `conformance-orchestrator-terminate`.
+ *
+ * @see schemas/orchestrator-decision.schema.json (TerminateDecision)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { isOrchestratorSupported } from '../lib/multi-agent-capabilities.js';
+
+const FIXTURE = 'conformance-orchestrator-terminate';
+const SKIP = !isOrchestratorSupported() || !isFixtureAdvertised(FIXTURE);
+
+describe.skipIf(SKIP)('orchestratorTermination: terminate decision → run.completed (CO-3)', () => {
+  it('terminate is the final orchestrator decision; run completes cleanly', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status).toBe('completed');
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as { events?: Array<{ type: string; payload?: Record<string, unknown>; sequence?: number }> })
+      .events ?? [];
+
+    const decisions = list.filter((e) => e.type === 'runOrchestrator.decided');
+    expect(decisions.length).toBeGreaterThan(0);
+
+    const lastDecision = decisions[decisions.length - 1];
+    const decision = lastDecision.payload?.decision as { kind?: string } | undefined;
+    expect(decision?.kind).toBe('terminate');
+
+    // CO-3: no terminate after another terminate. Equivalent: only one
+    // terminate decision per run.
+    const terminates = decisions.filter((e) => {
+      const d = e.payload?.decision as { kind?: string } | undefined;
+      return d?.kind === 'terminate';
+    });
+    expect(terminates.length).toBe(1);
+  });
+});

package/src/scenarios/otel-emission.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Track 11: OTel span emission verification.
+ *
+ * Verifies that hosts claiming observability conformance emit the
+ * canonical `openwop.*` spans + attributes documented in
+ * `spec/v1/observability.md` §"Run-level attributes" and §"Node-level
+ * attributes". Uses the in-process OTLP/HTTP-JSON collector started by
+ * `setup.ts` when `OPENWOP_OTEL_COLLECTOR=true`.
+ *
+ * Operator contract for this scenario to exercise the host:
+ *   1. Start the conformance suite with `OPENWOP_OTEL_COLLECTOR=true`.
+ *   2. Configure the host with
+ *      `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>` (port
+ *      printed at suite init) and
+ *      `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`.
+ *
+ * Skip conditions:
+ *   - Collector disabled (`OPENWOP_OTEL_COLLECTOR` unset / false).
+ *   - Host does not advertise `capabilities.observability` (presumed
+ *     non-conformant for OTel emission).
+ *   - Required fixture (`conformance-noop`) not advertised.
+ *
+ * @see spec/v1/observability.md §"Span attributes"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { getCollector, waitForRunSpans } from '../lib/otel-collector.js';
+
+const FIXTURE = 'conformance-noop';
+
+async function isObservabilityAdvertised(): Promise<boolean> {
+  try {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = (disco.json as { capabilities?: { observability?: unknown } }).capabilities ?? {};
+    return caps.observability !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+describe('otel-emission: required run-level + node-level attributes', () => {
+  it('host emits openwop.run + openwop.node.* spans with required attributes', async () => {
+    if (!getCollector()) {
+      // eslint-disable-next-line no-console
+      console.warn('[otel-emission] collector not started; set OPENWOP_OTEL_COLLECTOR=true to run');
+      return;
+    }
+    if (!isFixtureAdvertised(FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[otel-emission] fixture ${FIXTURE} not advertised; skipping`);
+      return;
+    }
+    if (!(await isObservabilityAdvertised())) {
+      // eslint-disable-next-line no-console
+      console.warn('[otel-emission] host does not advertise capabilities.observability; skipping');
+      return;
+    }
+
+    const collector = getCollector()!;
+    collector.reset();
+
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+
+    const runSpans = await waitForRunSpans(runId, { timeoutMs: 5_000, minCount: 2 });
+
+    expect(runSpans.length, driver.describe(
+      'observability.md §"Span attributes"',
+      'host MUST emit at least one openwop.* span carrying openwop.run_id',
+    )).toBeGreaterThan(0);
+
+    // Required run-level attributes per §"Run-level attributes": MUST
+    // include openwop.run_id (which we filtered on) and openwop.workflow_id.
+    const anySpanHasWorkflowId = runSpans.some(
+      (s) => s.attributes.get('openwop.workflow_id') === FIXTURE,
+    );
+    expect(anySpanHasWorkflowId, driver.describe(
+      'observability.md §"Run-level attributes"',
+      'spans MUST carry openwop.workflow_id matching the run\'s workflow',
+    )).toBe(true);
+
+    // Find an openwop.run span (lifecycle span; named per §"Span naming").
+    const runSpan = runSpans.find((s) => s.name === 'openwop.run' || s.name.startsWith('openwop.run.'));
+    expect(runSpan, driver.describe(
+      'observability.md §"Span naming"',
+      'host MUST emit a span named openwop.run (or openwop.run.<phase>) per run',
+    )).toBeDefined();
+
+    // Find an openwop.node.<typeId> span; conformance-noop has one node.
+    const nodeSpan = runSpans.find((s) => s.name.startsWith('openwop.node.'));
+    expect(nodeSpan, driver.describe(
+      'observability.md §"Span naming"',
+      'host MUST emit a span named openwop.node.<typeId> per node execution',
+    )).toBeDefined();
+
+    if (nodeSpan) {
+      // Required node-level attributes.
+      expect(typeof nodeSpan.attributes.get('openwop.node_id')).toBe('string');
+      expect(typeof nodeSpan.attributes.get('openwop.node_type')).toBe('string');
+      const attempt = nodeSpan.attributes.get('openwop.node_attempt');
+      expect(typeof attempt === 'number' && attempt >= 0, driver.describe(
+        'observability.md §"Node-level attributes"',
+        'openwop.node_attempt MUST be a non-negative number',
+      )).toBe(true);
+    }
+  });
+});

package/src/scenarios/otel-trace-propagation.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Track 11: W3C Trace Context propagation verification.
+ *
+ * Verifies that hosts claiming observability conformance honor inbound
+ * `traceparent` headers — spans emitted during the run MUST share the
+ * caller-provided traceId so distributed traces stitch correctly across
+ * client→host→provider boundaries.
+ *
+ * Reuses the in-process OTel collector from `setup.ts`.
+ *
+ * Skip conditions:
+ *   - Collector disabled.
+ *   - Host doesn't advertise `capabilities.observability`.
+ *   - Fixture `conformance-noop` not advertised.
+ *
+ * @see spec/v1/observability.md §"Trace context propagation"
+ * @see https://www.w3.org/TR/trace-context/
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { getCollector, waitForRunSpans } from '../lib/otel-collector.js';
+
+const FIXTURE = 'conformance-noop';
+
+/** Build a syntactically-valid traceparent with a known traceId. */
+function makeTraceparent(): { header: string; traceId: string } {
+  // W3C format: 00-<32 hex traceId>-<16 hex spanId>-01
+  const traceId = '4bf92f3577b34da6a3ce929d0e0e4736';
+  const spanId = '00f067aa0ba902b7';
+  return { header: `00-${traceId}-${spanId}-01`, traceId };
+}
+
+async function isObservabilityAdvertised(): Promise<boolean> {
+  try {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = (disco.json as { capabilities?: { observability?: unknown } }).capabilities ?? {};
+    return caps.observability !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+describe('otel-trace-propagation: inbound traceparent threads to emitted spans', () => {
+  it('host-emitted spans share the caller-supplied traceId', async () => {
+    if (!getCollector()) {
+      // eslint-disable-next-line no-console
+      console.warn('[otel-trace-propagation] collector not started; skipping');
+      return;
+    }
+    if (!isFixtureAdvertised(FIXTURE)) {
+      return;
+    }
+    if (!(await isObservabilityAdvertised())) {
+      // eslint-disable-next-line no-console
+      console.warn('[otel-trace-propagation] capabilities.observability not advertised; skipping');
+      return;
+    }
+
+    const collector = getCollector()!;
+    collector.reset();
+
+    const { header, traceId } = makeTraceparent();
+    const create = await driver.post(
+      '/v1/runs',
+      { workflowId: FIXTURE },
+      { headers: { traceparent: header } },
+    );
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+
+    const runSpans = await waitForRunSpans(runId, { timeoutMs: 5_000, minCount: 1 });
+
+    expect(runSpans.length).toBeGreaterThan(0);
+
+    // OTLP encodes traceId as a 32-char lowercase hex string in JSON. Compare case-insensitively
+    // since some exporters emit uppercase.
+    const wantTrace = traceId.toLowerCase();
+    const matching = runSpans.filter((s) => s.traceId.toLowerCase() === wantTrace);
+
+    expect(matching.length, driver.describe(
+      'observability.md §"Trace context propagation"',
+      'spans emitted during a run started with an inbound traceparent MUST share its traceId',
+    )).toBeGreaterThan(0);
+  });
+});

package/src/scenarios/pack-registry-publish.test.ts

@@ -0,0 +1,93 @@
+/**
+ * Pack-registry publish scenarios — `node-packs.md` §"PUT /v1/packs/{name}/-/{version}.tgz".
+ *
+ * The 19-code error catalog for the publish endpoint, recorded as
+ * `it.todo()` scenarios that document the publish contract until OpenWOP
+ * defines a test-mode registry namespace.
+ *
+ * Why placeholders:
+ *
+ *   The publish path is gated on `packs:publish` scope (see auth.md) plus
+ *   a binary tarball upload. Round-trip scenarios from a black-box suite
+ *   would either:
+ *     1. Require the suite's `OPENWOP_API_KEY` to carry super-admin / publish
+ *        scope on the host under test — gives the suite the ability to
+ *        stomp on the real catalog, NOT acceptable for v1.
+ *     2. Require a host-provided test-mode `/v1/packs-test/*` namespace
+ *        that mirrors the real surface but writes to an isolated catalog —
+ *        this surface doesn't exist in the spec yet.
+ *
+ *   Until option 2 is specified, the scenarios below document the
+ *   error-code contract so they become runnable once the isolated surface
+ *   exists.
+ *
+ * @see node-packs.md §"PUT /v1/packs/{name}/-/{version}.tgz"
+ * @see auth.md §"`packs:publish` scope"
+ * @see schemas/node-pack-manifest.schema.json
+ */
+
+import { describe, it } from 'vitest';
+
+describe('pack-registry-publish: URL / scope error catalog (deferred — no test-mode surface)', () => {
+  it.todo('PUT with a name that doesn\'t match `core.*` / `vendor.*` / `community.*` / `private.*` MUST return 400 invalid_pack_scope — public registries (packs.openwop.dev) MUST additionally refuse `private.*` and `local.*`');
+
+  it.todo('PUT with a single-segment URL pack name MUST return 400 invalid_pack_name (URL pack-name doesn\'t match the reverse-DNS pattern at all)');
+
+  it.todo('PUT with a non-semver URL version MUST return 400 invalid_version');
+});
+
+describe('pack-registry-publish: body-shape error catalog (deferred — no test-mode surface)', () => {
+  it.todo('PUT with a JSON body (instead of tarball bytes) MUST return 400 invalid_body — body is not a Buffer / not octet-stream-shaped');
+
+  it.todo('PUT with an empty body MUST return 400 invalid_body');
+});
+
+describe('pack-registry-publish: tarball extraction error catalog (deferred — no test-mode surface)', () => {
+  it.todo('PUT with a body that isn\'t a valid gzip stream MUST return 400 tarball_gunzip_failed');
+
+  it.todo('PUT with decompressed bytes exceeding the registry\'s cap (recommended default: 50 MB) MUST return 400 tarball_too_large');
+
+  it.todo('PUT with no `pack.json` at the tarball root MUST return 400 tarball_manifest_missing');
+
+  it.todo('PUT with `pack.json` exceeding the registry\'s per-file cap (recommended default: 256 KB) MUST return 400 tarball_manifest_too_large');
+
+  it.todo('PUT with `pack.json` that isn\'t valid JSON MUST return 400 tarball_manifest_not_json');
+
+  it.todo('PUT with `manifest.runtime.entry` declaring a path that isn\'t in the tarball MUST return 400 tarball_entry_missing');
+
+  it.todo('PUT with an entry source exceeding the registry\'s per-file cap (recommended default: 5 MB) MUST return 400 tarball_entry_too_large');
+
+  it.todo('PUT with a tarball entry whose name contains `..` or otherwise escapes the pack root MUST return 400 tarball_path_traversal');
+
+  it.todo('PUT with a tar stream that the parser can\'t read past the gzip layer MUST return 400 tarball_tar_parse_failed');
+});
+
+describe('pack-registry-publish: manifest contents error catalog (deferred — no test-mode surface)', () => {
+  it.todo('PUT with a `pack.json` that fails schema validation MUST return 400 invalid_manifest — detail message includes the failing path');
+
+  it.todo('PUT with `manifest.name` and/or `manifest.version` differing from the URL params MUST return 400 manifest_mismatch — registries MAY emit the granular pair (`manifest_name_mismatch` / `manifest_version_mismatch`); clients MUST handle either');
+
+  it.todo('PUT with server-computed SHA-256 not matching `X-Pack-Sha256` (when supplied) MUST return 400 pack_integrity_failure');
+
+  it.todo('PUT with `runtime.language` value not accepted by the registry MUST return 400 unsupported_runtime');
+});
+
+describe('pack-registry-publish: authorization + conflict (deferred — no test-mode surface)', () => {
+  it.todo('PUT without `packs:publish` scope or namespace claim MUST return 403 forbidden');
+
+  it.todo('PUT for an existing (name, version) with DIFFERENT content MUST return 409 conflict — registries MAY emit `version_conflict`; either form is spec-allowed');
+
+  it.todo('PUT for an existing (name, version) with IDENTICAL sha256 content MUST return 200 OK with the existing record (idempotent re-publish)');
+});
+
+describe('pack-registry-publish: unpublish window (deferred — no test-mode surface)', () => {
+  it.todo('DELETE /v1/packs/{name}/-/{version} for a version older than the registry\'s unpublish window (default 72h) MUST return 400 unpublish_window_expired — use the yank flow for security incidents past the window');
+});
+
+describe('pack-registry-publish: signature endpoint pairing (deferred — no test-mode surface)', () => {
+  it.todo('after a PUT with a `signing.signatureRef` blob in the tarball, GET /v1/packs/{name}/-/{version}.sig MUST return the persisted signature (200 with bytes OR 302 to a signed URL)');
+
+  it.todo('after a PUT WITHOUT a signature blob, GET /v1/packs/{name}/-/{version}.sig MUST return 404 signature_not_available');
+
+  it.todo('after a YANK, GET /v1/packs/{name}/-/{version}.sig MUST return 404 signature_not_available — yanked tarballs MUST NOT serve their signatures (consumers shouldn\'t be verifying against known-bad packs)');
+});

package/src/scenarios/pack-registry.test.ts

@@ -0,0 +1,328 @@
+/**
+ * Pack-registry read scenarios — `node-packs.md` §"Registry HTTP API".
+ *
+ * Vendor-neutral discovery-shape contracts for the read surface of a
+ * OpenWOP-compliant pack registry. Hosts that DO NOT operate a registry are
+ * spec-allowed to omit the entire `/v1/packs/*` namespace; this suite
+ * detects that case via a probe on `GET /v1/packs/-/search` and
+ * trivially-passes the rest of the scenarios when no registry is
+ * present.
+ *
+ * Why discovery-shape only:
+ *
+ *   The publish path is gated on `packs:publish` scope (auth.md) and a
+ *   binary tarball upload — both outside the black-box surface this suite
+ *   asserts. Round-trip publish scenarios live in
+ *   `pack-registry-publish.test.ts` as documented TODO scenarios until
+ *   OpenWOP defines a test-mode registry namespace that lets conformance
+ *   suites publish without touching the real catalog. Hosts should cover
+ *   publish round-trips in host-specific route tests until that isolated
+ *   surface exists.
+ *
+ *   What IS testable cross-implementation: error envelopes for the read
+ *   endpoints (`pack_not_found`, `invalid_pack_name`, `invalid_version`,
+ *   `signature_not_available`), the search-result shape, and the keychain
+ *   shape when present.
+ *
+ * Scenario gating:
+ *
+ *   - **Registry presence probe** runs once; if the host returns 404 for
+ *     the search endpoint with a non-openwop error envelope (or a static-html
+ *     404), the scenarios short-circuit. Hosts ARE NOT required to ship a
+ *     pack registry.
+ *
+ *   - **Read-endpoint error envelopes** assert the shape of error
+ *     responses to known-bad inputs (nonexistent pack names, bad scopes).
+ *     Hosts that ship a registry MUST return openwop error envelopes here.
+ *
+ *   - **Keychain shape** is gated on whether the host serves a keychain
+ *     for the probed namespace (signing is OPTIONAL per the spec).
+ *
+ * @see node-packs.md §"Registry HTTP API"
+ * @see registry-operations.md §"Signing keychain"
+ * @see schemas/node-pack-manifest.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+/** A nonsense pack name in the `private.*` scope. Hosts MUST NOT have
+ *  shipped a real pack at this name (the namespace is scoped to a
+ *  randomized suffix). */
+const NONEXISTENT_PACK = `private.conformance-probe.does-not-exist-${Date.now()}`;
+const NONEXISTENT_VERSION = '0.0.0-conformance';
+
+/** Reverse-DNS pack name pattern from `node-packs.md` §Naming. The `private`
+ *  scope is part of the v1.0 pack-name pattern (spec-side companion to the runtime's
+ *  pre-existing acceptance). */
+const PACK_NAME_RE = /^(core|vendor|community|private)\.[a-z][a-z0-9_-]*(\.[a-z][a-zA-Z0-9_-]*)+$/;
+
+/** Semantic Versioning 2.0.0. */
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+interface RegistryProbeResult {
+  /** True when the host advertises a pack registry (any /v1/packs/* read returns an OpenWOP-shaped response). */
+  readonly registryPresent: boolean;
+  /** Last status code observed on the probe. */
+  readonly probeStatus: number;
+}
+
+/** Probe `GET /v1/packs/-/search?q=` once per process; cached. */
+let cachedProbe: RegistryProbeResult | null = null;
+async function probeRegistry(): Promise<RegistryProbeResult> {
+  if (cachedProbe) return cachedProbe;
+  // Empty query is the cheapest probe — server SHOULD reject empty-q
+  // with `400 validation_error` if the registry is mounted, OR return
+  // 200 with `{results: []}` if it tolerates empty queries. Either
+  // shape proves the registry is mounted. A 404 with a non-JSON body
+  // (or no `error` field) means the host doesn't run a registry.
+  const res = await driver.get('/v1/packs/-/search?q=', { authenticated: false });
+  const body = res.json as { error?: unknown; results?: unknown } | undefined;
+  // Heuristic: if the response is JSON-shaped (has either `error` or
+  // `results`), the registry is mounted. A wholly missing namespace
+  // returns the host's catch-all 404 which usually has no body or a
+  // host-specific shape.
+  const looksLikeWop = res.status === 200 || (typeof body === 'object' && body !== null && ('error' in body || 'results' in body));
+  cachedProbe = { registryPresent: looksLikeWop, probeStatus: res.status };
+  return cachedProbe;
+}
+
+describe('pack-registry: read-endpoint shape contracts', () => {
+  it('GET /v1/packs/-/search returns an OpenWOP-shaped response (or registry is absent)', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return; // Host doesn't ship a registry.
+
+    const res = await driver.get('/v1/packs/-/search?q=', { authenticated: false });
+    // Spec doesn't pin empty-q behavior — both 400 (validation) and 200
+    // (empty results) are acceptable. We only assert the response is
+    // JSON-shaped.
+    expect([200, 400]).toContain(res.status);
+    const body = res.json as Record<string, unknown> | undefined;
+    expect(body, driver.describe(
+      'node-packs.md §"GET /v1/packs/-/search"',
+      'response MUST be JSON',
+    )).toBeDefined();
+
+    if (res.status === 200) {
+      expect(Array.isArray(body?.results), driver.describe(
+        'node-packs.md §"GET /v1/packs/-/search"',
+        'search response MUST carry a `results` array',
+      )).toBe(true);
+    } else {
+      expect(typeof body?.error, driver.describe(
+        'rest-endpoints.md §"Error envelope"',
+        '400 response MUST carry a string `error` field',
+      )).toBe('string');
+    }
+  });
+
+  it('GET /v1/packs/{nonexistent} returns 404 pack_not_found with openwop error envelope', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    const res = await driver.get(`/v1/packs/${encodeURIComponent(NONEXISTENT_PACK)}`, {
+      authenticated: false,
+    });
+    expect(res.status, driver.describe(
+      'node-packs.md §"GET /v1/packs/{name}"',
+      'unknown pack name MUST return 404',
+    )).toBe(404);
+
+    const body = res.json as { error?: unknown } | undefined;
+    expect(typeof body?.error, driver.describe(
+      'rest-endpoints.md §"Error envelope"',
+      '404 response MUST carry a string `error` field',
+    )).toBe('string');
+    // Reference impl emits `pack_not_found`; spec doesn't pin the exact
+    // string — but the prefix `pack_` is the documented family.
+    expect((body?.error as string).length, driver.describe(
+      'rest-endpoints.md §"Error envelope"',
+      '`error` field MUST be non-empty',
+    )).toBeGreaterThan(0);
+  });
+
+  it('GET /v1/packs/{name}/-/{version}.json returns 404 for nonexistent version', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    const res = await driver.get(
+      `/v1/packs/${encodeURIComponent(NONEXISTENT_PACK)}/-/${NONEXISTENT_VERSION}.json`,
+      { authenticated: false },
+    );
+    expect(res.status, driver.describe(
+      'node-packs.md §"GET /v1/packs/{name}/-/{version}.json"',
+      'unknown (name, version) MUST return 404',
+    )).toBe(404);
+
+    const body = res.json as { error?: unknown } | undefined;
+    expect(typeof body?.error, driver.describe(
+      'rest-endpoints.md §"Error envelope"',
+      '404 response MUST carry a string `error` field',
+    )).toBe('string');
+  });
+
+  it('GET /v1/packs/{name}/-/{version}.sig returns 404 signature_not_available for nonexistent version', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    const res = await driver.get(
+      `/v1/packs/${encodeURIComponent(NONEXISTENT_PACK)}/-/${NONEXISTENT_VERSION}.sig`,
+      { authenticated: false },
+    );
+    // Spec: 404 signature_not_available is the canonical code; the four
+    // cases (missing / yanked / unsigned / storage-unwired) are
+    // intentionally indistinguishable. A 302 redirect to a storage-
+    // backed signed URL is also spec-allowed for VALID signatures —
+    // for a NONEXISTENT pack, only 404 is correct.
+    expect(res.status, driver.describe(
+      'node-packs.md §"GET /v1/packs/{name}/-/{version}.sig"',
+      'nonexistent (name, version) MUST return 404 signature_not_available',
+    )).toBe(404);
+
+    const body = res.json as { error?: unknown } | undefined;
+    expect(typeof body?.error, driver.describe(
+      'node-packs.md §"GET /v1/packs/{name}/-/{version}.sig"',
+      '404 response MUST carry a string `error` field — `signature_not_available` is the canonical code',
+    )).toBe('string');
+    expect((body?.error as string).length).toBeGreaterThan(0);
+  });
+
+  it('GET /v1/packs/{bad-name}/-/{version}.json returns 400 invalid_pack_name', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    // Single-segment name violates the reverse-DNS pattern.
+    const res = await driver.get('/v1/packs/not-reverse-dns/-/1.0.json', {
+      authenticated: false,
+    });
+    expect(res.status, driver.describe(
+      'node-packs.md §"GET /v1/packs/{name}/-/{version}.json"',
+      'malformed pack name MUST return 400 invalid_pack_name',
+    )).toBe(400);
+
+    const body = res.json as { error?: unknown } | undefined;
+    expect(typeof body?.error, driver.describe(
+      'rest-endpoints.md §"Error envelope"',
+      '400 response MUST carry a string `error` field',
+    )).toBe('string');
+  });
+
+  it('GET /v1/packs/{name}/-/{bad-version}.json returns 400 invalid_version', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    // `not-a-version` violates semver.
+    const res = await driver.get(
+      `/v1/packs/${encodeURIComponent(NONEXISTENT_PACK)}/-/not-a-version.json`,
+      { authenticated: false },
+    );
+    expect(res.status, driver.describe(
+      'node-packs.md §"GET /v1/packs/{name}/-/{version}.json"',
+      'non-semver version MUST return 400 invalid_version',
+    )).toBe(400);
+
+    const body = res.json as { error?: unknown } | undefined;
+    expect(typeof body?.error).toBe('string');
+  });
+});
+
+describe('pack-registry: catalog response shape (when populated)', () => {
+  it('GET /v1/packs/{name} catalog records validate against the documented shape', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    // Probe search for a real entry. If the catalog is empty, skip.
+    const search = await driver.get('/v1/packs/-/search?q=', { authenticated: false });
+    if (search.status !== 200) return;
+    const results = (search.json as { results?: Array<{ name?: unknown }> } | undefined)?.results;
+    if (!Array.isArray(results) || results.length === 0) return;
+
+    // Walk up to 3 results and assert their catalog records are well-shaped.
+    const sample = results.slice(0, 3);
+    for (const entry of sample) {
+      const name = entry.name;
+      if (typeof name !== 'string') continue;
+      expect(name, driver.describe(
+        'node-packs.md §"Naming"',
+        `search result name "${name}" MUST match reverse-DNS pattern`,
+      )).toMatch(PACK_NAME_RE);
+
+      const cat = await driver.get(`/v1/packs/${encodeURIComponent(name)}`, {
+        authenticated: false,
+      });
+      expect(cat.status, driver.describe(
+        'node-packs.md §"GET /v1/packs/{name}"',
+        `catalog read for known pack "${name}" MUST return 200`,
+      )).toBe(200);
+
+      const body = cat.json as {
+        name?: unknown;
+        versions?: Record<string, unknown>;
+        'dist-tags'?: { latest?: unknown };
+      } | undefined;
+      expect(body?.name, driver.describe(
+        'node-packs.md §"GET /v1/packs/{name}"',
+        'catalog response MUST echo the requested pack name',
+      )).toBe(name);
+      expect(typeof body?.versions, driver.describe(
+        'node-packs.md §"GET /v1/packs/{name}"',
+        'catalog response MUST carry a `versions` map',
+      )).toBe('object');
+
+      // Every version key MUST be valid semver per the spec.
+      const versionKeys = Object.keys(body?.versions ?? {});
+      for (const v of versionKeys) {
+        expect(v, driver.describe(
+          'node-packs.md §"Versioning"',
+          `version key "${v}" MUST match SemVer 2.0.0`,
+        )).toMatch(SEMVER_RE);
+      }
+    }
+  });
+});
+
+describe('pack-registry: keychain shape (when present)', () => {
+  it('GET /v1/packs/{name}/-/keychain returns well-formed key entries when present', async () => {
+    const probe = await probeRegistry();
+    if (!probe.registryPresent) return;
+
+    // Probe for any real pack to fetch its keychain. Skip if no packs.
+    const search = await driver.get('/v1/packs/-/search?q=', { authenticated: false });
+    if (search.status !== 200) return;
+    const results = (search.json as { results?: Array<{ name?: unknown }> } | undefined)?.results;
+    if (!Array.isArray(results) || results.length === 0) return;
+
+    const first = results[0]?.name;
+    if (typeof first !== 'string') return;
+
+    const res = await driver.get(`/v1/packs/${encodeURIComponent(first)}/-/keychain`, {
+      authenticated: false,
+    });
+    // 200 with `{keys: []}` and 404 are both spec-allowed (keychain is
+    // optional; not every namespace publishes one).
+    expect([200, 404]).toContain(res.status);
+    if (res.status === 404) return;
+
+    const body = res.json as { keys?: unknown; namespace?: unknown } | undefined;
+    expect(Array.isArray(body?.keys), driver.describe(
+      'registry-operations.md §"Signing keychain"',
+      'keychain response MUST carry a `keys` array',
+    )).toBe(true);
+
+    const keys = body?.keys as Array<Record<string, unknown>>;
+    for (const key of keys) {
+      expect(typeof key.kid, driver.describe(
+        'registry-operations.md §"Signing keychain"',
+        'each key MUST have a string `kid`',
+      )).toBe('string');
+      expect(typeof key.algorithm, driver.describe(
+        'registry-operations.md §"Signing keychain"',
+        'each key MUST have a string `algorithm`',
+      )).toBe('string');
+      expect(typeof key.publicKey, driver.describe(
+        'registry-operations.md §"Signing keychain"',
+        'each key MUST have a string `publicKey`',
+      )).toBe('string');
+    }
+  });
+});