Ghost Citadel
Menu
PlaygroundPlay

Ghost Observatory documentation

75 entries: measures, guides, rules, commands, settings, warnings and source fields. Each entry identifies its snapshot or published scope; the earlier reference and sample do not describe the newer measure contract.

Updated

Browse documentation
Documentation homeMeasuresInstallation · earlier referenceCommands · earlier referenceReaderAll topicsA–Z index

Start here

Choose the reference that matches your Engine and Reader. The setup instructions and measure articles below describe different development snapshots.

Earlier setup reference

Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649

Install and run
Set up the Engine and Reader.
Prepare your first export
Map an event log and check the first run.
Commands and configuration
The complete command, setting and warning reference.

Current measure snapshot

Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot

Measures and formulas: definitions, worked examples and publication rules for this snapshot. The earlier setup instructions do not establish compatibility with it.

Understand a statistical method

These articles explain the mathematics before its use in Observatory. Each includes a formula, worked example, interpretation and references.

Browse by topic

Time and flow

9 entries
Process arrivals and closures: daily countsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
How Ghost Observatory counts new, completed and other closed objects by day, and how those flows differ from process-event counts.
Due-date risk: conditional probability and worked exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Calculate conditional due-date risk from Kaplan–Meier survival, inspect the older-closure basis and distinguish a missing estimate from a past-due object.
Kaplan–Meier survival: formula and time-to-close exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Follow the Kaplan–Meier formula for time to close, with a worked censored sample, closure outcomes, median thresholds and the Engine's population rules.
Lead time: definition and process exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Calculate elapsed time from an object's first recorded event to closure, and understand completed-only summaries, open objects and missing values.
Processing time: activity durations and parallel stepsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Read activity durations and object processing totals, including parallel steps, source duration policies and the limits of interpreting recorded time.
Remaining time: conditional median formula and exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Calculate an open object's conditional median time left from the survival curve, and see why subtracting its age from the overall median can be wrong.
SLA elapsed timeConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Calculate SLA time inside service-calendar hours, account for recorded pauses and compare the Engine's elapsed clock with the source system's own result.
Waiting time: process gaps, overlaps and worked exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Understand measured gaps, overlapping steps, linked work and external waits, with the exact rules for transition medians, P95 and waiting targets.
Work in progress (WIP): daily and average countsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Compare daily not-closed object counts with time-weighted average WIP, including unknown outcomes, reopening intervals and analysis-window boundaries.

People and work

2 entries
Earned time from activity targetsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
The formula for earned time in Ghost Observatory, with configured activity targets, event attribution, missing-target rules and a worked example.
Recorded work time and overlapsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
How Ghost Observatory combines recorded work intervals, counts overlapping time once and keeps unplaced work, screen time and schedules separate.

Statistical measures

6 entries
Kernel density estimation: duration curves and bandwidthConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Understand Gaussian KDE on log durations, Scott and Silverman bandwidths, comparison populations and the conditions for a published duration curve.
Percentiles: median, P90 and P95Concept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Calculate median, P90 and P95 with linear interpolation, check the minimum sample and identify the duration population behind each published percentile.
Relative risk and lift: formula and confidence intervalConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Compare a rule segment with the rest using relative risk, the Katz interval and explicit minimum counts, including the correction for zero cells.
Statistical process control: log-duration control limitsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Follow the log Individuals control-chart formula, geometric centre, moving ranges and the evidence required before Ghost Observatory draws limits.
Theil index: formula and worked exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Learn the Theil T formula with a worked example, interpret event-count concentration, and see how Ghost Observatory compares it with random allocation.
Wilson score interval: formula and worked exampleConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Calculate a Wilson score confidence interval with a worked example, then see how Ghost Observatory uses its lower bound for rule alerts.

Process paths

2 entries
Process variantsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
How Ghost Observatory groups complete activity sequences, counts their objects and calculates completed-object median and P95 times.
Repeated steps and returnsConcept · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
How Ghost Observatory counts repeated activities, objects with repeats and repeats after a return, including unknown-order limits.

Data sources

2 entries
Export requirementsGuide · Earlier product guidance · version not specified
Required fields for process paths, timing, handovers, controls and due-date analysis, with five checks to make before a run.
Rejected rows and unmapped columnsGuide · Earlier product guidance · version not specified
Understand missing columns, input_columns_unmapped warnings and rejected rows, and update field mappings when an export changes.

Commands

4 entries
observatory run [CONFIG]Reference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Run Ghost Observatory with a configuration file, choose the result path with --out, and select analyses with --tasks.
observatory validate --config FILEReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Checks every source against its contract and prints one JSON line per source: its status, the rows read, accepted and rejected, and a note.
observatory inspect FILE --jsonReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Prints row counts for non-sensitive tables. Add --include-sensitive to include every published table.
observatory guiReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
The desktop launcher. It needs the gui extra. Its options are --config FILE, --db FILE and --check.

Environment

4 entries
OBSERVATORY_PSEUDONYMIZATION_KEYReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Configure a 32-byte pseudonymization key as 64 hexadecimal characters when ANONYMIZE is true, or use OBSERVATORY_PSEUDONYMIZATION_KEY_FILE.
OBSERVATORY_MAX_NATIVE_THREADSReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Set OBSERVATORY_MAX_NATIVE_THREADS to a positive integer to cap Polars and BLAS threads used by Ghost Observatory on the local machine.
OBSERVATORY_READER_HOST, OBSERVATORY_READER_PORTReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
The current Reader does not read these environment variables. Use --host and --port instead.
OBSERVATORY_READER_*Reference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Configure Reader authentication with basic auth, bearer tokens or a trusted proxy, require authentication, and control access to the health endpoint.

Source keys

11 entries
id, path, source_systemReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Set a source ID, file path and adapter contract in Ghost Observatory. Find contract IDs in catalog.yaml or with obs.available_yaml_adapters().
role, domain, grain, authorityReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Describe source rows with role, domain, grain and authority. The sample maps event, work, object and desktop sources to explicit roles and authority values.
required, includeReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Control source inclusion in Ghost Observatory YAML. A missing required source blocks a run; include: false excludes the source from processing.
system, object_typeReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Declare the system namespace and object_type for Ghost Observatory source rows. Keep identifiers scoped to the correct system and type of work object.
timezone, encoding, delimiter, localeReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Set timezone, encoding, delimiter and locale for one Ghost Observatory source. Source parsing options override the corresponding run settings.
field_mapReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Configure field_map in Ghost Observatory YAML to map each canonical field to its source column. Read the definition and a minimal mapping example.
sequenceReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Declare event order fields and their basis in a Ghost Observatory YAML contract. Read the sequence definition and its role in paths and waiting times.
paramsReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Configure Ghost Observatory adapter params, including trace completeness, duration evidence policy and the sheet option for selecting an Excel worksheet.
object_link_expectation, object_relation_typeReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
object_relation plus a relation type makes the source a set of links between objects.
property_columnsReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Declare typed object attributes with property_columns in Ghost Observatory. Read the key outline and consult the selected contract for supported types.
source_context, json_envelopeReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
A declared parent object_id for saved pages, and the exact key paths (rows, errors, has_more) into a JSON document.

Measures

1 entry
Process mining metrics and formulasGuide · Engine 19.0.0rc597 · Reader 9.0.0rc656 · Development snapshot
Learn Theil, percentiles, lead time, WIP and survival analysis through formulas, worked examples and Ghost Observatory's implementation rules.

Before you write a configuration

7 entries
Lifecycle tokensReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Configure Ghost Observatory lifecycle tokens for completion and cancellation. Tokens match recorded activity names rather than raw status values.
Work-time evidenceReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Distinguish self-reported and system-observed work using source_metric_basis or a desktop export. Process-step duration is not a person's recorded work time.
OrderReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Declare process order with sequence in Ghost Observatory. Missing order withholds paths and waiting times; timestamps never substitute for declared order.
CalendarsReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Define workforce calendars in Ghost Observatory. Missing calendars leave schedule values unknown; assignments prefer the person, then team, then organisation.
The first and last dayReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Understand partial first and last days in schedule totals. Set analysis.windows to whole days when the observed period covers only part of a day.
PeopleReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Map a person’s accounts with identity_resolution in Ghost Observatory. Unmapped accounts remain separate identities scoped to their source system.
Time zonesReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Configure IANA time zones in Ghost Observatory. Timestamps without a zone use the run’s TIMEZONE, and the run records that interpretation.

Warnings

11 entries
input_columns_unmappedwarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Fix input_columns_unmapped by mapping any needed export fields in the adapter's column_map. Extra columns that are not needed can be ignored.
invalid_timestamphigh · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Rows with timestamps that do not match the declared formats were rejected. What to do: Add the file’s format to timestamp_formats, or fix the export format.
end_before_starthigh · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Rows with an end time earlier than their start time were rejected. What to do: Check the source’s clocks.
timestamp_zone_from_run_settingwarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Clock values had no zone, so they were read in the run’s TIMEZONE. What to do: Set TIMEZONE, or export with a zone.
duplicate_event_grain_consolidatedwarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Duplicate exports are counted once and recorded as exact_duplicate_event in row_decisions. Export an event ID when the records represent distinct events.
sequence_withheldinfo · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Events were kept but have no declared order. Timestamps are never promoted to process order. What to do: Declare sequence.fields and sequence.basis.
person_identity_source_scopedwarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
People are known only inside their own system and are not joined across systems. What to do: List them in identity_resolution.canonical_people to join them.
work_record_without_durationwarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Work records state no work time, so every total that includes them is unknown, not smaller. What to do: Export the duration.
schedule_clipped_to_observed_periodinfo · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Schedules use the observed period unless analysis.windows defines start and end. Set whole days to avoid partial schedule totals on the first and last day.
terminal_vocabulary_unmatchedwarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Fix terminal_vocabulary_unmatched by configuring completion and cancellation activities. Without a match, objects stay open and lead time is not measured.
time_to_close_insufficient_objectswarning · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
The time_to_close_insufficient_objects warning marks too few closures for a population estimate. Use the curve descriptively or include more observations.

Three things to know before you query

3 entries
Select one scopeReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
A scope_id is one analysis window and one evidence stream. The same object or person appears in several scopes, so select one scope before you count or sum.
Keep evidence classes separateReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Keep reported, observed and unclassified work separate. Overlapping evidence classes are never summed, and process-step duration has no work evidence class.
Completed is not approvedReference · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
An object whose outcome is completed reached the end of its history, whatever the business result. An approved claim and a rejected claim both end completed.

Worked example

1 entry
From a flagged claim to its source rowGuide · Published synthetic sample · Engine 18.6.0rc450
Trace a synthetic claim from the Reader to SQLite, independently recount the rule result, and inspect its original source rows.

Features

2 entries
Data settings: calendars, time zones and pseudonymsConcept · Earlier product guidance · version not specified
Configure pseudonyms, calendars and time zones, inspect data issues and choose how to use the result file and optional AI.
Nine questions the Reader answersGuide · Reader development preview · Engine 19.0.0rc597 · Captured 1 November 2026
Explore nine operational questions, the workspaces in the Reader development preview and the source fields required to investigate them.

Installation

3 entries
Run your first real exportGuide · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Map an order export in observatory.yaml, declare event order, validate the inputs and open the result in the Reader.
Reader launch optionsGuide · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Launch the local Reader, choose its address, open a result file and read the authentication, upload and validation options.
When a run stopsGuide · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
What a blocked run means, why it leaves the previous result untouched, and how validation and exit codes identify the problem.

Manufacturing

1 entry
Manufacturing export checklistGuide · Earlier product guidance · version not specified
Prepare ERP, MES and inspection histories for manufacturing analysis: object identity, declared sequence, timing and source authority.

Reader

1 entry
Reader workspaces and viewsGuide · Reader development preview · Engine 19.0.0rc597 · Captured 1 November 2026
Overview, Processes, People, Objects and Timing in the November 2026 Reader development preview, with links to selected screenshots.

Separation of duties

1 entry
Verify a separation-of-duties rule with SQLGuide · Published synthetic sample · Engine 18.6.0rc450
Query checked and flagged claims for an assessment-and-approval rule in the published SQLite sample, then inspect affected records.

Technology

4 entries
Calculation rulesRule · Historical design guidance · no release version established
Historical Ghost Observatory design rules for publication, time representation and missing values, with links to versioned measure references.
Python API and AI accessGuide · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
Use the Python API or SQLite to read results. Learn the API's read-only query controls and explicit access to sensitive tables.
Release checksConcept · Earlier product guidance · version not specified
How release checks rebuild samples, compare results with independent calculations and verify contracts, adapters and Reader views.
Security and runtimeGuide · Earlier product guidance · version not specified
Local data handling, pseudonyms, read-only results, Reader authentication, network boundaries, upload limits and exit codes.

A–Z index

75 entries

C

  • Calculation rules Technology · Historical design guidance · no release version established
  • Calendars Before you write a configuration · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
  • Completed is not approved Three things to know before you query · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649

D

E

F

I

  • id, path, source_system Source keys · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
  • input_columns_unmapped Warnings · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649
  • invalid_timestamp Warnings · Earlier command and setup reference · Engine 18.6.0rc590 / Reader 8.11.0rc649

K

L

M

N

O

P

R

S

T

V

W