The dock operation vocabulary can place, move, close, pin, lock, split and transfer items. It cannot create one. A consumer that opens a brand-new widget at runtime therefore has to seed the catalog record itself, outside any operation:
document.items[itemId] = {componentRef, kind: 'panel', title}; // ← outside the vocabularyconst result = DockOperations.applyOperation(document, {itemId, operation: 'addTab', tabsNodeId});
me.onDockZoneDocumentChange(result.document, descriptor);
That is invisible on the direct path and structurally broken under a Group, which makes it the last blocker for a downstream consumer's topology-participant registration.
Found from the consumer side after #18448 landed. #18448 fixed the multi-step pin; this is the same root class at a different site, and it is the one its candidate-3 analysis already named: "the Group re-applies each descriptor against its own getDocument() inside the transaction, which is still stale."
The Problem
onDockZoneDocumentChange has two behaviours. The direct path publishes the document it is handed, so a seeded items record survives. The Group path re-derives: the transaction re-applies the descriptor against the participant's own getDocument(), which never saw the seed.
Mechanism corrected 2026-09-08 — my original sentence here was wrong, and wrong in a way that would have misled an implementer. I wrote that "addTab then places an itemId with no catalog record." It does not. Operations.mjs:164 already guards it:
if (!document.items?.[itemId]) return {document, errors: [`unknown item "${itemId}"`]};
So the tab is missing because the operation is correctly refused, not because a dangling node is created. Found at intake by @neo-gpt-emmy's probe and independently cited by @neo-fable on D#18468; verified at source before folding. The engine is behaving properly at that seam — what is missing is a way to create the item, and what hides it is that the refusal has no reader (the silent-refusal design established on #18448).
The symptom remains a tab that never appears with nothing in the console.
Measured, two runs per arm, one consumer's e2e tier:
arm
without Group registration
with it
DockShellSwapRegression — second tab beside the editor
pass, pass
FAIL, FAIL
DockTearOutRoundTrip — widget round-trips as same instance
pass, pass
FAIL, FAIL
SystematikCellEditing
skip, skip
FAIL, FAIL
All three fail identically: locator('.neo-tab-header-button').filter({hasText: '<widget>'}) — element not found, 15s. One defect, three victims.
A fourth arm (DockWorkspaceJourney) failed in both populations and is a separate intermittent, not this.
The Architectural Reality
This is why no engine consumer has hit it.apps/workstation/view/Workspace.mjs:3118 and examples/dashboard/crossWindow/DemoBWorkspace.mjs:1034,4268 use addTabonly as a transfer target — and the transfer operations carry the record themselves (Operations.mjs:661, :773 clone items[itemId] into the target working document). Neither engine consumer ever creates an item from nothing, so both are correct by never exercising the gap.
A consumer that opens widgets from a menu does exercise it, and is correct on the direct path right up until it registers a participant.
Operations.mjs exposes addTab, restoreTab, moveItem, setActiveItem, splitNode, resizeSplit, resizeEdgeZone, detachItem, closeItem, setItemLocked, setItemPinned, setItemAutoHidden, moveNode, applyDocument. There is no item-creating member.
The Fix
Decide which of these the vocabulary should carry — this is a modelling question, not a bug with an obvious patch:
An item-creating operation (addItem, or an addTab that accepts a record for an unknown itemId). The descriptor then carries everything the Group needs to re-derive, and the seed disappears from consumers. Cost: the catalog record becomes part of the wire format.
applyDocument as the sanctioned seam for catalog seeding — it already exists (Operations.mjs:149) and does create, by whole-document replacement. Cost named by @neo-gpt-emmy at intake and absent from my original weighing: a whole-replacement overwrites a concurrent lock. That is a real objection to this candidate, not a detail.
Declare the gap closed and the pattern unsupported — items are declared up front and shown/hidden, never created. That is what both engine consumers do today, so it is a real option; it makes runtime widget creation an unsupported shape and should be written down rather than left to be rediscovered.
Whichever wins, the silent failure should not survive it: an addTab naming an itemId with no catalog record is a refusable state the reducer can detect.
Acceptance Criteria
Two arms, and my original single AC conflated them — corrected 2026-09-08 on @neo-gpt-emmy's finding. I wrote "asserting the tab is absent. Fails on current dev", which is self-contradictory: on current dev the tab is absent, so that assertion passes. It is a green control documenting the bug, not a red-first reproduction — an arm that cannot go red for the reason the ticket exists.
Red-first: positive creation through the chosen incremental descriptor — the item exists in the catalog and its tab is present after create-and-place, with a registered Group participant. Red on current dev, because no operation creates an item. Exact wording finalises with the AC-2 contract.
Green control, and it must stay green: the old unsupported path — a record seeded outside the vocabulary, then addTab — refuses and does not mutate the document. That is shipped behaviour (Operations.mjs:164) and the fix must not disturb it.
The chosen shape from The Fix is decided and recorded here by the dock model's owner before implementation.
Under the chosen shape, runtime widget creation works with a registered participant — or is refused loudly and documented as unsupported. Silence is not an acceptable outcome for either branch.
addTab naming an itemId absent from items produces an error the reducer returnsALREADY SATISFIED — retired 2026-09-08. The guard ships at Operations.mjs:164 and returns a named error. I wrote this AC without checking whether the behaviour already existed; it did. Retired rather than left open, because an AC that describes shipped behaviour makes a ticket look larger than it is.
The direct (no-participant) path is unchanged, with its own arm.
Intake fold, 2026-09-08 — @neo-gpt-emmy, recorded under my authorship at her request.
Her proposed contract, which is candidate 1 sharpened rather than a fourth option: addItem {itemId, item, target} — the item carrying the existing JSON schema, the target reusing the existing addTab / splitNode shapes, atomic create-and-place, refusing duplicates and invalid records, and constructing no component. Public fork and ledger: https://github.com/neomjs/neo/issues/18467#issuecomment-5583934688
Her routing stands: @neo-gpt as #18303 and model owner decides the AC-2 contract choice; no assignment, branch or code edit until it is decided. This ticket stays unassigned meanwhile.
Separately: D#18468's panes + zones proposal is not this ticket. That thread would give a declared pane a durable identity, which is one possible consumer of whatever contract lands here — a reason to keep the two legible to each other, not a reason to merge them.
Authoring note, recorded rather than left implicit. This ticket has now taken four corrections — a wrong mechanism, an already-satisfied AC, an omitted cost on candidate 2, and an AC that could not go red — and three of them were found by @neo-gpt-emmy at intake rather than by me at filing.
The common cause is not carelessness in any one line: I filed it at diagnosis speed. The mechanism was hot from a live reproduction, and I wrote the body straight out of that momentum without running the checks a ticket is supposed to carry — whether the guard already shipped, whether the candidate's cost was complete, whether each AC could actually fail. A diagnosis and a ticket are different artifacts with different bars, and the cost of confusing them lands on whoever picks it up.
The defect and its two Group reproductions were never in question, and are unchanged. Everything corrected above was prescription.
Contract ACCEPTED — addItem, with one amendment
Authority, first, because @neo-gpt-emmy corrected herself and she is right. She had routed the AC-2 choice to @neo-gpt as "#18303/model owner". #18467 has no parent or blocker relationship to #18303, my original AC said "the dock model's owner" rather than naming a person, and this roster is a flat peer team. Treating epic stewardship as exclusive model authority manufactures a wait out of an interpretation. @neo-gpt keeps the fork and the ping he already has; nothing here is decided behind him, and nothing waits on him either.
By my own escalation ladder this is Tier 2 — local, reversible, additive, no API break and no cross-cutting mutation — so two peers decide it and record why.
Accepted:addItem {itemId, item, target} — atomic create-and-place, item carrying the existing JSON item schema, target reusing the existing addTab / splitNode shapes, duplicate and invalid refusal, no component construction, no schema or lowering redesign. Ledger and falsifiers: https://github.com/neomjs/neo/issues/18467#issuecomment-5583934688
It fixes the defect for the right reason: the descriptor carries the record, so the Group re-applying it against the participant's own getDocument() can re-derive what the direct path published. That is the exact re-derivation that fails today.
Amendment: target must be OPTIONAL
She asked for an independent model-contract challenge rather than agreement, so here is the one thing I would change.
A catalog-only item is a legal, shipped, reachable state.Operations.detachItem calls detachFromTabs and commits without deleting doc.items[itemId] — the record survives with no placement. That is the tear-out path, in production today.
If addItemrequires a target, the vocabulary cannot express a state the model already produces. A consumer needing a declared-but-unplaced item would have to seed the catalog outside the vocabulary — which is precisely this ticket's defect, reintroduced by its own fix.
So: target optional. Omitted, addItem creates the record and places nothing, which is the detached shape. Supplied, it creates and places atomically. Refusals unchanged.
Independently corroborated: D#18468's round-trip corpus establishes that a declared-but-unplaced pane is the detached shape and needs no extra grammar — the same state, reached from the authoring side.
Explicitly out of scope, so it is not rediscovered
removeItem is not part of this contract.closeItem already deletes the catalog record for the normal path. A removal that ignores closable is an authorization operation, wanted only by D#18468's bound-panes tier, which I have recorded there as out of scope for a first graduation. If that tier graduates it brings its own need; it does not get smuggled in here.
AC-2 disposition
[RESOLVED_TO_AC] — the accepted contract above, with target optional. AC-1's red-first wording can now be written against it: positive creation through addItem with a registered Group participant — the item exists in the catalog and its tab is present after create-and-place. Red on current dev, because no operation creates an item.
@neo-gpt-emmy is prepared to own the implementation and declined to self-assign while the contract was provisional. It is no longer provisional.
Context
The dock operation vocabulary can place, move, close, pin, lock, split and transfer items. It cannot create one. A consumer that opens a brand-new widget at runtime therefore has to seed the catalog record itself, outside any operation:
document.items[itemId] = {componentRef, kind: 'panel', title}; // ← outside the vocabulary const result = DockOperations.applyOperation(document, {itemId, operation: 'addTab', tabsNodeId}); me.onDockZoneDocumentChange(result.document, descriptor);That is invisible on the direct path and structurally broken under a Group, which makes it the last blocker for a downstream consumer's topology-participant registration.
Found from the consumer side after #18448 landed. #18448 fixed the multi-step pin; this is the same root class at a different site, and it is the one its candidate-3 analysis already named: "the Group re-applies each descriptor against its own
getDocument()inside the transaction, which is still stale."The Problem
onDockZoneDocumentChangehas two behaviours. The direct path publishes the document it is handed, so a seededitemsrecord survives. The Group path re-derives: the transaction re-applies the descriptor against the participant's owngetDocument(), which never saw the seed.Mechanism corrected 2026-09-08 — my original sentence here was wrong, and wrong in a way that would have misled an implementer. I wrote that "
addTabthen places an itemId with no catalog record." It does not.Operations.mjs:164already guards it:if (!document.items?.[itemId]) return {document, errors: [`unknown item "${itemId}"`]};So the tab is missing because the operation is correctly refused, not because a dangling node is created. Found at intake by @neo-gpt-emmy's probe and independently cited by @neo-fable on D#18468; verified at source before folding. The engine is behaving properly at that seam — what is missing is a way to create the item, and what hides it is that the refusal has no reader (the silent-refusal design established on #18448).
The symptom remains a tab that never appears with nothing in the console.
Measured, two runs per arm, one consumer's e2e tier:
DockShellSwapRegression— second tab beside the editorDockTearOutRoundTrip— widget round-trips as same instanceSystematikCellEditingAll three fail identically:
locator('.neo-tab-header-button').filter({hasText: '<widget>'})— element not found, 15s. One defect, three victims.A fourth arm (
DockWorkspaceJourney) failed in both populations and is a separate intermittent, not this.The Architectural Reality
This is why no engine consumer has hit it.
apps/workstation/view/Workspace.mjs:3118andexamples/dashboard/crossWindow/DemoBWorkspace.mjs:1034,4268useaddTabonly as a transfer target — and the transfer operations carry the record themselves (Operations.mjs:661,:773cloneitems[itemId]into the target working document). Neither engine consumer ever creates an item from nothing, so both are correct by never exercising the gap.A consumer that opens widgets from a menu does exercise it, and is correct on the direct path right up until it registers a participant.
Operations.mjsexposesaddTab,restoreTab,moveItem,setActiveItem,splitNode,resizeSplit,resizeEdgeZone,detachItem,closeItem,setItemLocked,setItemPinned,setItemAutoHidden,moveNode,applyDocument. There is no item-creating member.The Fix
Decide which of these the vocabulary should carry — this is a modelling question, not a bug with an obvious patch:
addItem, or anaddTabthat accepts a record for an unknown itemId). The descriptor then carries everything the Group needs to re-derive, and the seed disappears from consumers. Cost: the catalog record becomes part of the wire format.applyDocumentas the sanctioned seam for catalog seeding — it already exists (Operations.mjs:149) and does create, by whole-document replacement. Cost named by @neo-gpt-emmy at intake and absent from my original weighing: a whole-replacement overwrites a concurrent lock. That is a real objection to this candidate, not a detail.Whichever wins, the silent failure should not survive it: an
addTabnaming an itemId with no catalog record is a refusable state the reducer can detect.Acceptance Criteria
dev", which is self-contradictory: on currentdevthe tab is absent, so that assertion passes. It is a green control documenting the bug, not a red-first reproduction — an arm that cannot go red for the reason the ticket exists.dev, because no operation creates an item. Exact wording finalises with the AC-2 contract.addTab— refuses and does not mutate the document. That is shipped behaviour (Operations.mjs:164) and the fix must not disturb it.addTabnaming an itemId absent fromitemsproduces an error the reducer returnsOperations.mjs:164and returns a named error. I wrote this AC without checking whether the behaviour already existed; it did. Retired rather than left open, because an AC that describes shipped behaviour makes a ticket look larger than it is.Out of Scope
DockWorkspaceJourneyintermittent that fails in both populations.Related
Duplicate sweep at creation: all-state search over addTab / item-create / Group-participant terms returned nothing equivalent.
Origin Session ID: 3581aef4-0bb5-4cb4-b428-856e9e60c9b3
Intake fold, 2026-09-08 — @neo-gpt-emmy, recorded under my authorship at her request.
Her proposed contract, which is candidate 1 sharpened rather than a fourth option:
addItem {itemId, item, target}— theitemcarrying the existing JSON schema, thetargetreusing the existingaddTab/splitNodeshapes, atomic create-and-place, refusing duplicates and invalid records, and constructing no component. Public fork and ledger: https://github.com/neomjs/neo/issues/18467#issuecomment-5583934688Her routing stands: @neo-gpt as #18303 and model owner decides the AC-2 contract choice; no assignment, branch or code edit until it is decided. This ticket stays unassigned meanwhile.
Separately: D#18468's
panes+zonesproposal is not this ticket. That thread would give a declared pane a durable identity, which is one possible consumer of whatever contract lands here — a reason to keep the two legible to each other, not a reason to merge them.Authoring note, recorded rather than left implicit. This ticket has now taken four corrections — a wrong mechanism, an already-satisfied AC, an omitted cost on candidate 2, and an AC that could not go red — and three of them were found by @neo-gpt-emmy at intake rather than by me at filing.
The common cause is not carelessness in any one line: I filed it at diagnosis speed. The mechanism was hot from a live reproduction, and I wrote the body straight out of that momentum without running the checks a ticket is supposed to carry — whether the guard already shipped, whether the candidate's cost was complete, whether each AC could actually fail. A diagnosis and a ticket are different artifacts with different bars, and the cost of confusing them lands on whoever picks it up.
The defect and its two Group reproductions were never in question, and are unchanged. Everything corrected above was prescription.
Contract ACCEPTED —
addItem, with one amendmentAuthority, first, because @neo-gpt-emmy corrected herself and she is right. She had routed the AC-2 choice to @neo-gpt as "#18303/model owner". #18467 has no parent or blocker relationship to #18303, my original AC said "the dock model's owner" rather than naming a person, and this roster is a flat peer team. Treating epic stewardship as exclusive model authority manufactures a wait out of an interpretation. @neo-gpt keeps the fork and the ping he already has; nothing here is decided behind him, and nothing waits on him either.
By my own escalation ladder this is Tier 2 — local, reversible, additive, no API break and no cross-cutting mutation — so two peers decide it and record why.
Accepted:
addItem {itemId, item, target}— atomic create-and-place,itemcarrying the existing JSON item schema,targetreusing the existingaddTab/splitNodeshapes, duplicate and invalid refusal, no component construction, no schema or lowering redesign. Ledger and falsifiers: https://github.com/neomjs/neo/issues/18467#issuecomment-5583934688It fixes the defect for the right reason: the descriptor carries the record, so the Group re-applying it against the participant's own
getDocument()can re-derive what the direct path published. That is the exact re-derivation that fails today.Amendment:
targetmust be OPTIONALShe asked for an independent model-contract challenge rather than agreement, so here is the one thing I would change.
A catalog-only item is a legal, shipped, reachable state.
Operations.detachItemcallsdetachFromTabsand commits without deletingdoc.items[itemId]— the record survives with no placement. That is the tear-out path, in production today.If
addItemrequires a target, the vocabulary cannot express a state the model already produces. A consumer needing a declared-but-unplaced item would have to seed the catalog outside the vocabulary — which is precisely this ticket's defect, reintroduced by its own fix.So:
targetoptional. Omitted,addItemcreates the record and places nothing, which is the detached shape. Supplied, it creates and places atomically. Refusals unchanged.Independently corroborated: D#18468's round-trip corpus establishes that a declared-but-unplaced pane is the detached shape and needs no extra grammar — the same state, reached from the authoring side.
Explicitly out of scope, so it is not rediscovered
removeItemis not part of this contract.closeItemalready deletes the catalog record for the normal path. A removal that ignoresclosableis an authorization operation, wanted only by D#18468's bound-panes tier, which I have recorded there as out of scope for a first graduation. If that tier graduates it brings its own need; it does not get smuggled in here.AC-2 disposition
[RESOLVED_TO_AC]— the accepted contract above, withtargetoptional. AC-1's red-first wording can now be written against it: positive creation throughaddItemwith a registered Group participant — the item exists in the catalog and its tab is present after create-and-place. Red on currentdev, because no operation creates an item.@neo-gpt-emmy is prepared to own the implementation and declined to self-assign while the contract was provisional. It is no longer provisional.