feat(protocol): validate requirement-id uniqueness in CI (#2050) (#2098)

Protocol 1.0 ratification requires requirement ids to be unique and validated in
CI (#2050), but nothing enforced it — `sync-suite.ts` only checked
the vendored suite's file digests against the lock, and the catalog schema has no
uniqueness constraint. A duplicate id arriving from the RFC source would go
unnoticed.

Add `checkCatalog()` to the `protocol:check` path: it loads the vendored
`catalog.json`, asserts every requirement has a non-empty string id, and fails on
any duplicate. Extracted `duplicateRequirementIds` as a pure, unit-tested helper,
and guarded the CLI dispatch behind `import.meta.main` so the module is
importable (matching the sibling protocol scripts).

Scopes only the "unique + validated in CI" acceptance criterion of #2050; the
normative inventory, profile/badge ratification, and whitepaper authoring live in
the rfcs/whitepaper repos and remain open.

Author: glennmichael123

scripts/protocol/sync-suite.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'bun:test'
+import { duplicateRequirementIds } from './sync-suite'
+
+// Protocol 1.0 ratification requires requirement ids to be unique and validated
+// in CI (stacksjs/stacks#2050). `protocol:check` now enforces this on the
+// vendored catalog; these cover the pure detector plus a regression guard on
+// the real catalog.
+describe('protocol requirement-id uniqueness (stacksjs/stacks#2050)', () => {
+  it('reports no duplicates for a unique list', () => {
+    expect(duplicateRequirementIds(['CORE-CONV-01', 'CORE-CONV-02', 'CORE-MVA-01'])).toEqual([])
+  })
+
+  it('reports each duplicated id once, sorted', () => {
+    expect(duplicateRequirementIds(['B-1', 'A-1', 'B-1', 'A-1', 'A-1', 'C-1'])).toEqual(['A-1', 'B-1'])
+  })
+
+  it('handles an empty list', () => {
+    expect(duplicateRequirementIds([])).toEqual([])
+  })
+
+  it('the vendored catalog.json has unique requirement ids', () => {
+    const catalog = JSON.parse(readFileSync(resolve(import.meta.dir, '../../protocol/suite/1.0-draft/catalog.json'), 'utf8')) as {
+      requirements: Array<{ id: string }>
+    }
+    const ids = catalog.requirements.map(requirement => requirement.id)
+    expect(ids.length).toBeGreaterThan(0)
+    expect(duplicateRequirementIds(ids)).toEqual([])
+  })
+})

scripts/protocol/sync-suite.ts

@@ -89,14 +89,59 @@ function checkSnapshot(): void {
   console.log(`Protocol suite matches ${basename(lock.sourceRepository)}@${lock.rfcsRevision} (${actualFiles.length} files)`)
 }
 
-if (process.argv.includes('--write')) {
-  const source = resolve(argument('--source') || process.env.STACKS_RFC_SOURCE || resolve(root, '../rfcs'))
-  writeSnapshot(source)
+/** Requirement ids that appear more than once in `ids` (sorted, deduped). */
+export function duplicateRequirementIds(ids: string[]): string[] {
+  const seen = new Set<string>()
+  const duplicates = new Set<string>()
+  for (const id of ids) {
+    if (seen.has(id))
+      duplicates.add(id)
+    else
+      seen.add(id)
+  }
+  return [...duplicates].sort()
 }
-else if (process.argv.includes('--check')) {
-  checkSnapshot()
+
+/**
+ * Validate the vendored requirement catalog: every requirement carries a
+ * non-empty string id and those ids are unique. Protocol 1.0 ratification
+ * requires requirement ids to be unique and validated in CI
+ * (stacksjs/stacks#2050); the vendored `catalog.json` had no such check, so a
+ * duplicate id sneaking in from the RFC source would go unnoticed.
+ */
+function checkCatalog(): void {
+  const catalogPath = resolve(suiteRoot, 'catalog.json')
+  if (!existsSync(catalogPath))
+    throw new Error(`protocol catalog missing at ${relative(root, catalogPath)}; run bun run protocol:sync`)
+
+  const catalog = JSON.parse(readFileSync(catalogPath, 'utf8')) as { requirements?: Array<{ id?: unknown }> }
+  const requirements = Array.isArray(catalog.requirements) ? catalog.requirements : []
+  if (requirements.length === 0)
+    throw new Error('protocol catalog has no requirements')
+
+  const ids = requirements.map(requirement => requirement?.id)
+  const missing = ids.filter(id => typeof id !== 'string' || id.length === 0).length
+  if (missing > 0)
+    throw new Error(`protocol catalog has ${missing} requirement(s) without a string id`)
+
+  const duplicates = duplicateRequirementIds(ids as string[])
+  if (duplicates.length > 0)
+    throw new Error(`protocol catalog has duplicate requirement id(s): ${duplicates.join(', ')}`)
+
+  console.log(`Protocol catalog: ${ids.length} requirement ids, all unique`)
 }
-else {
-  console.error('usage: bun scripts/protocol/sync-suite.ts --write [--source ../rfcs] | --check')
-  process.exit(2)
+
+if (import.meta.main) {
+  if (process.argv.includes('--write')) {
+    const source = resolve(argument('--source') || process.env.STACKS_RFC_SOURCE || resolve(root, '../rfcs'))
+    writeSnapshot(source)
+  }
+  else if (process.argv.includes('--check')) {
+    checkSnapshot()
+    checkCatalog()
+  }
+  else {
+    console.error('usage: bun scripts/protocol/sync-suite.ts --write [--source ../rfcs] | --check')
+    process.exit(2)
+  }
 }