learning-window

Learning window state

This optional workflow component owns learning collection checkpoints, not a resident gateway event cursor, task inbox, or transport lifecycle. It starts no resident daemon. Network reads delegate adapter-supplied capabilities and the existing cloud auth/HTTP owner. Core services do not depend on it.

The dispatcher supplies current joined membership for every configured scope. scripts/window_state.py:plan_windows returns each scope's earliest unread timestamp, including the immutable bootstrap timestamp for a newly joined room or newly configured scope. Never initialize a new room from another room's or scope's current timestamp.

After a trusted bounded collector returns a scope-qualified receipt, the dispatcher calls record_collection with the dedicated private state directory. The writer locks and validates state, atomically persists the complete receipt, then records collection progress only for rooms with covered available history. Failures and exhausted page budgets leave unread rooms at their prior position. The receipt's overall success flag cannot override a failed room. The persisted receipt contains unlearned events and must survive until its consumer commits them to a durable facts store.

Collection is not learning. This writer never advances a learned-facts cursor or claims dossiers changed. A recency-only update does not consume facts. Consumer acknowledgment and receipt retention need their own tested contract before unattended operation; never prune unlearned receipts to make a size gate pass.

scripts/collection_pass.py:collect_pass accepts an explicit configured scope list and injected membership/collector capabilities. It validates exact membership and window binding, persists partial receipts, and admits a consumer only when every configured scope has covered available history. It does not invoke a consumer or acknowledge facts. The optional dispatcher delegates to this contract. Direct model-authored receipt files are not trusted collector evidence. Same-user filesystem access can bypass any optional writer; do not claim this is all-provider authorization or mandatory protection of a legacy cursor.

command_collection.py:collect_commands invokes adapter-injected argument vectors for each configured hostname scope with strict rooms and bounded history commands. Credential/environment resolution belongs to those adapters. Partial strict failures are persisted with unread coverage; command timeouts and scope mismatches prevent consumer admission. No network command was exercised by its offline tests; adapter deployment and scheduled live runs need separate evidence. Scope exceptions retain their type and a fixed error_stages label for membership read/validation, history read, window order/validation or receipt persistence. Labels contain no exception text, command output or credentials; a history-read label alone does not distinguish network failure from command-output validation.

launch.sh manifest directory log detaches dispatch_collection.py with explicit manifest config, a dedicated private collection state directory and a caller resolved log path. It delegates interpreter selection to the repository Python resolver. A launch receipt means dispatcher requested, not consumer completion. The locked dispatcher performs collection before invoking the configured consumer argument vector and supplies every retained digest-verified bundle. No fact acknowledgment or receipt deletion is implemented; consumer exit stays unverified. Scope keys must match the canonical collector gateway hostname, not a Matrix homeserver alias. Private dispatcher wiring belongs to the caller's adapter.

Consumers run in their own process group. Before final readback and lock release, the dispatcher kills remaining group members and reaps its direct child, including on timeout, normal exit, and SIGTERM/SIGINT cancellation. A child deliberately escaping the group is outside this guarantee; this is not a sandbox.