This commit is contained in:
DevRunbook release export
@@ -0,0 +1,286 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user