Current

Documents, identity, and ACLs

Benchmark first

Corpora: QASPER · WikiSection · DocRED. Connectors use recorded provider fixtures because public content corpora do not test cursors, deletes, retries, or event ordering.

Protocol: Score text preservation, section Boundary F1/Pk/WindowDiff, entity/relation F1, stable-ID rate, duplicate rate, and incremental/full-sync equivalence. For polling and streaming, replay the same create→update→delete trace with injected duplicates, reordering, throttling, and cursor expiry; the final snapshot and emitted change set must agree.

KnowledgeDocument is the canonical provider-owned record. Its stable ID is {source_id}/{external_id}. Domain values are frozen dataclasses.

How it works

source_id names one configured source; external_id is the provider’s stable object key. Their pair prevents two providers from colliding. revision identifies content version, while updated_at is descriptive metadata and is never used as identity. ACL visibility and principals travel with the document so an allowed-ID set can be computed before retrieval scoring. Frozen values prevent an indexed object from changing behind its recorded revision.

document.py

from mari_components import DocumentACL, KnowledgeDocument, Principal

doc = KnowledgeDocument(
    source_id="github:acme/product",
    external_id="file:docs/refunds.md",
    title="Refund policy",
    body="## Enterprise\nRefunds close after 30 days.",
    revision="8f31c2a", updated_at="2026-08-31T10:00:00Z",
    source_url="https://github.com/acme/product/blob/main/docs/refunds.md",
    acl=DocumentACL(visibility="restricted", principals=(
        Principal(kind="team", identifier="support"),
    )),
    metadata={"path": "docs/refunds.md"},
)
assert doc.document_id == "github:acme/product/file:docs/refunds.md"

PollPage

Upserts, tombstones, cursor, checkpoint, snapshot completeness, provider metadata.

Tombstone

Explicit deletion by source and external ID.

KnowledgeSection

Stable section ID, offsets, text, and section revision.

Evidence

Exact quote plus document, revision, span, and optional section coordinates.

Research and standards

W3C PROV: entity identity and revision Zanzibar: relationship-based authorization

Mari carries principals and visibility but does not implement an authorization engine. The application resolves those fields to allowed_document_ids.