# Source Registry Admin Command Contract V01

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

Date: 2026-06-27

Repository: `pinklon/ai-capability-discipline`

Baseline commit: `700305089ffc65c8e0d682d6357295f77d76b2ab`

Status: command contract design only. This ticket does not implement the commands, does not mutate source registries, 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 tickets, does not start #271, and does not apply `codex-automerge`.

## Purpose

Define the first Source Registry Admin command contract design slice for governed source lifecycle administration.

This contract defines administrative actions, inputs, outputs, refusals, receipts, lifecycle transitions, environment impacts, authority-lane impacts, and hard boundaries before any source registry mutation code exists.

The contract exists so later implementation work can be scoped against a documented command surface instead of inferring behavior from ad hoc scripts, live runtime posture, or operator memory.

## Relationship To Source Registry Admin Product Requirements

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

This ticket defines the first command contract design slice.

This ticket does not implement the commands.

This ticket does not mutate source registries.

The command contract uses `docs/product-architecture/source_registry_admin_product_requirements_v01.md` as the baseline for lifecycle states, source record fields, approval behavior, receipt behavior, refusal behavior, and authority separation.

This ticket preserves #269 as closed historical Source Registry Admin planning evidence and treats #325 / PR #326 as the product-requirements anchor.

## 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 can define commands for source approval, registration, validation, and environment-scoped administration, but a source must not become substantively useful for detailed enrichment until its retrieval and extraction profile passes validation.

The command contract must preserve package/current-public authority separation. Source Registry Admin commands can govern current/public enrichment source records and lifecycle posture. They must not promote current/public material into package authority, rewrite package content, or bypass the package approval path.

## Non-Goals

This command contract design does not:

- implement Source Registry Admin commands
- add runtime mutation behavior
- mutate source registries or source sets
- enable, disable, retire, or promote any source
- use Cloudflare CLI or API
- change provider or model configuration
- change runtime retrieval behavior
- change package authority
- create Source Registry Admin implementation child tickets
- create extraction-profile implementation tickets
- start #271
- reopen #269
- close #269
- close #271
- 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 broad crawling
- approve wildcard origins
- approve browser-side source fetch
- approve browser-side provider calls
- approve browser-side current-source calls
- approve undocumented source use
- apply `codex-automerge`

## Command Contract Overview

The command contract separates command intent from implementation. Each command must produce deterministic dry-run or read-only output before any later implementation is allowed to alter source lifecycle state or environment posture.

Command classes:

| Class | Commands | Contract boundary |
| --- | --- | --- |
| Source intake | `add_source`, `approve_source`, `register_source` | Captures proposal, approval, metadata, boundaries, and citation fields without activation. |
| Validation and smoke | `validate_source`, `run_source_smoke` | Tests metadata, retrieval/extraction profile readiness, citation behavior, and browser/provider boundaries without activation. |
| Preview lifecycle | `enable_preview`, `disable_preview` | Defines Preview-only lifecycle transitions that require validation, receipts, and last-known-good capture before any later implementation can mutate an environment. |
| Production lifecycle | `mark_production_eligible`, `promote_to_production`, `disable_production` | Defines Production eligibility, promotion, and disablement gates that require Preview evidence, validation, receipts, and explicit authorization. |
| Emergency and recovery | `emergency_disable`, `rollback_registry`, `retire_source` | Defines restricted response paths that preserve audit history and require receipts. |
| Inspection and evidence | `list_sources`, `list_active_sources`, `show_source_detail`, `generate_receipt` | Provides read-only inspection and evidence generation boundaries. |

All lifecycle-changing commands must require receipt generation. Environment-changing commands must require last-known-good registry capture before any later implementation may mutate Preview or Production posture.

## Source Lifecycle Model

The lifecycle model preserves the Source Registry Admin product requirements baseline:

| 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. |

Recommended refinement for implementation planning: environment posture should be modeled separately from source identity. A source can be `registered` and have no active environments, `preview_enabled` only in Preview, `production_enabled` only in Production, or `disabled` for one environment while its historical record remains intact. This refinement does not remove any required lifecycle concept.

## Source Record Command Input Model

Minimum source-record command inputs:

| Field | Requirement |
| --- | --- |
| `source_id` | Stable source identifier used in registries, receipts, citations, and audit history. |
| `source_name` | Human-readable source name. |
| `source_version` or `publication_date` | Version or publication marker when applicable. |
| `source_type` | Source class, such as public standard, vendor documentation, government guidance, framework, or other approved class. |
| `authority_lane` | Authority lane. Current/public enrichment authority is the default for externally approved enrichment sources. |
| `canonical_url` or `document_location` | Canonical source location. User-provided retrieval outside governed `add_source` is refused. |
| `allowed_origin` | Exact allowed origin. Wildcard origins are forbidden. |
| `allowed_path_prefix` | Exact allowed path prefix or document location boundary. Broad crawling is forbidden. |
| `retrieval_profile_id` | Retrieval profile that defines bounded retrieval behavior. |
| `extraction_profile_id` | Extraction profile when different from retrieval profile or required for substantive bounded cited content. |
| `environment_eligibility` | Preview and Production eligibility markers and prerequisites. |
| `approval_status` | Approval status, including proposed, approved, rejected, disabled, or retired as applicable. |
| `approved_by` | Owner, steward, or approval role. |
| `approved_at` | Approval timestamp. |
| `approval_rationale` | Evidence-backed reason for approval and allowed use. |
| `source_owner` or `steward` | Accountable source owner or steward. |
| `citation_label` | Human-readable citation label used in answers. |
| `citation_url` | Citation URL or document reference. |
| `validation_status` | Validation result and state. |
| `active_environments` | Environments where the source is currently active. |
| `disable_reason` | Reason for disablement when applicable. |
| `retired_at` | Retirement timestamp when applicable. |
| `receipt_refs` | Receipt references for approval, validation, activation, disablement, rollback, retirement, and source-use documentation. |

Commands may require additional fields, but they must not relax these minimum source-record fields when the command creates, approves, registers, activates, disables, rolls back, or retires source posture.

## Command Definitions

### `add_source`

| Contract field | Requirement |
| --- | --- |
| Purpose | Create a proposed source record through the governed source-add workflow. |
| Required inputs | `source_id`, `source_name`, `source_type`, `authority_lane`, `canonical_url` or `document_location`, `allowed_origin`, `allowed_path_prefix`, `source_owner` or `steward`, `citation_label`, `citation_url`, proposal rationale, operator or actor. |
| Optional inputs | `source_version`, `publication_date`, proposed `retrieval_profile_id`, proposed `extraction_profile_id`, proposed `environment_eligibility`, proposed approval notes. |
| Required source lifecycle preconditions | Source ID must be absent from active records or present only as a rejected/retired historical record that is explicitly being superseded without deleting history. |
| Required environment preconditions | No Preview or Production activation is allowed. |
| Validation checks | Source ID uniqueness, exact allowed origin, exact allowed path prefix, HTTPS or owner-approved exception, source owner or steward present, citation fields present, no wildcard origins, no broad crawl boundary, no package-authority claim. |
| Refusal cases | Arbitrary web search, user-provided URL retrieval outside governed `add_source`, broad crawling, wildcard origins, missing steward, missing citation fields, duplicate active source ID, package-authority promotion, undocumented source use. |
| Output shape | Proposed source record, validation summary, refusal checks passed, lifecycle state `proposed`, no active environments, receipt requirement summary. |
| Receipt requirements | Intake receipt with command name, actor, timestamp, source ID, previous lifecycle state if any, new lifecycle state `proposed`, boundary confirmations, and audit-history preservation. |
| Audit/history behavior | Append proposal event. Preserve superseded or retired history. Do not delete prior records. |
| Source lifecycle transition | None to `proposed`, or historical supersession to a new `proposed` record. |
| Environment impact | None. |
| Authority-lane impact | Records proposed authority lane only. Does not grant package authority. |
| Hard boundaries | Does not activate the source, does not retrieve arbitrary URLs, and does not mutate runtime environment configuration. |

### `approve_source`

| Contract field | Requirement |
| --- | --- |
| Purpose | Record owner or steward approval for a proposed source under a defined authority lane and use boundary. |
| Required inputs | `source_id`, `approval_status`, `approved_by`, `approved_at`, `approval_rationale`, `authority_lane`, allowed use, excluded use, `environment_eligibility`, operator or actor. |
| Optional inputs | Approval evidence references, conditions, expiration or review cadence. |
| Required source lifecycle preconditions | Source is `proposed` or has an explicit reapproval reason. |
| Required environment preconditions | Source is inactive in Preview and Production. |
| Validation checks | Approver present, approval rationale present, authority lane allowed, environment eligibility explicit, source owner present, source boundaries present, no candidate-only activation. |
| Refusal cases | Missing approval evidence, missing owner or steward, activation without source approval, package-authority promotion, undocumented source use, approval of wildcard origin or broad crawl boundary. |
| Output shape | Approval decision, lifecycle state `approved` for accepted approvals, explicit rejection state for rejected proposals, approval evidence references. |
| Receipt requirements | Approval receipt with command name, actor, timestamp, source ID, previous lifecycle state, new lifecycle state, validation checks run, refusal checks passed, boundary confirmations. |
| Audit/history behavior | Append approval event. Preserve rejected and superseded proposal history. |
| Source lifecycle transition | `proposed` to `approved` when accepted. |
| Environment impact | None. |
| Authority-lane impact | Records approved authority lane, usually current/public enrichment. Does not create package authority. |
| Hard boundaries | Approval does not activate a source and does not authorize runtime retrieval behavior. |

### `register_source`

| Contract field | Requirement |
| --- | --- |
| Purpose | Record complete governed source metadata, approval evidence, boundaries, profiles, citation fields, and receipt references. |
| Required inputs | All minimum source-record fields that apply at registration: `source_id`, `source_name`, version or publication marker if applicable, `source_type`, `authority_lane`, canonical location, `allowed_origin`, `allowed_path_prefix`, `retrieval_profile_id`, `environment_eligibility`, `approval_status`, `approved_by`, `approved_at`, `approval_rationale`, steward, citation fields, `receipt_refs`, operator or actor. |
| Optional inputs | `extraction_profile_id` when different or required, validation notes, review cadence, deprecation notes. |
| Required source lifecycle preconditions | Source is `approved`. |
| Required environment preconditions | Source is inactive in Preview and Production. |
| Validation checks | Required metadata complete, approval status approved, retrieval profile present, extraction profile status documented, citation fields present, active environments empty, receipt references present. |
| Refusal cases | Activation without source approval, activation without validation, undocumented source use, missing retrieval profile, missing extraction profile when substantive extraction is required, source deletion that erases audit history. |
| Output shape | Registered source record, metadata completeness status, lifecycle state `registered`, active environments unchanged. |
| Receipt requirements | Registration receipt with previous lifecycle state, new lifecycle state `registered`, metadata validation checks, refusal checks passed, receipt references, boundary confirmations. |
| Audit/history behavior | Append registration event and retain approval evidence. |
| Source lifecycle transition | `approved` to `registered`. |
| Environment impact | None. |
| Authority-lane impact | Keeps approved authority lane. Does not alter package authority. |
| Hard boundaries | Registration does not activate Preview or Production. |

### `validate_source`

| Contract field | Requirement |
| --- | --- |
| Purpose | Validate source metadata, boundaries, authority lane, retrieval profile, extraction profile posture, citation fields, and environment eligibility. |
| Required inputs | `source_id`, validation scope, operator or actor, expected lifecycle state, expected environment posture. |
| Optional inputs | Environment target, profile override for dry-run validation, timestamp, evidence output path. |
| Required source lifecycle preconditions | Source is `registered`, `preview_enabled`, `production_eligible`, `production_enabled`, or `disabled` for revalidation. |
| Required environment preconditions | Validation can be environment-neutral or environment-scoped. It must not mutate active environments. |
| Validation checks | Metadata completeness, approval evidence, exact allowed origin, exact path prefix, retrieval profile, extraction profile if required, citation fields, environment eligibility, receipt references, no browser-side fetch path. |
| Refusal cases | Activation without validation, candidate-only source activation, arbitrary web search, user-provided URL retrieval outside governed `add_source`, broad crawling, wildcard origins, browser-side source fetch, browser-side provider/current-source calls. |
| Output shape | Validation status, checks run, problems, warnings, eligible next commands, receipt recommendation. |
| Receipt requirements | Required when validation changes source validation status or is used as evidence for lifecycle transition. |
| Audit/history behavior | Append validation event when receipt-backed. Preserve prior validation history. |
| Source lifecycle transition | None by itself. |
| Environment impact | None. |
| Authority-lane impact | Confirms authority lane. Does not promote authority. |
| Hard boundaries | Validation does not activate or deactivate any source. |

### `enable_preview`

| Contract field | Requirement |
| --- | --- |
| Purpose | Define Preview enablement for a registered and validated source. |
| Required inputs | `source_id`, target environment `preview`, expected repo head, expected previous Preview source set, last-known-good registry reference or output target, validation evidence, smoke plan, receipt output target, operator or actor. |
| Optional inputs | Activation window, rollback notes, preview smoke prompt set, expected active source IDs. |
| Required source lifecycle preconditions | Source is `registered` and validation status is passing for Preview. |
| Required environment preconditions | Preview eligibility is present. Last-known-good Preview registry capture is required before any later implementation mutates environment posture. |
| Validation checks | Source approved, registered, validated, Preview eligible, no candidate-only activation, receipt target present, last-known-good capture present, source not retired, expected source-set guard matches. |
| Refusal cases | Candidate-only source activation, activation without source approval, activation without validation, environment mutation without last-known-good registry capture, activation without receipt generation, wildcard origins, browser-side source fetch. |
| Output shape | Preview enablement plan, previous active environments, proposed active environments, lifecycle transition, receipt fields, rollback reference. |
| Receipt requirements | Required before and after any later implementation of Preview enablement. |
| Audit/history behavior | Append Preview activation event and preserve prior source-set posture. |
| Source lifecycle transition | `registered` to `preview_enabled` when later implemented and accepted. |
| Environment impact | Preview only. |
| Authority-lane impact | Current/public enrichment remains current/public. No package authority change. |
| Hard boundaries | This design ticket does not enable Preview. Production is unaffected. |

### `disable_preview`

| Contract field | Requirement |
| --- | --- |
| Purpose | Define Preview disablement without deleting source history. |
| Required inputs | `source_id`, target environment `preview`, disable reason, expected repo head, expected previous Preview source set, last-known-good registry reference or output target, receipt output target, operator or actor. |
| Optional inputs | Follow-up validation target, replacement source notes, rollback notes. |
| Required source lifecycle preconditions | Source is active in Preview or has a documented Preview posture discrepancy requiring correction. |
| Required environment preconditions | Last-known-good Preview registry capture is required before any later implementation mutates environment posture. |
| Validation checks | Source exists, Preview active or discrepancy documented, disable reason present, receipt target present, audit history preserved, expected source-set guard matches. |
| Refusal cases | Source deletion that erases audit history, environment mutation without last-known-good registry capture, emergency disable without a receipt, unknown source ID, missing disable reason. |
| Output shape | Preview disablement plan, previous active environments, proposed active environments, disable reason, rollback reference. |
| Receipt requirements | Required for lifecycle and environment posture change. |
| Audit/history behavior | Append disablement event. Preserve approval, validation, and activation records. |
| Source lifecycle transition | `preview_enabled` to `disabled` for Preview posture, unless Production remains active under separate posture. |
| Environment impact | Preview only. |
| Authority-lane impact | No authority-lane change. |
| Hard boundaries | This design ticket does not disable Preview. Production is unaffected. |

### `mark_production_eligible`

| Contract field | Requirement |
| --- | --- |
| Purpose | Record that a source has met Production eligibility prerequisites without activating Production. |
| Required inputs | `source_id`, Preview validation evidence, Preview smoke evidence, retrieval/extraction validation evidence, environment eligibility, receipt references, operator or actor. |
| Optional inputs | Eligibility expiration, reviewer notes, risk notes, follow-up smoke requirements. |
| Required source lifecycle preconditions | Source is `preview_enabled` or has equivalent receipt-backed Preview evidence. |
| Required environment preconditions | Production eligibility review is complete. Production remains inactive. |
| Validation checks | Preview evidence present, metadata validation passing, retrieval/extraction validation passing, receipt checks passing, Production eligibility explicit, last-known-good readiness documented. |
| Refusal cases | Production activation without production eligibility, activation without validation, Production activation without receipt generation, missing Preview smoke evidence, package-authority promotion. |
| Output shape | Production eligibility decision, lifecycle state `production_eligible`, evidence references, next eligible command. |
| Receipt requirements | Eligibility receipt with validation checks, evidence references, refusal checks passed, boundary confirmations. |
| Audit/history behavior | Append eligibility event. Preserve Preview evidence. |
| Source lifecycle transition | `preview_enabled` to `production_eligible`. |
| Environment impact | None. Production remains inactive. |
| Authority-lane impact | Confirms authority lane for current/public enrichment. No package authority change. |
| Hard boundaries | Does not activate Production. |

### `promote_to_production`

| Contract field | Requirement |
| --- | --- |
| Purpose | Define Production promotion for an eligible source with receipt-backed authorization, smoke evidence, and rollback readiness. |
| Required inputs | `source_id`, target environment `production`, production eligibility receipt, expected repo head, expected previous Production source set, last-known-good Production registry reference or output target, validation evidence, smoke evidence, receipt output target, operator or actor. |
| Optional inputs | Activation window, rollback notes, Production smoke prompt set, expected active source IDs. |
| Required source lifecycle preconditions | Source is `production_eligible`. |
| Required environment preconditions | Production eligibility present, Production last-known-good capture present, Production receipt target present, explicit authorization present. |
| Validation checks | Source approved, registered, validated, Preview evidence present, Production eligible, receipt target present, last-known-good capture present, expected source-set guard matches, source not retired. |
| Refusal cases | Production activation without production eligibility, Production activation without receipt generation, activation without source approval, activation without validation, environment mutation without last-known-good registry capture, rollback without a known-good target, package-authority promotion. |
| Output shape | Production promotion plan, previous active environments, proposed active environments, lifecycle transition, receipt fields, rollback reference. |
| Receipt requirements | Required before and after any later implementation of Production promotion. |
| Audit/history behavior | Append Production promotion event and preserve previous Production posture. |
| Source lifecycle transition | `production_eligible` to `production_enabled` when later implemented and accepted. |
| Environment impact | Production only. |
| Authority-lane impact | Keeps current/public enrichment authority. Does not promote package authority. |
| Hard boundaries | This design ticket does not promote to Production and does not start Production apply. |

### `disable_production`

| Contract field | Requirement |
| --- | --- |
| Purpose | Define Production disablement without deleting source history. |
| Required inputs | `source_id`, target environment `production`, disable reason, expected repo head, expected previous Production source set, last-known-good registry reference or output target, receipt output target, operator or actor. |
| Optional inputs | Follow-up validation target, replacement source notes, rollback notes, incident reference. |
| Required source lifecycle preconditions | Source is active in Production or has a documented Production posture discrepancy requiring correction. |
| Required environment preconditions | Last-known-good Production registry capture is required before any later implementation mutates environment posture. |
| Validation checks | Source exists, Production active or discrepancy documented, disable reason present, receipt target present, audit history preserved, expected source-set guard matches. |
| Refusal cases | Source deletion that erases audit history, environment mutation without last-known-good registry capture, emergency disable without a receipt, unknown source ID, missing disable reason. |
| Output shape | Production disablement plan, previous active environments, proposed active environments, disable reason, rollback reference. |
| Receipt requirements | Required for lifecycle and environment posture change. |
| Audit/history behavior | Append disablement event. Preserve approval, validation, activation, and Production evidence records. |
| Source lifecycle transition | `production_enabled` to `disabled` for Production posture, unless Preview remains active under separate posture. |
| Environment impact | Production only. |
| Authority-lane impact | No authority-lane change. |
| Hard boundaries | This design ticket does not disable Production. |

### `emergency_disable`

| Contract field | Requirement |
| --- | --- |
| Purpose | Define restricted emergency disablement for Preview or Production while preserving evidence and follow-up obligations. |
| Required inputs | `source_id`, target environment, emergency trigger, operator or actor, expected previous source set if available, last-known-good registry reference or capture target, emergency receipt output target, follow-up owner, follow-up deadline. |
| Optional inputs | Incident reference, risk notes, immediate containment rationale, later validation plan. |
| Required source lifecycle preconditions | Source exists and is active or suspected active in target environment. |
| Required environment preconditions | Emergency path must still capture or reference last-known-good posture and generate a receipt. |
| Validation checks | Source exists, environment valid, emergency reason present, receipt target present, audit history preserved, follow-up requirement present. |
| Refusal cases | Emergency disable without a receipt, source deletion that erases audit history, rollback without a known-good target when rollback is requested, unknown source ID, missing emergency trigger. |
| Output shape | Emergency disable plan, previous active environments if known, proposed active environments, emergency trigger, receipt fields, follow-up requirement. |
| Receipt requirements | Required. Emergency disable without a receipt is refused. |
| Audit/history behavior | Append emergency event and follow-up obligation. Preserve all prior records. |
| Source lifecycle transition | Active environment posture to `disabled` for the target environment when later implemented and accepted. |
| Environment impact | Target environment only unless explicitly authorized for both Preview and Production. |
| Authority-lane impact | No authority-lane change. |
| Hard boundaries | This design ticket does not execute emergency disablement. |

### `rollback_registry`

| Contract field | Requirement |
| --- | --- |
| Purpose | Define rollback to a known-good registry for a target environment. |
| Required inputs | Target environment, known-good registry reference, rollback reason, expected current registry reference, operator or actor, receipt output target. |
| Optional inputs | Source ID, incident reference, validation after rollback, smoke plan after rollback. |
| Required source lifecycle preconditions | Not source-specific unless rollback targets a source-specific environment posture. |
| Required environment preconditions | Known-good target exists and is compatible with target environment. |
| Validation checks | Known-good target present, expected current registry captured, rollback reason present, receipt target present, audit history preserved, boundary confirmations present. |
| Refusal cases | Rollback without a known-good target, environment mutation without last-known-good registry capture, source deletion that erases audit history, missing rollback reason. |
| Output shape | Rollback plan, target environment, current registry reference, known-good reference, affected source IDs, receipt fields. |
| Receipt requirements | Required for rollback planning and any later rollback execution. |
| Audit/history behavior | Append rollback event and preserve superseded registry references. |
| Source lifecycle transition | Environment posture changes to match known-good registry when later implemented and accepted. |
| Environment impact | Target environment only. |
| Authority-lane impact | No authority-lane change. |
| Hard boundaries | This design ticket does not execute rollback. |

### `retire_source`

| Contract field | Requirement |
| --- | --- |
| Purpose | Mark a source retired while preserving metadata, receipts, and audit records. |
| Required inputs | `source_id`, retirement reason, `retired_at`, operator or actor, receipt output target, active-environment posture. |
| Optional inputs | Replacement source ID, deprecation notes, citation-use sunset notes. |
| Required source lifecycle preconditions | Source exists and is not already retired, or a repeated retirement event is explicitly documented as no-op evidence. |
| Required environment preconditions | Source must be inactive or have a separate disablement plan for active environments before retirement can complete. |
| Validation checks | Source exists, retirement reason present, active environments reviewed, receipt target present, audit history preserved, source-use documentation impact recorded. |
| Refusal cases | Source deletion that erases audit history, retirement while active without a disablement plan, undocumented source use, missing retirement reason. |
| Output shape | Retirement decision, previous lifecycle state, new lifecycle state `retired`, source-use documentation impact, receipt fields. |
| Receipt requirements | Required. |
| Audit/history behavior | Append retirement event and preserve all records. |
| Source lifecycle transition | Current non-retired state to `retired` after environment posture is inactive or explicitly handled. |
| Environment impact | None by itself unless paired with disablement. |
| Authority-lane impact | Source is no longer eligible for normal activation in its authority lane. Does not erase authority history. |
| Hard boundaries | Retirement is not deletion. Audit history remains. This design ticket does not retire any source. |

### `list_sources`

| Contract field | Requirement |
| --- | --- |
| Purpose | List governed source records and lifecycle states. |
| Required inputs | Output format, operator or actor. |
| Optional inputs | Lifecycle filter, authority-lane filter, environment filter, source type filter. |
| Required source lifecycle preconditions | None. |
| Required environment preconditions | None. |
| Validation checks | Registry readable, output format valid, filters valid, no secret values emitted. |
| Refusal cases | Request for secret values, arbitrary web search, undocumented source use, package-authority promotion. |
| Output shape | Source list with source ID, source name, lifecycle state, authority lane, validation status, active environments, receipt references. |
| Receipt requirements | Optional inspection receipt unless used as governance evidence. |
| Audit/history behavior | Read-only access may be logged by operator environment, but source history is unchanged. |
| Source lifecycle transition | None. |
| Environment impact | None. |
| Authority-lane impact | None. |
| Hard boundaries | Read-only. Does not fetch sources or mutate registries. |

### `list_active_sources`

| Contract field | Requirement |
| --- | --- |
| Purpose | List active source IDs by environment. |
| Required inputs | Target environment, output format, operator or actor. |
| Optional inputs | Authority-lane filter, include inactive comparison, include receipt references. |
| Required source lifecycle preconditions | None. |
| Required environment preconditions | Target environment must be explicit. |
| Validation checks | Environment valid, active posture source IDs map to governed records, no candidate-only active sources. |
| Refusal cases | Unknown environment, undocumented source use, browser-side source fetch, browser-side provider/current-source calls. |
| Output shape | Environment, active source IDs, source names, lifecycle states, authority lanes, validation status, receipt references. |
| Receipt requirements | Optional inspection receipt unless used as governance evidence. |
| Audit/history behavior | Read-only access may be logged by operator environment, but source history is unchanged. |
| Source lifecycle transition | None. |
| Environment impact | None. |
| Authority-lane impact | None. |
| Hard boundaries | Read-only. Does not probe live Cloudflare or mutate source sets. |

### `show_source_detail`

| Contract field | Requirement |
| --- | --- |
| Purpose | Show governed source metadata, approval evidence, boundaries, profiles, citation fields, environment posture, and receipts. |
| Required inputs | `source_id`, output format, operator or actor. |
| Optional inputs | Include history, include receipt detail, include validation detail. |
| Required source lifecycle preconditions | Source record exists. |
| Required environment preconditions | None. |
| Validation checks | Source ID known, secret values redacted, record has audit-history references. |
| Refusal cases | Unknown source ID, request for secret values, undocumented source use, package-authority promotion. |
| Output shape | Source detail record with lifecycle state, authority lane, boundaries, profiles, approval evidence, citation fields, active environments, validation status, receipts, history summary. |
| Receipt requirements | Optional inspection receipt unless used as governance evidence. |
| Audit/history behavior | Read-only. Does not alter source history. |
| Source lifecycle transition | None. |
| Environment impact | None. |
| Authority-lane impact | None. |
| Hard boundaries | Read-only. Does not fetch source content or mutate environment posture. |

### `generate_receipt`

| Contract field | Requirement |
| --- | --- |
| Purpose | Generate receipt evidence for an admin action, refusal, validation run, activation, disablement, rollback, retirement, or source-use event. |
| Required inputs | Command name or receipt type, operator or actor, timestamp, source ID when applicable, environment when applicable, previous state when applicable, new state when applicable, validation checks run, refusal checks passed, boundary confirmations. |
| Optional inputs | Registry snapshot reference, last-known-good reference, rollback reference, citation/use documentation impact, incident reference. |
| Required source lifecycle preconditions | Depends on receipt type. Source-specific receipts require known source ID unless recording an unknown-source refusal. |
| Required environment preconditions | Environment-specific receipts require explicit environment. |
| Validation checks | Required receipt fields present, timestamp valid, source ID maps to known record or refusal case, boundary confirmations present. |
| Refusal cases | Emergency disable without a receipt, Production activation without receipt generation, activation without receipt generation, undocumented source use, source deletion that erases audit history. |
| Output shape | Receipt object or Markdown receipt with schema/version, command name, actor, timestamp, source and environment fields, checks, references, confirmations. |
| Receipt requirements | This command produces the receipt. |
| Audit/history behavior | Receipt reference is appended to relevant source or environment history when later implementation exists. |
| Source lifecycle transition | None by itself. |
| Environment impact | None. |
| Authority-lane impact | None. |
| Hard boundaries | Receipt generation does not authorize a mutation by itself. |

### `run_source_smoke`

| Contract field | Requirement |
| --- | --- |
| Purpose | Run bounded source smoke for metadata, retrieval/extraction profile readiness, citation lane, and browser/provider boundary checks. |
| Required inputs | `source_id`, smoke scope, target environment or dry-run environment, expected retrieval profile, expected extraction profile when applicable, expected citation behavior, operator or actor. |
| Optional inputs | Smoke prompt set, expected source markers, evidence output target, timestamp. |
| Required source lifecycle preconditions | Source is `registered`, `preview_enabled`, `production_eligible`, `production_enabled`, or `disabled` for revalidation. |
| Required environment preconditions | Smoke environment must be explicit. Browser-side source fetch and browser-side provider/current-source calls must remain forbidden. |
| Validation checks | Source exists, metadata complete, profile IDs present, citation label and URL present, boundary refusals exercised, browser/provider boundary checks pass. |
| Refusal cases | Browser-side source fetch, browser-side provider/current-source calls, arbitrary web search, user-provided URL retrieval outside governed `add_source`, broad crawling, wildcard origins, undocumented source use. |
| Output shape | Smoke result, checks run, citations observed or expected, refusals observed, browser/provider boundary confirmations, receipt recommendation. |
| Receipt requirements | Required when smoke evidence supports lifecycle transition or environment posture. |
| Audit/history behavior | Append smoke evidence reference when receipt-backed. |
| Source lifecycle transition | None by itself. |
| Environment impact | None unless later used as evidence for an authorized lifecycle command. |
| Authority-lane impact | Confirms citation lane. Does not promote package authority. |
| Hard boundaries | Smoke does not mutate registries or source sets. |

## Refusal Behavior

The command contract must explicitly refuse:

- arbitrary web search
- user-provided URL retrieval outside governed `add_source`
- broad crawling
- wildcard origins
- candidate-only source activation
- activation without source approval
- activation without validation
- Production activation without production eligibility
- Production activation without receipt generation
- browser-side source fetch
- browser-side provider/current-source calls
- package-authority promotion
- undocumented source use
- source deletion that erases audit history
- environment mutation without last-known-good registry capture
- rollback without a known-good target
- emergency disable without a receipt

Refusals are receipt-worthy when they affect lifecycle posture, environment posture, security boundary, source-use documentation, rollback readiness, or operator audit trail.

## Receipt Model

Each mutating or lifecycle-changing command must require a receipt before any later implementation can apply the requested change.

Minimum receipt fields:

| Field | Requirement |
| --- | --- |
| `command_name` | Command that produced or required the receipt. |
| `operator` or `actor` | Person, role, or automation identity that invoked the command. |
| `timestamp` | ISO 8601 timestamp. |
| `source_id` | Source identifier when source-specific. |
| `previous_lifecycle_state` | State before the command or `not_applicable`. |
| `new_lifecycle_state` | State after the command or proposed state for dry-run. |
| `previous_active_environments` | Active environment list before the command. |
| `new_active_environments` | Active environment list after the command or proposed state for dry-run. |
| `validation_checks_run` | Checks executed or required. |
| `refusal_checks_passed` | Refusal gates confirmed before accepting the command. |
| `registry_snapshot` or `last_known_good_reference` | Registry snapshot or last-known-good reference for environment-changing commands. |
| `citation_use_documentation_impact` | Whether source-use docs or citation behavior changed or remained unchanged. |
| `rollback_reference` | Rollback target or reason not applicable. |
| `boundary_confirmations` | Explicit confirmations for no arbitrary web search, no browser-side fetch, no package-authority promotion, and no audit-history deletion. |

Receipts for emergency disable, rollback, Production promotion, Production disablement, Preview enablement, and Preview disablement must include environment, expected previous source set, proposed new source set, and last-known-good registry reference.

## Audit/History Behavior

Source Registry Admin must be append-first. Commands may add proposal, approval, registration, validation, activation, disablement, emergency, rollback, retirement, smoke, or refusal events. They must not erase prior source history.

Audit history must preserve:

- source identity history
- approval evidence
- lifecycle state transitions
- active environment changes
- validation and smoke evidence
- receipt references
- disablement reasons
- retirement reasons
- rollback references
- refusal events that protect source, environment, authority, or audit boundaries

Source deletion that erases audit history is forbidden.

## Environment Behavior

Environment behavior is explicit and environment-scoped:

- `preview` and `production` are distinct environment postures.
- Preview enablement does not imply Production enablement.
- Production activation requires `production_eligible`.
- Environment mutation without last-known-good registry capture is refused.
- Production activation without receipt generation is refused.
- Emergency disable without a receipt is refused.
- Rollback without a known-good target is refused.
- This ticket does not mutate Preview or Production.

## Authority-Lane Behavior

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

- Current/public enrichment authority is the default 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 a source activation as package approval.
- Source-use documentation must identify whether claims are package-grounded or current/public enrichment-grounded.

Package-authority promotion is refused unless a separate owner-approved package-authority process exists outside this command contract.

## Guardrails

Hard guardrails:

- no arbitrary web search
- no user-provided URL retrieval outside governed `add_source`
- no broad crawling
- no wildcard origins
- no candidate-only source activation
- no activation without source approval
- no activation without validation
- no Production activation without production eligibility
- no Production activation without receipt generation
- no browser-side source fetch
- no browser-side provider/current-source calls
- no package-authority promotion
- no undocumented source use
- no source deletion that erases audit history
- no environment mutation without last-known-good registry capture
- no rollback without a known-good target
- no emergency disable without a receipt
- no source registry mutation from this design ticket
- no runtime retrieval behavior change from this design ticket

## Candidate Implementation Sequencing

Recommended next child tickets for later owner decision, not created by this ticket:

1. Define source registry schema and lifecycle-state validator v01.
2. Add dry-run source registry admin command parser v01.
3. Add source record validation v01.
4. Add receipt schema for source admin commands v01.
5. Add dry-run `add_source` and `validate_source` workflow v01.
6. Add dry-run Preview enable/disable workflow v01.
7. Add last-known-good registry snapshot model v01.
8. Add emergency disable/rollback design implementation v01.
9. Add operator documentation v01.

This sequencing is candidate planning only. It does not create implementation tickets and does not authorize implementation.

## Boundary Confirmations

- #325 / PR #326 defines Source Registry Admin product requirements.
- This ticket defines the first command contract design slice.
- This ticket does not implement the commands.
- This ticket does not mutate source registries.
- 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.
- The command contract preserves package/current-public authority separation.
- 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.
- No source was disabled.
- No source was retired.
- No source was 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 command contract design is merged and locally closed out, choose whether to implement source registry schema/lifecycle-state validation first or continue extraction-profile work for the next source.

Do not start either path by assumption.