@stacksjs/buddy 0.70.162 → 0.70.164

package/dist/commands/protocol/run-driver-contracts.js

@@ -0,0 +1,94 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { arch, platform } from "node:os";
+import { resolve } from "node:path";
+import { capabilityRegistry } from "../../../../config/src/capabilities";
+const root = resolve(import.meta.dir, "../../../../../../.."), reportRoot = resolve(process.env.PROTOCOL_REPORT_DIR || resolve(root, ".github/protocol/reports"));
+export function planDriverContracts(drivers) {
+  const tests = [...new Set(drivers.filter((driver) => driver.status === "supported").flatMap((driver) => driver.testEvidence))].sort(), records = drivers.map((driver) => ({
+    ...driver,
+    execution: driver.status === "supported" ? "run" : "not-run",
+    reason: driver.status === "supported" ? null : `Maturity is ${driver.status}; prerequisites and missing evidence are reported without promotion.`
+  }));
+  return { tests, records };
+}
+function sqliteVersion() {
+  const database = new Database(":memory:");
+  try {
+    return database.query("select sqlite_version() as version").get().version;
+  } finally {
+    database.close();
+  }
+}
+function markdown(report) {
+  const rows = report.drivers.map((driver) => `| ${driver.category} | ${driver.name} | ${driver.maturity} | ${driver.execution} | ${driver.topology} | ${driver.reason || "Retained test paths passed."} |`).join(`
+`);
+  return `# Stacks driver contract matrix
+
+- Source: \`${report.sourceRevision}\`
+- Runtime: Bun \`${report.environment.runtime.version}\` on \`${report.environment.platform.os}/${report.environment.platform.architecture}\`
+- SQLite: \`${report.environment.services.sqlite}\`
+- Redis: \`${report.environment.services.redis.version}\` at \`${report.environment.services.redis.topology}\`
+- Test files: ${report.testRun.files.length}
+- Result: **${report.testRun.status}**
+
+| Category | Driver | Maturity | Execution | Topology | Evidence boundary |
+| --- | --- | --- | --- | --- | --- |
+${rows}
+`;
+}
+export function runDriverContracts() {
+  const plan = planDriverContracts(capabilityRegistry);
+  if (!plan.tests.length)
+    throw Error("No supported driver contracts were selected");
+  const revisionResult = Bun.spawnSync(["git", "rev-parse", "HEAD"], { cwd: root });
+  if (revisionResult.exitCode !== 0)
+    throw Error("Could not resolve the Stacks revision");
+  const started = performance.now(), result = Bun.spawnSync(["bun", "test", ...plan.tests], { cwd: root, stdout: "inherit", stderr: "inherit" }), durationMs = Math.round(performance.now() - started), status = result.exitCode === 0 ? "pass" : "fail", report = {
+    schemaVersion: "1.0.0",
+    sourceRevision: revisionResult.stdout.toString().trim(),
+    environment: {
+      runtime: { name: "bun", version: Bun.version },
+      platform: { os: platform(), architecture: arch() },
+      ci: process.env.GITHUB_ACTIONS === "true" ? "github-actions" : "local",
+      services: {
+        sqlite: sqliteVersion(),
+        redis: {
+          version: process.env.REDIS_SERVICE_VERSION || "unreported",
+          url: process.env.REDIS_URL ? "redis://127.0.0.1:6379/0" : "not provisioned",
+          topology: "single-node loopback process provisioned by Pantry Action"
+        },
+        otherExternal: "not provisioned; partial/experimental drivers are not promoted"
+      }
+    },
+    testRun: { status, durationMs, files: plan.tests },
+    drivers: plan.records.map((driver) => ({
+      category: driver.category,
+      name: driver.name,
+      maturity: driver.status,
+      execution: driver.execution === "run" ? status : driver.execution,
+      topology: driver.topology,
+      prerequisites: driver.prerequisites,
+      evidence: driver.testEvidence,
+      limitations: driver.limitations,
+      reason: driver.reason
+    }))
+  };
+  mkdirSync(reportRoot, { recursive: !0 });
+  writeFileSync(resolve(reportRoot, "driver-matrix.json"), `${JSON.stringify(report, null, 2)}
+`);
+  writeFileSync(resolve(reportRoot, "driver-matrix.md"), markdown(report));
+  if (status === "fail")
+    throw Error("Supported driver contract tests failed");
+  console.log(`Driver contract matrix passed ${plan.tests.length} retained test files`);
+}
+export async function run() {
+  try {
+    runDriverContracts();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+if (import.meta.main)
+  await run();

package/dist/commands/protocol/run-driver-contracts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/protocol/run-driver-contracts.test.js

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "bun:test";
+import { planDriverContracts } from "./run-driver-contracts";
+describe("driver contract matrix planning", () => {
+  it("runs only supported evidence and reports all other maturity states explicitly", () => {
+    const plan = planDriverContracts([
+      { category: "cache", name: "memory", status: "supported", implementation: "memory.ts", testEvidence: ["memory.test.ts"], topology: "memory", prerequisites: [], limitations: [] },
+      { category: "cache", name: "redis", status: "partial", implementation: "redis.ts", testEvidence: ["redis.test.ts"], topology: "redis", prerequisites: ["Redis"], limitations: ["No live evidence"] },
+      { category: "queue", name: "sqs", status: "unsupported", implementation: null, testEvidence: [], topology: "sqs", prerequisites: ["AWS"], limitations: ["Reserved"] }
+    ]);
+    expect(plan.tests).toEqual(["memory.test.ts"]);
+    expect(plan.records.map((record) => [record.name, record.execution])).toEqual([
+      ["memory", "run"],
+      ["redis", "not-run"],
+      ["sqs", "not-run"]
+    ]);
+    expect(plan.records[1].reason).toContain("partial");
+  });
+});

package/dist/commands/protocol/source-manifest.d.ts

@@ -0,0 +1,25 @@
+export declare function buildSourceManifest(requestedRevision: string): SourceManifest;
+export declare function run(): Promise<void>;
+declare interface PackageEntry { name: string, path: string, version: string, publishable: boolean }
+declare interface SourceManifest {
+  schemaVersion: '1.0.0'
+  repository: string
+  sourceRevision: string
+  sourceTree: string
+  sourceDigest: string
+  generatedAt: string
+  classification: {
+    status: 'reference-implementation'
+    conformance: 'unverified'
+    notes: string
+  }
+  prerequisites: Record<string, string>
+  packages: PackageEntry[]
+  inventory: {
+    totalFiles: number
+    totalBytes: number
+    categories: Record<string, { files: number, bytes: number }>
+    extensions: Record<string, number>
+  }
+  protocolSuite: { version: string, rfcsRevision: string }
+}

package/dist/commands/protocol/source-manifest.js

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+const root = resolve(import.meta.dir, "../../../../../../.."), outputPath = resolve(root, ".github/protocol/evidence/source-manifest.json");
+function runGit(...arguments_) {
+  try {
+    return execFileSync("git", arguments_, { cwd: root, maxBuffer: 67108864 });
+  } catch (error) {
+    throw Error(`git ${arguments_.join(" ")} failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+function revision(value) {
+  return runGit("rev-parse", `${value}^{commit}`).toString().trim();
+}
+function showJson(sourceRevision, path) {
+  return JSON.parse(runGit("show", `${sourceRevision}:${path}`).toString());
+}
+function category(path) {
+  if (/(^|\/)(test|tests|__tests__)(\/|$)|\.(test|spec)\.[^.]+$/.test(path))
+    return "tests";
+  if (path.startsWith("protocol/suite/"))
+    return "vendored-protocol";
+  if (/(^|\/)(dist|generated|coverage)(\/|$)|\.d\.ts$/.test(path))
+    return "generated";
+  if (/\.(md|mdx|rst|txt)$/.test(path) || /(^|\/)docs\//.test(path))
+    return "documentation";
+  if (/(^|\/)(config|configs|\.github)(\/|$)|(^|\/)(tsconfig|package|bun\.lock|pantry)\b/.test(path))
+    return "configuration";
+  if (/\.(ts|tsx|js|jsx|vue|svelte|zig|rs|go|py|sh)$/.test(path))
+    return "source";
+  return "assets-and-data";
+}
+function addCount(record, key, bytes) {
+  const current = record[key] || { files: 0, bytes: 0 };
+  record[key] = { files: current.files + 1, bytes: current.bytes + bytes };
+}
+export function buildSourceManifest(requestedRevision) {
+  const sourceRevision = revision(requestedRevision), sourceTree = runGit("rev-parse", `${sourceRevision}^{tree}`).toString().trim(), treeListing = runGit("ls-tree", "-r", "-l", sourceRevision).toString(), lines = treeListing.trim().split(`
+`).filter(Boolean), categories = {}, extensions = {};
+  let totalBytes = 0;
+  const paths = [];
+  for (const line of lines) {
+    const match = line.match(/^\d+\s+blob\s+[0-9a-f]+\s+(\d+)\t(.+)$/);
+    if (!match)
+      continue;
+    const bytes = Number(match[1]), path = match[2];
+    if (path == null)
+      continue;
+    paths.push(path);
+    totalBytes += bytes;
+    addCount(categories, category(path), bytes);
+    const extension = extname(path).toLowerCase() || "[none]";
+    extensions[extension] = (extensions[extension] || 0) + 1;
+  }
+  const packages = paths.filter((path) => path === "package.json" || path.endsWith("/package.json")).flatMap((path) => {
+    const pkg = showJson(sourceRevision, path);
+    if (!pkg.name || !pkg.version)
+      return [];
+    return [{ name: pkg.name, path, version: pkg.version, publishable: pkg.private !== !0 }];
+  }).sort((a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path)), rootPackage = showJson(sourceRevision, "package.json"), suiteLock = showJson(sourceRevision, "protocol/suite.lock.json");
+  return {
+    schemaVersion: "1.0.0",
+    repository: "https://github.com/stacksjs/stacks",
+    sourceRevision,
+    sourceTree,
+    sourceDigest: `sha256:${createHash("sha256").update(treeListing).digest("hex")}`,
+    generatedAt: "derived-from-immutable-git-objects",
+    classification: {
+      status: "reference-implementation",
+      conformance: "unverified",
+      notes: "Reference implementation status does not imply a protocol profile claim; consult the report for per-requirement evidence."
+    },
+    prerequisites: rootPackage.system || {},
+    packages,
+    inventory: {
+      totalFiles: lines.length,
+      totalBytes,
+      categories: Object.fromEntries(Object.entries(categories).sort(([a], [b]) => a.localeCompare(b))),
+      extensions: Object.fromEntries(Object.entries(extensions).sort(([a], [b]) => a.localeCompare(b)))
+    },
+    protocolSuite: { version: suiteLock.protocolVersion, rfcsRevision: suiteLock.rfcsRevision }
+  };
+}
+function render(manifest) {
+  return `${JSON.stringify(manifest, null, 2)}
+`;
+}
+export async function run() {
+  const mode = process.argv.includes("--write") ? "write" : process.argv.includes("--check") ? "check" : null;
+  if (!mode) {
+    console.error("usage: bun storage/framework/core/buddy/src/commands/protocol/source-manifest.ts --write [--revision <ref>] | --check");
+    process.exit(2);
+  }
+  if (mode === "write") {
+    const index = process.argv.indexOf("--revision"), requestedRevision = index === -1 ? "HEAD" : process.argv[index + 1];
+    if (!requestedRevision)
+      throw Error("--revision requires a Git ref");
+    const manifest = buildSourceManifest(requestedRevision);
+    mkdirSync(dirname(outputPath), { recursive: !0 });
+    writeFileSync(outputPath, render(manifest));
+    console.log(`Wrote source manifest for ${manifest.sourceRevision} (${manifest.inventory.totalFiles} files, ${manifest.packages.length} packages)`);
+  } else {
+    if (!existsSync(outputPath))
+      throw Error("source manifest is missing; run bun run protocol:manifest");
+    const current = JSON.parse(readFileSync(outputPath, "utf8")), expected = render(buildSourceManifest(current.sourceRevision));
+    if (readFileSync(outputPath, "utf8") !== expected)
+      throw Error(`source manifest is stale or modified; run bun storage/framework/core/buddy/src/commands/protocol/source-manifest.ts --write --revision ${current.sourceRevision}`);
+    console.log(`Source manifest matches ${current.sourceRevision}`);
+  }
+}
+if (import.meta.main)
+  await run();

package/dist/commands/protocol/sync-suite.d.ts

@@ -0,0 +1,8 @@
+/** Requirement ids that appear more than once in `ids` (sorted, deduped). */
+export declare function duplicateRequirementIds(ids: string[]): string[];
+/**
+ * Requirement ids referenced by a fixture that are absent from `catalogIds`,
+ * formatted `fixtureId -> requirementId`.
+ */
+export declare function danglingFixtureRequirements(fixtures: Array<{ id: string, requirements?: string[] }>, catalogIds: Set<string>): string[];
+export declare function run(): Promise<void>;

package/dist/commands/protocol/sync-suite.js

@@ -0,0 +1,137 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+const root = resolve(import.meta.dir, "../../../../../../.."), suiteRoot = resolve(root, ".github/protocol/suite/1.0-draft"), lockPath = resolve(root, ".github/protocol/suite.lock.json");
+function digest(data) {
+  return `sha256:${createHash("sha256").update(data).digest("hex")}`;
+}
+function filesBelow(directory) {
+  return readdirSync(directory, { withFileTypes: !0 }).flatMap((entry) => {
+    const path = resolve(directory, entry.name);
+    return entry.isDirectory() ? filesBelow(path) : [path];
+  }).sort();
+}
+function argument(name) {
+  const index = process.argv.indexOf(name);
+  return index === -1 ? void 0 : process.argv[index + 1];
+}
+function gitRevision(repository) {
+  const result = Bun.spawnSync(["git", "-C", repository, "rev-parse", "HEAD"]);
+  if (result.exitCode !== 0)
+    throw Error(`Could not resolve the RFC repository revision: ${result.stderr.toString().trim()}`);
+  return result.stdout.toString().trim();
+}
+function writeSnapshot(sourceRepository) {
+  const sourceRoot = resolve(sourceRepository, "protocol/1.0-draft");
+  if (!existsSync(resolve(sourceRoot, "catalog.json")))
+    throw Error(`No protocol suite found at ${sourceRoot}`);
+  rmSync(suiteRoot, { force: !0, recursive: !0 });
+  const files = {}, sourceFiles = [
+    ...filesBelow(sourceRoot).map((sourcePath) => ({ sourcePath, path: relative(sourceRoot, sourcePath) })),
+    ...["LICENSE-SPECIFICATION.md", "LICENSE-FIXTURES.md"].map((path) => ({ sourcePath: resolve(sourceRepository, path), path }))
+  ];
+  for (const { sourcePath, path } of sourceFiles) {
+    const outputPath = resolve(suiteRoot, path), contents = readFileSync(sourcePath);
+    mkdirSync(dirname(outputPath), { recursive: !0 });
+    writeFileSync(outputPath, contents);
+    files[path] = digest(contents);
+  }
+  const lock = {
+    protocolVersion: "1.0-draft",
+    rfcsRevision: gitRevision(sourceRepository),
+    sourceRepository: "https://github.com/stacksjs/rfcs",
+    files
+  };
+  mkdirSync(dirname(lockPath), { recursive: !0 });
+  writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}
+`);
+  console.log(`Pinned ${Object.keys(files).length} protocol files at ${lock.rfcsRevision}`);
+}
+function checkSnapshot() {
+  if (!existsSync(lockPath))
+    throw Error(".github/protocol/suite.lock.json is missing; run bun run protocol:sync");
+  const lock = JSON.parse(readFileSync(lockPath, "utf8"));
+  if (!/^[0-9a-f]{40}$/.test(lock.rfcsRevision))
+    throw Error("suite lock has an invalid RFC revision");
+  const actualFiles = filesBelow(suiteRoot).map((path) => relative(suiteRoot, path)), expectedFiles = Object.keys(lock.files).sort(), unexpected = actualFiles.filter((path) => !lock.files[path]), missing = expectedFiles.filter((path) => !actualFiles.includes(path)), changed = expectedFiles.filter((path) => {
+    const absolutePath = resolve(suiteRoot, path);
+    return existsSync(absolutePath) && digest(readFileSync(absolutePath)) !== lock.files[path];
+  }), errors = [
+    ...missing.map((path) => `missing: ${path}`),
+    ...unexpected.map((path) => `unexpected: ${path}`),
+    ...changed.map((path) => `modified: ${path}`)
+  ];
+  if (errors.length > 0)
+    throw Error(`Vendored protocol suite does not match its lock:
+${errors.join(`
+`)}`);
+  console.log(`Protocol suite matches ${basename(lock.sourceRepository)}@${lock.rfcsRevision} (${actualFiles.length} files)`);
+}
+export function duplicateRequirementIds(ids) {
+  const seen = new Set, duplicates = new Set;
+  for (const id of ids)
+    if (seen.has(id))
+      duplicates.add(id);
+    else
+      seen.add(id);
+  return [...duplicates].sort();
+}
+function checkCatalog() {
+  const catalogPath = resolve(suiteRoot, "catalog.json");
+  if (!existsSync(catalogPath))
+    throw Error(`protocol catalog missing at ${relative(root, catalogPath)}; run bun run protocol:sync`);
+  const catalog = JSON.parse(readFileSync(catalogPath, "utf8")), requirements = Array.isArray(catalog.requirements) ? catalog.requirements : [];
+  if (requirements.length === 0)
+    throw Error("protocol catalog has no requirements");
+  const ids = requirements.map((requirement) => requirement?.id), missing = ids.filter((id) => typeof id !== "string" || id.length === 0).length;
+  if (missing > 0)
+    throw Error(`protocol catalog has ${missing} requirement(s) without a string id`);
+  const duplicates = duplicateRequirementIds(ids);
+  if (duplicates.length > 0)
+    throw Error(`protocol catalog has duplicate requirement id(s): ${duplicates.join(", ")}`);
+  console.log(`Protocol catalog: ${ids.length} requirement ids, all unique`);
+}
+export function danglingFixtureRequirements(fixtures, catalogIds) {
+  const dangling = [];
+  for (const fixture of fixtures)
+    for (const requirement of fixture.requirements ?? [])
+      if (!catalogIds.has(requirement))
+        dangling.push(`${fixture.id} -> ${requirement}`);
+  return dangling;
+}
+function checkFixtures() {
+  const fixturesPath = resolve(suiteRoot, "fixtures/conformance.json");
+  if (!existsSync(fixturesPath))
+    throw Error(`protocol fixture corpus missing at ${relative(root, fixturesPath)}; run bun run protocol:sync`);
+  const corpus = JSON.parse(readFileSync(fixturesPath, "utf8")), fixtures = Array.isArray(corpus.fixtures) ? corpus.fixtures : [];
+  if (fixtures.length === 0)
+    throw Error("protocol fixture corpus has no fixtures");
+  const ids = fixtures.map((fixture) => fixture?.id), missing = ids.filter((id) => typeof id !== "string" || id.length === 0).length;
+  if (missing > 0)
+    throw Error(`protocol fixture corpus has ${missing} fixture(s) without a string id`);
+  const duplicates = duplicateRequirementIds(ids);
+  if (duplicates.length > 0)
+    throw Error(`protocol fixture corpus has duplicate fixture id(s): ${duplicates.join(", ")}`);
+  const catalog = JSON.parse(readFileSync(resolve(suiteRoot, "catalog.json"), "utf8")), catalogIds = new Set((catalog.requirements ?? []).map((requirement) => requirement?.id).filter((id) => typeof id === "string")), normalized = fixtures.map((fixture) => ({
+    id: String(fixture?.id),
+    requirements: Array.isArray(fixture?.requirements) ? fixture.requirements.filter((requirement) => typeof requirement === "string") : []
+  })), dangling = danglingFixtureRequirements(normalized, catalogIds);
+  if (dangling.length > 0)
+    throw Error(`protocol fixtures reference unknown requirement id(s): ${dangling.slice(0, 10).join(", ")}`);
+  console.log(`Protocol fixtures: ${ids.length} fixtures, ids unique, all requirement refs resolve`);
+}
+export async function run() {
+  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();
+    checkFixtures();
+  } else {
+    console.error("usage: bun storage/framework/core/buddy/src/commands/protocol/sync-suite.ts --write [--source ../rfcs] | --check");
+    process.exit(2);
+  }
+}
+if (import.meta.main)
+  await run();

package/dist/commands/protocol/sync-suite.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/protocol/sync-suite.test.js

@@ -0,0 +1,44 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { describe, expect, it } from "bun:test";
+import { danglingFixtureRequirements, duplicateRequirementIds } from "./sync-suite";
+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 ids = JSON.parse(readFileSync(resolve(import.meta.dir, "../../../../../../../.github/protocol/suite/1.0-draft/catalog.json"), "utf8")).requirements.map((requirement) => requirement.id);
+    expect(ids.length).toBeGreaterThan(0);
+    expect(duplicateRequirementIds(ids)).toEqual([]);
+  });
+});
+describe("protocol fixture-corpus integrity (stacksjs/stacks#2051)", () => {
+  const catalogIds = new Set(["CORE-CONV-01", "CORE-CONV-02", "CORE-MVA-01"]);
+  it("reports no dangling refs when every requirement resolves", () => {
+    expect(danglingFixtureRequirements([
+      { id: "fixture.a", requirements: ["CORE-CONV-01", "CORE-CONV-02"] },
+      { id: "fixture.b", requirements: ["CORE-MVA-01"] }
+    ], catalogIds)).toEqual([]);
+  });
+  it("reports each unknown requirement ref as `fixture -> requirement`", () => {
+    expect(danglingFixtureRequirements([
+      { id: "fixture.a", requirements: ["CORE-CONV-01", "CORE-GONE-99"] },
+      { id: "fixture.b", requirements: ["NOPE-01"] }
+    ], catalogIds)).toEqual(["fixture.a -> CORE-GONE-99", "fixture.b -> NOPE-01"]);
+  });
+  it("tolerates fixtures with no requirements", () => {
+    expect(danglingFixtureRequirements([{ id: "fixture.a" }], catalogIds)).toEqual([]);
+  });
+  it("the vendored fixture corpus has unique ids and no dangling requirement refs", () => {
+    const base = resolve(import.meta.dir, "../../../../../../../.github/protocol/suite/1.0-draft"), corpus = JSON.parse(readFileSync(resolve(base, "fixtures/conformance.json"), "utf8")), catalog = JSON.parse(readFileSync(resolve(base, "catalog.json"), "utf8")), realIds = new Set(catalog.requirements.map((requirement) => requirement.id));
+    expect(corpus.fixtures.length).toBeGreaterThan(0);
+    expect(duplicateRequirementIds(corpus.fixtures.map((fixture) => fixture.id))).toEqual([]);
+    expect(danglingFixtureRequirements(corpus.fixtures, realIds)).toEqual([]);
+  });
+});

package/dist/commands/protocol.d.ts

@@ -0,0 +1,8 @@
+import type { CLI } from '@stacksjs/types';
+/**
+ * Framework-repo `buddy protocol:*` commands. The governance tooling itself
+ * lives beside this file under `commands/protocol/`; the protocol suite +
+ * evidence DATA stays under `.github/protocol/`. These wrap the tooling so it
+ * is discoverable via the CLI (`buddy protocol:conformance`).
+ */
+export declare function protocol(buddy: CLI): void;

package/dist/commands/protocol.js

@@ -0,0 +1,60 @@
+import { run as runConformance } from "./protocol/run-conformance";
+import { run as runCraft } from "./protocol/craft-evidence";
+import { run as runDesktop } from "./protocol/desktop-support";
+import { run as runDrivers } from "./protocol/driver-registry";
+import { run as runDriverContracts } from "./protocol/run-driver-contracts";
+import { run as runPantry } from "./protocol/pantry-evidence";
+import { run as runRelease } from "./protocol/release-manifest";
+import { run as runManifest } from "./protocol/source-manifest";
+import { run as runSync } from "./protocol/sync-suite";
+import { runTool } from "./run-tool";
+export function protocol(buddy) {
+  buddy.command("protocol:conformance", "Generate the Stacks protocol conformance report").action(async () => {
+    await runConformance();
+  });
+  buddy.command("protocol:sync", "Sync the vendored protocol suite from stacksjs/rfcs").option("--source <path>", "Path to a local rfcs checkout", { default: void 0 }).action(async (options) => {
+    await runTool(runSync, "--write", ...options.source ? ["--source", options.source] : []);
+  });
+  buddy.command("protocol:check", "Verify the vendored protocol suite is pinned + internally consistent").action(async () => {
+    await runTool(runSync, "--check");
+  });
+  buddy.command("protocol:manifest", "Write the protocol source manifest").option("--revision <ref>", "Source revision to pin (default HEAD)", { default: void 0 }).action(async (options) => {
+    await runTool(runManifest, "--write", ...options.revision ? ["--revision", options.revision] : []);
+  });
+  buddy.command("protocol:manifest:check", "Verify the protocol source manifest is current").action(async () => {
+    await runTool(runManifest, "--check");
+  });
+  buddy.command("protocol:release", "Write the protocol release manifest").option("--tag <tag>", "Release tag", { default: void 0 }).action(async (options) => {
+    await runTool(runRelease, "--write", ...options.tag ? ["--tag", options.tag] : []);
+  });
+  buddy.command("protocol:release:check", "Verify the protocol release manifest is current").action(async () => {
+    await runTool(runRelease, "--check");
+  });
+  buddy.command("protocol:drivers", "Write the driver capability registry evidence").action(async () => {
+    await runTool(runDrivers, "--write");
+  });
+  buddy.command("protocol:drivers:check", "Verify the driver capability registry evidence").action(async () => {
+    await runTool(runDrivers, "--check");
+  });
+  buddy.command("protocol:drivers:test", "Run the driver contract suite").action(async () => {
+    await runTool(runDriverContracts);
+  });
+  buddy.command("protocol:desktop", "Write the desktop support matrix evidence").action(async () => {
+    await runTool(runDesktop, "--write");
+  });
+  buddy.command("protocol:desktop:check", "Verify the desktop support matrix evidence").action(async () => {
+    await runTool(runDesktop, "--check");
+  });
+  buddy.command("protocol:pantry", "Write the pantry evidence").action(async () => {
+    await runTool(runPantry, "--write");
+  });
+  buddy.command("protocol:pantry:check", "Verify the pantry evidence").action(async () => {
+    await runTool(runPantry, "--check");
+  });
+  buddy.command("protocol:craft", "Write the Craft evidence").action(async () => {
+    await runTool(runCraft, "--write");
+  });
+  buddy.command("protocol:craft:check", "Verify the Craft evidence").action(async () => {
+    await runTool(runCraft, "--check");
+  });
+}