Skip to content

docs(rfc): define source and artifact REST APIs - #1437

Merged
Zxf-xufeng merged 17 commits into
masterfrom
codex/source-artifact-rest-api-docs
Sep 4, 2026
Merged

docs(rfc): define source and artifact REST APIs#1437
Zxf-xufeng merged 17 commits into
masterfrom
codex/source-artifact-rest-api-docs

Conversation

@Zxf-xufeng

@Zxf-xufeng Zxf-xufeng commented Sep 2, 2026

Copy link
Copy Markdown
Member

Which issue or RFC does this PR close?

Proposes RFC #1437: Source and Artifact base REST APIs.

Scope creation, retrieval, and binding are defined separately by #1401. This RFC treats an existing scope_id as the parent resource and part of each resource's public identity.

Rationale for this change

PowerContext already provides domain-specific operations for Source capture, Memory flush, Experience and Skill evolution, and Handoff workflows. It does not yet provide a stable foundational HTTP API for accessing durable Sources and committed Artifacts without creating a second data or identity space.

This RFC defines a deliberately narrow API that reuses the existing Source journal, immutable Artifact revisions and heads, lineage, authorization, and family-specific domain models. Artifact Create also records its validated input as target-bound provenance without allowing that system Source to be consumed by another generation flow.

What changes are included in this PR?

  • Add synchronized English and Chinese RFCs and keep them in the documentation navigation.
  • Define seven Scope-qualified operations:
    • Source: Create and Get.
    • Artifact: Create, Get head, Get Revision, List, and Replace.
  • Restrict the public Source type to content and Artifact families to memory, experience, skill, and handoff.
  • Require family-specific domain validation and canonical serialization for Artifact Create and Replace.
  • Flatten Artifact identity in responses and return ordered, read-only lineage through sources and artifacts arrays.
  • Make Artifact Create atomically persist a target-bound lineage_only Content Source, Revision 1, head, and ordinal-zero Source lineage.
  • Define shared Source-generation admission checks so Memory, Experience, Skill, Handoff, Candidate, and commit paths cannot reuse a lineage_only Source for another target.
  • Require Source-window consumers to filter such Sources from model input while still advancing the complete journal cursor, including an all-filtered no-op case.
  • Define opaque ETag semantics, If-Match optimistic concurrency for Replace, and If-None-Match conditional head reads.
  • Map the public fields and internal Source role to the existing persistence model without requiring new metadata-table columns.
  • Keep openapi/powercontext.yaml as the sole source of truth for the HTTP contract.

The RFC intentionally excludes Source List/Search, Artifact Search/Delete, cross-family List, client-writable lineage, Scope APIs, sharing, purge, and bulk mutation.

Are there any user-facing changes?

No runtime behavior changes are included. This PR documents the proposed public API, provenance rules, persistence mapping, compatibility boundaries, and implementation acceptance criteria.

How was this change tested?

  • git diff --check
  • uv run zensical build --clean -s (No issues found)
  • Verified both generated RFC pages exist.
  • Verified the published OpenAPI copy matches openapi/powercontext.yaml.

On macOS, the repository's make docs-test target stops at its GNU-specific install -D invocation. Running the equivalent file copy, strict Zensical build, output checks, and OpenAPI comparison succeeded.

AI usage statement

OpenAI Codex was used to compare the latest Yuque design with the repository RFC conventions, maintain English/Chinese parity, and draft the PR summary. The resulting RFC was reviewed and validated locally.

@Zxf-xufeng
Zxf-xufeng requested review from PsiACE and Teingi September 3, 2026 10:25

@Teingi Teingi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

…ct-rest-api-docs

# Conflicts:
#	zensical.toml
@Zxf-xufeng
Zxf-xufeng merged commit daa948a into master Sep 4, 2026
17 checks passed
@Zxf-xufeng
Zxf-xufeng deleted the codex/source-artifact-rest-api-docs branch September 4, 2026 17:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants