# Source Registry Admin Dry-Run Registry Snapshot Model V01

Issue: [#337](https://github.com/pinklon/ai-capability-discipline/issues/337)

Date: 2026-06-28

Repository: `pinklon/ai-capability-discipline`

Baseline commit: `352784a77e05d11f9b2479e5050673a8b26d3fa9`

Status: dry-run registry snapshot and last-known-good posture only. This ticket adds dry-run registry snapshot and last-known-good posture only. This ticket does not implement live snapshot creation, does not implement live Source Registry Admin commands, does not mutate source registries, does not mutate Preview or Production source sets, does not enable sources, does not disable sources, does not retire sources, does not promote sources, does not use Cloudflare CLI or API, does not call external URLs, does not change provider or model configuration, does not change runtime retrieval behavior, does not change package authority, does not start Production apply, does not start OKF implementation, does not start Google SDLC implementation, does not start multi-agent orchestration implementation, does not create Source Registry Admin live implementation child issues, does not create extraction-profile implementation tickets, does not close #271, does not reopen #269, does not close #269, and does not apply `codex-automerge`.

## Purpose

Define the dry-run registry snapshot and last-known-good model needed before future Source Registry Admin environment mutation can exist.

This slice makes snapshot posture testable in repo-local fixtures, parser receipt previews, and validation receipts. It is evidence posture only.

## Relationship To Command Contract

#329 / PR #330 defines Source Registry Admin command contract v01.

The command contract defines the administrative command surface, refusal behavior, receipt expectations, lifecycle transitions, environment behavior, authority-lane behavior, and guardrails. This snapshot model adds the registry-state evidence that future environment-changing commands must cite before any live path can be considered.

## Relationship To Schema/Lifecycle Validation

#331 / PR #332 defines Source Registry Admin schema and lifecycle validation.

The snapshot model reuses the existing source-record schema and lifecycle validation posture. Snapshot `source_records` must conform to the governed source record model, including lifecycle state, approval, validation, citation, authority-lane, retrieval profile, extraction profile, and audit-history constraints.

## Relationship To Dry-Run Parser

#333 / PR #334 defines Source Registry Admin dry-run command parser v01.

The parser remains a dry-run parser. This slice adds snapshot posture to future-mutating receipt previews for `enable_preview`, `disable_preview`, `promote_to_production`, `disable_production`, `emergency_disable`, `rollback_registry`, and `retire_source`.

## Relationship To Dry-Run Receipt Schema

#335 / PR #336 defines Source Registry Admin dry-run receipt schema enforcement.

The dry-run receipt schema already requires `dry_run: true`, `mutations_performed: false`, mutating command posture, last-known-good requirement flags, rollback requirement flags, and boundary confirmations. This slice extends that receipt-preview surface with concrete registry snapshot and last-known-good posture fields.

## Non-Goals

This dry-run registry snapshot model slice does not:

- implement live snapshot creation
- implement live Source Registry Admin commands
- mutate source registries
- mutate Preview or Production source sets
- enable, disable, retire, or promote any source
- use Cloudflare CLI or API
- call external URLs
- change provider or model configuration
- change runtime retrieval behavior
- change package authority
- start Production apply
- start OKF implementation
- start Google SDLC implementation
- start multi-agent orchestration implementation
- create Source Registry Admin live implementation child issues
- create extraction-profile implementation tickets
- close #271
- reopen #269
- close #269
- apply `codex-automerge`

This ticket does not implement live snapshot creation.

This ticket does not implement live Source Registry Admin commands.

This ticket does not mutate source registries.

This ticket does not mutate Preview or Production source sets.

## Registry Snapshot Model

Dry-run registry snapshots require these fields:

- `snapshot_id`
- `schema`
- `created_at`
- `created_by`
- `dry_run`
- `environment`
- `source_registry_version`
- `source_registry_hash`
- `active_source_ids`
- `source_records`
- `lifecycle_states`
- `active_environments`
- `authority_lanes`
- `validation_status`
- `receipt_ref`
- `last_known_good`
- `last_known_good_ref`
- `rollback_eligible`
- `rollback_reason`
- `boundary_confirmations`

The fixture schema marker is `source_registry_admin_dry_run_registry_snapshot_v01`.

`dry_run` must be `true`. `mutations_performed` must be `false` wherever a snapshot appears in dry-run command output or fixture posture.

`source_registry_hash` is required so rollback, emergency-disable, promotion, and receipt evidence can name the exact pre-change registry state.

`source_records` must conform to the Source Registry Admin source-record schema and lifecycle validation model.

## Last-Known-Good Model

Last-known-good references require these fields:

- `last_known_good_id`
- `schema`
- `environment`
- `snapshot_id`
- `source_registry_hash`
- `created_at`
- `validated_at`
- `validated_by`
- `validation_checks`
- `active_source_ids`
- `rollback_eligible`
- `rollback_exclusions`
- `receipt_ref`
- `boundary_confirmations`

The fixture schema marker is `source_registry_admin_last_known_good_registry_ref_v01`.

Last-known-good records without `validation_checks` are invalid because rollback evidence must name the validation basis.

## Rollback Eligibility

Rollback eligibility requires:

- a non-empty `snapshot_id`
- a non-empty `environment`
- a non-empty `source_registry_hash`
- `dry_run: true`
- `mutations_performed: false` where emitted in command output
- a non-empty `last_known_good_ref` when `rollback_eligible` is `true`
- source records that pass source-record schema and lifecycle validation
- active source IDs that exist in `source_records`
- boundary confirmations that prove no live mutation occurred

Production rollback eligibility also requires explicit validation evidence. A Production snapshot with `rollback_eligible: true` and no validation evidence is invalid.

## Emergency-Disable Posture

Emergency-disable receipt previews must carry snapshot posture before any future disable path can exist.

The dry-run posture must identify that:

- registry snapshot evidence is required
- last-known-good evidence is required
- rollback-reference posture is required
- no source was disabled by the dry run
- no Preview or Production source set was mutated
- no source registry was mutated

## Promotion Posture

Promotion receipt previews must carry snapshot posture before any future Production promotion path can exist.

The dry-run posture must identify that:

- registry snapshot evidence is required
- last-known-good evidence is required
- Production validation evidence is required
- package-authority promotion is not allowed through Source Registry Admin
- no source was promoted by the dry run
- no Production source set was mutated

## Receipt-Preview Integration

Dry-run receipt previews for these commands include snapshot posture:

- `enable_preview`
- `disable_preview`
- `promote_to_production`
- `disable_production`
- `emergency_disable`
- `rollback_registry`
- `retire_source`

The parser emits:

- `registry_snapshot_ref`
- `last_known_good_ref`
- `snapshot_posture`

`snapshot_posture` records whether registry snapshot evidence, last-known-good evidence, rollback-reference evidence, and Production validation evidence are required. It also repeats `dry_run_snapshot_only: true` and `mutations_performed: false`.

## Fixture Strategy

Fixtures live under `validation/fixtures/source_registry_admin/`.

- `dry_run_registry_snapshot_schema_v01.json` defines required snapshot and last-known-good fields.
- `dry_run_registry_snapshots_valid_v01.json` contains valid Preview and Production snapshot fixtures.
- `dry_run_registry_snapshots_invalid_v01.json` contains invalid snapshot cases for missing IDs, missing environment, missing registry hash, duplicate source IDs, active source IDs missing from source records, invalid lifecycle states, Production rollback without validation evidence, rollback target without last-known-good reference, missing boundary confirmations, non-dry-run posture, mutation implication, wildcard origins, package-authority promotion, audit-history deletion, and undocumented source use.
- `last_known_good_registry_refs_valid_v01.json` contains valid Preview and Production last-known-good references.
- `last_known_good_registry_refs_invalid_v01.json` contains invalid last-known-good references for missing validation checks and missing boundary confirmations.

## Validation Coverage

The focused validator is `validation/scripts/check_source_registry_admin_dry_run_registry_snapshot.py`.

It checks:

- snapshot schema fixture existence
- last-known-good fixture existence
- valid snapshot fixtures pass
- invalid snapshot fixtures fail for expected reasons
- valid last-known-good fixtures pass
- invalid last-known-good fixtures fail for expected reasons
- snapshot required fields
- last-known-good required fields
- source record schema and lifecycle conformance
- active source IDs exist in source records
- registry hash is present
- rollback target requires last-known-good reference
- Production rollback eligibility requires validation evidence
- boundary confirmations are present
- dry-run command receipt previews include snapshot posture where required
- `dry_run: true` and `mutations_performed: false` are preserved
- no fixture or parser output implies live registry mutation
- documentation, receipt, context-pack, and `run_all.py` wiring exist

## Boundary Confirmations

No source registries were mutated.

No source sets were mutated.

No source was enabled, disabled, retired, or promoted.

No Cloudflare CLI or API was used.

No external URLs were called.

No provider or model configuration was changed.

No runtime retrieval behavior was changed.

No package authority was changed.

#271 remains open.

#269 remains closed.

`codex-automerge` was not applied.

## Post-Closeout Next Action

After this dry-run registry snapshot / last-known-good model slice is merged and locally closed out, choose whether to add dry-run `add_source` plus `validate_source` workflow depth or continue extraction-profile work for the next source.