inbound-library/workplans/ILIB-WP-0002-library-infrastructure.md

id	type	title	domain	repo	status	flavor	owner	topic_slug	created	updated
ILIB-WP-0002	workplan	Establish the inbound-library infrastructure	infotech	inbound-library	active	implementation	claude	custodian	2026-10-05	2026-10-05

Establish the inbound-library infrastructure

Build the first working library, following INTENT.md:

• read-only IMAP intake;
• an append-only item store;
• file-backed topics, sources and subscriptions;
• notices through State Hub messages, a pull CLI and digest files;
• a systemd user timer on the workstation.

Python 3.11+ standard library only. The first consumer is intelligence-radar (IR-WP-0010).

Repository baseline and data contracts

id: ILIB-WP-0002-T01
status: todo
priority: high

Create the inbound_library package, python3 -m inbound_library with --help, a Makefile (check, test, demo, sync) and docs/data-contracts.md. The contracts define item, provenance, source, topic, subscription and notice, with schema versions. Record the install, test and run commands in AGENTS.md (taken over from ILIB-WP-0001-T02).

Acceptance: make check runs the unit tests on synthetic fixtures. The contracts document every field that a consumer may rely on.

Append-only item store

id: ILIB-WP-0002-T02
status: todo
priority: high

Store original bytes under data/items/<sha256>, with a provenance record for each delivery. Identical bytes delivered twice give one item with two deliveries. Derive plain text and metadata into separate, rebuildable records. Add an integrity check that rehashes every retained item. Never overwrite and never delete. Items without provenance go to quarantine.

Acceptance: the tests prove there is no overwrite, that deduplication works, that tampering is detected and that quarantine routing works.

Read-only IMAP intake

id: ILIB-WP-0002-T03
status: todo
priority: high

Poll one dedicated mailbox with imaplib, over TLS, using SELECT read-only and BODY.PEEK[]. Credentials come only from environment variable names set in the config. Keep a UIDVALIDITY/UID cursor in the library. Retain the full RFC 822 message as the item, and record each attachment as its own item linked to the message. Map the sender (and optionally a List-Id or subject pattern) to a registered source. Unknown senders are quarantined and not routed. Record DKIM/SPF authentication results as provenance, not as trust. Reuse the read-only IMAP approach of email-connect EMAIL-WP-0002 where that helps.

Acceptance: the tests run against a fixture mailbox. A live run is part of T07.

File-backed registries

id: ILIB-WP-0002-T04
status: todo
priority: high

Add registry/topics.json (a versioned vocabulary), registry/sources/*.json (owner repo, channel, match rules, topics, expected cadence, visibility: shared|restricted) and registry/subscriptions/<repo>.json (topics, sources, channels, cadence, agent name, digest path). A consumer registers a source from its own research with a commit. The commit is checked for unknown topics, duplicate match rules and restricted sources that leak to other repos.

Acceptance: check rejects invalid registries. A source registered by repo A is matched for repo B through a shared topic.

Matching and notification

id: ILIB-WP-0002-T05
status: todo
priority: high

Match new items to subscriptions by source and topic. Then deliver:

• a State Hub agent message (POST /messages/) per subscriber and run, listing the new item ids, sources and pull commands;
• a pull CLI: new --repo … --topic … --since …, show <item> and get <item>;
• a Markdown digest file per subscriber and cadence.

Record each notice in data/notices/, so a retry never notifies twice. If the hub is unreachable, keep the notice pending and retry on the next run.

Acceptance: the tests prove idempotent delivery and recovery when the hub is unreachable.

Scheduling, health and source silence

id: ILIB-WP-0002-T06
status: todo
priority: medium

Add a run-due that does the intake, then matching and delivery, under a lock. Add a systemd user service and timer in ops/systemd/, and a health command. Health reports:

• the last scan;
• items per source;
• sources that have stayed silent past their expected cadence;
• quarantine size;
• pending notices.

Acceptance: a silent source is reported, and repeated timer wakes are safe.

Provision the dedicated mailbox

id: ILIB-WP-0002-T07
status: todo
priority: high

Operator decisions:

• which mailbox (a new address, or a Gmail alias plus label or folder);
• how its IMAP credential is delivered (an app password through the secrets-engine path, never committed).

Then do a live read-only scan.

Acceptance: one real mail retained with provenance. No mailbox state changed.