diff --git a/20-product-tdd/claim-realization-matrix.md b/20-product-tdd/claim-realization-matrix.md index 442c89f..989fbad 100644 --- a/20-product-tdd/claim-realization-matrix.md +++ b/20-product-tdd/claim-realization-matrix.md @@ -16,6 +16,6 @@ Map product claims to participating units and clarify each unit's technical resp | 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 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 and hybrid composition remain independent | `core-py`; `client-web` and future Agent/application consumers | Pinned real multi-source/document/media corpus, real embedding and multimodal providers, local/delegated Peer journeys, and browser List navigation; not answer generation or Chat InKCre | +| 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 | diff --git a/20-product-tdd/cross-unit-contracts.md b/20-product-tdd/cross-unit-contracts.md index 655a168..cd3d0e2 100644 --- a/20-product-tdd/cross-unit-contracts.md +++ b/20-product-tdd/cross-unit-contracts.md @@ -56,3 +56,11 @@ Record durable data and behavior contracts that span more than one unit reposito - Resolver materialization and Organization may add graph facts，but the lexical retrieval owner alone maintains lexical records。Exact synchronous retrieval uses the generic Peer protocol without giving PeerManager the query or result meaning。 + +## Graph Navigation Retrieval Contract + +- Endpoint-closed graph read models，bounded Block/Relation neighborhoods，shortest-path + outcomes，random focal selection and presentation separation are owned by the + [Graph Navigation Retrieval Contract](graph-navigation-retrieval.md). +- Peer implementations may query shared graph authority directly. InfoBase views realize + navigation and presentation without becoming the owner of retrieval semantics. diff --git a/20-product-tdd/graph-navigation-retrieval.corpus.json b/20-product-tdd/graph-navigation-retrieval.corpus.json new file mode 100644 index 0000000..c07b6c5 --- /dev/null +++ b/20-product-tdd/graph-navigation-retrieval.corpus.json @@ -0,0 +1,103 @@ +{ + "contract": "core.graph_navigation_retrieval.v1", + "topology": { + "blocks": [ + "alpha", + "beta", + "gamma", + "delta", + "epsilon", + "isolated" + ], + "relations": [ + {"alias": "alpha_beta", "from": "alpha", "to": "beta", "content": "links"}, + {"alias": "beta_gamma", "from": "beta", "to": "gamma", "content": "quotes"}, + {"alias": "gamma_alpha", "from": "gamma", "to": "alpha", "content": "supports"}, + {"alias": "beta_delta", "from": "beta", "to": "delta", "content": "links"}, + {"alias": "alpha_epsilon", "from": "alpha", "to": "epsilon", "content": "mentions"}, + {"alias": "epsilon_delta", "from": "epsilon", "to": "delta", "content": "links"} + ] + }, + "scenarios": [ + { + "name": "outgoing_block_neighborhood", + "operation": "block_neighborhood", + "input": {"focal": "alpha", "direction": "out", "limit": 20}, + "assert": { + "status": "found", + "focal": "alpha", + "relation_set": ["alpha_beta", "alpha_epsilon"], + "endpoint_closed": true + } + }, + { + "name": "incoming_exact_content_neighborhood", + "operation": "block_neighborhood", + "input": {"focal": "delta", "direction": "in", "contents": ["links"], "limit": 20}, + "assert": { + "status": "found", + "focal": "delta", + "relation_set": ["beta_delta", "epsilon_delta"], + "endpoint_closed": true + } + }, + { + "name": "isolated_block_is_success", + "operation": "block_neighborhood", + "input": {"focal": "isolated", "direction": "both", "limit": 20}, + "assert": {"status": "found", "block_set": ["isolated"], "relation_set": []} + }, + { + "name": "missing_block", + "operation": "block_neighborhood", + "input": {"focal": "missing", "direction": "both", "limit": 20}, + "assert": {"status": "missing"} + }, + { + "name": "relation_neighborhood", + "operation": "relation_neighborhood", + "input": {"focal": "beta_gamma"}, + "assert": { + "status": "found", + "block_set": ["beta", "gamma"], + "relation_set": ["beta_gamma"], + "endpoint_closed": true + } + }, + { + "name": "unique_directed_shortest_path", + "operation": "find_path", + "input": {"from": "alpha", "to": "gamma", "direction": "out", "max_hops": 4, "max_explored_blocks": 1000}, + "assert": { + "status": "found", + "block_path": ["alpha", "beta", "gamma"], + "relation_path": ["alpha_beta", "beta_gamma"], + "endpoint_closed": true + } + }, + { + "name": "equal_shortest_path_has_no_tie_break_authority", + "operation": "find_path", + "input": {"from": "alpha", "to": "delta", "direction": "out", "contents": ["links", "mentions"], "max_hops": 4, "max_explored_blocks": 1000}, + "assert": {"status": "found", "hop_count": 2, "endpoint_closed": true} + }, + { + "name": "zero_hop_path", + "operation": "find_path", + "input": {"from": "beta", "to": "beta", "direction": "both", "max_hops": 4, "max_explored_blocks": 1000}, + "assert": {"status": "found", "block_path": ["beta"], "relation_path": []} + }, + { + "name": "direction_proves_disconnection", + "operation": "find_path", + "input": {"from": "delta", "to": "alpha", "direction": "out", "max_hops": 8, "max_explored_blocks": 10000}, + "assert": {"status": "not_found"} + }, + { + "name": "hop_budget_prevents_proof", + "operation": "find_path", + "input": {"from": "alpha", "to": "gamma", "direction": "out", "max_hops": 1, "max_explored_blocks": 1000}, + "assert": {"status": "limit_reached"} + } + ] +} diff --git a/20-product-tdd/graph-navigation-retrieval.md b/20-product-tdd/graph-navigation-retrieval.md new file mode 100644 index 0000000..89437c2 --- /dev/null +++ b/20-product-tdd/graph-navigation-retrieval.md @@ -0,0 +1,79 @@ +# Graph Navigation Retrieval Contract + +## Purpose + +Define the shared semantics of graph-navigation retrieval across peer implementations and +InfoBase views. Graph navigation reads persisted Blocks and Relations as graph authority. It +does not resolve content，rank semantic similarity，maintain an index，or own presentation、 +layout、camera or route state. + +## Read Model + +- `GraphModel` is the presentation-neutral read result. It contains existing Blocks and + Relations and is distinct from producer-oriented graph forms. +- Every returned Relation is endpoint-closed：both referenced Blocks appear in the same + `GraphModel`. A disappearing or dangling Relation is omitted from an otherwise successful + neighborhood result rather than exposing an unusable edge. +- Persisted Relation direction and content are returned unchanged. Query direction controls + admissible traversal，not the meaning or orientation of stored graph facts. +- Retrieval does not include labels，Resolver output，solved content，preview data，layout or + camera hints. Consumers obtain those through their respective owners. + +## Neighborhood Operations + +- A Block neighborhood returns the focal Block plus a bounded page of incident Relations and + their endpoints. Missing focal returns no result；an isolated focal succeeds with a graph + containing one Block and no Relations. +- Direction is `in`，`out` or `both`. Optional Relation contents are exact-match filters. +- Relation pages use persisted Relation identity descending with an exclusive continuation + cursor. `both` remains one public incident-page abstraction even when an implementation + queries incoming and outgoing branches separately. +- A Relation neighborhood returns that Relation and exactly its two endpoint Blocks. Missing + or no-longer-closed authority returns no result. +- Random Block selection is a primitive for choosing an initial focal entity. Empty authority + returns no Block；the contract makes no distribution-quality promise. + +## Bounded Path Operation + +- Path retrieval finds a shortest admissible Block-to-Block path within explicit hop and + explored-Block budgets. Direction and exact Relation-content filters apply during traversal. +- A found result contains an endpoint-closed `GraphModel` plus aligned ordered Block and + Relation identity paths. `from == to` is a valid zero-hop path. +- `not_found` means the admissible reachable graph was exhausted. `limit_reached` means a + budget prevented that proof. Implementations do not hide this distinction through retries + or silently broaden the query. +- When several equal-hop shortest paths exist，any valid shortest path is acceptable. The + contract does not promote an incidental database or traversal tie-break into product truth. +- If persisted rows change before final assembly and the candidate path no longer validates， + the operation fails as an ordinary retrieval/validation error. It does not fabricate a path + outcome or claim snapshot isolation. + +## Peer And Presentation Boundary + +- Python，web and future peers may implement these operations directly against shared graph + authority. Graph navigation does not require synchronous Peer delegation or a database RPC. +- InfoBase views consume retrieval results but do not define retrieval semantics. Graph views + may progressively realize a focal neighborhood；List or future views may use the same read + capability differently. +- Preview and solved-content presentations may consume the same Resolver-owned solved-content + authority，but remain separate presentation contracts. Preview is bounded and + interaction-free；solved content may support focused reading and business interaction. +- Block and Relation inspectors are entity-local. Application routing/history remains owned by + the client application，while a Graph view may realize those destinations as a navigation + host. + +## Shared Acceptance Corpus + +[`graph-navigation-retrieval.corpus.json`](graph-navigation-retrieval.corpus.json) owns stable +topology aliases，persisted Relation direction/content，scenario inputs and semantic assertions. +Runtime database identities，one arbitrary equal-shortest path，private query counts and UI +geometry are deliberately absent. Every peer runner resolves aliases only inside its +acceptance harness. + +## Explicit Non-Goals + +- generic N-hop/pattern query language，full-graph loading or community analysis +- semantic/lexical ranking，Resolver-local graph access or retrieval-driven graph mutation +- hidden retry，snapshot claims，path ranking or equal-path tie-break API +- presentation layout，camera，scene cache，node sizing or application navigation state +- graph-navigation Peer capability，inbound protocol or database RPC diff --git a/20-product-tdd/peer-database-runtime-contract.md b/20-product-tdd/peer-database-runtime-contract.md index 1680647..d8497a5 100644 --- a/20-product-tdd/peer-database-runtime-contract.md +++ b/20-product-tdd/peer-database-runtime-contract.md @@ -93,6 +93,12 @@ The shared browser-to-database and browser-to-runtime token contract is: - maximum lifetime: 24 hours; - signature secret: runtime-owned and at least 32 bytes. +A signer may move `iat` a small, bounded amount into the past to tolerate ordinary clock skew +between independently deployed Peers and protocol runtimes. It must derive `exp` from that adjusted +`iat`, so the allowance never increases the 24-hour maximum token lifetime. Clock-skew handling +belongs to the signing boundary; database queries and domain callers do not retry or rewrite tokens +individually. + PostgREST and native HTTP runtimes validate the same claim vectors. A missing, malformed, expired, overlong, wrong-secret, wrong-role, wrong-issuer, or wrong-audience token is denied. The contract does not assign secret custody to `core-py`; each deployment supplies the same diff --git a/20-product-tdd/unit-topology.md b/20-product-tdd/unit-topology.md index e2bb98e..a123511 100644 --- a/20-product-tdd/unit-topology.md +++ b/20-product-tdd/unit-topology.md @@ -39,3 +39,5 @@ Define cross-unit technical boundaries and ownership so changes do not leak resp - Lexical feature retrieval，multimodal AI content transport，faithful media materialization， Organization media interpretation and List-host navigation use the shared [Feature Retrieval And Media Interpretation Contract](feature-retrieval-and-media-interpretation.md). +- Endpoint-closed graph neighborhoods，bounded shortest paths and InfoBase-view separation use + the [Graph Navigation Retrieval Contract](graph-navigation-retrieval.md). diff --git a/AGENTS.md b/AGENTS.md index 01f0eef..ac8ca16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ This repository is the authoritative Hub for durable product truth shared across ## Development Workflow +- Follow the organization-wide [Verification and Test Policy](https://github.com/InKCre/.github/blob/main/TESTING.md); repository-local documents may only record justified local exceptions. - Runtime: Python 3.11+ for the SVC CLI. - Install SVC: `python -m pip install sustainable-vibe-coding==10.0.1`. - Inspect adoption: `svc status --json`. diff --git a/docs/index.md b/docs/index.md index 461eb80..0c6fb9a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,6 +9,7 @@ - [Knowledge capability contract](../20-product-tdd/knowledge-capability-contract.md) - [Semantic retrieval and Peer capabilities](../20-product-tdd/semantic-retrieval-and-peer-capabilities.md) - [Feature retrieval and media interpretation](../20-product-tdd/feature-retrieval-and-media-interpretation.md) +- [Graph navigation retrieval](../20-product-tdd/graph-navigation-retrieval.md) - [Peer database runtime contract](../20-product-tdd/peer-database-runtime-contract.md) - [Claim realization matrix](../20-product-tdd/claim-realization-matrix.md) - [Hub/Spoke ownership profile](../00-meta/submodule-profile.md)