kernel-zero.policy.json

{
  "apiVersion": "kernel-zero.dev/v1",
  "kind": "RepositoryPolicy",
  "metadata": {
    "name": "kernel-zero-self-policy",
    "revision": 1,
    "description": "Deterministic architecture rules for the KERNEL ZERO repository."
  },
  "scope": {
    "languages": [
      "typescript",
      "tsx"
    ],
    "include": [
      "apps/**/*.ts",
      "apps/**/*.tsx",
      "packages/**/*.ts"
    ],
    "exclude": [
      "**/*.test.ts",
      "**/fixtures/**",
      "packages/persistence/src/client.ts"
    ]
  },
  "layers": {
    "ui": [
      "apps/control/src/app/**/page.tsx",
      "apps/control/src/app/**/layout.tsx"
    ],
    "transport": [
      "apps/control/src/app/api/**/*.ts"
    ],
    "service": [
      "apps/control/src/server/**/*.ts"
    ],
    "persistence": [
      "packages/persistence/src/**/*.ts"
    ],
    "kernel": [
      "packages/domain/**/*.ts",
      "packages/contracts/**/*.ts",
      "packages/persistence/**/*.ts"
    ],
    "validator": [
      "packages/validator/**/*.ts"
    ]
  },
  "rules": [
    {
      "id": "server-modules-declare-boundary",
      "title": "Server modules declare their runtime boundary",
      "level": "error",
      "check": {
        "kind": "require-import",
        "files": [
          "layer:service",
          "layer:persistence"
        ],
        "module": "server-only",
        "allowTypeOnly": false
      },
      "remediation": "Add the server-only side-effect import at the module boundary."
    },
    {
      "id": "ui-does-not-import-persistence",
      "title": "UI routes use application services",
      "level": "error",
      "check": {
        "kind": "forbid-import-edge",
        "from": [
          "layer:ui"
        ],
        "deny": [
          "module:@kernel-zero/persistence",
          "module:@prisma/client"
        ]
      },
      "remediation": "Move persistence access behind a server application service."
    },
    {
      "id": "transport-does-not-import-repositories",
      "title": "Transport routes call services rather than repositories",
      "level": "error",
      "check": {
        "kind": "forbid-import-edge",
        "from": [
          "layer:transport"
        ],
        "deny": [
          "module:@kernel-zero/persistence",
          "module:@prisma/client"
        ]
      },
      "remediation": "Parse at ingress and call one application service."
    },
    {
      "id": "public-evidence-is-parsed",
      "title": "Evidence ingress parses the public contract",
      "level": "error",
      "check": {
        "kind": "require-boundary-parse",
        "files": [
          "apps/control/src/server/evidence/evidence-service.ts"
        ],
        "boundaryCalls": [
          "verifyEvidenceAttestation"
        ],
        "parserCalls": [
          "profile.evidenceSchema.safeParse"
        ]
      },
      "remediation": "Pass only a value proven by the strict evidence schema to the service."
    },
    {
      "id": "tenant-selector-requires-workspace",
      "title": "Tenant selectors require workspace context",
      "level": "error",
      "check": {
        "kind": "require-tenant-parameter",
        "files": [
          "packages/persistence/src/tenancy.ts"
        ],
        "symbols": "tenantSelector",
        "parameter": "workspaceId"
      },
      "remediation": "Require the exact workspace identifier in every tenant selector."
    },
    {
      "id": "governed-actions-have-closed-metadata",
      "title": "Governed actions declare enforcement metadata",
      "level": "error",
      "check": {
        "kind": "require-governed-operation",
        "files": [
          "apps/control/src/server/governed-actions.ts"
        ],
        "registryExport": "GOVERNED_ACTIONS",
        "requiredKeys": [
          "tenantScope",
          "audit",
          "idempotency"
        ],
        "declarationCalls": [
          "defineGovernedAction"
        ]
      },
      "remediation": "Declare every governed action through the closed registry contract."
    },
    {
      "id": "raw-database-client-is-contained",
      "title": "Raw database clients stay in persistence",
      "level": "error",
      "check": {
        "kind": "forbid-import-edge",
        "from": [
          "apps/**/*.ts",
          "apps/**/*.tsx",
          "packages/contracts/**/*.ts",
          "packages/domain/**/*.ts",
          "packages/validator/**/*.ts"
        ],
        "deny": [
          "module:@prisma/client"
        ]
      },
      "remediation": "Use the tenant-scoped persistence package instead of the raw client."
    },
    {
      "id": "kernel-does-not-import-profiles",
      "title": "Kernel packages never depend on a profile",
      "level": "error",
      "check": {
        "kind": "forbid-import-edge",
        "from": [
          "layer:kernel"
        ],
        "deny": [
          "module:@kernel-zero/profiles",
          "module:@kernel-zero/profile-software-architecture",
          "module:@kernel-zero/profile-manifest"
        ]
      },
      "remediation": "Move profile-specific logic behind the Profile interface and look it up through @kernel-zero/profiles from the control application."
    },
    {
      "id": "validator-stays-network-and-database-free",
      "title": "The standalone validator never depends on the control plane",
      "level": "error",
      "check": {
        "kind": "forbid-import-edge",
        "from": [
          "layer:validator"
        ],
        "deny": [
          "module:@kernel-zero/persistence",
          "module:@kernel-zero/profiles",
          "module:@prisma/client",
          "module-prefix:next"
        ]
      },
      "remediation": "Keep the validator on contracts, domain, and its profile."
    },
    {
      "id": "tenant-queries-carry-workspace",
      "title": "Tenant queries carry the workspace identifier",
      "level": "error",
      "check": {
        "kind": "require-call-argument",
        "files": [
          "layer:persistence"
        ],
        "callee": [
          "*.findFirst",
          "*.findMany",
          "*.updateMany",
          "*.deleteMany",
          "*.count"
        ],
        "argument": 0,
        "requiredPath": "where.workspaceId",
        "allowFrom": [
          "packages/persistence/src/audit.ts"
        ]
      },
      "remediation": "Put workspaceId in the where selector of every tenant-scoped query so a sibling tenant's rows are never reachable."
    },
    {
      "id": "policy-revision-state-is-governed",
      "title": "Policy revision state changes only through the governed lifecycle",
      "level": "error",
      "check": {
        "kind": "restrict-state-transition",
        "callee": [
          "*.policyRevision.updateMany"
        ],
        "argument": 0,
        "field": "data.state",
        "allowFrom": [
          "packages/persistence/src/policies.ts"
        ],
        "transitions": [
          {
            "from": "draft",
            "to": "approved"
          },
          {
            "from": "approved",
            "to": "active"
          },
          {
            "from": "active",
            "to": "superseded"
          }
        ]
      },
      "remediation": "Change a policy revision's state only from policies.ts, with a literal where.state predicate, through draft->approved, approved->active, or active->superseded."
    },
    {
      "id": "route-handlers-parse-their-input-get",
      "title": "GET route handlers parse their input before it escapes",
      "level": "error",
      "check": {
        "kind": "require-ingress-parse",
        "files": [
          "layer:transport"
        ],
        "symbols": "GET",
        "parserCalls": [
          "readEvidenceRequest"
        ],
        "readerCalls": [
          "dependencies.resolveSubmission"
        ],
        "allowedCalls": [
          "dependencies.service.submit",
          "errorResponse"
        ]
      },
      "remediation": "Pass the request only to the request-context reader and readEvidenceRequest; hand parsed values to one application service and build every response through errorResponse or Response.json."
    },
    {
      "id": "route-handlers-parse-their-input-post",
      "title": "POST route handlers parse their input before it escapes",
      "level": "error",
      "check": {
        "kind": "require-ingress-parse",
        "files": [
          "layer:transport"
        ],
        "symbols": "POST",
        "parserCalls": [
          "readEvidenceRequest"
        ],
        "readerCalls": [
          "dependencies.resolveSubmission"
        ],
        "allowedCalls": [
          "dependencies.service.submit",
          "errorResponse"
        ]
      },
      "remediation": "Pass the request only to the request-context reader and readEvidenceRequest; hand parsed values to one application service and build every response through errorResponse or Response.json."
    },
    {
      "id": "route-handlers-parse-their-input-put",
      "title": "PUT route handlers parse their input before it escapes",
      "level": "error",
      "check": {
        "kind": "require-ingress-parse",
        "files": [
          "layer:transport"
        ],
        "symbols": "PUT",
        "parserCalls": [
          "readEvidenceRequest"
        ],
        "readerCalls": [
          "dependencies.resolveSubmission"
        ],
        "allowedCalls": [
          "dependencies.service.submit",
          "errorResponse"
        ]
      },
      "remediation": "Pass the request only to the request-context reader and readEvidenceRequest; hand parsed values to one application service and build every response through errorResponse or Response.json."
    },
    {
      "id": "route-handlers-parse-their-input-patch",
      "title": "PATCH route handlers parse their input before it escapes",
      "level": "error",
      "check": {
        "kind": "require-ingress-parse",
        "files": [
          "layer:transport"
        ],
        "symbols": "PATCH",
        "parserCalls": [
          "readEvidenceRequest"
        ],
        "readerCalls": [
          "dependencies.resolveSubmission"
        ],
        "allowedCalls": [
          "dependencies.service.submit",
          "errorResponse"
        ]
      },
      "remediation": "Pass the request only to the request-context reader and readEvidenceRequest; hand parsed values to one application service and build every response through errorResponse or Response.json."
    },
    {
      "id": "route-handlers-parse-their-input-delete",
      "title": "DELETE route handlers parse their input before it escapes",
      "level": "error",
      "check": {
        "kind": "require-ingress-parse",
        "files": [
          "layer:transport"
        ],
        "symbols": "DELETE",
        "parserCalls": [
          "readEvidenceRequest"
        ],
        "readerCalls": [
          "dependencies.resolveSubmission"
        ],
        "allowedCalls": [
          "dependencies.service.submit",
          "errorResponse"
        ]
      },
      "remediation": "Pass the request only to the request-context reader and readEvidenceRequest; hand parsed values to one application service and build every response through errorResponse or Response.json."
    },
    {
      "id": "runtime-opens-at-the-boundary",
      "title": "The runtime is opened only where a request enters",
      "level": "error",
      "check": {
        "kind": "restrict-call-site",
        "callee": [
          "getRuntime"
        ],
        "allowFrom": [
          "layer:transport",
          "apps/control/src/app/app/route-context.ts"
        ]
      },
      "remediation": "Receive the runtime (or its prisma client and config) as a parameter from the route or page context instead of opening it inside a service or view."
    }
  ]
}