Source evolution and scoped impact

A detected source revision creates review candidates. It never silently replaces an accepted note or treats an unavailable copy as current truth. The source API always acquires current upstream revision/access before serving passages or projecting impact details.

Dependencies and access

The private connector configuration accepts a top-level consumers array. It maps explicit consumes / depends_on dependencies from a connector/document to squad/project decisions and owned documentation. This is reviewed host configuration, not an inferred permission grant.

{
  "id":"squad-a-integration",
  "owner":"EXACT_AUTHENTICATED_SUBJECT",
  "relation":"consumes",
  "connector_id":"docs",
  "document_id":"catalog",
  "api_version":"v2",
  "environment":"prod",
  "readers":["EXACT_CURRENT_OPERATOR_SUBJECT"],
  "fact":{"type":"project","id":"squad-a"},
  "documentation_uri":"https://selected.example/squad-a/integration"
}

The current operator must be allowed by the source document and consumer ACL; the candidate owner must also be allowed by the source document. Exact version/environment filters apply before retrieving the optional native consumer identity. Missing native facts receive no candidate. The host must keep these explicit source/consumer grants current; they do not infer account membership from names. Shared operator identity comes from the verified Root read capability; an environment override cannot impersonate a shared subject.

For the API v2 authentication example, two matching authorized squads get source-linked review candidates. A restricted owner, v1 consumer and test-environment consumer get no recipients/details. Native consumer_fact, relation, owned documentation reference and full source citation accompany the candidate. No notification is sent to people automatically; the caller receives authorized candidates for a dashboard/workflow.

Observation and lifecycle

Metadata records exact connector/document/revision/digest/observation time/access hash/URI/version/environment. Repeated deliveries of the same revision/access/content deduplicate candidates. A reused immutable revision with changed bytes fails as divergence. A cursor/hint gap reconciles the latest upstream state with bounded acquisition; unobserved intermediate revisions are not invented. A stable document ID can be explicitly remapped after a rename.

States distinguish observed revisions, analyzed dependencies, proposed candidates, explicit review, native accepted annotation, superseded candidates and unavailable sources. A new revision supersedes previous candidates. Deletion, revocation or acquisition failure removes current availability and returns no old passage or old impact detail. Restored access creates a candidate that needs fresh review; prior approval is not reused silently.

The operational lineage is a bounded, owner-private metadata ledger per verified host actor, under .synapse/source-monitor, with durable atomic replacement while holding the native writer lease. It retains no upstream body or credential. History/candidate count is bounded to 512 and serialized state to 4 MiB; exhaustion fails rather than silently dropping history. This ledger is not a signed accepted-knowledge proof. Accepted source history remains the native governed transaction evidence. Existing Git/index/receipt distinctions continue to apply.

Review, patch and native acceptance

Use the same syn sources --request / MCP sources contract with an additive operation:

{"connector":"docs","document_id":"catalog","cursor":null,"notification_revision":null,"cancelled":false,"operation":{"op":"observe"}}

review takes proposal_id. suggest_patch takes the reviewed ID, current expected_revision and bounded replacement; it produces a source-linked suggestion with a replacement digest, not a published edit. Revision, access policy or document mapping changes invalidate it. Both current adapters have write_back:false; publish fails even with explicit consent or a broadly privileged token. A future write adapter needs explicit capability, reviewer consent and an upstream concurrency precondition.

queue takes a reviewed proposal and explicitly authored annotation body. The exact note payload retains x-upstream-source, x-source-impact, x-source-consumer and x-source-dependency. Repeated identical queue requests return the original row. The queue remains pending until an operator uses accept with the exact returned pending_id and review_sha256. Fresh upstream access/revision/digest/policy must still match; exact pending bytes are checked again inside the native transaction. Generic native acceptance refuses source-derived queue rows without fresh adapter evidence, and MCP cannot invoke operator acceptance. Native source/history/index/status commit together through the existing transaction primitive.

This first acceptance slice is local-owner only. Shared observation/impact uses authenticated Root reads, but shared source-derived acceptance requires a dedicated Root host workflow and remains disabled. It cannot be bypassed through generic shared candidate sealing. The native accepted note is a historical, locally authored annotation, not a replicated live upstream page. Generic note retrieval preserves that historical annotation; it does not assert fresh remote authorization or currentness. Current external passages and impact views must use the source API. Privileged raw filesystem access remains outside the API’s access-control contract.

Upstream reads and local commits have optimistic preconditions, not an atomic transaction across GitHub and the local filesystem. No distributed write guarantee, complete enterprise ACL synchronization, background worker or human pilot ROI is claimed. Queue/index recovery has the same limits as the existing native operational queue; rebuilding an index does not invent missing review rows.

Verification

tests/source_impact_smoke.py uses actual Git commits and the native CLI/MCP on owned synthetic fixtures. It proves two-squad fan-out with version/environment/restricted-owner exclusions, idempotent notifications/queueing, review, explicit native acceptance and its preserved source citation, generic/MCP approval denial, changed authentication source, rename, stale patch/queued acceptance, revocation/deletion and no upstream mutation. Native state verify validates accepted local history before/after source changes. Pure tests cover immutable revision divergence, access-precondition changes, restored-access review and supersession. These are engineering conformance tests, not a consenting human field pilot.

See ADR-070, SYN-327 (#312), SYN-335 (#96) and the optional decision experiment.