@codyswann/lisa 2.345.1 → 2.348.0

package/all/copy-overwrite/scripts/schemas/lisa-state-contract.v1.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lisa.codyswann.dev/schemas/lisa-state-contract.v1.schema.json",
+  "title": "Lisa state contract (v1)",
+  "description": "Per-project declaration of every persistent entity and the reset policy that governs it. Governed by the reset-seed-coverage rule. The check compares a runtime inventory against this document and fails closed on any entity the document does not classify.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "contractVersion", "mode", "owner"],
+  "properties": {
+    "schemaVersion": {
+      "const": "lisa-state-contract-v1",
+      "description": "Pinned schema version. A bump is a deliberate migration."
+    },
+    "contractVersion": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The project's own version for its declared state. Bump whenever a policy or ownership predicate changes, so evidence from one run cannot be read as evidence for a different contract."
+    },
+    "mode": {
+      "enum": ["contract", "declared-noop"],
+      "description": "contract = this project holds persistent state and classifies it below. declared-noop = this project holds no persistent state; the check verifies that claim against the repository rather than trusting it."
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Team or role that answers questions about this file. Not an individual's personal account."
+    },
+    "noop": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "owner", "capabilityManifest"],
+      "description": "Required when mode is declared-noop. A bare exit 0 is indistinguishable from a successful destructive run and never satisfies the contract.",
+      "properties": {
+        "reason": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "capabilityManifest": { "type": "string", "minLength": 1 }
+      }
+    },
+    "environments": {
+      "type": "array",
+      "description": "Environments a reset may target. Each names how the environment identity is resolved server-side; a caller-supplied stage is only a request checked against it.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name", "identitySource"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "identitySource": { "type": "string", "minLength": 1 },
+          "resetAllowed": { "type": "boolean" }
+        }
+      }
+    },
+    "fixtureIdentity": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["description"],
+      "description": "How fixture-owned records are recognized. The ownership predicate the entire safety model rests on: a reserved id shape, a reserved account or namespace, or a marker attribute.",
+      "properties": {
+        "description": { "type": "string", "minLength": 1 },
+        "idPattern": { "type": "string", "minLength": 1 },
+        "reservedPrincipals": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "detection": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Tuning for the subtraction detectors. Detectors are a staleness signal, never the safety boundary.",
+      "properties": {
+        "sources": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Extra repository paths to scan for declared entities (migrations, schema files, model definitions)."
+        },
+        "ignore": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Entity names the detectors may find but that are not real persistent entities (framework bookkeeping, examples in docs)."
+        }
+      }
+    },
+    "entities": {
+      "type": "array",
+      "description": "One entry per persistent entity. Rows are only one kind of state: identity-provider objects, object-storage prefixes, search indexes, queues, caches, derived views, scheduled jobs and outbound side effects all belong here too.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "kind", "policy", "reason", "owner"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable, fully qualified identifier: namespace/schema plus name."
+          },
+          "kind": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The project's own vocabulary for what sort of state this is (table, view, materialized-view, identity-group, object-prefix, search-index, queue, cache-namespace, scheduled-job, external-record, ...)."
+          },
+          "policy": {
+            "enum": [
+              "fixture-owned",
+              "preserve",
+              "derived-rebuild",
+              "forbidden"
+            ],
+            "description": "fixture-owned = the reset may delete records it owns. preserve = untouched. derived-rebuild = recomputed from sources. forbidden = the reset must be structurally unable to touch it."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why this policy, in one sentence a reviewer can check. Classify by provenance (who writes it, can anything put it back), never by an emptiness observation."
+          },
+          "owner": { "type": "string", "minLength": 1 },
+          "ownership": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Required for fixture-owned: the predicate identifying which records the reset may delete. Never 'everything in this entity'."
+          },
+          "sweptBy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Required for fixture-owned: the routine that actually removes them. A fixture-owned entity nothing sweeps is the leak this contract exists to catch."
+          },
+          "rebuiltFrom": { "type": "string", "minLength": 1 },
+          "rebuiltBy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Required for derived-rebuild: the routine that recomputes it, and proves convergence."
+          },
+          "enforcedBy": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Required for forbidden: a control OUTSIDE the reset process — a least-privilege role, a revoked grant, a separate credential boundary, a constraint. 'The script does not touch it' is not an enforcement."
+          },
+          "retiredAt": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Set when the entity no longer exists. A classified entity absent from the inventory is stale and fails unless retired with a date."
+          }
+        }
+      }
+    },
+    "assurances": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "The required properties of the reset, each pointing at the evidence that proves it. A declaration with no evidence pointer fails the check.",
+      "properties": {
+        "preserves-non-fixture-data": { "$ref": "#/$defs/assurance" },
+        "rejects-reserved-id-collision": { "$ref": "#/$defs/assurance" },
+        "rejects-foreign-references": { "$ref": "#/$defs/assurance" },
+        "requires-write-acknowledgment": { "$ref": "#/$defs/assurance" },
+        "converges-on-second-apply": { "$ref": "#/$defs/assurance" },
+        "verifies-exact-counts": { "$ref": "#/$defs/assurance" },
+        "production-fails-closed": { "$ref": "#/$defs/assurance" },
+        "guard-at-the-choke-point": { "$ref": "#/$defs/assurance" },
+        "enumerates-before-mutating": { "$ref": "#/$defs/assurance" }
+      }
+    },
+    "waivers": {
+      "type": "array",
+      "description": "Dated IOUs for entities that genuinely cannot be classified yet. A waived entity is treated as preserve for safety and stays a visible finding; it never counts as classified.",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "reason", "owner", "ticket", "recordedAt"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 },
+          "owner": { "type": "string", "minLength": 1 },
+          "ticket": { "type": "string", "minLength": 1 },
+          "recordedAt": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "assurance": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["evidence"],
+      "properties": {
+        "evidence": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Pointer to the test, guard, role, or grant that proves this property."
+        },
+        "note": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/all/create-only/state/README.md

@@ -0,0 +1,41 @@
+# State contract
+
+`state-contract.json` is this project's declaration of every persistent entity and the reset policy
+that governs it, required by Lisa's `reset-seed-coverage` rule.
+
+Copy `state-contract.example.json` to `state-contract.json` and fill it in. Until that file exists,
+the state-classification check reports `not-adopted` — adoption is an explicit act, so no repo
+silently passes a gate it never wired.
+
+```bash
+node scripts/check-state-classification.mjs
+```
+
+Schema: `scripts/schemas/lisa-state-contract.v1.schema.json`.
+
+## The two things the template cannot do for you
+
+**Classify by provenance, not by observation.** "The table looked empty" is not evidence it is
+unused. Row-count statistics are approximations, and a table nobody has analyzed reports rows it
+holds. Ask who writes it and whether anything can put it back. Prefer `preserve` when unsure — an
+over-preserved entity leaks; an over-cleared one destroys.
+
+**Include state that is not rows.** Identity-provider objects, object-storage prefixes, search
+indexes, queues and dead-letter backlogs, caches with a persistence tier, derived and materialized
+views, runtime-created jobs, and outbound side effects all belong in `entities`. Leaked test state is
+most expensive exactly where nobody thought to look.
+
+## The four policies
+
+| Policy | Meaning |
+|---|---|
+| `fixture-owned` | The reset may delete records it owns here. Requires an `ownership` predicate and a `sweptBy` routine — an entity the suite creates but nothing removes is the leak this contract exists to catch. |
+| `preserve` | Left untouched. Catalog, reference data, anything a migration seeds, anything belonging to someone real. |
+| `derived-rebuild` | Recomputed from its sources after the reset, then proven converged. |
+| `forbidden` | The reset must be structurally unable to touch it. Requires `enforcedBy` naming a control outside the reset process — a role, a revoked grant, a credential boundary. "The script does not touch it" is not an enforcement. |
+
+## No persistent state at all?
+
+Set `"mode": "declared-noop"` and fill in the `noop` block (reason, owner, capability-manifest
+reference) instead of `entities`. The check verifies that claim against the repository rather than
+trusting it: a repo showing persistence signals may not declare a reset noop.

package/all/create-only/state/state-contract.example.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": "lisa-state-contract-v1",
+  "contractVersion": "REPLACE-ME-state-v1",
+  "mode": "contract",
+  "owner": "REPLACE-ME-team-or-role",
+  "environments": [
+    {
+      "name": "dev",
+      "identitySource": "REPLACE-ME: how the environment identity is resolved SERVER-SIDE. A caller-supplied --stage, URL or public build-time variable is a request to check against this, never the answer.",
+      "resetAllowed": true
+    },
+    {
+      "name": "production",
+      "identitySource": "REPLACE-ME",
+      "resetAllowed": false
+    }
+  ],
+  "fixtureIdentity": {
+    "description": "REPLACE-ME: how a fixture-owned record is recognized. Everything the reset may delete must match this; anything else belongs to someone real.",
+    "idPattern": "REPLACE-ME-or-remove",
+    "reservedPrincipals": []
+  },
+  "entities": [
+    {
+      "id": "REPLACE-ME.example_table",
+      "kind": "table",
+      "policy": "fixture-owned",
+      "reason": "REPLACE-ME: one sentence a reviewer can check.",
+      "owner": "REPLACE-ME",
+      "ownership": "REPLACE-ME: the predicate identifying records the reset may delete. Never 'everything in this entity'.",
+      "sweptBy": "REPLACE-ME: the routine that actually removes them. A fixture-owned entity nothing sweeps is the leak this contract exists to catch."
+    }
+  ],
+  "assurances": {
+    "preserves-non-fixture-data": { "evidence": "REPLACE-ME: test or role" },
+    "rejects-reserved-id-collision": { "evidence": "REPLACE-ME" },
+    "rejects-foreign-references": { "evidence": "REPLACE-ME" },
+    "requires-write-acknowledgment": { "evidence": "REPLACE-ME" },
+    "converges-on-second-apply": { "evidence": "REPLACE-ME" },
+    "verifies-exact-counts": { "evidence": "REPLACE-ME" },
+    "production-fails-closed": { "evidence": "REPLACE-ME" },
+    "guard-at-the-choke-point": { "evidence": "REPLACE-ME" },
+    "enumerates-before-mutating": { "evidence": "REPLACE-ME" }
+  },
+  "waivers": []
+}

package/dist/core/upstream-evidence-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA4qEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA+vNjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}
+{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0tEpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA0zNjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}