Explicit source revision acquisition

Synapse monitors selected upstream documentation through optional outer adapters. It preserves canonical source revision/digest/citation/access provenance and proposes knowledge separately. It does not become the authoring application or import an entire enterprise automatically.

Host configuration and access

Set SYNAPSE_SOURCES_CONFIG to an owner-private regular JSON file, at most 64 KiB, outside the knowledge workspace. Logical aliases and stable document IDs are the only selection accepted from CLI/MCP. Review these mappings as host capabilities; neither Markdown nor agents choose a token, identity, executable or arbitrary URL.

{
  "schema": "synapse.source-adapters/1",
  "connectors": {
    "docs": {
      "kind": "git_markdown",
      "repository": "/absolute/selected/git/repository",
      "reference": "main",
      "documents": {
        "catalog": {"path":"docs/api.md","readers":["local-owner"],"api_version":"v2","environment":"prod"}
      }
    },
    "github-docs": {
      "kind": "github",
      "owner": "selected-owner",
      "repository": "selected-repository",
      "reference": "main",
      "key_env": "SYNAPSE_GITHUB_SOURCE_TOKEN",
      "documents": {
        "catalog": {"path":"docs/api.md","readers":["EXACT_ROOT_SUBJECT_UUID"],"api_version":"v2","environment":"prod"}
      }
    }
  }
}

Local-owner mode uses local-owner by default. A separately trusted local host may set SYNAPSE_SOURCE_ACTOR; this is an explicit host mapping, not account authentication. Shared workspaces ignore that override and derive the subject from the current verified Root read capability. Source document readers must include that exact subject. The Root policy is checked before adapter selection/transport and again before returning content. Host policy bytes are hashed as acl_reference and checked again after acquisition; changes during execution deny output.

Git reads only a pinned commit object through fixed git commands, with user/global/system Git settings disabled, no hooks and a 10-second overall process deadline. Uncommitted edits are ignored; symlink/submodule objects and path traversal are rejected. A stable document ID can be explicitly remapped to a renamed Markdown path; its URI/revision changes visibly.

GitHub requires network_backends; key_env:null permits public reads without credentials. Credentials remain only in the environment. Use narrowly scoped GitHub App/user tokens with repository Contents read access. Current GitHub API access intersects the host document ACL; success is not a write grant. Resolve the branch/ref to an exact commit, read its Contents bytes, and recheck the ref with the same credential before output. Redirects/download URLs are never followed. Deleted/restricted/expired/rate-limited/failed sources expose no stale body. A fresh next poll is the bounded retry; no unbounded automatic retry loop runs.

Bounds, cursors and write policy

One request selects one exact document. Content is bounded to 256 KiB and the GitHub JSON response to 512 KiB, with a 10-second total upstream deadline. There is no background scheduler or secret-bearing webhook server. cancelled:true aborts before transport; in-progress work is bounded by its deadline. Webhooks are untrusted hints. Cursors/hints that disagree with the fresh upstream revision trigger a bounded latest-state reconciliation; this does not claim complete intermediate revision/event history. Replayed hints cannot replace current bytes with their claimed version. Source evolution owns durable dedup and impact candidates (SYN-327).

Both adapters advertise write_back:false. The request schema has no publication operation or reviewer-consent field that can unlock it. Suggested patches require a future explicit write capability plus exact upstream revision and reviewer consent. Possessing a token with broader GitHub permissions does not enable writes. Default acquisition remains read-only and makes no local source changes.

Adapter coverage

tests/sources_smoke.py exercises actual Git update/deletion, repeated notifications, policy revocation, cancellation, uncommitted edits, traversal denial and CLI/MCP parity. Optional SYNAPSE_TEST_LIVE_GITHUB=1 uses the authenticated local gh credential only in process memory for a read-only private repository probe; CI never requires it.

Primary transport contract: GitHub Contents API, commit API. ADR-049 and ADR-069 govern the separation of acquisition, source authority and acceptance.