@adammcarter/use-cases 0.1.0

package/schemas/v1/migration-test-matrix-result.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/migration-test-matrix-result.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "digest": { "$ref": "common.schema.json#/$defs/hash" },
+        "parser": { "type": "string", "minLength": 1 }
+      },
+      "required": ["path", "digest", "parser"]
+    },
+    "mode": { "enum": ["dry_run", "write"] },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tables_found": { "type": "integer", "minimum": 0 },
+        "rows_seen": { "type": "integer", "minimum": 0 },
+        "rows_importable": { "type": "integer", "minimum": 0 },
+        "rows_needing_review": { "type": "integer", "minimum": 0 },
+        "files_planned": { "type": "integer", "minimum": 0 },
+        "files_written": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["tables_found", "rows_seen", "rows_importable", "rows_needing_review", "files_planned", "files_written"]
+    },
+    "drafts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "output_path": { "type": "string", "minLength": 1 },
+          "feature_id": { "$ref": "common.schema.json#/$defs/id" },
+          "use_case_ids": {
+            "type": "array",
+            "items": { "$ref": "common.schema.json#/$defs/id" }
+          },
+          "content": { "type": "string" }
+        },
+        "required": ["output_path", "feature_id", "use_case_ids", "content"]
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "row_ref": { "type": ["string", "null"] },
+          "message": { "type": "string", "minLength": 1 }
+        },
+        "required": ["code", "row_ref", "message"]
+      }
+    },
+    "would_write": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "action": { "enum": ["create", "update_generated", "skip_unchanged", "conflict"] }
+        },
+        "required": ["path", "action"]
+      }
+    }
+  },
+  "required": ["schema_version", "source", "mode", "summary", "drafts", "warnings", "would_write"]
+}

package/schemas/v1/presentation-plan-result.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/presentation-plan-result.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "outcome": { "enum": ["generated", "no_eligible_items", "integrity_blocked"] },
+    "plan": {
+      "anyOf": [
+        { "$ref": "presentation-plan.schema.json" },
+        { "type": "null" }
+      ]
+    },
+    "candidate_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "considered": { "type": "integer", "minimum": 0 },
+        "eligible": { "type": "integer", "minimum": 0 },
+        "selected": { "type": "integer", "minimum": 0 },
+        "excluded": { "type": "integer", "minimum": 0 },
+        "excluded_by_reason": {
+          "type": "object",
+          "additionalProperties": { "type": "integer", "minimum": 0 }
+        }
+      },
+      "required": ["considered", "eligible", "selected", "excluded", "excluded_by_reason"]
+    },
+    "input_integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "matrix": { "enum": ["clean", "partial", "unusable"] },
+        "evidence": { "enum": ["clean", "partial", "unusable"] }
+      },
+      "required": ["matrix", "evidence"]
+    }
+  },
+  "required": ["schema_version", "outcome", "plan", "candidate_summary", "input_integrity"],
+  "allOf": [
+    {
+      "if": { "properties": { "outcome": { "const": "generated" } }, "required": ["outcome"] },
+      "then": {
+        "not": { "properties": { "plan": { "type": "null" } }, "required": ["plan"] }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "outcome": { "enum": ["no_eligible_items", "integrity_blocked"] }
+        },
+        "required": ["outcome"]
+      },
+      "then": {
+        "properties": {
+          "plan": { "type": "null" }
+        }
+      }
+    }
+  ]
+}

package/schemas/v1/presentation-plan.schema.json

@@ -0,0 +1,259 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/presentation-plan.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "plan_id": { "$ref": "common.schema.json#/$defs/id" },
+    "plan_content_hash": { "$ref": "common.schema.json#/$defs/hash" },
+    "generated_at": { "$ref": "common.schema.json#/$defs/timestamp" },
+    "mode": { "enum": ["showcase", "walkthrough"] },
+    "complete": { "type": "boolean" },
+    "prepared_not_performed": { "const": true },
+    "readiness": {
+      "enum": ["ready", "ready_with_evidence_gaps", "partial_due_to_integrity", "blocked"]
+    },
+    "integrity_acknowledgement_required": { "type": "boolean" },
+    "selection_method": { "enum": ["generated", "manual", "capsule", "deterministic"] },
+    "selection_profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "version": { "type": "integer", "minimum": 1 },
+        "digest": { "$ref": "common.schema.json#/$defs/hash" }
+      },
+      "required": ["id", "version", "digest"]
+    },
+    "input_snapshot": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "matrix_digest": { "$ref": "common.schema.json#/$defs/hash" },
+        "evidence_basis_digest": { "$ref": "common.schema.json#/$defs/hash" },
+        "changed_paths": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "freshness_policy": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": { "$ref": "common.schema.json#/$defs/id" },
+            "digest": { "$ref": "common.schema.json#/$defs/hash" },
+            "evaluated_at": { "$ref": "common.schema.json#/$defs/timestamp" }
+          },
+          "required": ["id", "digest", "evaluated_at"]
+        },
+        "host_surface": { "$ref": "common.schema.json#/$defs/host_surface" },
+        "workflow": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "effective_mode": {
+              "enum": ["continuous", "backfill", "showcase_only", "audit_only", "migration", "custom"]
+            },
+            "source": { "enum": ["default", "workspace_config"] },
+            "advisory": { "const": true }
+          },
+          "required": ["effective_mode", "source", "advisory"]
+        }
+      },
+      "required": [
+        "matrix_digest",
+        "evidence_basis_digest",
+        "changed_paths",
+        "freshness_policy",
+        "host_surface",
+        "workflow"
+      ]
+    },
+    "workspace_snapshot": { "$ref": "common.schema.json#/$defs/workspace_snapshot" },
+    "environment_expectations": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "host_surfaces": {
+          "type": "array",
+          "items": { "$ref": "common.schema.json#/$defs/host_surface" }
+        }
+      },
+      "required": ["host_surfaces"]
+    },
+    "audience": { "type": "string", "minLength": 1 },
+    "timebox_seconds": { "type": "integer", "minimum": 1 },
+    "sections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "section_id": { "$ref": "common.schema.json#/$defs/id" },
+          "title": { "type": "string", "minLength": 1 },
+          "purpose": { "type": "string", "minLength": 1 },
+          "item_ids": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "common.schema.json#/$defs/id" }
+          }
+        },
+        "required": ["section_id", "title", "purpose", "item_ids"]
+      }
+    },
+    "selected_items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "plan_item_id": { "$ref": "common.schema.json#/$defs/id" },
+          "presentation_format": {
+            "enum": ["testing", "comparing", "inspecting", "reviewing", "user_led", "explaining"]
+          },
+          "delivery_kind": { "enum": ["live_demo", "evidence_review", "explanation"] },
+          "scenario_scope": { "enum": ["whole_use_case", "explicit"] },
+          "use_case_id": { "$ref": "common.schema.json#/$defs/id" },
+          "scenario_ids": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/id" } },
+          "use_case_content_hash": { "$ref": "common.schema.json#/$defs/hash" },
+          "estimated_seconds": { "type": "integer", "minimum": 1 },
+          "estimate_source": { "enum": ["use_case", "default_profile"] },
+          "setup_steps": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "resolved_steps": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "expected_observations": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "teardown_steps": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "required_permissions": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "safety_constraints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "verification_policy_snapshot": { "$ref": "common.schema.json#/$defs/verification_policy" },
+          "approval_policy_snapshot": { "$ref": "common.schema.json#/$defs/approval_policy" },
+          "approval_resolution_required_at_run_start": { "type": "boolean" },
+          "required_evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "evidence_kind": { "$ref": "common.schema.json#/$defs/evidence_kind" },
+                "required_verifiers": {
+                  "type": "array",
+                  "items": { "enum": ["user", "agent", "script"] }
+                },
+                "minimum_count": { "type": "integer", "minimum": 1 },
+                "status": {
+                  "enum": ["candidate_observed", "missing", "unknown_due_to_integrity", "not_applicable"]
+                }
+              },
+              "required": ["evidence_kind", "required_verifiers", "minimum_count", "status"]
+            }
+          },
+          "evidence_summary": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "readiness": {
+                "enum": ["available_current", "available_stale", "missing", "invalid", "unknown", "ambiguous"]
+              },
+              "active_evidence_ids": {
+                "type": "array",
+                "items": { "$ref": "common.schema.json#/$defs/id" }
+              },
+              "basis": { "type": "string", "minLength": 1 }
+            },
+            "required": ["readiness", "active_evidence_ids", "basis"]
+          },
+          "freshness_summary": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "state": { "enum": ["current", "needs_review", "stale", "unknown", "invalidated"] },
+              "basis": { "type": "string", "minLength": 1 }
+            },
+            "required": ["state", "basis"]
+          },
+          "known_gaps": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "code": { "type": "string", "minLength": 1 },
+                "message": { "type": "string", "minLength": 1 },
+                "severity": { "enum": ["info", "warning", "error"] }
+              },
+              "required": ["code", "message", "severity"]
+            }
+          },
+          "selection_reasons": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+          "selection_reason_codes": {
+            "type": "array",
+            "items": { "type": "string", "minLength": 1 }
+          },
+          "score_components": { "type": "object", "additionalProperties": { "type": "number" } }
+        },
+        "required": ["use_case_id", "scenario_ids", "use_case_content_hash", "resolved_steps", "expected_observations", "verification_policy_snapshot", "approval_policy_snapshot", "selection_reasons", "score_components"]
+      }
+    },
+    "exclusions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "use_case_id": { "$ref": "common.schema.json#/$defs/id" },
+          "reason_code": { "type": "string", "minLength": 1 },
+          "blocking": { "type": "boolean" },
+          "reason": { "type": "string", "minLength": 1 }
+        },
+        "required": ["use_case_id", "reason"]
+      }
+    },
+    "known_gaps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "code": { "type": "string", "minLength": 1 },
+          "message": { "type": "string", "minLength": 1 },
+          "severity": { "enum": ["info", "warning", "error"] }
+        },
+        "required": ["code", "message", "severity"]
+      }
+    },
+    "diagnostics": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/diagnostic" } },
+    "capsule": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "capsule_id": { "$ref": "common.schema.json#/$defs/id" },
+        "content_hash": { "$ref": "common.schema.json#/$defs/hash" }
+      },
+      "required": ["capsule_id", "content_hash"]
+    },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  },
+  "required": ["schema_version", "plan_id", "mode", "complete", "selection_method", "workspace_snapshot", "environment_expectations", "audience", "timebox_seconds", "selected_items", "exclusions"],
+  "allOf": [
+    {
+      "if": { "properties": { "complete": { "const": false } }, "required": ["complete"] },
+      "then": {
+        "properties": {
+          "diagnostics": true
+        },
+        "required": ["diagnostics"]
+      }
+    }
+  ]
+}

package/schemas/v1/release-gate-result.schema.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/release-gate-result.schema.json",
+  "title": "ucase-release-gate-result-v1",
+  "description": "The decision emitted by the release gate: per-row required_for_release status, the pass/fail verdict, the set of blocked rows, and the policy mode. In release mode a required (required_for_release: true) row that is not FRESH sets policy_block and fails the gate (see deriveFreshness policy_block and releaseGating.test.ts).",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "status": {
+      "enum": ["FRESH", "SUSPECT", "UNPROVEN", "UNBOUND", "INVALID"],
+      "description": "Freshness status of a row at gate time."
+    },
+    "row": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "row_id": { "$ref": "common.schema.json#/$defs/id" },
+        "status": { "$ref": "#/$defs/status" },
+        "required_for_release": {
+          "type": "boolean",
+          "description": "Whether the row's approval_policy declares required_for_release."
+        },
+        "policy_block": {
+          "type": "boolean",
+          "description": "True when this row blocks release (required + not FRESH in release mode)."
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Human-readable reasons the row is not FRESH or is otherwise blocked (optional). Includes AUTHORITY_INSUFFICIENT when a FRESH required row is blocked by the release-gate authority requirement."
+        },
+        "authority_type": {
+          "enum": ["ci", "local"],
+          "description": "OPTIONAL. The authority.type of the row's matching FRESH proof (CI-neutral provenance; see authority.schema.json). Present only when the proof carries an authority block. Absent when there is no matching proof or it predates the authority block."
+        },
+        "authority_protected_ref": {
+          "type": ["boolean", "null"],
+          "description": "OPTIONAL. The authority.protected_ref tri-state of the matching FRESH proof: true/false when the provider attested the protected-branch state, null when unknown. protected_ref is provider-attested where available and otherwise unknown."
+        }
+      },
+      "required": ["row_id", "status", "required_for_release", "policy_block"]
+    }
+  },
+  "properties": {
+    "schema_version": { "const": 1 },
+    "policy_mode": {
+      "enum": ["feature", "release", "custom"],
+      "description": "The freshness/gate policy mode the decision was evaluated under."
+    },
+    "passed": {
+      "type": "boolean",
+      "description": "Pass/fail verdict: true when no row sets policy_block."
+    },
+    "generated_at": { "$ref": "common.schema.json#/$defs/timestamp" },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "rows_total": { "type": "integer", "minimum": 0 },
+        "rows_required": { "type": "integer", "minimum": 0 },
+        "rows_blocked": { "type": "integer", "minimum": 0 }
+      },
+      "required": ["rows_total", "rows_required", "rows_blocked"]
+    },
+    "blocked_row_ids": {
+      "type": "array",
+      "items": { "$ref": "common.schema.json#/$defs/id" },
+      "description": "Ordered row ids that block the release."
+    },
+    "authority_requirement": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "OPTIONAL echo of the CI-neutral release-gate authority requirement this decision was evaluated under (from workspace-config release_gate). Absent when no authority requirement is configured (off by default). The trust model is CI-NEUTRAL — only the proof's authority shape is inspected, not which provider produced it.",
+      "properties": {
+        "required_authority": {
+          "enum": ["ci"],
+          "description": "When \"ci\", a required row's matching FRESH proof must carry authority.type === \"ci\"."
+        },
+        "require_protected_ref": {
+          "type": "boolean",
+          "description": "When true, a required row's matching FRESH proof must carry authority.protected_ref === true."
+        }
+      }
+    },
+    "rows": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/row" }
+    }
+  },
+  "required": ["schema_version", "policy_mode", "passed", "generated_at", "summary", "blocked_row_ids", "rows"],
+  "examples": [
+    {
+      "schema_version": 1,
+      "policy_mode": "release",
+      "passed": false,
+      "generated_at": "2026-06-28T12:10:00Z",
+      "summary": { "rows_total": 2, "rows_required": 1, "rows_blocked": 1 },
+      "blocked_row_ids": ["checkout.apply_coupon"],
+      "rows": [
+        {
+          "row_id": "checkout.apply_coupon",
+          "status": "UNPROVEN",
+          "required_for_release": true,
+          "policy_block": true,
+          "reasons": ["row has a registered binding but no trusted proof event"]
+        },
+        {
+          "row_id": "checkout.view_cart",
+          "status": "FRESH",
+          "required_for_release": false,
+          "policy_block": false
+        }
+      ]
+    },
+    {
+      "schema_version": 1,
+      "policy_mode": "release",
+      "passed": false,
+      "generated_at": "2026-06-28T12:10:00Z",
+      "summary": { "rows_total": 1, "rows_required": 1, "rows_blocked": 1 },
+      "blocked_row_ids": ["checkout.apply_coupon"],
+      "authority_requirement": { "required_authority": "ci", "require_protected_ref": true },
+      "rows": [
+        {
+          "row_id": "checkout.apply_coupon",
+          "status": "FRESH",
+          "required_for_release": true,
+          "policy_block": true,
+          "reasons": ["AUTHORITY_INSUFFICIENT: release gate requires authority.type === \"ci\" and authority.protected_ref === true, but the matching proof was minted locally"],
+          "authority_type": "local",
+          "authority_protected_ref": null
+        }
+      ]
+    }
+  ]
+}

package/schemas/v1/showcase-approval-result.schema.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/showcase-approval-result.schema.json",
+  "$ref": "showcase-event-append-result.schema.json"
+}

package/schemas/v1/showcase-event-append-result.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/showcase-event-append-result.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "run_id": { "$ref": "common.schema.json#/$defs/id" },
+    "appended_event_ids": {
+      "type": "array",
+      "items": { "$ref": "common.schema.json#/$defs/id" }
+    },
+    "event": { "$ref": "showcase-event.schema.json" },
+    "status": { "$ref": "showcase-run-status-result.schema.json" }
+  },
+  "required": ["schema_version", "run_id", "appended_event_ids", "event", "status"]
+}