0014 · Standing folder shares

Status: Accepted · 2026-10-14. Amends the deferral of path-scoped standing grants in permissions.md.

Context

Sharing was one document at a time, or a one-time expansion by tag. Continuous behaviour was deliberately left to automations: a standing rule that widens access was thought hard to reason about, while a script is attributable — a named script, an owner, a run record for every grant.

In use, the commonest continuous share is a folder: give j@radium.ge the se/ folder, for writing. On the Medspace instance on 2026-10-14 that took, for two people and five folders:

a bulk share of every page already there, assembled by hand, because list_documents stopped at 50 without saying so;
a preview per page before it, 64 for one folder;
six automations, because each covers one folder and one recipient, and switching them from read to write meant deleting and recreating them;
and no way to say afterwards what anyone had been given.

The automation was standing in for a rule, at the cost of a script nobody needed to read, one per folder per person. And the worry the deferral named — access widening with nobody able to say why — was realised more fully by six scripts than by one listed rule.

Decision

A person can share a folder of theirs, standing. share_folder("wiki:se", "j@radium.ge", write) shares every document of theirs in se/ and beneath it now, and each one they put there later as it arrives — written there, moved there, or restored there.

Their own documents only. Only an owner can share a document, so a folder share is a rule about the owner's pages. A page somebody else keeps in the same folder is theirs to share.
It grants nothing itself. Each document it reaches gets an ordinary grant, made through the same Share every share goes through, with grant_reason = 'folder'. The checks, the access events, the reindex and the recipient's notification are the ones any share has, and revoking one document's grant works as it always did.
Arrival is off the outbox. A consumer on document.created, document.moved and document.restored applies the folder shares covering the document's new place. A failure retries without failing the save. The grant carries the cascade depth of the event that caused it, so an automation reacting to it cannot loop through a folder share. A departed owner's folder shares rest, as their automations do.
A folder is a folder. se covers se/proposals and never se-old, as everywhere else. wiki: alone is the whole space.
It is visible. list_folder_shares lists them, shared_with reports the ones reaching a person beside what they were given, and every grant one made says folder in the access list.
Ending it (unshare_folder) stops what comes later. What it already shared stays shared unless revoke_existing is asked for, which takes back only grants made by folder shares. A page shared directly stays shared, and an overlapping folder share that still stands shares its pages again.
Sharing raises access, never lowers it, here as everywhere: sharing a folder again with a different permission changes the rule, and upgrades readers, and an editor stays an editor.

Previews cover a whole set: preview_share takes several documents or a folder and answers once, merging what they link to outside the set.

Consequences

One call replaces a bulk share plus an automation per folder and recipient, and the result can be listed.
A document moved out of a shared folder keeps its grant. A grant is to a document, not to a place, and silently revoking on a move would surprise whoever was reading it. The folder share's owner can revoke it like any grant.
Ownership transfer does not carry folder shares: they belong to the person who made them, and the pages handed to someone else are theirs to share or not.
A busy shared folder raises a notification per arriving page for each recipient. That is what a share does; the inbox is where a person learns something new is theirs to read.
Tag-scoped standing grants stay deferred. A tag is applied by anyone who can edit, so a tag rule would let an editor widen the owner's audience. A folder holds a document because its owner, or someone they let edit it, put it there — and moving a page is visible in its history.

Alternatives rejected

Keep it in automations, with better tools. Dry runs, editing in place and backfill make the automation route workable, and they were built anyway. But a script per folder per person is the wrong unit for "this folder is shared with them": it cannot be listed as what it is, and reading it is the only way to know what it does.

Folder-level ACLs that documents inherit. A grant on the folder, evaluated at read time, would reach other people's documents in it, need a second path through every visibility query and the search filter, and make "why can they see this?" depend on where a page sits right now. Grants on documents keep one model and one filter.

Revoke on move out. Rejected for the reason under Consequences: access should not change because someone tidied a folder.

Amendment

2026-10-20 — Editors share (0020), so "only an owner can share a document" is no longer why a folder share reaches only its owner's pages. The rule stands for its own reason: a folder share that reached every page its owner could edit would grant on other people's pages as they arrived, which is the folder-level permission rejected below. The case against tag-scoped standing grants narrows the same way: an editor can now widen a page's audience directly, and a tag rule would do it without anyone choosing the page.