Check one saved SQLite condition and hand attention to a local inbox

This local tutorial collects a disposable SQLite observation, evaluates one saved check, preserves a maintenance annotation, retains an attention decision, and writes one operator-inbox file. It is for understanding the handoffs—not for deploying an application.

What this does

disposable SQLite queue
  → Monitor collects an observation
  → NQ evaluates one installed saved check and projects maintenance separately
  → Nightshift retains one attention receipt for that exact evaluation
  → NQ replays the receipt, retains delivery custody, and writes one local file
  → you inspect the retained records

The owners remain distinct. Monitor owns acquisition. NQ owns the saved-check result, the local read record, maintenance declaration, and notification custody. Nightshift owns the attention decision and its replayable receipt. The local inbox holds a delivery artifact; it does not prove a human saw it.

Requirements and exact public revisions

Use Linux x86-64, Git, a C compiler/linker, rustup with the installed Rust/Cargo 1.94.0 toolchain, Python 3.12, and Python's standard SQLite module. Check cargo +1.94.0 --version, rustc +1.94.0 --version, and python3 --version first. The local producer also uses /usr/bin/python3; that interpreter needs the standard SQLite module. Build debug binaries for this same-account local exercise. No credential, provider key, network webhook, daemon, or container is needed. Production identity isolation is not established by this debug tutorial.

Verify both interpreter paths and SQLite before creating the demo. Both should report Python 3.12 and successfully import SQLite:

python3 -c 'import sqlite3, sys; print(sys.version); print(sqlite3.sqlite_version)'
/usr/bin/python3 -c 'import sqlite3, sys; print(sys.version); print(sqlite3.sqlite_version)'

The required source revisions are Constellation NQ e259852ed58b8c0bf65a629b3c494afba28d9ce9 and Constellation Nightshift 019e6837565ebf5b0ac244cbd7c3edde28e25aea. The Nightshift source cut contains the matching Monitor integration source used below.

DEMO_PARENT=$(mktemp -d /tmp/saved-check-attention-setup.XXXXXX)
cd "$DEMO_PARENT"
git clone https://github.com/unpingable/constellation-nq.git nq
git -C nq checkout --detach e259852ed58b8c0bf65a629b3c494afba28d9ce9
git clone https://github.com/unpingable/constellation-nightshift.git nightshift
git -C nightshift checkout --detach 019e6837565ebf5b0ac244cbd7c3edde28e25aea

export CARGO_BUILD_JOBS=2 CARGO_INCREMENTAL=0 CARGO_PROFILE_DEV_DEBUG=0
CARGO_TARGET_DIR="$DEMO_PARENT/nq-target" cargo +1.94.0 build --locked --manifest-path nq/Cargo.toml -p nq-app --bin nq
CARGO_TARGET_DIR="$DEMO_PARENT/nightshift-target" cargo +1.94.0 build --locked --manifest-path nightshift/runtime/Cargo.toml -p nightshiftd --bin nightshift
CARGO_TARGET_DIR="$DEMO_PARENT/monitor-target" cargo +1.94.0 build --locked --manifest-path nightshift/integrations/monitor-predicate-support/Cargo.toml --bin monitor-concerns

This named profile needs NQ, the Nightshift runtime, and monitor-concerns. It does not build Pulse. That omission is specific to this saved-check/local-inbox path: it does not make Pulse a universally optional component or establish a plugin, replacement, or drop-in compatibility profile.

Run the disposable example

The root must be an absent absolute directory whose name begins nightshift-saved-check-run-. The script is create-only: choose a new root for a new occurrence rather than running it again over uncertain records.

python3 nightshift/runtime/examples/saved-check-recurring.py \
  --attention-inbox \
  --nightshift "$DEMO_PARENT/nightshift-target/debug/nightshift" \
  --monitor "$DEMO_PARENT/monitor-target/debug/monitor-concerns" \
  --nq "$DEMO_PARENT/nq-target/debug/nq" \
  --project-example "$DEMO_PARENT/nightshift/integrations/monitor-predicate-support/examples/local-queue-attention.py" \
  --root "$DEMO_PARENT/nightshift-saved-check-run-demo"

Expect a final "result": "qualified" record and an attention entry showing a local-file delivery accepted with human receipt not established. That does not mean the check succeeded: this example intentionally keeps a nonempty queue, so its saved-check outcome is failed while maintenance remains a separate annotation.

Read each record for what it says

Record	What it establishes	What it does not establish
Source observation time	When Monitor observed the disposable queue.	When Nightshift made an attention decision or whether another source is current.
NQ local read attempt	That NQ made the retained SQLite read for this saved-check evaluation.	General application health or an ongoing scheduler installation.
Maintenance declaration	Whether the condition was covered, overrun, uncovered, or unavailable at its stated coordinate.	A changed check result; a covered failure remains failed.
Attention decision time	When Nightshift evaluated its bounded attention policy over that retained material.	Fresh source evidence or authority to execute work.
Notification delivery	That NQ retained one local-file delivery result.	Human receipt, acknowledgment, resolution, or task success.

The attention receipt binds an exact policy and evaluation. NQ replays that receipt through the configured Nightshift executable before delivery custody. The example's duplicate submission returns the same delivery identity and does not create another file; an altered-receipt negative control refuses before a file is created.

Limits and recovery

The canonical delivery intent is limited to 32 KiB. The attention policy permits an event window of at most 300 seconds. While its foreground Python supervisor is running, each example command has a 30-second limit and 1 MiB output limit; it has no automatic retry. Keep this tutorial attended. Those limits and its after-command transcript do not establish survival of supervisor loss. If the supervisor disappears, the in-flight command and its result may be indeterminate. Reconcile existing processes and owner state before considering anything new. Component qualification covers selected uncertain-delivery behavior; this tutorial does not claim a full injected response-loss or interrupted-delivery journey.

Keep the disposable root after the command. A successful run contains the NQ database, Nightshift store, attention policy and bundle, configuration files, inbox, and commands.jsonl; an interrupted run may contain only a prefix of those files. The final JSON's attention.receipt_digest identifies Nightshift's decision; attention.notification_id identifies NQ's delivery custody. Neither identifies a human acknowledgment. Inspect an existing delivery with the retained root's notification configuration and notification ID:

"$DEMO_PARENT/nq-target/debug/nq" --config "$DEMO_PARENT/nightshift-saved-check-run-demo/notification.toml" --json \
  notification inspect --notification-id YOUR_RETAINED_NOTIFICATION_ID

If final output was lost, list this disposable store's retained delivery records without supplying an ID. This is read-only inspection, not another submission:

DEMO_ROOT="$DEMO_PARENT/nightshift-saved-check-run-demo"
"$DEMO_PARENT/nq-target/debug/nq" --config "$DEMO_ROOT/notification.toml" --json notification inspect

If notification.toml is absent but nq.toml exists, use that original configuration for the same read-only inspection: both select the same NQ database. Do not create missing configuration or a new store to make inspection succeed. An unavailable result, missing final ID, or incomplete transcript does not establish that no delivery occurred.

For a completed command, commands.jsonl retains its label, arguments, exit code and stdout. The nightshift-run and nightshift-next-slot stdout objects contain evaluation_id. If attention was reached, attention-bundle.json also contains receipt.evaluation_id. Select the exact retained ID; do not substitute the newest timestamp:

EVALUATION_ID=YOUR_EXACT_RETAINED_EVALUATION_ID
"$DEMO_PARENT/nightshift-target/debug/nightshift" --store "$DEMO_ROOT/nightshift.sqlite" \
  saved-check inspect --evaluation-id "$EVALUATION_ID"
# Only when the retained attention policy exists:
"$DEMO_PARENT/nightshift-target/debug/nightshift" --store "$DEMO_ROOT/nightshift.sqlite" \
  saved-check attention-status --policy "$DEMO_ROOT/attention-policy.json" \
  --evaluation-id "$EVALUATION_ID"

A partially written transcript line or an in-flight command with no retained ID remains unresolved; preserve it for operator investigation instead of inventing an ID or rerunning the generator. Stopping a command does not settle an uncertain delivery. Do not invent a new event identity or repeat an uncertain local-file write. Before copying this disposable state, establish quiescent commands and keep SQLite sidecars with their database. Backup quiescence is the only documented precaution here; restoration, migration, rollback, and a durable recurring installation have not been verified.

For external callers

Running the provided tutorial is not an SDK. An adapting caller must supply the exact project enrollment, actual source and saved-check definition, explicit maintenance material where applicable, the selected attention policy, and the configured replay enrollment. It must preserve the separate records above and inspect an existing attempt before considering another submission. This example is a concrete composition boundary, not a general agent-orchestration framework.

This path does not deploy an application, establish a general recurring-monitoring migration, make a family-wide alpha maturity claim, or supply AG/Docket permission or execution custody. It produces no governed external effect.

When something breaks

Use the troubleshooting guide to report the two source revisions, tool versions, command, retained notification/evaluation identifiers, and a minimal redacted diagnostic excerpt. Do not attach credentials, prompts, entire databases, or unrelated retained records. Support is experimental and best effort; while waiting, preserve and inspect the existing custody rather than repeating work blindly.