research: define the Source integration shape

[PsiACE]

Objective

Define a practical Source integration shape for external systems.

An external object may change while evidence used by an Artifact must remain exact. Research how a stable logical Source identity relates to an immutable observation or revision. Capture, Ref, and any hybrid form describe how that observation is materialized.

Provider connectors own discovery, synchronization, checkpoints, retries, credentials, and provider-specific change handling. This issue covers the Source values they produce and how PowerContext accepts, reads, stores, and cites those values.

Record the chosen shape in an RFC before changing the public Source model or API. The RFC records the design decision. Maintained docs, OpenAPI, and code describe current behavior.

Current baseline

Core provides typed Source adapters and supports captured and referenced materialization.

The builtin Runtime provides ContentSource and POST /v1/sources/content as an idempotent captured-text path. Reusing an identity with different content is a conflict. Runtime assembly, Server capabilities, and evidence projection currently handle ContentSource explicitly.

The research should decide whether ContentSource and the content API are the common capture boundary for external integrations or one concrete Source implementation alongside other typed Sources.

Research references

• Git repositories and GitHub-like services
• Notion
• Slack
• Linear
• Relevant memory and context projects

These are reference cases, not committed implementation targets.

Tracking

• Audit the current Source model, ContentSource, persistence, Runtime assembly, HTTP API, and evidence projection.
• Define the relationship between logical Source identity and immutable observation or revision identity.
• Compare Capture, Ref, and possible hybrid materialization.
• Define the minimum provenance required for an exact SourceRef.
• Decide the role of ContentSource and POST /v1/sources/content.
• Define how additional Source types register with persistence, Runtime, transport, and Artifact pipelines.
• Draft and review the RFC.
• Implement the accepted improvements.
• Validate the shape with one bounded Source integration.

Target completion is around 2026-09-01. The validation integration does not need to be a complete production connector.

This work does not design a full connector framework or move provider synchronization into the Source model.