docs(rfc): define source and artifact REST APIs - #1437
Merged
Conversation
…ct-rest-api-docs # Conflicts: # zensical.toml
…ct-rest-api-docs # Conflicts: # zensical.toml
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_idas 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?
contentand Artifact families tomemory,experience,skill, andhandoff.sourcesandartifactsarrays.lineage_onlyContent Source, Revision 1, head, and ordinal-zero Source lineage.lineage_onlySource for another target.If-Matchoptimistic concurrency for Replace, andIf-None-Matchconditional head reads.openapi/powercontext.yamlas 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 --checkuv run zensical build --clean -s(No issues found)openapi/powercontext.yaml.On macOS, the repository's
make docs-testtarget stops at its GNU-specificinstall -Dinvocation. 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.