# `observer` — the dynamic document observer A standing document is watched by an observer. Modules are admitted to the observer **while the program is running**; when the document changes every active module is told, and may answer, converse with other modules, or **propose** an edit. The observer is the only writer of the document. ## Classes | Class | Role | |---|---| | `SLObserverDocument` | The standing document: up to 64 lines, a revision that moves by exactly 1 per accepted edit. Refused edits change nothing. | | `SLObserverMessage` | The one envelope: NOTE, QUESTION, ANSWER, PROPOSE, FAULT, CHANGE. | | `SLObserverPort` | A module's bounded mailbox (16 in, 8 out per cycle). | | `SLDocumentObserver` | The hub. Nested built-in module `SLDocumentObserver.Auditor`. | | `SLObserverSummaryModule` | Drop-in; nested `Responder` tracks revision and edit mix, answers `summary?`. | | `SLObserverGuardModule` | Drop-in; nested `Responder` proposes redacting a forbidden line. | | `SLObserverReviewModule` | Drop-in; nested `Responder` opens a conversation with the auditor. | | `SLObserverView` | The modest GUI: a retained widget tree (labels, entry, buttons) with take-the-latch button presses. | | `observer-demo` | Self-checking scenario (88 checks). | | `observer-gui-demo` | Scripted presses through the view. | ``` sleela run lib/observer/observer-demo.sleela sleela run lib/observer/observer-gui-demo.sleela ``` ## Dropping a module in A module is a nested class holding an `SLObserverPort`: ``` SLObserverSummaryModule.Responder m = new SLObserverSummaryModule.Responder(); m.attach("summary"); observer.admit(m.portOf()); // at any time between cycles ``` then the host cycle pumps it: ``` observer.edit(0, line, "text", "host"); // delivers a CHANGE to every active port while (observer.beginCycle()) { m.pump(); // each module reads its inbox, writes its outbox observer.endCycle(); // the observer routes what was said } ``` ### Honest limit: what "while running" means SLeeLa links classes when a program starts; there is no run-time class loader in the VM. What is dynamic here is **admission**: new module instances (of nested classes already linked) join and leave a live observer at any time, with no restart and no change to the others. Linking a module whose source did not exist at start would need a host that restarts or re-links the program. The language also does not accept a subclass where its base is expected (`extends` does not widen types), so there is no shared `Responder` interface. Instead each module exposes `portOf()` and `pump()`, and the host's cycle calls `pump()` on the modules it holds. ## Listener lifecycle | Operation | Method | Effect | |---|---|---| | add | `admit(port)` | Joins the roster; told the revision it joined at. | | pause | `pause(name)` | Active only. Changes are counted as *missed* instead of queued; pending mail is discarded. | | resume | `resume(name)` | Paused only. The listener is told how many changes it missed so it can resynchronise. | | alter | `alter(name, ins, rep, del, first, last)` | Choose which edit ops (1/0) and which line range (`-1,-1` = all) the listener wants. Unwanted changes are counted as *filtered*. Works while paused. A deaf filter, bad flag or bad range is refused. | | replace | `replace(name, freshPort)` | Hot-swap: a fresh port with the same name takes the slot; the old port is retired. The roster does not grow. | | reinstate | `reinstate(name)` | Host decision: a quarantined listener returns with its faults cleared. | | delete | `retire(name)` | Final. A retired listener cannot be paused, resumed, altered, replaced or reinstated, and its name stays reserved. | All of these are refused mid-cycle and for unknown names, are audited, and touch only the one named listener. Document edits and the other listeners carry on unchanged. `SLObserverView` shows the paused state in the roster. ## Freeze (the system lock) `freeze()` makes the observer refuse `edit()` and module proposals (declined with "the document is frozen") until `thaw()`. Listeners keep listening; only writing stops. `editAdmin(...)` is the override for a host that holds the key: the same edit, audited as an override, and the freeze stays in place. The document GUI's system lock (`lib/guidoc`) uses this so the lock holds against every writer. ## Safety envelope (all enforced by the observer) | Rule | Limit | |---|---| | Modules never write the document; they **propose** | applied only if based on the current revision (optimistic concurrency) | | Proposals per cycle | 2 | | Proposal depth per host edit | 3 (a stubborn module cannot loop forever) | | Conversation hops | 4 (the next message is dropped and audited) | | Cycles per host edit | 16 (leftover mail is discarded and audited) | | Faults | 3 reported faults or outbox overflows quarantine a module; the rest carry on | | Sender | stamped by the observer; a module cannot impersonate another | | Admission | refused mid-cycle, when full (14), for empty/reserved/duplicate names, or non-fresh ports | | Edits | out-of-range, unknown op, or null text are refused with no change | | Audit | every admit/edit/decline/drop/quarantine goes to a bounded trail (64) | ## Conversation A module answers a QUESTION with `port.reply(...)`; `observer` is told of declined or accepted proposals through an ANSWER whose `extra` is `"declined"` or `"accepted"`. `SLObserverReviewModule` shows a chain (question, answer, follow-up) that the hop limit finally ends. ## Authoring notes `route` is a reserved word in SLeeLa (it is a contextual built-in), so the observer's routing method is `deliverMessage`. `SLGuiDom`/`SLGuiApp` do not link under the current binary (pre-existing: `SLGuiEventType` statics and an `SLTheme` ambiguity between `ui` and `user-interface`), so the view is self-contained rather than built on them. See also `lib/hotlink/HOTLINK.md`: the hot-link matrix (XML Schema) and the linker that gates which module types may be admitted and connected.