feat(api): implement source and artifact base REST APIs by Zxf-xufeng · Pull Request #1438 · oceanbase/powercontext

Zxf-xufeng · 2026-09-02T17:06:00Z

Which issue or RFC does this PR close?

Implements RFC #1437.

Scope creation, retrieval, and binding remain covered by #1401.

Rationale for this change

RFC #1437 defines a consistent base HTTP API for directly accessing durable Sources and committed Artifacts below an existing Scope.

This change implements that contract across the OpenAPI specification, server, persistence layer, Python client, and integration clients. It keeps Source creation independent from downstream generation and preserves the existing domain-specific Memory, Candidate review, Skill, and Handoff workflows.

What changes are included in this PR?

Add nine Scope-qualified HTTP operations for Source and Artifact access.
Implement Source:
Create with a server-generated source_id
Get by (scope_id, source_type, source_id)
List or Search a Source type collection through one collection GET
Implement Artifact:
Create Revision 1 with a server-generated artifact_id
Get the current head
Get an immutable historical revision
List or Search an Artifact family collection through one collection GET
Replace the current head by creating the next immutable revision
Logically delete the current head
Add pagination and opaque cursors bound to the collection and query parameters.
Return summary items without full content from collection operations.
Add Location, ETag, If-Match, and If-None-Match behavior for creation, optimistic concurrency, and conditional reads.
Keep Source creation independent from Memory, Experience, Skill, Handoff, and other generation commands.
Enforce Artifact Family capabilities so generic writes cannot bypass Candidate review or other protected workflows.
Reuse the existing Source journal, Artifact revision/head, and lineage tables rather than creating a second persistence model.
Add the persistence fields required by the RFC:
pc_sources.created_at
pc_artifacts.created_at
pc_artifact_heads.deleted_at
Update openapi/powercontext.yaml and regenerate the checked-in Python models, operations, and schema.
Update the Python client and the DSH, OpenCode, and Pi integration clients.
Add contract, generation, persistence, client, integration, and end-to-end coverage.

Are there any user-facing changes?

Yes. This is an additive API change.

The new endpoints expose:

Source Create, Get, List, and Search.
Artifact Create, Get, Get Revision, List, Search, Replace, and Delete.
Server-generated Source and Artifact identifiers.
Immutable Artifact revisions and optimistic concurrency through ETags.
Logical Artifact deletion while retaining historical revisions.

List and Search share the same collection endpoints: an omitted or blank query performs List, while a non-empty query performs Search.

Existing domain-specific APIs and workflows remain available and are not replaced by these base APIs. No existing public endpoint is removed or changed.

How was this change tested?

make check
make contract-test
make api-generate-check
make js-api-generate-check
make test (1047 passed, 12 skipped)
DSH plugin tests, build, and generation checks
OpenCode plugin tests and type checking
Pi plugin tests and type checking
Strict Zensical documentation build
git diff --check
GitHub Actions across Python 3.11, 3.12, 3.13, and 3.14
SQLite and OceanBase acceptance suites

AI usage statement

OpenAI Codex was used to update the cross-layer contract and generated clients, add regression coverage, review implementation risks, and draft the PR description.

Teingi · 2026-09-03T10:49:39Z

resolve conflicts

frf12

Please see the inline comments.

frf12 · 2026-09-03T16:27:59Z

+                artifacts=current.lineage.artifacts,
+            )
+            try:
+                revised = await self._artifacts.revise(connection, scope_id, current, draft)


Each Revision created by this management API should reference a server-owned lineage_only Source that records the direct write. The Revision 1 Source is filtered above, but Replace does not create a replacement Source, so Revision 2 can return sources: []. Please create a Source bound to the next Revision and commit it in the same transaction as revise().

Agreed. We will update Replace so that every Revision created through this management API has its own server-owned lineage_only Source recording the direct write.
For the next Revision N, Replace will:

create a new Source with role=lineage_only, operation=artifact_replace, and a target bound to (scope_id, family, artifact_id, revision=N);

use that new Source as the Source lineage of Revision N;

preserve the previous Revision and its Source unchanged;

inherit the previous Artifact lineage for now;

commit the Source, new Artifact Revision, head update, and lineage rows in the same transaction.

frf12 · 2026-09-03T16:27:59Z

+            async with self._database.transaction() as connection:
+                stored = await self._sources.add(connection, scope_id, source)
+                draft = draft.model_copy(update={"sources": (stored.ref,)})
+                artifact = await self._artifacts.create(


This path validates the Family content model and writes directly through ArtifactRepository, but it does not perform the complete Family write behavior. It skips Memory entry versions and projections, Handoff citation validation and fixed identity, Experience Search updates, and Skill package validation and Search updates. Please dispatch Create and Replace through Family-specific write handlers while retaining the direct management API behavior.

Thanks — fixed. The Base Artifact API now dispatches Create/Replace through a FamilyManagementWriter registry:

Memory reuses MemoryService, maintaining Entry Versions/heads, changes and search projections.

Experience and Skill maintain their existing search/package projections.

Handoff reuses HandoffService, including singleton enforcement and citation lineage.
The lineage-only Source, Artifact Revision and Family-derived state are committed in one transaction and roll back together on failure. No LLM generation or Candidate workflow is triggered. Regression tests and all PR checks pass.

frf12 · 2026-09-03T16:27:59Z

+            name=self._id_factory("source"),
+            materialization=SourceMaterialization.CAPTURED,
+            content=_canonical_source_text(content),
+            wire_content=None if isinstance(content, str) else _JSON_VALUE.validate_python(content, strict=True),


wire_content=None represents both a plain string Source and JSON null. As a result, content: null is stored and returned as the JSON string "null". Please preserve the distinction between an absent wire_content value and an explicit JSON null.

I’ll add an explicit persisted presence discriminator for wire_content, keep missing values backward-compatible with existing text Sources, and update response/digest mapping to use it. Regression tests will cover JSON null, the string "null", persistence round-trips, and HTTP responses.

frf12 · 2026-09-03T16:28:00Z

+            selected_rows = rows[:limit]
+            items = []
+            for row in selected_rows:
+                artifact = await self._artifacts.get(


This loop performs a separate Artifact and Source/Artifact reference read for every item after loading the heads. A 100-item page therefore produces many database queries, while RFC #1437 requires the response data to be read in batches. Please batch-load the selected Revisions and their sources and artifacts.

Agreed. The current implementation is an N+1 path: after loading the heads, each item performs one Revision query and two lineage queries.
I’ll add a repository-level batch loader keyed by the complete Revision identity, batch-load Source and Artifact lineage, and assemble results in page and ordinal order. The list path will then use a bounded constant number of queries. I’ll add ordering, lineage, pagination, and query-budget regression tests.

frf12 · 2026-09-03T16:28:00Z

+        self._artifacts = artifacts
+        self._clock = _utc_now if clock is None else clock
+        self._id_factory = _resource_id if id_factory is None else id_factory
+        self._cursor_secret = secrets.token_bytes(32) if cursor_secret is None else cursor_secret


This default creates a new cursor_secret whenever the Runtime starts. A cursor issued before a server restart therefore becomes invalid before its recorded expiration time. Please provide a stable configured secret, or define server restart as part of the cursor validity contract.

Teingi · 2026-09-04T06:00:04Z

resolve conflicts

…ct-rest-api-implementation # Conflicts: # integrations/dsh/plugins/powercontext/lib/index.js # integrations/dsh/plugins/powercontext/openapi/powercontext.yaml # integrations/dsh/plugins/powercontext/scripts/openapi-ops.mjs # integrations/dsh/plugins/powercontext/src/client.ts # integrations/dsh/plugins/powercontext/src/operations.generated.ts # integrations/dsh/plugins/powercontext/tests/client.spec.ts # integrations/dsh/plugins/powercontext/tests/operations-coverage.spec.ts # integrations/opencode/plugins/powercontext/lib/index.js # integrations/opencode/plugins/powercontext/src/client.ts # integrations/opencode/plugins/powercontext/src/operations.generated.ts # integrations/pi/plugins/powercontext/src/client.ts # integrations/pi/plugins/powercontext/src/operations.generated.ts # openapi/powercontext.yaml # scripts/generate_api.py # scripts/generate_js_operations.py # src/powercontext/builtin/runtime/application.py # src/powercontext/builtin/runtime/relational.py # src/powercontext/client/client.py # src/powercontext/http/__init__.py # src/powercontext/http/_generated/operations.py # src/powercontext/server/app.py # tests/e2e/test_builtin_runtime.py # tests/test_api_contract.py # tests/test_client.py # tests/test_js_operations.py

…ct-rest-api-implementation

Teingi

LGTM

Zxf-xufeng added 3 commits September 2, 2026 10:56

feat(api): add source and artifact access

596e99f

Merge branch 'master' into codex/source-artifact-rest-api-implementation

f35b67a

feat(api): align source and artifact access with RFC

d0b21c0

Zxf-xufeng changed the title ~~feat(api): add source and artifact access~~ feat(api): implement source and artifact base REST APIs Sep 2, 2026

Zxf-xufeng added 2 commits September 3, 2026 17:36

feat(api): implement latest source and artifact RFC

c859468

fix(api): validate artifact family content as JSON

edd44c4

Zxf-xufeng requested review from PsiACE, Teingi and frf12 September 3, 2026 10:47

Merge origin/master into codex/source-artifact-rest-api-implementation

e5006f7

frf12 reviewed Sep 3, 2026

View reviewed changes

fix(api): align artifact revision source semantics

c764d64

This was referenced Sep 4, 2026

bug(dsh): handle Scope failures at tool and command boundaries #1451

Open

fix(dsh): handle Scope failures at tool and command boundaries #1452

Open

Zxf-xufeng added 4 commits September 4, 2026 16:42

fix(api): reuse family artifact write flows

0153496

Merge remote-tracking branch 'origin/master' into codex/source-artifa…

f669836

…ct-rest-api-implementation

fix(ci): sync base API generated artifacts

20cb679

knqiufan mentioned this pull request Sep 4, 2026

bug(dsh): complete automatic-path diagnostics and recall presentation #1457

Open

1 task

test(cli): follow current config validation path

d7eb3d3

Zxf-xufeng mentioned this pull request Sep 4, 2026

feat(generation): standardize source access #1461

Draft

Teingi approved these changes Sep 4, 2026

View reviewed changes

Teingi merged commit fc75f92 into master Sep 4, 2026
17 checks passed

Uh oh!

Conversation

Zxf-xufeng commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Which issue or RFC does this PR close?

Rationale for this change

What changes are included in this PR?

Are there any user-facing changes?

How was this change tested?

AI usage statement

Uh oh!

Teingi commented Sep 3, 2026

Uh oh!

frf12 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Teingi commented Sep 4, 2026

Uh oh!

Teingi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Zxf-xufeng commented Sep 2, 2026 •

edited

Loading