# Source Registry Admin Schema Lifecycle Validation V01

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

Date: 2026-06-27

Repository: `pinklon/ai-capability-discipline`

Baseline commit: `e0a3403c3747d57425c2e824203bea1e3c19d133`

Status: schema and lifecycle validation foundation only. This slice does not implement live Source Registry Admin commands, does not create a command parser, 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 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 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 first repo-local Source Registry Admin source-record schema and lifecycle-state validation foundation.

This artifact turns the Source Registry Admin product requirements and command contract into validation artifacts that can be checked before later implementation work exists. It records required source fields, lifecycle states, allowed transitions, forbidden transitions, environment eligibility constraints, authority-lane constraints, refusal behavior, fixture strategy, and audit-history expectations.

The validation foundation is intentionally non-mutating. It validates records and transition contexts in repo fixtures. It does not administer any live registry.

## Relationship To Source Registry Admin Product Requirements

#325 / PR #326 defines Source Registry Admin product requirements.

This schema/lifecycle validation slice uses `docs/product-architecture/source_registry_admin_product_requirements_v01.md` as the baseline for lifecycle states, source record fields, approval behavior, environment eligibility, citation behavior, source history, guardrails, and non-goals.

The product requirement says Source Registry Admin is the governed administrative path for adding, approving, registering, documenting, enabling, disabling, retiring, and promoting enrichment sources. This slice validates the source-record and transition model before any implementation can use those concepts.

This ticket does not mutate source registries.

## Relationship To Command Contract

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

This schema/lifecycle validation slice uses `docs/product-architecture/source_registry_admin_command_contract_v01.md` as the baseline for command-facing source-record inputs, lifecycle transition language, refusal behavior, receipt requirements, environment behavior, authority-lane behavior, and post-closeout sequencing.

This slice validates the contract surface. It does not implement the commands, does not create a command parser, and does not create Source Registry Admin implementation child issues.

## Relationship To #271 Extraction Profiles

This ticket does not start #271.

#271 remains the extraction-profile lane.

#271 extraction profiles define whether an approved source can produce substantive bounded cited content. Source Registry Admin may validate that a source record names retrieval and extraction profile identifiers, but it must not invent profile behavior or make a source substantively useful for detailed enrichment until the extraction-profile lane validates that behavior.

The validator requires retrieval and extraction profile identifiers for active enrichment states. That requirement is a readiness guard, not an implementation of extraction-profile behavior.

## Non-Goals

This schema/lifecycle validation slice does not:

- implement live Source Registry Admin commands
- create a command parser
- mutate source registries
- mutate Preview or Production source sets
- enable, disable, retire, or promote any source
- create Source Registry Admin implementation child issues
- create extraction-profile implementation tickets
- close #271
- reopen #269
- close #269
- use Cloudflare CLI or API
- change runtime retrieval behavior
- change provider or model configuration
- change package authority
- start Production apply
- start OKF implementation
- start Google SDLC implementation
- start multi-agent orchestration implementation
- approve arbitrary web search
- approve user-provided URL retrieval outside governed `add_source`
- approve browser-side source fetch
- approve browser-side provider calls
- approve browser-side current-source calls
- approve broad crawling
- approve wildcard origins
- approve undocumented source use
- approve deletion semantics that erase audit history
- apply `codex-automerge`

## Source Record Schema

The schema artifact is `validation/fixtures/source_registry_admin/source_record_schema_v01.json`.

Minimum source-record fields:

| Field | Requirement |
| --- | --- |
| `source_id` | Stable source identifier used in registries, receipts, citations, and audit history. Missing source IDs are invalid. Duplicate source IDs in a fixture or registry set are invalid. |
| `source_name` | Human-readable source name. |
| `source_version` or `publication_date` | Version or publication marker when applicable. A doc-only fixture may use a publication marker. |
| `source_type` | Source class, such as public standard, vendor documentation, government guidance, framework, or other approved class. |
| `authority_lane` | Authority lane. Missing authority lane is invalid. `package_authority` is refused for Source Registry Admin promotion. |
| `canonical_url` or `document_location` | Canonical source URL or document location. Non-HTTPS canonical URLs are invalid unless an explicit doc-only fixture justification is present. |
| `allowed_origin` | Exact allowed origin. Wildcard origins are invalid. |
| `allowed_path_prefix` | Exact allowed path prefix or document location boundary. Broad path prefixes such as `/` are invalid. |
| `retrieval_profile_id` | Retrieval profile identifier. Active enrichment states require a value. |
| `extraction_profile_id` | Extraction profile identifier. Active enrichment states require a value. |
| `environment_eligibility` | Preview and Production eligibility constraints and prerequisites. |
| `approval_status` | Approval status for the source record. Active sources require approval. |
| `approved_by` | Owner, steward, or approval role. Active sources require approval evidence. |
| `approved_at` | Approval timestamp. Active sources require approval evidence. |
| `approval_rationale` | Evidence-backed reason for approval and allowed use. Active sources require approval evidence. |
| `source_owner` or `steward` | Accountable source owner or steward. |
| `citation_label` | Human-readable citation label used in answers. Source use without a citation label is invalid. |
| `citation_url` | Citation URL or document reference. Source use without a citation URL is invalid. |
| `validation_status` | Validation result and state. Production-enabled sources require validation. |
| `active_environments` | Environments where the source is currently active. Retired sources must have no active environments. |
| `disable_reason` | Reason for disablement when applicable. Disabled sources require a reason unless a fixture marks the disablement as not applicable. |
| `retired_at` | Retirement timestamp when applicable. |
| `receipt_refs` | Receipt references for approval, validation, activation, disablement, rollback, retirement, and source-use documentation. |

The schema also records `lifecycle_state` because lifecycle validation requires an explicit current state for fixtures and registry records.

## Lifecycle States

The required lifecycle states are:

| State | Meaning | Activation boundary |
| --- | --- | --- |
| `proposed` | Source has been identified for possible governed addition. | Not approved and not active. |
| `approved` | Source passed owner or steward approval for a defined authority lane and use boundary. | Approved but not enabled. |
| `registered` | Source has required metadata, approval evidence, retrieval/extraction boundaries, citation fields, and receipt references in the governed source record. | Known and governed, but not automatically active. |
| `preview_enabled` | Source is active in Preview for bounded smoke and validation. | Preview only. |
| `production_eligible` | Source has passed required Preview evidence, metadata validation, retrieval/extraction validation, receipt checks, and environment eligibility review. | Eligible for Production, but not active in Production. |
| `production_enabled` | Source is active in Production under explicit environment eligibility, validation evidence, and receipt-backed promotion. | Production active. |
| `disabled` | Source is inactive in one or more environments while source history, approval evidence, and receipts remain preserved. | Disabled without deleting audit history. |
| `retired` | Source is no longer eligible for normal activation, but source records, history, and audit trail remain preserved. | Retired without deleting audit records. |

## Allowed Lifecycle Transitions

The transition artifact is `validation/fixtures/source_registry_admin/source_lifecycle_transitions_v01.json`.

Allowed transitions:

| Transition | Required context |
| --- | --- |
| `proposed` to `approved` | Approval evidence and receipt context. |
| `approved` to `registered` | Complete source metadata, boundaries, citation fields, and receipt context. |
| `registered` to `preview_enabled` | Preview eligibility, validation evidence, receipt context, and last-known-good registry reference for environment mutation. |
| `preview_enabled` to `production_eligible` | Preview evidence, retrieval/extraction profile readiness, validation evidence, and receipt context. |
| `production_eligible` to `production_enabled` | Production eligibility, validation evidence, receipt context, and last-known-good registry reference for environment mutation. |
| `preview_enabled` to `disabled` | Disable reason, receipt context, and last-known-good registry reference for environment mutation. |
| `production_enabled` to `disabled` | Disable reason, receipt context, and last-known-good registry reference for environment mutation. |
| `disabled` to `preview_enabled` | Validation evidence, receipt context, and last-known-good registry reference. |
| `disabled` to `production_enabled` | Production eligibility, validation evidence, receipt context, and last-known-good registry reference. |
| Any non-retired active state to `retired` | Retirement reason, receipt context, audit-history preservation, and no active environments after retirement. |

## Forbidden Lifecycle Transitions

Forbidden transitions:

| Transition | Refusal reason |
| --- | --- |
| `proposed` to `production_enabled` | Skips approval, registration, Preview evidence, production eligibility, validation, and receipt context. |
| `approved` to `production_enabled` | Skips registration, Preview evidence, production eligibility, validation, and receipt context. |
| `registered` to `production_enabled` | Skips Preview evidence, production eligibility, validation, and receipt context. |
| `retired` to any active state | Retired sources cannot return to normal activation without a new superseding source record that preserves history. |
| `disabled` to an active state without validation and receipt context | Re-enablement requires validation and receipt evidence. |
| Any state to deletion that erases audit history | Source Registry Admin is append-first and must preserve audit history. |
| Any environment-changing transition without last-known-good registry reference | Environment mutation requires a last-known-good registry reference. |

## Environment Eligibility Constraints

Environment eligibility is explicit and environment-scoped:

- Preview and Production eligibility are distinct fields.
- Preview enablement does not imply Production eligibility.
- Production enablement requires `production_eligible` state first.
- Production enablement requires `validation_status: validated`.
- Production enablement requires a receipt reference.
- Environment-changing transition contexts require `last_known_good_registry_ref`.
- Retired sources must have empty `active_environments`.
- Disabled sources must have no active environments in the disabled environment and must record `disable_reason` when disablement applies.

This artifact does not mutate Preview or Production.

## Authority-Lane Constraints

Authority-lane behavior must preserve package/current-public separation:

- Current/public enrichment authority is the default lane for externally approved enrichment sources.
- Source Registry Admin may record authority lane, validation posture, citation behavior, and environment eligibility.
- Source Registry Admin must not promote current/public source material into package authority.
- Source Registry Admin must not rewrite package content.
- Source Registry Admin must not treat source activation as package approval.
- `package_authority` and package-authority promotion through Source Registry Admin are refused unless a separate owner-approved package-authority path exists outside this slice.

## Validation/Refusal Behavior

The focused validator `validation/scripts/check_source_registry_admin_schema_lifecycle.py` rejects or flags:

- missing source ID
- duplicate source ID in a fixture or registry set
- wildcard origins
- non-HTTPS canonical URLs unless explicitly justified in a doc-only fixture
- broad path prefixes such as `/`
- missing authority lane
- package-authority promotion through Source Registry Admin
- missing retrieval or extraction profile for active enrichment use
- production-enabled source without production eligibility
- production-enabled source without validation
- active source without approval
- retired source with active environments
- disabled source without disable reason when applicable
- environment mutation without last-known-good registry reference in transition context
- deletion semantics that erase audit history
- source use without citation label or citation URL
- user-provided URL retrieval outside governed `add_source`
- arbitrary web search
- browser-side source fetch

The validator is repo-local and standard-library only.

## Fixture Strategy

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

- `source_record_schema_v01.json` records required fields, conditional requirements, guardrails, and schema-level constraints.
- `source_lifecycle_transitions_v01.json` records states, allowed transitions, forbidden transitions, and transition-context test cases.
- `source_records_valid_v01.json` contains records that must pass schema and lifecycle validation.
- `source_records_invalid_v01.json` contains records that must fail for expected reason codes.

The invalid fixture set is intentional. It proves that guardrails fail closed instead of relying on prose-only requirements.

## Receipt And Audit-History Expectations

Source Registry Admin validation must preserve an append-first audit posture:

- Source records must keep receipt references for approval, validation, activation, disablement, rollback, retirement, and source-use documentation where applicable.
- Lifecycle-changing transition contexts must record receipt references.
- Environment-changing transition contexts must record `last_known_good_registry_ref`.
- Deletion semantics that erase audit history are forbidden.
- Retired sources must preserve historical records and receipts.
- Disabled sources must preserve source history and record disable reasons when applicable.

## Boundary Confirmations

- #325 / PR #326 defines Source Registry Admin product requirements.
- #329 / PR #330 defines Source Registry Admin command contract v01.
- This ticket validates source-record schema and lifecycle-state behavior.
- This ticket does not implement live Source Registry Admin commands.
- This ticket does not create a command parser.
- This ticket does not mutate source registries.
- This ticket does not mutate Preview or Production source sets.
- This ticket does not start #271.
- #271 remains the extraction-profile lane.
- #271 remains open.
- #269 remains closed.
- #269 was not reopened.
- #269 was not closed by this ticket.
- No Source Registry Admin implementation child issues were created.
- No extraction-profile implementation tickets were created.
- 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 provider or model configuration was changed.
- No runtime retrieval behavior was changed.
- No package authority was changed.
- No Production apply was started.
- No OKF implementation was started.
- No Google SDLC implementation was started.
- No multi-agent orchestration implementation was started.
- `codex-automerge` was not applied.

## Post-Closeout Next Action

Explicit owner decision point:

After this schema/lifecycle validation slice is merged and locally closed out, choose whether to add a dry-run Source Registry Admin command parser or continue extraction-profile work for the next source.

Do not start either path by assumption.