@nodaro/prompts 1.7.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/prompts",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "description": "Nodaro's prompt-engineering layer — person/picker catalogs with prompt hints, identity-lock clauses, entity prompt builders, brand presets, and prompt/reference assembly shared by the Nodaro platform and SDK.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/src/__tests__/b7-person-pack-e2e.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, beforeEach } from "vitest"
+import { registerPersonPack, resetPersonPacks } from "../person-packs.js"
+import { resetCatalogPacks, getRegisteredCatalogPacks } from "../catalog-packs.js"
+import { getRegisteredPickerCatalogs, projectAllCatalogs } from "../picker-catalogs.js"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+import { computePackSidecarCoverage } from "../catalog-sidecar-coverage.js"
+import { PERSON_SECTOR_PACK } from "./fixtures/person-sector-pack.js"
+
+beforeEach(() => {
+  resetPersonPacks()
+  resetCatalogPacks()
+})
+
+describe("B7 person pack — one registration, every read kind", () => {
+  it("enumerates in the registered person catalog + /v1/catalogs projection", () => {
+    registerPersonPack(PERSON_SECTOR_PACK)
+    const person = getRegisteredPickerCatalogs().find((c) => c.catalogId === "person")!
+    expect(person.dimensions!.some((d) => d.field === "sectorAttire")).toBe(true)
+    const projected = projectAllCatalogs().find((c) => c.catalogId === "person")!
+    expect(projected.dimensions!.some((d) => d.options.some((o) => o.id === "attire-modest-suit"))).toBe(true)
+  })
+
+  it("composes a hint for the pack dimension", () => {
+    registerPersonPack(PERSON_SECTOR_PACK)
+    expect(
+      getParameterPromptHint({ id: "n1", type: "person", data: { sectorAttire: "attire-modest-suit" } }),
+    ).toContain("modest tailored suit")
+  })
+
+  it("reports the declared sidecar exemption (not a failure)", () => {
+    registerPersonPack(PERSON_SECTOR_PACK)
+    const pack = getRegisteredCatalogPacks().find((p) => p.id === PERSON_SECTOR_PACK.id)!
+    const cov = computePackSidecarCoverage(pack)
+    expect(cov.exempted.length).toBeGreaterThan(0) // e.g. hi/ja/ko/zh-CN/ru/ar declared exempt
+    expect(cov.missing.filter((m) => m.locale === "he")).toEqual([]) // he provided
+  })
+})

package/src/__tests__/catalog-funnel-ratchet.test.ts

@@ -0,0 +1,97 @@
+// Ratchet: freeze the set of prompts/src files that read a RAW BASE catalog
+// array (STYLES, MOODS, PEOPLE, …) directly instead of the pack-composed funnel
+// (`getRegisteredPickerCatalogs()` / `getRegisteredPeople()`). A file that reads
+// a raw array bypasses deployment-registered packs, so the seam only holds if
+// that set can only SHRINK.
+//
+// The watched array names are DERIVED from `picker-catalogs.ts`'s own value
+// imports — the ONE file that legitimately pulls every base array in to compose
+// the funnel — so a brand-new catalog is watched automatically (no hand-list to
+// drift). Substring/regex scan + a 4s ceiling (spec §3 finding 5: AST walks blew
+// the CI budget).
+import { describe, it, expect } from "vitest"
+import { readFileSync, readdirSync, statSync } from "node:fs"
+import { join, dirname, relative } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const SRC = join(dirname(fileURLToPath(import.meta.url)), "..")
+const FUNNEL = join(SRC, "picker-catalogs.ts")
+
+// Files allowed to read raw base arrays today, two kinds:
+//   • composition roots — the funnels the rest of the world reads FROM. These
+//     are NOT debt; they are where the base arrays legitimately enter.
+//   • tracked offenders — pending repoint (Phase-0 scope note). May only shrink.
+// A stale entry (a listed file that no longer reads a raw array) fails too, so
+// the list cannot rot: repointing a file means deleting its line here.
+const ALLOWLIST = new Set<string>([
+  "picker-catalogs.ts", // composition root: the aggregate funnel composes every base array
+  "person-packs.ts", // composition root: getRegisteredPeople() composes packs onto raw PEOPLE
+  "picker-analyzer-registry.ts", // tracked offender: describe-to-picker analyzer, repoint pending
+  "picker-wiring.ts", // tracked offender: repoint pending
+])
+
+describe("catalog funnel import ratchet", () => {
+  it("no NEW prompts file reads a raw base catalog array (funnel bypass)", () => {
+    const start = Date.now()
+    const watched = deriveWatchedArrays(readFileSync(FUNNEL, "utf8"))
+    // Guard the guard: if the derivation ever silently finds nothing (funnel
+    // moved/renamed), the whole ratchet would go vacuous — fail loudly instead.
+    expect(watched.size, "derivation found no base arrays — is picker-catalogs.ts still the funnel?").toBeGreaterThan(40)
+
+    const offenders = new Set<string>()
+    for (const f of walk(SRC)) {
+      if (!f.endsWith(".ts") || f.includes("__tests__")) continue
+      if (importsAnyOf(readFileSync(f, "utf8"), watched).length) offenders.add(relative(SRC, f))
+    }
+
+    const newOffenders = [...offenders].filter((f) => !ALLOWLIST.has(f)).sort()
+    expect(newOffenders, `New direct raw-array reader(s) — read the pack-composed funnel instead: ${newOffenders.join(", ")}`).toEqual([])
+
+    const stale = [...ALLOWLIST].filter((f) => !offenders.has(f)).sort()
+    expect(stale, `Stale ratchet allowlist entr(ies) — file no longer reads a raw array, delete the line: ${stale.join(", ")}`).toEqual([])
+
+    expect(Date.now() - start, "ratchet exceeded 4s ceiling").toBeLessThan(4000)
+  })
+})
+
+/**
+ * The raw base-array export names, DERIVED from the funnel's own value imports:
+ * uppercase identifiers (`STYLES`, `PEOPLE`, `ANIMALS`, …) minus the metadata
+ * siblings (`*_LABELS` / `*_ORDER` / `*_FIELD_BY_*`). `import type { … }` and
+ * `export … from` are ignored, so type re-exports and the defining modules never
+ * match.
+ */
+function deriveWatchedArrays(funnelSource: string): Set<string> {
+  const watched = new Set<string>()
+  for (const name of importedNames(funnelSource)) {
+    if (/^[A-Z][A-Z0-9_]*$/.test(name) && !/_LABELS$|_ORDER$|_FIELD_BY_/.test(name)) watched.add(name)
+  }
+  return watched
+}
+
+/** Names this source VALUE-imports (skips `import type {…}` and inline `type` specifiers). */
+function importedNames(source: string): string[] {
+  const names: string[] = []
+  const re = /import\s+(?:[\w*]+\s*,\s*)?\{([^}]*)\}\s*from\s*["'][^"']+["']/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(source))) {
+    for (let spec of m[1].split(",")) {
+      spec = spec.trim()
+      if (!spec || spec.startsWith("type ")) continue
+      names.push(spec.split(/\s+as\s+/)[0].trim())
+    }
+  }
+  return names
+}
+
+/** Watched names this source imports (the bypass signal). */
+function importsAnyOf(source: string, watched: Set<string>): string[] {
+  return [...new Set(importedNames(source).filter((n) => watched.has(n)))]
+}
+
+function walk(dir: string): string[] {
+  return readdirSync(dir).flatMap((n) => {
+    const p = join(dir, n)
+    return statSync(p).isDirectory() ? walk(p) : [p]
+  })
+}

package/src/__tests__/catalog-packs.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import type { PickerCatalog, PickerOption } from "../picker-catalogs.js"
+import type { PickerOptionInput, PickerCatalogInput } from "../catalog-packs.js"
+import {
+  registerCatalogPack, getRegisteredCatalogPacks, resetCatalogPacks,
+  catalogPacksVersion, composePickerCatalogs,
+  type CatalogPack,
+} from "../catalog-packs.js"
+import { getParameterPromptHint } from "../parameter-prompt-hint.js"
+import { getPickerCatalog } from "../picker-catalogs.js"
+
+const base: readonly PickerCatalog[] = [
+  { nodeType: "setting", label: "Setting", catalogId: "setting", kind: "single", valueField: "setting",
+    options: [
+      { id: "forest", label: "Forest", promptHint: "in a forest", term: "forest" },
+      { id: "beach", label: "Beach", promptHint: "on a beach", term: "beach" },
+    ] },
+]
+
+beforeEach(() => resetCatalogPacks())
+afterEach(() => resetCatalogPacks()) // never leak a pack into another file's registry view
+
+describe("composePickerCatalogs — pure", () => {
+  it("returns a structurally-equal NEW array when no packs (does not mutate base)", () => {
+    const out = composePickerCatalogs(base, [])
+    expect(out).toEqual(base)
+    expect(out).not.toBe(base)
+    expect(out[0]).not.toBe(base[0])
+  })
+
+  it("deny removes entry ids from the copy, leaving base untouched", () => {
+    const out = composePickerCatalogs(base, [{ id: "p", catalogId: "setting", mode: "deny", denyIds: ["beach"] }])
+    expect(out[0].options!.map((o: PickerOption) => o.id)).toEqual(["forest"])
+    expect(base[0].options!.map((o: PickerOption) => o.id)).toEqual(["forest", "beach"]) // base immutable
+  })
+
+  it("extend appends single-dim options", () => {
+    const out = composePickerCatalogs(base, [{ id: "p", catalogId: "setting", mode: "extend",
+      options: [{ id: "shul", label: "Shul", promptHint: "in a synagogue", term: "shul" }] }])
+    expect(out[0].options!.map((o: PickerOption) => o.id)).toEqual(["forest", "beach", "shul"])
+  })
+
+  it("replace swaps the catalog wholesale for its catalogId", () => {
+    const vendored: PickerCatalogInput = { nodeType: "setting", label: "Setting", catalogId: "setting", kind: "single",
+      valueField: "setting", options: [{ id: "forest", label: "Forest", promptHint: "in a forest", term: "forest" }] }
+    const out = composePickerCatalogs(base, [{ id: "p", catalogId: "setting", mode: "replace", catalog: vendored }])
+    expect(out[0].options!.map((o: PickerOption) => o.id)).toEqual(["forest"])
+  })
+
+  it("applies packs in registration order and throws for an unknown catalogId", () => {
+    expect(() => composePickerCatalogs(base, [{ id: "p", catalogId: "nope", mode: "deny", denyIds: ["x"] }]))
+      .toThrow(/unknown catalog id "nope"/i)
+  })
+})
+
+describe("registry + version", () => {
+  it("register bumps the version; reset clears and bumps", () => {
+    const v0 = catalogPacksVersion()
+    registerCatalogPack({ id: "a", catalogId: "setting", mode: "deny", denyIds: ["beach"] })
+    expect(getRegisteredCatalogPacks().map((p: CatalogPack) => p.id)).toEqual(["a"])
+    expect(catalogPacksVersion()).toBeGreaterThan(v0)
+    const v1 = catalogPacksVersion()
+    resetCatalogPacks()
+    expect(getRegisteredCatalogPacks()).toEqual([])
+    expect(catalogPacksVersion()).toBeGreaterThan(v1)
+  })
+
+  it("rejects a duplicate pack id", () => {
+    registerCatalogPack({ id: "a", catalogId: "setting", mode: "deny", denyIds: ["beach"] })
+    expect(() => registerCatalogPack({ id: "a", catalogId: "setting", mode: "deny", denyIds: ["forest"] }))
+      .toThrow(/duplicate/i)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Compact hint mode over pack-added options
+// ---------------------------------------------------------------------------
+
+/**
+ * `PickerOption.term` is REQUIRED at the type level, but a pack is compiled
+ * separately — a vendored bundle built against a `@nodaro/prompts` that predates
+ * `term` hands us an option object with no such property at run time. The cast
+ * reproduces that exactly; without composition-time resolution the option would
+ * inject its full hint in full mode and `undefined` (i.e. nothing) in compact.
+ */
+// A pack literal WITHOUT `term` must type-check against the pack input
+// types (`PickerOptionInput`) — `term` is author-optional and resolved at
+// composition. The helper is deliberately an identity on the INPUT type, not a
+// cast to the registry's output type.
+function legacyOption(o: Omit<PickerOption, "term">): PickerOptionInput {
+  return o as PickerOption
+}
+
+describe("pack options resolve a term at composition", () => {
+  it("extend: a term-less pack option gets the derived term", () => {
+    const out = composePickerCatalogs(base, [{
+      id: "legacy", catalogId: "setting", mode: "extend",
+      options: [legacyOption({ id: "shul-hall", label: "Shul Hall", promptHint: "in a synagogue hall" })],
+    }])
+    expect(out[0].options!.find((o: PickerOption) => o.id === "shul-hall")!.term).toBe("shul hall")
+  })
+
+  it("replace: a term-less vendored catalog gets terms too", () => {
+    const vendored: PickerCatalogInput = {
+      nodeType: "setting", label: "Setting", catalogId: "setting", kind: "single", valueField: "setting",
+      options: [
+        legacyOption({ id: "shtiebel", label: "Shtiebel (Small Shul)", promptHint: "in a small prayer room" }),
+        legacyOption({ id: "nowhere", label: "None", promptHint: "" }),
+      ],
+    }
+    const out = composePickerCatalogs(base, [{ id: "legacy", catalogId: "setting", mode: "replace", catalog: vendored }])
+    const terms = Object.fromEntries(out[0].options!.map((o: PickerOption) => [o.id, o.term]))
+    // Parentheticals are stripped, and a no-op entry stays empty.
+    expect(terms).toEqual({ shtiebel: "shtiebel", nowhere: "" })
+  })
+
+  it("a pack-added value injects in BOTH modes, never an empty compact fragment", () => {
+    registerCatalogPack({
+      id: "legacy", catalogId: "setting", mode: "extend",
+      options: [legacyOption({ id: "shul-hall", label: "Shul Hall", promptHint: "in a synagogue hall" })],
+    })
+    // The registry view is what the hint path reads.
+    const opt = getPickerCatalog("setting")!.options!.find((o: PickerOption) => o.id === "shul-hall")
+    expect(opt?.term).toBe("shul hall")
+
+    const node = { id: "n1", type: "setting", data: { setting: "shul-hall" } }
+    expect(getParameterPromptHint(node)).toBe("in a synagogue hall")
+    expect(getParameterPromptHint({ ...node, data: { ...node.data, hintMode: "compact" } })).toBe("shul hall")
+  })
+})

package/src/__tests__/catalog-sidecar-coverage.test.ts

@@ -0,0 +1,27 @@
+import { describe, it, expect } from "vitest"
+import { computePackSidecarCoverage } from "../catalog-sidecar-coverage.js"
+import type { CatalogPack } from "../catalog-packs.js"
+
+const pack: CatalogPack = {
+  id: "sai/setting", catalogId: "setting", mode: "extend",
+  options: [{ id: "shul-hall", label: "Shul Hall", promptHint: "in a synagogue hall", term: "shul hall" }],
+  sidecars: { he: { "shul-hall": { label: "אולם בית כנסת" } } },      // he present
+  exemptSidecarLocales: ["hi", "ja", "ko", "zh-CN", "ru", "ar"],       // declared exemption
+}
+
+describe("computePackSidecarCoverage", () => {
+  it("reports missing non-exempt locales and lists the declared exemptions", () => {
+    const r = computePackSidecarCoverage(pack)
+    // he ok; hi/ja/ko/zh-CN/ru/ar exempt; es/fr/de/pt-BR missing (1 entry each)
+    expect(r.exempted.map((e) => e.locale).sort()).toEqual(["ar", "hi", "ja", "ko", "ru", "zh-CN"].sort())
+    expect(r.missing.map((m) => m.locale).sort()).toEqual(["de", "es", "fr", "pt-BR"].sort())
+    expect(r.missing.every((m) => m.id === "shul-hall")).toBe(true)
+  })
+
+  it("full 11-locale coverage yields zero missing", () => {
+    const locales = ["es","fr","de","pt-BR","ru","hi","ja","ko","zh-CN","he","ar"] as const
+    const full: CatalogPack = { ...pack, exemptSidecarLocales: [],
+      sidecars: Object.fromEntries(locales.map((l) => [l, { "shul-hall": { label: "x" } }])) }
+    expect(computePackSidecarCoverage(full).missing).toEqual([])
+  })
+})

package/src/__tests__/catalog-terms.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from "vitest"
+import { PICKER_CATALOGS, type PickerOption } from "../picker-catalogs.js"
+import { TERM_MAX_CHARS, deriveTerm, isSuspiciousDerivedTerm } from "../term.js"
+
+/** A term is a phrase, not a sentence (see the convention in `term.ts`). */
+const TERM_MAX_WORDS = 8
+
+/**
+ * Two ids in one catalog may share a term ONLY where they are deliberately the
+ * same thing filed twice. `music-genre` cross-lists Amapiano under both the
+ * electronic and the global groupings, so both ids legitimately inject
+ * "amapiano". Anything else is a copy-paste that makes two picks
+ * indistinguishable downstream — widen this set only for another deliberate
+ * cross-listing, never to silence a collision.
+ */
+const DUPLICATE_TERM_EXCEPTIONS: ReadonlySet<string> = new Set(["music-genre • amapiano"])
+
+/**
+ * The compact-term guard.
+ *
+ * Every catalog option carries a `term` — the short professional phrase a
+ * consumer injects in compact hint mode. `term` is RESOLVED at build time
+ * (`resolveTerm`): an authored `term` on the catalog entry when there is one,
+ * the mechanically-derived label otherwise.
+ *
+ * The derivation is safe for the large majority of labels, and predictably
+ * WRONG for a few recognizable shapes — UI compounds ("None / Hard Cut",
+ * "Fog / Mist"), parenthetical annotations ("Ultra-wide (14mm)",
+ * "ISO 1600 (visible grain)"), and — in the catalogs listed below — bare
+ * modifier words that only become a trade term with their category noun
+ * attached. This test fails for exactly those entries, so the fix is to
+ * author an explicit `term` on the catalog entry rather than to ship a
+ * mangled fragment into every downstream prompt.
+ */
+
+/**
+ * Catalogs whose labels are MODIFIERS, not standalone terms: a single derived
+ * word there is suspicious and must be authored explicitly.
+ *
+ *  - `lighting`   — the standard trade terms literally contain the category
+ *                   noun: "Short"/"Broad"/"Loop"/"Butterfly"/"Split"/"Hard"
+ *                   mean nothing alone and must read "short lighting",
+ *                   "loop lighting", "hard light". They also collide head-on
+ *                   with common English words, which is the worst case for a
+ *                   bare injection.
+ *  - `color-look` — "Warm"/"Cool"/"Faded"/"Vibrant" are grade adjectives; the
+ *                   term a colorist writes is "warm grade", "cool grade".
+ *  - `mood`       — the labels are bare emotion adjectives ("Happy", "Sad",
+ *                   "Tense"). Injected alone a bare adjective has nothing to
+ *                   attach to; the catalog describes the SUBJECT's emotional
+ *                   state, so the term names the expression or demeanor the
+ *                   hint spells out — "melancholic expression", "cocky
+ *                   smirk". ("melancholic mood" would be the wrong register:
+ *                   it points the model at the scene, not the face.)
+ *
+ * Deliberately NOT in the set:
+ *  - `tone` is free text, not a catalog at all.
+ *  - `aesthetic` / `style` / `render-quality` bare labels are proper names of
+ *    the thing itself ("cottagecore", "noir", "octane render") — already the
+ *    professional term, so flagging them would be noise.
+ *  - the multi-dim `person` / `styling` dimensions are bare by nature (dozens
+ *    of one-word options per dimension); they are left out to keep this guard
+ *    a work list rather than a wall. Widen the set here when a dimension is
+ *    shown to inject ambiguously.
+ */
+const BARE_WORD_SUSPICIOUS_CATALOG_IDS: ReadonlySet<string> = new Set([
+  "lighting",
+  "color-look",
+  "mood",
+])
+
+interface Row {
+  readonly catalogId: string
+  readonly option: PickerOption
+}
+
+/** Every option in the frozen upstream base, single-dim + multi-dim alike. */
+function allRows(): Row[] {
+  const rows: Row[] = []
+  for (const c of PICKER_CATALOGS) {
+    for (const o of c.options ?? []) rows.push({ catalogId: c.catalogId, option: o })
+    for (const d of c.dimensions ?? []) {
+      for (const o of d.options) rows.push({ catalogId: c.catalogId, option: o })
+    }
+  }
+  return rows
+}
+
+const ROWS = allRows()
+
+describe("catalog compact terms", () => {
+  it("walks a non-trivial number of options", () => {
+    expect(ROWS.length).toBeGreaterThan(1000)
+  })
+
+  it("every label whose derived term is unsafe has an explicit term authored", () => {
+    const flagged: string[] = []
+    for (const { catalogId, option } of ROWS) {
+      const bareWordSuspicious = BARE_WORD_SUSPICIOUS_CATALOG_IDS.has(catalogId)
+      if (!isSuspiciousDerivedTerm(option.label, { bareWordSuspicious })) continue
+      const derived = deriveTerm(option.label)
+      // An authored term is anything that is NOT just the derivation; when the
+      // two are equal, nothing was authored and the mangled form would ship.
+      if (option.term !== derived) continue
+      flagged.push(`${catalogId} • ${option.id} • ${option.label} → ${derived}`)
+    }
+    expect(
+      flagged,
+      `${flagged.length} catalog entries need an explicit \`term\` (label cannot be safely lowercased):\n${flagged.join("\n")}`,
+    ).toEqual([])
+  })
+
+  it("every resolved term is well-formed", () => {
+    const bad: string[] = []
+    for (const { catalogId, option } of ROWS) {
+      const term = option.term
+      const where = `${catalogId} • ${option.id} • ${option.label}`
+      if (typeof term !== "string") {
+        bad.push(`${where} → term is not a string (a builder path forgot to resolve it)`)
+        continue
+      }
+      if (term.length > TERM_MAX_CHARS) {
+        bad.push(`${where} → ${term.length} chars, over the ${TERM_MAX_CHARS} cap: "${term}"`)
+      }
+      if (term.includes("\n")) bad.push(`${where} → contains a newline: ${JSON.stringify(term)}`)
+      if (term.endsWith(".")) bad.push(`${where} → ends with a period: "${term}"`)
+      if (term === "" && option.promptHint !== "") {
+        bad.push(`${where} → empty term on an entry that DOES inject a hint`)
+      }
+      const words = term.trim().split(/\s+/).filter(Boolean)
+      if (words.length > TERM_MAX_WORDS) {
+        bad.push(`${where} → ${words.length} words, over the ${TERM_MAX_WORDS} cap: "${term}"`)
+      }
+    }
+    expect(bad, `${bad.length} malformed terms:\n${bad.join("\n")}`).toEqual([])
+  })
+
+  it("no two ids in a catalog resolve to the same term", () => {
+    const byCatalog = new Map<string, Map<string, string[]>>()
+    for (const { catalogId, option } of ROWS) {
+      if (!option.term) continue // no-op "auto"/"none" entries all inject nothing
+      let terms = byCatalog.get(catalogId)
+      if (!terms) byCatalog.set(catalogId, (terms = new Map()))
+      const ids = terms.get(option.term)
+      if (ids) ids.push(option.id)
+      else terms.set(option.term, [option.id])
+    }
+    const collisions: string[] = []
+    for (const [catalogId, terms] of byCatalog) {
+      for (const [term, ids] of terms) {
+        const unique = [...new Set(ids)]
+        if (unique.length < 2) continue
+        if (DUPLICATE_TERM_EXCEPTIONS.has(`${catalogId} • ${term}`)) continue
+        collisions.push(`${catalogId} • "${term}" ← ${unique.join(", ")}`)
+      }
+    }
+    expect(
+      collisions,
+      `${collisions.length} terms are shared by two ids, so the two picks inject the same fragment:\n${collisions.join("\n")}`,
+    ).toEqual([])
+  })
+})

package/src/__tests__/character-default-role.test.ts

@@ -48,8 +48,9 @@ describe("characterLockToRefLock", () => {
     expect(lock.text).toContain("must match exactly")
   })
 
-  it("coerces undefined -> soft (DEFAULT_IDENTITY_LOCK, the accepted back-compat behavior)", () => {
-    expect(characterLockToRefLock(undefined)).toEqual(characterLockToRefLock("soft"))
+  it("coerces undefined -> off (DEFAULT_IDENTITY_LOCK: characters default to no lock)", () => {
+    expect(characterLockToRefLock(undefined)).toEqual(characterLockToRefLock("off"))
+    expect(characterLockToRefLock(undefined)).toEqual({ enabled: false })
   })
 
   it("soft and strict escalate like getIdentityLockClause but stay reference-bound", () => {

package/src/__tests__/content-free-contract.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest"
+import { readFileSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+/**
+ * Content-free contract guard for @nodaro/prompts (FSL-1.1-Apache-2.0).
+ *
+ * Every published version of this package is an IRREVOCABLE grant, so it must
+ * carry no deployment-specific prompt content and no machinery that switches
+ * prompt output on the deployment's environment. A fixed clause a deployment
+ * folds into prompts (a "modesty" clause, a brand-safety negative, a forced
+ * vocal gender) is the DEPLOYMENT's own content: it lives in that deployment's
+ * registered `PromptPolicy` module (backend/src/lib/prompt-policy.ts — applied
+ * server-side, after this package's pure assembly runs), never in this package
+ * and never read from `process.env` inside this package.
+ *
+ * The concrete, generic signature of a violation is a `process.env` read in the
+ * package source: it is how the earlier fork gated a clause
+ * (`process.env.<FLAG> === "true"`), and a published package that branches on a
+ * deployment env var is by construction carrying deployment behavior. This is a
+ * capability/invariant guard, not a customer-symbol denylist — it names no
+ * deployment and stays correct as new prompt content is added.
+ *
+ * __tests__ is excluded (never bundled at runtime; and a guard necessarily
+ * mentions the pattern it forbids).
+ */
+function walk(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name)
+    if (statSync(p).isDirectory()) return name === "__tests__" ? [] : walk(p)
+    return p.endsWith(".ts") ? [p] : []
+  })
+}
+
+// packages/prompts/src/__tests__ -> packages/prompts/src
+const SRC_DIR = join(__dirname, "..")
+
+describe("content-free contract", () => {
+  it("no prompts source file reads process.env (deployment content must live in a registered PromptPolicy, not this package)", () => {
+    const offenders = walk(SRC_DIR).filter((f) =>
+      /process\s*\.\s*env\b/.test(readFileSync(f, "utf8")),
+    )
+    expect(offenders).toEqual([])
+  })
+})

package/src/__tests__/dod-replace-pack-acceptance.test.ts

@@ -0,0 +1,41 @@
+// DoD (spec §8 Phase 0): "SAI resets the 23 catalog files to upstream and
+// adopts its vendored packs by registration." In-package form: a full vendored
+// copy of a catalog registered as `replace` is adopted everywhere by
+// registration alone, with the upstream base left byte-identical.
+import { describe, it, expect, beforeEach } from "vitest"
+import {
+  PICKER_CATALOGS,
+  getPickerCatalog,
+  getRegisteredPickerCatalogs,
+  projectAllCatalogs,
+} from "../picker-catalogs.js"
+import { registerCatalogPack, resetCatalogPacks } from "../catalog-packs.js"
+import type { PickerCatalog } from "../picker-catalogs.js"
+
+beforeEach(() => resetCatalogPacks())
+
+describe("DoD — adopt a vendored replacement pack by registration", () => {
+  it("replaces one catalog wholesale across every read; base untouched", () => {
+    const upstreamMood = PICKER_CATALOGS.find((c) => c.catalogId === "mood")!
+    const upstreamSnapshot = JSON.stringify(PICKER_CATALOGS)
+
+    // SAI's vendored full copy: same shape, curated option set.
+    const vendored: PickerCatalog = {
+      ...upstreamMood,
+      options: [
+        { id: "calm", label: "Calm", promptHint: "with a calm mood", term: "calm", category: upstreamMood.options![0].category },
+      ],
+    }
+    registerCatalogPack({ id: "sai/mood", catalogId: "mood", mode: "replace", catalog: vendored })
+
+    // Every funnel/route/enumeration reflects the vendored copy…
+    expect(getPickerCatalog("mood")!.options!.map((o) => o.id)).toEqual(["calm"])
+    expect(getRegisteredPickerCatalogs().find((c) => c.catalogId === "mood")!.options!.map((o) => o.id)).toEqual([
+      "calm",
+    ])
+    expect(projectAllCatalogs().find((c) => c.catalogId === "mood")!.options!.map((o) => o.id)).toEqual(["calm"])
+
+    // …while the frozen upstream base is byte-identical (invariant: never edited in place).
+    expect(JSON.stringify(PICKER_CATALOGS)).toBe(upstreamSnapshot)
+  })
+})