Skip to content

Latest commit

 

History

History
788 lines (675 loc) · 48.7 KB

interfaces.md

File metadata and controls

788 lines (675 loc) · 48.7 KB

Interfaces

Every way to reach Sinex: the operation table and its transports, callers and their powers, the CLI, MCP, status, watches and stall alerts, live reads, and the latency budgets. The query catalog and its behaviour are in query; recall and agent arrival in recall; Today and the reader in web. The shared mechanics (the Operation trait, request and answer envelopes, the failure-to-exit-and-HTTP table, latency classes and deadlines, SSE framing, the status figure format) are the common command-surface crate's, including the answer contract every surface uses (envelope, section status, value states, budget fitting, errors); the signal rule schema, evaluator and route function are common signals.

Principles

  • One question, one answer, every surface. One parsed question, one resolved read context and one server-side answer serve the CLI, MCP, HTTP, follow and the reader. Page size, presentation budget and deadline never change what was selected.
  • One entry point for questions. The query is the entry point; a new capability arrives as a table, an alias, a stage or a verb on rows, never as a top-level command that restates a query. (ruling 2026-05-25, cc-queued:c2404522-7bba-4de3-936d-e08deb14262c@2026-05-25T00:40Z).
  • Agents are primary users and get no fewer powers than the operator; what distinguishes the operator is authorship, which the daemon computes. (ruling 2026-06-01, journal 2026-06-01 06:54).
  • Legible and honest. Every answer says what was observed, what was derived, what is unknown and what was left out of the display. A quiet source is not a failed one; a running process is not evidence of capture; a command with no recorded end is "end not recorded", never "running"; proximity is not provenance.
  • Captured text is data. Every result holding captured text carries the data notice, delimits payload text per row and escapes control sequences. What is masked, hashed or withheld is decided only by the operator's configured rules, applied identically on every output (output parity).
  • Nothing unasked without a rule. No streaks, scores, gamification or unsolicited behavioural advice; anything Sinex surfaces unasked comes from a declared signal rule.

Operation table

  • One typed operation table declares every command once. The CLI parser, the socket and HTTP routes, the MCP tools (with outputSchema generated from the answer types), help, completion and the shipped agent skill are generated from it. A command missing from the table fails closed.
  • Every feature reachable through MCP is in the CLI, and the reverse, unless the table records a reason. (ruling 2026-07-29, cc-queued:d6f4b0c3-840b-47b6-bd57-5f1bd6c9c7d4@2026-07-29T01:12Z).
  • The write path. Handlers hold only the read pool. Every write (stage, derived note, note, duplicate decision, curation, saved query, signal rule, archive request) goes to the one admission function as a request material plus events.

Transports

  • sinexd serves a Unix socket and an HTTP listener carrying one typed request protocol: POST /v1 with a tagged request, GET /v1/commands for the table's metadata, SSE for follow. There are no dotted method aliases.
  • The listen address and authentication mode are deployment configuration (default loopback with a peer-uid check; a token file for any other address) set through the NixOS module, the config file or environment variables (configuration). Phone or remote access is that configuration, not a product feature.
  • Requests are strict. Unknown fields are refused. A request that changes state (archive, restore, replay, tombstone, stage, recompute) has no default scope: an omitted scope is an error, never "everything".
  • Health is its own route: up or down, without internal error text, separate from capture health.
  • Version. The server reports its version; the client warns on a mismatch.
  • The daemon is required. Commands go through sinexd. Only the declared offline diagnostics (verify, status --offline, store verify) read the database directly through the reader role, and completion works from the published catalog file. (ruling 2026-09-14, cc:652ae14f-a036-496b-abfa-42e7574c9ec9:b8a68d64-772f-4d8c-8e95-435ce601d245).

Failures

Current build. Every failure is the shared command_surface::Failure (kind, message, product code, position and caret in the input, hint, suggestion, candidates, retryable), mapped once to an exit code and an HTTP status by the shared table in command-surface. Sinex uses the shared kinds as they are; stopped_early is the shared kind for an operation that did not finish.

  • On the wire a reply is {"outcome": "ok", "result": …}, {"outcome": "failed", "failure": {…}}, or {"outcome": "stopped_early", "failure": {…}, "result": …} when an archive, restore, replay, recompute, stage or tombstone moved some batches and then stopped; result names what moved and resume OPERATION continues it (lifecycle). A stopped operation is never reported as ok.

  • One conversion. Each layer of the daemon keeps its own typed error and converts into the daemon's error with ?; the method boundary turns that into the failure. A query refusal is placed in the query text there, with its span, caret, suggestion and candidates.

  • Database errors are classified by one table in sinex-store:

    Database error Kind Retryable Code
    no row not_found no
    the read pool has no free connection in time timeout yes read_pool_busy
    pool closed, connection lost, TLS, server shutting down (08…, 57P…) not_running yes database_unavailable
    unique violation (23505) conflict no the constraint
    foreign key, not null, check (23503, 23502, 23514) bad_value no the constraint
    statement timeout (57014) timeout yes statement_timeout
    serialization failure, deadlock (40001, 40P01) conflict yes the SQLSTATE
    insufficient privilege (42501): the reader role may not do it refused no the SQLSTATE
    a connection URL this build cannot use bad_value no
    any other internal no the SQLSTATE
  • Internal failures describe stored data the product cannot read, a broken invariant, or a task that stopped. They are internal, exit 4 and HTTP 500, and are not retryable. A schema declaration error has the same kind.

  • File and blob errors are classified in the same module: a missing file is not_found, a forbidden one refused, a slow one timeout; a sealed blob read without its key is refused; damaged bytes and any other disk error are io.

  • HTTP answers each failure with its kind's status; a kind with no status in the table (not_running, cancelled) answers 503. A missing or unknown token is answered 401 before any operation runs, with a refused failure.

  • sinexctl exits with the failure's code. A read that succeeded and matched nothing exits 1; Sinex has no other empty outcome. The CLI's own failures use the same table: a missing token file is not_configured, an endpoint or argument it cannot use bad_request, a daemon it cannot reach not_running (daemon_unreachable), and an answer it cannot decode not_running (daemon_protocol_mismatch: the daemon was built from other sources). Failed offline diagnostics are io. With --json a failure is {"error": {…}} on standard output and nothing on standard error; without it, standard error carries the message, the caret, the hint, a runnable correction and the candidates. sinexd exits with the same codes.

  • A daemon connection failure names the endpoint tried and the service-start command. A missing-token hint names read.token, agent.token and operator.token, which sinexd writes in its token directory, and --token-file selects one explicitly. A missing writer names sinexd run; a replay requiring the operator's key names sinexctl unlock IDENTITY_FILE.

  • MCP answers a failure as a tool error (isError) whose text is the message with its caret and correction, and whose structured content is {"error": failure}; never a success with empty rows.

Target line failures

Decided target, not built. The common request-level outcomes are ok, empty, degraded and error. A failed step has status: "failed" inside the line answer; previous step reports and undo lines remain present. Grammar reasons such as needs_all are product codes under bad_request, not new shared kinds. The shared failure table determines HTTP status and exit code: 0 success, 1 empty, 2 invalid input, 3 refusal, 4 not-found/conflict/I/O/internal, 5 stopped-early or degraded, 6 not-running, 7 timeout/cancelled. Current wire examples above describe the command-first build and do not replace the typed target line contract.

Callers

One command set

The operator and agents hold the same command set; there are no ordered access tiers. (ruling 2026-07-03, cc-queued:30f5e650-7033-4423-9f91-2b66ebd1e6b2@2026-07-03T13:20Z).

  • Grants are per-credential configuration, seeded with defaults by the NixOS module, never code constants. Which output a caller sees is decided by the output rules, which are the same for every caller (privacy); nothing is refused because the caller is an agent. Privacy rules may be written by any author; status lists those written by anyone but the operator as non-operator changes.
  • The credential carries grants; it is not an identity.
  • An act reserved to the operator is an explicit configured rule with its reason, listed in configuration and in help, never inferred from the token. The seeded reserved acts:
Act Rule Reason
confirming a tombstone's cascade preview any caller requests and previews; the operator confirms interactively (default; open operator question) tombstoning is the one irreversible deletion (tombstone)
same/distinct duplicate decisions that govern fusion every caller records decisions; the operator's govern, and a per-family setting admits others' duplicate decisions shape every fused record (fusion)

Computed authorship

  • Every write records written_by: author (operator, agent:<session>, agent:<origin>, script:<unit>, unattributed) and via (cli, mcp, web, hook, daemon, import, desktop).
  • No request field names an author. The client reports its harness identity (the variables supported harnesses already set: CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID, GEMINI_CLI, HERMES_SESSION_ID; for MCP, the harness connection), and the daemon decides:
    • the nearest harness wins;
    • operator only through the operator's own channels with no harness identity (an interactive terminal without harness variables is the operator);
    • script:<unit> from the calling process's cgroup unit;
    • otherwise unattributed.
  • No job runner is recognised by name. A launcher that forwards its caller's harness variables keeps the caller's session.
  • events where written_by.session = S lists everything one agent session wrote.

Agent writes are visible and undoable

  • Status lists the last week's agent writes by session and kind.
  • Decided target: sinex 'writes where by:S' undo --all [--dry-run] reverts every write one session made, listing it first and recording each reversal with its own author. It archives the session's notes, duplicate decisions, curation, saved queries, signal rules and derived-note outputs; archives what the session's stages admitted; and undoes the session's replays by the usual replay undo, possible at any later time. A tombstone confirmed in the session is listed as not revertible. A second undo restores what the first archived.

Derived conclusions

Decided target: sinex 'PARENT-REFERENCES' note PAYLOAD --as KIND writes an agent's derived conclusion: a registered kind, a payload matching its schema, at least one parent citation, the computed author, and the producer agent:<session> with its model as producer version. It passes the same admission and is withdrawn by its author's archive act or by session undo. Programs that derive continuously use the ingress as outside handlers, not a one-off note.

Agent guidance shipped with Sinex

  • Sinex ships a skill text generated from the operation table: what Sinex holds, the core operations, example queries with their read_as, the data notice, and the rule "cite event IDs". Sinex's NixOS module installs it into each harness's skill directory; the target sinex help --all prints it for other installations. (ruling 2026-10-18, cc:ee52794c-8a9e-43b6-9fbc-9749c7e78e8f:12f1a067-cc5b-41b7-9209-297099d6b0c1).
  • The MCP instructions field carries its summary; each tool description is short and says when to use the tool.
  • Context reaches agents without their asking, through Polylogue's session-start brief (agent arrival).

CLI

Decided target (2026-11-18), not built. The client is sinex; the daemon and its maintenance commands remain sinexd and sinexd admin. The current build still ships sinexctl with command-first parsing and one MCP tool per exposed command. Use sinexctl --help, sinexctl COMMAND --help, the generated tool list and GET /v1/commands for that build. The examples in this section specify the target; they do not claim that the binary rename or command port has shipped. The rename moves callers, packaging and integrations together and leaves one client name.

Grammar

sinex                                      Today on a terminal; status otherwise
sinex COMMAND [ARGS] [OPTIONS]
sinex SELECTION [OPTIONS] [VERB [ARG] [OPTIONS]]…
sinex recall | note TEXT | resume           the forms needing no selection

A selection is one shell argument. Quotes hold which rows; the words after them say what to do. A time lists its timeline, a path or URL its history, and a plain word searches. Queries retain the shared language's explicit | transforms:

sinex 'commands where cwd:/src/tide since:7d' read
sinex yesterday recall
sinex ~/src/tide/src/store.rs
sinex 'items where tag:place:norway' pick save collection:wallpapers
sinex note 'check bench disk' --when here

The first matching rule classifies the first argument locally, from declarations and the cached catalog: no argument; - for stdin references; command; verb; saved query name; unit; complete time expression; path or URL; reference; query text; plain-word search. Commands and verbs beat saved names. A time classifier must consume the complete argument: 'yesterday | where source:desktop.*' is a query, not a time with an ignored suffix. Paths begin /, ~/, ./ or ../; URLs begin http:// or https://. A reserved word can be searched with inner quotes, for example sinex '"status"'.

Each verb takes its declared number of words. Required text stays text even when it names a verb: note read writes read. The optional name in save read is absent, so read starts the next step. Literal -- marks one selection or required word, without disabling option parsing for the remaining line. Free text is one argument or -; stdin can be read once per line. An unquoted multiword query is refused with a shell-quoted correction. Commands and verbs are never guessed.

Verbs

Verb Words What it does
read 0 render rows in full; --view trace, --view privacy, --view compare; --follow streams; --to chooses output or an application
pick 0 narrow rows with the embedded picker before later steps
recall 0 build a cited pack; --as RECIPE, --rows LANE, --at then (recall)
note 1 write text; --as KIND writes a form, definition, forecast or derived conclusion
tag 1 label rows with NAME or NAME:VALUE; --remove takes it off; --empty records an explicit empty property
edit 1 revise an authored record, retaining its history; --expects REV checks the base
withdraw 0 take back an authored record, with history retained
judge 1 accept/reject/defer, rate --on SCALE, compare named rows, decide same/distinct or resolve a forecast
save 0 or 1 keep the question and selected rows; optionally name it, add --watch, or save to collection:NAME
archive 0 move selected live chains to the archive
restore 0 restore archived chains
replay 0 read stored originals again or recompute a derivation; --trial retains a comparison; --switch TRIAL selects its version
tombstone 0 permanently remove archived payloads after the applicable operator confirmation
undo 0 reverse an operation or request of writes
continue 0 continue an operation from its committed position
resume 0 reopen an episode or item where work stopped

The lifecycle's meanings remain in lifecycle; library curation in library; typed evidence records in evidence. resume means reopening work, while continue means an unfinished operation. There are no command aliases for replaced spellings.

Commands

Commands concern the system or intake rather than selected rows:

Command Purpose
help [TOPIC] one-screen cheatsheet; help query, help units, help fields KIND, help --all
status capture and consumer progress, hosts, disk, agent writes and privacy; --line, --follow, --offline, --verify
stage PATH… admit files, directories, databases, URLs or stdin (staging)
set [KEY [VALUE]] show effective settings and origins; change settings owned by Sinex
unlock FILE unlock sealed fields for --for D; --off locks them
install TARGET install shell completion/picker bindings or a harness MCP entry and skill; --dry-run, --remove, --program NAME
web open the reader
demo DIR build the synthetic world
mcp run the stdio MCP server
dev … read-only sql, feed --after POSITION, and `backup hold

Bare sinex renders Today on a terminal and status otherwise. Deployment-owned settings are displayed with the option that owns them; set refuses to replace them. status --offline and status --verify use the existing sinexd admin diagnostic owner; this is not a second database implementation.

Options and chains

Line options go anywhere: --json, --deadline MS|none, --request-id ID, --dry-run, --explain, --wait D, --hold D, --until-empty, --all, --endpoint, --token-file. Listing options before the first verb are --page-size N, --fields a,b, --why, --to, --format and --cursor. After a verb, options belong to that verb and undeclared options are refused.

Option Meaning
--page-size N transport rows per page, default 50; does not change selection
`--budget N none`
--cursor C continue the same question and read context
--all authorize a write or act on every row a query matched; not a paging option
`--to stdout pager
--format F document encoding, including JSONL and full citations
--json encode the whole reply as JSON
--why explain matches, defaults, or a figure's missing/partial state
--explain explain the parsed line and intended effects without running them
--dry-run report all effects without writing requests, runs, trials or other records

The selection resolves once at the first step's position. Only pick narrows it. Steps finish in order; a failure stops the line and retains each completed result and its undo line. Grouped/measured rows accept listing, read, recall and save. Writes and acts over several query rows require --all, with a count and runnable correction on refusal. A one-row act never chooses an arbitrary row: it offers a picker on a terminal or candidates otherwise. read --follow is last.

Retry retains the accepted selection, options, step identities and committed outcomes through the existing request/operation owner. It must neither select newly matching rows nor replay committed writes or application launches. A read continuation contains only that read and its original options and grants. Every state change prints its reversal (withdraw, request undo, or operation undo), including what cannot be reversed. Captured text is escaped and delimited under the same output rules on every surface.

Output

Lists are newest first unless the question orders them, with one screen of 50 rows and a footer carrying the read position, coverage, omissions and next lines. A terminal uses the pager for more; a machine receives structured rows and a continuation. Rendering goes to stdout; guidance and undo lines go to stderr. Colour encodes status, respects NO_COLOR, and is used only on a terminal. Unknown values say unknown; a count over incomplete coverage says lower bound. An empty answer distinguishes no match from unobserved or withheld evidence. A closed output pipe exits 141 without a panic.

read --to FILE writes one document; --to DIR writes an atomic bundle with its manifest, question, read context, references, omissions and replay recipe. It retains original-byte citations and applies output rules. Opening through --to app uses a declared opener and exact part/position, recording a view only when it was actually shown. A missing file or application is a typed failure.

Completion, picker and references

Completion uses the catalog atomically published by the daemon and works offline. It understands the grammar position, query fields/types/values, saved names, valid next verbs and their options, and says why a candidate applies. Shell registration for bash, zsh and fish comes from install; wrappers use --program NAME. MCP completion and the reader query box use the same typed query completion. No completion round trip waits on the daemon.

The embedded picker opens only with terminal input/output and no harness or machine format. It shows the selected question, counts and preview, keeps exact references and supports multi-select before subsequent verbs. Its key table and the completion/help/refusal rendering have one common owner shared with Polylogue. The immediate parser reuse is narrower: classification and argv step splitting around StepDeclarations::parse_step; product resolution and I/O remain local.

@3, @3.2, @2-5, @1,4 and @all refer to the last displayed listing in this terminal, with its question, read context and continuation. They are terminal convenience, never stored citations or MCP references. Durable references and ambiguous short forms are defined in citation forms. There is no REPL; the shell, pager, completion, picker and reader form the loop.

Help and orientation

help is a one-screen cheatsheet with runnable examples drawn from available data, plus help VERB, help query, help units, help fields KIND and help --all for the generated agent guide. With no matching data an example says so. --explain reports classification, resolved scope and effects without executing them. Every shipped example is exercised on the synthetic world by its implementing command; future features are absent from current generated help and tool schemas until implemented. A not_built refusal is not a shipped future capability.

Family with Polylogue

Both products use one-argument selections, typed verb arity, ordered chains, common request/answer/failure contracts, deadline and presentation semantics, terminal row numbers, completion, picker and help mechanics. run: names an execution, --to an output destination, resume reopens work, and save keeps a question and its selected result. Shared mechanics live in common; product resolvers, SQL lowering and domain models stay in their products.

Sinex retains its lifecycle, intake, library and evidence semantics. Its recall builds packs across personal evidence; Polylogue's brief packages AI work. Polylogue's brief can carry Sinex's here pack through global references. The relationship does not make one product's future features the other's release prerequisites.

MCP

Complete target. Three nested tools replace the command-specific tools. The current build's tool schemas enumerate its implemented operations. Read operations use the same typed declarations and ready requests as HTTP; each remaining domain command moves when its replacement owns the behavior. sinex-commands owns those runtime declarations; sinex-protocol carries the wire data independently of the runtime and performs no I/O.

Tool Access
sinex_read reads, including rows, recall, status, help and read-only SQL
sinex_write reads, authored writes, reversible lifecycle steps, and staging paths/text
sinex_act reads/writes plus URL staging, work resume, tombstone, interruption requests and host application opening

They carry the shared envelope {operation?, arguments, request_id?, deadline?, budget_tokens?, cursor?}. operation defaults to rows; a rows call is, for example:

{"operation":"rows","arguments":{"selection":"yesterday","steps":[{"verb":"recall"}]}}

An ordered references array can replace selection; the two are mutually exclusive. MCP never reads a terminal's @N file. The connection supplies caller session metadata, while the daemon computes authorship. Credential roles (read/agent/operator) remain separate from tool read/write/act access. Dispatch checks both before effects; a higher-access tool does not grant a higher credential. A line requires its highest step access. Interrupting notes and host-opening reads require act access. Paths/text stage as writes; URLs stage as acts. Read-only SQL retains the reader role, current output rules and caller-bound paging. Host-opening read.to requires act access and one idempotent launch; FILE/DIR, pager and clipboard destinations belong to the calling process.

Existing common declarations generate the compact tool-list projection and validate the complete typed arguments at dispatch. Handwritten examples do not replace those schemas. Each answer retains the common envelope, structured rows, read context, continuation, data notice and per-row delimiters. Budgets count the encoded answer and cut whole items with omission counts. Failed steps retain prior outcomes and undo lines; MCP sets isError for the actual failure. A continuation repeats only its read. MCP excludes the terminal picker, row numbers, raw material bytes, live read --follow streams, local destinations, offline/byte diagnostics, unlock, install, web, demo, MCP-server startup and backup commands. A streaming refusal gives a finite read or CLI form. Read-only SQL remains in the read tool, under its existing reader role and output rules.

Status

The status view

status returns a shared verdict object: {state: healthy}, or {state: degraded|unknown, reason: TEXT}. reasons lists every current problem. A stalled or falling-behind consumer, or a stalled source, makes the verdict degraded; its first reason names the affected source or consumer. Consumer reasons state how far behind it is and when its progress was last observed. With no consumer position samples and no degraded condition the verdict is unknown. Otherwise it is healthy.

consumers lists the publisher, search index and derivations with name, position, behind, rate (positions per second), estimate_seconds, last_advanced and state. Rates use the last 15 minutes of self-observation. The states are current when nothing remains, catching_up when the remaining positions decrease, falling_behind when progress advances without reducing the remaining work, stalled when at least three samples spanning five minutes show an unchanged position with work remaining, and unknown with fewer than two usable position samples or an observation span too short to classify. Keyed derivations track dirty and waiting keys rather than a commit cursor; their position, backlog and progress estimates are unknown. Per-event derivations start at position zero until they save their first cursor. Estimates are unknown when the samples cannot establish a positive catch-up rate. last_advanced is unknown until a sample shows an increase; a stalled reason can instead name the start of the observed unchanged span. The rate window smooths short bursts; the shorter stall window exposes a stopped reader sooner.

sources contains all rows of sources | sort by binding, following every 50-row page. source_states counts rows in each input state. The same source relation supplies offline status and the doctor sources check. Status and diagnostics read its rows directly, without preparing calendar rows, loading event declarations or creating continuation tokens. doctor reports the search backlog and failures in the last 24 hours as information; the failure detail points to sinex 'failures where since:24h'. The informational located_files doctor check counts retained live located contents with no current recorded file path available on this machine. It does not add a counter or filesystem walk to ordinary status.

The wider status design covers:

  • the daemon, writer, bus and ingress backlog, and database;
  • per source, its run state and coverage;
  • per derivation, its position, lag, pending version switch and compare result, and last failure (versions);
  • fusion's ambiguity counts;
  • replays, stages and recomputes in progress;
  • refusal figures: the refusal rate per source and kind, and kinds whose every material is refused;
  • failures; archive size and growth; disk free and days until full (warning below 14 days);
  • the last week's agent writes by session;
  • outside consumers' positions and lag (outside handlers).

Every figure uses the shared figure state and verdict of command-surface. Sinex's domain fields keep their own values beside it, each with a stated mapping to the verdict:

Field Values
last_run new, repeats, nothing, not_run
gap state gap, unknown, estimated
input state capturing, backlogged, quiet, stalled, held, unavailable(cause), excluded(reason), finished (input states)
coverage complete, gap(reason), unknown, outside_span, not_yet, excluded, unavailable(cause), held (completeness)

A run that found only repeats is healthy; a staged export is never stale; a missing cell carries its reason. The daemon initializes configured derivation readers once and shares those objects with execution, comparison and status. Status reports their existing version fingerprints; it never launches document or OCR tools to rediscover them. Status reads self-observation events, so nothing is recounted on the request path. There are no scheduled verify, scrub or check runs, because invariants hold by construction: store verify is on demand, reports mismatches and repairs nothing. status --offline reads positions, the last commit and the writer lock's holder through the reader role while the daemon is down. Recent telemetry checks archive membership by each sample's event ID, so reading the status window does not scan unrelated archive history. The read retains its time window, class visibility and order within each consumer's samples.

The sources relation

  • sources is the one source status relation and sources NAME the one detail view. Gaps, inputs and payload shapes are the query tables gaps, inputs and shapes (tables), read and paged like any query, so there are no separate gap, continuity, drift or readiness commands.
  • Fields: source, binding, shapes, version, event_types, purpose, exclusion, state, reason, last_error, last_run, expectation, silent_after, every, expires_after and the remaining margin, coverage, behind, rate, refused_rate, shape_changed, days_with_data_30d, gaps_30d and last_success.
  • One source-status path classifies sources for fill, panels, recall, status and alerts: recorded poll outcomes (success, unchanged, failure), cursor positions, gap records with their missing count, record failures and shape observations, read under the answer's read context. Never source-name prefixes, process liveness, run lifetime alone, or earliest and latest event alone.
  • A never-read binding is never healthy; an unchanged successful poll is never a stall.
  • sources NAME gives per-input accounting: records read, events made, suppressed, matched to another input, record errors with the first unparsed form. An input whose records did not become events shows as such instead of reading as complete.
  • sources [FILTER] [--days N] [--host H] renders the Sources grid: one row per source, one cell per day in the coverage vocabulary, and the state with its reason ("STALLED since Tue 12:28 · database busy on every poll"). Its footer names derivation lag, failures, stored-unparsed materials and disk runway.

The status bar

Decided target: status --line emits one JSON line on change, for a desktop bar or dashboard to consume:

  • the capture stripe, coloured by the most invasive capture running now: green for files only, amber for screen, red for keyboard and screen; audio and accessibility count with screen. It is a capture indicator, part of capture status;
  • the count of quiet sources;
  • passive signals not yet seen;
  • per binding, producing_now (an event admitted in the last 5 s).

Polylogue on Sinex

When Polylogue runs on Sinex, status shows both sides: what Polylogue has sent and Sinex committed, the confirmed-stream position Polylogue has applied, and its lag. While Sinex is unreachable, pending counts are not_measured and up_to_date: false is shown, never success (Polylogue primary mode).

Signals

Decided target surface: a signal rule is called a watch. sinex 'QUERY' save NAME --watch creates one; sinex watches lists them. Stored signal.* kinds and the shared evaluator remain unchanged. Full rules use sinex query:NAME note RULE-JSON --as watch.

A signal is a standing query with a declared delivery rule. It is the only way Sinex surfaces anything unasked. The rule schema, the evaluator, the route function, the interrupt budget, inhibition, outcomes, wait, backtest and desktop notifications are common signals; its conformance cases run in Sinex. What Sinex supplies:

  • its catalog for rule queries;
  • value targets (a file or a loopback URL) and action commands, named in configuration;
  • occurrences keyed by citation (record coordinates, source record key or derived key, never the reading), so replay and re-import never fire a rule again;
  • the attention inputs: presence, focus with the window-to-session join, deep work and breakpoints from the higher layer.

Rules, deliveries and acts

  • Declared, never inferred. A rule is an authored record written by the operator or an agent through a saved query with --watch or note --as watch and runs as written. Status lists rules written by others since the operator last looked; disabling one is an authored revision.
  • Passive by default: a delivery appears in the inbox, Today's Signals pane, the status bar and the day pack. Interrupting only for rules marked so, under the one interrupt budget.
  • Event kinds: signal.rule (an authored rule revision), signal.delivery (one handoff by the host deliverer, derived from the rule or forwarded report that fired and the readings its rows were computed from) and signal.outcome (what happened to a delivery afterwards: an outlet's attempt, shown, cleared, closed), plus signal.report for evaluator reports another product forwards. Decided target, not built: form definitions for elicitation. The evaluator and host policy checkpoint is daemon state, not events. Every delivery stores its route decision, holds and attention, so "why did this fire" and "why didn't it interrupt" are both queries.
  • Acts: sinex delivery:ID read, judge accept|reject, judge defer --until 1h, and sinex set quiet 14:00|off. sinex 'QUERY' --wait D [--hold D] [--until-empty] blocks until the query first matches or empties, recording nothing; sinex query:NAME read --view backtest --from 30d replays a rule over stored history with the route decisions it would have received, and writes nothing.
  • Three deliveries, one mechanism: a notice, a value, an action. An action names only a command already in configuration, runs outside sinexd with the triggering citation as its last argument, and its result returns as events.

The host deliverer

Sinex is the one deliverer on its host. A product whose grant has forward_signals (Polylogue on Sinex) sends its evaluator's reports (firings, cleared conditions, rule revisions and withdrawals, progress) in a signals frame through the producer path; each report is stored as a signal.report naming its authenticated producer and family. A report about any product but that family is refused, a cleared report takes effect only on that product's deliveries, and the sinex family cannot forward. Sinex's host policy takes them in beside its own rules' reports and routes their firings under the host's attention, budget and quiet hours; a forwarded current-state firing is held until its producer reports being up to date. A forwarded value or action is recorded not sent, because its configured outlet belongs to its own product. Polylogue shows only its own "Sinex blocked" notice directly, because the path to the deliverer is what is broken.

  • Outlets. An interrupting decision becomes a desktop notification through the common deliverer (notifications.bus_address, or the session bus) and, for a notice sent away while the operator is away, the configured notifications.away_command. A value is written to its configured file or loopback URL, and an action runs its configured command. Each attempt is recorded unknown and committed before the outlet runs, so an interrupted attempt is never run twice; an outlet still running at outlet_timeout_ms may have acted and stays unknown.
  • Deliveries cite what fired. A delivery's parents are the rule's reading (or the forwarded report) and the readings each matched row was computed from when it was first seen: the reading itself, or every reading a group selected. Replaying one of those readings archives the delivery with the rest of the chain, like any derived reading.
  • A firing whose basis changed is withdrawn. When a cited reading is archived (by a replay or a lifecycle step) or the privacy policy changes between selecting a row and handing its firing off, the handoff is withdrawn: no delivery is recorded and no outlet runs, only an outcome not_sent with reason basis_changed. Its inputs were read under a policy or from readings that no longer hold, so it is never shown as valid under the current ones. The evaluator retracts the firing and the rules are read again: if the rule still finds the occurrence, it fires afresh under the same delivery identity, citing the readings selected now; a threshold, change or daily firing fires again only on a new crossing, change or day. The current build checks the cited readings against the lifecycle. Policy-change withdrawal belongs to the output-time privacy design and is not built.
  • Any producer may notify (decided target, not built). A credentialed producer writes an attributed note, optionally with a cited target, --notify and --interrupt. sinex note TEXT --notify --key K is the script form; a later note under that key replaces the notice, and withdrawing it clears the notice. The same evaluator and host deliverer apply grouping, quiet hours and the interrupt budget. A second notice.submitted intake kind is not introduced.
  • Own notifications are excluded (decided target, not built). A notification captured by Sinex's D-Bus source whose hints carry a product's delivery identifier is marked as a signal origin, and no rule reads it.
  • Decided target, not built: sinex status prints presence, quiet, the budget, held notices and the last 24 hours of interruptions.

Shipped rules

Condition Ships Inhibits (host scope)
the daemon stalled enabled, interrupting capture stalled, source unreadable, runaway volume, refusal-rate spike
Sinex blocked (admission cannot accept producer input) enabled, interrupting
a source unreadable enabled, interrupting
capture stalled (completeness) enabled, interrupting; critical only where captured data is being lost now
expiry race enabled; interrupting when the margin is below one poll period
a host out of contact past its deadline; spool runway under one day (hosts) enabled, interrupting
a kind whose every material is refused; refusal-rate spike enabled, interrupting
disk runway below 14 days enabled, passive (a warning in status)
disk runway below 3 days enabled, interrupting runaway volume
new input, parser arrival, stage finished, spool runway under the out-of-contact deadline, link rot on a saved item enabled, passive
the resume digest: operator activity returns after a gap and the resume pack is delivered as a notice disabled; passive when enabled

Everything else is passive. Tripwires and prospective memory are notes with triggers; none is enabled by shipping an example. An inhibiting rule folds the notices of the rules it names into its own notification while it is open. A late fact (older than the rule's fresh_within) is delivered passively. "Digest" is not a rule kind: the day pack and Today's Signals pane are the digest.

No rule starts or resumes an agent session (default; open operator question): there is no agent-starting delivery, and the deployment's action commands include none that start or resume an agent, because a run would spend quota with no one acting.

Elicitation

Self-report prompts are deliveries of rules with deliver: ask and an instrument (elicitation). The answer is a note with the delivery as parent and its latency; sinex delivery:ID note 4 and sinex note 3 --as mood answer from the CLI, and notification actions answer with one click. Nothing is asked until the operator decides which prompts may be sent (default; open operator question).

Stall alerts

  • The stall rule fires from the source's declared expectation (silent_after or every) and its recorded poll outcomes. It tells apart an unchanged successful poll, an event-driven source with no recent events, an unavailable input, a parser rejection, an excluded source, source lag, a host out of contact within its deadline, and a missed expected read. It never fires from low counts alone.
  • An alert carries its evidence, the last success, the affected interval and a concrete next action, and stays visible in status and the day pack until recovery clears it.

Follow

  • Decided target: sinex 'QUERY' read --follow (SSE over HTTP, CLI stream) is a signal without a delivery rule: the same standing evaluator delivered to the open connection, on_new by default; --after POSITION continues it and --until-idle bounds the CLI wait. The stream itself stores no new authored question.
  • The initial data notice follows initialization of the subscription's watch and commit cursor. A matching commit admitted after that notice is beyond the initial cursor position and is delivered once.
  • Event follows wait for the search read model's saved position, including queries without an explicit text predicate. Read-model lag delays delivery. An event whose text the search index refuses (a full-text vector over PostgreSQL's size limit) is recorded in core.search_refusals and passed; it never holds the position. Read-model completion wakes subscriptions, and each captured batch stays within its lower exclusive and upper inclusive commit positions across every page.
  • Each message carries its commit or stream position as the SSE id. A reconnect with Last-Event-ID receives everything after it, from the confirmed stream or PostgreSQL, including lifecycle changes (archive, restore, replay, tombstone) that affect matching rows. A position whose history is unavailable refuses with a named gap; it never silently starts now.
  • Messages report withheld payloads as withheld; keepalives are not capture evidence. Grouped, aggregate and ranked subscriptions use on_change semantics.
  • Programs that act on every committed fact subscribe to the confirmed stream as outside handlers.

Latency budgets

Budgets are p95, end to end through the real binary with a warm daemon. Each operation belongs to one class of the shared command-surface classes; Sinex's budgets per class:

Class Sinex operations Budget
local help, version, grammar completion, refusals of malformed input ≤ 15 ms
status status, the first screen of bare sinex, status --line ≤ 100 ms
completion each keystroke, daemon up or down ≤ 50 ms
read REF read, indexed lists ≤ 100 ms to the first screen
search bare-word queries, recall ≤ 250 ms to the first page
aggregate grouped and joined queries ≤ 400 ms by default; a timeout names a narrower query; --deadline none lifts it

Requests carry the shared deadline beside their command arguments. Omitting it uses the operation's class default; a nonnegative integer is milliseconds and JSON null lifts the budget. The CLI and standalone sinexd admin spelling is --deadline MS|none, before the query text. MCP advertises the same typed argument. Status/read defaults are 100 ms, completion 50 ms, search/recall 250 ms, and programmable queries, SQL and grouped/analysis reads 400 ms. Local commands have a 15 ms budget. These are execution defaults, not bounds on valid questions or page sizes.

The daemon resolves one read budget when it accepts a call. Pool acquisition and setup consume it. Each query snapshot sets transaction-local statement_timeout from the remaining budget; an explicitly lifted deadline clears a previous request's budget. SQL continuation pages receive the current call's budget. follow bounds each read, while its wait for a notification stays open. PostgreSQL's maximum statement timer does not impose an upper bound on a caller's millisecond deadline.

An expired read returns retryable timeout (CLI exit 7), releases its backend and suggests narrowing the question or lifting the deadline. Closing a caller also cancels its unowned read. Once a mutation holds a saved request, the writer or a preparation, its read timer ends and its terminal result is awaited; a lost HTTP reader does not revoke that accepted work. Deadline changes do not alter producer backup custody or its own readiness protocol. Daemon database connections name their own task in application_name, including writer, publisher and API.

Journey budgets on top:

  • the morning view (bare sinex, Today) renders in under 1 s;
  • resuming work takes at most two commands or interactions to reach evidence;
  • a prepared pack is read in ≤ 20 ms, a moment pack on request in ≤ 250 ms, a closed day in ≤ 100 ms, a week in ≤ 400 ms and a month in ≤ 1 s;
  • note commits in under 1 s;
  • the machine section answers within Polylogue's 100 ms deadline;
  • confirmed delivery to follow and outside handlers arrives under 5 s after a row is queryable;
  • a stall alert arrives within the source's silent_after or every plus one evaluator tick and measured delivery delay.

A miss is recorded with its measurement, never met by relaxing the number. Measurement is paired benchmark runs with hardware-independent figures (rows scanned, bytes encoded, memory per page); no test asserts elapsed time (benchmarks).