Repository navigation
Add the entry tools - #2525
Merged
Merged
Add the entry tools#2525
Conversation
pournasserian
added
type:feature
4 tasks done
pournasserian
added a commit
that referenced
this pull request
Oct 19, 2026
Closes #2513 ## What The SCH-05 slice of F-SCH (#2415), on top of change set publish (#2482) and revert (#2511). Every content type write is now a change set operation. A create or a revision stores its new version and records the operation in the change set it names, in one unit of work. Nothing a write does is live until that set publishes. - **Core** (`FluentCMS.Core.ChangeSets`): - `ChangeSetTarget`: the set a write joins, either an existing set by id or a session id with the rationale and sources of the set the session's first write opens (CHG-02). - `ChangeSet.Record(operation)` adds the operation, or extends the one the set already holds for the item. The write must be based on the version that operation proposes, and the operation then proposes the write's version. A create stays a create and an update keeps its base, so a set still has one operation per item (CHG-03) and its diff runs from the base to the newest version. - **Core** (`FluentCMS.Core.Schema`): - `IContentTypeDirectory.CreateAsync` and `ReviseAsync` take a `ChangeSetTarget`. A create records a create proposing version 1, and a revision records an update from its base to the new version. - A revision's base is the latest version or the published one. In a set that already holds the type it is the version that set proposes, so the set can keep revising its own draft after another set drafts the type. Basing it on the published version leaves an unpublished draft behind, such as a rejected one. The referenced-field rule (SCH-04) then also checks the fields of every draft an open set proposes, so such a revision cannot drop a field another draft references. - A revision of a type no set has published, or one a published delete took offline (a rejected or reverted create), records a create, since there is nothing live to update. `ChangeSet.Record` takes whether the item is published, and an agent needs the create scope for such a revision (MCP-05). - A draft is a base only while a set that can still publish proposes it. A revision of a rejected or reverted draft is refused at once with `version_conflict` and points to the published version, instead of failing later at publish. While an open set proposes a draft, the latest or an older one, a revision keeps its referenced fields and its entity flag (SCH-03). A draft whose set went stale still counts until a person rejects it; #2588 tracks that. - References between types are checked against what each type is heading to: every draft an open set proposes, or its published version while there is none. A rejected draft neither drops a live reference nor offers a field to reference, and a field a pending draft removes is no target. A field another type references stays while any of that type's live versions or open drafts references it. - `GetPublishedAsync(slug)` reads the live version, or fails with `content_type_not_published`. `ContentTypeSummary` carries `PublishedVersion`. - **Infrastructure**: - `ChangeSetDirectory` gains an internal join for writes owned by another directory. `PrepareAsync` finds the expected failures before the caller's unit of work begins: unknown set, set not open, blank rationale, agent ownership and the items cap. Inside it, `BeginWriteAsync` opens the set or moves its revision, and `RecordAsync` records the operation after the item's own rows and event. An agent's daily cap is counted in `BeginWriteAsync` with its credential held, as `OpenAsync` does since #2580. It is therefore the one refusal that rolls a caller's unit of work back, and #2513's acceptance now says so. - `content_type.created` and `content_type.revised` now carry the set's id, and come after `change_set.opened` when the write opens its session's set. An extended operation appends `change_set.operation_updated`, the name #2575 uses for the same move of an entry operation. - Both directories share one `ChangeSetDirectory` per scope. - **MCP write tools** (#2514): `create_content_type` and `revise_content_type` pass their target to the directory, which now records the operation itself. `ProposedWrite` no longer opens its own unit of work or checks the set ahead of the write; the directory's checks run before anything is written, so a refused cap still keeps its security event. The answer names the kind the set recorded, so a revision of a type with nothing live reads as a create. In `WriteToolsTests` the agent's revision of the person's unpublished product is now expected as `Create null→2` instead of `Update 1→2`, which is the behaviour change agents see. The entry tools (#2525) keep the tool-level pre-check and add, since entry writes do not join change sets in their directory yet. - No migration: both pointers already exist. ## Why The decision, as written in #2513: `Version` is the latest version, which authoring builds on, and `PublishedVersion` is what is live. The authoring reads stay on the latest version: `GetAsync`, `ListAsync`, the schema document and entry validation. A set can then build on its own drafts, and entries can be written against the schema change they need in the same set (CHG-09). Delivery reads the published version when F-API arrives. Choices worth a look: - **The operation is written by the change set directory, inside the content type directory's unit of work.** Version and operation commit together, and the existing "expected failures before the unit of work" rule still holds for both. - **Extending instead of refusing a second write.** An agent iterating on a type within a session would otherwise need a new set for every revision. - **A unique index at commit** means the slug or version race it always meant. When the write opened a session's set, it may also be a concurrent first write of that session, so that case answers with `change_set_conflict`. - **Two revisions racing into the same set**: the loser now fails with `change_set_conflict`, since the set's revision moved first, rather than `version_conflict`. The race tests give each writer its own set to keep checking the version race. - **Reference checks at write time are best effort.** Sets publish in any order, and a revert can take a field away again, so a reference can still dangle across sets. #2604 checks references at publish, which is where the order is known. It also covers dropping a field together with the last reference to it in one set, which the write-time check still refuses. - **Breaking signature**: every caller of `CreateAsync` and `ReviseAsync` passes a target. In this PR that is the MCP schema tools and tests: the schema, entry and MCP scenarios write their content model in a `content-model` session set, as a person, so agent caps and the change set reads in tests are not affected. - **Answering from the set the write joined**: the schema tools read the session's set again after the write, which can race with a submit; #2615 passes the set out of the write. - **Not in this PR**: entries as change set operations, and refusing at publish an entry whose content type version is not published (F-CNT). Also left out: deleting a content type, the MCP schema tools, the desk's schema review and delivery reading the published schema. ## Tests Unit (Core): - A later write extends the item's operation, keeping its kind and base, for a create and an update. - A later write not based on the proposed version, a delete over an update, and an update over a delete are refused and change nothing. - A write is recorded only while the set is open. Integration, each on SQLite and PostgreSQL: - A create is an operation of its set, with `content_type.created` naming the set. The type lists with no published version and `GetPublishedAsync` refuses it until the set publishes. - A revision in the same set extends the operation (create from nothing to version 2). Its events name the version it was based on, and the diff lists both fields as added. - A revision of a published type into a new set is an update from the published version. It is live only after that set publishes, and the previous version stays readable. - After a rejected draft, a revision based on the published version goes through, while one based on the rejected draft fails with `version_conflict`. - After a rejected create, and after a published create was reverted, the next revision is recorded as a create, and publishing it makes the type live again. - A revision from the published version cannot drop a field that another draft in an open set references. - Writes through a session share the set the first one opens. - An unknown set, a set that is not open and a blank session rationale are refused inside a caller's unit of work, which then commits. - Inside a caller's unit of work, an agent cannot write into another agent's set, and a write past its items cap is refused. Neither stores a content type or change set event, the cap refusal keeps its security event, and the caller's unit of work commits. - A failure injected at either audit append of a revision, after the pointer and the set's revision reached the database, leaves neither the version nor the operation. A caller's unit of work rolled back after the revision's rows were saved leaves neither either. - A rejected draft is refused as a base, while a draft an open set proposes can be built on and publishes after it. - An agent without the create scope cannot revise a type with nothing live. - A revision from the published version keeps an open draft's entity flag, and may drop it once that draft's set is rejected. - A rejected draft of a page does not let its brand drop a field the live page references, and a field only a rejected draft has cannot be referenced. - A field that a pending draft removes cannot be referenced, from the draft's own set or another one. - A field that an older open draft references cannot be removed, even when a later draft of that type is the latest. - A set keeps revising its own draft after another set drafted the type, and a revision of it from the latest version is refused with `version_conflict`. - A revision into a rejected set that holds the type is refused with `change_set_not_open`. - A revision keeps the entity flag of an older open draft when the latest draft was rejected. - A content type write that would open a set past an agent's daily cap is refused, stores no set or type, and keeps one security event. - A session's first write appends the set's opening before the content type's own event. `dotnet build -warnaserror` and the full suite pass locally on SQLite and against a `postgres:17` container. No new package and no new project reference. ## Checklist - [x] Linked to an issue a maintainer has confirmed - [x] Targets `v2` - [x] Tests or docs updated where behaviour changed - [x] No tool-generated co-author trailers or footers
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.
Closes #2523
What
The last F-CNT (#2416) slice: the entry tools agents call over MCP (MCP-01, P1), following the write-tool conventions of #2514.
EntryTools(FluentCMS.Core.Builtin.Tools), discovered like the other built-in providers:list_entries,get_entry(latest draft or a named version, with state and pointers),get_entry_history,get_resolved_entry(entity-field references replaced by published values, plus what could not be resolved) andget_where_used(an entry, one entity field withfield, or a media asset withasset_id).create_entry,update_entryanddelete_entry. The new version, if any, and its operation commit together into a set named bychange_set_idor a session's set (ChangeSetTarget), ascreate_content_typedoes, so a refused add stores no version. The operation is an entity operation for an entity type.delete_entryproposes unpublishing, and an entry that is not published is refused with the newentry_not_published.get_entryafter a version conflict,get_schema_documentfor invalid fields,list_entriesfor a missing entry or a bad reference, andlist_content_typesfor an unknown type.ToolJsonrenders entries, summaries, history, resolved views and usages; states and reasons are snake_case like the rest.McpCoverageTestslists the tools,EntryToolsConformanceTestscovers the provider, and the MCP test session (ConnectedAgent) moved out ofWriteToolsTestsso both test classes share it, with a narrower scope where a test needs one.Why
P1 has every capability as a tool before it is a screen. These are the entry half of the reference scenario: an agent writes a product and a page that shows its price, and a person reviews and publishes them.
Choices worth a look:
ProposedWrite's shape, kept insideEntryToolsand not merged with the schema one, because SCH-05 is about to move the change set target into the directories. Entries follow that change when it lands.Tests
Unit (Core):
EntryToolsConformanceTests: names, descriptions, input schemas with examples, unknown arguments refused.McpCoverageTests: the new tools are registered, listed, and none approves or publishes.Integration over MCP, each on SQLite and PostgreSQL:
product.priceis used, and lists, reads and pages through the history.delete_entryrefuses an unpublished entry and proposes unpublishing a published one.get_where_usedwithout a target is refused.The full suite ran locally against a
postgres:17container as well as SQLite. No migration, no new package and no new project reference.Checklist
v2