System reference · spine

Glossary

The canonical domain vocabulary — generated from source, never hand-edited.

generated from CONTEXT.md f1fe5b51bf80346 terms

Naming

SimOps (public brand) vs SimOops (internal codename)
Decided 2026-07-07 (marketing-site grill): the product's public-facing name is SimOps — one "o", matching the sim-ops.io domain — used in all marketing copy, the app UI wordmark, docs prose, and customer-facing documents. SimOops (double "o") is the internal codename only: the repo, package names (@simoops/*), database names, container names. Never mix the two in one audience: customer-facing text always says SimOps; code and infra identifiers stay simoops. _Avoid_: "SimOops" in any public copy; renaming code identifiers to match the brand.

Spatial / map entities

Primitive entity kinds
The three first-class on-map entity primitives in the model today, distinguished by their geometry shape and lifecycle:
Auxiliary pin
A *display-axis* classification, distinct from the storage-axis "auxiliary point primitive" above. An auxiliary pin is an on-map entity whose UX shape is: pointlike geometry, rendered as an icon pin (not text), opened via click→properties-panel (read-only data + per-kind workflow actions), with the edit modal reached via the panel's Edit button or E key. Auxiliary pins are not members of SpatialEntityCollection (no multi-select participation) but do participate in SelectionService via a single selectedPin$ : {kind, data} | null slot, mutually exclusive with the entire spatial axis — both the Multi-selection's primary and its multiSelection map. Selecting a pin clears any worker / plant / area / road selection (single or multi); selecting any spatial entity clears the pin. Modifier-key clicks on a pin are silently treated as plain-click (the pin axis doesn't support add/toggle since pins are solo by construction).
Position provenance
How a Auxiliary pin's point was obtained — recorded only on the field-capturable pins (Observation, Incident, Blocker and Snag — all WorkGroup-backed, mixing GeolocatedPin). Four sources (PositionSource): manual (a person placed or dragged the pin on the map), device_gps (the capturing phone's geolocation fix), photo_exif (GPS tags read from an attached photo), and inferred (no fix was available so the system placed the pin — the site-centroid fallback on the anonymous QR form; to be repositioned at triage). Carried with an optional accuracy radius in metres. The coordinator-placed pins (delivery / alert / poi) have no provenance — they are always, implicitly, manual. _Avoid_: source (overloaded), origin; geotag (the act of tagging, not the recorded property).
Inferred location
A Position provenance of inferred: no fix was available, so the system placed the pin — the site-centroid fallback on the anonymous QR capture form. It marks a position nobody chose; triage repositions it (see Observation triage). Surfaced as *Placed at site centre · nobody chose this location* on the panel's Location row, carrying the Position rectification verb, and as a Site centre tell in list rows — it always counts as a Rough position (amended 2026-09-09, map #3779). _Avoid_: using this word for a GPS/EXIF point — that is a Sensed location.
Sensed location
A Position provenance of device_gps or photo_exif: the point came from a sensor rather than being deliberately placed, so it is approximate and carries an accuracy radius. It is surfaced to users *as* approximate — a "Approximate · ±N m / from device GPS" Location row on the properties panel of both pin kinds (an escalated incident's reads *from the observation's device GPS*), a subtle radius ring on the map, and — above the Rough position band — a nudge on the capture card and a ±N m tell in list rows. Manually correcting a sensed pin (drag, edit or Position rectification) reverts its provenance to manual and clears the radius; the original fix survives only on the pin's position-update timeline event, rendered as a history line in the panel's audit section (amended 2026-09-09, map #3779). _Avoid_: estimated, fuzzy, guessed; "GPS pin" (conflates the source with the pin); inferred (the enum's name for the system-placed fallback above).
Position rectification
The deliberate correction of a pin whose point nobody chose — a Sensed location or an Inferred location — after capture, ending in the manual provenance with the radius cleared. Three doors, one rule: the desktop Set exact location verb on the panel's Location row (observation and incident; arm-then-click place mode; drag remains the power-user path), the mobile Adjust location door on the quick-capture and geofence done screens (the reporter's own just-sent pending row only), and the also move the incident one-tap prompt offered when an escalated observation is rectified while the two pins still coincide (one request, incident can_edit, review block absolute, lock ignored). Authority is the kind's can_edit unchanged; a locked row says *Unlock to move*; a reviewed incident hides the verb. Never a new provenance value — the correction is a history fact on the position_updated event. Decided 2026-09-09 (map #3779); ADR 2026-06-10-inferred-location-provenance D6 amendment. _Avoid_: "move pin" (a universal verb declined by name — the verb sits beside the words that explain why the pin needs it); relocate (the report/locate handoff); rectified as a provenance value.
Rough position
A pin position the platform does not trust to be where the reporter stood: a Sensed location whose accuracy radius exceeds ACCURACY_CEILING_M (100 m — the same ceiling the nearby-work ranker draws; provisional pending #3785), or any Inferred location. One constant, two tells that can never disagree about a row: the reporter's capture-card nudge (*Location is rough (±N m)* with *Set on map* promoted and a bounded *Try again*; above 1 km the phone's approximate-location setting is named and the retry is dropped — soft, never a gate) and HSE's list tell (±N m / Site centre, muted text with a pin glyph in the row's indicator cluster, never a pill, no noticeboard item, no notification). Derived from the live provenance pair, so Position rectification clears it at once. Decided 2026-09-09 (map #3779). _Avoid_: inaccurate (the radius is honest — the point is uncertain, not wrong); approximate unqualified (every sensed point is approximate; rough is the band above the ceiling).
Multi-selection
A set of zero-or-more SpatialEntitys the user has explicitly grouped for *bulk operations* (delete, hide, lock, move-to-floor, reassign-contractor). Membership is kind-agnostic by design — worker, plant, area, road can mix freely. Auxiliary pins are deliberately excluded (see "Auxiliary pin" above and ADR 2026-05-21-auxiliary-pin-interaction-model.md D5); their interaction model is click→panel→workflow-actions, not bulk ops. Selecting a pin (any modifier) wipes the multi-selection — the spatial axis and the pin axis are full-mutex in both directions.
Bulk-action strip
The UI affordance that takes over the side panel when the multi-selection contains entities of more than one kind. Lists the bulk operations that apply across the mixed set (delete, hide, lock, move-to-floor, reassign-contractor) and nothing else — no per-entity properties. To edit an individual entity, single-click it out of the strip.
Disambiguation picker
A small popover that appears when a click lands on a stack of overlapping entities (>1 hit at the click point). Lets the user pick which one(s) to act on instead of guessing layer order.
Floor focus
A focused building floor acts as a selection lens: while it is active, every spatial gesture (single-click, box, lasso, Disambiguation picker, right-click, drag) and every attribute-based selection tool (by type, by contractor, by query) acts only on entities on the focused floor. With no floor focused, the site default applies — ground-level entities are selectable, upper floors are not shown. An entity counts as on the focused floor if it shares that floor in the same building *or* sits at the same physical elevation in a neighbouring building. Travelling *to* an off-floor entity happens off the map: selecting it from the Site member roster list, Site browser, or search focuses its floor and flies to it. Those non-spatial paths are deliberately exempt from the lens.
Off-floor hint
An on-map entity rendered dimmed because it sits on a building floor other than the one in Floor focus. It exists purely as a spatial cue — "something is over here on another floor" — and is fully inert: not hoverable, clickable, draggable, selectable, or reachable through the Disambiguation picker. To act on it you navigate to its floor (or reach it from the roster/search). Spans worker, plant, and ActiveArea; Auxiliary pins carry no floor and are never hints. Decided 2026-05-28 (grill session). _Avoid_: ghost (overloaded — the audit overlay renders "ghosts"), faded token (worker-specific; the concept is kind-agnostic), dimmed entity (names the rendering, not the inert-ness).
Noticeboard
The dock panel of live operational items grouped by kind — Alerts, deliveries, the permit-coverage advisory, and Clashes (split "relevant" vs "other" by the viewer's vantage). The operations board — distinct from the Health & Safety panel.
Health & Safety panel
The dock citizen hosting the site's H&S records — Observations, Incidents, Inspections, Actions and HSE register sections — opened with H. It presents full screen: H lands on a launcher grid of register tiles, each drilling in to its section at width. Distinct from the Noticeboard. Note the asymmetry: the *Incidents section* is one of five — the panel as a whole is Health & Safety, not "incidents".
Work home
The dock citizen for the Work domain's *scheduled work over place and time* (W, rail beside the map). It is one surface, the Plan Gantt, with plan and reality *layers* and no tabs (amended 2026-10-30, map #3954, ADR 2026-10-30-every-activity-is-a-work-line.md): the Plan and Reality tabs, the Board, the Graph and the Programme grid retired into it. Q opens it on the reality-only layer (planner_view). The map door's Changes here view borrows the rail as a transient body that replaces the Gantt. The all-roles Expand affordance opens the same Gantt at full width with the map hidden. The rail defaults to about half the screen. Decided 2026-08-12 (wayfinder map #2379, docs/decisions/2026-08-12-dock-domain-homes.md). _Avoid_: Work plan panel, Plan tab, Reality tab (all retired into the Plan Gantt); Analysis (the dissolved suite that held Reality and Region evolution); Region-evolution tab (retired).
Commercial home
The dock citizen for the Commercial domain's records (I, the second full-screen big-surface citizen beside the Health & Safety panel): a launcher grid of five tiles — Evidence (Evidence packs), Completions, Defects, Inventory, Lost time. The Lost time tile is a *resolving door*: membership picks the site-wide ledger or the own-firm position view (header always carries a "Your firm" / "Site-wide" scope label). Named plain Commercial — homes name domains, not roles; the button is entity.view-visible by design. Decided 2026-08-12 (wayfinder map #2379). _Avoid_: QS home / Commercial-QS (role-named), Analysis (the dissolved suite that held Evidence and Lost time).
Map aid
A data wash a surface paints on the map — the lost-time choropleth, the stock heat map, the INV-R24 scope wash. Aids persist after their surface closes (one lifetime rule, no per-aid exceptions): a labelled dismiss chip rides the map; ✕ clears the aid, the chip body reopens the owning surface unscoped, and clicking a painted place reopens it *scoped to that place*. Single occupancy — activating an aid replaces whatever persisted, so the place-click owner is always unambiguous. Per-site data; a site switch clears it. Decided 2026-08-12 (docs/decisions/2026-08-12-map-aid-handoff.md). _Avoid_: overlay (the map's layer vocabulary), aid clearing on surface close (the pre-#2400 contract this replaces).
Docked mode
The lost-time drill-in's second presentation: a standard left rail panel beside a live map, entered by "Dock to map" on the fullscreen drill-in header and left by "Expand" back (the Work-plan workspace's Expand pair in reverse). Drill-in state — scope arm, filters, feed-row ↔ place brushing — carries across the swap; Escape closes it like any rail panel. Not a dock citizen: no button, no keybind, reachable only through the Commercial home's Lost time section. Decided 2026-08-12 (docs/decisions/2026-08-12-map-aid-handoff.md). _Avoid_: split mode / half-screen (a third presentation class this decision declined to mint).
Site browser
The dock panel that lists the site's on-map objects grouped by kind — as a *non-spatial* way to find a thing and travel to it — covering both the selectable primitives (Workers, Plant, ActiveAreas, roads, PointOfInterests) and the Reference features building and zone under their own groups (ordered buildings → zones → roads, most- to least-prominent substrate). Together with the Site member roster and search, it is one of the off-map navigation paths deliberately exempt from the floor-focus selection *lens*.
Association snapshot
A one-shot read of the current multiSelection, used to pre-populate a domain modal that associates entities with a parent — incidents (involved_entities) and Smart Groups today. Entities outside the domain's accepted kinds (e.g. road for incidents) are filtered out and surfaced as a "skipped: N" hint, not silently dropped.
Variant
A value on a primitive's variant enum (e.g. PlantType.crane, FeatureType.work_area). Variants influence rendering, clash semantics, and creation-flow rules, but share the primitive's table/geometry shape.
Phase
A cross-cutting classification applied *across* primitives — values are construction | commissioning | handover. Decided 2026-05-19 (grill session): phase is derived from the variant by default, with an explicit nullable override when the variant doesn't determine phase uniquely. The mapping variant → default_phase is the single source of truth; the override exists for genuine independence cases (a WorkerType.construction worker doing handover snagging; a crane reused across phases).
Group
Two existing concepts that the codebase already names "group":
MAP_ENTITY_REGISTRY
A frontend TS const (no backend counterpart) keyed by MapEntityKind, holding per-kind hooks for the *behaviour* axis of on-map entities: drag, lock, hide, position update, floor-aware drop, drag-eligibility under workflow status. Membership is the union of every on-map kind that participates in those behaviours: worker | plant | road | area | poi | delivery | alert | incident | observation | blocker | textlabel. Each entry exposes getSelectedEntity(selection), getLocked(entity), canDrag(entity), toggleLock(entity), toggleHide(entity), updatePosition(entity, lonLat), plus per-kind constants (defaultLocked, floorAware).
Variant metadata
Per-primitive registries hold variant behaviour and identity. The existing FEATURE_TYPE_REGISTRY is the shape to follow. WORKER_TYPE_REGISTRY exists backend and frontend; PLANT_TYPE_REGISTRY exists frontend-only so far (the frontend registry file records this). Each per-primitive *TypeSpec carries the fields meaningful to that primitive (e.g. requires_levels on FeatureTypeSpec; WorkerTypeSpec today carries only its variant).
Token fields
The kind-agnostic half of a placed Token's form: the seven things any token says about itself whatever its kind — its name, its Contractor, the Permit it is placed under (with the inline quick request at creation), the Work line it sits on, the open Snags it resolves, its floor, and a free comment. One component renders them in that order for every host (the worker, plant and area creation modals, the entity edit modal and — decided 2026-09-22, ADR 2026-09-22-roving-crew.md — the Roving crew creation modal, which mounts six of the seven with the floor off); a host declares which of the seven it mounts (worker and plant creation both mount the floor, the Roof among its buttons — roofs spec P3; the edit modal offers no quick request) and never reorders them. Everything kind-specific — Variant, radii, lock, the audit strip — belongs to the host, around the block. The token's time is not host matter either: it is the Token window, mounted beside the block. Decided 2026-09-21 (grill session): in the block's value null is a real answer ("no contractor") and undefined only ever means the host did not mount that field; the empty-string dialect the pickers speak stays inside the block. _Avoid_: identity fields (presence, clash-rule and relation *identity* are three other things), placement fields (a Placement is a Handbook block), particulars (the HSE Schedule 1 word), card (a rendered surface).
Token window
The time half of a placed Token's form, mounted beside the Token fields block: *when* the token is on site — a single window on the day it is placed (all day, a shift, or custom hours) or a recurring Schedule group's occurrences and the end date they run to. One component owns the time mode and the single mode a toggle back restores, the shift and hours, the schedule and its end date, the Permit's schedule applied from the block's offer (spec T4), and the work window a co-created permit would take. The block *offers* a picked permit's schedule; the window *applies* it — the offer lands in the window directly, never through the host. What it shows and where an applied permit lands is one input — the kind of form it sits in, not a fork: - placement (plant, area): no date field, so a single window lands on the placement's day, and an applied permit whose own day is another — an overnight permit that began the evening before — is written as a one-occurrence schedule on its own night; - dated (worker, Roving crew): the window renders and owns the date field (hidden in schedule mode, held where a permit opened the placement), so an applied permit moves the day to the permit's own instead; - edit (an existing token): "This date only" or a schedule it converts to, starting from its own window (one occurrence on its day and shift); a permit lands on the token's own start day — the day its save re-anchors on — and the custom slider's absolute minutes ride along; a token of a Schedule group shows only the group's occurrence editor, and a permit replaces its occurrences and nothing else. A token whose window runs longer than one day on the site's wall clock — longer than one time of day can hold: a night shift over midnight still fits, 07:00 Monday to 17:00 Tuesday does not — is shown and edited as its range instead: start date and time, end date and time, on the site's clock, with no shift picker, all-day or convert toggle. A touched range saves exactly as entered (no re-anchoring), an end not after the start (or a cleared bound) is refused inline with Save disabled — and by the save itself, so the Enter key cannot send it either — and an applied permit replaces the range with the permit's own window. An untouched window — range or single — is never sent. Each opening of the host modal starts the window afresh — the modal stays mounted between tokens, and the last token's applied end date or remembered mode is not the next one's. All five token modals mount it (#4059, #4065). _Avoid_: time editor (the toggle inside it), schedule (one of its two modes), Active period (what a saved window becomes on the token).
Token creation host
What the worker, plant, area and Roving crew creation modals share as behaviour, written once (components/token-creation-host.ts, #4146): learning its visibility from the modal's token, seeding a fresh form from its context on each opening (the shared keys, the kind's declared defaults, the firms the viewer may assign — none where the kind's firm may be cleared, the first otherwise — and a Work line's seed), validity and the contractor badge from the kind's token-form declaration, Enter and Escape, cancel, and the submit answer — create, one spelling for every kind, whatever gesture opened the modal (TokenCreationAnswer, types/modal-answers.types.ts), given once per opening on the token the modal names in its spec. Each modal keeps its presentation — template, copy, test ids, which Token fields it mounts — and its kind's own behaviour, visibly (the plant's auto-generated name, the area's floor and building, the crew's size, the worker's Schedule-fix snag). Its Token window kind decides where the day lives: on the form (dated) or beside it (placement). _Avoid_: creation shell (it renders nothing), base modal (BaseModalComponent is another thing).
Create commit route
The door a confirmed creation form commits through, chosen from the form alone for every kind that mounts the Token fields and Token window — the worker and plant drops, the area draw and the Roving crew: intake — the inline quick request co-creates the entity and a brand-new Permit in one transaction; schedule — the occurrences become a Schedule group; or single — one create. A quick request counts only once it names a control category, and it wins over a schedule: the intake carries the schedule's whole occurrence group under the one permit, for every kind alike (a crew's since #4182), so only a schedule with no request takes the schedule door. The route also answers the window an intake co-create carries: a schedule's occurrence envelope, nothing for an all-day placement (the backend windows the permit), or the form's resolved one-off window. What a kind does once it is through the door — its payload, its store, its share of the commit tail — stays with the kind; through the schedule door every kind takes the one schedule create, ScheduleOrchestrationService.createSchedule(kind, …). A delivery mounts neither block and has no schedule, so it does not ask the route: its two create doors (the edit modal's save and the map drop) each choose between the intake and one create themselves. services/create-commit-route.ts (#4147). _Avoid_: commit tail (what runs after the create settles), placement (a Placement is a Handbook block).
Roving crew
A gang that moves about the site with no fixed place — an ad-hoc repair gang, a road-maintenance crew, a traffic-marshal pool, a snagging crew — recorded with everything a Token says about itself except a position: the Token fields (name, Contractor, Permit, Work line, comment), a trade Variant (maintenance · logistics · cleaning · security · supervision · snagging · other; no trade derives a Phase — a crew is phase-agnostic, as a road is, and the phase filter passes every crew), an optional crew size that imputes one, and the same Active period and Schedule group as a worker. It is its own kind, not a placeless worker and not a whole-site area: the first kind that is *schedulable but not spatial* — it is never placed, so it has no radius, no floor, no building and no lock, and it is created without a map click. Decided 2026-09-22 (grill session, map #3880). Not clashable — decided 2026-09-22 (grill session, map #3880): it never enters the clash engine (no adapter, no entity_type; its LINKABLE row is clashable=False, the delivery shape), so it is *not* a Token in the engine sense and the word *clashable* keeps its meaning. Its safety signal is its coverage state (unpermitted / pending / covered / lapsed, per the Permit coverage policy) plus the activation-gap alarm (alarm_stampable=True), both window-only questions, and a *Roving* row in the daily report's personnel table — never a scene. Where it shows is ruled separately on that map. Created and kept like a worker — decided 2026-09-22 (grill session, map #3880): it is created from the Add menu or from a permit's tray, never by a map click or from the phone, and is scheduled, linked to a permit, edited, undone, imported and exported exactly as a worker is, with the geometry left off — its record carries no position field at all, not an empty one. Counted like a worker, never placed — decided 2026-09-22 (grill session, map #3880): it sits on the day axis (ANCHOR_KINDS), so a day of its work closes out through a Completion record and it attaches to a Work line — it counts among a line's live, future, attached and completed tokens but never makes the line *placed work*, because that flag is the map's question; in the permit board's headcount but never its clash badge; a body ref (not a carrier) in the Lost time gang derivation, its crew size imputing one and bearing no place key; absent from the Site diary, which reads no headcount of any kind, and from every area-scoped report section, where a crew belongs to no area. An H&S party like a worker — decided 2026-09-22 (grill session, map #3880): a fifth involved kind on an Incident or Observation (the role vocabulary unchanged, the record showing its label and trade glyph with no locate handoff, never a person); an eighth Blocker ref kind that is basis-tier by the ordinary kind × ownership law — it carries presence (its whole window, no location), clamps the window, counts its crew size and keys no place; and a fourth kind in the work-candidates universe every phone-side tagging sheet reads — listed under *mine*, never *near you*, since proximity never adds a candidate and a crew has nothing to measure from. The pin-ring suggestions stay blind to it by construction. _Avoid_: site-wide crew (reads as a scope, and collides with the Blocker's whole-site scope), floating team (*team* means Contractor), gang (the lost-time count word for the bodies behind a token), bare crew (the bodies, not the record — see crew-hours under Lost time).
Interaction mode
What a click on the map does *right now* — the single active modal behaviour, one of: idle (normal selection), creating a primitive (worker / plant / area / road), placing an Auxiliary pin (delivery / poi / alert / incident / text), measuring, positioning a floor plan, or picking an analysis anchor. Exactly one is active at a time; the modes are mutually exclusive by convention, not by an enforcing owner. Decided 2026-05-29 (grill session): the mode is a *derived aggregate* — computed from the several services and component inputs that each own one mode, surfaced as one value under a fixed precedence — not a single owned state. The "in some placement/creation mode" predicate the map's cursor and click-short-circuit logic keys off derives from it. See docs/decisions/2026-05-29-map-event-wiring-host-decomposition.md. _Avoid_: creation mode (only one variant of it), placement mode (overloaded — names both the aggregate and the auxiliary-pin subset).
Geometry authoring
The one place a shape gets edited and committed, whatever kind wears it — a reference feature's whole-building polygon, one building level's footprint, a site Area's MultiPolygon, a road's vertex list. Those kinds persist through different endpoints into different local stores, but the *gesture* is one gesture: a shape is drawn, dragged, reshaped, cut or reverted, and something has to decide where the resulting ring lands, what undo step it earns, and which store learns about it. That decision has one owner, GeometryAuthoringService (ui/src/app/services/geometry-authoring.service.ts) — layer/feature CRUD, hole cutting (targeted and freeform), the active-feature lock, and the single subscriber to VertexEditService.results$ whose router fans to all three kinds. Decided 2026-08-25 (grill session, #3364): authoring is a *different question* from selection — *which* thing is selected, which FeatureSelectionService owns. The two meet at exactly two one-way points: the selection tells authoring which feature the cut candidates are now about (refreshPendingCutsFor), and authoring *reads* the current selection through SELECTED_ACTIVE_FEATURE rather than taking the selection service as a dep. Nothing flows back. _Avoid_: "reference-feature geometry" (the router is not reference-feature-only — naming it for one kind splits it across two modules), "feature editing" (overloaded — a feature's *attributes* are edited in a modal, which is a different gesture).
Shape write
One write of a stored shape (an active area's or reference feature's geometry), owned by backend/app/services/entity/geometry_revision.py: refuse an arm it cannot honour (422 geometry_revision_unarmable), lock the row(s) FOR UPDATE in id order, compare when armed (409 geometry_revision_mismatch), apply the new geometry, bump geometry_revision once. The module is the only author of the bump, and every function that opens a shape write is an enrolled door (tests/test_shape_write_census.py holds both). tests/test_shape_write_conformance.py asks every enrolled door: an armed stale write refuses and writes nothing; an accepted write, armed or not, bumps by exactly one; a second writer waits on the lock; an armed write that waited compares the revision it waited for. A door may be unarmed by design (the cut, its re-apply and its undo; the fill regenerate; the audit revert): its request carries no shape the client drew, so it holds no revision to arm with. It still locks and bumps, and its module states why (*_UNARMED_BECAUSE), which the probe reads in place of the armed answers. The lock re-reads the row whole (lock_rows, also the plain row lock a shapeless convert takes), and a door asks the found side of its authority again of that read before any arm is compared (write_authority.reauthorize_found, #4185), so a caller who lost the row while waiting hears 403, never the revision. The client's half is the Shape revision ledger below. _Avoid_: "geometry update" for the bump alone.
Shape revision ledger
The one owner of which stored geometry_revision this client holds for a shape (ui/src/app/services/shape-revision-ledger.ts; the app's instance is ShapeRevisions). Every geometry write is armed with the revision it was applied over, and the server refuses one whose shape has moved since. A door asks the ledger and derives nothing itself: - expect — what the next write on the shape is armed with: the revision of the row the door holds, or the one a vertex session on the shape holds, whichever is later (a session's live ops bump the stored revision and the store never hears of them). - applied over — the revision a write was sent against. The row a write *replaced* stands at it; that row is what the write's undo restores. - landed — the revision the server's answer names. The ledger takes the server's number. - follow — what a holder of an earlier revision has become through this client's *own* writes since.
Session revision
The revision bookkeeping of the vertex session open now (ui/src/app/services/vertex-session-revision.ts), owned by the Shape revision ledger as vertexSession: what a session holds is what the ledger *expects* of its shape. It keeps the session's OT base (base_rev, the revision the server transforms the session's ops against), the stored geometry_revision the session holds (the read it opened on, moved forward by every answer, every collaborator's frame and this client's own writes), its seed (the first answer, which sets the OT base; ops made before it wait, #4110), its gap marks (a gap answer, or a seed wait that timed out, #4123–#4126), the ops this client sent that the server has not answered, and a collaborator's op that reaches the session while its first op is out, which it holds rather than transforms (#4122). When a session stops, what it held and its gap mark are kept for its end, which is settled after it stops. Decided 2026-11-10 (#4138): this left VertexEditService, which is the ring editor again — the ring, its undo stack and the ring half of a collaborator's op, with no inject. The ring editor publishes each session boundary (sessionOpenings$) and the session revision hears it; the map's start names the read the session opened on. A collaborator's op has two halves with one owner each, in a stated order: the session revision admits it first (hold, or take its revisions), then the ring editor merges its ring. The session revision is also the one record of what kind of session the latest one was (a road's, or local-only: latestSessionWasRoad, latestSessionWasLocalOnly, #4224); the ring editor keeps no copy. _Avoid_: "OT state" for the whole of it (the stored revision and the gap marks are not OT), "session epoch" outside this module (it is how an answer is matched to the session that sent its op, and nothing else).
Armed shape-write door
The one implementation of what a shape write owes once it is sent (ui/src/app/services/armed-shape-write.ts; the app's instance is ArmedShapeWrites): it goes out armed with the revision it is applied over; a refusal because the shape moved since is not a failure, so the user's shape stays drawn and Keep mine / Take theirs is offered; *Keep mine* reads the shape the server holds, then sends again armed at the revision the refusal named, replacing that row (so its undo restores the collaborator's shape, never the one from before they wrote); a read that fails writes nothing; *Take theirs* shows the shape as it is now; a retry refused in turn is offered again. A door either hands it the whole write (write), or, where the write is sent on another module's stream (a floor journey, an amendment, a group update), hands it the error (refused). A *Keep mine* chosen before anything was refused is overwrite. A refused undo or redo step is stepRefused: its *Keep mine* replays the step armed at the token the refusal named, reading nothing, since the step writes its own recorded snapshot. - Shape-kind adapter — what varies by kind and nothing else: one row of the per-kind shape table (SHAPE_KINDS: area, road, reference feature, floor outline). A row answers every column or declines it with its ground (declined(…); the table census in armed-shape-write.spec.ts fails a silent gap): the banner kind; the current-shape read and *Take theirs*; the concurrency token (what a read names and what a refusal names); the echo hold (what keeps a collaborator's echo off a refused shape while the offer is up), or, declined, the refused shape kept by hand; and the undo record (the undo kind its step is recorded under, the noun an unnamed shape's step is called by, its snapshot, and its step arm); and the store door a cancelled vertex session's ring is put back through, and one shape reloaded through (putBack, reload, named over the ShapeStoreDoors the write-back supplies). Which row a session's shape belongs to is the table's to answer (rowOf, by the store that holds it). The road declines the put-back (#4122) and reloads through the road store; the floor outline declines both, since its session sends no vertex ops (#4112). The road declines the echo hold and keeps the refused line, stood at the revision it was drawn against so the next write is refused in turn (#4130). The area, the reference feature and the floor outline share the area door's hold (#4135). The reference feature's write is not optimistic, so it also draws the refused ring by hand. Its undo steps are the area kind's, on the row projected as an area (keeping the feature's own name, so an unnamed one's undo sends none): its store door is the area door. "All N" is the area row at a group's reach (allRows): *Keep mine* reads every row the retry replaces, and the group's compound step is recorded by schedule orchestration. - Step arm — how a recorded undo step of a row's kind is armed when it is replayed: the token it is sent with, the own landing it reports, and what *Keep mine* on its refusal moves. A geometry_revision row's step arm is the shape revision ledger. The floor outline's token is the building's updated_at (a levels write bumps the revision only when the derived envelope moves, so the revision cannot see a collaborator's levels write), which has no "one past", so the ledger cannot follow it; the row keeps its own lineage of armed writes instead (UpdatedAtLineage): a write armed at X that landed at Y was applied over exactly X, so X → Y is the client's own step. The lineage also hears the user's own unarmed levels writes — revert-to-envelope and the building editor's save (levelsLanded) — so a later floor-outline undo is not refused over them; and a floor-outline landing whose levels carry a footprint is reported to the shape revision ledger too, since it can move the building's envelope revision (#4223). A floor-outline save is armed at the building's updated_at as its session opened on it, not as the store holds it at save time, so a collaborator's levels write that reaches the client mid-session is refused onto the banner rather than overwritten (ruled 2026-11-11, #4191 ruling 1). *Keep mine* on a refused step moves that step's own arm and nothing else — a revision row's armedGeometryRevision, the floor outline's re-armed token kept beside the command — never the lineage, so an older step on the same shape that a collaborator's write passed stays behind it and is refused onto the banner, for the floor outline exactly as for an area. The lineage is forgotten with the ledger when the undo history is cleared. Ruled 2026-11-10 (#4140, call 4): a reference-feature reshape and a floor-outline reshape are undo steps, as an area's and a road's are. - Shape-write end — the one interface for how a shape write ends, for a caller with more to do than the write's own answer: restore, discard, reload, drop, wait for the session's own ops, the revision to arm with (read when the write is sent, never before), whether the server has already refused the gesture, landed, and where the choice is offered. A vertex session's end answers all of them; a drag names only what it has. A scheduled area whose save is already refused is offered the choice before its scope question, inside requestReshape.

Clash engine seams

Clash rule identity
Every clash identifies the rule it violated via a non-empty rule_name — the canonical "which rule was breached" label, surfaced in the UI with the hand-raised glyph. This is an invariant, not an optional field: the engine always sets it from the rule's name, and it is NOT NULL wherever it is persisted (ClashStance). Decided 2026-06-02 (grill session): a missing rule_name is treated as impossible, not survivable — there is no UI fallback; it is enforced by a required frontend type and a backend guard against empty names.
Clash identity
A clash is a computed value, not a stored row: the clash read (GET /api/clashes, GET /api/clashes/at-time, one ClashItem model) carries no id, no site_id and no creation time. What names a clash is its unordered entity pair plus its rule_name — Clash.key on the backend, clashIdentityOf (ui/src/app/utils/clash-identity.ts) on the frontend — and every frontend clash list, set and lookup keys on that. A clash's place in time is its conflict_start, which only a clash backed by a live Clash episode carries; the timeline clash lane draws a clash there and nowhere else (#4094, ruled 2026-11-06). _Avoid_: "clash id" — there is none, and code that reads one reads undefined.
Clash category
A per-variant declaration of *how a variant participates in clash rules* — distinct from the variant itself. Current members: physical_worker, live_hazard, mobile_plant. Decided 2026-05-19 (grill session): rules filter on clash category, not on enumerated variant lists. Adding a new variant means declaring its category; existing rules don't churn. The category lives on the variant's spec entry in the per-primitive registry.
Enclosure
The containment context an entity occupies for proximity purposes: the building it is placed inside (its building_feature_id), or the open air when it has none (building_feature_id is null). Two entities share an enclosure when they are in the *same* building, or *both* outdoors; a building wall is the boundary between enclosures. "Inside a building" means the building_feature_id FK is set — an explicit placement-with-a-level — not the mere geometric overlap of a footprint over a building outline.
Level
Any entry in a building's levels: a storey or the roof. A level is what an entity placed in a building is placed *on*.
Storey
An enclosed level of a building. "How many floors" counts storeys, and the count of poured slabs is a count of storeys; the roof is never one. The UI's word for a storey is "floor". _Avoid_: "level" where the roof must be excluded.
Roof
A building's one open-air level: always topmost, present on every building, and never a storey. The roof is a *place*, not an exposure state — a storey with no slab yet poured above it is exposed to what is overhead, but it is not the roof, and the roof stays the top of the designed building while the storeys beneath it are still going up.
Open-air surface
The ground outside buildings together with every roof: everything open to the sky, and what the site map shows when seen from above.
Unplaced
Of an area: drawn with no building. Which levels it covers is its vertical extent. Read as *open air* it lies on the open-air surface — the ground where it is clear of buildings, and the roof of each building it crosses — and meets what is also there (other unplaced areas, things outdoors, things on a roof) and whatever is floor unknown; it does not meet what is on a storey. Read as a column it meets all of those and the storeys too. An unplaced area is never inside a building, however much of one it covers.
Vertical extent
Of an unplaced area: which levels it covers beneath its shape — *open air* (the open-air surface only) or the column. The area's type picks the starting value: the two "keep out" types (exclusion, high-risk commissioning area) start as a column, the two "work here" types (work area, laydown) start as open air, and any type may be switched to the other. Every recurrence of an area shares one extent. An area placed on a level has no vertical extent; it is on that level.
Column
An unplaced area whose vertical extent is every level: it is on every level and in every enclosure its shape crosses — each storey and the roof of every building beneath it — as well as the ground outside. It is one drawn shape, seen on the site map and on every floor it covers. A column is never partial: it takes every building it crosses, roof included.
Floor unknown
Of a token or pin: over a building, with no level recorded. The building may be known; where in it is not. It is read cautiously — exposed to what is overhead, and met by an unplaced area above it — and it is never taken to be on the roof. _Avoid_: "outdoors" and "roof" for this state.
Slab count
Of a building: how many of its storeys have a poured slab above them, counted up from the ground. It is a count of storeys, never a level's index — zero means no slab is poured, and the most it can be is the number of storeys. The roof is never counted: nothing is poured above it. _Avoid_: "top concrete level", "highest poured floor" — both read as a level's index, which is one less than the count.
Exposed
Of a worker or an area: open to what a crane carries overhead. The opposite is protected — lying on a storey the Slab count covers, and beneath the outline of the level above. Everything else is exposed: a storey with no slab yet above it, the roof, the open-air surface, a Column, a token that is Floor unknown, and the part of an area that reaches out past the level above it.

Clash lifecycle and consequences

Clash episode
The persisted, first-class record of one clash over its lifetime — born when a specific conflict first appears, cleared when it ends. Identified by the same tuple as a clash stance: (site_id, entity pair, hazard) — where the hazard is coalesce(signature, rule_name) (CLASH_IDENTITY_SQL; rule_name survives only as the fallback for rows the signature backfill could not resolve; see Clash rule identity). Distinct from two neighbours:
Clash event
The edge-triggered DomainEvent a Clash episode emits at a lifecycle transition, consumed by the RulesEngine to fire a Clash consequence. Six kinds, in two groups by what drives them:
Clash consequence
The effect fired when a Clash event matches a rule — a Notification, Task, or email (any Channel the engine supports). Reuses the notification RulesEngine wholesale: a clash consequence is a NotificationRule keyed to its clash rule by FK, authored inline on the clash rule (one surface) but dispatched by the existing engine (one path). A create_task consequence ("you need to resolve this") auto-closes on clash_cleared and is manually closable by a coordinator stance.
Clash policy matrix
Historical (surface retired #671). The matrix-shaped authoring lens over the clash-rule set — a permit-code × permit-code grid per token-type pair — was retired as a standalone surface; per-site clash policy is now authored in the per-rule editor, whose save decision seam (ui/src/app/utils/clash-rule-save.ts, #649/#654) forks a seeded global rule into a per-site override (never PATCHing the seed) and authors per-site suppressions. The matrix *concept* survives as the per-rule permit matrix (#662): an optional permit_matrix on a single rule refining which permit combinations fire and at what severity/distance. What the retired surface got right is retained by the engine: distinct hazards each surface (one clash per (entity pair, predicate signature)), and within a signature the winner is most-specific → per-site → most-severe → priority. That resolution model is documented once, in root CLAUDE.md → "Per-pair clash emission & winner selection" and ADR 2026-06-29-permit-aware-clash-matrix-and-consequences.md (D8 + the distinct-hazards correction). The full-token-axis vocabulary — the real clashable entity_types (worker variants, plant types, active areas, road; never the legacy label worker, which no adapter emits) — is ADR 2026-06-30-clash-policy-matrix-full-token-axis-and-clash-types.md.
Clash suppression
A per-site off switch for a seeded clash cell. Authored in the per-rule editor as "Off for this site" (the create-suppression / clone-profile-create-suppression decisions in ui/src/app/utils/clash-rule-save.ts, gated to canManagePermitConfig), it compiles to a ClashRule with suppresses = true that carries the shadowed seed's filters and rides the per-site axis to outrank that seed: the engine *claims* its signature on the pairs it matches but emits no clash, so the cell is dark for that site alone. Because the claim is signature-scoped, turning a baseline cell Off silences only that hazard — a distinct permit hazard on the same pair still surfaces (it has a different signature); a more-specific rule of the *same* predicate likewise still outranks the suppression. A suppression only ever silences a pair that would *actually* clash. Decided #4, 2026-06-30. _Avoid_: "disabling the rule" — a disabled (enabled = false) rule is invisible to the engine, so the seed keeps firing; suppression is the deliberate, visible per-site silence.

Rule version history

Rule version snapshot
The frozen, full JSON state of an authored rule captured on every mutation (create / update / enable / disable / clone / delete) — the unit the editor's history view, diffing, and (clash today) revert read back. Append-only; the version row carries no FK to its rule, so history survives the rule's deletion (the delete-snapshot is written *before* the row goes). Per-rule version numbers are monotonic, allocated under a per-rule advisory lock. Spans all three authored-rule families — the ClashRule, the NotificationRule, and the ThresholdRule — which share this lifecycle (seeded-immutable-except-enable/disable, clone-to-customise) but not their field sets. _Avoid_: revision (reserved for DiscussionCommentRevision); audit log / audit trail (the durable AuditLog / GDPR store — a version snapshot is rule-editor history, not the site audit trail).
Rule version log
The shared seam every authored-rule family records through — RuleVersionLog over a RuleVersionAdapter port (backend/app/services/rule_versioning/). The port carries the one genuinely per-kind thing — the snapshot projection — plus the version model and operation enum; revert (rebuild a rule from a snapshot) and change-summary are *opt-in capability adapters* (clash supplies both today; the notification/threshold twins gain them by adding a hook, never by editing the core). The pure dict-diff is shared and per-kind-agnostic. Replaces the three hand-rolled version services. See docs/decisions/2026-06-13-rule-version-log-consolidation.md. _Avoid_: version service (the superseded per-kind hand-rolls); rule history (too vague — names the data, not the seam).
Rule shape
The portable clash-rule field set and its one owning module — backend/app/services/clash/rule_shape.py. FIELDS is introspected from the ClashRule model minus an explicit excluded set (row id + timestamps), so a field added by migration is carried by default; IDENTITY (site_id, profile_id, source — where a rule *lives*, not what it *says*) is explicit for the revert/seeder skip policies. The interface is to_snapshot / from_snapshot only — additive writer, tolerant reader (a key missing from an old Rule version snapshot hydrates to the model column default; stored snapshots are never migrated). Every ClashRule reconstruction site consumes it (the version adapter's projection + revert, the at-time rule reconstruction, the boot seeder); compile() stays in RuleCompiler, which derives site_specific from site_id at compile time. _Avoid_: hand-enumerating ClashRule fields at a call site (the #1688 dropped- field defect class); rule schema (the Pydantic create/update surface, which stays schema-driven and is only guard-tested as a subset of FIELDS).

Surfacing — bringing site activity to users

Noticeboard
Dock panel today (opened via PanelStateService's dock-panel state, activeDockPanel === 'noticeboard'). Shows shared site state — alerts, deliveries, clashes — that is the same for every user with access to the site. No per-user state; if you and I both have the noticeboard open, we see the same rows. Its rows span both temporal-anchoring classes: the delivery and clash lists are Scrubber-anchored surfaces, the alert list is a Now-anchored surface.
Notification
A per-user inbox item representing something directed *at this user*. Has per-user lifecycle state (unread, read, dismissed). Surfaced via the bell icon + count badge in the top toolbar, opened as a dropdown. Distinct from Noticeboard: notifications are personal, the noticeboard is shared. The same underlying domain event (e.g. "new incident filed") may produce both: a Noticeboard row (everyone sees site activity) *and* a Notification per targeted user (the HSE coordinator gets pinged).
System notification vocabulary
The closed set of values a notification's kind and source_entity_type may take — the backend StrEnums NotificationKind and NotificationSourceEntityType (models/_notifications.py). NotificationKind is every kind a seeded or dynamically-authored rule spec dispatches, every kind a threshold source's rules dispatch (each ThresholdDataSource declares its notification_kind — the weather editor's template kind among them), every trigger a clash consequence may be authored on (its notification carries the trigger as its kind, so clash_cleared, clash_escalated, clash_imminent and the two triage kinds are members beside clash_detected), plus the superadmin test dispatch's default. NotificationSourceEntityType is every literal source type those specs stamp, plus the two families an effect resolves from its payload (vocabulary.SOURCE_TYPE_PATHS): the kinds the activation-gap sweep alarms on, and the discussion subject kinds a mention names. tests/test_notification_vocabulary_census.py derives both from the dispatch doors and fails on drift.
Push subscription
A per-device web-push registration belonging to a user — the row that lets SimOops reach a closed browser. User-global (no site axis: a subscription is a fact about a device, not a membership; site scoping stays in rules-engine audience resolution). One user has many (phone PWA, desktop browser). Only the four personally-actionable notification families push (Task minted for you / assigned to you, @mention, outcome of a thing you raised) — never the Noticeboard firehose. Decided 2026-07-18 (wayfinder map #1293); see docs/decisions/2026-07-18-web-push-channel.md. _Avoid_: push token (mobile-native connotation), device registration.
Briefing
A per-user, on-entry roll-up — the surface a user meets when they enter (or refresh) a site: "what do I need to know and act on right now, and where do I go for it". Composed of modular briefing cards, each summarising one underlying surface (active Alerts; work-stopping Clash blockers and *my* clashes, consolidated into one card; *my* open Tasks; the Notification inbox; open incidents — with weather warnings and day-over-day changes as planned future cards, deferred until their data sources exist).
Scrubber-anchored surface
A dashboard surface whose contents are read as of the scrubber's viewDateTime — it moves with time-travel, so cycling the scrubber to a past or future moment shows what was (or will be) true then. Members today: the Noticeboard clash list, the Noticeboard delivery list, and the incident-list panel body. The defining test: the thing has a *position or extent in time* — a planned Active period, a moment of conflict, a report date — so "as of when?" is a meaningful question. Decided 2026-06-04 (grill session). _Avoid_: time-filtered (overloaded — every panel filters by something), historical view (implies past-only; the scrubber runs forward too).
Now-anchored surface
A dashboard surface whose contents are defined by liveness / workflow status, not by a position in time — outstanding work that is "now and ongoing" until someone acts on it. It is immune to the scrubber: cycling to a past or future moment never changes it. Members today: the active-alert list and count, and the open-incident count badge (draft / submitted / in_review, all-time). Synonym: *live backlog*.
NotificationRecipientState
The per-user state row for one user's view of one Notification. Carries per-user lifecycle timestamps. Unique on (notification_id, user_id).
Audience (notification dispatch)
The resolved set of user_ids a notification was fired to. Materialised at fire-time into NotificationRecipientState rows; not backfilled when memberships change later.
Dispatcher (per-kind helper) — historical, V1 only
A Python helper function — one per notification kind — that knew how to compute the audience for *that* event and called the generic notifications.dispatch(content, recipient_user_ids=...). Lived in backend/app/services/notifications/dispatchers/<kind>.py (the directory no longer exists).
DomainEvent
A typed, structured fact emitted by a domain service after a state change has committed (e.g. IncidentSubmitted, ReportReviewRequested, WeatherThresholdCrossed). Carries a small payload (IDs + key fields), a site_id, and an actor. Pure data — no behaviour, no DB session. Emitted into the EventBus; multiple subscribers may consume.
EventBus
The transactional-outbox pipeline DomainEvents flow through — *not* in-process pub/sub, which the 2026-05-23 ADR explicitly rejected (at-most-once delivery for events whose misses are a safety issue). Four legs, all in backend/app/services/events/:
Event — one word, three unrelated systems
event names three systems in this codebase. They are separate on purpose: each passes the deletion test on its own, and merging a pair has been proposed — and rejected — more than once.
Replayable (frame kind)
Whether a frame kind is delivered when a catch-up replay carries it, as well as when it arrives live. On the frontend it is a fact declared on each row of WebSocketService's channels table (replayable), and the replay has no router of its own: a catch_up_response runs its seq dedupe, then feeds every surviving frame through the same door a live frame takes (route(frame, 'live' | 'replay')), which drops a replayed frame only when its row is not replayable (#4096). The kinds no row claims — entity frames and unnamed broadcasts such as geometry_cut — replay as they route live. Its backend twin is persist on broadcast_to_room: what the ring holds is what a replay can carry. The two describe one fact from either end and are not yet derived one from the other. _Avoid_: "persisted" for the frontend fact (persistence is the ring's, replayability the consumer's); a per-kind arm in the replay loop.
Frame door (realtime)
The one declaration of what a realtime frame IS: backend/app/core/ws_frames.py holds one Pydantic model per event — every name the registry knows, thirty-three frames: its envelope, its routing (how the manager admits a reader: site_role for an entity_type-tagged frame, audience for one that always carries a directive — its own, or the specific_users one broadcast_to_users mints — room for the unrouted plane, and direct for a reply to the one socket that asked: a presence snapshot, a catch-up response, a vertex-op ack) and whether it is Replayable — and wire() is the exact dict the socket carries. WebSocketManager.broadcast_entity_event builds its frame through the door (frame_for_entity_event); every other family constructs its class at the one site that emits it (the config plane's broadcast_config_event, the task family's _broadcast, the presence manager, the vertex-op service, the cut outcome, the route handlers); and broadcast_to_room / broadcast_to_users / broadcast_to_user / broadcast_ephemeral take a frame and nothing else — the frame's replayable is the only thing that decides whether it is sequenced, and the wire-dict tier beneath (WebSocketManager.send_wire) is not on the broadcast port. The entity-type vocabulary — which read model each wire entity_type carries as data, the record → wire mapping of the two-identities rule made explicit once — is the door's other half, app/schemas/ws_frame_payloads.py (ENTITY_DATA), kept out of core/ because core may not import schemas. The typed union is dumped as JSON Schema to ui/src/app/services/__fixtures__/ws-frame-schema.json (make ws-frames-schema-check, in make test), the realtime twin of the OpenAPI snapshot, and the frontend draws its frame types from it. The schema is the frame as a client reads it: event always present, seq present exactly when the frame is Replayable, no audience (the manager strips it before serialising). The door refuses at build, before anything is sent — an undeclared entity_type or a delta on a create raises — so a mis-wired emitter on a post-commit path is a loud failure after a durable write, not a frame the frontend silently drops. A row with no wire identity (an audit revert of a shift, clash rule, rule profile or smart group) sends no entity frame: a revert is an edit, so it announces itself exactly as that kind's ordinary edit door does — a config_changed frame with the same domain, the updated op, the kind's read model and the kind's audience (a smart group's owner_or_shared), under the config plane's log-and-swallow policy (services/entity/config_revert_broadcast.py). _Avoid_: a {"event": …} dict literal anywhere under app/ outside the door (the census tests/test_ws_frame_census.py reds it — the walk's negative control is a synthetic module); a hand-written fixture standing for a frame (tests/test_ws_frame_wire.py captures real ones); a wire entity_type no emitter speaks ("zone" was one for years; the census now reds a member nothing under app/ names).
Frame types (frontend)
The frontend's realtime frame types, GENERATED from the committed frame schema: ui/scripts/generate-ws-frame-types.mjs renders __fixtures__/ws-frame-schema.json to services/__generated__/ws-frames.ts (make ws-frames-schema runs the backend dump and this in one step; make ws-frames-schema-check and make frontend-type-parity fail when either is stale). services/websocket.types.ts is the app's vocabulary over it — every frame name a consumer imports is an alias of a generated frame — so a frame change reddens tsc at its reader. A frame's declared record crosses into a store's hand-written row through storeRow, the one bridge: its parameter (WireSpelled<Row>) carries every key the row requires with the row's types, and lets only an optional key arrive as null; a key the row types more strictly than the wire (a bare backend str the row narrows) is named at the call site. _Avoid_: a hand-written frame interface beside the generated one; data: any on a frame (EntityEventDataPayload is retired); a cast from a frame's data to a row type anywhere but storeRow.
Known gap (frame door)
A frame name that goes on the wire by hand because its model is not declared (KNOWN_GAP_EVENTS in the frame door), or an entity type whose data is undeclared (an ENTITY_DATA entry with no record). Both sets are empty and pinned there by the census: a new event name is declared as a frame and a new EntityType member is declared in the vocabulary, never parked in a gap. The sets existed, shrink-only, between the two packages of epic #4093 F1.
RulesEngine
The bus subscriber that evaluates per-site NotificationRule rows against incoming DomainEvents and calls notifications.dispatch() for matching rules. Replaces the per-kind dispatcher helpers as those are migrated.
NotificationRule
A per-site row authored by a coordinator/admin that says "when DomainEvent X fires AND payload matches conditions Y, then fire effect Z". Effects today are dispatch_notification (FYI inbox item) and create_task (see Task below). The shape: - trigger: an event kind enum (e.g. weather_threshold_crossed, incident_submitted, report_review_requested). - conditions: a recursive boolean predicate tree (all / any / not + leaf clauses with field, op, val). Mirrors the existing clash-rule predicate composition (see Clash engine seams). - audience: set algebra (union / intersection / coalesce) over *audience kinds*: role: hse, capability, contractor_members_set: $payload.contractor_id, payload_user: $payload.reporter_id, payload_user_list, specific_users: [...], site_duty_owner. Resolved at fire time to a set[UUID]. - effect: dispatch_notification (Notification + per-user state rows) and/or create_task (Task + TaskAssignment rows).
Task
A *pending action* assigned to one or more users, distinct from Notification (which is informational). A Task's shared lifecycle is stamp columns, not a status enum (TaskLifecycle.STAMPS: resolved_at / cancelled_at / expired_at; open = no stamp) — resolving by any assignee clears it for the rest. Has an action_kind (TaskActionKind: approve_incident, provide_incident_detail), a target entity reference, and an optional due_at. Surfaced via the My Tasks panel (né *My Work*, renamed 2026-07-17, #1257); not shown in the bell dropdown (which is notifications-only).
Task closer
What closes a Task other than an assignee resolving it through its handler — how the Task closes when the thing it asks for happens (or stops mattering) somewhere else. Every action kind states its closers at registration (register_task_handler(..., closed_by=...)), as one or more of: OnEvent (an outbox event resolves it — the task_auto_resolver's tables are derived from these, never hand-kept), InModule (a named door closes it in-service, e.g. confirm_queue.dispose_if_settled for confirm_blocker, the receive-reminder sweep's clear pass for delivery_receive_reminder), or ExpiryOnly (nothing but the due-date sweep; stands alone). tests/test_task_closer_census.py holds every kind to a stated closer and every named event, payload field, target type and door to something that exists.
My Tasks
The dock panel listing *my open Tasks* — the single task inbox (dock id tasks, pencil-square icon, T keybind). Formerly My Work, a two-tab container that also carried a Close out tab (the bulk end-of-day Completion record capture, "close out today"). Decided 2026-07-13 (grill session). Amended 2026-07-17; shipped 2026-07-17 (#1257) (close-out re-scope, see docs/decisions/2026-07-17-close-out-two-verbs.md): the *Close out* tab is deleted — bulk completion moves to the site browser's multi-select — and the now single-tab panel un-wraps and renames to My Tasks (prefs v15 migration; a persisted-open my-work occupant migrates to tasks on load).
Channel
A delivery transport for a Notification or Task. Channel is an explicit axis: each rule's effect declares which channel(s) to use, and a *channel adapter* handles delivery. Three adapters are registered (services/notifications/channel_adapters/): in_app (WebSocket dispatch, in_app.py), email (email.py — enqueues EmailOutbox rows) and web_push (web_push.py). There is no SMS adapter; an unimplemented channel named by a rule fails cleanly at fire time with a log line, never a crash. _Avoid_: medium, transport, route (overloaded).
TaskAssignment
The per-user row for one user's view of one Task. Carries acknowledged_at (saw it) and lets the engine cancel/recreate assignments as audiences change. Unique on (task_id, user_id). Distinct from NotificationRecipientState (which carries *read* state, not action state — Task resolution lives on the Task row, not here). _Avoid_: task_user, task_inbox_entry.
Read state
NotificationRecipientState.read_at is the single per-user lifecycle field. NULL means unread; non-NULL means read. The bell badge count is COUNT(*) WHERE user_id = me AND read_at IS NULL AND (expires_at IS NULL OR expires_at > NOW()).
Click-through target
The Notification row carries structured target columns, not a URL: panel_hint (which panel to open), source_entity_type + source_entity_id (which entity to select). A small frontend NotificationClickRouterService switches on source_entity_type to call the appropriate panel-open + selection actions.
WebSocket audience: specific_users
One of the AudienceType literals in backend/app/core/websocket_events.py (AudienceType = Literal["owner_or_shared", "non_owner", "specific_users", "roles_or_users"]). The payload for specific_users is { user_ids: list[UUID] }; the _AUDIENCE_HANDLERS filter pipeline (in core/websocket_manager.py, registered via register_audience) matches the connection's user_id against the list. The notification subsystem composes over it.

Mentions

Mention
A directed reference to a Site member roster user, embedded inline in user-authored prose (e.g. a DiscussionComment (incident thread)|DiscussionComment body). A new Mention emits a DomainEvent consumed by the RulesEngine, firing a Notification of kind mention to the referenced user, pointing back at the surface where the mention was made. Cross-cutting — the same concept is used wherever a Mention-bearing surface accepts free-text input from users (today: incident and observation comments, via the shared discussion thread; near-term: Action and Inspection comment threads, and any narrative fields those grow). A single notification kind (mention) and a single seeded NotificationRule mean adding a new surface is a per-surface plumbing change; the engine layer is reused unchanged.
Mention pool
The set of users eligible to appear when a user begins authoring a Mention. Decided 2026-05-25 (grill session): the entire verified Site member roster, unfiltered by draft visibility, role, or contractor. The mention's job is to *pull a user into a thread*; pre-filtering pre-empts that intent. A mention sent to a user who can't see the underlying entity still fires; on click-through, the existing graceful-empty pattern applies (panel opens, row absent — see Click-through target).
Mention-bearing surface
A persisted text field that accepts Mentions. First landing: DiscussionComment.body on the incident thread; observation comments followed via the shared discussion thread. Near-term: Action and Inspection comment threads (and any narrative fields those grow). Adding a new mention-bearing surface plumbs the parser + emit-event into the surface's write path; the notification kind, audience resolver, seeded rule, and user pref row are reused unchanged.

Presence and identity

Site member roster
The set of verified SiteMembership rows for a site — the answer to "who's on this team?". Pending (unverified) members are excluded; they live in the admin/coordinator review surface, not in operational displays. The roster is the single source of truth for per-user identity attributes (display_name, role, contractor_id) consumed across the dashboard. _Avoid_: site users (overloaded with auth/identity), team list.
Presence
The per-session liveness overlay on top of the Site member roster. Tracks which roster members currently hold an active session in the site room (site:{site_id}), whether they're editing an entity, and where their viewport is centred. A user is "online" iff they appear in the presence list; "offline" iff they're in the roster but not in the presence list. Presence carries *status*, never *identity* — name, role, and contractor are read from the roster.
Role badge
The visual indicator of a user's SiteRole. Appears as a small corner overlay on presence bobbles (online and offline alike) and as a labelled chip in the Presence dropdown rows. Combines an icon (from heroicons) with a short label — nine roles, each an (icon, shortLabel, priority) entry in the ROLE_REGISTRY frontend constant (types/role-registry.ts; the once-planned per-role tint axis is gone — every entry shares the neutral background, identity rides icon + label). Roles not present in the registry (e.g. a new backend enum value not yet known to the frontend) render unbadged — no guessed fallback — and sort to the bottom of their section. The current user's own toolbar bobble is deliberately unbadged; the dropdown row representing them carries the full chip. _Avoid_: role icon, role tag, role chip (each describes a sub-part, not the atom).
Presence dropdown
The hover popover anchored beneath the toolbar presence bobbles. Two sections — Online (active sessions) and Offline (roster members not currently connected) — each sorted by role priority (admin → site_manager → coordinator → hse → member → commercial → contractor_hse → viewer → client, the registry's priority order) then alphabetically by display name. Includes the current user with a "(you)" annotation, in the Online section. Scrollable when content overflows a capped height; section headers stay sticky during scroll so the bucket label is always visible. Offline rows render at reduced opacity but keep contractor colour, role badge, and name intact — identity stays readable, only liveness recedes. Empty section headers are hidden. Non-interactive in V1 (no per-row click behaviour); the on-map viewport-cursor feature remains the affordance for "where is X looking right now?".

Row capabilities — predictive permission flags

Row capability
A per-user boolean on a casework record's read surface (can_edit, can_resolve, can_contest, …) predicting whether the server would allow that verb for that user on that record, right now. It mirrors the service's own gate — band, record state, and the user's relation to the record — and never enforces anything itself: enforcement stays at the route/service gate, and a capability that under-reports its gate hides the verb from exactly the persona the rule exists for (the entry-69 lesson). The casework kinds (the WorkGroup kinds — blocker, incident, observation, snag, defect — plus the standalone action) serve the same shape of flags.
Refusal (row capability)
The refusal a flag raises when it does not hold, carried as spec-row data beside the arms: a who-refusal (a code, a sentence in site language, a status — 403 by default — and optional variants, a state-keyed copy override so *why* a window is not editable stays two sentences under one flag; a variant states copy only) and, since the 2026-11-03 amendment (#4070), the ladder around it — the state rungs asked before the arms and after them, in the order declared. require(flag) walks the ladder and raises the first failing rung; refusal_for(flag) predicts it without raising. Every rung's atom is carried by every arm (a load check), so flag ⟺ who-admits ∧ every rung holds is structural. _Avoid_: error message (the copy alone), guard (the call site).
Refusal envelope (wire)
What a refusal looks like on the wire, whoever raised it (a service's DomainError, a route's HTTPException): {"error": {"detail", "code", "request_id"}}. The slug rides the envelope's own top-level code (null when none was named); the detail is the sentence, or — only where extra fields are load-bearing (an inspection's incomplete_items, a blocker's guard) — {message, ...extras} (#2769, normalise_legacy_detail). The frontend reads one structurally through refusalOf(err) → {code, message, fields} (utils/api-error.ts, #4100), and a karma spec builds one with refusalEnvelope(...) (testing/refusal-envelope.ts), which a backend golden pins to the renderer. _Avoid_: detail.code (the retired pre-#2769 shape), reading a refusal by its wording.
Error code (refusal slug)
The machine-readable slug a Refusal envelope (wire) carries in its code — a member of ErrorCode, the one StrEnum in app/core/error_codes.py and the closed vocabulary of every slug the envelope may carry (#4101). A raise names the member (code=ErrorCode.diary_not_found), never a string; OpenAPI exports the enum as the ErrorCode schema typing ErrorBody.code; the frontend's ErrorCode (types/error-codes.ts) is an alias of the union generated from the same enum (the realtime frame types, #4149) — there is no hand mirror, so a new member is the backend append plus a regeneration — and refusalOf / extractErrorCode answer that union, so a branch on a slug the backend cannot send is a compile error. A refusal family is a declared slug PREFIX branched on as a whole (capture_link_*: ERROR_CODE_FAMILIES, errorCodeStartsWith). A code-less refusal is one the frontend can only read as a sentence; the existing ones are a shrink-only baseline, and a new raise carries a code. _Avoid_: slug literals outside the registry, a hand-mocked fixture code the backend does not mint, family tests by substring.
Rung (state refusal)
A record-state atom on a flag's ladder, answering in the record's own words when it does not hold: a StateRefusal — status, code, sentence (which may quote the state it refuses, and the door's *act*), and the record-state keys that ride the envelope beside it (triage_status, status). The atom carries the *default*; a flag whose verb speaks the same state differently restates it (Rung(atom, refusal)) — the archive says 409 blocker_not_archivable of a record the close calls 409 blocker_not_resolvable, and the overlay verbs answer a rejected record 403 where the lifecycle verbs answer 409. Codes *and statuses* are verb-specific on the shipped surface, which is why the restatement is a whole refusal. The order of rungs is the wire: when two fail, the caller hears the first. _Avoid_: deferred gate (the retired 08-10 construct — a state the flag predicted but its refusal was blind to, leaving a hand guard to answer it; a flag now carries the rung or carries no refusal), precondition (payload validity, which is not a record state).
Scope-like vs voice-like relation
The two kinds of user-to-record relation an arm can require. A scope-like relation bounds *reach* — "within the contractors you may act on" (own_scope). A voice-like relation names *who may speak in a role the record creates* — the declarer, a member of the record's own firm, a member of the accused firm (may_contest). The distinction carries the superadmin rule: a superadmin holds every band and passes every scope-like relation, but fails every voice-like relation — they belong to no firm, so there is no accused firm to speak for (can_contest=False on a superadmin is correct behaviour, not a gap). Decided 2026-08-09 (grill session): this distinction is declared per relation, and the superadmin answer is *derived* from it, never hand-authored per kind.
Disclosure
**Who may *see* a record at all** — the row-level read grant, a first-class concept distinct from a Row capability: a capability predicts a *verb* for a reader already looking at the record; a disclosure decides whether the record exists for them (a reader outside it gets a 404, never a 403 — disclosure does not leak existence). A kind enrols its read grant once in app/services/workgroup/disclosure.py — its spec, its read flag, its context and viewer builders — and that single declaration serves all three consumers: the row predicate, the band question, and the list clause. There is no per-kind _can_see / _visibility_clause pair to keep in step, because there is no second author; the generative twin-agreement harness (tests/support/disclosure_twins.py) asserts per persona that the Python predicate and the composed SQL filter name the same row ids. Enrolment is discovered, not listed (#2802): disclosure.discover_capability_modules() reads the app/services tree for the enrollers, so there is no hand-maintained module list a kind can be missing from, and the discovery census (backend/tests/test_disclosure_enrolment_census.py over tests/support/enrolment_census.py) is the forcing function — it fails both the enroller the harness cannot see and the sql_rendered read flag that never enrols at all, and its two deliberate absences are declared with their grounds rather than stepped over. The composition law lives on the enrolment: list_filter returns None for "no filter" (the reader's band reads everything) and an explicit false() for "renders nothing" — conflating the two is whole-table disclosure. Eight kinds are enrolled: blocker, incident, observation, snag, defect, inspection, permit, alert. Decided 2026-08-16 (epic #2645 story A; docs/decisions/2026-08-16-row-disclosure-seam.md). _Avoid_: visibility clause / _can_see (the retired hand-written twins); row capability (verb prediction, not read grant); RBAC (the band grant is one atom of an arm, not the rule).

Event strips — per-kind append-only timelines

Event strip
One casework kind's append-only timeline — a per-kind event table (incident_events, observation_events, snag_events, blocker_events, …) whose rows all carry the same five facts: the parent detail's FK, the denormalised site_id, the acting user, a per-kind event_type enum, and a JSONB metadata payload. The tables stay per-kind (they carry per-kind enums); what is shared is the *semantics*, owned by the EventStrip substrate (app/services/workgroup/kind.py): how a row is appended and the total order it is read back in — instant first, then a deterministic tiebreak (seq where the strip has one, else id), so equal instants can never reorder between the timeline route and a serialiser's in-hand sort. Binding a strip is two facts (row model + FK column name); a kind cannot hold a private opinion about the ordering or the append. Two tables bind for their order alone (the HSE register's statutory hse_report_events and the stock_events ledger — neither carries the five facts, so neither may claim the append semantics). Eight strips are enrolled (epic #2645 story C, #2657–#2659). _Avoid_: audit trail (cross-entity, user-action-shaped, not a per-record timeline); DomainEvent (the durable delivery pipeline — a different "event"); activity feed (a rendering, not the substrate).

Casework substrate — reading a population, reading one record, ending a write

WorkGroupPage
One primitive for reading a WorkGroup kind's population — the read-side twin of the kind spec. Every list, queue and lookup over a kind otherwise restates the same five facts, and each restatement fails silently in its own direction: the WorkGroup→detail join; the group_type kind gate (omit it and the read is correct only while no other kind's detail table happens to answer its refinement); the site scope (omit the empty-scope short-circuit and you ask for site_id IN (), or — worse, if the scope was simply dropped — for every site's rows); the soft-delete default; and the Disclosure clause (hand-composing it means deciding the "band holder ⇒ no filter" half yourself, and reading a rendered-nothing clause as "no filter" discloses the whole table). A page owns all five, so a caller states only what is genuinely its own — which sites, which reader, and a refine callable that narrows the composed Select. Binding a page is two facts: the kind spec and the group_type. Five kinds bind one — blocker, incident, observation, snag, defect (app/services/workgroup/page.py). What a page deliberately does not own: ordering (the caller's — a queue ages by mint, a list by declaration — though page() *requires* one, because a paginated read without ORDER BY returns an arbitrary slice); serialization (it returns (WorkGroup, detail, *extras) rows, never wire shapes); and authorization (the scope arrives already reduced, the disclosure clause already resolved). Serialization is the Read shape seam's, which the page meets at the tuple and shares no opinion with. soft_deletes is derived from the detail model's column rather than declared, so a kind that grows a deleted_at gets the filter on its next read; the kinds without one are defect and alert. Decided 2026-08-20 (epic #2792). Entities are not the only shape a population is read in. A whole-site fold — the slip read's record context, its citation counts, the diary's snag tally — wants a handful of *columns* and must not hydrate an ORM row per record (BlockerDetail.evidence is lazy="selectin": the entity drags every evidence row on the site behind nine scalars). Those reads are the same population under the same five facts, so project() answers them in columns where rows() answers in entities. Its disclosure keyword is required, with two legitimate answers and no default: a reader's rendered clause, or an explicit None meaning *this fold runs behind its own gate*. Five folds took that decision silently before 2026-08-26 (#3359) — and had already decided the soft-delete arm three different ways between them. _Avoid_: query helper (it is the authority, not a convenience); repository (no write side); Record view (one record, not a population).
Record view
One record, as one reader sees it — the reader-scoped single-record load, as a value. A record surface is expensive *on purpose* (a clamping-set load, a per-basis-kind existence check, provenance queries, an indexed timeline read, a cross-record cause lookup, a declaration-closure walk); a list read carries none of it. That asymmetry is the deliberate part — *the right price on a record surface and the wrong one on a list* — so the two are two seams, not one parameterised one. What a record view removes is the hand-wiring: the loads that used to sit as a dozen sequential awaits inside a serialize_full method, where every new disclosure line was a same-method edit competing with the other eleven and the only instrument that could count the round trips was an HTTP request. As one loader it gives the read one measurable price (the statement count is pinned by a test, so a lazy re-load added later goes red), threads one clamping set through the whole disclosure by construction, and leaves the serializer pure — handed a RecordView, touching no session, so what the record *says* is testable without a database and what it *costs* is testable without a route. Four kinds have one (blocker, incident, observation and, since 2026-08-24 (#3102), snag — each services/<kind>/record_view.py); the snag's loader awaits nothing, which is a fact about how cheap that kind's derivations are and not a reason for it to read through a different door. _Avoid_: DTO (it is a load result, not a wire shape); serializer (the pure consumer of one); WorkGroupPage (a population, not a record).
Read shape
How a kind turns rows into its wire shapes, declared as a value — and the one implementation of *load once, then flatten* that every casework read rides (app/services/workgroup/read.py). Two shapes per kind, both declared in its services/<kind>/record_view.py: a RecordShape (the Record view loader plus the pure flattener) and a SummaryShape (the page loader, the pure row builder, and the kind's predictive-permission function). They are deliberately NOT on the kind spec — a kind's read module imports its kind_spec leaf, so a spec field pointing back at the loader would close an import cycle. What the seam owns is the two laws the four kinds were restating: the record's *load-then-flatten*, and the page's *resolve everything for the WHOLE page, then build rows without awaiting* — including the reader's membership per site the page spans, which is one batched query through core/rbac.get_site_memberships. That last part is why the fold was not cosmetic: incident's copy resolved the membership inside the row loop, a statement per distinct site, which is the per-row load the observation page had already removed (#2795) surviving on a sibling because nothing held the copies to one law. user=None means no permission block at all — the audience-less shape a broadcast or an anonymous submission answers with, never a defaulted-open one — and that is the law the cross-kind conformance suite drives through all four kinds. Decided 2026-08-24 (#3102, epic #3051). _Avoid_: serializer (the pure per-kind function a shape names, not the seam); WorkGroupPage (which rows, not what they say); presenter.
CaseworkCommit
The one write epilogue every casework verb ends with — flush → settle → audit → commit → drain → announce (app/services/workgroup/casework_commit.py). The sequence used to be hand-copied at ~50 call sites in two incompatible dialects: incident and observation wrote the audit row and blocker, action and inspection wrote none at all — three registers with an Event strip and no compliance trail; incident settled before the commit and observation sometimes after; incident drained before its broadcast and observation after it. None of that was a decision about those kinds, it was the order the code was written in. The order is the module's invariant, and the per-verb variance is the argument list. Why this order: flush so constraints fire here and FK-dependent rows have ids; settle (refresh) so the audit snapshot records what the row *is* after the write and the announcement's serialiser reads loaded attributes; audit staged into the same transaction as the write it describes (a trail that could commit separately from its subject is not a trail); commit through commit_point, never a bare session.commit(), so inside a door's unit_of_work it degrades to a flush; then drain the effects queued inside the transaction, then announce. The two records are not alternatives: the Event strip is the domain's own timeline, phrased for the people doing the work; the audit log is the compliance trail, one uniform shape across the estate, carrying actor, contractor, a round-trippable snapshot and a revision hash. A kind needs BOTH, everywhere. Decided 2026-08-20 (epic #2792 ruling R2). The enrolled set grows: the snag joined 2026-08-24 (#3099) — it was the last WorkGroup casework kind writing a strip and no trail, and its self-certified close-out is what releases a Completion record's "N snags open" caveat. Which kinds are under the seam is answered by CASEWORK_SERVICES (backend/tests/casework_epilogue_registry.py), never by a count in prose. _Avoid_: "the save method" (it is the epilogue, not the write); unit of work (the transaction door it calls, one layer down); post-commit hook (drain and announce are two of six steps, not the whole).

Partial update — absent, null, cleared

Patch
The absent-vs-null door — the one authority for the question every partial update asks, per field: *skip it, clear it, or set it?* (app/core/patch.py). Three wire shapes carry that decision — the field is absent, the field is null, or a clear_<field>: true flag stands beside it — and before 2026-08-24 the estate read them in four incompatible dialects at once: 13 clear_* request flags, 80 model_fields_set / exclude_unset probes across 45 modules, and a private UNSET sentinel in the HSE register's writes. Nothing about any one site looked wrong on its own; the incoherence lived *between* them, and api/routes/incidents/incidents_records.py spoke two dialects in one call — position_wgs84: null was ignored while persons: null emptied the involved-person set, so a reader had to know which argument they were looking at before they could predict the outcome.
Null-clearing declaration
The one statement of which fields' explicit null clears them, made on the request model and published on the wire (#4102). @null_clearing("a", "b") (app/core/patch.py) on a PATCH schema is read by Patch — a call site may no longer re-declare it — and stamped into the schema's JSON as the OpenAPI extension x-null-clears: true on a declared field, false on every other field that can hold null (its null never clears — skipped, or a 422 where the model refuses it, as a required firm does). Before it, OpenAPI rendered a clearing field and an inert one alike (anyOf[T, null]), so the frontend carried the difference in comments, and #4077 shipped through the gap — an area's "no contractor" clear was a no-op at both layers. The frontend half is the parity harness's request-side tier: every schema that publishes the extension has a row in ui/src/app/types/__parity__/null-clears.json naming the payload interface that sends it, and that payload's | null keys must be exactly the declared set (and it may carry no key the schema lacks). The five entity PATCH schemas (worker, plant, active area, roving crew, delivery) and the per-kind schedule-group bodies publish today. Every other partial-update body (each PATCH body, and each casework POST …/update body) that holds a nullable field sits on the known-gap set (KNOWN_GAP_SCHEMAS in tests/test_patch_null_clears_publication.py), keyed by schema name and read off the live OpenAPI, so it catches a body whatever its server-side null handling goes through; it may only lose members, and a body that starts publishing must leave it. Alongside it, the call-site null_clears= argument survives on its own shrink-only per-file ratchet. The schedule-group update, reconcile and convert bodies are per kind (#4177), so each publishes its own answer, including whether a null contractor_id clears. _Avoid_: "nullable" for this (every optional field is nullable on the wire; the question is what the null does); a comment on the frontend payload as the record of it (the extension is the record).

List reads — the row cap

Row cap
The defensive ceiling on a bare-array list route (RowCap / RowCapDep, app/api/deps.py): the route builds its list, keeps at most the site's list_row_cap rows (a client ?limit= may lower it, never raise it), and — only when it actually cut the list — answers with an X-Truncated: true response header. The body stays a bare array either way, so the cap is not pagination: no cursor, no total, no page N (that is Page[T], see docs/architecture/api-list-response-shape.md). The header is part of the wire contract (#4103): declared on every capped route's OpenAPI 200 response, exposed through CORS, and read on the frontend only through the Capped read door. tests/row_cap_registry.py records which list routes cap, which decline (and why), and how the frontend reads each capped one. _Avoid_: "pagination", "page" (a capped list has no next page); "limit" alone (the ?limit= parameter only lowers the cap).
Capped read
A frontend read of a row-capped route, through the one door that reads the cap (CappedListReader, ui/src/app/api/capped-list.ts). The reader names the route by its backend path template, which is both the URL the door fills and the identity it reports. A capped read hands back {rows, truncated} when a surface tells the person the list is incomplete (*surfaces*: the permit history lookup, the Plan Gantt), or the bare rows when it does not (*telemetry*); either way a truncated answer emits one client.list_truncated event naming the template and the row count, never row data or a filled URL. Ruled 2026-11-06 (epic #4093 call 6): the default signal is a developer one, on Grafana dashboard D, not UI. _Avoid_: reading X-Truncated anywhere else; calling a capped route with a raw http.get (its cut list then passes for a whole one).

Wire mirrors — the type-parity harness

Phantom key
A key a frontend read model declares that no response schema it mirrors carries (#4099). A read model is the hand-written type an API call reads a response into (http.get<Worker[]>(…)); its mirrored schemas are the ones the endpoints it is read from answer with, in the committed OpenAPI snapshot. A phantom key is a silent undefined at best — the frontend Clash required id, site_id and created_at, which no clash payload ever carried, and three consumers were broken in production (#4094). The phantom-key tier of the parity harness (make frontend-type-parity) forbids them, except where the type's row in ui/src/app/types/__parity__/read-models.json declares the key render-only with a one-line reason: a value the app derives itself (is_pending), or a view merge (a field another wire type contributes when the app folds it into this shape). That allowlist is the record of every view-model merge, and an entry the wire has caught up with reddens. The table is seeded from the endpoint match by scripts/verify-read-model-parity-census.mjs --write, and a read model with no row reddens the census. The tier is shallow: it compares a read model's top-level keys, so a type reached only nested inside another (the items of a *ListResponse) is not checked by it. _Avoid_: "extra field" (the wire may send keys the frontend ignores — that is not this); calling a nullable-vs-optional mismatch a phantom (the key exists on both sides; that gap is the frontend's optionality, a separate tier).
REST enum subset
The backend string enums the frontend names, generated from the committed OpenAPI snapshot into a module the app imports (#4150): ui/src/app/types/__generated__/rest-enums.ts, one RestEnums interface keyed by the enum component's name. A vocabulary under types/ is an alias of it (export type SiteRole = RestEnums['SiteRole'];, and a rename rides the alias: ImportRowStatus = RestEnums['RowStatus']), so a backend member reaches every reader through tsc on regenerate alone — make docs-openapi regenerates it after every dump, make rest-enums alone renders it from the committed snapshot, and make frontend-type-parity / make docs-openapi-check fail when it is stale. It is a subset by construction: an indexed read RestEnums['X'] anywhere under ui/src/app/ is what puts X in the file. It is the REST twin of the Frame types (frontend), and it is the app's import, not a drift guard — the whole 2 MB schema stays generated and gitignored (.type-parity/). The enum census (scripts/verify-enum-parity-census.mjs) holds what remains written by hand: a string-literal union naming a backend enum must be claimed by an Assert<…> in a hand parity module or exempt with a reason, and an unclaimed one is a red whose remedy is the alias. A plain set-equality pin (Mutual<X, Schemas['X']>) is no claim, because it says what the alias says (#4183), so a union that stays hand-written stays for a reason its parity module states. A table keyed by the union (Record<NotificationKind, …>) still reddens on a new member, by design: that is a decision per member, not a mirror. _Avoid_: a hand-written string-literal union beside a backend enum; a generated Assert<Mutual<…>> pin for one (retired with the hand unions it proved); importing .type-parity/schema from app code.

Incident discussion

DiscussionComment (incident thread)
A single user-authored post on a discussion thread. The model is the polymorphic discussion substrate (DiscussionComment / DiscussionCommentRevision / DiscussionCommentAttachment, models/_discussion.py, table discussion_comments), keyed by (subject_kind, subject_id) — the incident is one consumer (subject_kind="incident"). Carries a body, an author, timestamps, and optional attachments. Allowed in every incident workflow status (draft / submitted / in_review / approved / rejected) and frozen only when WorkGroup.status = archived. Body is editable by the author at any time (each edit writes a DiscussionCommentRevision row); whole-comment delete is allowed by the author (soft-tombstone) or by holders of incident_comment_moderate (hse + admin) for moderation, with a recorded reason. The body is a Mention-bearing surface — @-tokens in the body fire Mention notifications on POST/PATCH per the diff-based emission rule. _Avoid_: note, reply, message, post, remark; IncidentComment (no such model — the thread rides the shared substrate).
DiscussionCommentAttachment
A file attached to a DiscussionComment. Stored in a table separate from IncidentEvidence for forensic separation — the formal H&S record (initial evidence locked at submission) must remain distinguishable at the data layer from discussion artefacts uploaded later. Same 25 MB cap and same upload helper as IncidentEvidence; soft-deleted via removed_at rather than hard-deleted, with a faded placeholder visible in the UI. _Avoid_: comment file, secondary evidence.
DiscussionCommentRevision
An immutable snapshot of a DiscussionComment's body taken when the author edits it. The revision row stores the *pre-edit* body plus replaced_at + replaced_by_user_id. Drives the "(edited)" indicator + clickable diff in the comment UI. Comments are never hard-deleted; revisions are never edited. _Avoid_: version, history entry, edit record.
Relationships
- An incident's thread is the set of DiscussionComments with (subject_kind="incident", subject_id=<incident>) — a service-layer relation, not an FK on IncidentDetail. - A DiscussionComment has zero or more attachments and revisions. - A new comment writes an IncidentEvent (event_type=commented); a delete writes IncidentEvent(event_type=comment_deleted). Self-edits do *not* write timeline events — the revision row carries that history.
Distinguishing from sibling concepts
- vs IncidentEvent (backend/app/models/_incidents.py): events are *immutable workflow markers* on a per-incident audit log (submitted, approved, …). Comments are mutable discussion content. The two *intersect* — a posted comment writes an event for timeline coherence — but they answer different questions. - vs IncidentEvidence (same module): evidence is the *formal H&S record* uploaded at the time of incident creation, locked when the incident is submitted. Comment attachments are *discussion artefacts*, separable by table at the audit layer. - vs Notification: a notification is a per-user inbox item that *may be triggered by* a new comment (the dispatcher pings thread-participants + reporter + all hse/admin). The comment is the content; the notification is the surfacing.
Permissions
Two new Permission enum members: - incident_comment — granted to member / coordinator / hse / site_manager / admin. The reporter can comment on their own incident regardless of role (matches the existing reporter-bypass pattern for can_edit / can_submit / can_delete in compute_incident_permissions). - incident_comment_moderate — granted to hse + admin only. Soft-deletes (tombstones) any comment with a recorded reason; writes IncidentEvent(comment_deleted).

Incident investigation

Investigation risk axes
Nullable likelihood × consequence (1–5 each) on an incident, rating recurrence risk to size the investigation — deliberately the same 5×5 arithmetic and derived-band vocabulary as Observation risk rating, not a second matrix grammar (Frida's 3×3 was rejected). Distinct from the incident's flat severity, which stays the *outcome* classification. _Avoid_: severity (the outcome axis); risk matrix unqualified (say which instrument).
Investigation level
The band (low/medium/high/critical) derived from the Investigation risk axes — how deep the investigation goes, not how bad the outcome was. _Avoid_: severity band (the observation/incident outcome vocabulary).
Incident cause
A typed causal factor on an incident: free-text cause + a type from a per-site seeded registry (the Observation category pattern), optionally pinned to a Barrier layer and/or a Timeline step. Repeatable — supersedes the single free-text root_cause, which freezes read-only. _Avoid_: root cause (the frozen legacy field).
Barrier layer
The Swiss-Cheese defence a cause breached — organisation | supervision | conditions | unsafe_acts | technical_failure. A column on Incident cause; the column is the app's Swiss-Cheese model. _Avoid_: layer unqualified; slice.
Timeline step
An ordered Chain-of-Events step (label + narrative) on an incident investigation; causes pin to steps; the terminal step is the incident itself by convention. V1 edits as an ordered list — the drawn-timeline canvas is a later rendering upgrade, not a schema change. _Avoid_: event (an IncidentEvent is the audit-timeline row — a different thing); step of the workflow (this is causal narrative, not FSM).
Investigator
The nullable assigned-investigator slot on an incident, set by HSE (typically at review start). "Classifier" remains a permission (classification amendment), never a slot. _Avoid_: reviewer (the band, not the assignment).
Incident closure (derived)
An incident is *closed* when its workflow is terminal (approved/rejected) and every child Action is terminal (accepted/cancelled) — computed at read time, never stored. Frida's "Implementation" phase = approved with open actions, which falls out for free. _Avoid_: case-closed flag (a stored bit was rejected — it can contradict the derived truth).

Observation

Observation
A Safety Observation Report: an on-site safety sighting — an unsafe act, unsafe condition, or safe behaviour (ObservationType) — raised by anyone on site, including anonymously (in-app or via a QR Observation capture link), and gated through HSE Observation triage before it reaches the wider site. Modelled as a WorkGroup(group_type= observation) with a 1:1 ObservationDetail extension and surfaced as the fifth Auxiliary pin kind — the heroicons eye glyph, tinted by the derived Observation risk rating band once published (pending pins render dimmed on the HSE-only view). It shares Incident's *shape* — a positioned pin with Position provenance, involved entities, free-text persons, evidence, a Mention-bearing discussion thread, an event timeline — but its own lifecycle: submitted → triaged → published-or-discarded, with map visibility derived from status + band vs the site's Observation visibility threshold (accepted safe_behaviour rows are threshold-exempt), never encoded in the status. Submission emails site hse users immediately; crossing into visibility at triage emails coordinators. Accepted observations feed the report exactly once via the Report observation queue (a section plus SOR summary stats); an open published Observation is a Now-anchored surface item — never a Noticeboard row. Decided 2026-06-11 (grill session), superseding the 2026-06-09 instant-publish identity: see docs/decisions/2026-06-11-observation-triage-rework.md. _Avoid_: incident (the *something happened* record; Observation is the *something was seen* record); the v1 sense "calm instant-publish operational flag" (superseded); inspection / action (sibling surfaces — and note the boundary: an inspection Item result is deliberately never promoted to an Observation); note, sighting, finding.
ObservationStatus
The Observation lifecycle enum: pending_triage (the default at creation) → open (HSE accepted) or discarded (HSE judged not actionable; restorable), with open ⇄ resolved reopenable as before. Deliberately does not encode visibility — who sees an observation is derived from status plus Observation risk rating band vs the Observation visibility threshold, so re-rating never churns status. Distinct from soft-deletion, which remains a separate reversible act reserved for spam/test data, not a triage verdict. _Avoid_: published / logged as status values (visibility is derived); state (overloaded); incident status (a different enum).
Observation triage
The HSE act (hse / site_manager / admin) of reviewing a pending_triage Observation: accept or discard, rate or re-rate the Observation risk rating (a rating is required to accept an unsafe row — amended 2026-09-09), set or correct the ObservationType and Observation category, and reposition inaccurate pins by drag or Position rectification (routine for no-GPS anonymous submissions, which arrive on an Inferred location, and for any Rough position). Stamped triaged_by_user_id/triaged_at; performed from the triage queue in the Health & Safety panel. Coordinators never triage — the gate exists so HSEs sift observations before coordinators see them. _Avoid_: review / approve / reject (Incident's workflow vocabulary); moderation (the comment-thread term).
Observation risk rating
The 5×5 risk matrix carried by unsafe observations: likelihood (1–5) × consequence (1–5) → score (1–25) → a derived band low/medium/high/critical (fixed boundaries 1–4 / 5–9 / 10–15 / 16–25). The submitter may rate at creation via a colour-zoned tap-grid that sits in a fold collapsed by default on every authoring surface — *Rate the risk (optional)* / *HSE will rate it if you don't.* (absent for safe_behaviour); HSE rates or re-rates at triage and the band follows — Accept is gated on a rating for unsafe rows (*Rate the risk to accept*), Decline never is. A row that arrived unrated is an ordinary pending row marked Unrated (muted text, never a pill) and sorts by recency beneath the submitter-rated rows; the initial submitter rating is preserved for calibration and is NULL when they did not rate (amended 2026-09-09, map #3779; ADR 2026-06-11-observation-triage-rework D3; spec docs/plans/2026-09-09-observation-rating-fold-and-position-rectify-spec.md). A safe_behaviour is rating-less, map-less and action-less: it carries no corrective Action, because there is nothing to correct (amended 2026-08-31, #3617; ADR 2026-06-11-observation-triage-rework D4). Triage refuses an action block on a row accepted as a safe behaviour by type (observation_action_not_for_safe_behaviour) and does not offer the step at all — both reading the type the row is being *accepted as*, so reclassifying in the same act moves the step with it. The band — not the raw score — is what pins, filters, queue sort, and the Observation visibility threshold speak. _Avoid_: severity unqualified (Incident's flat enum — same band names, a different instrument); priority, urgency.
Observation visibility threshold
The per-site band (Site.observation_severity_threshold, default medium, tunable by hse / site_manager / admin) gating coordinator/member/viewer map visibility of rated (unsafe) observations: visible ⇔ status ∈ {open, resolved} and band ≥ threshold. safe_behaviour rows carry no band and are threshold-exempt — visible to every role once accepted (decided 2026-07-13, grill session; before that their NULL score never qualified, so positives were HSE-only). hse/admin see everything including the pending queue; a signed-in reporter always sees their own. It is also the default for the Report observation threshold, but no longer binds it — the one knob that served both surfaces was split when the report needed to reach below the map (decided 2026-06-12, see docs/decisions/2026-06-12-observation-report-threshold-split.md). _Avoid_: severity threshold unqualified; "report inclusion" (that is now the separate Report observation threshold).
Report observation threshold
The per-report band floor governing which accepted observations appear in the SOR report section — a separate knob from the Observation visibility threshold, persisted in the report section's form_data, defaulting to the site threshold (so a fresh report mirrors the coordinator map). Lowerable below the site threshold by anyone who can build the report (coordinator and above): below-threshold accepted observations are noise-filtered, not confidential, so an HSE-reviewed SOR may deliberately be more complete than the live map. It moves the band floor only — pending_triage/discarded rows never reach the report at any floor. safe_behaviour rows carry no band and are governed instead by a per-report *include safe behaviours* toggle (stats-only otherwise). Manual per-row check/uncheck (force_included/force_excluded) survives floor changes — the floor is a default line, not a reset. _Avoid_: visibility threshold (that one gates the map); a report-mode "severity filter".
Report observation queue
The exactly-once feed of accepted observations into reports. An Observation joins the queue when Observation triage accepts it and is consumed by the first exported report whose observations section offered it — printed, force-excluded, or left unchecked below the Report observation threshold floor alike: every offered row was surfaced to the report builder, so an exclusion is a recorded decision, not a crack. Draft reports never consume (abandoning a wizard returns nothing to limbo); each consumed observation records which report carried it. This replaced the observed-on-the-report-day window, which could never match — reports target tomorrow while sightings live in the past, so pre-queue observations never appeared in any report once triage lagged the sighting by a day (decided 2026-07-13, grill session). _Avoid_: report window (the temporal entity window, a different axis); backlog (the pending-triage pile — that is upstream of this queue).
Still-open observations
The report's non-consuming register of accepted unsafe observations still open that an earlier exported report first carried — the sibling group beside the Report observation queue, inside the one Health, Safety & Environment section. Disjoint from the queue by construction (the queue offers reported_at IS NULL, this register lists IS NOT NULL), so a row is offered for stamping or listed as still open, never both. Each row is a compact line — ref, band, description, location, corrective-action owner/due, first carried (a backfill sentinel prints "before the queue"), days open counted from Observation triage acceptance — oldest-open first, identical in the report panel, the PDF and the DOCX. It never stamps anything and offers no checkboxes: a report may drop the whole group through the section's include_still_open toggle, never one open hazard, and a row exits only by becoming resolved (reopening re-enters it). Capped at 200 rows with an explicit overflow line; the stats block stays batch-scoped and states still_open_total beside it (decided 2026-08-21, grill session — see #2984 and the amendment on docs/decisions/2026-07-13-observation-report-queue.md). _Avoid_: "carried" / "carry-forward" (the report table carryforward mechanism is an unrelated copy of prose rows, and it skips itself once a section has user content); backlog (the pending-triage pile).
ObservationType
Repurposed 2026-06-11 to the SOR three-way: exactly unsafe_act / unsafe_condition / safe_behaviour, now required at creation (three big buttons on every form, including the anonymous one). The v1 hazard-domain values (housekeeping, obstruction, …) moved to Observation category. safe_behaviour — the positive observation in customer speech and report labels — carries no risk rating; once accepted at triage it is visible to every role (a green eye pin, threshold-exempt — amended 2026-07-13, it previously never reached the coordinator map) and feeds the report's positive-observation ratio. _Avoid_: category (that is the hazard domain, a separate field); the v1 value set; kind, nature.
Observation category
The hazard domain of an Observation — a per-site, DB-seeded registry, not an enum (seeded: working_at_height, ppe, scaffolding, electrical, manual_handling, housekeeping, plant_and_equipment, environmental, security, access_egress, other; client-tunable without a migration). Single-valued and nullable at submission — anonymous reporters may not know the right bucket — and set or corrected at Observation triage. _Avoid_: bare "category" unqualified (collides with Clash category); tag, label.
Anonymous observation
An Observation whose reporter is truly unrecorded — reporter_user_id NULL and the audit identity suppressed — whether it arrived via the QR form or a signed-in user choosing *submit anonymously*. No sealed/hidden identity column exists, by design: the anonymity promise is real. Accepted consequences: no see-own/edit-own powers and no notification backflow for the reporter. A non-identifying submitted_via (app / app_anonymous / qr) is kept for triage context, plus an optional volunteered contact field. _Avoid_: pseudonymous (implies a recorded identity); unattributed.
Site boundary
A nullable site-level polygon (authored with the map drawing tools by the coordinator/hse/admin band) marking the operational perimeter — config, not map content: deliberately outside the Reference feature pipeline so import/versioning/bulk-delete never touch it. When unset, the active site map's bounds serve as an explicit degraded fallback. First consumer is Geofenced capture entry; the concept is generic — any future "is this on site?" question (Blocker whole-site scope, stock reasoning) may reuse it. Decided 2026-07-06 (grill session). _Avoid_: geofence (the *check* against the boundary, not the polygon); perimeter, site extent (the raster Site-map capture bounds — a scan footprint, not this).
Geofenced capture entry
The tokenless alternative to the QR poster: one global /observe URL where the server resolves the reporter's GPS fix against Site boundarys (buffered by fix accuracy) and serves only the matched site's capture form — one match goes straight in, several show a picker of matched names only, zero hands off to the poster path. Near-miss site names are never returned: non-enumerability is preserved by physical presence rather than token possession. The fence gates resolution only — a served form's submission is never rejected on location; the server stores containment facts (in-boundary, distance, accuracy) as provenance with submitted_via='geofence', and spoofability is accepted with Observation triage as the firewall. Successful resolution mints a short-lived session token required by the write endpoints (an ephemeral Observation capture link analogue). Decided 2026-07-06 (grill session). See docs/decisions/2026-07-06-geofenced-anonymous-observation-entry.md. _Avoid_: geofenced observation (the observation is ordinary; the *entry* is geofenced); GPS gate (resolution-only, never a submit gate).

Corrective actions — the close-the-loop hub

Action
A corrective work item raised when something on site needs fixing, owned by one responsible company (a contractor, never a user, at creation) and tracked through a review-gated lifecycle to HSE sign-off. A standalone entity — not a WorkGroup extension, not a Task — carrying a description, due date, per-site serial number, optional Action priority, and an optional Parent reference. Members may only route within their own ∪ supervised companies; coordinator/hse/site_manager/admin route to any (the sketch's COMPANY SCOPED vs ALL). Map presence is a badge on the parent's pin, not an own pin. _Avoid_: task (the per-user ping that *points at* an Action); corrective action triple (the frozen ObservationDetail seed fields); action item, todo.
Action lifecycle
assigned → pending_review → accepted, with cancel reachable from either live state. Creation always names a responsible company, so a new Action lands in assigned; Action close-out moves it to pending_review; HSE accept terminates; reject is an audited *transition* back to assigned (reason required, count kept) — the rework loop is not a state. cancelled is the terminal escape (an extension beyond the source sketch). Overdue is derived from the due date, never a state. _Avoid_: open/resolved (Task vocabulary); draft (no draft state exists).
Action close-out
The responsible company's evidence-backed claim of completion: any member of the responsible contractor (or HSE/admin on-behalf) submits a solution narrative plus photo evidence — hard-required; stamped with date-completed and who closed out. Enters Action review. _Avoid_: resolve (Task verb); complete (Inspection vocabulary).
Action review
The HSE sign-off gate on a closed-out Action: accept (terminal) or reject back to assigned with a required reason. The review band is hse + admin + site_manager, mirroring the incident review split. _Avoid_: triage (Observation vocabulary); approve (the incident gate's verb).
Action priority
Optional low/medium/high, chosen by HSE — required when the Action is spawned by a failed inspection item — and the input to due-date defaults. _Avoid_: severity (an outcome scale); band (the observation instrument).
Parent reference
The optional polymorphic link from an Action to the finding it remediates — an Observation, an incident, or an inspection Item result. Optional by design (ad-hoc actions are legal) and one-to-many (a parent may carry many Actions; the observation triage prompt raises one by default, prefilled and skippable). _Avoid_: target entity (Task vocabulary).

Inspections

Inspection
A templated safety audit run by an HSE inspector against an Auditee company: checklist items answered with comments and photos, a validation-gated submit ("submit available iff valid"), and a corrective Action offered per failed item at completion (the offer is a per-row prefill in the review step — several fails may be merged onto one Action, and the raise happens inside the submit transaction). Two-state lifecycle: in_progress → completed — submit is terminal; the inspector *is* the authority, so there is no separate approval step. Completed inspections are read-only, site-visible, scored, and PDF-exportable. A completed inspection may be removed from the register by the inspection_run band with a required reason — a reversible register act (deleted_at / deleted_by / deleted_reason), never a hard delete: the row, its item results and evidence survive, the by-id read still serves it in its removed state, and Restore is the mirror verb. Removed = did not happen for counting: every counting surface (the list and its total, the diary AUTO cell, the H&S tile badge) applies the one ON_REGISTER clause declared beside the kind's read grant. Each act is recorded on the audit trail (inspection_removed with the reason / inspection_restored). The creator hard-delete of an in-progress run is unchanged (#3939; ADR 2026-07-06-inspections-module D3 amendment). _Avoid_: audit (colloquial); survey; observation (the sibling ad-hoc surface — inspection items never become Observations).
Inspection template
The admin-authored checklist an inspection runs against: named, site-scoped, and versioned — editing mints a new immutable version (sections + items + pass threshold) and a run references the exact version it used, so history never mutates. Per item: question, section, comment required/optional, evidence-required (⇒ photo). _Avoid_: inspection type (Frida's column name for the same idea); form; checklist unqualified.
Item result
One answered checklist item on an inspection run: a three-way answer — pass ✓ / fail ✗ / N-A — plus comment and photo per the template item's flags. Deliberately inspection-internal: never promoted to Observation rows. A fail feeds the submit-time action confirmation step. _Avoid_: finding (unqualified); observation (the sibling entity).
Pass score
The completion-time score — passes over non-N/A items, judged against the template version's pass threshold — denormalised onto the completed inspection. _Avoid_: risk rating (the observation instrument).
Auditee
The company an inspection audits: a required reference to the site's contractor registry (a subcontractor or the principal contractor), never free text. Drives the responsible-company prefill of fail-spawned Actions and the completion-notification audience. _Avoid_: contractor name (the Frida free-text field this replaces).

Contractor discipline

Discipline
A contractor's trade classification — an unordered set of values from a fixed global vocabulary: civils, structure, envelope, mechanical, electrical, fire, building_services, fit_out, logistics, other. Multi-valued by domain necessity: an M&E firm is one firm with two trades, never two contractor rows (contractor identity is load-bearing for colour, clash predicates, oversight and audit). No primary value. building_services is fenced to the specialist services tail (lifts, BMS/controls, security and access, ICT/data, lightning protection) — never a home for plain mechanical, electrical or fire work, which have their own values. logistics is a *function* the diary must record (welfare, deliveries, cranage), not a trade. Site-specific packaging ("the civils team oversees the frame works here") is a contractor oversight edge, not a discipline — the tag is what the firm's own hands do. Drives Daily Site Diary trade-section routing only; all other consumers are deliberately deferred. Every contractor must end up with at least one; creates and edits can never reach zero. See docs/decisions/2026-08-09-contractor-discipline-classification.md. _Avoid_: MEP / M&E (a firm holding both mechanical and electrical, not a value); category (a clash-engine noun); trade tag (free-text connotation).

Work tracking — lines, dependencies, snags, lost time

Work line
A first-class, contractor-owned line of programme work: the anchor for Work dependency edges *and* for close-out. Two births, one noun: - imported: every task and milestone of a Programme becomes a line the moment its revision is ingested. It is keyed by (programme, activity code), its window is the file's printed dates, its status the file's, its contractor the programme's, and its heading the file's own band (derived, never stored). Its plan fields (name, code, planned window) are read-only because the file is their one writer, and a Programme update keeps them equal to the file. - hand-authored: by the coordinator band, or by promote-from-token. Such a line has no programme, is unique per site × contractor × code, and keeps editable plan fields.
Token attachment
A placed Token's link (work_line_id) to the Work line whose work it carries out. A line gathers many tokens over its life, often concurrent and in different places. A token's schedule is its own (default today when placed from a line), and the line's planned window is only a reference. The token's contractor is the line's. Doors: drag a bar from the Plan Gantt onto the map, the Bar detail's "Place a token from this line", the line search in every token modal, and the map right-click *Attach to work line…*. Attaching fills an empty Line place, and is what lets a successor raise a delay (Dependency violation). A line-attached token counts under its contractor in Reality without an issued permit. Decided 2026-10-30 (map #3954, ticket #3959). _Avoid_: link (the dependency edge's informal name); assignment (P6's resource vocabulary).
Line-token roster
The one declaration of which token kinds a Work line carries — exactly the day axis (worker, plant, active area, roving crew) — and of each kind's facts: its geometry (a roving crew has none, so it tends a line without placing it), its zone column, its broadcast spelling, and two facts that deliberately differ on an exclusion zone or a laydown: activity evidence (every row of every kind — what the dependency evaluator reads) and headcount (only someone on site — what Reality's line runs count). Every work-line, programme, planner and dependency reader asks it; a module there that lists token models itself is red (backend/app/services/entity/line_token_roster.py, #4063). Beside it, the line-token membership answers which ROWS of those kinds a set of lines carries (work_line_id naming the line), narrowed by the fact a reader names — every token, activity evidence, or not headcount — as one read (light rows, or whole entity rows per kind), its WHERE term, and the correlated per-line predicate; no work-line, programme, planner or dependency reader filters token rows by line or walks the roster for them itself (backend/app/services/entity/line_token_membership.py, #4168). _Avoid_: token models (the retired local tuples).
Line place
The building or zone (and floor) a Work line sits in. It is set by the first attached token placed inside one (its Token place), or by hand, and is never moved by later tokens. It is never read from plan codes or WBS names. A line with none sits under "No place yet" in the Plan Gantt's Area order. Decided 2026-10-30 (map #3954, ticket #3959). _Avoid_: band place / mapped place (the retired place-recovery machinery).
Line change
What a writer of Work lines announces (the work-line and programme code, the schedule-group epilogue, the token lifecycle and the contractor delete) when one changes in a way its Work dependency edges care about: tokens attach or detach, the line closes or reopens, its planned dates move, or lines are about to go. It is announced downward through the line leaf's port (backend/app/services/line_leaf/changes.py, LINE_CHANGES), and the dependency evaluator, which sits above the line code, is its one listener: it binds itself when it loads and decides what each change means, the episode broadcast included, and it binds once: a second listen is refused. The line code never names the evaluator; the import-direction census holds that (#4167). The cold-entry census (tests/test_entry_point_cold_import.py) holds that every process entry that loads an announcer binds the listener when entered cold: the three container entries by name and every __main__ entry, with the line-free entries named as shrink-only declines (#4194). _Avoid_: line hook (the evaluator's side of it); line event (a strip entry on the line's own timeline, a different thing).
Work dependency
A hand-authored or programme-imported edge WorkLine → WorkLine — never tokens (tokens churn; the line endures). Carries a link type (FS|SS|FF|SF, mirroring P6; hand-authored edges default FS) and a signed lag (stored in hours verbatim, evaluated as round(/8) calendar days) — the #1205 generalisation, pulled by the programme-import epic (2026-07-21; FS-only was the original shipped shape). Same-contractor edges permitted; self-edges, duplicates (same pair and link type), cross-site edges and cycles rejected (DFS at insert); transitive redundancy tolerated. Edges are immutable (edit = remove + re-add); deleting a line confirm-and-cascades; linking an already-complete predecessor is legal (Born satisfied). The contract per link type (FS: "B must not start until A is complete") yields three derived, never-stored conditions: *violated*, *unverified start*, *satisfied* (kept as record; completion notifies the successor's contractor). Authoring rides the one shared work-line permission (coordinator band; contractors never). Imported edges are born at ingest, one per staged relationship whose ends are both lines. A relationship that cannot be an edge (cycle, duplicate, non-line end) is dropped and counted, never failing the ingest. Imported edges carry provenance, are read-only (the Programme is their one writer) and are kept equal to the file by each Programme update. Hand-authored edges are update-invisible and are the only ones a remove verb touches. They are authored from the Bar detail's + predecessor / + successor search, across any programmes. Lag is entered in days and stored × 8 h. A link between programmes is a description, not a second noun (amended 2026-10-30, map #3954). See docs/decisions/2026-07-17-work-dependencies-and-violation-surfacing.md (+ the 2026-07-21 amendment in 2026-07-21-programme-revision-sync-and-edge-import.md). _Avoid_: token dependency (rejected shape); relationship (the staging row ProgrammeRelationship — an imported edge is its promoted consequence).
Dependency violation
The derived contradiction of a Work dependency observed on site — not a clash (clash stays geometric/emergent; a violation is *declared logic contradicted*). A dedicated graph-driven evaluator (on-write + sweep) persists violation episodes (own table; the edge stays stateless) that surface as a third noticeboard item kind above red — never ignorable, never suppressible; the only remedy is fixing the graph or the work. No token on the successor, no episode: *a claim may quiet, only an observation may alarm* — a plan's dates or statuses alone never raise one. Any attached token is the observation, laydown and exclusion ActiveAreas included: an attached area of any type means the activity has physically started (the line-token roster's *activity evidence* fact, #4069 ruling) — so a laydown on B may raise an episode, and a live laydown on A means A is not dark. (It is not *headcount* — see Plan Gantt.) Two kinds, one episode shape: *violated* (B's tokens scheduled against A's window — co-presence when both are tokened, B booked before A's planned finish otherwise) and *unverified start* (B booked or on site while A is unclosed with no live/future tokens — assume the worst; pending while B's booking lies ahead, active once it arrives). A bare successor's would-be violation is paint, not an episode — the Gantt marks the bar *waiting on A*. Both carry a one-click, pre-filled declare-Blocker handoff: the violation surfaces automatically, a human declares the blocker. The close-out duty ladder escalates FYI (edge authored) → nudge (last predecessor token ends unclosed) → violation (B arrives). Presentation: user copy says "delays" — "delay" replaces "violation" in *all* user copy (a *delay* is the planning concept: a declared dependency contradicted; internal/ schema/event names keep violation), and delays *create* Blockers — the blocker stays the sole timed-stoppage record, so a "Delays"-named stoppage surface is a Blockers surface. The pin is the hazard diamond; the noticeboard renders an uncollapsible emergency banner — its first five cards, the rest behind Show all (N), the header counting every open delay (2026-11-15 ruling, #4273); map paint is place-centric (place-band glow, token-less). RuleSeverity is untouched. See docs/decisions/2026-07-17-work-dependencies-and-violation-surfacing.md. _Avoid_: clash (different machinery and severity vocabulary); mega-red (a prototype nickname, not shipped copy); blocker (a violation *suggests* one; only a human declares it); slip (a bar's lateness against its own plan, from the variance authority — not a delay).
Snag
A contractor's own-work defect caveat — work not constructed to spec, flagged by the team that built it while recording work completion (the "wee box" riding every record-work-completion gesture, daily or closing; there is no standalone raise button). A snag can never be raised against another trade: a cross-trade grievance is a Blocker. Substrate: a WorkGroup sibling (SnagDetail), anchored by a polymorphic token ref + work_line_id snapshotted at raise. Two stored states, open → closed; the *"complete · N snags open"* caveat (Tony's "98%, not 100%") is derived, never stored — the roll-up to 100% is the join emptying. Close is a per-snag human tick — via a Resolving token's wee box or a direct tokenless close — and both paths sit behind a hard photo gate (422 snag_closeout_photo_required; the completion photo is dual-purposed). Close self-certifies: no verification state — a deliberate departure from industry two-step close (verification migrated to blockers). Soft-delete is the mistake path; no reopen edge — a resurfaced defect is a fresh snag, fresh clock. Snag clocks (raised_at → closed_at) are responsiveness metrics and never feed lost time. Visibility: owning team + principal side (HSE deliberately out — snags sit on the commercial axis, not the safety axis). See docs/decisions/2026-07-17-snag-own-work-caveat.md. _Avoid_: defect (Defect is now a first-class contractual noun — different parties, register and legal weight; no promotion path either way) / punch item / NCR (industry imports with heavier workflow); snag list / snag board (there is no standalone board — snags live inside the Completions view); blocker (obstruction, not defect).
Resolving token
A Token placed to fix open Snags. The *snag* holds a re-pointable polymorphic ref to it — so "fix scheduled" is derived from the live ref, never stored, and one corrective visit can fix many snags. It inherits the original work line by default; its record-work-completion wee box carries per-snag "fixed?" ticks (a shared token closing 3 of 4 is legal), and closing rolls the completion caveat away (98 → 100%). _Avoid_: rework token, corrective action (Action is the H&S close-the-loop entity — unrelated machinery).
Lost time
The unified, read-only rollup the commercial side reads: crew-hours = actuals window × stood-down headcount, derived, never stored — and the totals count blockers only (Colin: "lost time is the sum of those little blockers"). Snag rows appear as clocks-only responsiveness metrics with zero crew-hours. Capture is one nullable stood_down_headcount on the blocker detail (defaults from affected worker refs, editable; multi-crew = multiple blockers); the blocker's actuals window is the loss window, read against the record's lifecycle — three states, not two: resolved (a declared resumption has elapsed; the only costable one), live (none elapsed and the record still open — an age, never a loss) and undeclared (closed with no restart ever recorded, so no end, no duration, no crew-hours, and out of both totals with the omission counted beside them). Attribution: *loser* = the blocker's contractor; *responsible* = triage-accepted blame only, stored at triage confirm (pre-derived from the cause chain; ratified 2026-07-17). Served by read-only GET /api/lost-time behind lost_time_view; reviewed in the Lost time section of the Commercial full-screen surface (I) — a resolving door: lost_time_view lands on the site-wide ledger, blocker.view + a firm membership on the own-firm position view — with linked-brushing map coupling — choropleth off by default, a "review range" pill that never pokes the scrubber.
LedgerWalk
The Lost time ledger's one pass over the admitted rows, as a value. The pass was always one walk feeding a dozen carriers; what it had no name for was its own *result*, so every carrier the assembly needed was another accumulator threaded through the loop and another argument threaded through the assembly. walk() produces exactly one LedgerWalk and assemble() consumes exactly one, so a block that wants a new figure asks the walk for a field rather than growing the loop a parameter. It is frozen, because the walk is over by the time anyone holds one: accumulation happens inside walk, every consumer reads. (The collections it holds are ordinary lists and dicts — freezing fences *re-binding*, which is the seam that matters.) The three unfiltered indexes ride here too — the chain rows, the stopped-at map and the place accounts are each derived once per request, before the loop, and read by several assembly blocks; a second derivation is exactly the *"there is one answer to where a record was"* failure they exist to prevent (services/lost_time/lost_time_service.py, spec §3.3). _Avoid_: "the loop" (it is the loop's *result*); accumulator (a LedgerWalk holds the accumulators and is not one); ledger payload (the assembled wire shape, downstream of this).
Close-out (work sense)
An umbrella naming three distinct gestures, disambiguated by object: work-line close (the load-bearing "can the next trade start?" verb on a Work line), daily completion (a Completion record — optional and silent), and finished-early (an explicit whole-token early-done signal that removes remaining scheduled occurrences behind a confirm-N dialog — the *nuke*, never a ghost). Token expiry ≠ completion: a lapsed window proves nothing about the work. Distinct from Permit close-out (a permit lifecycle transition) and Action close-out (H&S). See docs/decisions/2026-07-17-close-out-two-verbs.md. _Avoid_: close out (bare, without naming which gesture); completion (only the daily record); expiry (a schedule fact, not a statement about work).
Work candidates
The shared suggestion seam every token-tagging mobile flow picks from: the actor's own or oversight-inclusive day-active work (POST /api/sites/{site_id}/work-candidates, scope=own|oversight), derived server-side from membership. "Mine" is eligibility, "near me" is ranking: an optional device fix (POST body, never a URL) only *orders* the list and computes the near_you fact — proximity never adds or removes a candidate, so denying location loses ranking, never function. Adopters: blocker raise, record-completed-work (snag wee-box inherits). Distinct from affected-suggestions (cause-anchored, cross-contractor, coordinator- facing). Decided 2026-07-18 (wayfinder map #1293); see docs/decisions/2026-07-18-transient-geolocation-privacy.md and docs/plans/2026-07-18-geolocation-work-candidates-spec.md. _Avoid_: nearby work (the ranking, not the universe); suggestions (bare — collides with affected-suggestions).

Bookable resources — exclusive, calendar-booked equipment

Bookable resource
A per-site catalogue row for a piece of shared equipment that can be booked (a hoist, a cement mixer): a name, a Resource type, a colour, its Bookable hours, and a retired mark. Added in the app by the manage band (admin, coordinator, site manager), never by a code change. Two hoists are two resources; there is no capacity pool. Retiring one cancels its future Bookings and keeps its past ones. Short form on the surface: *resource*. _Avoid_: plant (the placed, contractor-owned kind — a resource is not a Plant row or a PlantType value); resource in the P6 sense (a programme file's labour/material resource); asset; shared token.
Resource type
The site-defined kind of a Bookable resource (hoist, mixer, …). It gives the resource a glyph and lets the calendar filter. Site data, not a compiled enum: a site may add a type nobody anticipated.
Booking
One firm's exclusive window on one Bookable resource: a contractor, a start and an end, an optional note, an optional plain reference to a Permit. Always timed (15-minute grain, no all-day), may cross midnight. Two bookings on one resource never overlap — a hard refusal, not a clash; back-to-back is legal. A cancelled booking is deleted and the audit trail is the record. In v1 only the manage band books; contractors read every firm's bookings by name. Its status has one value, confirmed, the seam a later request-and-approve flow extends. _Avoid_: slot (the empty stretch, not the claim); reservation; *booked* in the Work dependency sense (a token scheduled against a line); token (a booking is not an entity kind).
Out of service
A Booking with no contractor and a required note giving the reason (inspection, breakdown). Same exclusivity law, drawn hatched, notifies nobody. There is no separate blackout concept.
Bookable hours
A Bookable resource's weekly hours per weekday, in site time. The calendar shades the rest. A booking outside them is allowed with a warning, not refused. No per-date exceptions — Out of service covers those. Distinct from a Shift, which only seeds creation defaults.
Booking series
Bookings created together by a repeat, sharing a series_id. Creation is all or nothing: if any occurrence collides, nothing is booked and the colliding days are named. Afterwards each occurrence is an ordinary booking. Not a schedule group — that machinery belongs to the entity kinds.

Daily site diary — the per-day multi-author record

Site diary
The per-day site record: SiteDiary, unique per (site, work_date), holding append-only immutable attributed Diary entry rows and rendering through the report template + PDF machinery via an adapter — never a ReportSession. Multi-author (whole-diary write grain within the gate), partially machine-answered (AUTO cells attributed to SimOps, no entry rows), published once per day by the Publish sweep. Gate: verified membership + contractor_id == site.main_contractor_id + write-band role — no role-band side door; subcontractors get nothing; the client reads the published PDF only. _Avoid_: consolidated report (the incumbent noun — collapses, nothing is merged); daily report (a ReportSession derivation, a different noun); diary as a report template (it renders *through* templates, it is not one).
Diary entry
One append-only immutable row: author, server-assigned written_at, shift_id captured at write by containment, section/question binding, and a kind — answer · nil_report · photo_dump · photo_exclusion · erratum. SUGGEST-backed answers store source ids plus the rendered-text snapshot at write ("stores what it rendered"). A nil-report ("nothing to report", attributed) is a different fact from a hole (no entry at all) — never string-matched; holes publish as visible gaps. _Avoid_: edit / amendment (no update path exists — the only post-publish kind is the Erratum).
Working period
The diary's day: [D @ boundary, D+1 @ boundary) site-local, boundary a per-site setting (diary_day_boundary, default 06:00). work_date is the period's day label. CompletionRecord.work_date derivation aligns to this boundary (an 01:00 close-out stamps the prior day) — the photo harvest keys on the work-day stamp, never uploaded_at. _Avoid_: calendar day (midnight-bounded — the site-TZ day contract's algebra applies, but the diary's boundary is the site's, not midnight).
Publish sweep
The boundary tick that ends a diary's day: computes AUTO cells (frozen into the revision's snapshot — never recomputed, so re-renders cannot change the body), renders the crane snip server-side, renders the immutable PDF (Rev A), and fires distribution (derived audience ∪ SiteDiaryRecipient top-ups, PDF attached). There is never a publish button; empty and hole-y days publish anyway — the gappy PDF is the enforcement. _Avoid_: submit / approve / sign-off (no such step exists anywhere).
Erratum
The only thing a published diary admits: an append-only attributed row, server-assigned timestamp, diary-write gate, no time window, photos allowed. Renders only in the Errata appendix of a versioned re-render (Rev A/Rev B, drawing-style; all revisions retained): the body never changes across revisions and holes stay holes forever. Humans may erratum against an AUTO cell — both stand, each attributed to its actual author. Re-distribution re-fires the morning-email machinery flagged as a revision. _Avoid_: amendment / correction (implies the record changes — it never does); addendum (a detachable loose sheet — rejected).

Defects — the imported contractual quality register

Defect
A contractual quality event: work not in accordance with the Scope, notified between the contracting parties under NEC4 (defined 11.2(5); corrected cl 43, accepted cl 44, uncorrected cost cl 45). First-class in SimOps as the seventh WorkGroup sibling (DefectDetail — WorkGroupType has seven members, defect the last minted), but on a site whose contract names a communication system (cl 13.2 — South Clyde names Sypro) the SimOps record is derivative: a defect is raised and accepted in the named system first and arrives by per-contractor CSV/XLSX import (upsert on (site, contractor, event_reference); rows are never deleted on import — statuses move, registers don't shrink). The upload's contractor scope *is* the defect's contractor; parties are not modelled. Status is the observed register vocabulary (awaiting_correction → corrected → acceptance_proposed) with closure a separate closed_at/closed_by overlay — "corrected but not closed" is one party's claim, not settled fact; open = closed_at IS NULL (the diary's QA/QC count is this query). Visibility mirrors Sypro's private pages: owning contractor's members see their own register; principal set (commercial in — cl 45 money; HSE out — quality axis, not safety) sees all; not main-contractor-gated, unlike the site diary. Native lifecycle (raise/correct/certify/close in SimOps) is the design goal and is deferred by name. A defect is not a Snag and there is no promotion path — escalation happens in the named system, never by conversion. See docs/decisions/2026-08-10-defect-domain-object.md. _Avoid_: NCR (ISO 9001 vocabulary, not carried); Defect Notification (Sypro product noun); snag (own-work caveat, different register and legal weight); punch item.
Defect evidence
A close-out photo citing an imported Defect — *this photograph evidences the correction of defect X*. The twelfth file-evidence kind (DefectEvidence), the snag's evidence row minus its phase tag: phase exists to feed a close gate, and SimOps has no close verb for a defect to gate. Created by one verb only, adoption: a photo already attached to a Completion record gains a second row sharing its storage_key — one blob, several duties, no byte copy — so the bytes outlive any one of those rows being deleted. A reference, never a raise: it changes no fact about the defect (not status, not closed_at, not prevents_completion, not the diary's QA/QC counts), which is precisely why it sits outside the no-promotion-path ruling — annotating a derivative record is not a Snag becoming a defect. Offered against open defects only (closed_at IS NULL, so "corrected but not closed" IS offered — that is where a contractor's supporting photo belongs); many defects may cite one photo. Written by whoever can both *see* the defect and attach the photo (defect.view ∧ entity.edit) — no permission token of its own. See docs/decisions/2026-08-10-defect-domain-object.md D7 (amended 2026-08-21). _Avoid_: defect photo (the register's own Sypro documents are not this); raise (nothing here mints a defect); proof / verification (a photo is one party's claim about a correction, never its acceptance).

Programme import — staging, lines at ingest, programme updates

Programme
One contractor's plan as handed over in a file: the durable, site-scoped identity a Programme revision belongs to, never itself a file. It carries a required contractor, the contractor of every Work line the programme mints, re-stamped on every line when changed. A programme speaks for one contractor even when it describes others' work: a main contractor's master programme is that contractor's programme. Uploaded by work_plan.manage for any contractor; named from the file's project node (root WBS name, else proj_short_name, else the file stem) unless a name is typed. The first question of the upload is "New programme, or an update to an existing one?", never guessed. A site holds several, one per file lineage, and their headings never merge. The plan layer of the Work home's Plan Gantt shows programmes; each has a programme header carrying its Programme age. Carries current_revision_id and the Logic pointer. Amended 2026-10-30 (map #3954, ticket #3961). _Avoid_: series (the model's word that leaked onto the card); master programme (a programme under the main contractor is just a programme); plan for the uploaded thing (plan is the Gantt layer); project (P6's noun for the file contents); default contractor (the contractor is required; it is simply the programme's contractor).
Programme revision
One immutable handed-over programme file (P6 XER, a native Powerproject .pp, or a PDF print), staged as WBS nodes + activities + relationships that are never mutated after ingest. revision_kind (baseline / progress_update / ce_impact) is metadata — CE fragnets are revisions of the *same* series. The raw file lives in object storage (ultimate provenance). source_format (ProgrammeSourceFormat: xer / pp / pdf / xlsx — xlsx reserved, no v1 code emits it) is the single fidelity switch: xer and pp are the two full-fidelity profiles (identical on every question a seam asks — logic, wall-clock dates, absence is a signal); a pdf revision is *degraded* — lines + dates only, day-precision, and Edge-blind. The door infers the format by content sniff (SQLite magic / ERMHDR / %PDF), never by extension; bytes matching none are refused at the door. Amended 2026-09-07 (map #3749, ADR 2026-09-07-programme-import-second-source-format-powerproject.md). revision_kind is retained metadata that nothing reads and no form asks for; rev_label is optional, prefilled from the file. A revision whose ingest failed may be deleted; a ready revision is undone only as the latest Programme update (amended 2026-10-30, map #3954). _Avoid_: version (feature-versioning vocabulary); import (the act, not the artifact); "Powerproject fidelity" (there is no fourth axis — what the file lacks is a per-row fact).
Programme update
Uploading a new revision of an existing Programme. The upload *is* the attended act: the revision applies itself as the ingest job's last step — every imported Work line takes its activity's name, code and printed dates; new activities become lines; imported edges become the file's relationships; a vanished activity's line is deleted when bare, kept as an Orphaned line when it carries site facts. Status follows the file until the site touches the line. One digest of any episodes; one summary to the uploader. The latest update can be undone (the previous revision re-applies). A PDF update never deletes and never touches edges. Decided 2026-10-30 (map #3954, ticket #3962). _Avoid_: sync, sync review, apply, revision apply (the retired attended review and its commit act).
Staging
The role the Programme* tables play: the immutable record of what each file said. Since 2026-10-30 (map #3954) staging is no longer a gate. The ingest job's last step makes every staged task and milestone a Work line and every relationship a Work dependency, so the "only critical chains get lines" philosophy is reversed. Staging is a role, not a noun: the rows remain what they are after the lines are minted from them.
Promotion
*(retired 2026-10-29, map #3954)* The former curated act that minted Work lines from a selection of staged activities. Every activity is now a line at ingest; there is no ceremony, preview or Promote bar. Not to be confused with promote-from-token, the hand-authoring door, which survives. _Avoid_: "promote" for ingest.
Band mapping
The per-Programme memory of which bands are hidden: Band path → hidden, written by the ⊘ hide-band verb on a Plan Gantt heading and restored from the programme header. A hidden band's activities are still lines and their edges keep evaluating; hiding is display only (design and procurement bands are the usual noise). A renamed hidden band comes back visible after a Programme update, and one click re-hides it. Narrowed 2026-10-30 (map #3954): the contractor / place / level columns and the remembered place suggestions are dropped. Nothing about place or contractor is read from a band. _Avoid_: band suggestion (retired); admin chains (the retired regex: hide the band instead).
Band path
A WBS band's cross-revision identity: the root-stripped, verbatim-case chain of wbs_names from the highest in-file ancestor *below the project node* to the band, joined with › . The short_name chain (ordinals on every real file) is never an identity — it lies silently across a re-scope. A path that no revision carries is a miss, never a guess. The band path keys band hiding (Band mapping), and its segments are the Plan Gantt's breadcrumb headings. The last segment is the band's label; descendant matching is structural (segment lists), never a string prefix. Decided 2026-09-01 (#3612). _Avoid_: short_name path / natural path (the retired ordinal chain); band id (no surrogate exists).
Band rename
*(retired 2026-10-30, map #3954)* The former sync-review facet that moved a band mapping to a renamed band. A Programme update applies itself, and a renamed hidden band reappears visible to be re-hidden on the Gantt. _Avoid_: re-key (the *line* verb).
Activity code
A P6 classification stamped on an activity — a type (AREA, OWNER / SUPPLIER, STAGE…) and one of that type's values (BOILER HALL, CAREYS, STAGE 5) — staged verbatim and vocabulary-blind on every Programme revision as code values + activity assignments. A code means nothing to any seam: it is a file fact, listed as text in the line's Bar detail ("AREA: BOILER HALL") for the planner to read. No place or contractor is derived from it, and it earns no filter chip (amended 2026-10-30, map #3954). _Avoid_: activity code for the P6 task_code (that is the activity_code, the opaque natural key); UDF (a different P6 table — productivity here, never location); tag.
Code role
*(retired 2026-10-30, map #3954; machinery dropped)* The former per-programme declaration that an activity-code type named a place or the contractor. No longer a concept: place never comes from plan codes. _Avoid_: code mapping, location code.
Site lexicon
The site's whole-phrase vocabulary: every place (Reference feature with geometry — a building, a zone, any other named feature) and every Contractor, each by its name, short code and aliases. One module (services/site_lexicon.py) answers "what does this phrase name here?" for permit import, programme place suggestion, Code role proposal and the code answers alike (programme place suggestion and code-role proposal retired 2026-10-30, map #3954; permit import is the remaining programme-adjacent caller). Its laws: matching is whole-phrase (an alias is another exact key, a substring is an absent key — P2); a name beats an alias whatever order the two were registered in; a building beats a zone bearing the same name; a placeholder is not vocabulary — "Site wide", "TBC", "N/A", "Various", "None" name nothing, so a feature so named answers for no phrase and a band so named proposes nothing; and only geometry-bearing features are places (a feature nothing can paint or clash against is not somewhere a permit lands or a band is suggested). The fold every matcher shares — lowercase, strip, collapse whitespace — is core/phrase.normalise_phrase, and the wire's alias tidy rule folds through it too. Decided 2026-09-02 (#3691, epic #3651). _Avoid_: "resolver lookup tables" (the permit resolver *holds* a lexicon, it is not one); "site dictionary".
Activity mapping
*(retired 2026-10-30, map #3954; table dropped)* The former accepted per-activity contractor / place / level override. A line's contractor is its programme's, and its place comes from a token (Line place). _Avoid_: activity override.
Sync review
*(retired 2026-10-30, map #3954)* The former attended, facet-grouped review of what a newly-ready revision changed. A Programme update applies itself, and what it changed is read from its summary and the revision history. _Avoid_: sync, review (for an update).
Apply
*(retired 2026-10-30, map #3954)* The former coordinator act committing a Sync review. A Programme update applies itself as the ingest job's last step. _Avoid_: apply / revision apply as a user-facing verb.
Orphaned line
An imported line whose activity has left its programme's current revision but which is kept because it carries site facts (a token, evidence, a completion record, a comment, a hand link, a hand-set place, a status a SimOps verb moved). A bare line in the same position is deleted. Derived, never a column; reappearance heals it. Sits under "No longer in the programme" at the foot of its programme, last dates frozen. Verbs: Re-key (it *is* another activity now) and detach ("keep as a hand line"). A soft orphan is one a PDF update did not find — kept even when bare, re-judged by the next logic-carrying update. Rewritten 2026-10-30 (map #3954, ticket #3962).
Re-key
The identity assertion on an Orphaned line: "this line *is* that activity now". The orphan adopts the activity's key and file fields; the bare twin the update minted is absorbed. Refused if the twin carries site facts. No heuristic matching anywhere. Rewritten 2026-10-30 (map #3954, ticket #3962).
Logic pointer
Programme.current_logic_revision_id — the edge-facet diff basis, stamped only by logic-carrying updates (XER, and pp since 2026-09-07). Keeps PDF updates edge-no-ops and makes an XER-after-PDF update set the imported edges from the new XER, never from a blind revision. A .pp update moves it like an XER; mixing the two full-fidelity formats on one programme is an ordinary update.
Edge-blind
The epistemic stance toward a PDF revision's missing logic: no information about edges, never evidence of absence. A PDF update touches no edges and deletes no lines; a missing activity becomes a soft Orphaned line. _Avoid_: edge-empty (implies a true zero).
Born satisfied
An imported or hand-authored edge whose predecessor line is already complete at creation — legal, inert, the truth of history. Drains most of a mid-project import's violation storm.
Slip chip
The variance atom: a signed-days lateness (+14d) comparing a Work line's planned window against site reality, derived at read time and never stored. Thresholds are a per-site setting (default amber +1..+5d, red >+5d). Since 2026-10-30 (map #3954) it renders as the Plan Gantt's slip tail (planned finish → expected finish, labelled +Nd; a bare unfinished line tails to today) and in the Bar detail. The weekly programme health digest keeps it, and its per-place paragraph and the choropleth's *behind* mode read placed lines only. All of these read one authority (/work-lines/variance). Milestone rows carry a bounded worst-ancestor slip forecast, deliberately not CPM. A slip is not a delay (Dependency violation). See docs/decisions/2026-07-21-plan-vs-reality-variance.md.
Sibling pair
The same programme revision handed over in two source formats — the SCEC rev-36 native Powerproject .pp beside Careys' P6 Cloud XER of it; each synthetic revision A / B emitted by both fixture writers. The unit the Equivalence contract is measured on. Decided 2026-09-07 (#3760). _Avoid_: "the pair" for a revision A→B sequence (that is a revision pair, one format, the delta list's subject).
Equivalence contract
What two parsers must agree on for a Sibling pair, as four lists over the leaf activities — *exact* (byte-equal per activity code) · *rule* (equal under a named normalisation with the count the real pair expects) · Named allowance · *delta* (the staged sync delta from one format's A→B equals the other's). Symmetric on the shared set; anything unlisted fails, including a skip reason a parser mints that no list names. One comparator in test support, two callers: the synthetic pair in CI, the real SCEC pair as an opt-in local gate (SIMOOPS_PROGRAMME_PAIR_DIR, make programme-pair-gate, outside make test). Decided 2026-09-07 (#3760, early dates re-listed by #3757). _Avoid_: "parity test" (the P6 clash gate's word); "real-pair gate" as a domain term (it names the opt-in test only).
Named allowance
A fact one source format carries and the other cannot — the XER's WBS-summary activities, late dates, float and driving flag; the .pp's overall-percent-complete — asserted present on its side and absent on the other, so a parser that starts inventing it, or an emitter that stops planting it, trips the suite. The list is closed: an asymmetry not named is a failure. Decided 2026-09-07 (#3760). _Avoid_: tolerance / fuzz (an allowance is exact about which side holds the fact); "known gap" (it is asserted, not tolerated).
Summary axis
Powerproject's own hierarchy — EXPANDED_TASK → BAR → TASK — and the fixed source of a .pp revision's Band path: every expanded task except the root chart (IS_PROJECT = 1, stripped structurally like the P6 project node) and the Orphanage. Bars are never a band segment: a multi-task bar's tasks sit on the enclosing expanded task, the bar name rides the activity's bag. WBS_ENTRY (P6's PROJWBS, identical below the root on SCEC) rides the bag as evidence and is never chosen per file. A coded expanded task is a band, not work — the .pp parser emits leaves only. Decided 2026-09-07 (#3756). _Avoid_: WBS as the .pp hierarchy's name (that is the optional overlay); axis detection (no file chooses its own axis).
Orphanage
Powerproject's second top-level chart beside the root — where a planner parks tasks removed from the programme — found structurally (any non-root top-level expanded task), never by name. Its tasks are counted under the skip reason orphanage_task and never staged: a parked task is not work the programme carries. Decided 2026-09-07 (#3756). _Avoid_: Orphaned line (an imported line kept after its code left the current revision — a different orphan on a different plane).
Skip channel
The one place an ingest reports what it could not use — the revision's skipped_relationships reason→count dictionary — and, under the Equivalence contract, an exact per-format value. XER reasons: cross_project · unknown_link_type · unusable_task_row · unusable_actv_code_row · dangling_code_assignment. Powerproject reasons: duplicate_activity_code (the merge key is verified, never assumed) · orphanage_task · summary_endpoint (logic attached to a bar or expanded task) · skipped_endpoint (an endpoint on a task the parser itself skipped) · dangling_code_assignment (+ the shared unknown_link_type); cross_project is never minted for a .pp. A completed-section fold is resolution, not a skip. Decided 2026-09-07 (#3756, #3760). _Avoid_: warning list / error list (a skip is a counted, named drop, not a fault — faults end the revision failed with an ingest_error_code).

Blockers — declared work stoppages

Blocker
A declared, first-class record that a cause stopped or impaired specific work over an actual time window. Substrate: a WorkGroup (group_type=blocker) + 1:1 detail extension — the same minting pattern as Incident and Observation — inheriting comments, contractor tagging, Position provenance and the active → resolved → archived lifecycle. It is the sixth Auxiliary pin kind; geometry is nullable — when the cause is itself a pin the blocker renders as a badge on the cause, and only pinless causes ("council closed the access road") get their own pin — and only while the blocker is active: the pin drops on resolve, a rejected suggestion (which lands on resolved) drops with it, and archive carries no map meaning (#3943).
Blocker acknowledgment
An optional coordinator counter-signal on a Blocker — acknowledged or disputed, with a note — that never gates the record's existence. A contractor declaring their own work blocked is self-serving evidence; the contemporaneous acknowledgment (either direction) is the second opinion claims tooling weighs. Decided 2026-07-06 (grill session).
Relayed report
A Blocker raised by a desk person from a message somebody else sent them — WhatsApp, email, a phone call, a word in the cabin — as opposed to a first-hand raise by the person who saw the work stop. It carries three facts *as told to us*, none of them verified by the platform: who told us (a name, free text, never a user account), the channel (whatsapp / email / phone / in_person; absent = first-hand), and when they told us (a third instant beside the actuals window and the declaration stamp; it pre-fills the stop instant and is shown on the record face). The declarer stays the desk person, and the ledger's recording lag reads the declaration, never the relay — the relay instant is unverifiable and would let a desk type promptness. A relayed count is prose in the description, never the firm's word: the firm speaks it in *Needs your count*, or the meeting's attested-count arm retypes it with the firm's rep present. A relayed photo is an ordinary gallery pick: the app claims a taken-at instant or a Sensed location only where the bytes carry them, and never the reporter or the reported-at instant from a file. Decided 2026-09-18 (map #3810 ticket #3817). _Avoid_: reporter (the filing user on an Observation / Incident, who holds see-own powers this name never grants); on behalf of (implies delegated authority); forwarded (a property of the message, not the record); second-hand (reads as untrustworthy, where the point is only that it is unverified).
Attested count
A firm's send-home count typed by a blocker_triage holder at the coordination meeting with a named representative of that firm recorded present — stored as the firm's word, never the coordinator's. The count write carries attested_by {name, user_id?}; the record's updated event holds the name, the firm and the site-local date; the basis bundle reads *"spoken by ⟨rep⟩, ⟨firm⟩, at the ⟨date⟩ meeting"*. No column — stood_down_basis stays declared, and a later own-firm correction is a later act. It is the one exception to the count being the owning firm's own act (blocker_count_not_yours for every other caller) and the only way a triage holder types another firm's figure: a count in a forwarded message stays prose (see Relayed report). The *Present for ⟨firm⟩* declaration is per sitting, per firm, client state only — there is no meeting entity. Decided 2026-09-16 / 2026-09-18 (map #3810 tickets #3811, #3819). _Avoid_: witnessed count (the *blamed ⇒ witnessed* rule this arm amends, not the act); proxy count (the proxy band never types a count — A-F1); meeting count (it is the firm's count, spoken at a meeting).
Meeting mode
The Completions → Blockers tab's second reading — the coordination meeting's table, where the coordinator runs completion and triage on one row. Two bands: every row still awaiting triage, however old (closed-but-suggested included — silence is not a decision), and the rows raised, confirmed or rejected inside the daily report's site-local day window; no "meeting held" stamp. A band-one row expands in place into the confirm form (one triage-form component, two hosts — the modal and the row), hosts the discussion thread as the rebuttal and the completion fields (locked until a rep is present — see Attested count); rows decided during the sitting stay put with a *decided* mark. Entered from the daily report's Blockers section (bidirectional — closing the table restores the report on the same draft session) and from the Noticeboard's awaiting count, which is a door, never rows. Prints as confirmed rows plus one *"N raises awaiting triage, not listed"* line. The push is untouched: every raise still mints its confirm_blocker Task. Decided 2026-09-16 / 2026-09-18 (map #3810 tickets #3811, #3819). _Avoid_: meeting (as an entity — none exists); triage queue (the Task is the push, this is the table); "Lost time → Blockers" (a mis-naming — the host is the Completions surface's Blockers tab; crew-hours and £ live on the Lost time Ledger).
Stand-down
The people-measure inside a Blocker — how many operatives were stood down (site verb: "we were stood down"); substrate stood_down_headcount. A measure, never a record type: the Blocker owns the window and cause, the stand-down counts heads. Plant "stands", people "are stood down" — the site-language object split. Decided 2026-07-25 (wayfinder map #1742).

Inventory — materials and stock

Delivery line item
One manifest row on a delivery: free-text description, quantity, unit (plain string; per-site suggestions; no unit conversion, ever — units merge only on equality), and an *optional* Material reference. The manifest is what a delivery *says* it carries; what actually arrived is established by Receive. _Avoid_: cargo, payload; manifest (the collective, not the row).
Material
A thin, site-scoped catalog entry ("rebar 12mm") that line items may reference — the Permit type shape: seeded vocabulary, adapted per site, never forced at entry time. Cross-delivery aggregation ("how much 12mm rebar is on site?") exists only where the reference is set. _Avoid_: product, SKU (implies an org-level catalog; this is per-site).
Stock lot
The received instance of a Delivery line item — the thing that is physically *somewhere*. Carries a polymorphic current-location attribute (laydown ActiveArea FK, point with Position provenance, building + level, or unassigned) as a cache; every location change is a transfer Stock event, so history lives in the ledger. Stock is not time-windowed: when a laydown area's window elapses with stock still in it, nothing auto-moves — an orphaned-stock advisory surfaces it (the elapsed-but-unresolved house pattern). _Avoid_: batch (process-industry connotation); inventory item (the ledger tracks lots, not catalog rows).
Stock event
One signed-delta entry in the append-only stock ledger: delivery_in / consumption / loss / transfer / adjustment, each referencing its cause (delivery, incident, token/permit/area, or a note). Contractor + quantity are mandatory; finer attribution is optional polymorphic refs. Balances are always derived from events; corrections are compensating entries. An incident-linked loss posts immediately — never gated on the incident approval workflow. _Avoid_: stock movement (transfers are one kind, not the genus); stocktake (an adjustment's occasion, not a ledger concept).
Receive
The explicit workflow action on a delivery pin that turns manifest into stock: pre-filled from the line items, edited to actual received quantities (short loads, part-rejection), posting delivery_in events. Damage is not a quantity edit but a first-class ReceiveException authored inside the sign-off (ReceiveExceptionKind: damaged / wrong_item, its quantity deliberately not bounded by the received quantity). Receipts are repeatable, with an explicit final declaration; sign-off IS receive (#1279, ADR I7) — a receipt pre-filled from an extraction draft flips that document to confirmed atomically. Status changes alone never post stock — completion is not receipt. _Avoid_: check-in, goods-in (dockyard jargon); complete (a delivery status, deliberately distinct).

Document intake

Ingest
Channel-side arrival of a document. Shipped: a file landing via an upload route. Designed-for but unshipped: the email channel (the intake spec explicitly declines an IngestAddress table or EmailIngest model for now). Says nothing about what happens to the document next. _Avoid_: using it for the whole pattern (that's Document intake).
Document intake
The pattern itself: a document arrives (Ingest), its genre is declared by the channel's affordance (a button, an address prefix — never a classifier), Extraction optionally drafts structured content, and a human's confirmation IS the domain write — nothing provisional touches domain tables. Degrades to manual entry when no provider is configured. A vertical riding the pattern is a document family (manifest documents, order documents); each family brings its own sibling <X>Document + draft workspace — families share idioms, never tables. _Avoid_: document ingestion (collides with the email-channel term); OCR pipeline (extraction is one optional stage, not the pattern).
Extraction
The LLM step only (services/extraction/): a provider adapter (ExtractionProvider, Claude API / OpenRouter) with one typed method per genre, run as a TaskIQ job, writing a draft into the document row. Never runs unrequested; logs provider/model/tokens, never content. _Avoid_: conflating with Document intake (the pattern survives extraction being absent).
Tabular intake
The spreadsheet half of arriving data, and a different thing from Document intake: no LLM, no genre declaration, no draft — a .csv/.xlsx whose columns a per-customer YAML config maps onto domain fields. services/intake/ owns everything domain-blind about that: the bounded read and the CSV/XLSX grid every tabular intake reads through (permit register, defect register, bulk import), the config substrate, the two-phase TTL cache that carries an import_id between the preview and the commit, and the transform registry — the named pure functions a config may name against a cell. What a row *means* stays per package. The registry is the seam that matters: parse_datetime, strip and to_string are shared and know nothing about permits or defects, because a private copy of one is how "the same transform name" came to mean two different things in two intakes (#2814). A client's registry spreads the shared set and adds only the transforms its own domain knows (permits add split_values and regex_extract). TransformError lives with the applier, so "a refused cell is a visible error row naming row, column and value" is one contract shared rather than copied — the two register imports report refusals identically, and a refused row is never a silent skip (#2555). Wall-clock cells take their zone resolution from the one home (core/timeutil) and then refuse rather than fall back: an unknown IANA key misreads every cell in the upload, so it fails the whole file rather than becoming a page of identical row errors. _Avoid_: Document intake (the LLM pattern — different verbs, different tables); "the parser" (a config-driven parser is one client of the grid, not the substrate); "importer" (ambiguous between the grid, the parser and the domain write).
Spatial intake
The file half of arriving data — a GeoJSON reference layer, a shapefile ZIP, a site-map GeoTIFF, a DXF floor plan — and a peer of Tabular intake, not a client of it. Each arrival path is a leg; every leg does the same six things (stage → byte cap → parse → persist/version → audit → broadcast → reap), and until #3108 each hand-rolled all six. Seven legs, all of them on the spine: GeoJSON, shapefile and site-map joined in #3108; the DXF import, the DXF pre-flight and the two raster floor-plan legs in #3109 — which is when the last hand-rolled ceilings went (a 413 carrying no slug, and one number checked by two authors). The intake spine (services/intake/spatial.py) owns the domain-blind half: the suffix gate, the byte ceiling enforced *while* the upload is staged (so an over-cap file costs one chunk of disk and zero parser work), the off-loop parse, the ordered parse → land → announce, and one scratch directory reaped in finally on every path. An IntakeAdapter is that leg as a *value* — kind, suffixes, byte_cap, parse — declared beside the parser it names and holding no session, user or request state; the request-scoped half reaches the spine as the land (persist/version + audit + the durability point) and announce (post-commit broadcast) callables. The upload itself reaches it as a SourceFile — filename, claimed size, stream — so a leg whose door is not a multipart route (the DXF launch saga, deliberately transport-free) rides the spine without inventing a request. The claimed size is only ever an *arm*: a chunked upload declares nothing, so the authority is the count kept while the bytes are written. The ceiling is a whole-upload refusal, never a partial import: over-cap is InvalidInput 422 carrying upload_size_exceeded, the same shape on every leg, mirroring geometry_limit_exceeded (the vertex/extent caps) and multiple_shapefiles_in_zip (the multi-layer archive). The three are distinct questions and each answers with its own slug — bytes, geometry size, archive shape — so a client branches on the slug rather than on prose. _Avoid_: "upload validation" (the cap is one of several refusals, and the adapter is not a validator); reading byte_cap as the geometry caps (#2946 guards vertices and extent, not bytes — they compose).
Gallery entry
What one attached file looks like on the wire, for every one of the twelve file-evidence kinds. Seven fields: the six the file says about itself (id, filename, content_type, size_bytes, uploaded_at, uploader_user_id) plus download_url — a same-origin backend streaming path, never a presigned S3 URL, and the only address a reader has for the bytes. Declared once as app/schemas/gallery.py::GalleryEntry (#3128); each kind's read schema inherits it and may add a field it alone needs (completion's caption, inspection's item_key, snag's phase, a Permit attachment's expected_slot_key) but may never restate a shared one. EvidenceDescriptor is the base minus the URL — the shape of a kind that declines to be a gallery. Exactly one does: the stock-event pour ticket, a descriptor list served from its own route where the client addresses the bytes from ids it already holds. A named decline, with its reversal condition ("if the wire ever grows a download_url, enrol it") written down beside it. No gallery entry carries storage_key. The raw S3 object key is the server's address for the bytes; a client holding one can do nothing with it — prod's reverse proxy exposes no S3 route — except learn the bucket layout. The COLUMN is untouched on every evidence row: the download route reads it to fetch the blob, and db/storage_scope enumerates it to answer whether anyone still names those bytes. _Avoid_: "evidence response" (twelve classes, one contract — the noun is the contract); calling the stock ticket a gallery entry; reading the strip as a column removal.

Claims evidence — QS tooling

Evidence pack
A persistent, attestable bundle of contemporaneous records over declared parameters (time window × area × contractor × record classes): a frozen context snapshot plus a branded narrative document and raw data annexes, generated by the report pipeline's provider DAG. At generation an append-only attestation records a content hash over pack + snapshot + parameters — "this pack, these contents, this moment". Permit windows/timelines serve as the in-system as-planned leg; blockers, audit, clash episodes, weather, and the stock ledger are as-built; the external P6 programme stays external. A Claim workspace (heads of claim, valuations, lifecycle) is deliberately not an entity. The pack workspace surfaces as the Evidence tile of the Commercial full-screen surface (I, gated evidence_pack.manage) — not a standalone dock panel (originally a 2026-07-13 Analysis-suite tab; the suite dissolved into the domain homes, ADR 2026-08-12-dock-domain-homes.md). _Avoid_: claim (the QS's argument, made outside SimOops); report (the daily coordination artifact); export (an ephemeral download; packs persist).
Commercial (role)
A site role for the QS/commercial persona, minted in the hse pattern: sitewide read (cross-contractor by necessity), evidence-pack generation, export, audit_view — plus the commercial blocker band (blocker_edit / blocker_manage / blocker_suggest — blockers are, deliberately, the one record a QS edits; blocker_triage is withheld), lost_time_view, hse_exposure_submit, snag_view and defect_view. No other entity mutation or triage/workflow verbs. Exists so claims pilots never start with a coordinator over-grant. _Avoid_: QS role (persona, not the role name); quantity surveyor (ditto).
Completion record
A declared, evidence-backed statement that the work a token represents was done on a given site-local day: keyed by (entity, work_date) — one per token per day, which is what makes all-day (unwindowed) tokens completable day by day. Covers the temporal clashable kinds — those that live on the day axis, carrying start_at/end_at (Tokens, ActiveAreas). Not deliveries, whose completion-with-evidence moment is Receive; and not roads (nor buildings/zones), which are persistent geometry with no temporal columns at all — no work date names their work, so there is nothing to complete. Note the test is "has a time axis", *not* "has a non-null window": an all-day token has a null window and still completes. Living, not frozen: reversible and editable within the declaring contractor's authority (the require_contractor_access seam), with every change on an append-only event strip so contemporaneity stays provable for Evidence packs. Surfacing only — completing never mutates the token's window or geometry and never removes it from clash detection. Amended 2026-07-17: daily completion is optional and silent — no nudge, no visual guilt; the QS as-built takes whatever exists (Close-out (work sense), one of three gestures). Every record-work-completion gesture carries the Snag wee box. Capture is per token (properties panel, mobile record-completed-work) or via the site browser's multi-select bulk close — the My Work *Close out* tab (decided 2026-07-13) is retired with the panel's rename to *My Tasks*. Token expiry ≠ completion. Decided 2026-07-06 (grill session); road retired as an anchor 2026-07-15 (the axis is temporal, not clashable — D2 correction). See docs/decisions/2026-07-06-token-completion-records.md and docs/decisions/2026-07-17-close-out-two-verbs.md. _Avoid_: completed status (Delivery's enum value — a different lifecycle); close-out (the Permit close-out transition); sign-off (a possible future QS attestation, deliberately not this); "every clashable kind" (roads clash but never complete).

Permits to Work

Permit
A formal, time-bounded authorisation for work on a site: who (contractor), what (scope of work, controls), where (location), and when (a start/end window). One entity regardless of how it arrived — via the in-app request/approval workflow or via file import from an external allocation tool (provenance is recorded). A permit answers *"is this allowed to happen here?"* — it sits on top of the RAMS process, it does not replace it. _Avoid_: permit number (that is one field of a Permit, and historically the only vestige of one); PermitSet (the import batch record, not the permit).
Permit-linked entity
An on-map entity that can carry a permit_id — i.e. trace to a Permit. Five kinds today: Worker, Plant, Delivery, ActiveArea (the schedulable polygon areas — work_area / exclusion / laydown / HRCA) and ReferenceFeature (reference geometry — zone / road / building). This is the entity set the inline permit-request flow and the Permit coverage policy reason about.
Permit type
A per-site template defining a category of permit — its name and code (e.g. Hot Works/HW), the pre-checks a requestor must complete, whether it requires a parent permit, and its default duration. Sites set their own list (per HSG250 practice); a UK/EU default set is seeded and sites adapt it during onboarding. A single permit may carry several types at once (see Permit control category); the type catalogue is the vocabulary, a permit selects a set from it. _Avoid_: org-scoped template (permit types belong to the site, mirroring how site rules define the permitted-activity list).
Permit control category
The set of hazardous-activity controls a single permit authorises — a permit is *"Hot Work, Confined Space, General"*, not one thing. Each category is a Permit type drawn from the site catalogue; the permit carries a set. The set is the permit's identity for two purposes: it drives the clash engine (a Hot-Work category near a Confined-Space category conflicts) and the card's at-a-glance chips. The governing workflow regime (stages, parent requirement, extendability, pre-check checklist, duration) is derived from the set by most-restrictive/union rules — there is no single "primary" type. General is the near-universal base category and is visually de-emphasised. On import, the external tool's free-text *Control* column is the source of the set.
Permit hierarchy
A parent/child relationship between permits, expressed as a capability of the permit type system (requires parent), not a universal invariant. The UK default templates model the common principal-contractor convention: a General Permit (authorisation to work on site, mostly free-text scope) parents high-risk children (Hot Works, Confined Space, …) which inherit its location and contractor, carry their own parent-nested windows (not the parent's dates), and add type-specific controls. Sites that only permit high-risk activity simply use types with no parent requirement.
Permit family
A General (umbrella) Permit plus its single-issuer child permits — "two permits stapled together, both with their own issuers" — each running its own lifecycle, window, sign-off and authorised issuer, grouped under a shared parent_permit_id. The family is the structural answer to cross-discipline work (distinct authorised issuers); a lone permit carrying a Permit control category set is the degenerate "family of one" for same-issuer control bundles. The family is the clash unit — a token's clash categories are the temporally-gated union over its whole family (parent + open children), so decomposition never goes clash-blind. Parent transitions gate on child aggregate state (close-out blocked while any child is non-terminal; "work begins" blocked until children are live). Decided 2026-06-18 (grill session) — "P2-soft": families primary, multi-category re-scoped (not removed). ADR landed: docs/decisions/2026-06-18-configurable-permit-workflow-engine.md (amends 2026-06-16). _Avoid_: multi-category permit as the cross-discipline answer (that is the same-issuer control bundle); reading "stapled together" as mere display grouping (each child is a real, independently-signed permit).
Permit attachment
A file (RAMS, drawings, isolation certificate, lift plan, photo) uploaded against a Permit as the evidence behind its declared controls and pre-checks. Bytes live in S3; a row carries the metadata, reusing the same storage substrate as incident/observation evidence. Attachments are editable only while the permit is a draft (or in corrections), and their identities fold into the permit's signed content hash — so each approval signature attests to the exact file set, and a post-approval swap is detectable. A new or revised document after that point means corrections (pre-issue) or a reissue. Each file may be tagged to an Expected-attachment slot; a slot marked *required* must be satisfied before the permit can be submitted. _Avoid_: "evidence" for a permit's files (that is the WorkGroup / incident / observation noun — a permit has *attachments*, even though they share the storage helper); treating attachments as mutable after submit (they freeze).
Expected-attachment slot
A per-Permit type keyed prompt for a document ({key, label, required}, e.g. Confined Space → *Rescue plan*) against which a Permit attachment is tagged (expected_slot_key). Slots union across a permit's category set, deduped by key. A slot is either advisory — a satisfied/unsatisfied checklist that gates nothing — or required, in which case it gates submission: a Permit cannot leave draft until every required slot has a tagged file. required ORs across the category set (required by any contributing type → required in the union) and is enforced by the required_attachments_present workflow guard on the submit transition, not by a parallel check. _Avoid_: "expected attachment" for the *file* (the slot is the prompt; the file is the Permit attachment); assuming all slots block submit (only required ones do).
Permit coverage policy
A per-site policy stating that every placed Permit-linked entity must trace to an active Permit. When enabled, unpermitted entities are surfaced (badges, noticeboard signals), not blocked at placement — paperwork lag must not break the map-first workflow. Disabled on sites that don't run general permits.
Permit lifecycle
The fixed state machine every in-app permit walks: draft (requestor-only visibility) → requested → endorsed (first approval: coordination check) → approved (second approval: H&S desk review — on the permit schedule but not yet live) → issued (the walk-down: issuer and receiver both sign; work may proceed) → closed (formal close-out signed off). Rejected is terminal and available at all three gates; each gate can also send the permit back for corrections (requestor edits and resubmits — the full chain restarts). Imported permits join the machine at *issued*.
Workflow definition
The per-site (optionally per-Permit type) data artifact that *is* a permit's Permit lifecycle — a versioned graph of State marker-tagged states and action-keyed edges (each carrying its Actor tokens, guards, and effects), seeded with the default lifecycle and clone-to-customised. The test-only FSM Machine promoted to a runtime source of truth; admins compose it from a fixed registry of dev-authored guards/effects/handlers and never author logic. Each permit pins the workflow_version_at_creation it began under, so edits never strand live permits. Built as a domain-agnostic substrate (an Incident or Observation may adopt it later). Decided 2026-06-18 (grill session); ADR 2026-06-18-configurable-permit-workflow-engine.md. _Avoid_: state machine (the shape is now data, not code); workflow *instance* (a permit walking a definition is not the definition).
State marker
A member of the fixed semantic spine — the dev-owned vocabulary every consumer keys off *instead of* a literal status value, so a site may rename or reshape its Workflow definition states without breaking anything downstream. Permit markers (PermitMarker, ten members): WORK_MAY_PROCEED, EDITABLE, the three-way visibility partition VISIBILITY_REQUESTOR / VISIBILITY_CONTRACTOR_REVIEW / VISIBILITY_PUBLIC, CLASH_RELEVANT, EXPIRY_ALARM, TERMINAL, SPENT, WITHDRAWABLE. A state carries a subset; consumers prefer PermitMarker.X in permit_markers(status) (frontend hasMarker(p, …)) over branching on a literal status == "issued" — a handful of concrete-status branches legitimately remain. The same move as Clash category (rules filter on category, not enumerated variants). Decided 2026-06-18 (grill session). _Avoid_: status (the configurable per-site *name* — a marker is the fixed *meaning*); flag (overloaded).
Actor token
The per-transition declaration of *who may take an edge* in a Workflow definition: WorkflowEdge.actors is a set of abstract tokens from a fixed dev-authored registry of five (workflow/actors.py: requestor, coordinator, hs, issuer, receiver), satisfied by disjunction. Each token resolves to its permission band inside the resolver (e.g. permit_approve_stage1/stage2); only issuer consults Permit appointment. The 2026-06-18 design's richer gate binding — optional specific-users lists and a site-defined display label ("PtW Coordinator") — is unshipped; what shipped is the token registry. _Avoid_: role (a token resolves to a band, it is not itself a role); gate binding (the unshipped richer design — no GateBinding exists in code).
Permit event
A row in a Permit's permanent transition timeline — one per lifecycle action (created, submitted, endorsed, approved, issued, countersigned, closed, expired, withdrawn, rejected, corrections-requested, extended, reissued), plus one status-preserving overlay: handed_back (the holder's signed "work complete, area left safe" declaration — not a transition; mobile permits spec §5.3, #1583), and one system-recorded overlay: matched_place_cleared (a feature or layer delete cleared the permit's matched place; the actor is the deleting user and the detail line names the place, #4211). It carries the actor (nullable — *expired* is system-driven), a timestamp, an optional note, and JSONB metadata, and is the source for the activity feed, the PDF history, and the CSV export. The cryptographic gate attestations live in the separate signature ledger; a signing event links its signature for the content-hash. Mirrors the incident timeline. _Avoid_: conflating an event with a signature (every signature has an event, but submitted / expired / withdrawn / reissued events have none); the delivery-bus *OutboxEvent* (transient and pruned — not the audit record).
Permit close-out
The formal act that ends a permit: work finished or stopped, area checked (fire watch held after hot works), tools and barriers removed, sign-off recorded. The holder's hand-back (the handed_back overlay event) may precede it — a signed "work complete, area left safe" declaration that changes no status. Expired is the alarm state — end time passed with no close-out — and still requires a close-out to reach *closed*. Unclosed permits are the red-flag surface; a site gate can hold new issues until yesterday's permits are closed. _Avoid_: expiry as a synonym for closure (the external tool conflated them).
Permit issue (walk-down)
The distinct act that makes an *approved* permit live: the issuer physically verifies controls at the workface (fresh gas test, exclusion zone up, named personnel present) and both issuer and receiver sign in-app. The issuer can refuse — bounce to corrections or reject — if conditions aren't met. _Avoid_: issue as a synonym for second approval (approval is the desk decision the night before; issue is the morning act that goes live).
Permit appointment
The per-site, optionally permit-type-scoped record naming a user as an authorised issuer — the in-app analogue of the written Authorised Person appointment in UK practice (formal, named, scoped, not portable between sites). Appointments layer on top of existing site roles rather than being a role: a zone construction manager is *both* a coordinator and an appointed issuer. Role bands give the workflow defaults (request = member+, first approval = coordinator+, second approval = hse/admin); issuing always requires an appointment. The same mechanism is how a site configures *who* acts at each gate. _Avoid_: permit-issuer as a SiteRole (one-role-per-membership can't model it); PTW-coordinator (the external tool's name for the second-approval band).
Permit signature
An authenticated in-app action: verified user identity, timestamp, the permit content as signed, and the state transition, audit-logged and rendered onto the permit document. Signatures occur at issue (issuer + receiver), close-out, and approvals. No drawn-squiggle capture — an authenticated action is stronger evidence than a wet-ink lookalike.
Permit receiver
The named site user (a member of the receiving contractor, defaulting to the requestor) who accepts the permit at issue and countersigns from their own device, confirming they understand its limits and conditions. The permit goes live only when both issuer and receiver signatures land. _Avoid_: free-text receiver names (the countersign must be attributable).
Permit board
The site-wide live coordination view of permits: what's issued and live where, what's approved for tomorrow, what's expired awaiting close-out. The board is public within the site — its whole function is the fire marshal and the neighbouring subbie seeing live hot works at a glance — even though in-flight applications (draft → approved) stay scoped to the requesting contractor plus the review band. In SimOops the board is a dock panel and the map *is* its spatial half (linked entities locate permits).
Permit band
"Which band is this permit in" has two answers, because two surfaces ask it about two different things. They are documented together here but declared apart: WalletBand in ui/src/app/domain/permit-band.ts, PermitBoardBand with the rest of the PTW wire shapes (ui/src/app/types/permit-application.types.ts, mirrored in models/_permits.py).
Close-out gate
A per-site, contractor-scoped policy: a contractor with expired-unclosed permits cannot have new permits issued (approvals proceed; going-live is held, with the offending permits listed) until they close out. The in-app form of "most sites won't issue tomorrow's permits until yesterday's are closed". Default off.
Permit reissue
The default way a permit's life is prolonged: a one-click clone with fresh dates and a reissued from link to its predecessor, walking the full chain again — including a fresh walk-down. UK practice insists on this for high-risk work because the issue act embeds physical re-verification; "extending" paper is the mechanism for skipping it.
Permit extension
A per-type capability (off for every high-risk type in the UK default set; on for General): a requested new end time approved at the second-approval gate, stretching the window without re-issue. Exists for administrative parent permits where nothing physical needs re-verifying. Child permits never outlive their parent's window. _Avoid_: extending high-risk permits (that is a reissue, by design).
Permit spatiality
Permits have no geometry of their own. The entities working under a permit (workers, plant, deliveries, areas) carry the geometry and reference the permit; a permit's spatial footprint *is* its linked entities. Spatial permit semantics flow through them: clash rules see a linked permit's type as an entity attribute (hot-works token near solvent-works token), and a permit's authorised extent, where one exists, is a linked work-area feature. The permit row keeps only a textual location and the import resolver's spawn hints. The external tool's spatial columns map onto SimOops terms with a vocabulary inversion worth pinning: their *Zone* is a SimOops Floor (building level), their *Area* is a SimOops Building or Zone, and their *Location* is free-text within. The persisted field literally named zone_raw holds a floor, not a zone. _Avoid_: permit-as-map-object (two spatial truths that can disagree — the token in the corridor under a permit that says plant room 3); reading "zone" off an imported permit as a SimOops Zone (it is the floor).
Linked / unlinked permit
Whether a Permit has any entities referencing it via the permit_id FK. A linked permit has at least one linked entity, so it has a spatial footprint (see Permit spatiality) and lights up the map under the permit lens; an unlinked permit exists but has zero linked entities — no spatial footprint yet — and is the population a coordinator works through when placing tokens. The authoritative signal is the live FK count (linked_entity_count), never a denormalised tally. This is the permit-side mirror of the token-side Permit coverage policy (a token with no permit): both ask "is the permit↔entity link present?", from opposite ends. _Avoid_: "mapped" (collides with the background site map); "active" (the live window / ActiveArea / alerts); "allocated" (resource allocation); "located" (an imported permit is already located by its text/matched-feature while still unlinked).
Permit placement
Dropping the entities that become a permit's footprint. Two distinct surfaces, easy to conflate: the apply workbench builds a *draft's* footprint *before* submit (placement there is required — a draft needs at least one linked entity to be submittable) and routes each drop through the confirm-and-link path; board placement is the rapid-fire walk that drops tokens under an already-issued Linked / unlinked permit|unlinked permit (the population is imported permits awaiting tokens). Board placement is issued-only — a draft offers "Continue application" (back to the apply workbench), never a board place affordance — and is tools-island-driven: the normal Add palette chooses the kind case-by-case, limited to the linkable map-token kinds (worker, plant, area). The map auto-focuses each permit's matched zone/building as the walk advances (viewport only — never the scrubber, see Permit spatiality). _Avoid_: placing tokens under a draft from the board (its footprint belongs in the apply workbench); "per-permit armed toolset" (placement no longer derives a tool set from the permit — the fixed armedTools are the linkable kinds and the tools-island Add palette is the chooser).
Permit window
A permit's start_at/end_at define a daily recurring work window across a date range — *"07:00–17:00 each working day from the 11th to the 17th"* — not one contiguous block running through the overnights. A six-day permit is six daily windows, not 144 unbroken hours. This is the interpretation the entity spawner already encodes (buildPermitScheduleOccurrences stamps the permit's HH:MM onto each calendar day in range), so visualisations and clash-overlap must read the window the same way. Whether a *physical hazard* (an open excavation, a created opening) persists outside the daily window is a separate, category-dependent question. _Avoid_: rendering or reasoning about a multi-day permit as a single all-day/all-span bar (its true footprint is the daily window repeated).

RAMS

RAMS document
The register identity for a contractor's RAMS: site, authoring contractor, title, reference number. Content is never decomposed (no risk-table or method-statement fields) — RAMS revisions carry the files. Permits link a RAMS document by nullable FK alongside the legacy free-text rams_reference; permit submission warns, never blocks, on an unreviewed / superseded / past-review-date RAMS. _Avoid_: rams_reference (the legacy string); attachment (the permit slot a revision file also satisfies).
RAMS revision
One immutable issued revision of a RAMS document: rev label, attached file(s), review/expiry date, and a single overall verdict — submitted → accepted | accepted_with_comments | rejected (the source's A/AC/R key; rejection sends the contractor back to upload a new revision). The current revision is derived — the latest revision whose status is an acceptance (accepted or accepted_with_comments) — never a stored flag. The linked revision's identity folds into the permit content hash at submit, so an approval attests the exact RAMS it rested on. _Avoid_: version (template vocabulary); superseded as a status (it is derived).
RAMS review lane
A per-revision, per-discipline review record — discipline from a per-site registry seeded with the AFRY five (Civils, Erection Lead, Mech/Elec Supervisor, Commissioning Manager, HSE), plus reviewer, note, date. Lanes are the evidence trail and never individually gate — the overall verdict is the revision's status (on the real review sheet most lanes are blank). _Avoid_: approval stage (permit vocabulary); reviewer band (RBAC term).
RAMS briefing signature
A signature-grade attestation that a named person was briefed on and signed a specific RAMS revision: name + company (optionally a user id), timestamp, and the revision's content hash — captured either by a supervisor on the operative's behalf or self-served through a per-revision public capture link (QR; the Observation capture link pattern). Does not mint a user identity for drivers or visiting crews. _Avoid_: sign-on sheet (the paper artefact this replaces); permit signature (transition-coupled, a different mechanism).

Site map

Site-map capture
A single georeferenced image of the site at a point in time — an aerial/drone pass or a scanned site plan — stored as a SiteMap (calibrated, COG-tiled). A site accumulates captures over its life; uploading a new one never deletes the old. Each carries a captured_at (when the survey was taken, distinct from when it was uploaded). _Avoid_: bare "capture" unqualified — it is overloaded with the export/report *screenshot* sense; and "version", which implies a strict lineage the flat capture list does not have.
Canonical site map
The one capture a site is currently running on — the shared background every member sees by default and that reports/exports bake in. Distinct from a member's local view. Decided 2026-06-09 (grill session): the active background is promoted from per-user ephemeral state to shared, coordinator-published site state (Site.active_site_map_id, broadcast over WebSocket); selecting a capture in the Site Maps panel *publishes* it (coordinator-only; members are read-only, no personal-preview tier). Every change appends to a site_map_activations log, so "which capture was active at time T" has one answer — the activation with the greatest activated_at ≤ T. A later, opt-in Phase 2 surfaces *temporal* divergence: when the scrubber sits far from the canonical capture's captured_at, a non-intrusive banner offers to jump to the capture current at that moment. See docs/decisions/2026-06-09-canonical-site-map-and-provenance.md. _Avoid_: "active map" as a per-user notion — it is now site-canonical.

Temporal

Site day
A calendar day (YYYY-MM-DD) as the site's clock reads it. The day boundary is the site's midnight — never the server's, never the viewer browser's, never the CI runner's — because "what day is it here?" is a question about the site. It is the day a Completion record keys its work_date on, the day the dashboard's selectedDate names, the day an incident_date records, and the "site-local working day" the coordinator day tour anchors to. Ratified 2026-08-10 in docs/decisions/2026-08-10-site-tz-day-contract.md, which is the source of truth; ui/CLAUDE.md → "Site-local vs viewer-local time formatting" is the working guide.
Active period
The single canonical "when does this entity exist / when is it scheduled" range. Expressed as two NOT NULL timestamps start_at / end_at on Worker, Plant, ActiveArea, and Delivery. A concrete absolute range (may span midnight). Decided 2026-05-22 (grill session): - Every primitive entity kind — including high_risk_commissioning_area ("HRCA") — uses *only* the Active period model. HRCA has no special "daily recurring window" semantic; its distinctiveness lives entirely in clash rules. - Both bounds are NOT NULL. No null = "all-day", no null = "open-ended", no sentinel dates. Every entity has a concrete range. - Delivery's scheduled_start / scheduled_end columns rename to start_at / end_at for consistency (legacy from before the model was unified). - See docs/decisions/2026-05-22-active-area-table-split.md.
Shift
A site-level configuration row defining a recurring clock-hour window (e.g. "Day shift, 06:00-18:00"). Shifts are referenced by name from Permit imports and from the dashboard scrubber to seed default Active period values when an entity is created. A shift is *not* a temporal property of an entity — entities only carry Active periods.
Schedule group
A set of entity instances generated from one recurring-schedule definition, sharing a schedule_group_id — its members are Occurrences. Spans Worker, Plant, and ActiveArea; each member carries its own Active period. The group exists while it has ≥1 member and ceases when the last is deleted (there is no separate group row). A revert restores group membership through the group doors, never by writing it: the row leaves its group or rejoins the group its entry names, the door recounts every member, and an entry naming a group that has ceased is refused 409 audit_revert_reference_gone (ruled 2026-11-11, #4192, re-ruling epic #4152 call 4). A revert waits only in its first, id-ordered lock read; a row it must lock after that (a third group's members, a late joiner) held by another write refuses it 409 audit_revert_contended, which is retryable (#4208).
Schedule-group write epilogue
The one ending every schedule-group door shares — GroupWrite in app/services/entity/schedule_group_commit.py. Before the commit: capture → version → flush → settle → attach → audit → commit; after it: invalidate → announce → reconcile → line evaluation, the single-row lifecycle's order. The order is the module's invariant; a door's only choices are the rows it names and the frame it announces. The five token group doors (update, reconcile, convert, delete, finish early) end in it, as do the area schedule's create and finish early (#4162), the token copy, the area copy and the token schedule create, which edit no group and announce one entity_created per created row (GroupFrame.CREATED, #4163), and the revert's leave and join legs (schedule_membership.py, #4192). The area full delete is a declared decline (ADR 2026-06-14 D2: its frames stay per-area entity_deleted). tests/test_schedule_group_epilogue_census.py discovers every group write under app/services/ and holds it to the epilogue or a declined door with its grounds (the fill doors; permit co-creation, which is all-or-none with the permit); its known-gap set is empty. A door composed into a caller's unit of work gets PendingReads, which resolve after that commit; a door that answers with a body (reconcile, convert, the area and token schedule creates) answers through GroupWriteOutcome.respond, which hands a composed caller a PendingResponse, so READS_IN_DOOR_GAPS is empty (#4195). The Schedule group sibling of CaseworkCommit (#4161). _Avoid_: group commit (a commit is one step of seven).
Occurrence
A single member of a Schedule group — one entity row covering one Active period. The "All N" count in the edit/delete flow is the group's occurrence count.
Reach
When editing or deleting a member of a Schedule group, the choice of whether the change applies to this Occurrence alone or the whole group — surfaced to the user as the "This one / All N" prompt. Decided 2026-05-29 (grill session): "reach" is the canonical name for this axis; the edit/delete flow resolves a reach, then applies the operation at that reach. See docs/decisions/2026-05-29-schedule-operation-dispatch.md. _Avoid_: scope (AnalysisRegion already lists "scope" on its own _Avoid_ list — it is the loose word that concept was sharpened away from; reusing it here would overload the glossary).
Window
The half-open datetime interval [start, end) as a value object (app/db/queries.py::Window) — the one authority for temporal overlap, so the half-open law cannot be re-derived by hand with different edge inclusivity. A None bound is unbounded on that side, which is how the domain spells "all-day". Two distinct questions, two doors, deliberately not one: overlaps(other) (window-vs-window — touching at a boundary is *not* overlap, delegating to core/timeutil.py::windows_overlap, the single implementation) and contains(instant) (point-in-window — the start edge is closed, an entity has arrived at its own start_at; the end edge is open, it is already gone at its own end_at). The point reading is not expressible as a degenerate overlap: a zero-width window [T, T) overlaps nothing at all (#602). SQL renderings come from the same object (apply and the clauses seam), so the Python predicate and the query filter are one law. Adopted across the hand-rolled overlap re-rolls by epic #2645 (E1/E2 #2662, #2663; predicates via FU4 #2738, point-in-window via FU5 #2744). The frontend twin is ui/src/app/domain/entity-window.ts's entityWindowsOverlap (#2932): the same three laws — half-open, an unstated bound open-ended on that side, an unparseable bound read as unstated — asked of two placed entities. It replaced the extra.timeRange wall-clock channel, a pair of site HH:MM strings a placed entity carried *beside* its window; that channel named no instant, so it needed a midnight-wrap reading and day-edge completion of a missing bound, and it is retired end to end (readers #2932 L3–L5, storage scrubbed by migration 321). _Avoid_: inclusive range / [start, end] (the closed end double-counts a boundary instant); "touching windows overlap" (they do not); re-spelling the predicate inline (the value object is the door); timeRange (the retired wall-clock channel — a window names instants, not a time of day).
Day range
An inclusive run of Site days from_day .. to_day (app/db/queries.py::DayRange) — the other window kind a read may be asked about, beside the Window of instants. Its days are the site's own calendar days, so it carries no zone: a cross-site read spans several clocks, and one day on two sites is two different spans of instants. Its one exit to instants is DayRange.window(site_zone) → [site midnight(from_day), site midnight(to_day + 1)), resolved through core/timeutil.site_local_window, so a DST day is 23 or 25 hours. A None bound is unbounded, as on a Window. _Avoid_: a UTC-midnight bracket over an instant column (that is the UTC day, not the site's — #4104 found the observation list reading it); reading a day range as an instant window or vice versa.
Window query
The rule for how a read takes a time window on the wire (#4104). Every window a query parameter carries is one of two kinds, and each kind has one FastAPI door in app/api/deps.py: WindowQuery (start / end, date-time with a UTC offset, half-open — answers a Window) and DayRangeQuery (from_day / to_day, date, inclusive — answers a Day range). Both refuse an inverted pair (query_window_inverted, 422). tests/test_window_query_census.py walks the OpenAPI document and requires a new route's window parameters to come through a door; the thirty hand-spelled operations that predate them are frozen there with their classified kind, shrink-only and never renamed (epic #4093 call 4: a rename is wire churn for every consumer). _Avoid_: a fresh spelling (since/until, date_from/date_to, window_start/…) on a new route; an untyped str bound parsed by hand in the handler (a malformed value 500s instead of 422ing).

Areas and reference geometry

ActiveArea
A polygon that participates in clash detection *and* carries an Active period. Variants: exclusion, laydown, work_area, high_risk_commissioning_area (HRCA). All ActiveAreas have NOT NULL start_at / end_at. PR3 of the unified-temporal-model rollout landed 2026-05-23 — schedulable polygons now live in their own backend table active_areas (separate from Reference features), with sibling history tables active_area_versions and active_area_geometry_history. See docs/decisions/2026-05-22-active-area-table-split.md for the forking rationale.
Whole-floor area
An ActiveArea with placement_mode = 'whole_floor', created by a Floor-fill action rather than a freeform polygon draw. Its polygon is snapshotted from the building's polygon-with-holes at fill time and frozen thereafter — subsequent building footprint edits do not auto-propagate. A fill_source_revision mismatch with the building's current revision surfaces a "Footprint changed since fill" chip on the panel with a "Regenerate" action to re-sync the group's polygons explicitly. Operationally indistinguishable from a freeform area on the map — clash rules fire per-row, floor-aware rendering filters identically. The provenance lives on the panel, not on the map.
Whole-zone area
An ActiveArea with placement_mode = 'whole_zone', created by a Fill action targeting a zone rather than a freeform polygon draw. The sibling of Whole-floor area with the degenerate slice count: a zone has no floors, so one fill produces exactly one row per occurrence. Its polygon is snapshotted from the zone's geometry at fill time and frozen thereafter — later zone edits do not auto-propagate; a fill_source_revision mismatch surfaces the same stale chip + "Regenerate" action as the building case.
Fill
The umbrella action: creating whole-container ActiveArea rows by snapshotting a Reference feature's geometry, in one transaction. A building slices into its levels, the roof among them (Floor-fill → N Whole-floor area rows); a zone is a single slice ("Fill zone…" → one Whole-zone area row per occurrence). Roads (linestrings) are not fillable — no interior to snapshot — and neither are level-less buildings (the rejected third tier). One container per fill action: filling three zones is three actions with three groups. Every fill mints a Fill group, down to size 1.
Floor-fill
The building-flavoured surface of Fill: creates N Whole-floor area rows (× K recurrences) over selected floors of one building in one shot. Its entry-point is the "Floor-fill area…" button on the building properties panel (the A → F chord that once doubled it was retired 2026-09-23 to free an Add-menu slot). It lands on the same modal the zone case uses, with the floor picker shown.
Fill group
The set of Whole-floor area / Whole-zone area rows produced by one Fill action, identified by a shared fill_group_id UUID. Invariant: placement_mode ∈ {whole_floor, whole_zone} IFF fill_group_id IS NOT NULL.
Reference feature
A polygon (or linestring) that's part of the site's static geometry but carries no Active period. Variants: building, zone, and road (the linestring case). After PR3 (2026-05-23) the `geometadata_features table is exclusively reference geometry — the schedulable polygons moved to active_areas. A DB-level CHECK constraint enforces the boundary: feature_type IN (unknown, building, zone, road)`.
Floor footprint
An optional per-level polygon on a building — carried inside the level entry itself (the elevation_m grow-the-dict precedent), so it versions and replays through the existing feature history with no new machinery. Sparse by design: a level without its own polygon inherits the union envelope; nothing is backfilled. Together with the per-level elevation interval this forms the implicit prism model — the deliberate ceiling of SimOops's 3D ambition (per-level 2D polygon × elevation interval; no Z coordinates, meshes, or 3D geometry types in storage). Level awareness lands at write time: placement/move derive building_feature_id + building_level from refined (point, level-polygon) containment — auto-set, overridable — while the clash engine stays FK-based and level polygons never enter predicates. Overlapping envelopes resolve by refinement first (level containment, then smallest area), with the reference-feature Disambiguation picker for genuinely ambiguous picks. Decided 2026-07-06 (grill session). See docs/decisions/2026-07-06-per-floor-building-footprints.md. _Avoid_: level geometry (ambiguous with entity building_level); floor plan (the per-level interior drawing — a different system, see Floor plan); 3D model (explicitly ruled out).
Floor plan
The per-(building × level) interior drawing that renders while Floor focus is active — backed by exactly one of two artifact kinds: a raster COG (image/GeoTIFF uploads, or DXF imports taking the raster fallback) or a vector artifact (the default for DXF imports: an immutable per-level GeoJSON of the drawing's linework, text, and hatch fills). Both artifact URLs are resolved at-time off the FloorPlanVersion chain. One plan per building level, whichever the kind. Decided 2026-07-13 (grill session). See docs/decisions/2026-07-13-vector-floor-plans.md. _Avoid_: "vector layer" (collides with reference layers and MapLibre style layers — say *vector-backed floor plan* or *plan linework*); "drawing" (the DXF is the *source*; the floor plan is the derived artifact).
FloorPlanVersion
The third member of the version substrate, joining FeatureVersion and ActiveAreaVersion: a row owns the half-open system-time interval [valid_from, valid_to), the chain is gapless and non-overlapping, and db/queries.as_of is the one predicate that reads it. It replaced an audit-log scan — "which COG was authoritative at T" used to mean finding the latest entity_type='floor_plan' row ≤ T and reading a *snapshot dict key* out of it. Three things were wrong with that and none had a test that could see them: audit pruning truncates the history the tile proxy serves from; a rename inside the snapshot builder turns every historical answer into None with no type error anywhere; and the three distinct "no URL" outcomes were one indistinguishable None. They are now three named states — before_creation (no row in force: the plan did not exist yet), deleted (the row in force is a delete), unprocessed (a row was in force but its artifact column is NULL — the COG or linework had not been built, or the build failed) — and the tile proxy has a different right answer for each. Unlike the other two families, a create row is NOT epoch-anchored: a newly drawn feature should appear at every scrubber position including the past, but revision mode asks *what the building looked like then*, and a plan uploaded today did not exist yesterday. Added 2026-08-20 (epic #2792 G5, migration 315 + a one-shot backfill). _Avoid_: "plan history" (the audit trail this replaced); Floor plan (the current row, not the chain).
DxfImportLaunch
Starting a DXF import is not one call, it is a short saga whose steps have to happen in one order and whose middle can fail: validate the options and assignments → spool and parse the upload (a cheap reject before Redis or S3 are touched) → claim the per-site import lock → seed the Redis progress entry → stage the drawing to S3 under its per-render-mode key scheme → enqueue the worker job — and if any of the last three raises, release the lock, or the site stays blocked. The ordering *is* the correctness content: the lock is claimed before anything is staged because the thing being prevented is two multi-minute render jobs racing over the same buildings, and the guard is only worth having at enqueue time, before the duplicate becomes a job. Progress is seeded before the enqueue because the modal starts polling the instant the 202 lands, and per-building failures must have somewhere to be counted. The compensating release exists because from the claim onwards the *worker* is what releases the lock — if no worker ever runs, nobody does, and the site is blocked until the TTL expires. It is a function (services/geometadata/dxf_import_launch.py), not a 215-line route handler, so it is callable from somewhere that is not a request; it raises DomainError, and the one transport detail the wire still owes — the X-Active-Import-Session header on the 409 — rides the refusal's active_session field for the route to render. Named 2026-08-20 (epic #2792 G4). _Avoid_: "the upload endpoint" (the saga outlives the request); "job" (the enqueued render is the job; this is what gets it there).
Plan slab
The theme-coloured fill rendered under a vector-backed Floor plan's linework, clipped to the level's Floor footprint (else the building envelope) with a subtle edge lift — the "inside the building" ground that keeps interior linework from reading as marks on the site imagery. _Avoid_: "background colour" (the raster-era equivalent, baked into the COG at import; the slab is a live style layer).
Ghost linework
Floor-plan content falling outside the Floor footprint — grid lines, reference annotations — rendered muted/translucent rather than clipped, so it reads as reference floating over the site, not as geometry claiming the ground. Split from inside linework geometrically at extraction (footprint intersection), never by DXF layer-name convention. _Avoid_: "clipped"/"cropped" (the raster-era cutline truncated this content; the vector path deliberately preserves it).
Schedulable
Retired 2026-05-23 (PR3). Was a deprecated UI gate (isSchedulableType) listing exclusion/laydown/work_area as types that went through the permit-driven, datetime-bound creation flow. After PR3 every ActiveArea type is schedulable by virtue of living in active_areas (which enforces NOT NULL temporal bounds at the column level); the three-type gate is gone. A local const of the same name survives in the area-creation workflow, now listing all four types (HRCA included) to branch the create path, with a standing TODO to fold it into a registry query.
Geometry cut
Subtracting a shape from an ActiveArea or Reference feature's polygon, leaving a hole (donut) or a reduced outline — recorded as a first-class operation (before/after snapshots, provenance, undo-by-restore) in the per-family geometry history. Two flows share one seam: the automatic feature-vs-feature cut (a building cuts zones/laydowns per the LayerType rule matrix — shipped) and the freeform cut (the user draws an ad-hoc cutter against a selected polygon; the cutter geometry is stored inline on the history row, gated by entity_edit, never by the rule matrix). Decided 2026-07-06 (grill session): a cut is also a *versioned event* — it writes the same temporal version rows as any other geometry update, so at-time reconstruction (revision mode) sees it; every reshape path (vertex edit, PATCH, drag, undo) must carry interior rings through rather than collapsing them; cut-undo is a command in the main per-kind undo stack, with redo. See docs/decisions/2026-07-06-freeform-hole-cutting.md. _Avoid_: hole tool (the cut is the operation; a hole is one outcome); clip/boolean subtract (GIS jargon); erase (implies deletion of the entity).

Reports

ReportScene
A single clash-focused frame in a safety report — a geographic bounds (optionally a rotation-aware polygon + draw-time view), the entities spatially inside it, and a clash summary. The unit a coordinator accepts/rejects in the report wizard; each accepted scene is captured to one headline image. A scene *projects to* an AnalysisRegion but is not one. _Avoid_: snip (that's the capture mechanic), cluster (the pre-acceptance proximity grouping, not the accepted frame).
Report issue
An issued copy of a completed report session: the artefact a coordinator's export of a completed session mints, delivered under the anchored report-issues/ family and recorded as a ReportSessionIssue (session, site, format, object key, filename, issued-at/by). Export is the issuing act; completion alone issues nothing, and a draft export is not paper. Issues are append-only — a re-export is a second issue, never an overwrite — and are read by the report.view band (every role) through the Commercial home's Reports tile; the read band never reaches a session, an export or a render job, so a reader can never be the export that stamps observations as reported. Decided 2026-10-08 (#3935). _Avoid_: export (the act, and a draft's ephemeral file), render job.
Site overview
The whole-site context image in a report — one full-page map of the entire site. Distinct from the per-scene minimap inset (the small locator thumbnail composited into each ReportScene image) and from a ReportScene image itself.
Evening works boundary
The site-local time of day from which the daily report's Afternoon / Evening Works section lists the day's work; declared per site (Site.evening_works_from), default 17:00. The window it opens is [D @ evening_works_from, D+1 @ 00:00) site-local — the end is site midnight, not a shift's end — and "active" in it means Window overlap, so a day task running into the evening appears. Site-wide: one site, one boundary, no per-report override. Declared, never derived — a site that moves its back shift to 16:00 moves this knob too (the diary's R12 ruling applied to the report); the platform holds no back shift as data. Edited on Settings ▸ Site ▸ Shifts, beside the shift rows. _Avoid_: back shift (a named Shift row, not this), cutoff, 17:00 (the default, not the definition).
Weather summary
The record form of a report's weather: five hour-stamped cells over the report session's window — temp high @ HH:00 · temp low @ HH:00 · max gust @ HH:00 · max sustained wind @ HH:00 + Beaufort · precipitation total (mm). It sits above the retained weather ribbon on both the on-screen preview and the PDF/DOCX export. The ribbon stays the *shape-of-the-day glance*; the summary is what a reader copies into a claim.

Analysis

Analysis tool
A *kind of computation and presentation* run over an AnalysisRegion. The founding tool is Region evolution — the ChangePointStream stepper/list. **The Analysis *suite* (the Y dock panel that hosted the tools as tabs) dissolved 2026-08-12** (wayfinder map #2379, docs/decisions/2026-08-12-dock-domain-homes.md): Region evolution and the planner view live in the Work home — since 2026-09-01 as the map door's Changes here view (the Region-evolution tab retired 2026-09-01, the Reality place drill 2026-10-30), Evidence and Lost time in the Commercial home; the tool concept survives the move, the constructor *grid* did not. A region-based tool consumes the same region a Constructor door produces but renders differently and owns its own controls (the look-forward/look-back *horizon* slider belongs to the tool's Changes here host); the Planner (Reality) and Evidence surfaces embed their own views rather than a constructor-built region. _Avoid_: mode (overloaded with Interaction mode and the create/select keyboard modes), analysis type (vague), constructor (that is the region-selection axis, not the computation).
Constructor
The UI affordance that *builds* an AnalysisRegion — how the user chooses the spatial scope. Amended 2026-09-01 (fold ADR 2026-09-01-region-evolution-folds-into-reality.md D6): the constructor *grid* retired — live regions now arise from doors (a right-clicked building / zone / entity → Changes here; the Reality place-row door retired with the Place drill 2026-10-30), and only *Edit knobs* survives, on the neighbourhood region. The anchor kinds that remain: scene_box (the report wizard's per-scene projection — never a live constructor), entity_neighbourhood (anchor on an entity + knobs), building (a building + floor(s)), zone (a zone feature); freehand_polygon is retired end-to-end. All but entity_neighbourhood differ *only* in how the polygon_wgs84 + level_set are obtained; each resolves to that shared shape and the AnalysisEngine is identical across them. The anchor_kind discriminant records provenance for display/audit, not engine behaviour. _Avoid_: tool (the computation axis), anchor (fits entity_neighbourhood specifically — a drawn box has no anchor), selector (generic).
AnalysisRegion
A scoping value: *which entities and which time window* the AnalysisEngine should consider. A tagged union over anchor kinds — scene_box | entity_neighbourhood | building | zone (freehand_polygon retired 2026-09-01 with the constructor grid) — each variant carries the inputs its anchor needs. Every variant carries a time_window (Active period applied to the analysis: forward_days/backward_days relative to the scrubber's viewDateTime) and the polygon-plus-level-set that the engine ultimately queries against.
AnalysisEngine
The pure function that takes an AnalysisRegion and produces a ChangePointStream for the region's time window. Uniform on the region's polygon, not polymorphic on anchor kind: every Constructor resolves to a polygon_wgs84 + level\_set on the frontend (including entity_neighbourhood, whose knobs are resolved via turf.js), so the engine always computes the same thing — "entity-id set inside polygon × level\_set changes". The anchor_kind is carried for provenance/display only; the engine does not branch on it.
ChangePoint
A single unit of inflection emitted by the AnalysisEngine. Carries:
ChangePointStream
The ordered list of ChangePoints returned by the AnalysisEngine for one AnalysisRegion over its time window. Always anchored at the scrubber's viewDateTime; emits points within [viewDateTime - backward_days, viewDateTime + forward_days]. The stream is computed on demand — no precomputed materialised view — and cached by (region-hash, viewDateTime, anchor_id) only within the panel session. _Avoid_: timeline (overloaded with gantt timeline, audit-log timeline, scrubber timeline), inflection stream (jargon), change-feed (overloaded with WebSocket "feed" terminology).
Stepper
The UI control inside the Region-evolution panel (the Work home's third tab, also reachable from the map's right-click *"scheduled changes here"* door) that drives sequential navigation through a ChangePointStream. "Next" / "Previous" buttons (plus arrow-key chords when the panel is focused) advance the scrubber's viewDateTime to the next/previous ChangePoint and expose the delta summary in a banner. The same panel surfaces the stream as a list so the coordinator can jump to any ChangePoint directly; sequential and jump-to are alternate projections of one stream.
Region evolution
The look-forward/look-back Analysis tool — it walks a ChangePointStream over an AnalysisRegion. One tool, three *surfaces* — live, with one host (amended 2026-10-30, map #3954 — the Reality Place drill retired): the map door's transient Changes here view (entity.view) — not a tab; and in-report as a section. Live regions arise from the door (a right-clicked building, zone or entity), never from a constructor grid. The report section consumes a ChangePointStream for a ReportScene's projected AnalysisRegion and renders each ChangePoint as a row in a per-region block; the rail arrives pre-ticked at each day's Day peak (a *default tick*, minted on Day-entry only — amended 2026-09-25, map #3864) and the coordinator ticks or unticks which rows should be captured as a full map screenshot at export time. Unticked rows render as table-only entries (timestamp, delta summary, clash counts). The lookahead is opt-in per scene — adding a scene does not implicitly enable a Region evolution block for it.
Day peak
For one site-local calendar day (Site day) in a report scene's Region evolution horizon, the ChangePoint after which the most entities are in the region — the largest in_scope_after. Ties go to the earliest instant at which the day's count reaches its peak (where the tokens come online); rows sharing one instant resolve to the last in stream order, whose in_scope_after is the settled state at that instant, so the row's text matches its picture. A day with no ChangePoint has no peak — no tick, nothing prints. The peak is taken over the whole day, with no shift fact: where the day shift is busiest it lands there by construction. A pure selection over the frozen ChangePointStream — the AnalysisEngine is untouched.
Day-entry
The moment a site-local calendar day first falls inside a scene's lookahead horizon — the day-range diff of the window before and after a recompute, never of the frozen ChangePointStreams, so a day is entered whether or not it carries change points: the per-scene opt-in (every day is new), a horizon extension (only the added days), a P1 polygon reset (every day is new again). A quiet day that later gains change points on a same-window *Refresh* was already entered; its peak row arrives tagged *day peak*, unticked (ruled 2026-09-27, #3932). It is the only moment the Day peak rule mints default ticks. A *Refresh* with the same window has no new day, so it leaves ticks exactly as the hash-keyed survival leaves them: an unticked default stays unticked, a hand tick survives, a vanished row surfaces the "removed" hint. There is no button — re-running the rule on purpose is untick-and-re-tick the opt-in. Decided 2026-09-25 (#3867 R1). _Avoid_: suggest (a second door to the same rule), fill (a Refresh that "fills empty days" needs a dismissed-set the day-entry rule makes unnecessary), inherit.
Section switch
The derived all / some / none control on the report's Clash Highlights section — *Region evolution on all accepted scenes*. It reads the accepted scenes' lookahead.enabled (checked = every accepted scene opted in, indeterminate = some, unchecked = none) and stores nothing. Ticking it opts in every accepted scene not yet opted in — each gets the seed horizon (Site.region_evolution_forward_days) and its default ticks; unticking clears every scene's lookahead, hand curation included, with no confirm (it mirrors the per-scene untick). No inheritance: a scene accepted later arrives unopted and the switch drops to indeterminate. Opt-in itself stays per scene (ADR D6). Decided 2026-09-25 (#3867 R3). _Avoid_: section flag (a stored second authority over each scene's lookahead.enabled, drifting the moment one scene is unticked), inherit (nothing is inherited), select all (that is scene acceptance, the neighbouring control).
Changes here
The transient body of the Work home rail that the map's right-click *"scheduled changes here"* door lands on (entity.view). It replaces the Plan Gantt while open: the Region evolution Stepper under Changes here · <region label>, with its own scrubber-anchored look-window slider and a ✕. Closing it (✕ / Escape) returns the Gantt if the rail was open before the door, else closes the rail; the door records {railWasOpen}. The region is cleared on close. It is the stepper's one live host. It reads tokens only, so a Programme update has no stepper. Width key work:changes-here (288). Decided 2026-09-01 (#3606); amended 2026-10-30 (map #3954, ticket #3966). _Avoid_: Region-evolution tab (it is not a tab); breadcrumb view (rejected: the rail's shape would depend on how you arrived).

Planner analysis

Planner
The persona this capability serves: a user who owns a longer-term master schedule (WBS / activities in P6 or similar) held outside SimOps and uses SimOps as a representation of site reality to check that plan against. Whether "planner" becomes a distinct SiteRole or is served to an existing role is unresolved (RBAC TBD). _Avoid_: scheduler (overloaded with the recurring-Schedule group machinery), coordinator (a distinct in-app persona/role).
Reality (planner sense)
What Planner analysis treats as ground truth: the live, as-recorded operational state — issued Permits together with placed tokens (Workers, Plant, ActiveAreas, deliveries) — read on the valid-time axis (each entity's Active period: *when work is scheduled*, the column the scrubber walks), not the system-time edit history. It is a *proxy* for reality, not verified actuals: the rows are mutable and only as current as the site team keeps them. Because the read is valid-time, the V1 views need no new history/versioning machinery — the live DB already encodes the whole schedule, past to future. Distinct from the external master plan and from the planning-cycle plan_state='actual' fork (removed in #674). Two questions are asked of a token here, and they disagree on a laydown or an exclusion zone: it is activity (physical stuff is happening for its line) but not headcount (nobody is on site in it). Headcount is crew-only — the line-token roster's *headcount* fact (#4069). _Avoid_: actuals (implies verified/frozen — these are mutable live rows), ground truth (overclaims), plan (the opposite — the external expectation).
Plan Gantt
The Work home's one surface: every Work line of every Programme that is on, under its programme's own headings (compressed breadcrumbs, never merged across programmes), with the plan and reality layers toggleable (plan · reality · both; reality needs planner_view). Two presentations of the same rows: Table view (one activity per row with code · name · start · finish columns and a bar — the default) and Gantt view (labelled bars lane-packed under each heading). Order: by contractor, by date, or by area (by Line place, then "No place yet"). A line is listed when anything drawn for it — planned bar, slip tail, its tokens' runs — meets the window (±2w by default). Marks: milestone rows + vertical date lines, today line, slip tail, ⧗ *waiting on A* (paint), ◆/◇ delay episode / pending (tokened lines only), dependency links coloured by verdict. Reality reaches a line only through a Token attachment (a strip under the row in Table, a ghost behind the bar in Gantt); the rest is Unlinked reality. A line's run spans the days any attached token stood (activity); its headcount counts crew only, so a line whose only standing tokens are laydown or exclusion areas draws an activity on site — no crew run (headcount: 0 on the wire, drawn sparser and dashed beside a crewed run's hatch). Unlinked reality is presence, so a loose laydown stays out of it (#4069). Decided 2026-10-30 (map #3954, ticket #3958). _Avoid_: Plan tab, Reality tab, Board (as a surface), Graph, Programme grid (all retired into it); plan for the programme it shows (say programme).
Bar paint
Everything one Work line's bar draws in the Plan Gantt, said once: its bar (or a milestone's ◆), slip tail and band, a late milestone's forecast ◇, its state (a complete line dims; an orphan dims and takes a dashed outline), its ⧗ / ◇ / ◆ delay mark, leaf crumb, label, tooltips, contractor ink, reality ghosts and, in Gantt view, its room on its lane. One pure function builds it (plan-bar-paint.ts) and one bar cell draws it in both presentations — on a Gantt view lane and in a Table row's bar cell — which differ in geometry only; the ◆ and ◇ answer their own press in both. A lane's bar is also the place-token drag handle, the selected ring and the links' anchor; in the Table the row is all three. Decided 2026-11-10 (#4141: the Gantt and Table bars' different orphan and milestone treatments were drift, unified). _Avoid_: bar markup per presentation (the shape this replaced).
Plan Gantt view
What the Plan Gantt's template draws, composed in one order by one pure factory (plan-gantt-view.ts): the rows in the reader's order (only Area order reads the site's places), then the delay marks and leaf crumbs, then one Bar paint per shown line (in Gantt view its lane room, measured against the bar column), then Gantt view's lanes or Table view's reality strips, then *both*'s reality foot (Unlinked reality); the links and their stubs are drawn off the rows the table measured. It takes the store's state plus the measures only a mounted table can make — the bar column's width, each listed row's middle, how wide a label draws — and touches no DOM, so the composition order is specced without a mount. The component keeps only what needs the DOM: measuring, resize, the drag source, the busy cue, a held landing. Decided 2026-11-10 (#4142). _Avoid_: deriving rows, paints or links in the component (the shape this replaced); view model on the store (the measures are one mount's, the store is the site's).
Bar detail
The panel a Plan Gantt bar opens — one Work line's file facts (status as of the data date, % complete, critical flag, its activity code values), expected finish and slip, Line place, the verdict in words, "Place a token from this line", reality runs on the line, predecessors and successors with verdict glyphs and the + predecessor / + successor authoring door, and the casework the Board carried (lifecycle verbs, tokens, blockers, lost time, close-out evidence and completion, comments). A bottom sheet in the rail, a right column in Expand. It is what the Board became. Decided 2026-10-30 (map #3954). _Avoid_: Board, row-expand (retired hosts).
Programme age
A programme header's "data date D — N weeks old" cue, amber past four weeks: why a stale file's sea of slip tails is honest rather than alarming. Sits beside the PDF fidelity badge. Decided 2026-10-30 (map #3954). _Avoid_: plan-age cue (the prototype's name, before *plan* was reserved for the layer).
Unlinked reality
Tokens on site that no shown Work line carries — a contractor with no programme, a crew on no line, a line whose programme is off or whose band is hidden. Drawn in the Plan Gantt's "On site — not on a line shown here" foot group and as a faint presence strip on each programme header. Never matched to a heading by name. Decided 2026-10-30 (map #3954). _Avoid_: unassigned (that is P5's permit-less bucket).
Plan overlay
*(retired 2026-10-30, map #3954)* The former drawing of promoted lines and ghosts on Reality's rows. Plan and reality are now layers of one Plan Gantt that meet only through a token on a line. _Avoid_: the term for any live surface.
Ghost bar
*(retired 2026-10-30, map #3954)* The former overlay bar for a staged, unpromoted activity. Every activity is now a Work line, so nothing is left to ghost. (The Plan Gantt's reality *ghost behind a bar* is a different thing: a tokened line's run in Gantt view.) _Avoid_: the term for any live surface.
Place drill
*(retired 2026-10-30, map #3954)* The former region-evolution stepper opened from a Reality place label. The Plan Gantt's Area order is the place read; Changes here is the stepper's one live host. _Avoid_: the term for any live surface.
Two densities
*(retired 2026-10-30, map #3954)* The former two-line-rows-at-rail-width rule. The Plan Gantt has two *presentations* (Table · Gantt) instead. _Avoid_: the term for any live surface.
Critical (driving path)
A staged activity, or the line promoted from it, whose P6 driving_path_flag is set — staged as a column (2026-09-01), shown as a *critical* flag in the Bar detail's file facts (the grid chip retired with the Programme grid, 2026-10-30). Every activity is a line now, whether critical or not. Distinct from the manual Critical / Sub Critical activity code (a chip like any other) and from SimOps computing any float of its own (it does not — CPM stays out of scope). _Avoid_: critical path (P6 computes it; SimOps only reads the flag).
Activity (planner sense)
The atom the planner reads and compares: an issued Permit seen as a unit of scheduled work — the closest SimOps analogue of a P6 activity, since it alone carries a structured *who* (Contractor), *what* (permit categories), *when* (Permit window) and *where* (matched Named place + linked tokens). Placed tokens are its manifestation: they supply the hard location (their building/zone FKs) and the human detail (label, worker_type) the permit's own free-text location lacks. Tokens carrying no permit surface as a separate "unpermitted" bucket. _Avoid_: task (overloaded with the Task action item), WBS element (the external plan's unit), activity-as-a-new-entity (it is the permit under a planner lens, not a new row).
Named place
The unified location axis for Planner analysis: a building or a zone (the site's two non-temporal named Reference feature kinds), treated as one "place" axis because a planner reasons about both as named locations ("Electrical Building", "Turbine Hall") whether or not SimOps gives them floors. Floor (a building's building_level) is a first-class drill-down — "in the Turbine Hall" and "on Level 2" are both valid queries. A place is attributed from the tokens' hard FKs (building_feature_id, zone_id), with a permit's free-text location as fallback. Vocabulary inversion (see Permit spatiality): the planner's external terms are the *inverse* of SimOps's — their *Zone* = our floor, their *Area* = our building/zone. V1 renders SimOps's terms; a translation adapter is deferred. _Avoid_: zone (one member, not the axis), area (overloaded with ActiveArea), location (too generic).
Token place
The one Named place a placed token is in. A token is in exactly one container: a building (on a floor) or a zone. Zones are imagined outside buildings, so a zone drawn inside a building is not a modelled place. The rule, in order: the token's declared key (its building and floor, else its zone — a worker's zone_id, an ActiveArea's zone_feature_id); then its geometry, where a building that holds it wins and a zone answers only where no building does; an area laid flush against a place only touches it and is not in it. Geometry never overrides a key. One module states it (services/planner/token_place.py), and its three readers keep their own policy on top: a Line place needs exactly one place, lost time buckets a record reaching several as (multiple places), and the planner matrix reads keys only and splits buildings from zones by its grain. Rooms subdividing a floor would land in the same module. Ruled 2026-11-10 (epic #4152 call 3, #4175). _Avoid_: smallest containing place (the retired tie-break).
Planner timeline
The spine of Planner analysis (working name): a lookahead-shaped activity matrix — rows grouped contractor-first (Named place as filter / sub-group, pivotable to place-first), columns a near-term window, cells the Activity (planner sense) bars (the Permit window daily-recurring semantics preserved). Built to structurally mirror the planner's P6 Gantt so the two read side by side. Decided 2026-06-18 (grill session): - A dedicated Planner surface, not a tool inside the coordinator Analysis panel (see Analysis tool): the postures differ (broad, contractor-organised, lived-in vs region-scoped, ephemeral, scrubber-stepped). It reuses the AnalysisEngine + AnalysisRegion / Constructor model and the permit-ribbon *math* (permitDailyWindows), rendering fresh — the permit-board ribbon's own today | tomorrow × intraday-hour view is the wrong granularity to stretch. - Lookahead time model: default ~14-day horizon (the 2-week short-interval lookahead) + a ~5-day backward tail (so overstaying — "still here 3 days after they should have moved" — is visible), expandable to ~6 weeks; day columns, week columns when stretched. - Now-anchored and scrubber-decoupled: its own anchor-date control; it does not re-window when the map scrubber time-travels; selecting an activity/cell drives the scrubber one-way for spatial inspection. (A Now-anchored surface in spirit.) _Avoid_: Gantt (the shape, not the thing), Lookahead (as the abstraction title — the surface is bidirectional via the backward tail; "lookahead" is fine as a user-facing *label*, echoing the Region evolution avoid-note), permit board (the operational Permit board ribbon — a different surface).
Congestion (trade-stacking)
The headline spatial-temporal metric of Planner analysis: the degree to which a Named place is over-subscribed over an interval — the count of distinct Contractors (and/or total token footprint against the place's capacity) co-located there. It is the insight SimOps can surface that the planner's external schedule cannot: P6 encodes activity *logic* but not *spatial* contention, while SimOps is spatial-native. Drives the aggregate mode of the place choropleth (see Planner timeline). (The designed-for congestion-over-time companion ribbon has not shipped.) _Avoid_: clash (the Clash engine's proximity/rule conflict — congestion is a planning density, not a safety clash), crowding (informal), density (the continuous-heatmap *rendering*, not the place-level metric).
Resource loading
The reality-side per-contractor presence counts across the Planner timeline window. What ships is deliberately modest: the spine band's occupancy badge and the per-activity Nw · Mp marker counts (whose own tooltip says "markers placed, not a headcount" — SimOps counts placed markers, never people). The designed-for histogram ribbon beneath the timeline (the WeatherRibbon pattern reused) has not shipped. Purely descriptive — no planned-vs-actual baseline exists in-app (see Reality (planner sense)). _Avoid_: S-curve (cumulative-progress — not computable without a baseline), utilisation (implies a capacity denominator SimOps does not hold).
Dwell time
The consecutive duration a Contractor has occupied / is scheduled in a Named place — the metric that operationalises *overstay* detection inside the present-reality constraint: the surface shows "in the Electrical Building N days and counting, M scheduled" (the Planner timeline's backward tail supplies the "and counting") and the planner judges whether that is wrong. Surfaced as a per-Activity (planner sense)|activity badge plus a sortable column. The app never asserts lateness; it supplies the number. _Avoid_: duration (the Active period length of one entity — dwell aggregates presence across a place), age (overloaded).

Site provisioning

Create-Site wizard
The in-app flow that provisions a new Site and its operable baseline. Superadmin-only today (architected so the gate can widen later). Builds progressively: step 1 creates the bare Site row + the creator's verified admin SiteMembership, and each later step drives the *existing* per-site operations against that real site — shifts, a first Contractor, the active rule profile, the background Site map, and optional invites.

Site organisation — contractors

Contractor
A team operating on a Site; its members own the workers, plant, deliveries, areas, and permits tagged to it. A Contractor belongs to exactly one Site, and a row may only be tagged with a contractor of its own site — every write naming a firm passes one door (services/contractor_site.require_contractor_on_site, a 422 contractor_not_on_site for every caller, superadmin included; ruled 2026-11-04). Casework reaches it at its shared seams: the WorkGroup contractor-tag replace (incident, observation, alert, blocker and snag tags), the involved-persons replace (incident and observation employers, mobile capture included) and a blocker's losing firm on mint, update and confirm; evidence packs, orders, order documents, invites, invite links (the link's firm, and the firm a joiner picks on register / accept), contractor oversight (the subordinate) and a lost-time rate's labour:contractor:<id> scope ask it too. A firm the record already carries is an echo and saves. The domains whose refusal was pinned before the door existed ask the same door and name their own refusal, so their wire is unchanged (action action_invalid_contractor, RAMS, inspection, stock, stock threshold, work line and main-contractor 400s; the blocker responsible firm's 422 blocker_responsible_cross_site; the nil return's, the HSE duty owner's and the defect import's 422s). Carries aliases ("also known as" — CC08, AFW; added 2026-09-01, #3611), whole-phrase matched by every name→contractor matcher (permit import; programme code roles retired 2026-10-30) — the twin of a Reference feature's place aliases; site vocabulary, never per-programme config.
Main contractor
The single principal Contractor of a Site, designated per-site and opt-in — a Site may have none. When set it is the root of the contractors-panel hierarchy and the parent of every otherwise-unparented Contractor on the Site.
Contractor oversight
A supervisor → subordinate edge between two Contractors on a Site: the supervisor's members gain CRUD parity over the subordinate's entities. The edge does double duty — it is *both* the authorisation grant *and* the panel hierarchy. "Appears under X" ≡ "X can edit it".
Transitive authority
Whether Contractor oversight authority cascades down the subtree. When a Site's oversight_transitive flag is on (the default), a supervisor's members reach *every* descendant — so the Main contractor reaches every Contractor on the Site; when off, authority is one-hop (direct subordinates only).
Subordinate / supervisor
The two ends of a Contractor oversight edge — the subordinate is nested beneath, the supervisor sits above. In UI prose "responsible" is an acceptable synonym for supervisor. _Avoid_: parent/child (reserve those for generic tree mechanics).
Oversight relationship
A viewer-relative classification of a clash-token (worker, plant, or ActiveArea — anything entity_kind: token) by where its owning Contractor sits relative to the viewing user's Contractor: - mine — the token's Contractor *is* the viewer's; - subordinate — the token's Contractor is in the viewer's canonical supervised set (the Subordinate / supervisor subtree, honouring the Site's Transitive authority flag — *not* an unconditional descendant walk); - other — everything else, deliberately absorbing supervisors, unrelated Contractors, and unassigned (no-Contractor) tokens alike.
Relevant clash
A viewer-relative classification of a Clash: a clash is relevant to a viewing user when at least one participating entity is owned by a Contractor in the viewer's responsibility set — their own Contractor plus its Subordinate / supervisor subtree (honouring the Site's Transitive authority flag); equivalently, any participant whose Oversight relationship is mine or subordinate. A clash whose participants are *all* other is non-relevant.
Affiliated coordinator
A user whose Site membership carries a coordinator/admin role *and* a contractor_id. They are vantaged (their Contractor anchors an Oversight relationship vantage), so they receive the Relevant/Other panel grouping like any contractor — but their Clash stance authority follows their role (coordinator = site-wide), not their Contractor scope. Clash grouping (vantage) and stance authority (role) are deliberately decoupled; an affiliated coordinator is the case that separates them. Decided 2026-06-05 (grill session); see the ADR. _Avoid_: conflating "what I'm responsible for" (vantage/grouping) with "what I may act on" (role/authority) — they are independent axes.

Demo sandbox

Demo Template
The single, PII-free snapshot of the real SCEC site from which every Demo World is cloned — produced once by Scrub (demo sense)|scrubbing a real SCEC extract, and refreshed only when the schema or seed data changes. _Avoid_: "golden copy", "demo seed" — it is not the synthetic site built by seed.py; it is a scrubbed clone of the *real* site.
Demo World
An ephemeral, isolated, throwaway instance of SimOps preloaded with the Demo Template, handed to one prospect to explore freely; independent from every other Demo World and discarded when it goes idle or ages out. _Avoid_: "demo session" (collides with the auth/HTTP sense of session and the unrelated ReportSession entity); "demo site" (a Demo World *contains* a site, but is the whole isolated instance, not just the Site row).
Scrub (demo sense)
The one-time transformation that removes all PII and commercially-sensitive content from a real SCEC extract to produce the Demo Template — by dropping, replacing-with-synthetic, or redacting each field per a scrub map. _Avoid_: "anonymise" — scrubbing also drops commercial IP and may relocate identifying geometry, not only personal identifiers.
Synthetic floor plan
A procedurally-generated, function-themed building-interior raster that stands in for a real Floor focus|floor's plan in the Demo Template, so the demo never exposes a client's actual architectural drawings — one per building floor (and the storage zone), georeferenced to the real footprint and rendered in a shared paper-and-ink CAD style. Amended 2026-07-13 (grill session): with vector-backed Floor plans, the stand-in matches the real plan's kind — a synthetic vector twin (the same procedural linework emitted as GeoJSON) for vector-backed plans, the raster for raster-backed ones. _Avoid_: "fake plan", "placeholder" — it is a deliberate, footprint-accurate stand-in, not a blank or a generic filler.
Character
One of the named, fictional people baked into the Demo Template as the demo's cast — each holding a genuine role-scoped site membership (coordinator, HSE manager, contractor supervisor, QS, site manager, client), except the anonymous operative, who deliberately has no account. Every Tour is experienced *as* a Character; the visitor can switch between them; workflow counterparties are other Characters. Fiction by construction — injected after scrub verification, never derived from a real person. _Avoid_: "persona" (this glossary uses persona for the abstract user archetype a capability serves; a Character is a concrete demo identity), "demo user" (ambiguous with the visiting prospect), "actor" (reserved for Co-actor).
Co-actor
A Character other than the one the visitor is viewing as, performing its side of a workflow while the visitor watches the consequence arrive live — the contractor's photo close-out landing in the HSE review queue. How one visitor experiences a two-sided loop without switching seats mid-story. Co-actor actions are real domain writes in the visitor's own Demo World. _Avoid_: "bot", "ghost", "simulation" (nothing is mocked — the writes are real).
Re-anchor (demo sense)
The Demo Template transformation that shifts every timestamp in the scrubbed extract so the snapshot's "present" lands on today, preserving site-local wall-clock times — making a Demo World's data genuinely current instead of frozen at the extraction date. The shift is followed by the settle onto the present: whatever the snapshot recorded *after* its anchor (rows written after the site's data lock) is told as having happened AT the present, so no record is born, signed or expired in the world's future. _Avoid_: "rebase" (collides with git and with the Alembic migration-chain rebaseline), "date shift" (imprecise about the wall-clock-preserving contract).
History class (re-anchor sense)
What a temporal column records, which decides how the settle onto the present treats it: happened (an occurrence — collapsed onto the present), schedule (a plan, deadline or window — shifted only, the future may stay the future), latch (a sweep's "already told them" stamp — cleared, the sweep has not fired), chain (a version chain's validity bounds — fast-forwarded) and record day (the day a record is *of* — a record of a day not yet begun never existed). Declared per column name in app/demo_world/reanchor_history.py; an unclassified column fails the build. _Avoid_: "timestamp type" (the SQL type does not say which of these it is).
Fabricated history
Deterministic fictional records — stoppages, ledger events, inspection runs, review chains, investigation timelines — written into the Demo Template after scrub verification, giving the record classes the scrub necessarily drops a believable past. The substrate every history-selling demonstration stands on. _Avoid_: "synthetic data" (too broad — synthetic floor plans are a different thing), "backfill" (collides with data-migration backfills).

Learning surfaces — tutorial & onboarding

Lesson
The atom of teaching: everything we teach about *one addressable thing* — a tool (Worker, Box-select), a panel (Noticeboard, the permits board), or a concept that has no single button (clash detection, the timeline scrubber, Floor focus). Keyed to that thing's id in a tool/feature registry. Concept-Lessons (no backing control to point at) are first-class — the reference library needs a "what is a clash?" entry even though there is no clash *button*. A Lesson holds up to two *renderings* of the same teaching: a Clip and a Recipe. Authored once; composed by many Tours and by Contextual help. _Avoid_: "module" (overloaded — names the unit but also any code module), "topic", "card" (Briefing already owns "card"), "step" (a step is one beat *inside* a Recipe, not the Lesson).
Clip
The reference rendering of a Lesson: a short, authored, autoplaying screen-capture (+ blurb) that shows the thing in ~10 seconds. The *pull* artifact — what Contextual help surfaces, and the medium of the per-tool reference library. Produced by the docs-site capture pipeline (provenance- hashed, staleness-flagged). _Avoid_: "video" (a Clip is a short silent loop, not a narrated film), "screencast" (implies length + voiceover).
Recipe
The tour rendering of a Lesson: the live step(s) that teach the thing by making the user *operate the real app* — what to spotlight, what outcome to wait for, what consequence to point at once it happens. The *push* artifact — what a Tour sequences. A Recipe drives and observes the live app in the user's own Demo World (or real site); it renders nothing pre-recorded. _Avoid_: "script" (overloaded with JS), "flow" (collides with the capture pipeline's Playwright flows), "steps" alone (a Recipe is the named bundle).
Reveal beat / Do beat / Nav beat
The kinds of step a Recipe is built from (BeatKind = 'reveal' | 'do' | 'nav'). A reveal beat — the app points the user at something that has appeared (the now-red token after a clash, the clash row in the Noticeboard) or narrates over a dim, while the user watches. A do beat — control passes to the user; the beat completes when the user *achieves the beat's outcome*, however they get there (gating is on observable domain state — "a clash now exists", "a pin is selected" — not on a prescribed click path). A nav beat — a click-gated navigation step that moves the user to the surface the next beat needs. A Tour interleaves them. _Avoid_: "show step / action step" (weaker), "task" (Task is the surfacing concept), "interaction" (every beat is an interaction of some kind).
Tour
An ordered, audience-targeted sequence of Lessons plus connective narration — a *playlist*. Owns no teaching content of its own; it sequences and frames Lessons' Recipes. The prospect Tour is one ("spatial basics → move a worker → watch it clash → wind the clock → read the noticeboard"); a "permits deep-dive" is another; a role-specific customer-onboarding Tour is another. The same Lesson may appear in several Tours. _Avoid_: "walkthrough", "journey" (buzzword), "guide" (the docs-site Guide zone owns that word), "wizard" (implies a one-off form-completion flow).
Contextual help
The pull surface: surfaces a *single* Lesson's Clip (+ blurb) right where its tool lives, on demand — reached by a deliberate affordance on the tool itself. No sequence, no narration, no app-driving — just "what is this thing", summoned when the user wonders. The reference half of the system; the Tour is the guided half. _Avoid_: "tooltip" (a tooltip is a one-line label; Contextual help opens a Clip), "help mode", "inspector".

Role handbooks — permission-derived induction

Handbook
A per-role induction document, derived from the permission spine rather than hand-maintained: one book per distinct ROLE_PERMISSIONS frozenset (viewer and client merge into the read-only book while their sets stay identical). A book's reachable-feature skeleton is generated from the Permission model and stitched into a workflow narrative by authored connective tissue, so a permission change mechanically updates the book and flags the stitching for review. Public: a handbook describes the product's role model, nothing site-specific. _Avoid_: "role guide" (the Guide zone is the end-user help; a handbook is the role-scoped induction read), "manual".
Band
The coarse capability class a role holds on a feature — one of view, contribute, manage, approve, in ascending order. Derived mechanically from the role's permission verbs on that feature (the highest verb class held), it is the one-line summary a Handbook shows against each feature; the full all-roles × all-verbs matrix is the internal reference on the feature page. A band change is pinned and queued for stitching review, never silently re-pinned. _Avoid_: "level", "tier" (a tier is the documentation quality contract, a different axis), "role".
Placement
The unit of authorship in a Handbook: a ::: feature <row> block whose head the generator fills (feature name + Band line + link) and whose body is the authored connective tissue. Its position in the section tree *is* the workflow ordering. A placement naming a feature the book's role cannot reach breaks the build; a reachable tier-1 feature left unplaced reddens the coverage report; a reachable tier-2 feature left unplaced is swept into the book's "Also available to you" appendix. _Avoid_: "section", "entry" — a placement is specifically the feature block, tissue and all.
Was this page useful? Report a problem

No cookies and no third-party analytics. A verdict records this page's path — and a search that finds nothing records the words you typed — in this site's own server log.

Generated from source · SimOops living system reference