fix(spec): stop the i18n index pointing at five schemas a translation bundle cannot reach

The `objectstack-i18n` core list is correct; the damage was downstream, in the
transitive closure. Eight pointers shipped in that index and seven arrived
through a single edge: `shared/strict-object.ts` imports
`shared/suggestions.zod.ts` for its "did you mean?" text, which imports
`data/field.zod.ts`, which drags in filter, expression, field-value,
identifiers and value-domain. That is a schema-building helper's
implementation, not the authorable shape of a translation bundle -- which
addresses everything by name string. The largest of them, the Unified Query
DSL, is a different skill's whole subject, shipped into every i18n session with
an instruction to read it.

The feasibility question the finding asked -- a general reachability rule, or a
per-package list -- is answered first, and against the general rule. Cutting
traversal through non-shipping helpers is the precise version of that rule, and
it removes five of the five pointers named; it also removes
`shared/identifiers.zod.ts`, which must STAY (bundle keys are exactly those
`snake_case` identifiers, and the SKILL.md spends a table and a "Critical:" note
on it, while nothing imports the file), and it keeps
`kernel/metadata-protection.zod.ts`, which must go (a first-class direct
import). A depth-4 pointer reached through a helper belongs on the keep side
and a depth-1 pointer reached through a schema edge on the drop side: no
predicate over the import graph orders those that way, because the fact that
separates them is not in the graph.

So: a per-package allowlist beside the map, opt-in, with a guard that refuses a
package name the map does not have, a file the closure never reaches, a file
that is already core, and a repeat. An allowlist rather than a denylist because
`shared/value-domain.zod.ts` joined this index recently and unnoticed, when a
new import edge appeared several files away -- a denylist misses every new
arrival by construction. `data/field.zod.ts` is kept deliberately:
`FieldTranslationSchema.options` is keyed by select-option value, and
`SelectOptionSchema` is the declaration those keys must match.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2oQebDDxYKfWZusyd8GXk

Author: claude

packages/spec/scripts/build-skill-references.ts

@@ -30,8 +30,10 @@ import { findModuleDocBlock } from './lib/file-description';
 import { createSink, type Owns } from './lib/generated-output';
 import {
   SHARED_CORE_SCHEMAS,
+  TRANSITIVE_ALLOWLIST,
   checkCoreEntryShape,
   checkSingleOwner,
+  checkTransitiveAllowlist,
 } from './lib/skill-map-guards';
 
 // ── Paths ────────────────────────────────────────────────────────────────────
@@ -396,6 +398,14 @@ function main() {
   ];
   let totalSkills = 0;
 
+  // The allowlist guard needs each package's closure, so the closures are
+  // resolved once, up front, and reused by the emit loop below.
+  const closures: Record<string, string[]> = {};
+  for (const [skillName, coreFiles] of Object.entries(SKILL_MAP)) {
+    closures[skillName] = resolveAll(coreFiles).files;
+  }
+  problems.push(...checkTransitiveAllowlist(SKILL_MAP, TRANSITIVE_ALLOWLIST, closures));
+
   for (const [skillName, coreFiles] of Object.entries(SKILL_MAP)) {
     const skillDir = path.resolve(SKILLS_DIR, skillName);
     if (!fs.existsSync(skillDir)) {
@@ -404,8 +414,19 @@ function main() {
     }
 
     console.log(`📦 ${skillName}`);
-    const { files: allFiles, missing } = resolveAll(coreFiles);
+    const { files: resolved, missing } = resolveAll(coreFiles);
     for (const m of missing) problems.push(`${skillName} → ${m} (no such file under packages/spec/src)`);
+
+    // A package that declares a transitive allowlist publishes its core files
+    // plus exactly those pointers; one that declares none publishes the whole
+    // closure, as before. See TRANSITIVE_ALLOWLIST for why the constraint is a
+    // hand-authored list and not a rule over the import graph.
+    const allowed = TRANSITIVE_ALLOWLIST[skillName];
+    const coreSet = new Set(coreFiles);
+    const allFiles =
+      allowed === undefined
+        ? resolved
+        : resolved.filter((f) => coreSet.has(f) || allowed.includes(f));
     console.log(`   ${coreFiles.length} core + ${allFiles.length - coreFiles.length} deps`);
 
     const refsDir = path.resolve(skillDir, 'references');

packages/spec/scripts/lib/skill-map-guards.ts

@@ -134,6 +134,118 @@ export function checkSingleOwner(map: SkillCoreMap, shared: Record<string, strin
   return problems;
 }
 
+/**
+ * Which transitive pointers a package publishes, when the closure is wrong.
+ *
+ * ## The feasibility question this answers, decided before anything was built
+ *
+ * The closure walks every local `import ... from` edge out of a package's core
+ * files. Two routes were on the table for constraining it: (1) a REACHABILITY
+ * RULE -- follow only imports the package's authorable face can reach, which
+ * would generalise to every package; (2) a per-package list beside the map,
+ * which fixes one package at a time. Route 1 is the better shape IF it can be
+ * made precise. It cannot, and the measurement is specific rather than
+ * hand-wavy:
+ *
+ *  - `objectstack-i18n` publishes eight transitive pointers, and SEVEN of them
+ *    arrive through one edge -- `shared/strict-object.ts` imports
+ *    `shared/suggestions.zod.ts` for its "did you mean?" text, which imports
+ *    `data/field.zod.ts`, which drags in filter, expression, field-value,
+ *    identifiers and value-domain. That is a schema-building HELPER's
+ *    implementation, not the authorable shape of a translation bundle. Cutting
+ *    traversal through non-shipping helpers is the obvious precise rule, and it
+ *    removes five of the five pointers the finding names.
+ *  - It also removes `shared/identifiers.zod.ts`, which MUST STAY: a bundle's
+ *    object and field keys are the `snake_case` identifiers that file defines,
+ *    and the SKILL.md spends a table and a "Critical:" note on exactly that.
+ *    No import edge expresses it -- `system/translation.zod.ts` does not import
+ *    the file at all, because a bundle addresses everything by NAME STRING.
+ *  - And it KEEPS `kernel/metadata-protection.zod.ts`, which must go: that one
+ *    is a first-class direct `.zod.ts` import of `translation.zod.ts`.
+ *
+ * So the required outcome puts a depth-4 pointer reached through a helper on
+ * the KEEP side and a depth-1 pointer reached through a schema edge on the DROP
+ * side. No predicate over the import graph orders those two that way, because
+ * the fact that separates them -- what a translation bundle can address -- is
+ * not in the graph. Route 1 is therefore not merely unbuilt here; it is
+ * unbuildable from this input, and route 2 is what ships.
+ *
+ * The list is an ALLOWLIST, not a denylist, and that is the half that keeps it
+ * from rotting the way the closure did: `shared/value-domain.zod.ts` joined the
+ * i18n index recently, unnoticed, when a new import edge appeared several files
+ * away. An allowlist cannot silently gain a row; a denylist silently misses
+ * every new arrival.
+ *
+ * A package with NO entry here publishes its full closure, unchanged. Declaring
+ * a list is a claim about that package's authorable face, and only a package
+ * whose face someone has actually read should carry one.
+ */
+export const TRANSITIVE_ALLOWLIST: Record<string, readonly string[]> = {
+  // Everything else the closure reaches here is `strictObject()`'s error-message
+  // machinery and what that drags behind it -- the Unified Query DSL among them,
+  // a different skill's whole subject, shipped into every i18n session with an
+  // instruction to read it.
+  'objectstack-i18n': [
+    // Bundle keys ARE these identifiers: `objects.<name>.fields.<name>` must
+    // match the `snake_case` names the object and field schemas declare, which
+    // the SKILL.md states as a "Critical:" rule with its own table.
+    'shared/identifiers.zod.ts',
+    // `FieldTranslationSchema.options` is keyed by select-option VALUE, and the
+    // SKILL.md teaches that keying by example. `SelectOptionSchema` -- the
+    // declaration those keys must match -- lives here.
+    'data/field.zod.ts',
+  ],
+};
+
+/**
+ * A declared transitive allowlist must name a real package and reachable files.
+ *
+ * The list is hand-authored, and a hand-authored list that can quietly say
+ * nothing is the same defect one layer up: a typo'd package name would leave
+ * the over-eager closure fully published while the map LOOKS constrained, and a
+ * file the closure never reaches would read as a pointer that is being kept
+ * when it was never there to keep.
+ */
+export function checkTransitiveAllowlist(
+  map: SkillCoreMap,
+  allowlist: Record<string, readonly string[]>,
+  closures: Record<string, readonly string[]>,
+): string[] {
+  const problems: string[] = [];
+  for (const [skillName, allowed] of Object.entries(allowlist)) {
+    const coreFiles = map[skillName];
+    if (coreFiles === undefined) {
+      problems.push(
+        `TRANSITIVE_ALLOWLIST names ${skillName}, which is not a SKILL_MAP package — ` +
+          `the list would constrain nothing. Fix the name or delete the entry.`,
+      );
+      continue;
+    }
+    const core = new Set(coreFiles);
+    const closure = new Set(closures[skillName] ?? []);
+    const seen = new Set<string>();
+    for (const rel of allowed) {
+      if (seen.has(rel)) {
+        problems.push(`${skillName} → ${rel} is listed twice in TRANSITIVE_ALLOWLIST.`);
+        continue;
+      }
+      seen.add(rel);
+      if (core.has(rel)) {
+        problems.push(
+          `${skillName} → ${rel} is already a core entry; listing it as a transitive ` +
+            `pointer says it is both, and the index would name it once regardless.`,
+        );
+      } else if (!closure.has(rel)) {
+        problems.push(
+          `${skillName} → ${rel} is in TRANSITIVE_ALLOWLIST but nothing in the package's ` +
+            `core closure imports it — this row keeps a pointer that does not exist.`,
+        );
+      }
+    }
+  }
+  return problems;
+}
+
 /**
  * Every core entry must be a path this generator can actually publish.
  *

packages/spec/scripts/skill-map-guards.test.ts

@@ -34,8 +34,10 @@ import { describe, expect, it } from 'vitest';
 
 import {
   SHARED_CORE_SCHEMAS,
+  TRANSITIVE_ALLOWLIST,
   checkCoreEntryShape,
   checkSingleOwner,
+  checkTransitiveAllowlist,
   type SkillCoreMap,
 } from './lib/skill-map-guards';
 
@@ -115,6 +117,70 @@ describe('checkSingleOwner — one schema file, one owning package', () => {
   });
 });
 
+describe('checkTransitiveAllowlist — a constraint that constrains nothing is refused', () => {
+  const map: SkillCoreMap = { 'objectstack-i18n': ['system/translation.zod.ts'] };
+  const closures = {
+    'objectstack-i18n': ['system/translation.zod.ts', 'shared/identifiers.zod.ts'],
+  };
+
+  it('accepts a list naming a file the closure really reaches', () => {
+    expect(
+      checkTransitiveAllowlist(map, { 'objectstack-i18n': ['shared/identifiers.zod.ts'] }, closures),
+    ).toEqual([]);
+  });
+
+  it('accepts an empty list — publishing no transitive pointer is a real answer', () => {
+    expect(checkTransitiveAllowlist(map, { 'objectstack-i18n': [] }, closures)).toEqual([]);
+  });
+
+  it('refuses a package name that is not in the map', () => {
+    // The failure this exists for: a typo leaves the over-eager closure fully
+    // published while the map LOOKS constrained.
+    const problems = checkTransitiveAllowlist(map, { 'objectstack-i18nn': [] }, closures);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('not a SKILL_MAP package');
+  });
+
+  it('refuses a file the closure never reaches', () => {
+    const problems = checkTransitiveAllowlist(
+      map,
+      { 'objectstack-i18n': ['data/query.zod.ts'] },
+      closures,
+    );
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('does not exist');
+  });
+
+  it('refuses a file that is already a core entry', () => {
+    const problems = checkTransitiveAllowlist(
+      map,
+      { 'objectstack-i18n': ['system/translation.zod.ts'] },
+      closures,
+    );
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('already a core entry');
+  });
+
+  it('refuses a file listed twice', () => {
+    const problems = checkTransitiveAllowlist(
+      map,
+      { 'objectstack-i18n': ['shared/identifiers.zod.ts', 'shared/identifiers.zod.ts'] },
+      closures,
+    );
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain('listed twice');
+  });
+
+  it('every shipped list names a package the map has', () => {
+    // The one fact about the real list this file can assert without re-running
+    // the generator; reachability of each row is `check:skill-refs`'s job,
+    // because only it has the closure.
+    for (const skillName of Object.keys(TRANSITIVE_ALLOWLIST)) {
+      expect(skillName).toMatch(/^objectstack-/);
+    }
+  });
+});
+
 describe('the generator wires the guards in', () => {
   const source = (): string => fs.readFileSync(GENERATOR, 'utf-8');
 
@@ -131,4 +197,11 @@ describe('the generator wires the guards in', () => {
   it('calls checkSingleOwner on SKILL_MAP and the declared ledger', () => {
     expect(source()).toContain('checkSingleOwner(SKILL_MAP, SHARED_CORE_SCHEMAS)');
   });
+
+  it('calls checkTransitiveAllowlist, and filters the emitted set by the list', () => {
+    // Both halves matter: the guard alone would validate a list the emit path
+    // never reads, which is the shape of a constraint that constrains nothing.
+    expect(source()).toContain('checkTransitiveAllowlist(SKILL_MAP, TRANSITIVE_ALLOWLIST, closures)');
+    expect(source()).toContain('allowed.includes(f)');
+  });
 });

skills/objectstack-i18n/references/_index.md

@@ -14,14 +14,8 @@ from `node_modules` — there is no local copy in the skill bundle.
 
 ## Transitive dependencies
 
-- `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1).
 - `node_modules/@objectstack/spec/src/data/field.zod.ts` — Exports: FieldType, SelectOptionSchema, LocationCoordinatesSchema, CurrencyConfigSchema, CurrencyValueSchema
-- `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification
-- `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010)
-- `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol
 - `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — Exports: SystemIdentifierSchema, SnakeCaseIdentifierSchema, MetadataItemNameSchema
-- `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities
-- `node_modules/@objectstack/spec/src/shared/value-domain.zod.ts` — Standard value domains: one closed vocabulary and one membership predicate for settings and fields.
 
 ## How to read these