An AI Library Index Should Return Leads, Not Authority

An assistant can be good at finding a document and still be wrong about what that document proves. Search can locate a plausible title. It cannot confirm that the file was read, that a claim is supported, or that the assistant has permission to use its contents.

I have been exploring this boundary while designing a possible library for Aribito, a small local AI team prototype. The Aribito demo currently lets a person compare attributed suggestions and choose one or hold the decision. I described that experience in an earlier CoderLegion article. The library discussed here is proposed, not part of that running demo.

The smallest useful record

My first sketch is an index of metadata cards. Each card has a stable ID, a source kind, an opaque reference, a title, subjects, a short summary, and explicit freshness and verification labels. The invented examples set content_included=False and contain no source body. A summary could itself expose source content, be wrong, stale, or carry an instruction; a metadata field does not make its text trustworthy.

Here is a self-contained Python example. Every record is invented, and demo: references intentionally resolve nowhere. The example reads no files and calls no model.

"""Illustrative, self-contained index example for this article.

Uses fabricated metadata. It does not read source files or connect to Aribito.
"""

from dataclasses import asdict, dataclass
from typing import Literal


SourceKind = Literal["project_note", "demo_guide", "role_outline"]
Freshness = Literal["current", "stale", "unknown"]
Verification = Literal["checked", "unverified"]


@dataclass(frozen=True)
class IndexEntry:
    entry_id: str
    source_kind: SourceKind
    canonical_ref: str  # Opaque demo reference, never a local file path.
    title: str
    logical_day: int | None
    subjects: tuple[str, ...]
    summary: str
    sensitivity: Literal["public", "restricted"]
    freshness: Freshness
    verification_status: Verification
    content_included: Literal[False] = False


def find_candidates(entries: tuple[IndexEntry, ...], term: str) -> tuple[IndexEntry, ...]:
    """Find metadata matches; a match is not evidence or permission."""
    needle = term.strip().casefold()
    if not needle:
        return ()
    return tuple(
        entry
        for entry in entries
        if entry.sensitivity == "public"
        and needle in " ".join((entry.title, *entry.subjects, entry.summary)).casefold()
    )


if __name__ == "__main__":
    # All three records are invented; these references resolve nowhere.
    fixture = (
        IndexEntry("demo-note-1", "project_note", "demo:note:1",
                   "Prototype project note", 12, ("prototype",),
                   "A sample project note exists.", "public", "unknown", "unverified"),
        IndexEntry("demo-guide-1", "demo_guide", "demo:guide:1",
                   "Prototype demo guide", 12, ("prototype",),
                   "A sample demonstration guide exists.", "public", "unknown", "unverified"),
        IndexEntry("demo-role-1", "role_outline", "demo:role:1",
                   "Public role outline", None, ("roles",),
                   "A sample public role outline exists.", "public", "unknown", "unverified"),
    )
    for candidate in find_candidates(fixture, "prototype"):
        print(asdict(candidate))

Run this as python aribito_library_index_example.py. A search for prototype prints two candidate cards. Their freshness is still unknown, and their verification status is still unverified.

What the code proves, and what it does not

The function can match a term against public metadata, including the unverified summary. It does not open the original source, evaluate its claims, or interpret the summary as an instruction. Even a perfect match is only a suggested place to look.

That leaves four useful states to keep apart:

1. Found: a metadata card matched the query.
2. Read: the original source was actually opened under a defined boundary.
3. Supported: a specific claim was checked against that source.
4. Allowed: the intended use of that claim was authorized.

The sample reaches only the first state. A possible later handoff would send the candidate reference to a bounded source reader, then carry its actual read status and claim-level evidence forward for review. That handoff has not been implemented or tested. Source eligibility, card visibility, reference resolution, and stale or contradictory records still need design; the Python type hints and public label do not enforce those boundaries for real documents.

The rule I want to preserve is simple: a useful search hit stays a candidate until the later checks actually happen. That lets an assistant help a person find the next place to look without speaking as if it already knows what is there.

What fields would make a suggested source useful to you without making it look more certain than it is?

---

Direction and publication decision: Masato Kato. Prose and illustrative code: Codex editorial assistance. This is a design example, not a live Aribito feature or model transcript.