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.
- One question, one answer, every surface. One parsed question, one resolved read
context and one server-side answer serve the CLI, MCP, HTTP,
followand 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.
- One typed operation table declares every command once. The CLI parser, the socket
and HTTP routes, the MCP tools (with
outputSchemagenerated 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.
sinexdserves a Unix socket and an HTTP listener carrying one typed request protocol:POST /v1with a tagged request,GET /v1/commandsfor the table's metadata, SSE forfollow. 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).
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;resultnames what moved andresume OPERATIONcontinues 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_foundno the read pool has no free connection in time timeoutyes read_pool_busypool closed, connection lost, TLS, server shutting down ( 08…,57P…)not_runningyes database_unavailableunique violation ( 23505)conflictno the constraint foreign key, not null, check ( 23503,23502,23514)bad_valueno the constraint statement timeout ( 57014)timeoutyes statement_timeoutserialization failure, deadlock ( 40001,40P01)conflictyes the SQLSTATE insufficient privilege ( 42501): the reader role may not do itrefusedno the SQLSTATE a connection URL this build cannot use bad_valueno any other internalno 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 onerefused, a slow onetimeout; a sealed blob read without its key isrefused; damaged bytes and any other disk error areio. -
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 arefusedfailure. -
sinexctlexits 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 isnot_configured, an endpoint or argument it cannot usebad_request, a daemon it cannot reachnot_running(daemon_unreachable), and an answer it cannot decodenot_running(daemon_protocol_mismatch: the daemon was built from other sources). Failed offline diagnostics areio. With--jsona 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.sinexdexits 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.tokenandoperator.token, whichsinexdwrites in its token directory, and--token-fileselects one explicitly. A missing writer namessinexd run; a replay requiring the operator's key namessinexctl 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.
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.
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) |
- Every write records
written_by:author(operator,agent:<session>,agent:<origin>,script:<unit>,unattributed) andvia(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;
operatoronly 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 = Slists everything one agent session wrote.
- 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.
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.
- 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 targetsinex help --allprints it for other installations. (ruling 2026-10-18, cc:ee52794c-8a9e-43b6-9fbc-9749c7e78e8f:12f1a067-cc5b-41b7-9209-297099d6b0c1). - The MCP
instructionsfield 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).
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.
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 hereThe 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.
| 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 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.
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.
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 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 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.
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.
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 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.
sourcesis the one source status relation andsources NAMEthe one detail view. Gaps, inputs and payload shapes are the query tablesgaps,inputsandshapes(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_afterand the remaining margin,coverage,behind,rate,refused_rate,shape_changed,days_with_data_30d,gaps_30dandlast_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 NAMEgives 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.
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).
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).
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;
valuetargets (a file or a loopback URL) andactioncommands, 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.
- Declared, never inferred. A rule is an authored record written by the operator or
an agent through a saved query with
--watchornote --as watchand 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) andsignal.outcome(what happened to a delivery afterwards: an outlet's attempt, shown, cleared, closed), plussignal.reportfor 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, andsinex 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 30dreplays 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
sinexdwith the triggering citation as its last argument, and its result returns as events.
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 configurednotifications.away_command. A value is written to its configured file or loopback URL, and an action runs its configured command. Each attempt is recordedunknownand committed before the outlet runs, so an interrupted attempt is never run twice; an outlet still running atoutlet_timeout_msmay 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_sentwith reasonbasis_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,
--notifyand--interrupt.sinex note TEXT --notify --key Kis 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 secondnotice.submittedintake 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 statusprints presence, quiet, the budget, held notices and the last 24 hours of interruptions.
| 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.
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).
- The stall rule fires from the source's declared expectation (
silent_afterorevery) 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.
- 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_newby default;--after POSITIONcontinues it and--until-idlebounds 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_refusalsand 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 withLast-Event-IDreceives 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_changesemantics. - Programs that act on every committed fact subscribe to the confirmed stream as outside handlers.
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;
notecommits in under 1 s;- the machine section answers within Polylogue's 100 ms deadline;
- confirmed delivery to
followand outside handlers arrives under 5 s after a row is queryable; - a stall alert arrives within the source's
silent_afteroreveryplus 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).