@stacksjs/buddy 0.70.163 → 0.70.164

package/dist/commands/protocol/run-conformance.js

@@ -0,0 +1,358 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { arch, platform } from "node:os";
+import { resolve } from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { Action } from "../../../../actions/src/index";
+import { assertCapabilityAvailable, capabilityRegistry } from "../../../../config/src/capabilities";
+import { decryptValue, encryptValue, generateKeypair } from "../../../../env/src/crypto";
+import { escapeHtml } from "../../../../error-handling/src/error-page-template";
+import { appPath, defaultsAppPath } from "../../../../path/src/index";
+import { createValidationErrorResponse } from "../../../../router/src/error-handler";
+import { timingSafeEqualString } from "../../../../security/src/hash";
+import { object, string } from "../../../../validation/src/index";
+const root = resolve(import.meta.dir, "../../../../../../.."), suiteRoot = resolve(root, ".github/protocol/suite/1.0-draft");
+function git(...arguments_) {
+  const result = Bun.spawnSync(["git", ...arguments_], { cwd: root });
+  if (result.exitCode !== 0)
+    throw Error(result.stderr.toString().trim());
+  return result.stdout.toString().trim();
+}
+function exactSourceDigest() {
+  const tree = git("rev-parse", "HEAD^{tree}");
+  return `sha256:${createHash("sha256").update(tree).digest("hex")}`;
+}
+function tamper(ciphertext) {
+  const prefix = "encrypted:", payload = Buffer.from(ciphertext.slice(prefix.length), "base64"), last = payload.length - 1;
+  if (last >= 0)
+    payload[last] = (payload[last] ?? 0) ^ 1;
+  return `${prefix}${payload.toString("base64")}`;
+}
+function blob(revision, path) {
+  return `https://github.com/stacksjs/stacks/blob/${revision}/${path}`;
+}
+export function executeSecurityEvidence(revision) {
+  const evidence = new Map, cryptoUrl = blob(revision, "storage/framework/core/env/src/crypto.ts"), comparisonUrl = blob(revision, "storage/framework/core/security/src/hash.ts"), renderUrl = blob(revision, "storage/framework/core/error-handling/src/error-page-template.ts"), started = performance.now();
+  try {
+    const { publicKey, privateKey } = generateKeypair(), encrypted = encryptValue("secret", publicKey), roundTrip = decryptValue(encrypted, privateKey);
+    let tamperRejected = !1;
+    try {
+      decryptValue(tamper(encrypted), privateKey);
+    } catch {
+      tamperRejected = !0;
+    }
+    const passed = roundTrip === "secret" && !encrypted.includes("secret") && tamperRejected;
+    evidence.set("CORE-SEC-05", {
+      status: passed ? "pass" : "fail",
+      evidenceUrl: cryptoUrl,
+      durationMs: Math.max(0, performance.now() - started),
+      notes: passed ? "Authenticated-encryption round trip passed and modified ciphertext was rejected." : "Authenticated-encryption fixture failed."
+    });
+  } catch (error) {
+    evidence.set("CORE-SEC-05", {
+      status: "fail",
+      evidenceUrl: cryptoUrl,
+      durationMs: Math.max(0, performance.now() - started),
+      notes: `Authenticated-encryption fixture threw: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+  const comparisonStarted = performance.now(), unequal = timingSafeEqualString("token-a", "token-b") === !1;
+  evidence.set("CORE-SEC-07", {
+    status: unequal ? "pass" : "fail",
+    evidenceUrl: comparisonUrl,
+    durationMs: Math.max(0, performance.now() - comparisonStarted),
+    notes: unequal ? "The public authenticator comparison helper uses the runtime timing-safe primitive." : "Timing-safe comparison fixture failed."
+  });
+  const renderStarted = performance.now(), renderOk = escapeHtml("<script>alert(1)</script>") === "&lt;script&gt;alert(1)&lt;/script&gt;";
+  evidence.set("CORE-SEC-02", {
+    status: renderOk ? "pass" : "fail",
+    evidenceUrl: renderUrl,
+    durationMs: Math.max(0, performance.now() - renderStarted),
+    notes: renderOk ? "Untrusted markup is converted to HTML entities by the default escaper." : "Default render-escaping fixture failed."
+  });
+  return evidence;
+}
+export function executeConfigEvidence(revision) {
+  const evidence = new Map, url = blob(revision, "storage/framework/core/config/src/capabilities.ts"), started = performance.now();
+  let failedClosed = !1, message = "";
+  try {
+    assertCapabilityAvailable("queue", "planned");
+  } catch (error) {
+    failedClosed = !0;
+    message = error instanceof Error ? error.message : String(error);
+  }
+  evidence.set("CORE-CONFIG-02", {
+    status: failedClosed ? "pass" : "fail",
+    evidenceUrl: url,
+    durationMs: Math.max(0, performance.now() - started),
+    notes: failedClosed ? `Selecting an unavailable driver is rejected before use: ${message}` : "Fail-closed capability guard accepted an unavailable driver."
+  });
+  const drvStarted = performance.now();
+  let drvFailedClosed = !1;
+  try {
+    assertCapabilityAvailable("queue", "planned-driver");
+  } catch {
+    drvFailedClosed = !0;
+  }
+  evidence.set("STD-DRV-01", {
+    status: drvFailedClosed ? "pass" : "fail",
+    evidenceUrl: url,
+    durationMs: Math.max(0, performance.now() - drvStarted),
+    notes: drvFailedClosed ? "A planned driver is rejected loudly with no silent fallback." : "Driver-failure fixture did not reject a planned driver."
+  });
+  return evidence;
+}
+export async function executeValidationEvidence(revision) {
+  const evidence = new Map, validationUrl = blob(revision, "storage/framework/core/validation/src/validator.ts"), envelopeUrl = blob(revision, "storage/framework/core/router/src/error-handler.ts"), started = performance.now(), result = await object({ profile: object({ email: string().email() }) }).validate({ profile: { email: "bad" } }), valOk = result.valid === !1 && Object.keys(result.errors).includes("profile.email");
+  evidence.set("CORE-VAL-01", {
+    status: valOk ? "pass" : "fail",
+    evidenceUrl: validationUrl,
+    durationMs: Math.max(0, performance.now() - started),
+    notes: valOk ? "Nested invalid input produced a stable field-keyed error at profile.email." : "Field-keyed validation fixture failed."
+  });
+  const envStarted = performance.now(), fieldErrors = {};
+  for (const [field, errors] of Object.entries(result.errors))
+    fieldErrors[field] = errors.map((entry) => entry.message ?? String(entry));
+  const response = createValidationErrorResponse(fieldErrors, new Request("http://conformance.local/profile", { method: "POST" })), body = await response.text(), durationEnv = Math.max(0, performance.now() - envStarted), envelopeOk = response.status === 422 && body.includes('"message":"Validation failed"') && body.includes("profile.email");
+  evidence.set("CORE-ERR-01", {
+    status: envelopeOk ? "pass" : "fail",
+    evidenceUrl: envelopeUrl,
+    durationMs: durationEnv,
+    notes: envelopeOk ? "Validation failure serialized to a stable 422 envelope with error, message, status, and field errors." : "Error-envelope fixture failed."
+  });
+  const leaks = ["stack", "password", "SELECT", "/home/"].filter((token) => body.includes(token));
+  evidence.set("CORE-ERR-02", {
+    status: envelopeOk && leaks.length === 0 ? "pass" : "fail",
+    evidenceUrl: envelopeUrl,
+    durationMs: durationEnv,
+    notes: leaks.length === 0 ? "Production error envelope contained no stack trace, credentials, raw query, or filesystem path." : `Production error envelope leaked: ${leaks.join(", ")}.`
+  });
+  return evidence;
+}
+export function executeConventionsEvidence(revision) {
+  const evidence = new Map, rolesUrl = blob(revision, "storage/framework/core/path/src/index.ts"), overrideUrl = blob(revision, "storage/framework/core/router/src/stacks-router.ts"), started = performance.now(), conv01Ok = appPath("Actions/Greet").endsWith("/app/Actions/Greet");
+  evidence.set("CORE-CONV-01", {
+    status: conv01Ok ? "pass" : "fail",
+    evidenceUrl: rolesUrl,
+    durationMs: Math.max(0, performance.now() - started),
+    notes: conv01Ok ? "The Action role maps to its documented app/Actions/<name> path." : "Role-to-path mapping fixture failed."
+  });
+  const overrideStarted = performance.now(), logical = "Actions/NotifyUser.ts", userCandidate = appPath(logical), defaultCandidate = defaultsAppPath(logical), resolved = existsSync(userCandidate) ? userCandidate : defaultCandidate, conv02Ok = existsSync(userCandidate) && existsSync(defaultCandidate) && resolved === userCandidate;
+  evidence.set("CORE-CONV-02", {
+    status: conv02Ok ? "pass" : "fail",
+    evidenceUrl: overrideUrl,
+    durationMs: Math.max(0, performance.now() - overrideStarted),
+    notes: conv02Ok ? "With the same logical path present in both app/ and framework defaults, resolution selects the app-owned file." : "Override-precedence fixture failed."
+  });
+  return evidence;
+}
+export async function executeLifecycleEvidence(revision) {
+  const evidence = new Map, url = blob(revision, "storage/framework/core/actions/src/action.ts"), started = performance.now(), mvaOk = (await new Action({
+    name: "Increment",
+    handle(request) {
+      return { value: request.body.value + 1 };
+    }
+  }).handle({ body: { value: 1 } }))?.value === 2;
+  evidence.set("CORE-MVA-01", {
+    status: mvaOk ? "pass" : "fail",
+    evidenceUrl: url,
+    durationMs: Math.max(0, performance.now() - started),
+    notes: mvaOk ? "An Action was invoked directly with no HTTP transport and returned its computed result." : "Direct Action invocation fixture failed."
+  });
+  return evidence;
+}
+export async function executeQueryEvidence(revision) {
+  const evidence = new Map, url = blob(revision, "storage/framework/core/database/src/types.ts"), started = performance.now();
+  try {
+    const { sql } = await import("../../../../database/src/types"), attack = "' OR 1=1 --", query = sql`SELECT * FROM users WHERE email = ${attack}`, parameterized = query.sql === "SELECT * FROM users WHERE email = ?" && Array.isArray(query.parameters) && query.parameters.length === 1 && query.parameters[0] === attack;
+    evidence.set("CORE-SEC-01", {
+      status: parameterized ? "pass" : "fail",
+      evidenceUrl: url,
+      durationMs: Math.max(0, performance.now() - started),
+      notes: parameterized ? "Untrusted input is bound as a positional parameter and never inlined into the SQL text." : "Query-parameterization fixture failed."
+    });
+  } catch (error) {
+    evidence.set("CORE-SEC-01", {
+      status: "skipped",
+      evidenceUrl: null,
+      durationMs: Math.max(0, performance.now() - started),
+      notes: `Query builder unavailable in this environment: ${error instanceof Error ? error.message.slice(0, 100) : String(error)}`
+    });
+  }
+  return evidence;
+}
+export async function executeDatabaseEvidence(revision) {
+  const evidence = new Map, url = blob(revision, "storage/framework/core/query-builder/src/index.ts"), started = performance.now();
+  try {
+    const { createQueryBuilder, setConfig } = await import("../../../../query-builder/src/index");
+    setConfig({ dialect: "sqlite", database: ":memory:" });
+    const db = createQueryBuilder();
+    await db.raw`DROP TABLE IF EXISTS conformance_widgets`.execute();
+    await db.raw`CREATE TABLE conformance_widgets (id INTEGER PRIMARY KEY, name TEXT)`.execute();
+    await db.insertInto("conformance_widgets").values({ id: 1, name: "a" }).execute();
+    const created = await db.selectFrom("conformance_widgets").selectAll().execute();
+    await db.updateTable("conformance_widgets").set({ name: "b" }).where("id", "=", 1).execute();
+    const updated = await db.selectFrom("conformance_widgets").select(["name"]).where("id", "=", 1).execute();
+    await db.deleteFrom("conformance_widgets").where("id", "=", 1).execute();
+    const afterDelete = await db.selectFrom("conformance_widgets").selectAll().execute(), crudOk = created.length === 1 && created[0]?.name === "a" && updated[0]?.name === "b" && afterDelete.length === 0;
+    evidence.set("CORE-DATA-01", {
+      status: crudOk ? "pass" : "fail",
+      evidenceUrl: url,
+      durationMs: Math.max(0, performance.now() - started),
+      notes: crudOk ? "Create, read, update, and delete round-trip succeeded against SQLite." : "CRUD fixture failed."
+    });
+    const txStarted = performance.now();
+    await db.insertInto("conformance_widgets").values({ id: 1, name: "keep" }).execute();
+    let rolledBack = !1;
+    try {
+      await db.transaction(async (trx) => {
+        await trx.insertInto("conformance_widgets").values({ id: 2, name: "temp" }).execute();
+        throw Error("force rollback");
+      });
+    } catch {
+      rolledBack = !0;
+    }
+    const rows = await db.selectFrom("conformance_widgets").selectAll().execute(), txOk = rolledBack && rows.length === 1 && rows[0]?.id === 1;
+    evidence.set("CORE-DATA-03", {
+      status: txOk ? "pass" : "fail",
+      evidenceUrl: url,
+      durationMs: Math.max(0, performance.now() - txStarted),
+      notes: txOk ? "A failing transaction rolled back its writes, leaving prior state intact." : "Transaction-rollback fixture failed."
+    });
+    const relStarted = performance.now();
+    await db.raw`DROP TABLE IF EXISTS conformance_books`.execute();
+    await db.raw`DROP TABLE IF EXISTS conformance_authors`.execute();
+    await db.raw`CREATE TABLE conformance_authors (id INTEGER PRIMARY KEY, name TEXT)`.execute();
+    await db.raw`CREATE TABLE conformance_books (id INTEGER PRIMARY KEY, author_id INTEGER, title TEXT)`.execute();
+    await db.insertInto("conformance_authors").values({ id: 1, name: "Ada" }).execute();
+    await db.insertInto("conformance_books").values([{ id: 1, author_id: 1, title: "B1" }, { id: 2, author_id: 1, title: "B2" }]).execute();
+    const related = await db.selectFrom("conformance_books").innerJoin("conformance_authors", "conformance_authors.id", "=", "conformance_books.author_id").select(["conformance_books.title", "conformance_authors.name"]).where("conformance_authors.id", "=", 1).execute(), relationOk = related.length === 2 && related.every((row) => row.name === "Ada");
+    evidence.set("CORE-DATA-02", {
+      status: relationOk ? "pass" : "fail",
+      evidenceUrl: url,
+      durationMs: Math.max(0, performance.now() - relStarted),
+      notes: relationOk ? "A relation query joined related rows across two tables." : "Relation fixture failed."
+    });
+  } catch (error) {
+    const note = `Query builder unavailable in this environment: ${error instanceof Error ? error.message.slice(0, 100) : String(error)}`;
+    for (const id of ["CORE-DATA-01", "CORE-DATA-02", "CORE-DATA-03"])
+      if (!evidence.has(id))
+        evidence.set(id, { status: "skipped", evidenceUrl: null, durationMs: Math.max(0, performance.now() - started), notes: note });
+  }
+  return evidence;
+}
+function validateSemantics(report, catalog, fixtures) {
+  const errors = [], expected = new Set(catalog.requirements.map((requirement) => requirement.id)), seen = new Set, fixtureIds = new Set(fixtures.fixtures.map((fixture) => fixture.id));
+  for (const result of report.results) {
+    if (seen.has(result.requirementId))
+      errors.push(`${result.requirementId}: duplicate result`);
+    if (!expected.has(result.requirementId))
+      errors.push(`${result.requirementId}: unknown requirement`);
+    if (result.fixtureId && !fixtureIds.has(result.fixtureId))
+      errors.push(`${result.requirementId}: unknown fixture`);
+    if (result.status === "pass" && !result.evidenceUrl)
+      errors.push(`${result.requirementId}: pass requires evidence`);
+    seen.add(result.requirementId);
+  }
+  for (const id of expected)
+    if (!seen.has(id))
+      errors.push(`${id}: missing result`);
+  if (report.profileClaim !== null)
+    errors.push("The Stacks adapter must remain unverified until profile calculation is implemented");
+  return errors;
+}
+function renderSummary(report) {
+  const counts = new Map;
+  for (const result of report.results)
+    counts.set(result.status, (counts.get(result.status) || 0) + 1);
+  const rows = [...counts].sort(([a], [b]) => a.localeCompare(b)).map(([status, count]) => `| ${status} | ${count} |`).join(`
+`);
+  return `# Stacks protocol conformance report
+
+**Profile claim:** Unverified
+**Implementation:** \`${report.implementation.revision}\` (${report.implementation.version})
+**Protocol:** ${report.protocol.version}, catalog ${report.protocol.catalogRevision}, suite ${report.protocol.suiteVersion}
+**Runtime/platform:** Bun ${report.execution.runtime.version} on ${report.execution.platform.os}/${report.execution.platform.architecture}
+**CI:** [run](${report.execution.ci.runUrl}) \xB7 [artifact](${report.execution.ci.artifactUrl})
+
+| Status | Count |
+| --- | ---: |
+${rows}
+
+Only executable adapter checks are marked \`pass\`. All remaining requirements stay \`skipped\` until their fixtures are wired to Stacks public APIs.
+`;
+}
+export async function buildReport() {
+  const startedAt = new Date, catalog = JSON.parse(readFileSync(resolve(suiteRoot, "catalog.json"), "utf8")), fixtures = JSON.parse(readFileSync(resolve(suiteRoot, "fixtures/conformance.json"), "utf8")), lock = JSON.parse(readFileSync(resolve(root, ".github/protocol/suite.lock.json"), "utf8")), packageJson = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8")), revision = process.env.GITHUB_SHA || git("rev-parse", "HEAD"), runUrl = process.env.GITHUB_SERVER_URL && process.env.GITHUB_REPOSITORY && process.env.GITHUB_RUN_ID ? `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` : `https://github.com/stacksjs/stacks/commit/${revision}`, evidence = executeSecurityEvidence(revision);
+  for (const [id, value] of executeConfigEvidence(revision))
+    evidence.set(id, value);
+  for (const [id, value] of executeConventionsEvidence(revision))
+    evidence.set(id, value);
+  for (const [id, value] of await executeValidationEvidence(revision))
+    evidence.set(id, value);
+  for (const [id, value] of await executeLifecycleEvidence(revision))
+    evidence.set(id, value);
+  for (const [id, value] of await executeQueryEvidence(revision))
+    evidence.set(id, value);
+  for (const [id, value] of await executeDatabaseEvidence(revision))
+    evidence.set(id, value);
+  const fixtureByRequirement = new Map(fixtures.fixtures.flatMap((fixture) => fixture.requirements.map((id) => [id, fixture.id]))), results = catalog.requirements.map((requirement) => ({
+    requirementId: requirement.id,
+    fixtureId: fixtureByRequirement.get(requirement.id) || null,
+    ...evidence.get(requirement.id) || {
+      status: "skipped",
+      evidenceUrl: null,
+      durationMs: 0,
+      notes: requirement.evidence === "behavior" ? "Fixture adapter is not implemented yet." : "Inspection evidence is not linked yet."
+    }
+  })), drivers = capabilityRegistry.map((driver) => ({
+    category: driver.category,
+    name: driver.name,
+    version: packageJson.version,
+    serviceVersion: null,
+    topology: driver.topology,
+    status: driver.status,
+    evidenceUrl: driver.testEvidence[0] ? `https://github.com/stacksjs/stacks/blob/${revision}/${driver.testEvidence[0]}` : null,
+    prerequisites: driver.prerequisites
+  }));
+  return {
+    reportVersion: "1.0.0-draft.1",
+    protocol: { version: catalog.protocolVersion, catalogRevision: catalog.catalogRevision, suiteVersion: fixtures.suiteVersion, rfcsRevision: lock.rfcsRevision },
+    implementation: { name: "Stacks", version: packageJson.version, revision, repository: "https://github.com/stacksjs/stacks", sourceDigest: exactSourceDigest() },
+    execution: {
+      startedAt: startedAt.toISOString(),
+      completedAt: new Date().toISOString(),
+      runtime: { name: "bun", version: Bun.version },
+      platform: { os: platform(), architecture: arch() },
+      ci: { provider: process.env.GITHUB_ACTIONS ? "github-actions" : "local", runUrl, artifactUrl: `${runUrl}#artifacts` }
+    },
+    profileClaim: null,
+    results,
+    drivers,
+    extensions: catalog.extensions.map((extension) => extension.id === "EXT-DESKTOP-01" ? { id: extension.id, status: "experimental", evidenceUrl: `https://github.com/stacksjs/stacks/blob/${revision}/protocol/evidence/desktop-support.json`, notes: "Craft targets are explicitly experimental pending native release evidence and signing infrastructure." } : { id: extension.id, status: "unsupported", evidenceUrl: null, notes: "Not evaluated by this adapter." }),
+    exceptions: [],
+    generator: { name: "@stacksjs/protocol-adapter", version: "1.0.0-draft.1", revision }
+  };
+}
+export async function run() {
+  const report = await buildReport(), schema = JSON.parse(readFileSync(resolve(suiteRoot, "schemas/conformance-report.schema.json"), "utf8")), catalog = JSON.parse(readFileSync(resolve(suiteRoot, "catalog.json"), "utf8")), fixtures = JSON.parse(readFileSync(resolve(suiteRoot, "fixtures/conformance.json"), "utf8")), ajv = new Ajv2020({ allErrors: !0, strict: !1 });
+  addFormats(ajv);
+  const validate = ajv.compile(schema), errors = [
+    ...validate(report) ? [] : (validate.errors || []).map((error) => `${error.instancePath || "/"} ${error.message || "is invalid"}`),
+    ...validateSemantics(report, catalog, fixtures)
+  ];
+  if (errors.length > 0) {
+    for (const error of errors)
+      console.error(`error: ${error}`);
+    process.exit(1);
+  }
+  const outputDirectory = resolve(process.env.PROTOCOL_REPORT_DIR || resolve(root, ".github/protocol/reports"));
+  mkdirSync(outputDirectory, { recursive: !0 });
+  writeFileSync(resolve(outputDirectory, "stacks-conformance.json"), `${JSON.stringify(report, null, 2)}
+`);
+  writeFileSync(resolve(outputDirectory, "stacks-conformance.md"), renderSummary(report));
+  console.log(`Protocol report generated in ${outputDirectory}`);
+}
+if (import.meta.main)
+  await run();

package/dist/commands/protocol/run-conformance.test.d.ts

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

package/dist/commands/protocol/run-conformance.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "bun:test";
+import { buildReport, executeConfigEvidence, executeConventionsEvidence, executeDatabaseEvidence, executeLifecycleEvidence, executeQueryEvidence, executeSecurityEvidence, executeValidationEvidence } from "./run-conformance";
+const REVISION = "0".repeat(40);
+describe("protocol adapter evidence", () => {
+  it("executes authenticated encryption, timing-safe comparison, and default escaping checks", () => {
+    const evidence = executeSecurityEvidence(REVISION);
+    expect(evidence.get("CORE-SEC-05")?.status).toBe("pass");
+    expect(evidence.get("CORE-SEC-07")?.status).toBe("pass");
+    expect(evidence.get("CORE-SEC-02")?.status).toBe("pass");
+  });
+  it("rejects unavailable and planned drivers loudly, before any work begins", () => {
+    const evidence = executeConfigEvidence(REVISION);
+    expect(evidence.get("CORE-CONFIG-02")?.status).toBe("pass");
+    expect(evidence.get("STD-DRV-01")?.status).toBe("pass");
+  });
+  it("invokes an Action directly, independent of any HTTP transport", async () => {
+    const evidence = await executeLifecycleEvidence(REVISION);
+    expect(evidence.get("CORE-MVA-01")?.status).toBe("pass");
+  });
+  it("parameterizes untrusted values instead of inlining them into SQL", async () => {
+    const evidence = await executeQueryEvidence(REVISION);
+    expect(evidence.get("CORE-SEC-01")?.status).toBe("pass");
+  });
+  it("performs a CRUD round-trip, a relation join, and rolls back a failed transaction", async () => {
+    const evidence = await executeDatabaseEvidence(REVISION);
+    expect(evidence.get("CORE-DATA-01")?.status).toBe("pass");
+    expect(evidence.get("CORE-DATA-02")?.status).toBe("pass");
+    expect(evidence.get("CORE-DATA-03")?.status).toBe("pass");
+  });
+  it("produces field-keyed validation errors and a redacted 422 envelope", async () => {
+    const evidence = await executeValidationEvidence(REVISION);
+    expect(evidence.get("CORE-VAL-01")?.status).toBe("pass");
+    expect(evidence.get("CORE-ERR-01")?.status).toBe("pass");
+    expect(evidence.get("CORE-ERR-02")?.status).toBe("pass");
+  });
+  it("maps canonical roles to paths and prefers app-owned overrides", () => {
+    const evidence = executeConventionsEvidence(REVISION);
+    expect(evidence.get("CORE-CONV-01")?.status).toBe("pass");
+    expect(evidence.get("CORE-CONV-02")?.status).toBe("pass");
+  });
+  it("reports each registered driver independently", async () => {
+    const report = await buildReport();
+    expect(report.drivers.length).toBeGreaterThan(7);
+    expect(report.drivers).toContainEqual(expect.objectContaining({ category: "database", name: "sqlite" }));
+    expect(report.drivers).toContainEqual(expect.objectContaining({ category: "queue", name: "sqs" }));
+  });
+  it("marks every passing requirement with a source evidence url", async () => {
+    const passing = (await buildReport()).results.filter((result) => result.status === "pass");
+    expect(passing.length).toBeGreaterThanOrEqual(15);
+    expect(passing.every((result) => typeof result.evidenceUrl === "string" && result.evidenceUrl.startsWith("https://"))).toBe(!0);
+  });
+});

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

@@ -0,0 +1,7 @@
+import type { CapabilityDriver } from '../../../../config/src/capabilities';
+export declare function planDriverContracts(drivers: readonly CapabilityDriver[]): {
+  tests: string[]
+  records: Array<CapabilityDriver & { execution: 'run' | 'not-run', reason: string | null }>
+};
+export declare function runDriverContracts(): void;
+export declare function run(): Promise<void>;

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 }
+}