@adammcarter/use-cases 0.1.0

package/packages/core/dist/schemas/v1/showcase-event.schema.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/showcase-event.schema.json",
+  "oneOf": [
+    { "$ref": "#/$defs/p6_event" },
+    { "$ref": "#/$defs/run_started" },
+    { "$ref": "#/$defs/action_recorded" },
+    { "$ref": "#/$defs/observation_recorded" },
+    { "$ref": "#/$defs/verdict_recorded" },
+    { "$ref": "#/$defs/run_finished" },
+    { "$ref": "#/$defs/approval_recorded" }
+  ],
+  "$defs": {
+    "base_props": {
+      "schema_version": { "const": 1 },
+      "event_id": { "$ref": "common.schema.json#/$defs/id" },
+      "aggregate_id": { "$ref": "common.schema.json#/$defs/id" },
+      "sequence": { "type": "integer", "minimum": 1 },
+      "recorded_at": { "$ref": "common.schema.json#/$defs/timestamp" },
+      "actor_type": { "$ref": "common.schema.json#/$defs/actor_type" },
+      "host_surface": { "$ref": "common.schema.json#/$defs/host_surface" },
+      "idempotency_key": { "type": "string", "minLength": 1 }
+    },
+    "p6_event": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": { "const": 1 },
+        "event_type": {
+          "enum": [
+            "run_started",
+            "action_recorded",
+            "observation_recorded",
+            "verdict_recorded",
+            "failure_decision_recorded",
+            "run_paused",
+            "run_resumed",
+            "epoch_started",
+            "carry_forward_recorded",
+            "run_finished",
+            "approval_recorded",
+            "approval_rejected",
+            "approval_retracted",
+            "observation_corrected",
+            "verdict_corrected",
+            "failure_decision_corrected",
+            "carry_forward_corrected",
+            "finish_corrected"
+          ]
+        },
+        "event_id": { "$ref": "common.schema.json#/$defs/id" },
+        "run_id": { "$ref": "common.schema.json#/$defs/id" },
+        "aggregate_id": { "$ref": "common.schema.json#/$defs/id" },
+        "sequence": { "type": "integer", "minimum": 1 },
+        "recorded_at": { "$ref": "common.schema.json#/$defs/timestamp" },
+        "actor_type": { "$ref": "common.schema.json#/$defs/actor_type" },
+        "host_surface": { "$ref": "common.schema.json#/$defs/host_surface" },
+        "idempotency_key": { "type": "string", "minLength": 1 },
+        "intent_digest": { "$ref": "common.schema.json#/$defs/hash" },
+        "payload": { "type": "object" }
+      },
+      "required": [
+        "schema_version",
+        "event_type",
+        "event_id",
+        "run_id",
+        "aggregate_id",
+        "sequence",
+        "recorded_at",
+        "actor_type",
+        "host_surface",
+        "idempotency_key",
+        "intent_digest",
+        "payload"
+      ]
+    },
+    "run_started": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "event_type": { "const": "run_started" },
+        "plan": { "$ref": "presentation-plan.schema.json" },
+        "schema_version": { "$ref": "#/$defs/base_props/schema_version" },
+        "event_id": { "$ref": "#/$defs/base_props/event_id" },
+        "aggregate_id": { "$ref": "#/$defs/base_props/aggregate_id" },
+        "sequence": { "$ref": "#/$defs/base_props/sequence" },
+        "recorded_at": { "$ref": "#/$defs/base_props/recorded_at" },
+        "actor_type": { "$ref": "#/$defs/base_props/actor_type" },
+        "host_surface": { "$ref": "#/$defs/base_props/host_surface" },
+        "idempotency_key": { "$ref": "#/$defs/base_props/idempotency_key" }
+      },
+      "required": ["schema_version", "event_type", "event_id", "aggregate_id", "sequence", "recorded_at", "actor_type", "host_surface", "idempotency_key", "plan"]
+    },
+    "action_recorded": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "event_type": { "const": "action_recorded" },
+        "action": { "type": "object" },
+        "schema_version": { "$ref": "#/$defs/base_props/schema_version" },
+        "event_id": { "$ref": "#/$defs/base_props/event_id" },
+        "aggregate_id": { "$ref": "#/$defs/base_props/aggregate_id" },
+        "sequence": { "$ref": "#/$defs/base_props/sequence" },
+        "recorded_at": { "$ref": "#/$defs/base_props/recorded_at" },
+        "actor_type": { "$ref": "#/$defs/base_props/actor_type" },
+        "host_surface": { "$ref": "#/$defs/base_props/host_surface" },
+        "idempotency_key": { "$ref": "#/$defs/base_props/idempotency_key" }
+      },
+      "required": ["schema_version", "event_type", "event_id", "aggregate_id", "sequence", "recorded_at", "actor_type", "host_surface", "idempotency_key", "action"]
+    },
+    "observation_recorded": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "event_type": { "const": "observation_recorded" },
+        "observation": { "type": "object" },
+        "schema_version": { "$ref": "#/$defs/base_props/schema_version" },
+        "event_id": { "$ref": "#/$defs/base_props/event_id" },
+        "aggregate_id": { "$ref": "#/$defs/base_props/aggregate_id" },
+        "sequence": { "$ref": "#/$defs/base_props/sequence" },
+        "recorded_at": { "$ref": "#/$defs/base_props/recorded_at" },
+        "actor_type": { "$ref": "#/$defs/base_props/actor_type" },
+        "host_surface": { "$ref": "#/$defs/base_props/host_surface" },
+        "idempotency_key": { "$ref": "#/$defs/base_props/idempotency_key" }
+      },
+      "required": ["schema_version", "event_type", "event_id", "aggregate_id", "sequence", "recorded_at", "actor_type", "host_surface", "idempotency_key", "observation"]
+    },
+    "verdict_recorded": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "event_type": { "const": "verdict_recorded" },
+        "verdict": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "use_case_id": { "$ref": "common.schema.json#/$defs/id" },
+            "decision": { "$ref": "common.schema.json#/$defs/verdict" }
+          },
+          "required": ["use_case_id", "decision"]
+        },
+        "schema_version": { "$ref": "#/$defs/base_props/schema_version" },
+        "event_id": { "$ref": "#/$defs/base_props/event_id" },
+        "aggregate_id": { "$ref": "#/$defs/base_props/aggregate_id" },
+        "sequence": { "$ref": "#/$defs/base_props/sequence" },
+        "recorded_at": { "$ref": "#/$defs/base_props/recorded_at" },
+        "actor_type": { "$ref": "#/$defs/base_props/actor_type" },
+        "host_surface": { "$ref": "#/$defs/base_props/host_surface" },
+        "idempotency_key": { "$ref": "#/$defs/base_props/idempotency_key" }
+      },
+      "required": ["schema_version", "event_type", "event_id", "aggregate_id", "sequence", "recorded_at", "actor_type", "host_surface", "idempotency_key", "verdict"]
+    },
+    "run_finished": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "event_type": { "const": "run_finished" },
+        "finish": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "outcome": { "enum": ["passed", "passed_with_waivers", "partial", "failed", "blocked"] }
+          },
+          "required": ["outcome"]
+        },
+        "schema_version": { "$ref": "#/$defs/base_props/schema_version" },
+        "event_id": { "$ref": "#/$defs/base_props/event_id" },
+        "aggregate_id": { "$ref": "#/$defs/base_props/aggregate_id" },
+        "sequence": { "$ref": "#/$defs/base_props/sequence" },
+        "recorded_at": { "$ref": "#/$defs/base_props/recorded_at" },
+        "actor_type": { "$ref": "#/$defs/base_props/actor_type" },
+        "host_surface": { "$ref": "#/$defs/base_props/host_surface" },
+        "idempotency_key": { "$ref": "#/$defs/base_props/idempotency_key" }
+      },
+      "required": ["schema_version", "event_type", "event_id", "aggregate_id", "sequence", "recorded_at", "actor_type", "host_surface", "idempotency_key", "finish"]
+    },
+    "approval_recorded": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "event_type": { "const": "approval_recorded" },
+        "approval": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "decision": { "enum": ["approved", "rejected", "approved_with_known_gaps"] },
+            "approver": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": { "enum": ["user", "agent"] },
+                "identity": { "type": "string", "minLength": 1 }
+              },
+              "required": ["type", "identity"]
+            },
+            "recorded_by": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "type": { "enum": ["cli", "host"] },
+                "identity": { "type": "string", "minLength": 1 }
+              },
+              "required": ["type", "identity"]
+            },
+            "capture_method": { "enum": ["interactive_cli", "host_prompt"] },
+            "scope": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "run_id": { "$ref": "common.schema.json#/$defs/id" },
+                "plan_hash": { "$ref": "common.schema.json#/$defs/hash" },
+                "workspace_snapshot": { "$ref": "common.schema.json#/$defs/workspace_snapshot" },
+                "environment_snapshot": { "type": "object" },
+                "exclusions": { "type": "array" }
+              },
+              "required": ["run_id", "plan_hash", "workspace_snapshot", "environment_snapshot", "exclusions"]
+            },
+            "resolved_policy": { "$ref": "common.schema.json#/$defs/approval_policy" },
+            "statement": { "type": "string", "minLength": 1 }
+          },
+          "required": ["decision", "approver", "recorded_by", "capture_method", "scope", "resolved_policy", "statement"]
+        },
+        "schema_version": { "$ref": "#/$defs/base_props/schema_version" },
+        "event_id": { "$ref": "#/$defs/base_props/event_id" },
+        "aggregate_id": { "$ref": "#/$defs/base_props/aggregate_id" },
+        "sequence": { "$ref": "#/$defs/base_props/sequence" },
+        "recorded_at": { "$ref": "#/$defs/base_props/recorded_at" },
+        "actor_type": { "$ref": "#/$defs/base_props/actor_type" },
+        "host_surface": { "$ref": "#/$defs/base_props/host_surface" },
+        "idempotency_key": { "$ref": "#/$defs/base_props/idempotency_key" }
+      },
+      "required": ["schema_version", "event_type", "event_id", "aggregate_id", "sequence", "recorded_at", "actor_type", "host_surface", "idempotency_key", "approval"]
+    }
+  }
+}

package/packages/core/dist/schemas/v1/showcase-finish-result.schema.json

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

package/packages/core/dist/schemas/v1/showcase-run-status-result.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/showcase-run-status-result.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "run_id": { "$ref": "common.schema.json#/$defs/id" },
+    "complete": { "type": "boolean" },
+    "execution_status": {
+      "enum": ["prepared_not_performed", "running", "paused", "completed", "aborted", "incomplete"]
+    },
+    "run_outcome": {
+      "enum": ["prepared_not_performed", "passed", "passed_with_waivers", "partial", "failed", "blocked", "aborted", "incomplete"]
+    },
+    "approval_state": {
+      "enum": [
+        "not_required",
+        "resolution_required",
+        "pending",
+        "approved",
+        "rejected",
+        "approved_with_known_gaps",
+        "stale_due_to_run_change"
+      ]
+    },
+    "unresolved_failure_count": { "type": "integer", "minimum": 0 },
+    "items": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "plan_item_id": { "$ref": "common.schema.json#/$defs/id" },
+          "verdict": { "enum": ["pass", "partial", "fail", "waived", "blocked", "none"] },
+          "item_currency": {
+            "enum": ["current", "stale_due_to_epoch_change", "carried_forward", "corrected", "unknown"]
+          },
+          "verification_state": {
+            "enum": ["not_required", "requirements_unmet", "requirements_met", "stale", "unknown_due_to_integrity"]
+          },
+          "latest_observation_event_id": { "type": ["string", "null"] },
+          "latest_verdict_event_id": { "type": ["string", "null"] }
+        },
+        "required": [
+          "plan_item_id",
+          "verdict",
+          "item_currency",
+          "verification_state",
+          "latest_observation_event_id",
+          "latest_verdict_event_id"
+        ]
+      }
+    },
+    "known_gaps": { "type": "array", "items": { "type": "object" } },
+    "diagnostic_summary": { "type": "object" }
+  },
+  "required": [
+    "schema_version",
+    "run_id",
+    "complete",
+    "execution_status",
+    "run_outcome",
+    "approval_state",
+    "unresolved_failure_count",
+    "items",
+    "known_gaps",
+    "diagnostic_summary"
+  ]
+}

package/packages/core/dist/schemas/v1/showcase-start-result.schema.json

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

package/packages/core/dist/schemas/v1/use-case-file.schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/use-case-file.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "feature": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "name": { "type": "string", "minLength": 1 },
+        "summary": { "type": "string", "minLength": 1 }
+      },
+      "required": ["id", "name", "summary"]
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "owner": { "type": "string", "minLength": 1 },
+        "lifecycle": { "enum": ["planned", "active", "deprecated", "removed"] },
+        "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+      }
+    },
+    "use_cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/use_case" }
+    },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  },
+  "required": ["schema_version", "feature", "use_cases"],
+  "$defs": {
+    "use_case": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "title": { "type": "string", "minLength": 1 },
+        "lifecycle": { "enum": ["planned", "active", "deprecated", "removed"] },
+        "value_tier": { "enum": ["critical", "core", "supporting", "long_tail"] },
+        "journey_role": { "enum": ["golden", "alternate", "edge", "negative", "failure"] },
+        "usage_frequency": { "enum": ["common", "occasional", "rare"] },
+        "tags": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "$ref": "common.schema.json#/$defs/id" }
+        },
+        "source_refs": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kind": { "const": "file" },
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "not": {
+                  "anyOf": [
+                    { "pattern": "^/" },
+                    { "pattern": "(^|/)\\.\\.(/|$)" }
+                  ]
+                }
+              }
+            },
+            "required": ["kind", "path"]
+          }
+        },
+        "related_use_cases": {
+          "type": "array",
+          "items": { "$ref": "common.schema.json#/$defs/id" }
+        },
+        "actor": { "type": "string", "minLength": 1 },
+        "intent": { "type": "string", "minLength": 1 },
+        "preconditions": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "trigger": { "type": "string", "minLength": 1 },
+        "scenarios": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "oneOf": [
+              { "$ref": "#/$defs/gherkin_scenario" },
+              { "$ref": "#/$defs/steps_scenario" }
+            ]
+          }
+        },
+        "observable_outcomes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "host_applicability": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "host_surface": { "$ref": "common.schema.json#/$defs/host_surface" },
+              "supported": { "type": "boolean" },
+              "notes": { "type": "string" }
+            },
+            "required": ["host_surface", "supported"]
+          }
+        },
+        "verification_policy": { "$ref": "common.schema.json#/$defs/verification_policy" },
+        "approval_policy": { "$ref": "common.schema.json#/$defs/approval_policy" },
+        "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+      },
+      "required": ["id", "title", "lifecycle", "value_tier", "journey_role", "usage_frequency"],
+      "allOf": [
+        {
+          "if": {
+            "properties": { "lifecycle": { "const": "active" } },
+            "required": ["lifecycle"]
+          },
+          "then": {
+            "properties": {
+              "actor": true,
+              "intent": true,
+              "preconditions": true,
+              "trigger": true,
+              "scenarios": true,
+              "observable_outcomes": true,
+              "host_applicability": true,
+              "verification_policy": true,
+              "approval_policy": true
+            },
+            "required": [
+              "actor",
+              "intent",
+              "preconditions",
+              "trigger",
+              "scenarios",
+              "observable_outcomes",
+              "host_applicability",
+              "verification_policy",
+              "approval_policy"
+            ]
+          }
+        }
+      ]
+    },
+    "gherkin_scenario": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "kind": { "const": "gherkin" },
+        "given": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "when": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "then": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+      },
+      "required": ["id", "kind", "given", "when", "then"]
+    },
+    "steps_scenario": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "kind": { "const": "steps" },
+        "steps": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "observable_outcomes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      },
+      "required": ["id", "kind", "steps"]
+    }
+  }
+}

package/packages/core/dist/schemas/v1/workflow-mode.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/workflow-mode.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "mode": {
+      "enum": ["continuous", "backfill", "showcase_only", "audit_only", "migration", "custom"]
+    },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  },
+  "required": ["schema_version", "mode"]
+}

package/packages/core/dist/schemas/v1/workspace-config.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://use-cases.dev/schemas/v1/workspace-config.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": { "const": 1 },
+    "workspace_id": { "$ref": "common.schema.json#/$defs/id" },
+    "data_root": { "$ref": "#/$defs/relative_path" },
+    "use_cases_dir": { "$ref": "#/$defs/relative_path" },
+    "evidence_dir": { "$ref": "#/$defs/relative_path" },
+    "demo_capsules_dir": { "$ref": "#/$defs/relative_path" },
+    "showcase_runs_dir": { "$ref": "#/$defs/relative_path" },
+    "component_id": { "$ref": "common.schema.json#/$defs/id" },
+    "default_workflow_mode": {
+      "enum": ["continuous", "backfill", "showcase_only", "audit_only", "migration", "custom"]
+    },
+    "verifiers": { "$ref": "#/$defs/verifiers_config" },
+    "release_gate": { "$ref": "#/$defs/release_gate" },
+    "extensions": { "$ref": "common.schema.json#/$defs/extensions" }
+  },
+  "required": ["schema_version", "workspace_id", "data_root", "use_cases_dir", "evidence_dir", "demo_capsules_dir", "showcase_runs_dir", "component_id"],
+  "$defs": {
+    "release_gate": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "OPTIONAL CI-neutral release-gate authority requirement (off by default). When present, a required_for_release row whose only FRESH proof was minted with insufficient provenance authority is policy-blocked in RELEASE mode only; feature mode is never affected. The trust model is CI-NEUTRAL — only the proof's authority shape is inspected (see schemas/v1/authority.schema.json), not which provider produced it. Omitting this object, or leaving every field unset/falsy, preserves today's gating exactly.",
+      "properties": {
+        "required_authority": {
+          "enum": ["ci"],
+          "description": "When \"ci\", a required row's matching FRESH proof must carry authority.type === \"ci\" (minted inside a recognised CI provider). A local-run proof (or no authority block) is insufficient and blocks release."
+        },
+        "require_protected_ref": {
+          "type": "boolean",
+          "description": "When true, a required row's matching FRESH proof must carry authority.protected_ref === true (the provider attested a protected branch). false/null/unknown is insufficient. protected_ref is provider-attested where available and otherwise unknown."
+        }
+      }
+    },
+    "verifiers_config": {
+      "type": "object",
+      "propertyNames": { "$ref": "common.schema.json#/$defs/id" },
+      "properties": {
+        "default": { "$ref": "common.schema.json#/$defs/id" }
+      },
+      "additionalProperties": { "$ref": "common.schema.json#/$defs/verifier" }
+    },
+    "relative_path": {
+      "type": "string",
+      "minLength": 1,
+      "not": {
+        "anyOf": [
+          { "pattern": "^/" },
+          { "pattern": "(^|/)\\.\\.(/|$)" }
+        ]
+      }
+    }
+  }
+}