docs: rewritten for OSQL standard

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
+PCDs describe a database as a sequence of SQL operations, not as final data. The
-snapshots.
+stored artifact is **how to build the state**, not **the state** itself. We
+describe this as _operational_, instead of the traditional _stateful_.
 
-| Stateful                       | Operational                                                 |
+## 2. Operational SQL (OSQL)
-| ------------------------------ | ----------------------------------------------------------- |
-| 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                                |
 
-## 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
+1. **Append-only**: once an operation exists, it is never edited or deleted.
-operations.
+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
+UPDATE quality_profile_custom_formats
-INSERT INTO quality_profiles (name, language_id) VALUES (...);
+SET score = 1200
-
+WHERE profile_id = qp('1080p Quality HDR')
--- Quality list
+AND custom_format_id = cf('Dolby Atmos')
-INSERT INTO quality_profile_qualities (...);
+AND score = 400; -- expected previous value
-
--- Custom format scores  
-INSERT INTO quality_profile_custom_formats (...);
-
--- Tags
-INSERT INTO quality_profile_tags (...);
 ```
 
-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.
 
-```
+## 4. Layers
-database-repo/
+
-├── pcd.json                           # Manifest
+PCDs run in layers. Every layer is append-only, but later layers can override
-├── operations/
+the effect of earlier ones.
-│   ├── core/
+
-│   │   ├── quality_profiles/
+1. **Schema**\
-│   │   │   ├── hd-quality.sql
+   Core DDL for the PCD. Created and maintained by Profilarr. Creates tables,
-│   │   │   ├── 4k-remux.sql
+   FKs, indexes. **No data.**
-│   │   │   └── efficient-1080p.sql
+
-│   │   ├── custom_formats/
+2. **Dependencies**\
-│   │   │   ├── dv-hdr10-plus.sql
+   Reserved for future use. Will allow PCDs to compose with other PCDs.
-│   │   │   ├── dolby-atmos.sql
+
-│   │   │   └── scene-release.sql
+3. **Base**\
-│   │   └── regular_expressions/
+   The actual shipped database content (profiles, quality lists, format
-│   │       ├── dolby-vision-pattern.sql
+   definitions) for this PCD/version.
-│   │       ├── hdr10-plus-pattern.sql
+
-│   │       └── remux-pattern.sql
+4. **Tweaks**\
-│   └── tweaks/
+   Optional, append-only operations that adjust behaviour (allow DV, allow CAMS,
-│       ├── anime-formats.sql
+   disable group Z).
-│       └── av1-profiles.sql
+
-└── README.md
+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.
+In the case of the schema, it's the same layout, with only the DDL in `ops/` and
-
+no tweaks:
-## Execution Model
-
-PCDs execute as layered operations:
 
+```text
+schema-pcd/
+├── pcd.json
+└── ops/
+    └── 0.schema.sql
 ```
-1. Schema (CREATE TABLE statements)
+
-   ↓
+## 6. Dependencies (Post-2.0)
-2. Dependencies (other PCD operations)
+
-   ↓
+**Dependencies are not part of 2.0.** At current scale (~10 in use databases),
-3. Database (this PCD's operations)
+forking solves shared-code needs without the complexity of dependency
-   ↓
+resolution, version conflicts, and circular dependency detection. The layer
-4. User customizations (user's operations)
+system supports adding dependencies in 2.1+ without breaking existing PCDs.
-   ↓
+We'll build dependency support when clear duplication patterns emerge and
-Result: Populated database
+forking proves insufficient.
-```