Proof

Proof is how Project Canon becomes more than prose. Validators, gates, fixtures, Doctor, generated-doc drift checks, and declared task checks all verify that implementation still matches the canon.

Convention with runtime validator

A convention can own the prose, scope, generated docs, and runtime enforcement in one definition.

service-db-boundary.ts

01import { defineConvention } from "@opencanon/core";
02 
03export default defineConvention({
04  id: "service-db-boundary",
05  title: "Services compose DAL instead of direct DB clients",
06  topics: ["service", "dal"],
07  why: "DAL modules keep table/query details in one layer.",
08  rule: "Services own workflow composition but should use DAL modules for persistence details.",
09  applies: { kind: "files", globs: ["src/services/**/*.ts"] },
10  render: {
11    kind: "generated",
12    docs: "docs/opencanon/canon/service-db-boundary.md",
13    style: "reference"
14  },
15  runtime: {
16    kind: "validator",
17    severity: "error",
18    scope: "import-edge",
19    facts: ["imports"],
20    validate({ ctx }) {
21      return ctx.facts.imports()
22        .filter((edge) => edge.source.endsWith("/db/client"))
23        .map((edge) => edge.from.report({
24          line: edge.line,
25          message: "Services must not import DB clients directly."
26        }));
27    }
28  }
29});

Facts, not string scans

Validators read structured facts from the project runtime. Facts include imports, exports, calls, comments, literals, dependency metadata, graph edges, and file content when a file-scoped check genuinely needs text.

Graph-aware checks

graph validator

01runtime: {
02  kind: "validator",
03  severity: "warning",
04  scope: "project",
05  facts: ["graph"],
06  validate({ ctx }) {
07    return ctx.graph.callers("loadCompany").map((edge) =>
08      edge.source.file.report({
09        line: edge.source.line,
10        message: "Inspect loadCompany side effects before changing this call.",
11        fix: {
12          safety: "manual",
13          command: "opencanon graph callees loadCompany",
14          description: "Inspect downstream side effects before changing this call."
15        }
16      })
17    );
18  }
19}

Graph-backed checks can inspect symbols, references, callers, callees, and impact edges before a risky edit spreads.

Fixtures

Fixtures are tiny virtual projects that pin expected behavior. They live under opencanon/fixtures/ and run with the same validator engine as real project files.

opencanon/fixtures/service-db-boundary/invalid.ts

01import { defineFixture } from "@opencanon/core/testing";
02 
03export default defineFixture({
04  files: ({ file }) => [
05    file.ts("src/services/company.service.ts", `
06      import { db } from "../db/client";
07 
08      export function loadCompany(id: string) {
09        return db.company.findUnique({ where: { id } });
10      }
11    `)
12  ]
13});

Commit gates

Gates are for ambiguous changes that require user intent before commit. They produce pending approvals rather than normal findings.

gate runtime

01runtime: {
02  kind: "gate",
03  severity: "error",
04  scope: "file",
05  facts: ["literals"],
06  validate({ ctx }) {
07    for (const file of ctx.targetFiles) {
08      if (!file.text.includes("sessionTtlDays")) continue;
09 
10      ctx.commitGate({
11        id: "auth-session-ttl-change",
12        title: "Auth session TTL changed",
13        reason: "Session duration affects security and product behavior.",
14        question: "Did the user approve this auth session TTL change?",
15        file: file.path,
16        evidence: [{ file: file.path }],
17        approvalScope: "staged-diff"
18      });
19    }
20 
21    return [];
22  }
23}

approval flow

01opencanon validate --check-fixtures
02opencanon validate --changed
03opencanon gate pending --format json
04opencanon gate approve auth-session-ttl-change \
05  --summary "User approved changing sessionTtlDays from 365 to 730." \
06  --via agent

Generated docs stay derived

OpenCanon-owned Markdown is rendered from definitions. Doctor rerenders and diffs generated docs so humans get clean prose without making Markdown a second source of truth.