diff --git a/dav/CHANGELOG.md b/dav/CHANGELOG.md new file mode 100644 index 0000000..cdb8c2b --- /dev/null +++ b/dav/CHANGELOG.md @@ -0,0 +1,110 @@ +# DCM Validation Corpus — Changelog + +## 2026-04-26 — Migration into the DCM repo + +Moved from `croadfeldt/dcm-self-test-corpus` to `croadfeldt/dcm/dav/` +following ADR-001 (DAV as standalone consumer-agnostic framework, DCM +as its first consumer). + +Path renames: +- `use_cases/` → `use-cases/` (hyphen, matching DCM convention) +- `use_cases/cross_domain/` → `use-cases/cross-domain/` +- `schema/` → `schemas/` (plural, matching DCM convention) + +Internal updates: +- All cross-domain UC `handle:` fields rewritten from `cross_domain/x` + to `cross-domain/x` to match the new directory layout. +- `analysis.schema.json` moved to the DAV repo (`engine/src/dav/schemas/`) + since it describes DAV output, not corpus content. +- `dav-version.yaml` removed; provenance now tracked via `git rev-parse + HEAD` of the DCM repo itself. + +The dimension vocabulary value `policy_complexity: cross_domain_constraint` +intentionally retains its underscore form — it's a controlled vocabulary +term, not a path. + +Vocabulary rename (same date): the dimension value +`resource_complexity: compound_service` was renamed to +`composite_service` to match the architecture's adoption of "Composite +Service" as the canonical catalog-level term (Meta Provider was retired +as a provider type; what was previously called a compound service is +now a Composite Service registered by an ordinary Service Provider). +The UC `cross-domain/tenant-onboarding.yaml` was updated to use the new +value. Historical entries below mentioning `compound_service` describe +the value as it was when those entries were written — the actual +vocabulary value in use today is `composite_service`. + + +## Unreleased + +### Added + +- Six additional hand-authored use cases expanding Phase 1a coverage + across new domains, profiles, and failure shapes: + - `data/persistent-volume-provision` (uc-seed-004a, dev profile) — + happy-path storage provisioning; introduces the `data` domain. + - `governance/policy-override-approval` (uc-seed-005a, prod profile) + — soft-policy override workflow with human-in-loop approval; + exercises the override_requests machinery. + - `compute/vm-provision-with-provider-failure` (uc-seed-006a, + standard profile) — recovery policy path when a service provider + becomes unreachable mid-realization; first use of the + `recovery_policy` dimension value. + - `governance/audit-merkle-tree-verification` (uc-seed-007a, sovereign + profile) — cryptographic verification of historical audit events + via Merkle inclusion and consistency proofs with sovereignty-scoped + key material. + - `cross-domain/tenant-onboarding` (uc-seed-008a, fsi profile) — + atomic onboarding of a new FSI tenant across identity, policy, + data, and provider domains; first use of `compound_service` and + `compliance_gated` in the corpus. + - `governance/minimal-profile-policy-scope-boundary` (uc-seed-009a, + minimal profile) — negative architectural claim: FSI-scoped + policies (data-residency, dual-approval, encryption-at-rest-mandatory) + must NOT evaluate against minimal-profile requests. Exercises + the profile inheritance boundary at the bottom of the profile + chain. + +- Two new domain directories: `use-cases/data/` and `use-cases/governance/`. + +- Profile coverage expanded: `dev`, `fsi`, and `minimal` now represented + (previously only `standard`, `prod`, `sovereign`). + +- Controlled-vocabulary cell coverage expanded: + - `lifecycle_phase`: adds `modification` (override and audit-verification + flows). + - `resource_complexity`: adds `compound_service` (tenant onboarding). + - `policy_complexity`: adds `recovery_policy`, `system_defaults_only`. + - `provider_landscape`: adds `multiple_eligible`, `mixed`. + - `governance_context`: adds `audit_heavy`, `compliance_gated`, + `no_governance`. + - `failure_mode`: adds `provider_failure`. + +### Initial seed (previously released) + +- Initial seed with 3 hand-authored use cases covering foundational + scenarios across three domains: + - `compute/vm-standard-provision` — happy-path VM creation in the + standard profile. Foundational baseline. + - `cross-domain/sovereign-decommission-with-peer` — edge case + exercising peer_dcm coordination during sovereign-profile + decommission with peer disconnection failure mode. + - `identity/auth-provider-drift-detection` — drift detection + between DCM's identity cache and the authoritative IdP, with + human-escalation policy path. + +- Schema definitions (`schema/use_case.schema.json`, + `schema/analysis.schema.json`) matching DCM self-test engine + v1.0 canonical schemas. + +- Governance documentation: contribution workflow, review criteria, + retirement policy, controlled-vocabulary reference. + +### Notes + +- No baselines yet. Baselines will be generated when the stage 2 + engine first runs these cases against the current DCM spec. +- Repository currently at `croadfeldt/dcm-self-test-corpus` during + the validation phase. Migration to `dcm-project/dcm-self-test-corpus` + is planned once the process has accumulated ~25 validated cases + and demonstrated its value through a full PR cycle. diff --git a/dav/README.md b/dav/README.md new file mode 100644 index 0000000..caf1a25 --- /dev/null +++ b/dav/README.md @@ -0,0 +1,136 @@ +# DCM Validation Corpus + +The curated body of use cases that define what the DCM (Data Center +Management) architecture is contractually required to support. This +corpus is consumed by [DAV](https://github.com/croadfeldt/dav) (DCM +Architecture Validation), which runs each use case through an LLM- +driven analysis to verify the architecture supports the scenario. + +## What lives here + +``` +dav/ +├── README.md (this file) +├── CHANGELOG.md (corpus evolution) +├── schemas/ +│ └── use_case.schema.json (UC YAML structure) +└── use-cases/ + ├── compute/ (VMs, bare metal, containers) + ├── cross-domain/ (scenarios crossing 2+ domains) + ├── data/ (data services, storage) + ├── governance/ (policy, compliance, audit) + └── identity/ (authn/authz, IdP integration) +``` + +The DAV analysis output schema (`analysis.schema.json`) lives in the +DAV repo at `engine/src/dav/schemas/`, since it describes DAV's output +format rather than corpus content. + +## Use case format + +Every use case is a YAML file conforming to `schemas/use_case.schema.json`. + +Filename convention: `.yaml` — a use case with +handle `compute/vm-standard-provision` lives at +`use-cases/compute/vm-standard-provision.yaml`. The handle's first +segment is the domain (matching the directory); the second segment +matches the filename. + +UUID convention: `uc-` generated at creation time; stable for the +life of the use case. + +## How DAV consumes this + +DAV's Tekton pipeline clones the DCM repo and walks `dav/use-cases/**` +loading every YAML it finds. A typical PipelineRun parameterizes: + +``` +--param consumer-spec-repo-url=https://github.com/croadfeldt/dcm.git +--param consumer-corpus-repo-url=https://github.com/croadfeldt/dcm.git +--param corpus-uc-subpath=dav/use-cases +``` + +(spec and corpus point at the same repo; the corpus subpath is the +new location.) + +For full DAV usage see the DAV README. + +## Contribution workflow + +Use cases enter the corpus via: + +1. **Direct hand authoring.** Open a PR adding a new YAML under the + appropriate domain. CI (eventually) runs DAV's stage 2 against the + new case and the architect spot-checks the result. +2. **Promotion from a DAV exploration run.** An architect reviews a + generated case in DAV's Review Console and clicks "promote to + corpus," which opens a PR against this directory with the YAML + pre-filled. + +## Review criteria for corpus admission + +A use case gets merged when: + +- ✅ Schema-valid against `schemas/use_case.schema.json` +- ✅ Dimensions are internally consistent (not contradictory) +- ✅ Scenario is concrete enough that DAV's analysis can engage with it +- ✅ Success criteria are testable (or at least observable in the spec) +- ✅ Tags are useful for filtering (domain, complexity, edge flags) +- ✅ Not a near-duplicate of an existing case +- ✅ Initial DAV run produces a verdict an architect agrees with + +## Retirement + +A use case can be retired only via a PR with explicit rationale: + +- The architecture has genuinely moved past supporting it (NOT "we + broke it and didn't fix the spec to match") +- It was superseded by a more precise or comprehensive case +- It was admitted in error (e.g., duplicates an existing case) + +Retirement moves the YAML to `retired//` rather than deleting it, +preserving the historical record. + +## Controlled vocabularies + +Dimension values are constrained. Valid values as of schema v1.0: + +- **profile**: `minimal | dev | standard | prod | fsi | sovereign` +- **lifecycle_phase**: `new_request | modification | decommission | + drift_detection | brownfield_ingestion | rehydration_faithful | + rehydration_provider_portable | rehydration_historical_exact | + rehydration_historical_portable | expiry_enforcement` +- **resource_complexity**: `single_no_deps | hard_dependencies | + composite_service | conditional_soft_deps | process_resource | + cross_dependency_payload` +- **policy_complexity**: `system_defaults_only | single_gating | + multi_policy_chain | conflicting_policies | orchestration_flow_static | + dynamic_conditional_flow | cross_domain_constraint | + human_escalation_required | governance_matrix_enforcement | + recovery_policy` +- **provider_landscape**: `single_eligible | multiple_eligible | + none_eligible | peer_dcm_required | process_provider | mixed` +- **governance_context**: `no_governance | standard_governance | + audit_heavy | compliance_gated | sovereignty_enforced` +- **failure_mode**: `happy_path | provider_failure | policy_violation | + peer_dcm_disconnect | data_inconsistency | rollback_required | + partial_fulfillment | timeout | resource_exhaustion` + +Note: `policy_complexity: cross_domain_constraint` is a vocabulary term +and intentionally retains the underscore form. Directory names use +hyphens (`cross-domain/`); the dimension value does not. + +These vocabularies evolve alongside DCM itself. Additions require a +schema bump and updates to DAV's `core/consumer_profile.py`. + +## License + +Apache 2.0 (matches the DCM project). + +## History + +This corpus previously lived at `croadfeldt/dcm-self-test-corpus`. It +moved to its current location in the DCM repo following ADR-001, which +made DAV a standalone consumer-agnostic framework with DCM as its first +consumer. The old corpus repo is archived; PR history through that +move is preserved there. diff --git a/dav/schemas/use_case.schema.json b/dav/schemas/use_case.schema.json new file mode 100644 index 0000000..6fad545 --- /dev/null +++ b/dav/schemas/use_case.schema.json @@ -0,0 +1,211 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "DCM Use Case", + "description": "A DCM validation use case: an architecture scenario DAV evaluates against the DCM/UDLM spec. The scenario describes intent, actor, and expected behavior; dimensions classify it along the controlled vocabularies so coverage can be measured; generated_by + metadata carry provenance.", + "type": "object", + "required": [ + "uuid", + "handle", + "version", + "scenario", + "generated_by" + ], + "properties": { + "uuid": { + "type": "string", + "pattern": "^uc-", + "description": "Stable unique id, server-owned. Form: 'uc-' for generated UCs, or a 'uc-' for intentional seed handles. Never reused." + }, + "handle": { + "type": "string", + "pattern": ".*/.*", + "description": "Human-readable '/' path (e.g. 'compute/vm-standard-provision'). The leading segment groups the UC by domain; must match the file's location." + }, + "version": { + "type": "string", + "description": "Semantic version of this UC's content (e.g. '1.0.0'). Bumped when the scenario materially changes." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Free-form labels for search/grouping (domain, profile, failure-mode, foundational, etc.). Not validated against a vocabulary." + }, + "scenario": { + "type": "object", + "description": "The use case itself — what is being validated.", + "required": [ + "description", + "actor", + "intent", + "success_criteria", + "dimensions", + "profile" + ], + "properties": { + "description": { + "type": "string", + "description": "Prose statement of the scenario: the situation, what the platform must do, and why. The primary text the evaluator reasons over." + }, + "actor": { + "type": "object", + "description": "Who initiates the scenario.", + "required": [ + "persona", + "profile" + ], + "properties": { + "persona": { + "type": "string", + "description": "The role driving the request (e.g. 'application-team-member', 'platform-operator', 'compliance-auditor')." + }, + "profile": { + "description": "The actor's operating profile (capability-set preset). See scenario.profile.", + "enum": [ + "minimal", + "dev", + "standard", + "prod", + "fsi", + "sovereign" + ] + } + } + }, + "intent": { + "type": "string", + "description": "The outcome the actor wants, stated as intent (the 'what', not the 'how'). DCM is intent-based; this is the consumer's declared goal." + }, + "success_criteria": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "description": "Observable, checkable conditions that must all hold for the scenario to pass. Each is a discrete assertion the evaluation tests against the spec." + }, + "dimensions": { + "type": "object", + "description": "Classifies the UC along DCM's controlled vocabularies so corpus coverage is measurable. Values are drawn from the consumer-profile vocabulary — SOURCE OF TRUTH: examples/dcm-reference-profile.yaml (mirrored into engine consumer_profile). Kept as described strings here (not hard enums) deliberately, so the schema does not become a second, drift-prone copy of that vocabulary; the engine enum-constrains at eval time.", + "required": [ + "lifecycle_phase", + "resource_complexity", + "policy_complexity", + "provider_landscape", + "governance_context", + "failure_mode" + ], + "properties": { + "lifecycle_phase": { + "type": "string", + "description": "Where in the resource lifecycle the scenario sits. Vocabulary (dcm-reference-profile.yaml): new_request, modification, decommission, drift_detection, brownfield_ingestion, rehydration_{faithful,provider_portable,historical_exact,historical_portable}, expiry_enforcement." + }, + "resource_complexity": { + "type": "string", + "description": "Shape/dependency complexity of the requested resource(s). Vocabulary: single_no_deps, hard_dependencies, compound_service, conditional_soft_deps, process_resource, cross_dependency_payload." + }, + "policy_complexity": { + "type": "string", + "description": "Policy-evaluation complexity exercised. Vocabulary: system_defaults_only, single_gating (formerly single_gatekeeper), multi_policy_chain, conflicting_policies, orchestration_flow_static, dynamic_conditional_flow, cross_domain_constraint, human_escalation_required, governance_matrix_enforcement, recovery_policy." + }, + "provider_landscape": { + "type": "string", + "description": "The provider-eligibility situation for placement. Vocabulary: single_eligible, multiple_eligible, none_eligible, peer_dcm_required, meta_provider_composed, process_provider, mixed." + }, + "governance_context": { + "type": "string", + "description": "The governance/compliance posture in force. Vocabulary: no_governance, standard_governance, audit_heavy, compliance_gated, sovereignty_enforced." + }, + "failure_mode": { + "type": "string", + "description": "The failure (or happy_path) the scenario exercises. Vocabulary: happy_path, provider_failure, policy_violation, peer_dcm_disconnect, data_inconsistency, rollback_required, partial_fulfillment, timeout, resource_exhaustion." + } + } + }, + "profile": { + "description": "The deployment/operating profile (a platform capability-set preset) the scenario runs under. Profiles are capability sets, not a strict hierarchy; named values are presets. minimal=least overhead (not least security), sovereign=in-boundary/air-gap-capable.", + "enum": [ + "minimal", + "dev", + "standard", + "prod", + "fsi", + "sovereign" + ] + }, + "expected_domain_interactions": { + "type": "array", + "description": "The cross-domain interactions the scenario should drive, one entry per (domain, interaction). Used to check the UC touches the right Data/Policy/Provider/Audit surfaces.", + "items": { + "type": "object", + "required": [ + "domain", + "interaction" + ], + "properties": { + "domain": { + "type": "string", + "description": "The DCM domain touched: typically data, policy, provider, or audit." + }, + "interaction": { + "type": "string", + "description": "What happens in that domain during the scenario." + } + } + } + } + } + }, + "generated_by": { + "type": "object", + "description": "Provenance of how this UC was authored/generated.", + "required": [ + "mode", + "source" + ], + "properties": { + "mode": { + "description": "Why the UC was produced: 'authoring' (deliberately written), 'regression' (captured from a run), 'pr-targeted' (written to exercise a specific PR/change).", + "enum": [ + "regression", + "pr-targeted", + "authoring" + ] + }, + "source": { + "description": "Origin of the content: human-authored, AI-assisted (human+model), drawn from the corpus, or LLM-produced (guided/unguided).", + "enum": [ + "corpus", + "llm-unguided", + "llm-guided", + "ai-assisted", + "human-authored" + ] + }, + "model": { + "type": [ + "string", + "null" + ], + "description": "The model that produced the UC, if LLM-sourced; null for human-authored." + }, + "prompt_version": { + "type": [ + "string", + "null" + ], + "description": "Version of the authoring prompt used, if LLM-sourced; null otherwise." + }, + "timestamp": { + "type": "string", + "description": "ISO-8601 time the UC was generated/authored." + } + } + }, + "metadata": { + "type": "object", + "description": "Admission/lifecycle bookkeeping (when admitted, under which DCM version, author, baseline lineage). Not part of the scenario semantics." + } + } +} diff --git a/dav/use-cases/compute/vm-provision-with-provider-failure.yaml b/dav/use-cases/compute/vm-provision-with-provider-failure.yaml new file mode 100644 index 0000000..edc4059 --- /dev/null +++ b/dav/use-cases/compute/vm-provision-with-provider-failure.yaml @@ -0,0 +1,67 @@ +uuid: uc-seed-006a +handle: compute/vm-provision-with-provider-failure +scenario: + description: An application team submits a VM provisioning request. The policy + checks pass and the service provider accepts the dispatch, but partway through + realization the provider becomes unreachable. The recovery policy must classify + the partial-realization state, decide whether to requeue against another eligible + provider, hold the request pending provider recovery, or fail the request and + release any partially-allocated resources. The tenant must not be left with + orphaned partially-provisioned state. + actor: + persona: application-team-member + profile: standard + intent: Provision a VM under conditions where the primary service provider fails + mid-realization + success_criteria: + - Provider unreachability is detected within the dispatch timeout, not indefinitely + pending + - Partially-allocated resources are either reconciled to a completed state or cleanly + released + - Recovery policy decision is explicit and audit-recorded (requeue / hold / fail) + - If another eligible provider exists and policy permits, the request is requeued + automatically + - The tenant's requested state never shows a resource in an indeterminate state + without a matching recovery record + dimensions: + lifecycle_phase: new_request + resource_complexity: single_no_deps + policy_complexity: recovery_policy + provider_landscape: multiple_eligible + governance_context: standard_governance + failure_mode: provider_failure + profile: standard + expected_domain_interactions: + - domain: provider + interaction: service provider accepts dispatch then becomes unreachable mid-realization + - domain: policy + interaction: recovery policy classifies partial-realization state and selects + action + - domain: provider + interaction: if policy selects requeue, alternate eligible provider is dispatched + - domain: data + interaction: partial-realization state tracked, reconciled or released per recovery + decision + - domain: audit + interaction: failure detection, recovery decision, and final outcome recorded + with provider identities +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-23T04:45:00.000000+00:00' +tags: +- compute +- vm +- failure-mode +- recovery-policy +- standard-profile +- provider-unreachable +version: 1.0.0 +metadata: + admitted_at: '2026-04-23T04:45:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt diff --git a/dav/use-cases/compute/vm-standard-provision.yaml b/dav/use-cases/compute/vm-standard-provision.yaml new file mode 100644 index 0000000..12176a5 --- /dev/null +++ b/dav/use-cases/compute/vm-standard-provision.yaml @@ -0,0 +1,56 @@ +uuid: uc-seed-001a +handle: compute/vm-standard-provision +scenario: + description: An application team requests a new virtual machine in the standard + profile. The platform must run the applicable policy checks before allocation, + allocate the VM through an eligible service provider, and produce an auditable + record of the provisioning. This use case is scoped to standard VM provisioning + only; the data-plane tenant-isolation concern is validated separately by + compute/vm-tenant-isolation-enforcement. + actor: + persona: application-team-member + profile: standard + intent: Provision a new VM in the standard profile + success_criteria: + - VM is created and reachable for the requesting team + - Applicable (resolved-profile) policies are evaluated before allocation + - Provisioning is recorded in the audit trail with actor, intent, and outcome + - "The request is idempotent — repeating it does not create duplicate VMs" + dimensions: + lifecycle_phase: new_request + resource_complexity: single_no_deps + policy_complexity: single_validation + provider_landscape: single_eligible + governance_context: standard_governance + failure_mode: happy_path + profile: standard + expected_domain_interactions: + - domain: policy + interaction: resolved-profile validation evaluates the request before allocation + - domain: provider + interaction: service provider allocates the VM resource + - domain: data + interaction: resource record created + - domain: audit + interaction: provisioning event recorded +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-20T18:41:39.738396+00:00' +tags: +- compute +- vm +- happy-path +- standard-profile +- single-provider +- foundational +version: 1.1.0 +metadata: + admitted_at: '2026-04-20T18:41:39.738428+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt + edited: '2026-06-29 — split out data-plane tenant isolation (Piotr PR-65 #2); see compute/vm-tenant-isolation-enforcement' diff --git a/dav/use-cases/cross-domain/ansible-inventory-brownfield-ingestion.yaml b/dav/use-cases/cross-domain/ansible-inventory-brownfield-ingestion.yaml new file mode 100644 index 0000000..db35bbd --- /dev/null +++ b/dav/use-cases/cross-domain/ansible-inventory-brownfield-ingestion.yaml @@ -0,0 +1,83 @@ +uuid: uc-seed-bfi-001 +handle: cross-domain/ansible-inventory-brownfield-ingestion +scenario: + description: An operations team manages an existing estate (bare metal, VMs, + hypervisors, appliances, network gear) through configuration-management + inventory (e.g. Ansible) - hosts, groups, per-host variables, and embedded + credentials. They migrate management to DCM by ingesting that inventory as + brownfield entities WITHOUT recreating or moving any running resource. + Inventory groups become DCMGroups; host definitions become resource + entities with their attributes; embedded plaintext credentials become + vault-backed credential resources; and telemetry collection is + auto-established for every ingested entity per the provider contract + observability obligation. The inventory remains authoritative during a + coexistence window - ingestion is additive and reversible until cutover. + actor: + persona: platform-operator + profile: standard + intent: Adopt an existing configuration-management inventory into DCM as + first-class entities, groups, and credentials - in place, with zero + resource recreation and no management gap during transition + success_criteria: + - Every inventory host is ingested as a resource entity with its attributes + (vars) preserved and its provenance recorded as brownfield + - Inventory groups (including nested groups) map to DCMGroups with + membership preserved, so group-scoped policy and observability apply + immediately (OBS-008) + - Resources are ADOPTED in place - no resource is recreated, restarted, or + migrated as a side effect of ingestion (adopt-not-recreate) + - Embedded plaintext credentials are detected, converted to vault-backed + credential resources, and flagged for rotation; no plaintext credential + survives ingestion into entity definitions + - Telemetry collection is established for every ingested entity per the + provider-contract observability obligation (PRV-007) without per-entity + manual configuration + - During coexistence, changes made via the legacy inventory are detected as + drift against the ingested entities rather than silently diverging + - Ingestion is reversible before cutover - removing DCM management leaves + the estate exactly as found + dimensions: + lifecycle_phase: brownfield_ingestion + resource_complexity: cross_dependency_payload + policy_complexity: multi_policy_chain + provider_landscape: mixed + governance_context: standard_governance + failure_mode: happy_path + profile: standard + expected_domain_interactions: + - domain: data + interaction: inventory hosts/groups/vars ingested as entities, DCMGroups, + and attributes with brownfield provenance + - domain: provider + interaction: configuration-management system acts as an information + provider for discovery; credential conversion via credential resources + - domain: policy + interaction: ingestion scope, credential-handling, and coexistence drift + rules policy-evaluated + - domain: audit + interaction: every adopted entity, group mapping, and credential + conversion recorded with before/after provenance +generated_by: + mode: authoring + source: llm-guided + model: claude-opus-4-8 + prompt_version: seed-1.0 + timestamp: '2026-06-07T21:30:00.000000+00:00' +tags: +- brownfield +- ingestion +- ansible +- inventory +- migration +- dcmgroup +- credentials +- adopt-in-place +- coexistence +- standard-profile +version: 1.0.0 +metadata: + admitted_at: '2026-06-07T21:30:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt diff --git a/dav/use-cases/cross-domain/sovereign-decommission-with-peer.yaml b/dav/use-cases/cross-domain/sovereign-decommission-with-peer.yaml new file mode 100644 index 0000000..6b62b82 --- /dev/null +++ b/dav/use-cases/cross-domain/sovereign-decommission-with-peer.yaml @@ -0,0 +1,71 @@ +uuid: uc-seed-002a +handle: cross-domain/sovereign-decommission-with-peer +scenario: + description: A resource has been replicated to a peer DCM instance for + disaster-recovery. Decommissioning it is a PEER-COORDINATED operation — a + two-phase release across both DCM instances with a single, consistent + cross-DCM audit trail. (This is distinct from rehydration — rehydrate replays + Intent into a new Requested state on another provider; this releases both + existing replicas.) The peer-coordination mechanic is profile-independent; the + SOVEREIGN profile is what MANDATES it here — sovereign data-residency requires + that a DR replica exists and that its release is residency-checked and + coordinated, not silently dropped. The peer must satisfy the provenance floor + (its attested capability set must cover what this transaction requires) for the + coordinated release to preserve end-to-end provenance. + actor: + persona: sovereign-tenant-admin + profile: sovereign + intent: Decommission a resource such that both the local and the peer replica are + released, with a consistent cross-DCM audit record + success_criteria: + - Local replica is released only after the peer acknowledges the decommission + - If the peer is unreachable, the decommission is held in a pending state, not + silently completed + - The peer's attested capability set is verified to meet the transaction's + provenance requirements before coordination proceeds + - Final audit record includes the peer acknowledgement evidence and is consistent + across both DCM instances + - Sovereign data-residency constraints are not violated during the wind-down + dimensions: + lifecycle_phase: decommission + resource_complexity: hard_dependencies + policy_complexity: cross_domain_constraint + provider_landscape: peer_dcm_required + governance_context: sovereignty_enforced + failure_mode: peer_dcm_disconnect + profile: sovereign + expected_domain_interactions: + - domain: policy + interaction: sovereignty policy mandates the peer replica + residency check at + decommission; verifies peer meets the provenance floor before coordinating + - domain: provider + interaction: peer_dcm provider coordinates the two-phase release with the remote DCM + - domain: provider + interaction: service provider releases the local resource only after peer-ack + - domain: data + interaction: resource record marked released with peer-ack metadata + - domain: audit + interaction: cross-DCM audit record stitched together consistently +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-20T18:41:39.741639+00:00' +tags: +- cross-domain +- decommission +- sovereign +- peer-dcm +- peer-coordinated +- provenance-floor +- edge-case +- failure-mode +version: 1.1.0 +metadata: + admitted_at: '2026-04-20T18:41:39.741660+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt + edited: '2026-06-29 — reframe peer-coordinated (not rehydrate), sovereign-as-mandate, peer provenance floor (Piotr PR-65 #4)' diff --git a/dav/use-cases/cross-domain/tenant-onboarding.yaml b/dav/use-cases/cross-domain/tenant-onboarding.yaml new file mode 100644 index 0000000..f9bd530 --- /dev/null +++ b/dav/use-cases/cross-domain/tenant-onboarding.yaml @@ -0,0 +1,77 @@ +uuid: uc-seed-008a +handle: cross-domain/tenant-onboarding +scenario: + description: A platform engineer onboards a new tenant into a DCM deployment whose + instance profile is fsi. Onboarding is a single atomic operation that provisions + the tenant identity boundary, binds the tenant to the instance's resolved profile + (the platform default — near-term the instance applies one profile deployment-wide), + composes the appropriate compliance/sovereignty overlay (Sovereignty Zone + + Accreditation — a SEPARATE axis from the profile) for the tenant's declared + regulatory scope, establishes storage and compute quota allocations, and configures + the tenant's auth-provider claims mapping (identity is delegated to the IdP; DCM + holds the claims-mapping reference, not a membership store). There is no separate + bespoke tenant-to-profile mapping table — the binding is the profile (a capability + set) bound via a policy_profile DCMGroup; profile selection per tenant is a future + capability. Either all onboarding steps complete or none persist. + actor: + persona: platform-engineer + profile: fsi + intent: Onboard a new tenant as an atomic operation, bound to the instance profile + with its compliance overlay and quotas, before it can request any resources + success_criteria: + - Tenant identity boundary is created and bound to the instance's resolved profile + (the platform default) via a policy_profile DCMGroup — no separate mapping artifact + - The compliance/sovereignty overlay (Sovereignty Zone + Accreditation) for the + tenant's declared regulatory scope is composed with the profile, not folded into it + - Storage and compute quotas are allocated with the requested ceilings + - Auth-provider claims mapping is configured (delegated identity; DCM stores the + reference, not cached membership) + - Partial onboarding is not observable downstream; either the tenant is fully + governed or the partial state is rolled back + - The instance profile's policies are active on the tenant before its first request + dimensions: + lifecycle_phase: new_request + resource_complexity: composite_service + policy_complexity: cross_domain_constraint + provider_landscape: mixed + governance_context: compliance_gated + failure_mode: happy_path + profile: fsi + expected_domain_interactions: + - domain: data + interaction: tenant identity boundary (tenant_boundary DCMGroup) created, bound + to the instance profile (policy_profile DCMGroup) + - domain: policy + interaction: instance-profile policies + composed compliance/sovereignty overlay + bound to the tenant + - domain: data + interaction: storage and compute quota allocations recorded against the tenant + - domain: provider + interaction: auth provider configured with the tenant claims-mapping reference + (delegated identity) + - domain: policy + interaction: onboarding atomicity enforced by an orchestration flow policy + - domain: audit + interaction: single onboarding record stitches all sub-operations together +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-23T04:45:00.000000+00:00' +tags: +- cross-domain +- tenant +- onboarding +- fsi-profile +- atomic-composition +- approved-list-profile +- compliance-overlay-separate-axis +version: 1.1.0 +metadata: + admitted_at: '2026-04-23T04:45:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt + edited: '2026-06-29 — instance-profile binding (approved-list model), drop bespoke mapping, compliance as separate axis (Piotr PR-65 #5 / DR-B)' diff --git a/dav/use-cases/data/persistent-volume-provision.yaml b/dav/use-cases/data/persistent-volume-provision.yaml new file mode 100644 index 0000000..61e03a3 --- /dev/null +++ b/dav/use-cases/data/persistent-volume-provision.yaml @@ -0,0 +1,58 @@ +uuid: uc-seed-004a +handle: data/persistent-volume-provision +scenario: + description: A development team requests a new persistent block volume attached + to an existing VM in their tenant. The storage provider must allocate the volume + from the tenant's eligible storage class, enforce tenancy at the storage plane, + respect any data-residency constraints, and produce an auditable record including + capacity consumed against tenant quota. + actor: + persona: application-team-member + profile: dev + intent: Provision a persistent block volume and attach it to an existing VM in + the tenant + success_criteria: + - Volume is created in a storage class the tenant is authorized to consume + - Volume is attached to the target VM without cross-tenant exposure + - Tenant quota is updated to reflect the new consumption + - Provisioning and attachment are recorded in the audit trail + dimensions: + lifecycle_phase: new_request + resource_complexity: cross_dependency_payload + policy_complexity: single_validation + provider_landscape: single_eligible + governance_context: standard_governance + failure_mode: happy_path + profile: dev + expected_domain_interactions: + - domain: policy + interaction: tenant-isolation gating evaluates volume request against tenant's + storage class eligibility + - domain: provider + interaction: storage provider allocates block volume in eligible class + - domain: provider + interaction: service provider attaches volume to target VM + - domain: data + interaction: volume record created with tenancy and VM reference, quota incremented + - domain: audit + interaction: provisioning and attachment recorded with actor, intent, outcome +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-23T04:45:00.000000+00:00' +tags: +- data +- storage +- volume +- happy-path +- dev-profile +- cross-resource-dependency +version: 1.0.0 +metadata: + admitted_at: '2026-04-23T04:45:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt diff --git a/dav/use-cases/governance/audit-merkle-tree-verification.yaml b/dav/use-cases/governance/audit-merkle-tree-verification.yaml new file mode 100644 index 0000000..6dc3c8d --- /dev/null +++ b/dav/use-cases/governance/audit-merkle-tree-verification.yaml @@ -0,0 +1,63 @@ +uuid: uc-seed-007a +handle: governance/audit-merkle-tree-verification +scenario: + description: A compliance auditor requests cryptographic verification that a specific + set of historical audit events has not been tampered with since the events were + recorded. DCM must produce signed tree heads and merkle inclusion proofs for the + requested events, and the auditor's independent verification against the tree + heads must succeed. Under a sovereign profile, the signing key material must + remain within sovereignty boundaries. The verification is a query over existing + audit state — it modifies no tenant resources, only reads and produces proofs. + actor: + persona: compliance-auditor + profile: sovereign + intent: Cryptographically verify that a named range of audit events has not been + tampered with + success_criteria: + - Signed tree heads are retrievable for every audit epoch covering the requested + event range + - Inclusion proofs are produced for each requested event and verify against the + tree heads + - Consistency proofs demonstrate the tree heads form a coherent append-only sequence + - Signing key material used for tree heads never leaves the sovereignty boundary + - Verification failure on any event is surfaced with the specific event and proof + step that failed + dimensions: + lifecycle_phase: modification + resource_complexity: single_no_deps + policy_complexity: cross_domain_constraint + provider_landscape: single_eligible + governance_context: audit_heavy + failure_mode: happy_path + profile: sovereign + expected_domain_interactions: + - domain: audit + interaction: merkle tree heads retrieved for requested audit epochs + - domain: audit + interaction: inclusion proofs generated for each event in range + - domain: audit + interaction: consistency proofs generated between epoch tree heads + - domain: policy + interaction: sovereignty policy verifies signing key material residency + - domain: data + interaction: audit event records looked up by handle and epoch +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-23T04:45:00.000000+00:00' +tags: +- governance +- audit +- merkle +- cryptographic-verification +- sovereign-profile +- compliance +version: 1.0.0 +metadata: + admitted_at: '2026-04-23T04:45:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt diff --git a/dav/use-cases/governance/minimal-profile-policy-scope-boundary.yaml b/dav/use-cases/governance/minimal-profile-policy-scope-boundary.yaml new file mode 100644 index 0000000..dd866e3 --- /dev/null +++ b/dav/use-cases/governance/minimal-profile-policy-scope-boundary.yaml @@ -0,0 +1,83 @@ +uuid: uc-seed-009a +handle: governance/minimal-profile-policy-scope-boundary +scenario: + description: A developer in a minimal-profile sandbox provisions a VM with an + attached persistent volume and a cross-region network attachment. Under the + minimal profile, the FSI-scoped policies (data-residency, dual-approval for the + privileged cross-boundary operation, mandatory encryption-at-rest) are NOT part + of the request's RESOLVED PROFILE, so they must not evaluate; the request proceeds + under only the policies the minimal profile carries (effectively system defaults). + The architectural property this validates is DCM's policy-applicability model — + which policies fire is determined BY CONSTRUCTION from the request's resolved + profile (the profile selected from the platform's approved list, or the platform + default), and a policy not in that set is OUT OF SCOPE — neither evaluated nor + recorded as skipped-and-passed. The same request shape resolved under an + fsi profile WOULD fail (data-residency + dual-approval), which is what makes the + boundary real. (Per the approved-list model there is no floor/ceiling — the + platform governs applicability via its approved list + default, not a strictness + rank.) + actor: + persona: individual-developer + profile: minimal + intent: Provision a VM with attached volume and cross-region network attachment + under a minimal resolved profile, with FSI-scoped policies correctly out of scope + success_criteria: + - Request succeeds because no policy in the minimal resolved profile rejects it + - FSI-scoped policies (data-residency, dual-approval, encryption-at-rest-mandatory) + are NOT in the resolved profile and do not evaluate + - The audit record uses three distinct outcomes — evaluated-pass, evaluated-fail, + out-of-scope — and lists FSI-scoped policies as OUT OF SCOPE, not skipped-and-passed + - No silent fallback evaluates FSI policies with soft enforcement and records a pass + - The same request shape resolved under an fsi profile would fail on at least + data-residency and dual-approval (the boundary is real, not run-specific) + dimensions: + lifecycle_phase: new_request + resource_complexity: cross_dependency_payload + policy_complexity: system_defaults_only + provider_landscape: mixed + governance_context: no_governance + failure_mode: happy_path + profile: minimal + expected_domain_interactions: + - domain: policy + interaction: the engine resolves the request's profile and selects that profile's + policies by construction — FSI-scoped policies are out of scope, not evaluated + - domain: policy + interaction: policies in the minimal resolved profile evaluate (system defaults + for this profile) + - domain: provider + interaction: service provider allocates the VM in the minimal sandbox + - domain: provider + interaction: storage provider allocates the volume without forced encryption-at-rest + (FSI-scoped, out of scope for minimal) + - domain: provider + interaction: network provider establishes the cross-region attachment without + residency rejection (FSI-scoped, out of scope for minimal) + - domain: data + interaction: request record stores the resolved profile + its policy set for audit + - domain: audit + interaction: audit record lists policies-evaluated with three-state outcomes; does + not record out-of-scope FSI policies as skipped-and-passed +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-23T04:45:00.000000+00:00' +tags: +- governance +- policy +- resolved-profile +- minimal-profile +- negative-policy-claim +- out-of-scope-not-skipped-pass +- three-state-audit +- system-defaults-only +version: 1.1.0 +metadata: + admitted_at: '2026-04-23T04:45:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt + edited: '2026-06-29 — resolved-profile membership + three-state audit honesty; approved-list (no floor/ceiling) (Piotr PR-65 #7 / DR-E)' diff --git a/dav/use-cases/governance/policy-override-approval.yaml b/dav/use-cases/governance/policy-override-approval.yaml new file mode 100644 index 0000000..15b0c58 --- /dev/null +++ b/dav/use-cases/governance/policy-override-approval.yaml @@ -0,0 +1,62 @@ +uuid: uc-seed-005a +handle: governance/policy-override-approval +scenario: + description: A platform engineer requests a time-bounded override of a soft-enforcement + governance policy that is currently blocking a business-critical deployment. The + override request must be evaluated against the policy's override eligibility rules, + routed for approval by the authorized approver role, and the resulting override + (if granted) must be recorded with scope, duration, and rationale. Hard-enforcement + policies must remain unoverridable. This exercises the override_requests workflow + as a modification to the policy-application state for the matched request scope. + actor: + persona: platform-engineer + profile: prod + intent: Obtain time-bounded override of a soft policy to unblock a business-critical + deployment + success_criteria: + - Override eligibility is evaluated against the policy's own override rules, not + globally permitted + - Approval is routed to the role authorized for this override class, not the requester + - Granted overrides are scoped in time and narrowed to the specific matched request + - Hard-enforcement policies are rejected as unoverridable without approval attempt + - Override grant and subsequent policy-suppressed events are audit-linked + dimensions: + lifecycle_phase: modification + resource_complexity: single_no_deps + policy_complexity: human_escalation_required + provider_landscape: single_eligible + governance_context: standard_governance + failure_mode: happy_path + profile: prod + expected_domain_interactions: + - domain: policy + interaction: override request evaluated against policy's override eligibility + declaration + - domain: policy + interaction: approval routed to authorized approver role + - domain: data + interaction: override record created with scope, duration, approver, rationale + - domain: policy + interaction: subsequent policy evaluations honor active override for matched scope + - domain: audit + interaction: override grant and every suppressed policy event are linked for review +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-23T04:45:00.000000+00:00' +tags: +- governance +- policy +- override +- human-in-loop +- prod-profile +- approval-workflow +version: 1.0.0 +metadata: + admitted_at: '2026-04-23T04:45:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt diff --git a/dav/use-cases/identity/auth-provider-drift-detection.yaml b/dav/use-cases/identity/auth-provider-drift-detection.yaml new file mode 100644 index 0000000..625c92a --- /dev/null +++ b/dav/use-cases/identity/auth-provider-drift-detection.yaml @@ -0,0 +1,66 @@ +uuid: uc-seed-003a +handle: identity/auth-provider-drift-detection +scenario: + description: DCM delegates identity to the IdP and does NOT keep an authoritative + membership cache (see identity/connected-delegation). Under a sovereign / + disconnected deployment, DCM is permitted to hold a point-in-time IDENTITY + PROJECTION (provenance=observed) so it can keep operating while the IdP is + unreachable. This use case detects that such a projection (or a previously + materialized authorization decision) has DIVERGED from the IdP once connectivity + or a reconciliation cycle allows comparison — classifies the divergence under the + tenant's governance policy, and either remediates or escalates for human review. + This is explicitly the disconnected/sovereign + audit case; in a connected + deployment DCM delegates live and there is no cache to drift. + actor: + persona: sovereign-tenant-admin + profile: sovereign + intent: Detect and respond to divergence between DCM's disconnected identity + projection and the authoritative IdP, under sovereign/disconnected operation + success_criteria: + - Divergence is detected within one reconciliation cycle of connectivity/comparison + - The identity projection is provenance-marked observed and is never treated as the + system of record for membership + - Discrepancies are classified by severity per governance policy (silent fixup vs + escalation) + - Automated remediation only runs for governance-approved divergence categories + - Escalation produces a reviewable, audited record including before/after state + dimensions: + lifecycle_phase: drift_detection + resource_complexity: cross_dependency_payload + policy_complexity: human_escalation_required + provider_landscape: single_eligible + governance_context: sovereignty_enforced + failure_mode: data_inconsistency + profile: sovereign + expected_domain_interactions: + - domain: provider + interaction: auth provider re-resolves canonical state from the IdP (authoritative) + - domain: data + interaction: compare the observed point-in-time projection vs canonical IdP state + - domain: policy + interaction: classify divergence severity and remediation path; gate on whether a + projection is permitted (disconnected/sovereign) + - domain: audit + interaction: record divergence detection, classification, and action +generated_by: + mode: authoring + source: human-authored + model: null + prompt_version: seed-1.0 + timestamp: '2026-04-20T18:41:39.744440+00:00' +tags: +- identity +- auth +- drift-detection +- delegated-identity +- disconnected-projection +- sovereign-profile +- human-in-loop +version: 1.1.0 +metadata: + admitted_at: '2026-04-20T18:41:39.744455+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt + edited: '2026-06-29 — re-scope to disconnected/sovereign projection drift; DCM delegates, holds references not membership (Piotr PR-65 #8 / DR-C)' diff --git a/dav/use-cases/observability/udlm-universal-telemetry-export.yaml b/dav/use-cases/observability/udlm-universal-telemetry-export.yaml new file mode 100644 index 0000000..429a597 --- /dev/null +++ b/dav/use-cases/observability/udlm-universal-telemetry-export.yaml @@ -0,0 +1,79 @@ +uuid: uc-seed-obs-001 +handle: observability/udlm-universal-telemetry-export +scenario: + description: A platform operations team connects its existing observability tooling + (metrics TSDB, log aggregator, alerting pipeline, SIEM) to DCM. Rather than DCM + writing N per-tool adapters, DCM exposes ONE UDLM-modeled, schema-discoverable + export surface over STANDARD TRANSPORTS — OTLP, Prometheus scrape, and a message-bus + subscription against the published event catalog. "No bespoke adapters" means no + DCM-side per-tool integration code — any tool that speaks a standard transport + consumes the same uniform entity/event vocabulary directly. Where a consumer speaks + a proprietary protocol, a thin standard exporter sits at the CONSUMER edge (one per + protocol, outside DCM), not inside DCM. The export is policy-scoped (a subscriber + sees only what its authorization and data-classification policies allow), + retention-governed, and itself auditable. + actor: + persona: platform-operator + profile: standard + intent: Establish a universal telemetry export so monitoring, alerting, logging, and + audit tooling consume DCM data through one UDLM-modeled interface over standard + transports, with no DCM-side per-tool adapters + success_criteria: + - Telemetry entities (metrics, events, log records, audit records) are exposed as + UDLM-modeled data with schemas discoverable by the consumer at subscription time + - A curated event-stream subscription delivers lifecycle, drift, policy, and audit + events via the message bus using the published event-catalog vocabulary + - Resource metrics are exported over a standard transport (OTLP / Prometheus scrape) + consumable with no DCM-specific adapter + - Export scope is policy-evaluated per subscriber (data classification + tenancy) + - Subscription creation, schema discovery, and export access are recorded in the + audit trail + - A second, different consuming tool attaches via the same discovery/subscription + path with no export-side change (proof the surface is uniform, not per-tool) + dimensions: + lifecycle_phase: new_request + resource_complexity: composite_service + policy_complexity: multi_policy_chain + provider_landscape: multiple_eligible + governance_context: audit_heavy + failure_mode: happy_path + profile: standard + expected_domain_interactions: + - domain: data + interaction: telemetry entities + event catalog exposed as UDLM-modeled, + schema-discoverable data + - domain: provider + interaction: information provider serves export/discovery over standard transports; + message bus delivers the curated event stream + - domain: policy + interaction: subscriber authorization, data-classification scoping, and retention + policy evaluated for the export + - domain: audit + interaction: subscription lifecycle and export access recorded in the tamper-evident + audit chain +generated_by: + mode: authoring + source: llm-guided + model: claude-opus-4-8 + prompt_version: seed-1.0 + timestamp: '2026-06-07T18:30:00.000000+00:00' +tags: +- observability +- udlm +- telemetry-export +- standard-transports +- otlp +- prometheus +- message-bus +- universal-consumption +- happy-path +- standard-profile +- foundational +version: 1.1.0 +metadata: + admitted_at: '2026-06-07T18:30:00.000000+00:00' + admitted_dcm_version: preview + promoted_from_run: null + initial_baseline_path: null + author: chris@croadfeldt + edited: '2026-06-29 — honest adapter model: one UDLM surface over standard transports, edge translators outside DCM (Piotr PR-65 #9)'