Merge pull request #32 from Entrolution/fix/spec-review-remediation

Fix 25 spec review issues across core and extensions

Author: gvonness-apolitical

schemas/academic.schema.json

@@ -92,8 +92,8 @@
     },
     "resetTrigger": {
       "type": "string",
-      "description": "When to reset counters",
-      "enum": ["chapter", "section", "none"]
+      "description": "When to reset counters. Uses heading level identifiers corresponding to the core heading block's level attribute.",
+      "enum": ["heading1", "heading2", "heading3", "heading4", "heading5", "heading6", "none"]
     },
     "theoremBlock": {
       "type": "object",

spec/core/00-introduction.md

@@ -129,7 +129,7 @@ document.cdx
     └── dublin-core.json    # Dublin Core metadata (required)
 ```
 
-### 1.5a Annotation Layers
+### 1.6 Annotation Layers
 
 Codex provides three annotation storage locations, each serving different purposes:
 
@@ -151,7 +151,7 @@ All annotation layers are **outside the content hash boundary** — adding annot
 
 **Implementation note**: Core annotations live in `security/annotations.json` because they share the security directory's "outside content hash" semantics. When migrating from core annotations to the collaboration extension, implementations SHOULD convert existing annotations to the collaboration format and remove the core annotations file. The two formats SHOULD NOT coexist in the same document to avoid confusion.
 
-### 1.6 Specification Organization
+### 1.7 Specification Organization
 
 This specification is organized into the following sections:
 
@@ -173,8 +173,9 @@ Extension specifications (optional modules) are defined separately:
 - Phantom Extension
 - Forms Extension
 - Semantic Extension
+- Legal Extension
 
-### 1.7 Versioning
+### 1.8 Versioning
 
 This specification uses semantic versioning (MAJOR.MINOR.PATCH):
 

spec/core/03-content-blocks.md

@@ -1003,6 +1003,15 @@ Example:
 }
 ```
 
+### 5.1 Extension Mark Types
+
+Extensions MAY define additional mark types for use within text nodes. Unlike block types, extension marks are NOT required to use a namespace prefix — marks operate within the text node's `marks` array where the collision risk is lower. However, extensions MAY use a namespace prefix (e.g., `legal:cite`) when the unqualified name could cause confusion with marks from other extensions.
+
+Extension marks:
+- SHOULD be documented in the extension specification
+- MUST define their field table (type, required fields, optional fields)
+- SHOULD avoid names that collide with core marks or marks from commonly-paired extensions
+
 ## 6. Internationalization
 
 ### 6.1 Text Direction and Writing Mode

spec/core/03a-anchors-and-references.md

@@ -295,6 +295,8 @@ Extensions extend the base Person type with additional fields via schema composi
 
 All Person objects MUST include at minimum the `name` field. Extensions SHOULD include the base fields alongside their extension-specific fields. The naming distinction between "author" and "signer" is intentional to reflect the semantic difference in their contexts.
 
+Extensions MAY add domain-specific identity fields to the Person object. The core `identifier` field remains available for persistent scholarly or decentralized identifiers. Extension-specific identity fields are additive — they do not replace `identifier`. For example, the collaboration extension adds `userId` for session-level identity, and the security extension adds `keyId` for cryptographic key association. A Person object MAY include both `identifier` and extension-specific fields simultaneously.
+
 ## 10. Relationship to Extensions
 
 The anchor system is defined in the core specification but is primarily consumed by extensions:
@@ -307,3 +309,16 @@ The anchor system is defined in the core specification but is primarily consumed
 | Semantic (`codex.semantic`) | Internal `semantic:ref` `target` fields use Content Anchor URI syntax |
 
 See the respective extension specifications for details.
+
+## 11. Cross-Reference Mechanism Selection
+
+Multiple mechanisms exist for cross-referencing within Codex documents. Use the following guidance:
+
+| Mechanism | Extension | Use When |
+|-----------|-----------|----------|
+| `link` mark (with `#anchor` href) | Core | General-purpose internal links; hyperlink-style references |
+| `semantic:ref` | Semantic | Scholarly cross-references (e.g., 'see Section 3', 'as shown in Figure 2') with automatic label generation |
+| `presentation:reference` | Presentation | Layout-aware references that need presentation-specific formatting or page numbers |
+| `academic:theoremRef` / `academic:equationRef` | Academic | References to theorems, equations, or other numbered academic elements |
+
+For simple internal links, use the core `link` mark. For documents requiring automatic numbering and label generation (e.g., 'Figure 3', 'Theorem 2.1'), use extension-specific reference marks. When multiple reference types apply, prefer the most semantically specific mechanism.

spec/core/05-asset-embedding.md

@@ -288,14 +288,24 @@ Embedded files are attachments that accompany the document but are not directly
 
 ### 6.3 Referencing Embedded Files
 
-Embedded files can be referenced from content:
+Embedded files can be referenced from content using a `paragraph` block with a `link` mark pointing to the embedded file:
 
 ```json
 {
-  "type": "attachment",
-  "ref": "assets/embeds/quarterly-data.xlsx",
-  "title": "Download source data",
-  "icon": "spreadsheet"
+  "type": "paragraph",
+  "children": [
+    {
+      "type": "text",
+      "value": "Download source data",
+      "marks": [
+        {
+          "type": "link",
+          "href": "assets/embeds/quarterly-data.xlsx",
+          "title": "Download source data"
+        }
+      ]
+    }
+  ]
 }
 ```
 

spec/core/06-document-hashing.md

@@ -122,9 +122,12 @@ The following table summarizes what is included in and excluded from the documen
 | Security | No | Signatures reference the hash — not part of it |
 | Timestamps | No | Administrative metadata (`created`, `modified`) |
 | Provenance | No | Lineage tracking and derivation history |
+| CRDT metadata | No | Transient synchronization state from collaboration extension |
 
 This boundary ensures that the document's identity represents its **semantic content** — what the document says — rather than how it appears or administrative metadata about it.
 
+> **Note:** CRDT metadata added by the collaboration extension (`crdt` fields on content blocks) is excluded from the content hash. CRDT data represents transient synchronization state and MUST be stripped before computing the document hash.
+
 ### 4.2 Canonical Content Structure
 
 ```json

spec/core/08-metadata.md

@@ -37,6 +37,8 @@ Location: `metadata/extended.json` (or custom paths)
 
 ### 3.1 File Format
 
+The `version` field in Dublin Core metadata refers to the Dublin Core Metadata Element Set standard version (currently 1.1), not the Codex specification version. The Codex specification version is declared in the manifest's `specVersion` field.
+
 ```json
 {
   "version": "1.1",

spec/extensions/README.md

@@ -13,20 +13,22 @@ This directory contains specifications for Codex extensions. Each extension adds
 | [Security](security/README.md) | `codex.security` | 0.1 | Draft | Digital signatures, encryption, access control |
 | [Phantoms](phantoms/README.md) | `codex.phantoms` | 0.1 | Draft | Off-page annotation clusters |
 | [Presentation](presentation/README.md) | `codex.presentation` | 0.1 | Draft | Layout templates and rendering hints |
+| [Legal](legal/README.md) | `codex.legal` | 0.1 | Draft | Legal citations, clause references, jurisdiction metadata |
 
 ## Extension Compatibility
 
 Extensions are designed to work together. The following matrix shows compatibility between extensions:
 
-| Extension | semantic | academic | forms | collaboration | security | phantoms | presentation |
-|-----------|----------|----------|-------|---------------|----------|----------|--------------|
-| semantic | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| academic | ✓ | - | △* | ✓ | ✓ | ✓ | ✓ |
-| forms | ✓ | △* | - | ✓ | ✓ | ✓ | ✓ |
-| collaboration | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
-| security | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ |
-| phantoms | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
-| presentation | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| Extension | semantic | academic | forms | collaboration | security | phantoms | presentation | legal |
+|-----------|----------|----------|-------|---------------|----------|----------|--------------|-------|
+| semantic | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| academic | ✓ | - | △* | ✓ | ✓ | ✓ | ✓ | ✓ |
+| forms | ✓ | △* | - | ✓ | ✓ | ✓ | ✓ | ✓ |
+| collaboration | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ |
+| security | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| phantoms | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ | ✓ |
+| presentation | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| legal | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
 
 **Legend:**
 - ✓ = Fully compatible
@@ -69,6 +71,7 @@ Most extensions store data in dedicated directories:
 | collaboration | `collaboration/` | `comments.json`, `changes.json` |
 | security | `security/` | `signatures.json`, `encryption.json` |
 | phantoms | `phantoms/` | `clusters.json` |
+| legal | `legal/` | `citations.json` |
 
 ### Shared Definitions
 

spec/extensions/academic/README.md

@@ -632,7 +632,7 @@ Location: `academic/numbering.json`
   "version": "0.1",
   "equations": {
     "style": "chapter.number",
-    "resetOn": "chapter"
+    "resetOn": "heading1"
   },
   "theorems": {
     "style": "chapter.section.number",
@@ -644,11 +644,11 @@ Location: `academic/numbering.json`
   },
   "algorithms": {
     "style": "number",
-    "resetOn": "chapter"
+    "resetOn": "heading1"
   },
   "exercises": {
     "style": "chapter.number",
-    "resetOn": "chapter"
+    "resetOn": "heading1"
   },
   "customVariants": {
     "axiom": {
@@ -690,10 +690,16 @@ This produces: Theorem 1, Lemma 2, Proposition 3, Theorem 4, etc.
 
 ### 10.3 Reset Triggers
 
+The `resetOn` field accepts heading level identifiers: `heading1` through `heading6`, corresponding to the core `heading` block's `level` attribute. For example, `"heading1"` resets numbering at each level-1 heading.
+
 | Reset On | Description |
 |----------|-------------|
-| `chapter` | Reset at each chapter |
-| `section` | Reset at each section |
+| `heading1` | Reset at each level-1 heading |
+| `heading2` | Reset at each level-2 heading |
+| `heading3` | Reset at each level-3 heading |
+| `heading4` | Reset at each level-4 heading |
+| `heading5` | Reset at each level-5 heading |
+| `heading6` | Reset at each level-6 heading |
 | `none` | Never reset (document-wide numbering) |
 
 ## 11. Examples

spec/extensions/collaboration/README.md

@@ -64,6 +64,8 @@ Each content block can carry CRDT metadata:
 }
 ```
 
+**Hashing:** CRDT metadata (`crdt` fields on content blocks) MUST be stripped before computing the document content hash (see Core Specification, Section 6 — Document Hashing). CRDT metadata represents transient synchronization state, not document content. Implementations MUST materialize CRDT operations to plain content before hashing.
+
 ### 3.4 Text CRDTs
 
 For rich text editing within blocks, integrate with text CRDTs:
@@ -231,7 +233,27 @@ Location: `collaboration/comments.json`
 | `resolved` | boolean | No | Whether comment is resolved |
 | `replies` | array | No | Reply comments |
 
-### 4.3a Author Object
+### 4.3a Reply Object
+
+The `replies` array contains reply objects. Replies are flat — they do not nest (a reply cannot contain further replies). Replies do not have their own anchors; they inherit the anchor context of the parent comment.
+
+```json
+{
+  "id": "c1-r1",
+  "author": { "name": "Author", "email": "author@example.com" },
+  "created": "2025-01-15T10:30:00Z",
+  "content": "Good point, I'll expand this section."
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique reply identifier |
+| `author` | object | Yes | Reply author (see Author Object below) |
+| `created` | string | Yes | ISO 8601 creation timestamp |
+| `content` | string | Yes | Reply text content |
+
+### 4.3b Author Object
 
 The `author` field uses a consistent structure throughout the collaboration extension:
 
@@ -359,7 +381,21 @@ Location: `collaboration/changes.json`
 }
 ```
 
-### 5.3 Change Types
+### 5.3 Change Record Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | Yes | Unique change identifier |
+| `type` | string | Yes | Change type (see Change Types below) |
+| `anchor` | ContentAnchor | Yes | Anchor to the affected content (see Anchors and References spec) |
+| `position` | object | No | Position for insert/move operations (e.g., `{ "after": "block-id" }`) |
+| `before` | object | No | Content state before the change (for `modify` and `delete` types) |
+| `after` | object | No | Content state after the change (for `modify` and `insert` types) |
+| `author` | object | Yes | Change author (see Author Object in section 4.3a) |
+| `timestamp` | string | Yes | ISO 8601 change timestamp |
+| `status` | string | No | Change status: `"pending"`, `"accepted"`, or `"rejected"` (default: `"pending"`) |
+
+### 5.4 Change Types
 
 | Type | Description |
 |------|-------------|
@@ -369,7 +405,7 @@ Location: `collaboration/changes.json`
 | `move` | Block moved to new position |
 | `format` | Formatting changed |
 
-### 5.4 Accepting/Rejecting Changes
+### 5.5 Accepting/Rejecting Changes
 
 Changes can be:
 - `pending` - Not yet reviewed