docs(rfc): define unified artifact tags - #1467
Conversation
| One table cannot express conditional foreign keys to both `pc_artifact_heads` and `pc_memory_entry_heads`. The owning | ||
| Artifact foreign key is enforced for every row. For `memory_entry`, the repository must additionally lock and validate | ||
| the current `(scope_id, memory_artifact_id, entry_id)` head in the same transaction before changing assignments. The | ||
| transaction rejects a missing entry. This is an explicit application invariant, not a best-effort cleanup rule. |
There was a problem hiding this comment.
[P2] Validate entry existence against the current manifest
pc_memory_entry_heads only contains active search projections. I verified on this commit with SQLite that forget() removes the entry's head row while the entry remains readable in the current manifest; rebuilding projections does not restore that row. Requiring it here would therefore reject tag replacements for inactive entries, contradicting the following paragraph's promise that their tags can be reorganized without reactivation.
Please lock the owning Artifact head and validate entry_id against that Revision's authoritative manifest. The inactive-query path should also resolve citations from the manifest. Update both language versions and add an acceptance case for reading, replacing, and clearing tags after deactivation.
There was a problem hiding this comment.
Fixed in b962344. Both RFCs now require locking the owning Artifact head and validating entry_id against that Revision's authoritative manifest, accepting both active and inactive entries. Tag reads and mutations do not require a pc_memory_entry_heads row.
Inactive tag queries and entry listing resolve state and citations from the same manifest before pagination. The RFC acceptance criteria now cover reading, replacing, and clearing tags after deactivation, preserving assignments through projection rebuilds, and rejecting targets absent from the current manifest. The single-table design is unchanged.
Validation: document hooks, bilingual JSON examples and local links, and make docs-test passed. I also independently reproduced the deactivation and projection-rebuild behavior with SQLite on the reviewed commit.
Which issue or RFC does this PR close?
Closes #1466.
Rationale for this change
Users need stable custom labels for organizing and retrieving Memory, Experience, Skill, and Handoff content without
editing immutable Artifact revisions or overloading behavior-bearing metadata. Memory entries also need independent
labels even though the standard profile stores them inside one Memory Artifact per Scope.
What changes are included in this PR?
pc_artifact_tagsassignment table for whole Artifacts and logical Memory entries.all/anyfiltering, target identity, concurrency, authorization, publication,migration, and observability semantics.
conventions.
This PR contains design documentation only. It does not change the current API or persisted schema.
Are there any user-facing changes?
No runtime behavior changes in this PR. If implemented, the RFC introduces additive tag APIs and optional list/search
filters. The design declares no breaking change and requires existing unfiltered behavior and historical responses to
remain unchanged.
How was this change tested?
make docs-testwith Node.js 22.22.3: passed, including lint, 545-page static generation, and export verification.git diff --cached --check: passed.The repository-wide
ty checkcurrently reports three pre-existing unresolvedscripts.scope_bindingimports inCodex integration hooks; this documentation-only change does not modify those files.
AI usage statement
OpenAI Codex (GPT-5) was used to inspect existing contracts, draft the bilingual RFC, and run validation. The author
reviewed the final design and delivery.