ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Annotation contract — per-node sticky notes with @-mention support

Defines AnnotationState, MentionRecord, AnnotationStore and the conflict-resolution constants for graph sticky notes. LWW per field; edit-wins within 60 s of soft-delete; 5-min soft-delete TTL; mentions are append-only.

field.key.label
Annotation contract — per-node sticky notes with @-mention support
field.version.label
field.type.label
field.title.label
Annotation contract — per-node sticky notes with @-mention support
field.description.label

Defines AnnotationState, MentionRecord, AnnotationStore and the conflict-resolution constants for graph sticky notes. LWW per field; edit-wins within 60 s of soft-delete; 5-min soft-delete TTL; mentions are append-only.

field.tags.label
graph,annotation,mention,conflict,lww,m3
field.owners.label
field.stability.label
public

Per-node sticky notes with @-mention support.

Conflict policy

| Rule | Value | |---|---| | Last-write-wins per field | Yes — fields are independent | | Edit-wins window after delete | 60 s | | Soft-delete TTL | 300 s | | Mentions | Append-only |

AnnotationState fields

| Field | Mutable | Description | |---|---|---| | `id` | No | Unique annotation id | | `targetId` | No | Node/edge this is pinned to | | `authorId` | No | Creator user id | | `createdAt` | No | ISO 8601 creation timestamp | | `title` | Yes (LWW) | Short label | | `color` | Yes (LWW) | Hex background color | | `resolved` | Yes (LWW) | Resolved flag | | `body` | Yes (LWW) | Markdown body with @-mentions | | `deletedAt` | Yes (soft-delete) | ISO 8601 or null | | `mentions` | Append-only | @-mention records |