docs(spec,metadata-protocol): the code is the record for platform agent definitions (#4507) - #4512
Merged
Conversation
…ent` definitions (#4507) `agent` is the only authorable type with no governed write path — ADR-0063 §2 closes `*.agent.ts` to third parties, so both `allowOrgOverride` and `allowRuntimeCreate` are false and nothing reaches `saveMetaItem`. Its rows are written by the shipping plugin at boot (`AIStudioPlugin.registerMeta` → `metadataService.register()` → `MetadataManager.register` → `DatabaseLoader.save`), which writes `sys_metadata` directly with a fresh checksum and appends no `sys_metadata_history` row. A shipped agent definition that changes between releases therefore leaves no metadata-side change log. That is a deliberate position, and it now sits beside the declaration rather than only in an issue: the two definitions live in version control (`@objectstack/service-ai-studio`, `cloud` repo), so git already holds the full reviewable history, and a second history in `sys_metadata` would be a WORSE record — it would capture only the boots where a given deployment saw the checksum move, so two deployments on one release would carry different "histories" of an identical, code-fixed definition. The note names the two consequences that read as bugs and are not: the `skipped` outcome `os migrate meta --stored` reports for `agent` is correct and permanent for this type, and Studio showing no History tab is the absence of anything to show. `migrateStoredMetadata`'s TSDoc — where the skip reason was what made this look like a gap — now points at it. It also states its own expiry: opening `agent` to tenant authoring removes the git fallback, so opening the type and giving it a real history path are the same piece of work. Comment-only; empty changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WoZPKPDqJ7WB7z84xk9y3f
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
August 1, 2026 14:13
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 107 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
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
2 participants
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.
Closes #4507. Comment-only — no behaviour changes, empty changeset.
Why
#4507 started as "the
agenttype has no change log — fix the write path." Checking it out produced the opposite conclusion, so this PR writes the conclusion down where the next person will hit it instead of leaving it in a closed issue.agentis the only authorable metadata type with no governed write path.packages/spec/src/kernel/metadata-plugin.zod.tsalready explained the flags:What it did not explain is the consequence. Because both
allowOrgOverrideandallowRuntimeCreatearefalse,saveMetaItemwould route an agent down the legacy raw-engine branch — and nothing calls it. The rows are written instead by the shipping plugin at boot:DatabaseLoader.savewrites thesys_metadatarow directly with a freshchecksumand appends nosys_metadata_historyrow. So a shipped agent definition that changes between releases leaves no metadata-side change log and has no metadata-side rollback. The plugin's own log line is the tell:refreshed (shipped definition changed).The position, now recorded
That is accepted, not overlooked, and the note says why in a way that should survive re-discovery:
@objectstack/service-ai-studioin thecloudrepo (agents/ask-agent.ts,agents/metadata-assistant-agent.ts). Git already holds the full, reviewable history of every change.sys_metadatawould be a worse record, not a better one. It would capture only the boots where a given deployment happened to see the checksum move — so two deployments on the same release would carry different "histories" of an identical, code-fixed definition. The note says explicitly: do not add one to close a perceived gap.It also names the two consequences that look like bugs and are not:
os migrate meta --storedreportsagentrowsskippedcloudcommit logAnd it states its own expiry: if
agentis ever opened to tenant authoring, an author-owned definition has no git to fall back on — so opening the type and giving it a real history path become the same piece of work.Second edit
migrateStoredMetadata's TSDoc is where this looked like a gap in the first place — its skip reason reads as a to-do. It now points at the note beside the declaration, so the migration's refusal is read as a design decision rather than an unfinished branch.Verification
Comment-only.
packages/specrebuilt with no generated-artifact drift (the change lives in a comment inside the type-registry array literal, so nothing propagates to the 8 generated artifacts). Spec kernel suite green (33 files / 689 tests),eslintclean on both files,check:doc-authoringandcheck:slot-lookuppass.Empty-frontmatter changeset — the sanctioned "this PR releases nothing" declaration.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WoZPKPDqJ7WB7z84xk9y3f
Generated by Claude Code