From 59cf14edfb43723d66ebfb1e38bc9c170b9aede1 Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Tue, 11 Aug 2026 08:06:55 +0800 Subject: [PATCH] docs(knowledge): define mail collection contracts - establish typed Job/Cron and Source/storage boundaries - define Mail graph, materialization, and InfoBase navigation contracts --- 10-prd/_drivers/operational-realities.md | 2 +- 10-prd/behavior/capabilities.md | 5 ++ 10-prd/behavior/claims.md | 13 ++- 10-prd/behavior/rules-and-invariants.md | 6 ++ 10-prd/behavior/scope.md | 2 + 10-prd/behavior/workflows.md | 12 ++- .../cross-domain-interactions.md | 2 +- 10-prd/glossary.md | 22 +++-- 20-product-tdd/claim-realization-matrix.md | 1 + 20-product-tdd/cross-unit-contracts.md | 3 + .../knowledge-capability-contract.md | 90 ++++++++++++++++--- ...emantic-retrieval-and-peer-capabilities.md | 3 +- 12 files changed, 138 insertions(+), 23 deletions(-) diff --git a/10-prd/_drivers/operational-realities.md b/10-prd/_drivers/operational-realities.md index 2560c44..a887d68 100644 --- a/10-prd/_drivers/operational-realities.md +++ b/10-prd/_drivers/operational-realities.md @@ -3,5 +3,5 @@ - runtime reality: multiple runtimes can operate around the same info-base. - runtime reality: a block may carry inline content or an opaque pointer to actual bytes stored elsewhere. - existing system limitation: storage-backed content access may be deferred, so consumers need one hydration contract rather than interpreting block pointers directly. -- runtime reality: collection may be a tracked pull run, an event-driven record, or an extension-owned protocol request; only run-oriented collection requires a collect-job lifecycle. +- runtime reality: collection may be a tracked pull run, an event-driven record, or an extension-owned protocol request; only run-oriented collection requires a Job lifecycle. - product boundary: an InKCre deployment is one owner context. Runtime clients are peer nodes, while users or accounts named by an external protocol remain protocol-bound projections rather than InKCre tenants. diff --git a/10-prd/behavior/capabilities.md b/10-prd/behavior/capabilities.md index 5dbc6c5..9f1884f 100644 --- a/10-prd/behavior/capabilities.md +++ b/10-prd/behavior/capabilities.md @@ -40,6 +40,11 @@ - related claim(s): collect external information into reusable units; reliably collect RSS and Atom feeds - non-goal: RSS/Atom collection does not include a feed-reader UI or make fetched full text and downloaded enclosures part of feed-authored authority +## Capability: Email communication collection + +- related claim(s): collect external information into reusable units; preserve email communication records for later use +- non-goal: email collection does not imply a mailbox mirror, a dedicated inbox UI, automatic attachment download, or the complete send/reply/agent action surface + ## Capability: Multi-runtime peer participation - related claim(s): organize information in one reusable info-base diff --git a/10-prd/behavior/claims.md b/10-prd/behavior/claims.md index 54ceea8..c5b5b42 100644 --- a/10-prd/behavior/claims.md +++ b/10-prd/behavior/claims.md @@ -4,7 +4,7 @@ - claim intent: source-specific information should become reusable product memory instead of remaining transient output or a parallel source-native object store. - evaluation dimensions: collection persists the information as blocks and relations, preserves source meaning needed for later use, and keeps source configuration separate from graph authority. -- evidence expectation: collection workflows persist a resolver-readable graph; run-oriented workflows also record collect-job lifecycle state without making that lifecycle part of the information itself. +- evidence expectation: collection workflows persist a resolver-readable graph; run-oriented workflows also record Job lifecycle state without making that lifecycle part of the information itself. - source rationale: `../_drivers/market-and-user-pressures.md`, `../_drivers/operational-realities.md` - realization pointers: `../../20-product-tdd/system-state-and-authority.md`, `../../20-product-tdd/cross-unit-contracts.md` - impact on existing claims: collection supplies information that organization and application may later act on, but the three capabilities are not mandatory lifecycle stages. @@ -22,11 +22,20 @@ - claim intent: a configured syndication source should preserve feed-authored information as reusable graph state while avoiding avoidable duplicate updates. - evaluation dimensions: RSS 2.0 and Atom sources use exact native identity when available, scope incremental state to its authority, keep full text separate from feed-authored content, and expose enclosure materialization as an explicit policy or command. -- evidence expectation: real RSS and Atom documents prove create, replay, update, conditional request, unidentified-item policy, partial failure, full-text enrichment, and semantic enclosure behavior through the ordinary collect-job path. +- evidence expectation: real RSS and Atom documents prove create, replay, update, conditional request, unidentified-item policy, partial failure, full-text enrichment, and semantic enclosure behavior through the ordinary collection Job path. - source rationale: `../_drivers/market-and-user-pressures.md`, `../_drivers/operational-realities.md` - realization pointers: `../../20-product-tdd/knowledge-capability-contract.md`, `../../20-product-tdd/claim-realization-matrix.md` - impact on existing claims: feed collection realizes the general collection claim; it does not add a feed-reader UI, make enrichment primary authority, or require fuzzy content identity. +## Claim: InKCre preserves email communication records for later use + +- claim intent: a person should be able to collect current and historical email communication at low cost without turning the info-base into an email-server mirror. +- evaluation dimensions: ordinary and backfill collection preserve useful message structure, participants, mailbox membership, flags, MIME metadata, and reply/reference evidence; remote bytes remain materializable on demand; source-owned remote actions are explicit and configurable. +- evidence expectation: a real IMAP server plus generic Job/Cron execution evidence prove ordinary and scheduled collection, bounded historical backfill, exact remote MIME materialization, and generic info-base viewing through the same persisted Mail graph. +- source rationale: `../_drivers/market-and-user-pressures.md`, `../_drivers/operational-realities.md` +- realization pointers: `../../20-product-tdd/knowledge-capability-contract.md`, `../../20-product-tdd/claim-realization-matrix.md` +- impact on existing claims: Mail realizes collection and use through one graph; it does not add a Mail-only inbox product, guarantee mailbox mirroring, or complete the future email client/agent vision. + ## Claim: InKCre exposes info-base information for retrieval and downstream use - claim intent: people and downstream capabilities should be able to find and navigate useful information in the info-base. diff --git a/10-prd/behavior/rules-and-invariants.md b/10-prd/behavior/rules-and-invariants.md index ea2e1b2..c082bf0 100644 --- a/10-prd/behavior/rules-and-invariants.md +++ b/10-prd/behavior/rules-and-invariants.md @@ -42,6 +42,12 @@ - violation impact: uncertain external information may overwrite the wrong graph state or a heuristic may be misrepresented as identity. - linked claim(s): collect external information into reusable units; reliably collect RSS and Atom feeds +## Collection preserves source meaning without becoming a remote mirror + +- rationale: a source may synchronize facts and explicit remote actions while the info-base remains reusable graph memory rather than a replica of the source system. +- violation impact: deletion, folder, flag, or byte-fetch behavior would either erase useful information without product intent or force every source into an expensive mirroring contract. +- linked claim(s): collect external information into reusable units; preserve email communication records for later use + ## Source-authored facts and semantic enrichment remain separate - rationale: fetched full text and downloaded enclosure bytes can improve use without becoming authority for what a feed authored. diff --git a/10-prd/behavior/scope.md b/10-prd/behavior/scope.md index ce2f61d..9cf86fd 100644 --- a/10-prd/behavior/scope.md +++ b/10-prd/behavior/scope.md @@ -5,6 +5,7 @@ - automatic or event-driven collection of information from external systems - low-friction memo-like capture through bounded compatible backends or collectors - RSS 2.0 and Atom collection with source-scoped incremental state, default full-text enrichment, and policy-controlled enclosure materialization +- IMAP email collection with ordinary incremental runs, bounded historical backfill, source-owned remote-state policy, on-demand MIME materialization, and generic info-base rendering - organization of information already in the info-base when it improves later use - feature, semantic, and graph-navigation retrieval, with indexing and embedding as application support - extension-based capability addition for source, resolver, storage, sink, or bounded protocol behavior @@ -18,6 +19,7 @@ - Spoke-local runtime operations and deployment procedures - multi-tenant or per-user ownership and access control inside one InKCre deployment - feed-reader UI, OPML management, or exhaustive compatibility with every malformed syndication document +- a Mail-only inbox/folder/message-list product or complete compose/send/reply email-agent behavior in the current Mail slice ## Open Question diff --git a/10-prd/behavior/workflows.md b/10-prd/behavior/workflows.md index aad4b28..de1504b 100644 --- a/10-prd/behavior/workflows.md +++ b/10-prd/behavior/workflows.md @@ -4,7 +4,7 @@ - actor: source capability, extension-provided source, or extension-owned collection protocol - trigger: a collection run starts, external data is received, or a compatible client submits information -- normal flow: source-native information is mapped to one block or a graph of blocks and relations, then persisted under info-base authority; a run-oriented source also records its collect-job lifecycle +- normal flow: source-native information is mapped to one block or a graph of blocks and relations, then persisted under info-base authority; a run-oriented source executes through one typed Job lifecycle - exception flow: a collection command may fail or leave explicitly accepted partial effects without turning execution status into an information state - observable outcome: new or updated reusable information units exist for later organization or application @@ -18,12 +18,20 @@ ## Workflow: RSS And Atom Collection -- actor: a configured RSS 2.0 or Atom source and the ordinary collect-job runner +- actor: a configured RSS 2.0 or Atom source and an eligible Job runner - trigger: a manual collection command or configured schedule creates a pending job - normal flow: the source conditionally fetches a bounded feed document, reconciles the feed and identifiable items by exact native evidence, persists enclosure metadata, then attempts configured full-text and enclosure enrichment without replacing feed-authored authority - exception flow: unidentified items follow explicit create/discard policy; primary item failures and enrichment failures remain visible in job diagnostics, and source state advances only after a successful contentful snapshot - observable outcome: resolver-readable feed/item/enclosure graph state exists, exact replays are idempotent, and optional semantic children remain distinguishable from primary source facts +## Workflow: Email Communication Collection + +- actor: a configured Mail source and any eligible Job-capable peer +- trigger: a person requests ordinary collection or bounded backfill, or a configured Cron creates an ordinary collection Job +- normal flow: the source reads protocol facts, reconciles exact occurrences and best-effort canonical messages, persists source/mailbox/message/participant/body/MIME/flag/reply graph facts, and advances only source-owned incremental checkpoints whose accepted effects are durable +- exception flow: one Job is one attempt and never retries itself; mailbox-local failure may leave accepted partial graph effects; missed Cron occurrences are not replayed; attachment bytes remain remote until explicitly materialized through their resolver +- observable outcome: collected communication can be discovered and rendered through generic info-base navigation, while later collection updates observed mailbox membership and flags without treating the info-base as a remote mirror + ## Workflow: Retrieval And Use - actor: application capability, sink, or downstream workflow diff --git a/10-prd/domain-structure/cross-domain-interactions.md b/10-prd/domain-structure/cross-domain-interactions.md index 6c29203..d5bd37f 100644 --- a/10-prd/domain-structure/cross-domain-interactions.md +++ b/10-prd/domain-structure/cross-domain-interactions.md @@ -3,7 +3,7 @@ ## Interaction Pair: Source -> Info-base - semantic contract: sources gather data, but the info-base owns persisted reusable graph state. -- shared language: source, collect job, block, relation, info-base. +- shared language: source, job, block, relation, info-base. ## Interaction Pair: Info-base -> Sink diff --git a/10-prd/glossary.md b/10-prd/glossary.md index 09361ff..27a02d3 100644 --- a/10-prd/glossary.md +++ b/10-prd/glossary.md @@ -60,17 +60,29 @@ - user-visible or business lifecycle language: normally hidden behind the product's clients and deployment. - notes on ambiguity with framework terms: peer equality describes shared authority and participation, not identical execution ability; one interaction may still have caller/provider or client/server roles. -## collect job +## job -- canonical business meaning: one execution lifecycle record for source collection. -- user-visible or business lifecycle language: the tracked run state of a collection execution. -- notes on ambiguity with framework terms: this is a product execution record, not a generic background-job abstraction. +- canonical business meaning: one typed, one-shot execution request and its lifecycle record. +- user-visible or business lifecycle language: a tracked run that a capable peer may claim and execute. +- notes on ambiguity with framework terms: a job records one attempt; it does not promise source completeness, retry itself, or become an information state. + +## cron + +- canonical business meaning: a recurring policy that creates a job for a due occurrence. +- user-visible or business lifecycle language: a schedule for starting future runs. +- notes on ambiguity with framework terms: cron creates commands but does not execute their business behavior; missed occurrences remain missed unless a person separately starts a run. ## collection - canonical business meaning: the action of persisting source-specific information into the info-base as one block or a graph of blocks and relations. - user-visible or business lifecycle language: bringing information into InKCre so it remains available for later action. -- notes on ambiguity with framework terms: collection is not a state carried by information, and not every collection access mode has a collect job. +- notes on ambiguity with framework terms: collection is not a state carried by information, and not every collection access mode has a Job. + +## backfill + +- canonical business meaning: an explicit collection intent over a caller-specified historical range. +- user-visible or business lifecycle language: bringing older source information into InKCre on demand. +- notes on ambiguity with framework terms: backfill is collection, not a separate capability or a synonym for an ordinary incremental run; its exact boundaries remain source-specific. ## organization diff --git a/20-product-tdd/claim-realization-matrix.md b/20-product-tdd/claim-realization-matrix.md index 889b0a1..5230b4f 100644 --- a/20-product-tdd/claim-realization-matrix.md +++ b/20-product-tdd/claim-realization-matrix.md @@ -13,6 +13,7 @@ Map product claims to participating units and clarify each unit's technical resp | --- | --- | --- | --- | | Collect external information into reusable units | Memos-compatible backend maps native requests to memo-family blocks, relations, resolver output, and storage-backed attachments | `core-py`; released MoeMemos client as acceptance actor | Bounded Memos 0.29.1-compatible API and MoeMemos Android 2.0.4 journey; not full Memos server or collector coverage | | Reliably collect RSS and Atom feeds | RSS extension maps bounded RSS 2.0/Atom snapshots to feed, item, enclosure, full-text, and semantic-content graph state | `core-py` | Real-protocol HTTP doubles, PostgreSQL graph acceptance, optional live endpoint smoke, exact replay/update/state/enrichment cases; not a feed-reader product | +| Preserve email communication records for later use | Mail extension maps protocol-neutral Mail facts to source, mailbox, canonical email, participant, body, MIME, flag, and reply/reference graph state; remote MIME bytes are materialized lazily | `core-py`; `client-web` as Job peer, info-base navigation host, and resolver consumer | Real Dovecot/IMAP plus PostgreSQL proves ordinary collection, bounded backfill, remote materialization, and built-browser rendering; not a Mail-only inbox or complete email agent | | Accept memo-like capture through familiar clients | Memos extension provides the first memo-family backend access mode | `core-py`; `client-web` for deployment-scoped extension configuration | Backend write/read, comments, attachments, hot credential replacement, hot enable/disable, and graph round-trip | | Organize information in one reusable info-base | Explicit focal-block rumination is the first admitted organization approach; an Agent may add an ordinary graph interpretation while preserving the focal graph | `core-py`; `client-web` as an explicit trigger surface | Real-provider Resolver/Agent/Tool/graph journey and meaningful no-write boundary; not a complete organization taxonomy, periodic organizer, replacement, merge, or linking realization | | Expose information for retrieval and downstream use | Semantic retrieval returns one bounded global ranking of existing Blocks/Relations and score metadata; feature and graph-navigation retrieval remain future | `core-py`; `client-web` and future Agent/application consumers | Pinned real Memos/RSS/Atom/HTML/storage corpus, real provider embedding and rumination, four top-three/distractor judgments, local and delegated Peer journeys; not answer generation or Chat InKCre | diff --git a/20-product-tdd/cross-unit-contracts.md b/20-product-tdd/cross-unit-contracts.md index 510ecab..8dbeae7 100644 --- a/20-product-tdd/cross-unit-contracts.md +++ b/20-product-tdd/cross-unit-contracts.md @@ -33,6 +33,9 @@ Record durable data and behavior contracts that span more than one unit reposito - Sources and extensions may propose graph data, but info-base owns persisted graph insertion. - Embedding generation may be triggered during ingestion, but embeddings remain derived application support rather than source-owned or info-base-owned authority. +- Generic one-shot Jobs and Crons, Source graph anchors and writable-Storage selection, the + Mail reference graph/materialization integration, and info-base navigation/solved-content + boundaries are owned by the same Knowledge Capability Contract. ## Semantic Retrieval And Peer Capability Contract diff --git a/20-product-tdd/knowledge-capability-contract.md b/20-product-tdd/knowledge-capability-contract.md index 3ff6068..23d35f9 100644 --- a/20-product-tdd/knowledge-capability-contract.md +++ b/20-product-tdd/knowledge-capability-contract.md @@ -127,14 +127,14 @@ external API uses one of those words. ```python class ProtocolExtension(ExtensionBase): - @classmethod - def api_dependencies(cls): - return [] - - @classmethod - def _register_apis(cls, root): - root.include_router(public_routes) - root.include_router(protocol_routes, dependencies=[protocol_auth]) + @classmethod + def api_dependencies(cls): + return [] + + @classmethod + def _register_apis(cls, root): + root.include_router(public_routes) + root.include_router(protocol_routes, dependencies=[protocol_auth]) ``` - This composition does not introduce a core terminal-user identity. External users or @@ -157,9 +157,25 @@ external API uses one of those words. URL or graph identity changes. - A source-time watermark may reduce duplicate admission when exact identity is unavailable, but it is not identity, reconciliation, or a correctness proof. -- When collection exposes collect jobs, manual and scheduled triggers create ordinary - pending jobs and use the same claim/runner path. A schedule is command-creation policy, not - a hidden second execution path. +- A Source may own one optional graph-anchor Block. The Source row remains authority for + operational configuration; the Block is a lazy, resolver-readable projection and Relation + endpoint for provenance. Sources do not retain a collected-item ledger when graph identity + can locate already collected facts; cursors and validators remain valid source state. +- A Source may select one writable Storage. The selected type must advertise writable + capability at the persisted boundary. Deployment-default writable Storage and the always + available PostgreSQL binary fallback complete source byte-placement policy without making + Storage infer source semantics. +- Manual and scheduled triggers create typed, one-shot pending Jobs and use the same + capability-handler, eligibility, atomic-claim, execution, and closure path. A Job has no + retry or business-specific completeness semantics; timeout is a per-attempt execution + budget, while partial progress and checkpointing remain owned by the invoked capability. +- A Cron is global command-creation policy, not a hidden execution path or a Source-owned + schedule. A due occurrence is materialized under database serialization with one + `scheduled_for` identity and at most one outstanding Job. Missed occurrences remain missed; + an immediate run is a separately created Job. +- Ordinary source collection and bounded historical backfill are different exact Job + capabilities. Backfill remains collection, accepts a source-specific range, and is not + prohibited from Cron merely because recurrence is normally low-value. - Complexity follows marginal utility: compare unresolved harm, mechanism coverage, dependency/obscurity, and maintenance cost. Stop after a weaker explicit mechanism removes the important loss; theoretical completeness alone does not justify a stronger identity or @@ -218,6 +234,58 @@ optional semantic enrichment: Exact resolver identities, relation strings, source config fields, parser libraries, byte limits, and transaction sequencing remain implementation-owned by the RSS unit. +## Mail Reference Integration + +The Mail extension is the reference integration for incremental communication collection, +source graph anchors, generic Jobs/Crons, and resolver-owned remote materialization: + +- One Mail Source selects one public protocol plus typed protocol parameters and common Mail + policy. A thin adapter factory creates a fresh async-context adapter per command. Adapters + expose protocol-neutral remote facts and part access; Source owns collection, graph + production, state advancement, and accepted partial effects. +- The provenance chain is `Source --manages--> Mailbox --contains--> Email`. Mailboxes remain + source-scoped observations. The membership Relation carries the exact remote locator needed + for later access. Canonical Email reconciliation uses a linear strongest-evidence-first + ladder; zero or ambiguous matches create rather than guess, nullable identity may be + completed, and contradictory non-null identity prevents reuse. +- An Email root contains only authored scalar facts. Participants are EmailAddress Blocks; + text and HTML bodies reuse exact semantic content resolvers; attachment and inline parts are + metadata Blocks. Roles, ordering, membership, flags, Content-ID/Location embedding, and + reply/reference structure remain Relations rather than copied root attributes. +- Collection records MIME metadata but does not download ordinary attachments. A MIME-part + Resolver first reuses any existing singular semantic `content` child; otherwise explicit + materialization fetches the exact remote part through the Mail adapter, writes bytes through + source-selected Storage policy, classifies them through the Mail-owned evidence ladder, and + adds one semantic content child. Benign concurrent duplicates do not make resolution fail; + ordinary use consumes one matching child and organization may later clean duplicates. +- The exact synchronous Peer capability is `extensions.mail.mime_part.materialize.v1`. + A browser peer may solve Mail graph state locally and delegate only this unavailable remote + operation to a capable peer. The provider inbound calls a non-delegating local path. +- The exact Mail Resolver identities are `extensions.mail.source.v1`, + `extensions.mail.mailbox.v1`, `extensions.mail.email.v1`, + `extensions.mail.email_address.v1`, and `extensions.mail.mime_part.v1`. + +Protocol commands, relation payload grammar, config fields, IMAP checkpoint wire shape, +mailbox traversal, and transaction batching remain implementation-owned by the Mail unit. + +## Info-Base Navigation And Solved Content + +- Hydrated content is the inline value or Storage-loaded bytes behind one Block. Solved + content is a Resolver-derived use projection that may combine hydrated content with local + graph facts and may lazily materialize missing semantic content under its contract. +- `InfoBaseRouter` is a client-supplied, deployment-singleton capability port over stable + Block/Relation-oriented destinations. It maps domain navigation to the client's existing + navigation authority; it does not maintain a second history or prescribe Graph as the only + possible default presentation. +- `InfoBaseView` is a navigation host that realizes those destinations. GraphSurface is the + first realizer; future list or other surfaces may realize the same domain routes. A route + destination outlet owns application-like popup composition and navigation semantics. +- Block inspection and solved-content rendering are separate destinations. A Resolver selects + a presentation-neutral solved-content renderer; the navigation host composes it inside the + destination container. Destination-owned popups may own their shell because they participate + in route/history behavior, while reusable renderer content remains independent of popup, + drawer, card, or page presentation. + ## Compatibility And Evolution - A source product/API version and a canonical or resolver contract version are independent diff --git a/20-product-tdd/semantic-retrieval-and-peer-capabilities.md b/20-product-tdd/semantic-retrieval-and-peer-capabilities.md index 7637a9f..f975b99 100644 --- a/20-product-tdd/semantic-retrieval-and-peer-capabilities.md +++ b/20-product-tdd/semantic-retrieval-and-peer-capabilities.md @@ -138,7 +138,8 @@ The first admitted exact capability IDs are: - `core.semantic_retrieval.v1`; - `core.organization.rumination.v1`; -- `core.extension.management.v1`. +- `core.extension.management.v1`; +- `extensions.mail.mime_part.materialize.v1`. ## Runtime Authentication And Advertisement