Spec: versioned source_ref schema for doc pointers

[aurexav]

Parent

• Epic: Agent memory UX: MCP surface + skills + doc pointers (epic) #74

Problem

• source_ref is required and flexible, but lacks a standard, versioned schema for document pointers.
• Without a schema, downstream agents cannot reliably hydrate original long-form content.

Scope

• Define a versioned source_ref schema for doc pointers (e.g., kind, schema_version, doc_id, uri, content_hash, locator/span, mime_type, access hints).
• Define compatibility rules (forward/backward), validation expectations, and safe limits.

Acceptance criteria

• Add a spec or guide page that defines the schema and rules.
• Provide at least one reference example payload.
• Explicitly document how this interacts with the English-only boundary (canonicalize facts to English; store originals elsewhere).

Notes

• Backlog draft: docs/plans/2026-02-23-agent-memory-mcp-skills-backlog.md.

[aurexav]

Clarification: resolver-based source_ref (Core vs Extensions)

Decision

• source_ref is resolver-based and extension-resolved.
• ELF Core stores/returns source_ref as opaque JSON and never dereferences it.
• Extensions/skills/backends may dereference source_ref into bounded excerpts.

Recommended top-level shape
{
"schema": "source_ref/v1",
"resolver": "fs_git|fs|pg_doc|sqlite_doc|url|codex_thread|...",
"ref": { "...": "resolver-specific address" },
"state": { "...": "optional snapshot/version" },
"locator": { "...": "optional excerpt selector(s)" },
"hashes": { "...": "optional integrity checks" },
"hints": { "...": "optional debug/UX" }
}

Resolver tiers

• reproducible: dereference is stable and replayable given (ref + state).
  • Example: fs_git with ref={repo,path} and state={commit_sha}.
• best_effort: dereference may change over time.
  • Example: codex_thread with ref={thread_id,message_id?}. In this tier, resolvers should expose verified=true/false.

Locator recommendation for fs_git

• Primary: TextQuoteSelector (exact + prefix + suffix)
• Optional refinement/hints: text_position, line_range, heading
• Default policy: require commit_sha for fs_git; allow a separate fs_worktree resolver for local/dev-only best-effort references.