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.**