feat(spec)!: publish the banned-keys rule the tracing filter arm enforces

The published `system/TraceSamplingConfig.json` accepted `{ dialect: 'cel' }` at
`composite[].condition` while the runtime refused it — the card's own worked
instance of a published JSON Schema WIDER than the zod it is generated from.

Teach the closed projection list a fourth named pattern, `banned-keys`, and
declare the tracing slot's rule through it. Two ledger rows retired.

Claude-Session: https://claude.ai/code/session_01AmH9bKvGoLjiY86Q4Z3og2
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/spec/dropped-refinements.baseline.json

@@ -2,10 +2,10 @@
   "description": "Shrink-only ledger of every PUBLISHED JSON Schema that is STILL WIDER than the Zod type it was generated from, because a rule written as `.refine()` reaches the runtime and not the file (#18670). `z.toJSONSchema()` has no arm for a `custom` check: a plain record, the same record with a `.refine()`, and the same record with an ABORTING `.refine()` all project byte-identically (measured on zod 4.4.3, the version packages/spec resolves). So a document one of these files ACCEPTS can still be refused at parse time, and an author -- or an AI -- validating against packages/spec/json-schema/** finds out a release later. Each `sites` path is a position under that schema at which a refinement is dropped; the same paths are written onto the artifact itself as `x-dropped-refinements`. Item 2 closed the first patterns: a refinement DECLARED through the closed list in src/shared/refinement-projection.ts is emitted into the published file, reads `projected` rather than `dropped`, and its row LEAVES this ledger in the same PR -- which is why the ledger shrinks and never grows on a repair. Every refinement outside that closed list stays here, and adding an arm to the list is a public-contract decision, not a refactor. Hand-edited on purpose and with no `gen:` script: a generator would let a new gap be admitted by running a command instead of by a decision, which is the silence this ledger exists to end. Adding, removing or moving a site fails packages/spec/scripts/build-schemas.ts until the line moves with it, and the failure prints the corrected entry in full. ⛔ Do not delete or weaken a refinement to shorten this file -- the runtime rule is correct; it is the projection that is silent, and the remedy is to teach the closed list a NAMED pattern, never to drop the rule.",
   "measured": {
     "zod": "4.4.3",
-    "publishedSchemasWithDroppedRefinements": 202,
-    "droppedRefinementSites": 553,
-    "refinementSitesThatDidProject": 367,
-    "refinementSitesWithNoJsonFormToCompare": 3
+    "publishedSchemasWithDroppedRefinements": 200,
+    "droppedRefinementSites": 551,
+    "refinementSitesThatDidProject": 369,
+    "refinementSitesWithNoJsonFormToCompare": 9
   },
   "entries": {
     "ai/BlueprintField": {
@@ -1044,16 +1044,6 @@
         "rateLimit"
       ]
     },
-    "system/TraceSamplingConfig": {
-      "sites": [
-        "composite.element.condition.options[0]"
-      ]
-    },
-    "system/TracingConfig": {
-      "sites": [
-        "sampling.composite.element.condition.options[0]"
-      ]
-    },
     "ui/Action": {
       "sites": [
         "in",

packages/spec/scripts/refinement-projection.test.ts

@@ -20,6 +20,9 @@
  *     set and `\S` is its complement, so the pin is the whole argument; JSON
  *     Schema specifies `pattern` as an ECMA-262 regex, which is the same engine
  *     this assertion runs on.
+ *   - `banned-keys` — over the whole key-presence lattice, with a
+ *     present-but-`null` value, and on a name `Object.prototype` carries, which
+ *     is the one JSON shape where "own property" and `in` come apart.
  *
  * ## Why an equality pin and not a comment
  *
@@ -44,11 +47,13 @@ import {
   NON_BLANK_PATTERN,
   NON_BLANK_STRING,
   PROJECTABLE_REFINEMENT_PATTERNS,
+  bannedKeys,
   dependentRequired,
   projectableRefinementOf,
   requiredOneOf,
 } from '../src/shared/refinement-projection';
 import { SSLConfigSchema } from '../src/data/driver-sql.zod';
+import { TraceSamplingConfigSchema } from '../src/system/tracing.zod';
 import {
   emitProjectableRefinement,
   projectPublishedJsonSchema,
@@ -85,6 +90,30 @@ const requiredOneOfSatisfied = (node: Record<string, unknown>, doc: Record<strin
   return branches.some((branch) => branch.required.every((key) => Object.prototype.hasOwnProperty.call(doc, key)));
 };
 
+/**
+ * The node's banned-key rule — `propertyNames.not.enum`, wherever the emitter put
+ * it — evaluated the way a validator would, and refusing to report anything when
+ * the node carries no such rule, so a projection that stopped emitting fails
+ * rather than passing vacuously.
+ *
+ * Both placements are read because the emitter chooses between them by what the
+ * node already carries: a record already states `propertyNames: { type:
+ * 'string' }`, so its ban is conjoined through `allOf`; a bare object has no
+ * `propertyNames` and takes the rule directly.
+ */
+const bannedKeysSatisfied = (node: Record<string, unknown>, doc: Record<string, unknown>): boolean => {
+  const clauses = [node, ...((node.allOf as Record<string, unknown>[] | undefined) ?? [])];
+  const banned = clauses
+    .map((clause) => (clause.propertyNames as { not?: { enum?: string[] } } | undefined)?.not?.enum)
+    .filter((list): list is string[] => Array.isArray(list));
+  if (banned.length === 0) {
+    throw new Error('the node carries no propertyNames.not.enum — nothing to evaluate');
+  }
+  return banned.every((list) =>
+    Object.keys(doc).every((name) => !list.includes(name)),
+  );
+};
+
 /**
  * ECMA-262 WhiteSpace ∪ LineTerminator, by code point so no control byte is
  * ever written into this file (`scripts/check-nul-bytes.mjs` is the authority
@@ -98,7 +127,7 @@ const BLANK_CODE_POINTS = [
 ];
 
 describe('the list of projectable patterns is CLOSED', () => {
-  it('names exactly the two arms this change landed', () => {
+  it('names exactly the arms this list has landed, and nothing else', () => {
     // ⛔ Growing this is a public-contract decision: every arm narrows a
     // published artifact. A new arm updates this line in the same PR, which is
     // what makes it a reviewed diff rather than a quiet widening of the
@@ -107,6 +136,7 @@ describe('the list of projectable patterns is CLOSED', () => {
       'required-one-of',
       'non-blank-string',
       'dependent-required',
+      'banned-keys',
     ]);
   });
 
@@ -462,6 +492,175 @@ describe('dependent-required: one dependency map, read twice', () => {
   });
 });
 
+describe('banned-keys: one key list, read twice', () => {
+  it('declares the keys it was given', () => {
+    const rule = bannedKeys(['dialect']);
+    expect(projectableRefinementOf(rule)).toEqual({ pattern: 'banned-keys', keys: ['dialect'] });
+  });
+
+  it('emits `propertyNames` with a `not` over the names, when the node states none', () => {
+    const node: Record<string, unknown> = { type: 'object' };
+    emitProjectableRefinement(node, { pattern: 'banned-keys', keys: ['a', 'b'] });
+    expect(node).toEqual({ type: 'object', propertyNames: { not: { enum: ['a', 'b'] } } });
+  });
+
+  it('conjoins through `allOf` rather than replacing the `propertyNames` a record already states', () => {
+    // A record emits `propertyNames: { type: 'string' }` of its own. Replacing
+    // it would trade the key-TYPE rule the node already stated for the key-NAME
+    // rule this arm adds, which is a narrowing paid for with a widening.
+    const node: Record<string, unknown> = { type: 'object', propertyNames: { type: 'string' } };
+    emitProjectableRefinement(node, { pattern: 'banned-keys', keys: ['dialect'] });
+    expect(node.propertyNames).toEqual({ type: 'string' });
+    expect(node.allOf).toEqual([{ propertyNames: { not: { enum: ['dialect'] } } }]);
+  });
+
+  it('⛔ never writes a TOP-LEVEL `anyOf` or disturbs the node’s own shape', () => {
+    const node: Record<string, unknown> = { type: 'object', properties: { a: { type: 'string' } } };
+    emitProjectableRefinement(node, { pattern: 'banned-keys', keys: ['b'] });
+    expect(node.anyOf).toBeUndefined();
+    expect(node.properties).toEqual({ a: { type: 'string' } });
+  });
+
+  it('is idempotent — the same arm twice states one rule, not two', () => {
+    const node: Record<string, unknown> = { type: 'object', propertyNames: { type: 'string' } };
+    emitProjectableRefinement(node, { pattern: 'banned-keys', keys: ['dialect'] });
+    emitProjectableRefinement(node, { pattern: 'banned-keys', keys: ['dialect'] });
+    expect(node.allOf).toEqual([{ propertyNames: { not: { enum: ['dialect'] } } }]);
+  });
+
+  it('drops an empty key list rather than publishing a rule that bans nothing', () => {
+    const node: Record<string, unknown> = { type: 'object' };
+    emitProjectableRefinement(node, { pattern: 'banned-keys', keys: [] });
+    expect(node).toEqual({ type: 'object' });
+  });
+
+  it('the predicate and the keywords agree over the whole presence lattice', () => {
+    const rule = bannedKeys(['x', 'y']);
+    const node = publish(z.record(z.string(), z.unknown()).refine(rule));
+    const keys = ['x', 'y', 'z'] as const;
+    for (let mask = 0; mask < 8; mask += 1) {
+      const doc: Record<string, unknown> = {};
+      keys.forEach((key, i) => {
+        if (mask & (1 << i)) doc[key] = 'v';
+      });
+      const asJson = JSON.parse(JSON.stringify(doc)) as Record<string, unknown>;
+      expect(
+        rule(asJson),
+        `runtime vs keywords disagree for ${JSON.stringify(asJson)}`,
+      ).toBe(bannedKeysSatisfied(node, asJson));
+    }
+  });
+
+  it('a banned key present with a `null` value is PRESENT on both sides', () => {
+    const rule = bannedKeys(['dialect']);
+    const node = publish(z.record(z.string(), z.unknown()).refine(rule));
+    const doc = JSON.parse('{"dialect":null}') as Record<string, unknown>;
+    expect(rule(doc)).toBe(false);
+    expect(bannedKeysSatisfied(node, doc)).toBe(false);
+  });
+
+  it('⛔ judges OWN properties — a name `Object.prototype` carries is not "present" in an empty document', () => {
+    // The measurement behind the predicate reading `hasOwnProperty` and never
+    // `key in value`: `in` walks the prototype chain, so a ban spelled with it
+    // would refuse `{}` itself while `propertyNames` accepts it. That is a
+    // disagreement about a JSON DOCUMENT, not an edge outside the domain.
+    const rule = bannedKeys(['toString']);
+    const node = publish(z.record(z.string(), z.unknown()).refine(rule));
+    const empty = JSON.parse('{}') as Record<string, unknown>;
+    expect('toString' in empty).toBe(true);
+    expect(rule(empty)).toBe(true);
+    expect(bannedKeysSatisfied(node, empty)).toBe(true);
+  });
+
+  it('LIT CONTROL — the same name written INTO the document is refused by both', () => {
+    const rule = bannedKeys(['toString']);
+    const node = publish(z.record(z.string(), z.unknown()).refine(rule));
+    const doc = JSON.parse('{"toString":"x"}') as Record<string, unknown>;
+    expect(rule(doc)).toBe(false);
+    expect(bannedKeysSatisfied(node, doc)).toBe(false);
+  });
+});
+
+describe("the LIVE seam: the card's own worked instance stops saying yes", () => {
+  /** The published structured-filter arm of `TraceSamplingConfig.composite[].condition`. */
+  const structuredFilterArm = (): Record<string, unknown> => {
+    const node = publish(TraceSamplingConfigSchema, 'input');
+    const composite = (node.properties as Record<string, Record<string, unknown>>).composite;
+    const item = composite.items as Record<string, Record<string, Record<string, unknown>>>;
+    const condition = item.properties.condition as unknown as Record<string, unknown>;
+    return (condition.anyOf as Record<string, unknown>[])[0];
+  };
+
+  /** A `TraceSamplingConfig` that parses, with only `condition` varying. */
+  const parses = (condition: unknown): boolean =>
+    TraceSamplingConfigSchema.safeParse({
+      type: 'composite',
+      composite: [{ strategy: 'always_on', condition }],
+    }).success;
+
+  it('states the ban, and keeps the record shape it always stated', () => {
+    const arm = structuredFilterArm();
+    expect(arm.type).toBe('object');
+    expect(arm.propertyNames).toEqual({ type: 'string' });
+    expect(arm.allOf).toEqual([{ propertyNames: { not: { enum: ['dialect'] } } }]);
+  });
+
+  it("the card's own specimen — `{ dialect: 'cel' }` — is refused by BOTH sides now", () => {
+    const doc = JSON.parse('{"dialect":"cel"}') as Record<string, unknown>;
+    expect(parses(doc)).toBe(false);
+    expect(bannedKeysSatisfied(structuredFilterArm(), doc)).toBe(false);
+  });
+
+  it('⛔ no document this arm ACCEPTS is refused by the emitted keywords', () => {
+    const arm = structuredFilterArm();
+    const rule = bannedKeys(['dialect']);
+    const corpus: Array<Record<string, unknown>> = [
+      {},
+      { amount: { $gt: 1 } },
+      { 'account.name': { $eq: 'acme' } },
+      { dialect: 'cel' },
+      { dialect: null },
+      { dialect: 'cel', source: 'record.amount > 10' },
+    ];
+    for (const doc of corpus) {
+      const asJson = JSON.parse(JSON.stringify(doc)) as Record<string, unknown>;
+      // Equality, not implication: this arm is exact, so a one-sided pin would
+      // pass a projection that had stopped narrowing at all.
+      expect(
+        bannedKeysSatisfied(arm, asJson),
+        `disagreement on ${JSON.stringify(asJson)}`,
+      ).toBe(rule(asJson));
+    }
+  });
+
+  it('⛔ and the EXPRESSION the runtime still accepts is still accepted by the file', () => {
+    // The union's other arm is what carries a dialect-bearing document, so
+    // narrowing the structured-filter arm refuses nothing the runtime accepts.
+    const doc = { dialect: 'cel', source: 'record.amount > 10' };
+    expect(parses(doc)).toBe(true);
+    const node = publish(TraceSamplingConfigSchema, 'input');
+    const composite = (node.properties as Record<string, Record<string, unknown>>).composite;
+    const item = composite.items as Record<string, Record<string, Record<string, unknown>>>;
+    const condition = item.properties.condition as unknown as Record<string, unknown>;
+    const envelope = (condition.anyOf as Record<string, unknown>[])[1];
+    const objectArm = (envelope.anyOf as Record<string, unknown>[])[1];
+    expect(objectArm.required).toEqual(['dialect', 'source']);
+  });
+
+  it('LIT CONTROL — a structured filter with no `dialect` is accepted by both', () => {
+    const doc = JSON.parse('{"amount":{"$gt":10}}') as Record<string, unknown>;
+    expect(parses(doc)).toBe(true);
+    expect(bannedKeysSatisfied(structuredFilterArm(), doc)).toBe(true);
+  });
+
+  it('its ledger row is gone because the site now reads `projected`, naming the arm', () => {
+    const census = collectDroppedRefinements('system/TraceSamplingConfig', TraceSamplingConfigSchema);
+    const site = census.projected.find((s) => s.path === 'composite.element.condition.options[0]');
+    expect(site?.declaredPatterns).toEqual(['banned-keys']);
+    expect(census.dropped.map((s) => s.path)).not.toContain('composite.element.condition.options[0]');
+  });
+});
+
 describe('the verdict is adjudicated per NODE over every check on it', () => {
   const nonBlank = (): z.ZodString => z.string().refine(NON_BLANK_STRING, 'non-blank');