blockworx/doc_ng/

model.rs

//! Document model — collaborative log architecture.
//!
//! Relation taxonomy (final form — see design doc):
//!   1. LEAF VALUES — `Register<T>`: value + stamp, LWW. Atomicity by the
//!      Frankenstein test: if concurrent edits to different sub-fields were
//!      both kept, is the result coherent? No → one Register over the
//!      composite (`GridRect`, `Vec<Waypoint>`). Yes → split into namespaces.
//!   2. NAMESPACES — fixed composite structure inlined into its owner
//!      (Label): a plain struct whose fields are Registers (or nested
//!      namespaces). Not entities: no ID, no lifecycle. Addressed by
//!      hierarchical target paths (`BlockTargets::Title(LabelTargets::Name)`).
//!   3. SET MEMBERSHIP — variable-cardinality containment: authored
//!      child-side (`owner` Register on the entity); parent-side sets are
//!      DERIVED (`DocumentCache`).
//!   4. VALUE-KEYED REGISTER FAMILIES — available pattern; no current
//!      instances (route labels graduated to entities).
//!
//! Register placement IS the atomicity decision: `Register<GridRect>` declares
//! an atomic composite; `title: Label` (a struct of Registers) declares a
//! namespace. The Targets enums must mirror this structure exactly — one
//! enum leaf path per Register.
//!
//! Cardinality is enforced by STRUCTURE, not by repair: "at most one" → a
//! field on the owner (Block.icon); "zero or more" → entities with owners.
//!
//! Stamps are FIRST-CLASS MERGE STATE, inline in every Register: snapshots
//! must contain them (replay resolves tail LWW against snapshot-point stamps)
//! and they must converge (snapshot==replay asserts them). The "no notion of
//! time" property belongs to the user-facing PROJECTION (KDL export, review
//! rendering), which strips stamps mechanically — not to the storage layout.
//!
//! Zero-value principle: every type's default is meaningful (`Role::Accent0`,
//! null `AssetHash`, empty rect, `Stamp::BOTTOM`, `Liveness::Deleted`). The model
//! is Option-free: absence is map-absence (entities) or stamped Liveness
//! (slots); "no value" is a meaningful zero.

use crate::doc_ng::{
    hash::AssetHash,
    id::{BlockId, CommentId, ImageId, PinId, RouteId, RouteLabelId, TextId},
    stamp::Stamp,
};
use ahash::{HashMap, HashSet};
use serde::{Deserialize, Serialize};
use std::sync::Arc;

/// The universal authored cell: current value + stamp of the write that set
/// it. `apply` is the ENTIRE merge rule and the only write path — no code can
/// update a value while forgetting its stamp, and the LWW comparison lives in
/// exactly one place. Default = (`T::default()`, BOTTOM): every register exists
/// from time 0 holding its meaningful zero, so first-write needs no special
/// case anywhere in the fold.
#[derive(Default)]
pub struct Register<T> {
    value: T,
    stamp: Stamp,
}

pub enum Applied {
    Won,
    LostToNewer,
}

impl<T> Register<T> {
    pub fn get(&self) -> &T {
        &self.value
    }
    pub fn stamp(&self) -> Stamp {
        self.stamp
    }
    /// LWW: the later (stamp, actor) wins; a losing write is reported so the
    /// fold can record `Collision::RegisterOverwrite`.
    pub fn apply(&mut self, value: T, stamp: Stamp) -> Applied {
        if stamp > self.stamp {
            self.value = value;
            self.stamp = stamp;
            Applied::Won
        } else {
            Applied::LostToNewer
        }
    }
}

// ---------------------------------------------------------------------------
// Liveness (entities and slots)
// ---------------------------------------------------------------------------

#[derive(Clone, Copy, PartialEq, Eq, Default)]
pub enum Liveness {
    Alive,
    #[default]
    Deleted,
}

/// Stamped presence + retained inner — ENTITIES ONLY (value slots like
/// Block.icon are atomic Registers whose zero value means absent).
/// `presence` is an ordinary
/// Register — delete-vs-restore is plain LWW on it. Delete-wins over edits is
/// STRUCTURAL: edit commands cannot target presence, so no edit (any stamp)
/// resurrects; losing edits apply to the retained inner, are flagged
/// (`Collision::EditOfDeleted`), and surface on Restore.
/// Default = (Deleted @ BOTTOM, `T::default()`).
#[derive(Default)]
pub struct Live<T> {
    pub presence: Register<Liveness>,
    pub inner: T,
}

// ---------------------------------------------------------------------------
// Document root (authored state only)
// ---------------------------------------------------------------------------

/// The Document is a singleton entity with one register (Name). AUTHORED
/// STATE ONLY — all derived indexes live in `DocumentCache`. This struct (with
/// its stamps) is what snapshot==replay asserts over; the KDL export is a
/// stamp-stripping projection of it.
///
/// The document is the IMPLICIT ROOT of the containment tree: not an element,
/// cannot be deleted/moved/raced. Blocks whose parent is `Id::NULL` live at
/// document level. Single-canvas presentation, if wanted, is a UI convention
/// — not a merge invariant.
pub struct Document {
    pub name: Register<String>, // DocumentTargets::Name
    pub blocks: HashMap<BlockId, Live<Block>>,
    pub pins: HashMap<PinId, Live<Pin>>,
    pub routes: HashMap<RouteId, Live<Route>>,
    pub route_labels: HashMap<RouteLabelId, Live<RouteLabel>>,
    pub texts: HashMap<TextId, Live<Text>>,
    pub comments: HashMap<CommentId, Live<Comment>>,
    pub images: HashMap<ImageId, Live<Image>>,
}

/// DERIVED — all reverse indexes, maintained incrementally by the fold and
/// fully rebuildable: `rebuild(&Document) -> DocumentCache` (the ground truth
/// the incremental maintenance is property-tested against). Never serialized
/// as authoritative state; never targeted by commands. No entries for
/// tombstoned elements. Future indexes (spatial, by-scope) belong here.
pub struct DocumentCache {
    pub top_level: HashSet<BlockId>, // blocks with parent == Id::NULL
    pub blocks: HashMap<BlockId, BlockIndex>,
    pub routes: HashMap<RouteId, RouteIndex>,
    /// Routes whose authored presence is Alive but whose EFFECTIVE liveness is
    /// dead (an endpoint pin is tombstoned) — derived, flagged
    /// (`Collision::RouteOrphanedByDelete`), auto-revived when the endpoint is
    /// Restored. Rendered as deleted. See "no dangling routes" below.
    pub suppressed: HashSet<RouteId>,
}

// ---------------------------------------------------------------------------
// Geometry (fixed-point; deterministic bytes for hashing)
// ---------------------------------------------------------------------------

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct GridPoint {
    pub x: i32,
    pub y: i32,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct GridSize {
    pub w: u32,
    pub h: u32,
}
/// Atomic wherever it appears — always behind a single Register (fails the
/// Frankenstein test: one author's position + another's size is a rect
/// neither authored).
#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct GridRect {
    pub top_left: GridPoint,
    pub size: GridSize,
}

/// An f32 stored as floor(val * 2^24).
/// NOTE: `f32 -> FracVal` on NaN saturates to 0 (Rust `as` cast). Reject NaN
/// at command construction (`debug_assert`) rather than relying on saturation.
#[derive(
    Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize,
)]
pub struct FracVal(i64);

impl From<f32> for FracVal {
    fn from(val: f32) -> FracVal {
        debug_assert!(!val.is_nan(), "NaN must not enter the document");
        Self((val as f64 * 2.0f64.powi(24)) as i64)
    }
}
impl From<FracVal> for f32 {
    fn from(val: FracVal) -> f32 {
        ((val.0 as f64) / 2.0f64.powi(24)) as f32
    }
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScreenPoint {
    pub x: FracVal,
    pub y: FracVal,
}

#[derive(Default, Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub struct ScreenSize {
    pub w: FracVal,
    pub h: FracVal,
}

/// Atomic (same reasoning as `GridRect`). Default = empty rect (meaningful zero).
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct ScreenRect {
    pub top_left: ScreenPoint,
    pub size: ScreenSize,
}

// ---------------------------------------------------------------------------
// Shared value enums
// ---------------------------------------------------------------------------

#[derive(Clone, Copy, PartialEq, Eq, Default, Debug, Serialize, Deserialize)]
pub enum LabelSide {
    #[default]
    Top,
    Center,
    Bottom,
}

/// Zero-value principle: no `Option<u8>` roles/accents. The domain is exactly
/// the 9-accent palette; Accent0 is the meaningful default ("plain").
#[derive(Clone, Copy, PartialEq, Eq, Default, Debug, Serialize, Deserialize)]
pub enum Role {
    #[default]
    Accent0,
    Accent1,
    Accent2,
    Accent3,
    Accent4,
    Accent5,
    Accent6,
    Accent7,
    Accent8,
}

#[derive(Clone, Copy, PartialEq, Eq, Default, Debug, Serialize, Deserialize)]
pub enum PinDir {
    #[default]
    Input,
    InOut,
    Output,
}

// ---------------------------------------------------------------------------
// Namespaces — inlined register groups, NOT entities
// ---------------------------------------------------------------------------

/// A namespace of four independent registers: concurrent rename + side-flip
/// are both kept, coherently. No ID — addressed through the owner's path.
#[derive(Default)]
pub struct Label {
    pub name: Register<String>,    // ...(LabelTargets::Name)
    pub side: Register<LabelSide>, // ...(LabelTargets::Side)
    pub offset: Register<FracVal>, // ...(LabelTargets::Offset)
    pub hidden: Register<bool>,    // ...(LabelTargets::Hidden)
}

/// Icon value: asset + placement, held whole in a single Register on Block.
/// Plain fields (no inner Registers) — the register boundary is the icon
/// itself. Default is the ZERO icon: null `AssetHash`, empty rect, renders as
/// nothing, means "no image".
#[derive(Serialize, Deserialize, Debug, Clone, Default)]
pub struct Icon {
    pub asset: AssetHash,
    pub rect: ScreenRect,
}

// ---------------------------------------------------------------------------
// Elements (entities)
// ---------------------------------------------------------------------------

pub struct Block {
    /// Zero-value principle: `Id::NULL` = the document itself (implicit root).
    /// Cycle repair treats NULL as the tree root; unknown non-null IDs are the
    /// dangling-ref repair case.
    pub parent: Register<BlockId>, // BlockTargets::Parent
    pub rect: Register<GridRect>, // BlockTargets::Rect (atomic)
    pub locked: Register<bool>,   // BlockTargets::Locked
    pub title: Label,             // BlockTargets::Title(..)
    pub type_label: Label,        // BlockTargets::TypeLabel(..)
    /// Atomic value slot: the WHOLE icon (asset + placement) is one register.
    /// Default = zero icon (null `AssetHash`, empty rect) = "no image", so
    /// absence is just a value: clearing = writing the zero icon, an ordinary
    /// stamped LWW write — the stamp records when it was cleared, and
    /// clear-vs-edit is plain LWW. Atomicity is required by zero-as-absence:
    /// a namespace here could resurrect half an icon.
    pub icon: Register<Icon>, // BlockTargets::Icon
}

/// DERIVED — lives in `DocumentCache`, rebuilt from child-side owner registers.
pub struct BlockIndex {
    pub pins: HashSet<PinId>,         // from Pin.owner
    pub routes: HashSet<RouteId>,     // from Route.owner
    pub texts: HashSet<TextId>,       // from Text.owner
    pub comments: HashSet<CommentId>, // from Comment.owner
    pub images: HashSet<ImageId>,     // from Image.owner
    pub children: HashSet<BlockId>,   // from Block.parent
}

/// Entity: variable cardinality per block, externally referenced (Route.from/to).
pub struct Pin {
    pub owner: Register<BlockId>, // PinTargets::Owner (membership)
    pub name: Register<String>,
    pub type_name: Register<String>, // renamed from type_label: it's a bare
    pub tag: Register<String>,       //   string, not a Label namespace
    pub tag_hidden: Register<bool>,
    pub rect: Register<GridRect>, // atomic
    pub dir: Register<PinDir>,
    pub pin_accent: Register<Role>,
    pub port_accent: Register<Role>,
    pub port_pin_accent: Register<Role>,
    pub flip_lr: Register<bool>,
}

/// Waypoint lock lives inside the atomic waypoints value: a polyline (with
/// its locks) is one author's coherent intent — one register, whole-value LWW.
#[derive(Clone, Copy, PartialEq, Eq, Default, Debug, Serialize, Deserialize)]
pub struct Waypoint {
    pub pos: GridPoint,
    pub locked: bool,
}

pub struct Route {
    pub owner: Register<BlockId>, // RouteTargets::Owner (membership)
    pub name: Register<String>,   // RouteTargets::Name
    pub from: PinId,              // RouteTargets::From
    pub to: PinId,                // RouteTargets::To
    pub role: Register<Role>,     // RouteTargets::Role
    pub waypoints: Register<Vec<Waypoint>>, // RouteTargets::Waypoints (atomic)
}

/// DERIVED — lives in `DocumentCache`, rebuilt from `RouteLabel.owner`.
pub struct RouteIndex {
    pub labels: HashSet<RouteLabelId>,
}

/// Entity: a label placed along a route. Graduated from a value-keyed register
/// family because entries are expected to grow properties.
pub struct RouteLabel {
    pub owner: Register<RouteId>, // RouteLabelTargets::Owner (membership)
    pub pos: Register<FracVal>,   // RouteLabelTargets::Pos (offset along route)
}

pub struct Text {
    pub owner: Register<BlockId>, // TextTargets::Owner (membership)
    pub text: Register<String>,   // TextTargets::Text (atomic string)
    pub pos: Register<GridPoint>, // TextTargets::Pos
    pub role: Register<Role>,     // TextTargets::Role
}

pub struct Comment {
    pub owner: Register<BlockId>, // CommentTargets::Owner (membership)
    pub rect: Register<GridRect>, // CommentTargets::Rect (atomic)
    pub role: Register<Role>,     // CommentTargets::Role
    pub title: Label,             // CommentTargets::Title(..)
}

/// Entity: free-floating placed image (block icons are the atomic Icon value).
pub struct Image {
    pub owner: Register<BlockId>,   // ImageTargets::Owner (membership)
    pub asset: Register<AssetHash>, // ImageTargets::Asset
    pub rect: Register<ScreenRect>, // ImageTargets::Rect (atomic)
}

pub enum Asset {
    Svg(Arc<[u8]>), // Arc: crosses the sync thread boundary
    Png(Arc<[u8]>),
}

// ---------------------------------------------------------------------------
// Design decisions (all resolved)
// ---------------------------------------------------------------------------
// STAMPS INLINE, NOT SIDECAR: a (ElementId, TargetPath)-keyed sidecar is a
// parallel structure whose keys must mirror every struct field — the
// two-homes pattern in infrastructure form. Stamps are first-class merge
// state (snapshots need them; they must converge), so they live in the
// Register. "Clock-free" is a property of the export projection, not storage.
//
// EDIT-VS-DELETE: delete wins, structurally — edits cannot target presence.
// Losing edits land in retained inner, flagged, surface on Restore. The only
// presence arbitration is delete-vs-restore: plain LWW on Live.presence.
//
// NO DANGLING ROUTES (a route exists only between live endpoints):
//   - SEQUENTIAL (bundled cascade): deleting a block records concrete Delete
//     commands in the same Change for its pins, every route terminating on
//     those pins (including routes owned by OTHER blocks/scopes — deletion is
//     inherently boundary-crossing; see ECO/lease design), those routes'
//     labels, and the owned subtree recursively. The Change is the undo unit.
//     Commit-time closure check (debug): no command in a delete batch leaves
//     a reference dangling within the batch's own view.
//   - CONCURRENT (repair by suppression): merges can compose a live route
//     with a tombstoned endpoint; the fold derives effective_liveness =
//     authored_presence && endpoints_live (DocumentCache::suppressed), flags
//     it, and never authors state (no synthesized stamps). Restore of the
//     endpoint automatically revives suppressed routes.
//
// ABSENCE: entities = map-absence (structural; unforgeable IDs mean nothing
// races a nonexistent entity). Value slots = atomic Register<T> whose ZERO
// value means absent (Block.icon): clearing is a stamped write of the zero,
// so "when was it cleared" is the register stamp and clear-vs-edit is plain
// LWW. The model is Option-free; every zero is meaningful.
//
// MERGE-COHERENCE OF BATCHED RESTRUCTURES: all commands in a Change share its
// stamp, so competing bulk operations (e.g. two users each wrapping top-level
// content in a new scope) resolve UNIFORMLY — one side wins every contested
// register; no torn trees. Divergent wrapper scopes do not coalesce
// (independent creations are independent intents); the loser's empty scope is
// a post-merge lint entry alongside spatial overlap.