inbound-library/INTENT.md

INTENT — inbound-library

Status: Draft baseline 0.1 Date: 2026-10-05

1. Intent

inbound-library collects material that may matter to the ecosystem. Consuming repositories can find it, review it, and decide what it means for them.

It answers three questions:

• What has arrived? Mail and registered sources, kept with their original bytes and their provenance.
• Who should look at it? Material is matched to the topics that repositories have registered.
• How do they get it? Notification, then access when the consumer chooses.

The library keeps and routes material. It does not judge whether material is true, relevant or good. That review belongs to the consuming repository.

2. First use case

The daily and weekly intelligence briefs that Grok and ChatGPT automations deliver by email. They are consumed by intelligence-radar.

intelligence-radar used to receive them only through a drop folder. Pulling them from the signed-in websites was rejected: it would break the providers' terms of service. Email is a delivery the providers offer, so collecting it is legitimate.

3. Vocabulary

Item

One piece of retained material, for example an email, an attachment or a captured document. It has:

• its original bytes, content-addressed by SHA-256;
• a provenance record: channel, sender, received-at, Message-ID or URL, and source;
• derived text and metadata, which never replace the original bytes.

Source

A registered origin of items, for example a sender address, a feed or a URL. A source has an owner (the repository that registered it), topics, and an expected cadence. A consuming repository may register sources from its own research. The library then makes those sources available to every repository whose topics match.

Topic

A shared name for an area of interest, such as intelligence.daily-brief. Topics form a small, versioned vocabulary. They are not free tags per item.

Subscription

A repository's registered interest. It has:

• topics, and optionally sources;
• delivery channels;
• cadence;
• the agent name that receives notices.

Notice

A pointer sent to a subscriber: "these items arrived for your topics". A notice refers to items. It does not copy them.

4. Principles

L1 — Original bytes are kept. Items are append-only and content-addressed. Derived text, parsing and classification can be redone. The original cannot.

L2 — Provenance is part of the item. An item without a known channel and sender or origin is quarantined. It is not routed.

L3 — Only material that was delivered or published. Items come from mail sent to the library's mailbox, or from sources published for access. No account sessions are used, no scraping happens behind sign-ins, and no provider's terms of service are worked around.

L4 — Read-only toward the mailbox. The mailbox is read without changing it. The scan cursor lives in the library, not in mail flags.

L5 — The library routes. It does not judge. Every item enters as unreviewed. Relevance and credibility are decided by the consumers, and their review outcomes may be recorded back as annotations.

L6 — Notices are pointers and idempotent. A subscriber is told about an item once per subscription. Retries never create duplicate notices.

L7 — Registries are files. Topics, sources and subscriptions live as versioned files in this repository. Consumers change them with a commit. The State Hub is a read model and receives notices only as messages.

L8 — Shared by default, restricted when declared. Sources registered by one repository are visible to every repository with matching topics. The exception is a source the registering repository marks restricted.

L9 — Standard library first. Python 3.11+ standard library. It runs on the workstation under a systemd user timer and moves to the cluster once the contracts are stable.

5. Service contract

Intake

• an IMAP mailbox, polled read-only;
• registered sources;
• items submitted by a consumer through the CLI.

Delivery to subscribers

• State Hub agent messages: one notice per subscriber per run that has new matches.
• Pull CLI/API: new --topic … --since …, show <item> and get <item> (original bytes).
• Periodic digest file: a Markdown digest for each subscriber and cadence.

Operation

• a health report: last scan, items per source, sources that missed their expected cadence, and quarantine size;
• an integrity check over every retained item.

6. Success criteria

inbound-library succeeds when:

• a brief emailed by Grok or ChatGPT reaches intelligence-radar within one timer interval, without an operator;
• every item can be traced back to its original bytes and delivery;
• a source registered by one repository is found by another repository through topics;
• a missed delivery (a source that stays silent past its cadence) is visible rather than silent;
• adding a consumer is a commit, not a code change.

7. Non-goals

inbound-library is not:

• a mail client, or a sender of mail other than notices;
• a scraper of signed-in websites;
• an editorial or fact-checking system;
• a news-content farm;
• a replacement for a consumer's own evidence store. Consumers retain what they decide to use.

8. One-line description

inbound-library keeps material delivered to the ecosystem and routes it, by topic, to the repositories that asked to see it.