# 05 — Domain and data model

## Domain boundaries

### Identity and workspace

Owns users, workspaces, memberships and authorization. The MVP may expose one personal workspace per user while retaining workspace IDs in the model for future team support.

### Playbook registry

Owns playbook identity, immutable versions, lifecycle, source, compatibility, content digest and publication state.

### Repository intelligence

Owns repository identities, manual profiles, source observations, profile snapshots, commands, protected paths and health findings.

### Composition

Owns drafts, normalized inputs, resolved policies, prompt blocks, lint findings, rendered output and generated runs.

### Artifacts

Owns exported Markdown, Run Packs, manifests, digests, retention and download authorization.

### Integrations

Owns forge connections, encrypted credentials, capability snapshots, synchronization jobs and health.

### Quality

Owns lint rules, evaluation cases, fixture references, evaluation results and quality status.

### Audit and operations

Owns audit events, job state, operational metrics and retention.

## Conceptual relationships

```mermaid
erDiagram
    USER ||--o{ WORKSPACE_MEMBERSHIP : has
    WORKSPACE ||--o{ WORKSPACE_MEMBERSHIP : contains
    WORKSPACE ||--o{ REPOSITORY : owns
    WORKSPACE ||--o{ COMPOSITION_DRAFT : owns
    WORKSPACE ||--o{ GENERATED_RUN : owns
    WORKSPACE ||--o{ INTEGRATION : owns

    PLAYBOOK ||--o{ PLAYBOOK_VERSION : versions
    PLAYBOOK_VERSION ||--o{ PLAYBOOK_EVALUATION : evaluated_by
    PLAYBOOK_VERSION ||--o{ COMPOSITION_DRAFT : selected_by
    PLAYBOOK_VERSION ||--o{ GENERATED_RUN : frozen_in

    REPOSITORY ||--o{ REPOSITORY_PROFILE_REVISION : profile_versions
    REPOSITORY ||--o{ REPOSITORY_SNAPSHOT : observed_as
    REPOSITORY_SNAPSHOT ||--o{ REPOSITORY_FINDING : produces
    REPOSITORY_PROFILE_REVISION ||--o{ COMPOSITION_DRAFT : used_by
    REPOSITORY_PROFILE_REVISION ||--o{ GENERATED_RUN : frozen_in

    COMPOSITION_DRAFT ||--o{ DRAFT_INPUT : contains
    COMPOSITION_DRAFT ||--o{ PROMPT_LINT_FINDING : reports
    GENERATED_RUN ||--o{ GENERATED_ARTIFACT : exports
    GENERATED_RUN ||--o{ RUN_FEEDBACK : receives

    INTEGRATION ||--o{ INTEGRATION_SECRET : references
    INTEGRATION ||--o{ SYNC_JOB : runs
```

## Core records

The complete relational contract and deletion behavior are defined in `docs/27-database-reference.md` and `database/reference-schema.sql`. The records below summarize the domain-facing fields.

### `user`

- `id`
- normalized unique email
- display name
- password hash managed by the authentication implementation
- instance role and account status
- password/session timestamps

### `workspace` and `workspace_membership`

- workspace identity, type and lifecycle timestamps
- membership user, role and creation timestamp
- every private resource is authorized through workspace membership

### `auth_session`, `invitation` and `password_reset_token`

Revocable session and single-use token records store hashes, never bearer values. Expiry, use and revocation are explicit.

### `playbook`

Mutable identity record.

- `id` UUID
- `slug` globally unique stable slug
- `namespace` such as `builtin`, `private.<workspace>` or future registry namespace
- `source_type` built_in, private, imported, remote_registry
- `created_at`, `updated_at`

### `playbook_version`

Immutable published content or mutable draft revision.

- `id` UUID
- `playbook_id`
- `semantic_version`
- `status` draft, reviewed, validated, battle_tested, deprecated
- `package_api_version`
- `title`, `summary`, `category`
- `risk_tier`
- `package_json` normalized canonical document
- `template_text`
- `content_digest`
- `published_at`
- `supersedes_version_id`
- `created_by`

Unique: `(playbook_id, semantic_version)` and `content_digest` within source namespace as appropriate.

Published rows are immutable at the application layer and protected by tests. A correction creates a new version.

### `repository`

- `id`
- `workspace_id`
- `display_name`
- `source_type` manual, gitea
- `external_owner`, `external_name`, `external_id`
- `integration_id` nullable
- `default_branch`
- `archived`
- timestamps

### `repository_profile_revision`

An immutable normalized profile used for composition.

- `id`
- `repository_id`
- `revision_number`
- `profile_json`
- `source_snapshot_id` nullable
- `content_digest`
- `created_by`
- `created_at`

### `repository_snapshot`

Evidence captured from an integration.

- `id`
- `repository_id`
- `integration_id`
- `captured_at`
- `capability_snapshot_json`
- `evidence_json`
- `evidence_digest`
- `sync_job_id`

### `repository_finding`

- `id`
- `snapshot_id`
- `rule_id`
- `severity` info, low, medium, high
- `title`
- `rationale`
- `evidence_pointer`
- `recommended_playbook_slug`
- `status` open, dismissed, resolved

### `composition_draft`

Mutable user workspace.

- `id`
- `workspace_id`
- `playbook_version_id`
- `repository_profile_revision_id` nullable
- `input_json`
- `autonomy_level`
- `work_mode`
- `last_render_digest`
- `updated_at`
- `created_by`

### `generated_run`

Immutable generation record. “Run” does not imply that Codex executed it.

- `id`
- `workspace_id`
- `source_draft_id` nullable
- `playbook_version_id`
- `playbook_snapshot_json`
- `repository_profile_snapshot_json` nullable
- `normalized_input_json`
- `policy_snapshot_json`
- `rendered_prompt`
- `render_digest`
- `lint_result_json`
- `generated_at`
- `generated_by`

### `generated_artifact`

- `id`
- `run_id`
- `artifact_type` prompt_text, markdown, run_pack_zip, agents_suggestion
- `storage_key`
- `filename`
- `size_bytes`
- `sha256`
- `expires_at` nullable
- `created_at`

### `integration`

- `id`
- `workspace_id`
- `type` gitea
- `display_name`
- `base_url`
- `status` configured, healthy, degraded, disabled
- `capabilities_json`
- `last_checked_at`
- timestamps

### `integration_secret`

The database stores encrypted material and metadata, never a retrievable plaintext response.

- `id`
- `integration_id`
- `secret_kind`
- `encrypted_value`
- `key_version`
- `last_four` optional safe identifier
- `created_at`, `rotated_at`

### `playbook_evaluation`

- `id`
- `playbook_version_id`
- `case_id`
- `fixture_version`
- `environment_json`
- `result_status`
- `dimension_scores_json`
- `evidence_artifact_key`
- `executed_at`
- `executed_by`

### Additional operational records

The reference schema also defines:

- favorites, collections and collection items;
- invitations, password resets and sessions;
- run feedback;
- evaluation cases and immutable results;
- PostgreSQL-backed jobs with leases and retries;
- append-only audit events;
- singleton instance setup/configuration state.

The application may store draft lint findings inside draft JSON, but final lint results and provenance are frozen in `generated_run`. Do not create a second contradictory source of truth.

## Indexing strategy

- GIN full-text index over playbook title, summary, category, tags and intent fields;
- B-tree indexes on workspace ownership, lifecycle, category, risk and update timestamps;
- unique digest indexes for immutable package and run content;
- trigram index for tolerant title/tag matching if extension support is available;
- partial indexes for active playbook versions and pending jobs.

## Retention

- playbook versions: retained indefinitely unless legally required otherwise;
- generated runs: operator-configurable, default indefinite for personal self-hosting;
- generated binary artifacts: default 90 days while immutable run text remains;
- integration snapshots: default latest 20 per repository plus referenced snapshots;
- audit events: default 180 days;
- operational logs: default 14–30 days.

Deleting a repository may anonymize or detach historical runs rather than destroying their frozen profile snapshot, depending on user selection and legal requirements.