From e1768c3f47081f11af38f5ee3115d00e094c8419 Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Mon, 24 Aug 2026 16:58:55 +0800 Subject: [PATCH 1/2] docs(collection): define GitHub saved-repository collection - add the Stars and Lists product claim and capability boundary - define canonical current-snapshot graph reconciliation - record real GitHub authority as the acceptance boundary --- 10-prd/behavior/capabilities.md | 5 ++++ 10-prd/behavior/claims.md | 9 ++++++ 10-prd/behavior/scope.md | 1 + 20-product-tdd/claim-realization-matrix.md | 1 + .../knowledge-capability-contract.md | 28 +++++++++++++++++++ 5 files changed, 44 insertions(+) diff --git a/10-prd/behavior/capabilities.md b/10-prd/behavior/capabilities.md index 58d0637..db53694 100644 --- a/10-prd/behavior/capabilities.md +++ b/10-prd/behavior/capabilities.md @@ -55,6 +55,11 @@ - 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: GitHub saved-repository collection + +- related claim(s): collect external information into reusable units; preserve GitHub Stars and Lists for later use +- non-goal: GitHub collection does not mirror repository activity, preserve removed memberships as current facts, or become a GitHub-specific browsing product + ## 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 d4f5fe7..3dd65ac 100644 --- a/10-prd/behavior/claims.md +++ b/10-prd/behavior/claims.md @@ -36,6 +36,15 @@ - 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 preserves GitHub Stars and Lists for later use + +- claim intent: a person's saved GitHub repositories and their List organization should become reusable info-base graph facts instead of remaining available only through GitHub's UI. +- evaluation dimensions: one configured access context discovers its authenticated account, preserves canonical account/repository/list identity, and reconciles current Star and List-membership relations without deleting collected entity blocks. +- evidence expectation: a real authenticated ordinary collection Job matches GitHub's complete visible Stars, Lists, and memberships; replay is idempotent and the resulting graph supports ordinary navigation and resolver projection. +- 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: GitHub realizes general graph collection; it does not add repository activity synchronization, a GitHub-only view, or uncertain content-based identity. + ## 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/scope.md b/10-prd/behavior/scope.md index 9cf86fd..cc2f4b0 100644 --- a/10-prd/behavior/scope.md +++ b/10-prd/behavior/scope.md @@ -6,6 +6,7 @@ - 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 +- GitHub Stars and Lists collection as reusable account, repository, list, ownership, and current-membership graph facts - 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 diff --git a/20-product-tdd/claim-realization-matrix.md b/20-product-tdd/claim-realization-matrix.md index 989fbad..14d3cc2 100644 --- a/20-product-tdd/claim-realization-matrix.md +++ b/20-product-tdd/claim-realization-matrix.md @@ -14,6 +14,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 | +| Preserve GitHub Stars and Lists for later use | GitHub extension maps one authenticated complete snapshot to canonical account, repository, list, ownership, Star, membership, and Source-provenance graph facts | `core-py` | Real GitHub GraphQL authority plus ordinary Job and PostgreSQL graph comparison proves complete visible sets, idempotent replay, graph navigation, and resolver projections; not repository activity synchronization or a GitHub-specific browser | | 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 and system-driven media interpretation are admitted organization approaches; Agents may add ordinary graph interpretations while preserving existing graph authority | `core-py`; `client-web` as an explicit rumination trigger and retrieval consumer | Real-provider Resolver/Agent/Tool/graph journeys, meaningful no-write boundary, and bounded independent media candidates; not a complete organization taxonomy, replacement, merge, or linking realization | | Expose information for retrieval and downstream use | Semantic retrieval ranks existing Blocks/Relations by meaning; lexical feature retrieval recalls existing Blocks from explainable textual clues; graph-navigation returns endpoint-closed neighborhoods and bounded shortest paths; hybrid composition remains independent | `core-py`; `client-web` and future Agent/application consumers | Pinned real multi-source/document/media topology corpus, real embedding and multimodal providers, local/delegated Peer journeys, and browser List/Graph navigation; not answer generation or Chat InKCre | diff --git a/20-product-tdd/knowledge-capability-contract.md b/20-product-tdd/knowledge-capability-contract.md index 61321c6..9ea0903 100644 --- a/20-product-tdd/knowledge-capability-contract.md +++ b/20-product-tdd/knowledge-capability-contract.md @@ -238,6 +238,34 @@ 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. +## GitHub Saved-Repository Reference Integration + +The GitHub extension is the reference integration for complete current-collection +reconciliation over shared graph entities: + +- One Source access context discovers its authenticated account from the remote authority. + The Source graph anchor collects that canonical account; configuration does not duplicate + account identity. +- Canonical account, repository, and list Blocks use GitHub's stable graph node identity. + Account kind distinguishes users and organizations without creating a second owner entity. +- Directed facts form `Source -> Account`, `Account -> Repository` Stars, + `Account -> List` ownership, `List -> Repository` membership, and + `Account -> Repository` ownership. Membership and ownership remain Relations rather than + copied root fields. +- Ordinary collection obtains a complete visible remote snapshot before applying graph + changes. Any remote protocol error or incomplete pagination rejects the snapshot instead + of turning missing data into deletion authority. +- Reconciliation updates canonical metadata and replaces only the current relation families + denied by the complete snapshot. Removed Stars, Lists, or memberships do not delete their + previously collected entity Blocks. +- Exact replay reuses canonical Blocks and Relations. Multiple Source access contexts for the + same account receive no independent observation layer in this slice; the last successfully + reconciled complete snapshot is the current observed relation set. + +GraphQL query shape, pagination and batching mechanics, resolver identities, relation strings, +configuration fields, and transaction sequencing remain implementation-owned by the GitHub +unit. + ## Mail Reference Integration The Mail extension is the reference integration for incremental communication collection, From 3296867c3d47f285686703a919c3adef0b3b3d43 Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Mon, 24 Aug 2026 22:31:22 +0800 Subject: [PATCH 2/2] docs(extension): restore durable ownership boundaries - keep concrete extension contracts with their owning Spokes - retain only generic product and cross-unit truth in the Hub - strengthen shared promotion guidance across independent owner axes --- 00-meta/skills/edit-svc-shared-docs/SKILL.md | 4 + 10-prd/behavior/capabilities.md | 15 --- 10-prd/behavior/claims.md | 29 +---- 10-prd/behavior/rules-and-invariants.md | 8 +- 10-prd/behavior/scope.md | 5 - 10-prd/behavior/workflows.md | 16 --- 20-product-tdd/claim-realization-matrix.md | 7 +- 20-product-tdd/cross-unit-contracts.md | 10 +- .../knowledge-capability-contract.md | 119 +----------------- 9 files changed, 17 insertions(+), 196 deletions(-) diff --git a/00-meta/skills/edit-svc-shared-docs/SKILL.md b/00-meta/skills/edit-svc-shared-docs/SKILL.md index f16ba8c..ffbd876 100644 --- a/00-meta/skills/edit-svc-shared-docs/SKILL.md +++ b/00-meta/skills/edit-svc-shared-docs/SKILL.md @@ -39,6 +39,10 @@ Apply this before editing any doc that may be mixed. 2. Reject shared promotion if the statement depends on one Spoke's local class names, method names, table names, or runtime sequencing unless those names are themselves the durable contract. 3. Reject shared promotion if the remaining local details would lose a readable home. 4. Prefer Spoke-local `AGENTS.md` and `docs/30-unit-tdd/` for implementation vocabulary, runtime hazards, and local mechanics. +5. Check delivery owner, durable owner, interface layer, and external capability owner independently. First-party distribution, + current delivery pressure, importance, or successful acceptance on one axis does not prove promotion on another. +6. Concrete Extension behavior stays with the owning Extension unless it proves a product-wide claim or cross-unit contract + that remains meaningful without naming that implementation. ## Workflow B: Update Hub Shared Docs diff --git a/10-prd/behavior/capabilities.md b/10-prd/behavior/capabilities.md index db53694..c93f32a 100644 --- a/10-prd/behavior/capabilities.md +++ b/10-prd/behavior/capabilities.md @@ -45,21 +45,6 @@ - related claim(s): accept memo-like capture through familiar clients - non-goal: a memo-compatible backend does not become a complete clone of the external product and does not include browsing or using the wider InKCre info-base -## Capability: Syndicated feed collection - -- 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: GitHub saved-repository collection - -- related claim(s): collect external information into reusable units; preserve GitHub Stars and Lists for later use -- non-goal: GitHub collection does not mirror repository activity, preserve removed memberships as current facts, or become a GitHub-specific browsing product - ## 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 3dd65ac..bd41ac2 100644 --- a/10-prd/behavior/claims.md +++ b/10-prd/behavior/claims.md @@ -18,33 +18,6 @@ - realization pointers: `../../20-product-tdd/system-state-and-authority.md`, `../../20-product-tdd/cross-unit-contracts.md` - impact on existing claims: organization optimizes reusable product memory; it does not own collection-time graph construction or retrieval indexes. -## Claim: InKCre reliably collects RSS and Atom feeds - -- 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 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 preserves GitHub Stars and Lists for later use - -- claim intent: a person's saved GitHub repositories and their List organization should become reusable info-base graph facts instead of remaining available only through GitHub's UI. -- evaluation dimensions: one configured access context discovers its authenticated account, preserves canonical account/repository/list identity, and reconciles current Star and List-membership relations without deleting collected entity blocks. -- evidence expectation: a real authenticated ordinary collection Job matches GitHub's complete visible Stars, Lists, and memberships; replay is idempotent and the resulting graph supports ordinary navigation and resolver projection. -- 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: GitHub realizes general graph collection; it does not add repository activity synchronization, a GitHub-only view, or uncertain content-based identity. - ## 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. @@ -58,7 +31,7 @@ - claim intent: a person, Agent, or downstream capability should be able to find existing information whose meaning is related to a natural-language query without first generating an answer. - evaluation dimensions: one bounded query returns globally ranked blocks and relations with score metadata; relation direction contributes to meaning; unavailable or stale derived support is excluded rather than repaired during the read. -- evidence expectation: a real provider embeds graph state collected through ordinary Memos, RSS, Atom, storage, resolver, and organization boundaries; judged primary entities enter the global top three and outrank explicit distractors. +- evidence expectation: a real provider embeds graph state from ordinary collection, storage, resolver, and organization boundaries; judged primary entities enter the global top three and outrank explicit distractors. - source rationale: `../_drivers/market-and-user-pressures.md`, `../_drivers/business-and-service-objectives.md` - realization pointers: `../../20-product-tdd/semantic-retrieval-and-peer-capabilities.md`, `../../20-product-tdd/claim-realization-matrix.md` - impact on existing claims: this realizes semantic retrieval only; feature retrieval, graph-navigation retrieval, answer generation, and Chat InKCre remain independent product capabilities even when another capability is also implemented. diff --git a/10-prd/behavior/rules-and-invariants.md b/10-prd/behavior/rules-and-invariants.md index 87d7b74..5a6d5b3 100644 --- a/10-prd/behavior/rules-and-invariants.md +++ b/10-prd/behavior/rules-and-invariants.md @@ -52,19 +52,19 @@ - rationale: stable native identity can justify reconciliation, while content fingerprints and time cutoffs provide weaker and less stable guarantees. - 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 +- linked claim(s): collect external information into reusable units ## 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 +- linked claim(s): collect external information into reusable units ## 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. +- rationale: derived or externally fetched content can improve use without becoming authority for what a source authored. - violation impact: enrichment failure would corrupt primary collection semantics and provenance would be lost. -- linked claim(s): reliably collect RSS and Atom feeds; expose info-base information for retrieval and downstream use +- linked claim(s): collect external information into reusable units; expose info-base information for retrieval and downstream use ## One deployment is one owner context diff --git a/10-prd/behavior/scope.md b/10-prd/behavior/scope.md index cc2f4b0..ed36316 100644 --- a/10-prd/behavior/scope.md +++ b/10-prd/behavior/scope.md @@ -4,9 +4,6 @@ - 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 -- GitHub Stars and Lists collection as reusable account, repository, list, ownership, and current-membership graph facts - 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 @@ -19,8 +16,6 @@ - wire transport internals and local interface details - 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 136565b..df60a9c 100644 --- a/10-prd/behavior/workflows.md +++ b/10-prd/behavior/workflows.md @@ -16,22 +16,6 @@ - exception flow: the operation exposes its own correctness and partial-effect boundary rather than being treated as a hidden part of collection - observable outcome: a testable graph or use-facing improvement exists on information that was already persisted -## Workflow: RSS And Atom Collection - -- 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/20-product-tdd/claim-realization-matrix.md b/20-product-tdd/claim-realization-matrix.md index 14d3cc2..62e3a2a 100644 --- a/20-product-tdd/claim-realization-matrix.md +++ b/20-product-tdd/claim-realization-matrix.md @@ -11,12 +11,7 @@ Map product claims to participating units and clarify each unit's technical resp | Product claim | Reference realization | Participating units | Evidence boundary | | --- | --- | --- | --- | -| 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 | -| Preserve GitHub Stars and Lists for later use | GitHub extension maps one authenticated complete snapshot to canonical account, repository, list, ownership, Star, membership, and Source-provenance graph facts | `core-py` | Real GitHub GraphQL authority plus ordinary Job and PostgreSQL graph comparison proves complete visible sets, idempotent replay, graph navigation, and resolver projections; not repository activity synchronization or a GitHub-specific browser | -| 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 and system-driven media interpretation are admitted organization approaches; Agents may add ordinary graph interpretations while preserving existing graph authority | `core-py`; `client-web` as an explicit rumination trigger and retrieval consumer | Real-provider Resolver/Agent/Tool/graph journeys, meaningful no-write boundary, and bounded independent media candidates; not a complete organization taxonomy, replacement, merge, or linking realization | | Expose information for retrieval and downstream use | Semantic retrieval ranks existing Blocks/Relations by meaning; lexical feature retrieval recalls existing Blocks from explainable textual clues; graph-navigation returns endpoint-closed neighborhoods and bounded shortest paths; hybrid composition remains independent | `core-py`; `client-web` and future Agent/application consumers | Pinned real multi-source/document/media topology corpus, real embedding and multimodal providers, local/delegated Peer journeys, and browser List/Graph navigation; not answer generation or Chat InKCre | | Retrieve semantically related info-base entities | Resolver/Relation projections feed profile-scoped derived embeddings; one domain facade executes locally or delegates the exact capability to an eligible Peer | `core-py`; `client-web` Peer consumer | Freshness/invalidation/maintenance checks, global Block/Relation ranking, real provider quality gate, exact-target and failover/outcome-unknown protocol cases | -| Recall blocks from lexical feature evidence | Block-local Resolver labels/text feed one derived record per Block; one facade ranks exact/substring/term evidence locally or through an eligible Peer | `core-py`; `client-web` Peer consumer and InfoBaseListView host | Exact identifiers, Chinese fragments, Mail metadata, PDF body, real image/audio/video faithful text, Agent interpretation, freshness/Jobs, delegated Peer, and built-browser navigation | +| Recall blocks from lexical feature evidence | Block-local Resolver labels/text feed one derived record per Block; one facade ranks exact/substring/term evidence locally or through an eligible Peer | `core-py`; `client-web` Peer consumer and InfoBaseListView host | Exact identifiers, Chinese fragments, source metadata, document bodies, real image/audio/video faithful text, Agent interpretation, freshness/Jobs, delegated Peer, and built-browser navigation | diff --git a/20-product-tdd/cross-unit-contracts.md b/20-product-tdd/cross-unit-contracts.md index cd3d0e2..4d2263e 100644 --- a/20-product-tdd/cross-unit-contracts.md +++ b/20-product-tdd/cross-unit-contracts.md @@ -27,15 +27,15 @@ Record durable data and behavior contracts that span more than one unit reposito ## Info-Base Ownership Contract -- Collection, organization, application, graph authority, resolver/storage composition, - extension protocol authentication, and the Memos reference integration are owned by the +- Collection, organization, application, graph authority, resolver/storage composition, and + extension protocol authentication are owned by the [Knowledge Capability Contract](knowledge-capability-contract.md). - 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. +- Generic one-shot Jobs and Crons, Source graph anchors, writable-Storage selection, + source graph/materialization patterns, 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 9ea0903..60c7599 100644 --- a/20-product-tdd/knowledge-capability-contract.md +++ b/20-product-tdd/knowledge-capability-contract.md @@ -50,8 +50,8 @@ storage(pointer) -> actual bytes ------------------+-> resolver -> solved/use-fa direct relations ---------------------------------+ ``` -- Blocks and relations are the shared persisted information authority. A Tweet, - repository, feed item, memo, or other source-native object is mapped into that graph; it +- Blocks and relations are the shared persisted information authority. A source-native object + is mapped into that graph; it does not gain a parallel durable object store merely because its native shape is useful. - When `block.storage` is absent, `block.content` is inline content. When storage is present, `block.content` is an opaque pointer whose grammar belongs to that storage handler. @@ -185,121 +185,6 @@ external API uses one of those words. the important loss; theoretical completeness alone does not justify a stronger identity or synchronization subsystem. -## Memos Reference Integration - -The Memos extension is the first reference implementation of memo-like capture: - -- The ownership unit is the memo-family extension. A Memos-compatible backend is one access - mode; future collectors or product adapters remain separate delivery scopes over the same - family meaning. -- Canonical memo root facts are persisted directly in root block content. Attachments, - parent/comment structure, and references exist only as component blocks and relations. -- Comments are independent memo roots connected to their parent. Each attachment is a - metadata block related to one semantic content block whose actual bytes are storage-backed. -- Backend reads consume resolver output and then map that solved value to the selected native - API version. Adapters do not read graph rows as an alternative semantic authority. -- A successful write guarantees its primary memo mutation was persisted. It does not promise - an atomic, residue-free graph; owned component cleanup may be best effort when the product - contract says so. -- The deployment-scoped compatibility profile and credential do not create User, tenant, or - per-row ownership tables. The local block ID is the memo's info-base identity. - -Memos protocol versions, client deviations, relation strings, storage identifiers, and -transaction sequencing remain implementation-owned by the responsible unit. - -## RSS And Atom Reference Integration - -The RSS extension is the first reference source that proves incremental feed collection and -optional semantic enrichment: - -- RSS 2.0 and Atom keep their protocol-authored feed, item, and enclosure facts in canonical - metadata/root blocks. Feed membership, enclosures, full text, and materialized content are - graph relations rather than copied root fields. -- Feed continuity prefers a source-scoped native feed identity, then a declared self URL, - then the configured URL. An unproven configured-URL change creates a new feed root and - retains historical graph state. -- Item reconciliation prefers the protocol-native ID and then the alternate link. When both - are absent, source policy chooses create or discard; no content fingerprint is treated as - identity. Create policy may use the previous successful contentful snapshot time as a - source-time admission watermark. -- Conditional request validators are scoped to the configured request URL; the unidentified - item watermark is scoped to the exact feed root. A `304` does not advance the contentful - snapshot watermark. -- Feed-authored content remains primary authority. Full-text extraction is a separate - semantic text enrichment, enabled by default, and use-time text may prefer it. Extraction - failure does not turn a valid primary item collection into failure. -- Enclosure metadata is always collectible. Automatic download is policy-controlled and - manual materialization remains available; materialized bytes become one exact semantic - content child or an explicit file fallback. -- Collection commits primary items independently and records structured job diagnostics. - Accepted partial effects and enrichment failures remain visible; source state advances only - after a successful contentful snapshot. - -Exact resolver identities, relation strings, source config fields, parser libraries, byte -limits, and transaction sequencing remain implementation-owned by the RSS unit. - -## GitHub Saved-Repository Reference Integration - -The GitHub extension is the reference integration for complete current-collection -reconciliation over shared graph entities: - -- One Source access context discovers its authenticated account from the remote authority. - The Source graph anchor collects that canonical account; configuration does not duplicate - account identity. -- Canonical account, repository, and list Blocks use GitHub's stable graph node identity. - Account kind distinguishes users and organizations without creating a second owner entity. -- Directed facts form `Source -> Account`, `Account -> Repository` Stars, - `Account -> List` ownership, `List -> Repository` membership, and - `Account -> Repository` ownership. Membership and ownership remain Relations rather than - copied root fields. -- Ordinary collection obtains a complete visible remote snapshot before applying graph - changes. Any remote protocol error or incomplete pagination rejects the snapshot instead - of turning missing data into deletion authority. -- Reconciliation updates canonical metadata and replaces only the current relation families - denied by the complete snapshot. Removed Stars, Lists, or memberships do not delete their - previously collected entity Blocks. -- Exact replay reuses canonical Blocks and Relations. Multiple Source access contexts for the - same account receive no independent observation layer in this slice; the last successfully - reconciled complete snapshot is the current observed relation set. - -GraphQL query shape, pagination and batching mechanics, resolver identities, relation strings, -configuration fields, and transaction sequencing remain implementation-owned by the GitHub -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