From d84fcb7a21339b752fb99507dc047223f6ad70cf Mon Sep 17 00:00:00 2001 From: Sam Chau Date: Mon, 3 Nov 2025 02:02:12 +1030 Subject: [PATCH] docs: rewritten for OSQL standard --- docs/structure.md | 149 ++++++++++++++++++-------------- {schema => ops}/0.schema.sql | 0 {schema => ops}/1.languages.sql | 0 {schema => ops}/2.qualities.sql | 0 4 files changed, 86 insertions(+), 63 deletions(-) rename {schema => ops}/0.schema.sql (100%) rename {schema => ops}/1.languages.sql (100%) rename {schema => ops}/2.qualities.sql (100%) diff --git a/docs/structure.md b/docs/structure.md index 40dc9fc..cac67b3 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -1,79 +1,102 @@ -# PCD Structure +# Profile Compliant Databases (PCDs) -## Operational vs Stateful +## 1. Purpose -PCDs are **operational databases** - they store SQL operations, not data -snapshots. +PCDs describe a database as a sequence of SQL operations, not as final data. The +stored artifact is **how to build the state**, not **the state** itself. We +describe this as _operational_, instead of the traditional _stateful_. -| Stateful | Operational | -| ------------------------------ | ----------------------------------------------------------- | -| Stores what data should be | Stores how to create data | -| `{"name": "HD Quality"}` | `INSERT INTO quality_profiles (name) VALUES ('HD Quality')` | -| Merge conflicts when combining | Natural composition through execution order | -| Diffs show state changes | Diffs show operation changes | +## 2. Operational SQL (OSQL) -## Document Driven SQL +PCDs use SQL in an append-only, ordered way. Call this **Operational SQL +(OSQL)**. -Each entity is stored as a complete SQL document containing all related -operations. +1. **Append-only**: once an operation exists, it is never edited or deleted. +2. **Ordered**: operations run in a defined order; later operations can override + the effects of earlier ones. +3. **Replayable**: anyone can rebuild the database by replaying operations in + order. +4. **Relational**: operations target real tables/columns/rows, so constraints + (FKs) still apply. -**Example: A profile document (`profiles/hd-quality.sql`)** +This gives "Mutable Immutability": history is immutable; results are mutable +because new ops (operations) can be added. + +## 3. Change-Driven Development (CDD) + +CDD is the workflow for producing operations. + +1. Start from a change: "profile `1080p Quality HDR` should give `Dolby Atmos` a + higher score". +2. Express it as a single SQL operation: ```sql --- Profile entity -INSERT INTO quality_profiles (name, language_id) VALUES (...); - --- Quality list -INSERT INTO quality_profile_qualities (...); - --- Custom format scores -INSERT INTO quality_profile_custom_formats (...); - --- Tags -INSERT INTO quality_profile_tags (...); +UPDATE quality_profile_custom_formats +SET score = 1200 +WHERE profile_id = qp('1080p Quality HDR') +AND custom_format_id = cf('Dolby Atmos') +AND score = 400; -- expected previous value ``` -One file = one complete entity with all relationships. +3. Append it to the appropriate layer (see Layers below) +4. Recompose. -## Directory Structure +The expected-value guard (`AND score = 400`) is what makes conflicts explicit. -``` -database-repo/ -├── pcd.json # Manifest -├── operations/ -│ ├── core/ -│ │ ├── quality_profiles/ -│ │ │ ├── hd-quality.sql -│ │ │ ├── 4k-remux.sql -│ │ │ └── efficient-1080p.sql -│ │ ├── custom_formats/ -│ │ │ ├── dv-hdr10-plus.sql -│ │ │ ├── dolby-atmos.sql -│ │ │ └── scene-release.sql -│ │ └── regular_expressions/ -│ │ ├── dolby-vision-pattern.sql -│ │ ├── hdr10-plus-pattern.sql -│ │ └── remux-pattern.sql -│ └── tweaks/ -│ ├── anime-formats.sql -│ └── av1-profiles.sql -└── README.md +## 4. Layers + +PCDs run in layers. Every layer is append-only, but later layers can override +the effect of earlier ones. + +1. **Schema**\ + Core DDL for the PCD. Created and maintained by Profilarr. Creates tables, + FKs, indexes. **No data.** + +2. **Dependencies**\ + Reserved for future use. Will allow PCDs to compose with other PCDs. + +3. **Base**\ + The actual shipped database content (profiles, quality lists, format + definitions) for this PCD/version. + +4. **Tweaks**\ + Optional, append-only operations that adjust behaviour (allow DV, allow CAMS, + disable group Z). + +5. **User Ops**\ + User changes created for a specific instantiation of a database. Heavy value + guards to detect conflicts and alert users when upstream changes. + +## 5. Repository Layout + +A PCD repository has a manifest, an operations folder, and an optional tweaks +folder. + +```text +my-pcd/ +├── pcd.json +├── ops/ +│ ├── 1.create-1080p-Efficient.sql +└── tweaks/ + ├── allow-DV-no-fallback.sql + └── ban-megusta.sql ``` -Each entity type has its own directory. Each entity gets its own document file. - -## Execution Model - -PCDs execute as layered operations: +In the case of the schema, it's the same layout, with only the DDL in `ops/` and +no tweaks: +```text +schema-pcd/ +├── pcd.json +└── ops/ + └── 0.schema.sql ``` -1. Schema (CREATE TABLE statements) - ↓ -2. Dependencies (other PCD operations) - ↓ -3. Database (this PCD's operations) - ↓ -4. User customizations (user's operations) - ↓ -Result: Populated database -``` + +## 6. Dependencies (Post-2.0) + +**Dependencies are not part of 2.0.** At current scale (~10 in use databases), +forking solves shared-code needs without the complexity of dependency +resolution, version conflicts, and circular dependency detection. The layer +system supports adding dependencies in 2.1+ without breaking existing PCDs. +We'll build dependency support when clear duplication patterns emerge and +forking proves insufficient. diff --git a/schema/0.schema.sql b/ops/0.schema.sql similarity index 100% rename from schema/0.schema.sql rename to ops/0.schema.sql diff --git a/schema/1.languages.sql b/ops/1.languages.sql similarity index 100% rename from schema/1.languages.sql rename to ops/1.languages.sql diff --git a/schema/2.qualities.sql b/ops/2.qualities.sql similarity index 100% rename from schema/2.qualities.sql rename to ops/2.qualities.sql