Co-work Folder Setup Boundary

The read-only proof that a selected folder is the only Co-work folder on its line of descent, and the explicit all-or-nothing setup that writes only after that proof holds.

Details

Co-work folder setup

Setting a folder up for Co-work writes .wbuddy/manifest.yaml and the canonical store at .wbuddy/cowork/. Before either exists, Co-work proves that the selected folder is the only Co-work folder on its own line of descent: no ancestor already holds a store, and no walked descendant already holds a .wbuddy/cowork/store.yaml of its own.

Overlapping stores are unresolvable rather than untidy. Two stores that both enclose a file each claim that file under a different folder-relative path, each keep their own content hash for it, and each read the other's writes as outside drift. The overlap has no correct resolution once it exists, so the boundary is established before any write rather than repaired afterwards.

Inspection reads, setup writes

Choosing a folder inspects it. Inspection writes nothing beneath the selected folder. It reads that folder's Work Buddy data, walks its ancestors looking for an owning Co-work folder, and walks its descendants looking for a store boundary. It resolves to one of a small set of states:

• initialized: the folder is already a Co-work folder. The only action offered is opening it.
• inside_existing_folder: an ancestor is already a Co-work folder. The result names that folder and its store identity, and offers opening the owner or choosing another folder.
• contains_nested_folder: the descendant walk crossed at least one store boundary. The result names every boundary crossed, each with its folder name, host path, and store identity where that boundary itself reads as an initialized folder. The only action offered is choosing another folder.
• unavailable: the descendant walk reached its cumulative work threshold before it could answer, carrying the reason folder_too_large_for_safe_setup. The action offered is choosing a narrower folder inside the selected one.
• collision: the folder holds Work Buddy data that does not form a complete Co-work folder. A reason code separates an incomplete or redirected managed layout, store records that contradict each other, and data that could not be read at all. The actions offered are repairing that data or choosing another folder.
• uninitialized: an ordinary folder that can be set up.
• inspection_pending: the descendant walk has more tree to cover. The result carries a continuation token, a count of entries visited, and a short suggested wait. A caller asks again with that token until the walk resolves.

Setup is a separate, explicit call. It consumes the authorization a terminal inspection minted, re-walks the whole tree in one unpaged pass while holding the folder operation locks, and proceeds only if the folder still classifies as uninitialized.

Setup is all or nothing. A failure part way through removes the store directory it created, restores the exact manifest bytes it published, removes the .wbuddy directory when setup was what created it, and unregisters the store. A refused or failed setup leaves the folder as it was.

Refusals name the state and the action

A caller that asks for setup on a folder that cannot take it receives a typed code, prose that names both the folder's state and the action that answers it, and an HTTP status consistent with that code:

• folder_already_initialized: the folder is already a Co-work folder, and the answer is to open it instead of setting it up again.
• inside_existing_folder: the folder sits inside a Co-work folder, and the answer is to select a folder outside that one.
• contains_nested_folder: the folder encloses a Co-work folder, and the answer is to select a folder that does not enclose it.
• folder_too_large_for_safe_setup: the folder holds too many items to check safely, and the answer is to select a narrower folder inside it.
• folder_layout_incomplete: the folder holds Work Buddy data that does not form a complete Co-work folder, and the answer is to repair that data or select a different folder.
• identity_conflict: the folder's store records were read and disagree about which store the folder holds. That is a different repair from an incomplete layout, and it is reported as its own code rather than folded into one.
• folder_unreachable: the folder's Work Buddy data could not be read.
• descendant_scan_incomplete: the descendant walk could not finish, because a descendant could not be read or kept changing while it was listed.
• folder_changed: the folder moved out from under the observation a person was shown.

The message is the whole contract for an agent caller, which reads the exception text and nothing else, so each refusal states the folder's state and the action together.

Retryable and settled refusals

Three refusals are worth asking again unchanged. folder_unreachable says that reading the folder's Work Buddy data failed, so the classification settled nothing about what that data holds and the same folder can classify differently on the next attempt. descendant_scan_incomplete says the same thing about one descendant. folder_changed says the folder moved between observation and setup, and a fresh inspection can resolve it.

Every other refusal describes a fact the walk established. An already initialized folder, an enclosing or enclosed Co-work folder, a folder past the work threshold, an incomplete layout, and contradictory store records are all settled: repeating the call cannot change any of them, and only the user acting on the folder can. Those refusals carry a non-retryable status and prose that avoids transient wording, so an automatic retry layer does not queue a folder whose answer is fixed.

An unreadable folder is unread, not broken

Failing to read the folder's Work Buddy data is a different answer from reading it and finding it damaged. folder_unreachable reports that Co-work cannot tell what state the folder is in and asks the caller to try again in a moment. It deliberately does not use the repair wording that a genuine collision uses, because an agent told the data is broken repairs a folder that was never shown to be broken. A healthy store held open by a backup or a scanner classifies this way, and the very next attempt is expected to succeed.