lime/docs/model.md

Lime model

This document is the source of truth for Lime's pure Lisp engine. The small CLX adapter translates this model to X11; it does not redefine it.

Terms

Activity

An Activity is a durable, named task container. It owns a pool of normal clients and a library of saved Views. It is not a virtual desktop and it does not intrinsically belong to one monitor or all monitors.

Examples: lime development, day job, game.

Every client has exactly one home Activity. A shared client additionally has client-shared-p set: any Activity may request it, but it still receives at most one global Lease. Sharing means availability, not sticky visibility, cloning, or an automatic placement in every draft. activity-client-ids is the home pool; activity-available-client-ids includes shared guests as well.

set-client-shared changes this eligibility without granting leases. Making a client private again removes its requests from foreign saved Views and live/cached drafts, releasing any foreign lease. Home checkpoints survive; the client is not automatically summoned home.

move-client-to-activity changes home ownership and releases the current lease. For private clients it prunes obsolete saved/cached/live references outside the destination, including layout leaves and focus preferences. For shared clients, valid saved requests survive; only the lease-holder's live placement is removed. With :target-head-id, the placement is queued in the destination's inactive working draft for that Head (preserving float geometry and existing destination layout). Without it, the client is simply parked. It never switches Heads or silently grants a lease in another active draft. All removal/focus policy is prepared on copies before committing membership.

activity-deletion-summary describes deletion without mutating the model. delete-activity accepts only an Activity with no home clients and no mounted Presentations on any Head. Hidden clients and shared clients borrowed elsewhere still count as home clients: move or close them first. Deletion never closes applications, switches Heads, or rehomes clients implicitly.

Deletion removes the Activity's Views and cached/suspended drafts, prunes their entries from Viewsets, and removes Viewsets left empty. Cached references to shared guests disappear, but the actual guests retain their homes and leases elsewhere. An optional :expected-revision protects a prior confirmation from concurrent edits; all validation precedes mutation. There is no built-in undo.

View

A View is a named, saved, single-Head checkpoint within an Activity. It contains the desired visible client placements, Head-relative layout data, and preferred focus. It is a definition, not a runtime owner of windows.

Examples within lime development: code, debug, docs.

An absent client means “this View does not request it on this Head”; it does not mean “hide it everywhere in the Activity.”

The concrete tiling representation is a binary tree of layout-leaf and layout-split nodes. A split is horizontal or vertical and stores a relative ratio. The tree contains exactly the View's :tile placements; :float placements carry Head-relative geometry separately.

A View or Presentation also records one layout policy:

• :manual renders its explicit tree. Focused-split orientation/ratio edits and slot swaps switch the live draft to this policy.
• :master-stack derives a conventional master area and equal stack from tile placement order. Its options are :master-count, :master-ratio, and master/stack :orientation; new tiled clients reflow under the same policy.
• :monocle retains the full tree and all leases, but renders only the focused tiled client at the Head's full usable rectangle. Changing focus changes the visible client without changing leases or the checkpoint.

The policy and its options are snapshot data: they are copied into a Presentation at activation and only reach a View through explicit save/update. Floating is deliberately orthogonal to these tiling policies. A float stores a complete :x, :y, :width, and :height rectangle as normalized fractions of its owning Head; it therefore adapts to Head pixel dimensions without putting X11 geometry in the model. toggle-client-floating, toggle-focused-client-floating, and set-client-floating-geometry modify only an active Presentation. Toggling a client back to tile returns it to the current tiling policy; master/stack reflows, while the manual tree inserts a new leaf. As with any live change, the rectangle reaches a View only through an explicit save/update.

Head

A Head represents one independently addressable display rectangle, normally a physical monitor. A Head has zero or one active Presentation. Its pixel rectangle is backend data: at X11 startup, RandR discovery normally derives the non-overlapping rectangles from active CRTCs; explicit rectangles remain available for nested servers and unusual arrangements. RandR change events refresh the physical-topology snapshot. A caller then explicitly reconciles the model's logical Head ids: a removed Head's live Presentation can move intact to one chosen surviving/new Head, or suspend as an unbound cached draft. No output event silently changes an Activity, View, or Lease.

Presentation

A Presentation is one Activity's current working arrangement on one Head. Together these arrangements form the Activity's live workspace across Heads. There is at most one working arrangement per (Activity, Head), whether visible or inactive. Recalling a View replaces that arrangement in place, not an extra cached workspace. Draft means no source checkpoint, not a second navigation target.

Switching away keeps the arrangement and releases its visible leases. Returning restores current locations, unsaved windows, layout and focus. Explicit moves/summons remove previous live locations, including inactive ones; a later return cannot reclaim those windows. Hiding survives returns. The low-level Head-local open-activity-draft operation creates an empty first portion; it never gathers windows from another Head. Ordinary frontend navigation adds a portable/extended policy above this operation.

A portable Activity selects one working arrangement independent of its physical Head. bring-presentation-to-head moves/resumes that arrangement; if it is displayed elsewhere, it swaps with the target Head's current arrangement. Active leases remain attached to their Presentation objects. Hidden clients stay hidden, dirty layouts stay dirty, and checkpoints are not recalled. The displaced Activity's cached portions transpose between the same two Heads, preserving its full working state rather than overwriting a cache. An inactive incoming arrangement changes only the destination's active selection.

Explicitly extending an Activity enables independent Head-local portions. This is navigation intent, not a second Activity type or a window-count rule; closing/hiding the final window on a portion never automatically folds it. The adapter persists this policy separately from the core world and can make an Activity portable again after its other portions are empty and inactive.

Only explicit checkpoint recall requests historical placements and offers strict/partial/take policies. A partial recall may expose missing slots for an explicit reclaim command, but Activity return drops those requests instead of retrying them. Saved checkpoints never change through a move or partial recall. Recalling a checkpoint on another Head detaches its older inactive source label while preserving the old arrangement's remaining windows and layout. When topology reconciliation suspends a draft from a removed Head, its head-id is temporarily absent and it holds no leases; an explicit resume can bind that draft to any current Head.

Lease

A Lease is the exclusive, runtime-only right for one active Presentation to show one real client. It is not persisted in a View.

client -> zero or one active Presentation lease

No lease means the client is parked. One lease means it is visible in that Presentation. Two leases are invalid: a real X11 window is not a clone.

Viewset

A Viewset is a deliberate whole-desk shortcut, not the default switching behavior. It is a saved mapping of Heads to Activity/View selections:

Development
  left  -> Lime development / Code
  right -> Lime development / Debug

After work
  left  -> Game / Play
  right -> Comms / Chat

Its activation uses its own preflight/plan/commit machinery, but validates all target Heads together. A Viewset saves durable Head -> View selections—it does not serialize mutable Presentations, drafts, focus overrides, or Leases. Capturing the current desk therefore requires every selected Head to be mounted from a saved View; save a View first when a Head holds an unsaved draft.

All target Heads release their outgoing leases before any incoming View is mounted. That makes a genuine swap safe:

before: left -> Code, right -> Play
after:  left -> Play, right -> Code

Neither incoming View conflicts with the other’s outgoing lease or mounted View. A client leased on an unselected Head remains an ordinary external collision, resolved explicitly as strict, partial, or take. If two target Views both request the same client, the Viewset is rejected as internally ambiguous; Lime never chooses a winner based on entry order.

Invariants

1. A client has exactly one home Activity; shared clients are eligible elsewhere.
2. Each Head has at most one active Presentation.
3. A named View has at most one active mounted Presentation.
4. A normal client has at most one Lease globally.
5. A Lease must point to an active Presentation in an eligible Activity (home, or any Activity for a shared client), containing a placement for it.
6. A saved View never changes as a side effect of a lease collision.
7. Switching one Head changes only that Head unless an explicit operation transfers a client lease, revokes sharing, or activates a named Viewset.
8. Each (Activity, Head) has at most one current working arrangement.
9. Each client has at most one current live location, even while undisplayed. Missing slots from an explicit partial recall are not live locations.
10. A source checkpoint labels only one working arrangement. Saved View definitions may still contain overlapping sets of windows.

Activation is a plan, not a UI monolith

The core deliberately separates collision detection, resolution choice, and state mutation:

preflight-view-activation
  -> Activation Report: ready / conflicts
  -> strict, partial, or take plan builder
  -> commit-activation-plan

The menu is only one consumer of the report:

Docs needs Emacs, currently leased by Left / Code

Open reduced      -> build-partial-activation-plan
Move Emacs here   -> build-taking-activation-plan
Go to Left        -> frontend focus command
Cancel            -> no plan

This lets the same semantics work from keyboard bindings, an on-screen menu, IPC, or a Lisp REPL.

Viewset activation is a grouped plan

preflight-viewset-activation
  -> Viewset Report: all selected Heads, outgoing group, conflicts
  -> strict, partial, or take Viewset plan builder
  -> commit-viewset-plan

The grouped preflight deliberately excludes leases and mounted Views held by selected Heads’ outgoing Presentations, because the single commit releases all of them first. It still checks stale world revision and every target Head’s outgoing Presentation id immediately before mutation.

Topology reconciliation is a plan too

RandR supplies the desired physical Head identifiers, but it never gets to choose task routing. The separate core sequence is:

preflight-head-topology-reconciliation
  -> Head Topology Report: retained / added / removed / live removed sources
  -> build-head-topology-reconciliation-plan with explicit source -> destination moves
  -> commit-head-topology-reconciliation-plan

An incoming move keeps the exact live Presentation, including its unsaved layout, focus, and leases. If a surviving destination already has a live Presentation, that destination becomes a normal cached draft and releases its leases before the incoming Presentation mounts. A removed source omitted from the move list becomes an unbound, lease-free cached draft instead. Added Heads with no incoming move are genuinely blank; a normal Activity or View command can mount something there later.

Collision behavior

The normal strict command makes no change if a requested client is leased by a different active Head. It does not silently use “last request wins.”

Two explicit alternatives exist:

• Partial activation mounts the View with free clients and records the contested clients as unavailable slots.
• Take activation transfers the contested leases atomically to the target Presentation. The source Presentation becomes temporarily incomplete; its saved View remains unchanged.

A newly freed client is never auto-awarded to another Presentation. An explicit reclaim command fills an available slot, avoiding windows that jump between monitors unexpectedly.

New windows and snapshots

New clients join the focused Head's active Activity and live Presentation. They do not retroactively appear in old saved Views. show-client-on-presentation changes only the live draft; update-view-from-presentation is the deliberate checkpoint update operation.

Updating a partially mounted/degraded Presentation is rejected by default so a missing contested client cannot be silently erased from a reliable checkpoint.

Backend boundary

The model knows nothing about X11, CLX, pixels, or an event loop. The backend translates a committed logical transition into batched effects:

logical plan -> unmap / configure / map / stack / focus -> X11

The backend must preserve the model's one-lease invariant and use X11 event feedback only to update client lifecycle state. A permanently destroyed client is retired from its Activity, saved Views, live/cached Presentations, and lease; it cannot leave a phantom tiling slot behind. Layout trees, floating geometry, Head work areas, RandR discovery and hotplug-migration policy, ICCCM/EWMH, and input binding policy all belong above or below this core rather than inside lease resolution.