rfcs: define source snapshot integration shape

[XnLemon]

如果duplicate的话可以close

Which issue or RFC does this PR close?

Part of #1240 #1363.

Rationale for this change

External Sources such as GitHub issues, Notion pages, Slack messages, and Linear issues may change over time.

PowerContext needs to support the latest Source value for ongoing search and ingestion, while preserving the exact source text that was used to produce an Artifact. The current Source model treats (scope_id, source_type, source_id) as one immutable payload, so it cannot represent a mutable Source head together with retained historical snapshots.

This RFC defines the proposed boundary before changing the public Source model, persistence schema, or API.

What changes are included in this PR?

• Add an English RFC describing the proposed Source integration shape.
• Add a synchronized Chinese RFC.
• Define a mutable Source head that points to the latest snapshot.
• Define immutable Source snapshots containing the observed payload, content hash, provider revision, capture time, and optional locator.
• Require Artifact, Candidate, and Handoff exact evidence to reference the snapshot used during generation.
• Define the default behavior:
  • latest snapshot is used for current search and ingestion;
  • historical snapshots remain available for Artifact lineage;
  • a changed provider revision creates a new snapshot instead of replacing the old one.
• Clarify the roles of Capture, Ref, and Hybrid materialization.
• Keep ContentSource as one concrete captured-text Source rather than a universal provider model.
• Keep provider discovery, synchronization, checkpoints, retries, credentials, and provider-specific change handling in connectors.
• Document how TencentDB-Agent-Memory influenced the design:
  • ISourceFetcher and SourceFetcherRegistry;
  • provider revision metadata such as Git commit hashes;
  • SHA-256 based incremental detection;
  • asset version counters and audit records.
• Explain why TencentDB-Agent-Memory’s “pull and ingest the latest value” behavior is not sufficient for PowerContext Artifact evidence, which requires retained historical snapshots.
• Document persistence, Runtime, compatibility, rollout, validation, and open design questions.

No runtime code, OpenAPI schema, or database migration is included in this PR.

Are there any user-facing changes?

No released user-facing behavior changes are included.

This is a proposed design RFC only. The RFC intentionally leaves the final public field names, persistence migration, retention policy, and OpenAPI changes for a follow-up implementation after review.

How was this change tested?

• make docs-test
• git diff --check
• Verified that the English and Chinese RFCs are present and synchronized around the same design decisions.

AI usage statement

This PR was prepared with OpenAI Codex using GPT-5.6, with repository inspection, GitHub issue review, and TencentDB-Agent-Memory source research performed by the AI assistant. Final design decisions and submission remain subject to maintainer review.

验证已通过：

make docs-test
Build finished
No issues found

[XnLemon]

cc @PsiACE 如果duplicate的话可以close
做了一下同类型项目 research 可以补充产品我继续调研

TencentDB-Agent-Memory 把 hash 变化视为重新拉取并 ingest 最新值的信号，保留旧 source 原文不是它的主要 contract。它没有做 rfc 内提到的 保留的 immutable snapshot 所以感觉这里有点说法
PowerContext 的要求不同：当 Artifact 已经引用这份原文时，当前 Source 变化后旧 payload 仍必须可用。因此 PowerContext 可以采用 metadata 与 fetcher 分离，同时为 Artifact citation 增加保留的 immutable snapshot。

[knqiufan]

This RFC is quite good. However, there are some aspects where I suggest further optimization could be made:

1. RFC process and document structure

In both RFC files (lines 1–7):

• The RFC number should match the PR number, so the files should be renamed from 1240_... to 1388_....
• The metadata should include RFC PR: #1388, while keeping research: define the Source integration shape #1240 as the Tracking Issue.
• Both English and Chinese pages should be added to the RFC navigation in zensical.toml.

The document would also be easier to review if it followed the repository RFC template more closely, with separate Guide-level explanation, Reference-level contract, Drawbacks, Prior art, Unresolved questions, and Future possibilities sections.

The PR currently says Closes #1240. Since several central design decisions are still unresolved, I suggest using Relates to #1240 or Part of #1240 for now, and restoring the closing relationship after #1240’s acceptance criteria have been satisfied.

2. Logical identity and exact evidence identity

In the English Motivation and Source head/snapshot sections (lines 32–87; Chinese lines 29–76), the description of the current SourceRef is slightly misleading.

The current reference is exact for an accepted immutable Source row: (scope_id, source_type, source_id) is the persistence identity, a different payload for the same identity is rejected, and Artifact lineage points to that immutable row. The missing concept is a logical object that can own multiple immutable observations.

I think the RFC should define the final identities explicitly. For example:

SourceKey = (scope_id, source_type, source_id)
SourceRef = (scope_id, source_type, source_id, observation_id)

SourceKey would identify the logical source, while SourceRef would always identify exact evidence. A separate SnapshotRef is also possible, but the RFC should select one model and use it consistently.

Scope ownership, observation ID composition and conflict rules, head selection, and the exact reference type are part of the public and persisted contract. They should not remain open questions after the RFC is approved.

3. ContentSource compatibility and Hybrid

The ContentSource sections (English lines 111–119 and 170–173; Chinese lines 98–105 and 153–155) currently appear to promise two incompatible behaviors:

• the same logical ID may receive multiple snapshots;
• the existing content API keeps its current immutable identity/payload idempotency.

Today, a ContentSource ID is an immutable capture ID, not a separate logical provider identity. I suggest keeping ContentSource as a single-observation immutable capture. Provider objects that need multiple observations should use a new typed Source Definition. This preserves current callers, including prompt import, without trying to infer mutable identity from metadata.

I am also not sure that Hybrid needs to be a third materialization mode. A captured observation can retain the external locator and revision as provenance while the captured canonical value remains authoritative. If Hybrid stays, the RFC needs to define which value is authoritative during digest mismatch, provider failure, and reconciliation. Otherwise, Capture and Ref seem sufficient.

4. Source Definition, canonicalization, and projection contracts

The snapshot model (English lines 69–82; Chinese lines 59–72) mentions a canonical value and content_hash, but a hash cannot be interoperable without a canonicalization contract.

The RFC should define:

• stable Source Definition name and version;
• value and provenance schemas;
• logical and observation identity rules;
• canonical bytes and digest algorithm;
• which provenance fields participate in observation identity;
• how old observations are interpreted after a Definition upgrade;
• what “equivalent provenance” means and who evaluates it.

The projection/capability registry also needs a concrete contract if it remains normative: projection name and version, input and output schemas, determinism, canonicalization, missing-capability behavior, and preservation of the original observation lineage. Otherwise, this part could be moved into a follow-up proposal.

5. Source state and connector state need a clearer boundary

In the Source head and connector sections (English lines 63–78 and 121–131; Chinese lines 53–68 and 107–117), provider locator data and operational connector state are still mixed together.

I suggest separating these concepts:

• logical Source head: current observation and deletion state;
• immutable observation: exact identity, canonical value digest, materialization, and declared provenance;
• Source Definition: schema, identity, canonicalization, compatibility, and projection rules;
• connector binding/run state: credential references, checkpoint, retry state, health, and provider namespace.

Credentials should never be stored in the Source head or observation. A provider locator should become durable provenance only when its meaning and canonical form are declared by the Source Definition.

The connector protocol also needs correctness rules, not only a list of connector responsibilities:

1. start a run from an opaque checkpoint;
2. return a visible per-item outcome;
3. persist accepted results before returning a durable receipt;
4. advance the checkpoint using compare-and-swap;
5. reject stale checkpoint updates;
6. never advance past an item that cannot be safely replayed.

Deletion needs similar precision. An authoritative deletion event or absence from a complete discovery run may produce deletion evidence. An incomplete listing, timeout, permission failure, or disconnected connector must not silently delete the Source head. Deleting the head must not delete immutable observations or rewrite existing Artifact lineage.

6. Exact reads, retention, and concurrent head advancement

The Ref section correctly says that failure to resolve an exact revision must not fall back to the provider’s current value. It should also specify that:

• the returned value is canonicalized and checked against the stored digest;
• not found, permission denied, digest mismatch, and temporary unavailability are distinct failures;
• consumers fail explicitly when exact evidence is unavailable;
• converting a Ref into a captured observation is an explicit operation.

The minimum retention guarantee also needs to be settled before approval. At least, any observation referenced by a durable Artifact, candidate, or handoff must be protected from ordinary GC. Head deletion must not imply observation deletion. Legal or user-requested hard deletion should be treated as a separate audited operation with an explicit lineage-breaking policy.

For operations that consume “latest”, the RFC should define a freeze boundary. An ingestion or generation operation should resolve and freeze exact SourceRefs, or a Source high-watermark, when it starts. Later head advancement must not change the inputs of the running operation, and its output lineage must record the exact observations actually used.

7. Migration is part of the design contract

The migration section (English lines 158–173; Chinese lines 143–155) currently leaves too much to implementation.

The RFC does not need to contain SQL, but it should define:

• how each legacy Source row receives a deterministic observation ID;
• whether a logical head is created for every legacy row;
• how existing Artifact lineage receives an observation reference;
• how legacy two-part API references remain readable and are eventually deprecated;
• whether old and new workers/servers may run together;
• migration interruption and rollback behavior;
• how the current payload-conflict semantics are preserved.

Without these rules, it is difficult to evaluate compatibility across persistence, OpenAPI, generated clients, HTTP, MCP, and existing lineage.

8. Prior-art links and validation coverage

All six TencentDB /blob/main/ links in the Prior art section currently return 404. They should be replaced with commit-pinned permalinks, for example using commit 5299c00aaf65481703c180fd69df066d11254eb7, so the evidence remains stable.

The rollout matrix should also cover:

• scope ownership and cross-scope rejection;
• observation ID conflicts;
• canonicalization and Definition-version compatibility;
• concurrent head advancement and operation freezing;
• durable receipt and checkpoint CAS;
• partial item failure;
• complete versus incomplete discovery;
• permission failure not producing deletion;
• legacy Source, lineage, and OpenAPI migration;
• unchanged ContentSource immutable semantics;
• Ref digest mismatch and unavailability;
• English/Chinese API and documentation consistency.

9. Coordination with the parallel Source Definition work

There is also a maintainer-authored public WIP branch, [codex/source-definition-rfc](https://github.com/oceanbase/powercontext/tree/codex/source-definition-rfc), with commits 61199414 through b4885bdc.

That work already defines SourceKey and exact SourceRef identities, keeps ContentSource single-observation, uses Capture/Ref without introducing Hybrid, and includes Definition, canonicalization, connector receipt/checkpoint, deletion, and incomplete-discovery contracts. Several of those choices directly conflict with this RFC.

Since the branch is still WIP, it should not automatically override this proposal. However, I think the two designs should be reconciled before either one is merged. It would be better to select one contract as the baseline and fold the useful problem statement and TencentDB research from this RFC into it, instead of leaving two incompatible Source models in the project history.

Overall, I think the RFC has a solid motivation and useful prior-art research. My main concern is that identity, compatibility, lifecycle, migration, and retention are still treated as implementation details even though they define the core public contract. Resolving those items, coordinating with the parallel WIP, and then fixing the RFC metadata, links, navigation, and test matrix would make this a much stronger and implementable proposal.

[XnLemon]

This RFC is quite good. However, there are some aspects where I suggest further optimization could be made:

1. RFC process and document structure

In both RFC files (lines 1–7):

• The RFC number should match the PR number, so the files should be renamed from 1240_... to 1388_....
• The metadata should include RFC PR: #1388, while keeping research: define the Source integration shape #1240 as the Tracking Issue.
• Both English and Chinese pages should be added to the RFC navigation in zensical.toml.

The document would also be easier to review if it followed the repository RFC template more closely, with separate Guide-level explanation, Reference-level contract, Drawbacks, Prior art, Unresolved questions, and Future possibilities sections.

The PR currently says Closes #1240. Since several central design decisions are still unresolved, I suggest using Relates to #1240 or Part of #1240 for now, and restoring the closing relationship after #1240’s acceptance criteria have been satisfied.

2. Logical identity and exact evidence identity

In the English Motivation and Source head/snapshot sections (lines 32–87; Chinese lines 29–76), the description of the current SourceRef is slightly misleading.

The current reference is exact for an accepted immutable Source row: (scope_id, source_type, source_id) is the persistence identity, a different payload for the same identity is rejected, and Artifact lineage points to that immutable row. The missing concept is a logical object that can own multiple immutable observations.

I think the RFC should define the final identities explicitly. For example:

SourceKey = (scope_id, source_type, source_id)
SourceRef = (scope_id, source_type, source_id, observation_id)

SourceKey would identify the logical source, while SourceRef would always identify exact evidence. A separate SnapshotRef is also possible, but the RFC should select one model and use it consistently.

Scope ownership, observation ID composition and conflict rules, head selection, and the exact reference type are part of the public and persisted contract. They should not remain open questions after the RFC is approved.

3. ContentSource compatibility and Hybrid

The ContentSource sections (English lines 111–119 and 170–173; Chinese lines 98–105 and 153–155) currently appear to promise two incompatible behaviors:

• the same logical ID may receive multiple snapshots;
• the existing content API keeps its current immutable identity/payload idempotency.

Today, a ContentSource ID is an immutable capture ID, not a separate logical provider identity. I suggest keeping ContentSource as a single-observation immutable capture. Provider objects that need multiple observations should use a new typed Source Definition. This preserves current callers, including prompt import, without trying to infer mutable identity from metadata.

I am also not sure that Hybrid needs to be a third materialization mode. A captured observation can retain the external locator and revision as provenance while the captured canonical value remains authoritative. If Hybrid stays, the RFC needs to define which value is authoritative during digest mismatch, provider failure, and reconciliation. Otherwise, Capture and Ref seem sufficient.

4. Source Definition, canonicalization, and projection contracts

The snapshot model (English lines 69–82; Chinese lines 59–72) mentions a canonical value and content_hash, but a hash cannot be interoperable without a canonicalization contract.

The RFC should define:

• stable Source Definition name and version;
• value and provenance schemas;
• logical and observation identity rules;
• canonical bytes and digest algorithm;
• which provenance fields participate in observation identity;
• how old observations are interpreted after a Definition upgrade;
• what “equivalent provenance” means and who evaluates it.

The projection/capability registry also needs a concrete contract if it remains normative: projection name and version, input and output schemas, determinism, canonicalization, missing-capability behavior, and preservation of the original observation lineage. Otherwise, this part could be moved into a follow-up proposal.

5. Source state and connector state need a clearer boundary

In the Source head and connector sections (English lines 63–78 and 121–131; Chinese lines 53–68 and 107–117), provider locator data and operational connector state are still mixed together.

I suggest separating these concepts:

• logical Source head: current observation and deletion state;
• immutable observation: exact identity, canonical value digest, materialization, and declared provenance;
• Source Definition: schema, identity, canonicalization, compatibility, and projection rules;
• connector binding/run state: credential references, checkpoint, retry state, health, and provider namespace.

Credentials should never be stored in the Source head or observation. A provider locator should become durable provenance only when its meaning and canonical form are declared by the Source Definition.

The connector protocol also needs correctness rules, not only a list of connector responsibilities:

1. start a run from an opaque checkpoint;
2. return a visible per-item outcome;
3. persist accepted results before returning a durable receipt;
4. advance the checkpoint using compare-and-swap;
5. reject stale checkpoint updates;
6. never advance past an item that cannot be safely replayed.

Deletion needs similar precision. An authoritative deletion event or absence from a complete discovery run may produce deletion evidence. An incomplete listing, timeout, permission failure, or disconnected connector must not silently delete the Source head. Deleting the head must not delete immutable observations or rewrite existing Artifact lineage.

6. Exact reads, retention, and concurrent head advancement

The Ref section correctly says that failure to resolve an exact revision must not fall back to the provider’s current value. It should also specify that:

• the returned value is canonicalized and checked against the stored digest;
• not found, permission denied, digest mismatch, and temporary unavailability are distinct failures;
• consumers fail explicitly when exact evidence is unavailable;
• converting a Ref into a captured observation is an explicit operation.

The minimum retention guarantee also needs to be settled before approval. At least, any observation referenced by a durable Artifact, candidate, or handoff must be protected from ordinary GC. Head deletion must not imply observation deletion. Legal or user-requested hard deletion should be treated as a separate audited operation with an explicit lineage-breaking policy.

For operations that consume “latest”, the RFC should define a freeze boundary. An ingestion or generation operation should resolve and freeze exact SourceRefs, or a Source high-watermark, when it starts. Later head advancement must not change the inputs of the running operation, and its output lineage must record the exact observations actually used.

7. Migration is part of the design contract

The migration section (English lines 158–173; Chinese lines 143–155) currently leaves too much to implementation.

The RFC does not need to contain SQL, but it should define:

• how each legacy Source row receives a deterministic observation ID;
• whether a logical head is created for every legacy row;
• how existing Artifact lineage receives an observation reference;
• how legacy two-part API references remain readable and are eventually deprecated;
• whether old and new workers/servers may run together;
• migration interruption and rollback behavior;
• how the current payload-conflict semantics are preserved.

Without these rules, it is difficult to evaluate compatibility across persistence, OpenAPI, generated clients, HTTP, MCP, and existing lineage.

8. Prior-art links and validation coverage

All six TencentDB /blob/main/ links in the Prior art section currently return 404. They should be replaced with commit-pinned permalinks, for example using commit 5299c00aaf65481703c180fd69df066d11254eb7, so the evidence remains stable.

The rollout matrix should also cover:

• scope ownership and cross-scope rejection;
• observation ID conflicts;
• canonicalization and Definition-version compatibility;
• concurrent head advancement and operation freezing;
• durable receipt and checkpoint CAS;
• partial item failure;
• complete versus incomplete discovery;
• permission failure not producing deletion;
• legacy Source, lineage, and OpenAPI migration;
• unchanged ContentSource immutable semantics;
• Ref digest mismatch and unavailability;
• English/Chinese API and documentation consistency.

9. Coordination with the parallel Source Definition work

There is also a maintainer-authored public WIP branch, [codex/source-definition-rfc](https://github.com/oceanbase/powercontext/tree/codex/source-definition-rfc), with commits 61199414 through b4885bdc.

That work already defines SourceKey and exact SourceRef identities, keeps ContentSource single-observation, uses Capture/Ref without introducing Hybrid, and includes Definition, canonicalization, connector receipt/checkpoint, deletion, and incomplete-discovery contracts. Several of those choices directly conflict with this RFC.

Since the branch is still WIP, it should not automatically override this proposal. However, I think the two designs should be reconciled before either one is merged. It would be better to select one contract as the baseline and fold the useful problem statement and TencentDB research from this RFC into it, instead of leaving two incompatible Source models in the project history.

Overall, I think the RFC has a solid motivation and useful prior-art research. My main concern is that identity, compatibility, lifecycle, migration, and retention are still treated as implementation details even though they define the core public contract. Resolving those items, coordinating with the parallel WIP, and then fixing the RFC metadata, links, navigation, and test matrix would make this a much stronger and implementable proposal.

Sorry for I had not realized that #1240 had already moved into implementation and that PsiACE had an existing WIP branch. My intention with #1388 was to write a from-scratch RFC to clarify the problem and establish a baseline before changing the public Source model or API, so the overlap was unintentional. After reviewing PsiACE’s RFC and implementation, I’m prepared to treat that branch as the current implementation baseline and align this RFC with its core decisions around SourceKey/SourceRef, single-observation ContentSource, and Capture/Ref authority. The remaining changes should mainly clarify retention and legacy-migration invariants, and decide whether the detailed Connector lifecycle and projection contracts belong here or in follow-up work. I have also swept up the smaller issues mentioned: the RFC files are now numbered 1388, RFC PR metadata and English/Chinese navigation have been added, the relationship is now Part of #1240, and the TencentDB-Agent-Memory links are pinned to a specific commit.

One additional scope clarification follows from this review: I will treat PsiACE’s branch as the current implementation baseline, while keeping #1388 as the contract baseline. #1388 is intended to define how an external object Source—using GitHub/Linear-like systems as motivating examples, not committed provider targets—is represented and accepted by PowerContext. It is not a GitHub/Linear integration plan and does not define a general Connector framework. Provider discovery, synchronization, credentials, retries, checkpoints, and provider-specific deletion handling remain Connector responsibilities, consistent with the boundaries stated in #1240.

For the remaining RFC pass, I plan to make the following invariants explicit:

• An accepted observation must remain value-stable for every existing SourceRef; retention or garbage collection must never silently redirect it to a newer observation.
• A referenced observation may be read only through its immutable external revision. PowerContext must not fall back to the provider’s current value.
• Legacy (source_type, source_id) records and Artifact references must map deterministically to the one observation that already exists. Migration must not invent history or reinterpret an old reference as latest.
• Existing ContentSource behavior remains compatible, while evolving integrations use SourceKey plus observation_id.
• rfcs: define source snapshot integration shape #1388 will retain only the minimum Connector and projection hooks required to enforce these rules. Detailed Connector lifecycle, projection catalogs, and remote-worker protocols can follow separately unless implementation evidence shows that they are required by the baseline.

The OpenDAL text-file path can serve as a bounded validation integration, but it is not intended to make files, GitHub, or Linear normative Source types.

我之前没有注意到 #1240 已经进入实现阶段，也没有注意到 PsiACE 已经有一条 WIP 分支。这次提交 #1388 的初衷，是从零开始写一份 RFC，在修改公共 Source 模型和 API 之前把问题与设计基线重新说明清楚，因此和现有分支产生重叠并非有意。看过 PsiACE 的 RFC 和实现后，我接受这条已开发分支作为当前实现基线，后续会围绕它对齐 SourceKey/SourceRef、单次 observation 的 ContentSource，以及 Capture/Ref 的权威性等核心决策。RFC 还需要调整的地方主要是补充 retention 和 legacy migration 的不变量，并决定 Connector lifecycle 与 projection 的详细契约是保留在本 RFC，还是拆到后续工作中。你提到的较小问题我也已经 sweep 掉了：RFC 文件已改为 1388，补充了 RFC PR metadata 和中英文导航，将关系改为 Part of #1240，并把 TencentDB-Agent-Memory 链接固定到了具体 commit。

这次讨论还带来一个范围上的澄清：我会把 PsiACE 的分支视为当前实现基线，同时把 #1388 保留为契约基线。#1388 旨在定义外部对象型 Source 如何被 PowerContext 表示和接收；GitHub/Linear-like 系统只是动机案例，并不是承诺实现的 provider。它不是 GitHub/Linear 集成方案，也不定义通用 Connector framework。Provider discovery、同步、凭证、重试、checkpoint 以及 provider-specific deletion handling 仍属于 Connector 职责，这与 #1240 中定义的边界一致。

RFC 剩余部分会明确以下不变量：

• 已接受的 observation 对已有 SourceRef 必须保持值稳定；retention 或 GC 不能将其静默重定向到更新的 observation。
• referenced observation 只能通过外部不可变 revision 读取，不能回退到 provider 当前值。
• 旧的 (source_type, source_id) 记录和 Artifact 引用必须确定性地映射到现有的唯一 observation；迁移不能凭空制造历史，也不能把旧引用解释成 latest。
• 保持现有 ContentSource 行为兼容；需要演进的集成则使用 SourceKey 加 observation_id。
• rfcs: define source snapshot integration shape #1388 只保留落实这些规则所必需的最小 Connector 和 projection 接口；详细的 Connector lifecycle、projection catalog 和 remote-worker protocol，除非实现证明它们是基线必需，否则拆到后续工作。

OpenDAL 文本文件路径可以作为一个 bounded validation integration，但不会因此把文件、GitHub 或 Linear 固化成规范性的 Source 类型。

[XnLemon]

After comparing TencentDB-Agent-Memory’s Source handling with the current Source Definition and observation model, my conclusion is that they address adjacent but different layers.

TencentDB-Agent-Memory primarily models the current state of an acquisition and ingestion resource. Its SourceFetcher routes protocols and returns the current provider version; Wiki uses filename as the current key and SHA-256 as a change detector; CodeGraph stores the current repository, branch, commit hash, operational version, and synchronization status. These choices work well for pulling and incrementally ingesting the latest value, but they do not provide immutable observation history or an exact reference that an Artifact can retain after the provider value changes.

I especially support the following decisions in the current design:

• Separating SourceKey from SourceRef. SourceKey identifies the continuing logical object, while SourceRef identifies the exact immutable observation used as evidence. Tencent’s in-place updates demonstrate why one identity cannot safely represent both roles.
• Keeping Scope ownership, Source Definition, acquisition provenance, and consumer views separate. Provider paths, connection identities, and projection consumers should not silently redefine Source identity.
• Making materialization an authority contract. A captured observation is resolved from the canonical value retained by PowerContext; a referenced observation must resolve from an immutable external revision. A captured observation may retain the provider locator and revision as provenance without introducing an ambiguous third fallback mode.
• Keeping ContentSource as a single-observation captured-text Source. It remains a useful compatibility and direct-ingestion path without becoming a universal representation for GitHub, Notion, Slack, Linear, or other provider objects.
• Treating named projections as deterministic consumer views of an exact observation. A projection may be cached or persisted, but its authority and lineage remain the exact SourceRef.

The TencentDB-Agent-Memory research therefore supports the acquisition/provenance separation, provider-revision metadata, hashing, incremental detection, and operational audit aspects of the design. It also clarifies the additional requirement PowerContext has: a changed current Source must not replace evidence already referenced by an Artifact.

I would like to keep the following as focused follow-up questions rather than change the current RFC baseline:

1. Projection evidence coordinates: When is an exact SourceRef sufficient by itself, and when should Artifact evidence also record a projection name/version and an offset or semantic anchor? An offset should never stand alone; if a newer observation produces different offsets, it should create new Artifact lineage rather than rewrite the old citation.
2. Current-head ordering: Because observation_id is opaque and does not imply time order, what prevents a late older observation or a concurrent writer from moving the current head backwards? Should head advancement use an explicit CAS, provider-specific ordering, or a high-watermark?
3. Legacy migration: How should existing two-part ContentSource references be mapped to exact observations while preserving their current payload and preventing them from resolving to a future head? How should missing or inconsistent legacy payloads be represented?
4. Retention and deletion: When may unreferenced observations be reclaimed? How should provider deletion, permission loss, and legal or user-requested hard deletion be reported when they make cited evidence unavailable?
5. Public reference shape: Which details belong in the semantic contract now, and which should remain implementation choices—for example, whether every durable SourceRef directly carries scope_id, how observation_id is generated, and how these fields appear in OpenAPI.

These questions are adjacent implementation and contract follow-ups, not proposed changes to the current normative model.

The current #1388 RFC should be read as a synthesis rather than a competing Source design. Its normative Source Definition, SourceKey/SourceRef, observation, materialization, projection, and lifecycle contracts preserve PsiACE’s baseline and conventions. The TencentDB-Agent-Memory section is explicitly non-normative research input contributed by #1388; it explains the comparison and motivation without introducing a second Source contract.

中文

将 TencentDB-Agent-Memory 的 Source 处理方式与当前 Source Definition 和 observation 模型对比后，我的结论是：两者解决的是相邻但不同层次的问题。

TencentDB-Agent-Memory 主要建模 acquisition 和 ingestion 资源的当前状态。它的 SourceFetcher 根据协议路由并返回当前 provider version；Wiki 使用 filename 作为当前 key、使用 SHA-256 检测变化；CodeGraph 保存当前 repository、branch、commit hash、操作版本和同步状态。这些设计适合拉取和增量摄取最新值，但没有提供不可变的 observation history，也没有提供在 provider 内容变化后仍可由 Artifact 保留的精确引用。

我特别认同当前设计中的以下决定：

• 分离 SourceKey 和 SourceRef。 SourceKey 标识持续存在的逻辑对象，SourceRef 标识实际作为证据使用的精确不可变 observation。Tencent 的原地更新模型说明，同一个 identity 无法安全承担这两个职责。
• 分离 Scope ownership、Source Definition、acquisition provenance 和 consumer view。 Provider path、connection identity 和 projection consumer 不应静默改变 Source identity。
• 把 materialization 定义为权威来源契约。 Captured observation 从 PowerContext 保留的 canonical value 解析；referenced observation 必须从外部不可变 revision 解析。Captured observation 可以保留 provider locator 和 revision 作为 provenance，但不需要引入含糊的第三种 fallback 模式。
• 保持 ContentSource 为 single-observation captured-text Source。 它可以继续承担兼容和直接摄取入口，但不应成为 GitHub、Notion、Slack、Linear 等 provider object 的通用表示。
• 把 named projection 作为 exact observation 的确定性 consumer view。 Projection 可以缓存或持久化，但其权威来源和 lineage 仍然是精确 SourceRef。

因此，TencentDB-Agent-Memory 调研支持当前设计中 acquisition/provenance 分离、provider revision metadata、hash、增量检测和运维审计等部分。同时，它也进一步说明了 PowerContext 的额外要求：当前 Source 变化后，已经被 Artifact 引用的证据不能被替换。

我希望将以下内容保留为聚焦的 follow-up 问题，而不是修改当前 RFC 基线：

1. Projection evidence 定位： 哪些场景只记录 exact SourceRef 就足够？哪些场景还需要记录 projection name/version，以及 offset 或 semantic anchor？Offset 不能脱离 snapshot 单独存在；如果新 observation 产生了不同 offset，应产生新的 Artifact lineage，而不是改写旧 citation。
2. Current-head 顺序： observation_id 是 opaque 的，不表示时间顺序。如何防止晚到的旧 observation 或并发 writer 将 current head 回退？Head advancement 应使用独立 CAS、provider-specific ordering，还是 high-watermark？
3. Legacy migration： 现有两段式 ContentSource reference 如何映射成 exact observation，同时保持当前 payload，并禁止它们以后解析到新的 head？缺失或不一致的 legacy payload 应如何表达？
4. Retention 与删除： 未被引用的 observation 何时可以回收？Provider 删除、权限丢失，以及 legal/user-requested hard deletion 导致引用证据不可用时，应如何报告？
5. 公共引用形态： 哪些内容现在属于语义契约，哪些保留为实现决策？例如 durable SourceRef 是否直接携带 scope_id、observation_id 如何生成，以及这些字段如何进入 OpenAPI。

这些问题属于相邻的实现和契约 follow-up，不是对当前规范模型的修改建议。

当前 #1388 RFC 应被理解为一份综合结果，而不是与现有设计竞争的另一套 Source 模型。其规范性的 Source Definition、SourceKey/SourceRef、observation、materialization、projection 和 lifecycle 契约完整保留了 PsiACE 的基线与约定。TencentDB-Agent-Memory 章节被明确标记为 #1388 提供的非规范性调研输入，用于说明对比和设计动机，不会引入第二套 Source contract。