Merge remote-tracking branch 'origin/main' into claude/issue-16882-connect-agent-reachability-copy

Author: claude

.changeset/driver-config-registry-off-vocabulary-lookup-guard.md

@@ -0,0 +1,49 @@
+---
+'@objectstack/spec': patch
+---
+
+fix(spec): the driver-config registry refuses an off-vocabulary id instead of answering with a truthy non-schema
+
+`DRIVER_CONFIG_JSON_SCHEMAS`, `DRIVER_ID_ALIASES` and `DATABASE_DRIVER_ALIASES`
+are plain object literals, so all three inherit `Object.prototype`, and every
+lookup into them was a bare index. Measured against the built artifact
+(`dist/data/index.mjs`) on the repo's Node 22 baseline (v22.22.2), an id that
+names an inherited member resolved that member and was handed onward as if it
+were a driver:
+
+| call | before | after |
+|:--|:--|:--|
+| `getDriverConfigJsonSchemaById('memory')` | the JSON Schema | the JSON Schema — unmoved |
+| `getDriverConfigJsonSchemaById('constructor')` | `{}` — an EMPTY JSON Schema that accepts every config | `TypeError` naming the id and the legal vocabulary |
+| `getDriverConfigJsonSchemaById('toString')` | `'[object Object]'` — a **string**, where the signature promises an object | `TypeError` |
+| `getDriverConfigJsonSchemaById('valueOf')` | the registry object itself | `TypeError` |
+| `getDriverConfigJsonSchemaById('__proto__')` | `TypeError: … is not a function` | `TypeError`, now naming the id |
+| `getDriverConfigJsonSchemaById('nope')` | `TypeError: … is not a function` | `TypeError`, now naming the id |
+| `resolveDriverId('constructor')` | the `Object` **function** — truthy, not a driver id | `undefined` |
+| `resolveDriverId('__proto__')` | `Object.prototype` — a truthy object | `undefined` |
+| `resolveDatabaseDriverId('constructor')` | the `Object` **function** | `undefined` |
+| `driverHasLocalDefault('constructor')` | `undefined`, out of a function declared `boolean` | `true`, as its doc promises for an unknown id |
+| `resolveDriverId('pg')` / `resolveDriverId(' PostgreSQL ')` | `'postgres'` | `'postgres'` — unmoved |
+
+`getDriverConfigJsonSchemaById` handing back `{}` is the worst of these: an
+empty JSON Schema validates anything, so a Studio connection form or a
+`DriverDefinitionSchema.configSchema` consumer that asked "what shape must this
+config have" was told "any shape at all" and reported success.
+
+The resolvers' half is reachable without a plain-JS consumer. The CLI refuses an
+unclaimed operator selection with `if (driverType && !kind)` after calling
+`resolveDatabaseDriverId`, so `OS_DATABASE_DRIVER=constructor` produced a truthy
+`kind` that is not a driver id and walked past the refusal.
+
+All three lookups now go through an `Object.prototype.hasOwnProperty.call` check.
+This narrows and widens nothing: every legal spelling is an own key of its table,
+so no value accepted before is refused now, and only answers that were never
+inside the declared return types move. The declared signatures are unchanged —
+`getDriverConfigJsonSchemaById` stays `(id: BuiltinDriverId) => Record<string, unknown>`
+and both resolvers stay `(driver: unknown) => BuiltinDriverId | undefined`.
+
+A null-prototype table was the other available shape and was measured rather than
+assumed: a `__proto__: null` object literal does not type-check against the
+`Readonly<Record<…>>` annotation at all (TS2353), and the
+`Object.assign(Object.create(null), …)` spelling that does compile silently costs
+that annotation — a table missing a driver stopped failing to compile (TS2741).

.github/workflows/lint.yml

@@ -2407,6 +2407,26 @@ jobs:
       - name: Quick-reference section counts match their tables
         run: pnpm check:quick-reference-counts
 
+      # #17388: three hand-written pages enumerate @objectstack/spec's importable
+      # subpaths or its protocol namespaces, and nothing read any of them. When
+      # #16325 step 3 deleted the ./cloud exports entry and added ./marketplace,
+      # every MECHANICAL counter of that set moved with it -- the anti-vacuity
+      # floor pin, the alias-coverage pin, export-origins, root-meta, llms.txt,
+      # quick-reference counts, ~25 in all -- and all three prose enumerations
+      # kept advertising cloud and never listed marketplace, until a human swept
+      # for them. Step 2 of that same chain was FAILed in review by exactly this
+      # class of unlisted counter.
+      # It holds TWO derived sets, not one: the exports map's 16 bare ./<name>
+      # entries, and the 15 of those whose declared CATEGORY_TITLES title ends in
+      # " Protocol" (meta-spelling is a subpath and is titled "Vocabulary", not a
+      # protocol). Display names come from that same declaration, so the #5853
+      # "Qa Protocol" class of wrong-but-stable spelling is a finding here too.
+      # It lives in this job with the other docs guards: the edit that breaks it
+      # is a docs edit, so a packages/** paths filter would blind it to its own
+      # failure mode.
+      - name: Hand-written spec enumerations match the exports map
+        run: pnpm check:docs-spec-enumerations
+
       # #11752: the "Overlay whitelist (shared-DB tenancy invariant)" table in
       # metadata-lifecycle.mdx is a hand-kept copy of DEFAULT_METADATA_TYPE_REGISTRY
       # sitting directly under the sentence that calls the registry the single

package.json

@@ -61,6 +61,7 @@
     "check:corpus-claim-drift": "node scripts/check-corpus-claim-drift.mjs --self-test && node scripts/check-corpus-claim-drift.mjs",
     "check:skill-identifier-liveness": "node scripts/check-skill-identifier-liveness.mjs --self-test && node scripts/check-skill-identifier-liveness.mjs",
     "check:quick-reference-counts": "node scripts/check-quick-reference-counts.mjs --self-test && node scripts/check-quick-reference-counts.mjs",
+    "check:docs-spec-enumerations": "node scripts/check-docs-spec-enumerations.mjs --self-test && node scripts/check-docs-spec-enumerations.mjs",
     "check:overlay-whitelist-table": "node scripts/check-overlay-whitelist-table.mjs --self-test && node scripts/check-overlay-whitelist-table.mjs",
     "check:runtime-services-index": "node scripts/check-runtime-services-index.mjs --self-test && node scripts/check-runtime-services-index.mjs",
     "check:skill-frame-sync": "node scripts/check-skill-frame-sync.mjs --self-test && node scripts/check-skill-frame-sync.mjs",

packages/spec/src/data/driver/config-registry.test.ts

@@ -5,10 +5,12 @@ import { describe, it, expect } from 'vitest';
 import { DatasourceSchema } from '../datasource.zod';
 import {
   BUILTIN_DRIVER_IDS,
+  type BuiltinDriverId,
   DATABASE_DRIVER_SELECTION_ALIASES,
   DATABASE_DRIVER_SELECTION_IDS,
   DRIVER_CONFIG_SCHEMAS,
   DRIVER_ID_ALIASES,
+  driverHasLocalDefault,
   getDriverConfigJsonSchemaById,
   getDriverConfigSchema,
   resolveDatabaseDriverId,
@@ -222,3 +224,149 @@ describe('DATABASE_DRIVER_SELECTION_IDS — what a boot flag may offer (#6969)',
     expect(Object.isFrozen(DATABASE_DRIVER_SELECTION_IDS)).toBe(true);
   });
 });
+/**
+ * The OFF-VOCABULARY population — the one the pins above cannot reach (#16903).
+ *
+ * ⚠ Every existing case in this file iterates `BUILTIN_DRIVER_IDS`,
+ * `DRIVER_ID_ALIASES` or a hand-written canonical spelling: exactly the
+ * population that behaves. They were all green while
+ * `getDriverConfigJsonSchemaById('constructor')` returned `{}` — an EMPTY JSON
+ * Schema that accepts every config it is asked to judge — and while
+ * `resolveDriverId('constructor')` returned the `Object` FUNCTION out of a
+ * signature that says `BuiltinDriverId | undefined`. A pin over canonical ids
+ * alone would be green before and after the guard and would prove nothing, so
+ * the population is the point of this describe.
+ */
+describe('driver lookups — an OFF-vocabulary id is refused, never answered with a non-schema (#16903)', () => {
+  /**
+   * The consumer that actually reaches these, spelled as the cast it is.
+   * `getDriverConfigJsonSchemaById` and both resolvers are published
+   * (`packages/spec/api-surface/data.json`), so "unreachable in-repo" is not
+   * "unreachable": a plain-JS consumer arrives with zero type checking, and for
+   * the resolvers the id can also arrive from `OS_DATABASE_DRIVER` or from
+   * authored `datasource.driver` metadata — which is exactly where
+   * `constructor` and `toString` show up.
+   */
+  const untypedJsonSchema = (id: string): unknown => getDriverConfigJsonSchemaById(id as BuiltinDriverId);
+
+  /**
+   * Words that resolve an INHERITED member, grouped by what the bare lookup did
+   * with each before the own-property guard. Measured against the built
+   * artifact (`dist/data/index.mjs`) on the Node 22 baseline (v22.22.2).
+   */
+  const PROTOTYPE_RESOLVABLE_CALLABLE = [
+    // Returned a truthy NON-schema — the silent wrong answers, and the reason
+    // this is a bug rather than a tidy-up. `constructor` ran `Object()` and gave
+    // `{}`; `toString` gave the STRING '[object Object]'; `valueOf` gave the
+    // registry object itself.
+    'constructor',
+    'toString',
+    'valueOf',
+    // Returned a `boolean` (each called with no argument, receiver = the
+    // registry) where the signature promises an object — which is why a
+    // truthiness assertion alone cannot catch this family either.
+    'hasOwnProperty',
+    'isPrototypeOf',
+    'propertyIsEnumerable',
+  ];
+
+  /**
+   * Words with no own key AND nothing callable behind them: `__proto__`
+   * resolved `Object.prototype`, the rest resolved `undefined`. Both spellings
+   * already threw a `TypeError` off a non-callable, so these are the CONTROLS —
+   * the guard must not invent a new failure for input that already failed.
+   */
+  const ALREADY_THREW = ['__proto__', 'nope', '', 'com.vendor.snowflake'];
+
+  const OFF_VOCABULARY = [...PROTOTYPE_RESOLVABLE_CALLABLE, ...ALREADY_THREW];
+
+  it('holds this population HONEST — every word above is outside the vocabulary', () => {
+    // Without this, a spelling promoted into the table would leave every pin
+    // below asserting a refusal for a LEGAL id, and they would go on passing
+    // while meaning the opposite of what they say.
+    for (const word of OFF_VOCABULARY) {
+      expect(BUILTIN_DRIVER_IDS as readonly string[], word).not.toContain(word);
+      expect(Object.prototype.hasOwnProperty.call(DRIVER_ID_ALIASES, word), word).toBe(false);
+    }
+  });
+
+  it('throws for an id naming a callable Object.prototype member, instead of returning a non-schema', () => {
+    for (const id of PROTOTYPE_RESOLVABLE_CALLABLE) {
+      expect(() => untypedJsonSchema(id), id).toThrow(TypeError);
+    }
+  });
+
+  it('still throws for a plainly absent id, exactly as it always did', () => {
+    // The control: `__proto__` and an unknown word threw a `TypeError` before
+    // the guard too. The guard is a narrowing, so this assertion must be green
+    // on both sides of it — if it moves, the change did more than close a hole.
+    for (const id of ALREADY_THREW) {
+      expect(() => untypedJsonSchema(id), id).toThrow(TypeError);
+    }
+  });
+
+  it('names the offending id and the legal vocabulary in every refusal', () => {
+    // A bare `.toThrow()` is not a refusal assertion here: two of these words
+    // already threw. What distinguishes a REFUSAL from the old incidental
+    // `… is not a function` is that the message names the subject and what was
+    // expected instead.
+    for (const id of OFF_VOCABULARY) {
+      let message = '';
+      try {
+        untypedJsonSchema(id);
+      } catch (error) {
+        message = (error as Error).message;
+      }
+      expect(message, id).toContain('getDriverConfigJsonSchemaById');
+      expect(message, id).toContain(JSON.stringify(id));
+      for (const canonical of BUILTIN_DRIVER_IDS) {
+        expect(message, `${id} → ${canonical}`).toContain(canonical);
+      }
+    }
+  });
+
+  it('still answers every canonical id with its own JSON Schema, unmoved', () => {
+    // The narrowing must stop at the vocabulary edge: the guard refuses more and
+    // accepts nothing new, so every in-vocabulary answer is byte-identical.
+    for (const id of BUILTIN_DRIVER_IDS) {
+      const json = getDriverConfigJsonSchemaById(id) as { type?: string; properties?: object };
+      expect(json.type, id).toBe('object');
+      expect(json.properties, id).toBeTruthy();
+    }
+    // …and the memoised identity survives the guard.
+    expect(getDriverConfigJsonSchemaById('postgres')).toBe(getDriverConfigJsonSchemaById('postgres'));
+  });
+
+  it('resolves an off-vocabulary spelling to `undefined`, never to a truthy non-id', () => {
+    // `resolveDriverId('constructor')` returned the `Object` FUNCTION and
+    // `resolveDriverId('__proto__')` returned `Object.prototype` — both truthy,
+    // neither a `BuiltinDriverId`, out of a signature that admits only
+    // `BuiltinDriverId | undefined`.
+    for (const word of OFF_VOCABULARY) {
+      expect(resolveDriverId(word), word).toBeUndefined();
+      expect(resolveDatabaseDriverId(word), word).toBeUndefined();
+    }
+  });
+
+  it('answers `true` for an off-vocabulary driver in driverHasLocalDefault, never `undefined`', () => {
+    // The declared return is `boolean` and the doc promises `true` for an id the
+    // table does not know. A truthy non-id from `resolveDriverId` used to index
+    // `DRIVER_LOCAL_DEFAULT` to `undefined`, so `constructor` and `__proto__`
+    // came back `undefined` out of a function declared `boolean`.
+    for (const word of OFF_VOCABULARY) {
+      expect(typeof driverHasLocalDefault(word), word).toBe('boolean');
+      expect(driverHasLocalDefault(word), word).toBe(true);
+    }
+  });
+
+  it('still answers every canonical id from the vocabulary table, unmoved', () => {
+    // The other side of the same edge, for the resolvers.
+    for (const id of BUILTIN_DRIVER_IDS) {
+      expect(resolveDriverId(id), id).toBe(id);
+      expect(resolveDatabaseDriverId(id), id).toBe(id);
+    }
+    expect(resolveDriverId('  PostgreSQL ')).toBe('postgres');
+    expect(resolveDriverId('sqlite3')).toBe('sqlite');
+    expect(resolveDatabaseDriverId('sqlite3')).toBeUndefined();
+  });
+});