Skip to content

Expose structured MCP reads with stable ledger identities - #601

Merged
WaylandYang merged 3 commits into
deeplethe:devfrom
Floating-Y:feat/550-structured-read-contract
Sep 11, 2026
Merged

WaylandYang merged 3 commits into
deeplethe:devfrom
Floating-Y:feat/550-structured-read-contract

Conversation

@Floating-Y

Copy link
Copy Markdown
Contributor

MCP readers currently have to parse prose to recover facts and provenance.
Add structuredContent alongside existing text for find_entities,
search_chunks, entity_facts, and changes, using the same UUIDs as RDF exports.

  • Preserve fact identities, both time axes, source document IDs, raw values,
    relation qualifiers, and explicit limit metadata.
  • Return read failures as MCP errors instead of successful empty collections.
  • Document the supported structured read contract and its limitations.
  • Restore RDF links to derived premises in Turtle and JSON-LD.
  • Add authenticated MCP integration tests and PostgreSQL CI coverage.

No database migration or new dependency is required.
Conflict/review export (#564), chunk provenance in RDF, and SPARQL
remain separate work.

Validation

  • Formatting and workspace Clippy passed.
  • Workspace tests with PostgreSQL required: 604 passed, 1 ignored.
  • Frontend tests: 18 passed.
  • Frontend production build passed.

Closes #550.

@Floating-Y
Floating-Y force-pushed the feat/550-structured-read-contract branch 2 times, most recently from f386e58 to f053c8b Compare September 10, 2026 17:01
Signed-off-by: Floating-Y <118035379+Floating-Y@users.noreply.github.com>
Signed-off-by: Floating-Y <118035379+Floating-Y@users.noreply.github.com>
Signed-off-by: Floating-Y <118035379+Floating-Y@users.noreply.github.com>
@WaylandYang
WaylandYang force-pushed the feat/550-structured-read-contract branch from f053c8b to 88257f4 Compare September 10, 2026 23:57
@WaylandYang

Copy link
Copy Markdown
Contributor

Reviewed against dev after #600/#602 — no logical conflict with the qualifier work, identities are the real row ids, invalidated rows behave as the export does, and the tests read every id back. Thank you; merging.

Three small things I'll take as a follow-up rather than hold this on (tracked in an issue):

  1. tools_graph.rs resolve() maps a database error to "could not look up entities", which entity_facts then wraps as Invalid entity: … (expected a name, or the uuid returned by find_entities) and neighbors / timeline / paths_between report as Unknown entity with isError:false. An outage reads as a bad argument; a distinct "could not read" result, as find_entities already returns, is the fix.
  2. docs/decisions/0020 gets an inserted paragraph without a date; the records README asks for a dated revision note in place.
  3. web/src/docs/mcp.md tabulates every structuredContent field under a heading called "contract" but never says whether a removal or rename needs a record. One sentence either way.

Also noted: refused calls (the shared check_call guard) skip the mcp.tool_called audit row; search_chunks.limit_reached and an entity-valued qualifier are untested.

@WaylandYang
WaylandYang merged commit f574b56 into deeplethe:dev Sep 11, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Clarify or expose a stable structured read contract for facts, evidence, proofs, history, and conflicts

2 participants