Skip to content

docs(marvel): record the fileshare-3 ruling and its read bound in the cp design - #1237

Merged
arcaven merged 2 commits into
mainfrom
build/marvel/cp-fileshare3-bound
Nov 2, 2026
Merged

arcaven merged 2 commits into
mainfrom
build/marvel/cp-fileshare3-bound

Conversation

@arcavenai

@arcavenai arcavenai commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

This records, in the design that already limits what marvel's file copy can reach, the bound on a scheduled publish verb the operator ruled in. Left unwritten, such a verb could later be built to read whatever its own configuration names, which would undo the containment cp was ruled on.

The change adds one section, 9a, to docs/design/marvel-cp.md, after the section that records R1 to R4. It is design text only, with no code and no renumbering. It records Desk card fileshare-3 (2026-11-02, option 3, a marvel verb run by the daemon on a schedule) and the bound the operator confirmed the same day:

  • P1: the owner's policy file gains its own entry for the verb's read paths, separate from the jail (A3), under the A1 checks; the verb reads only those paths.
  • P2: a missing, unreadable or daemon-writable policy file turns it off, as A1 already does for cp.
  • P3: the verb is generic and knows nothing of any other component's layout (ADR-005).
  • P4: the policy is read on each scheduled run, so A6 stops the next one; this follows from P2 and A6.

The publish set and any one-way mirror are left out; both are separate items recorded elsewhere, and a mirror needs its own design note. The section uses placeholders only and names no real directory.

Additive only; no existing section changes.

… cp design

Adds section 9a to the cp design: Desk card fileshare-3 (option 3, a
marvel verb run by the daemon on a schedule) and the bound the operator
confirmed. The verb reads only paths named in the owner-written policy
file marvel cannot write, turns off when that file is missing,
unreadable or daemon-writable, and is generic. The publish set and any
mirror are left out.

@arcaven arcaven left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Section 9a is worth having: it puts the bound on a scheduled publish verb into the design a build has to meet. The bound matches what was confirmed in substance. One citation does not hold against A3 as written. That gap is where the containment would leak, so I am asking for one sentence before this merges.

Finding (medium), docs/design/marvel-cp.md P1 (line 145 at this head). P1 says the verb reads only "paths named in the owner's policy file ... (A1, A3)". A3 does not name any paths of that kind. It names, per workspace: the jail, the directions, the callers, optional path prefixes within the jail, and the daily budget. The card's own cost line for options 2 and 3 is reach outside the jail. So the paths this verb reads have no field in A3 today.

A later build could fill that gap in two ways:

  • read the jail and its prefixes, which is narrower than the ruling;
  • add its own path list somewhere other than the owner's file, which is the outcome 9a exists to prevent.

Fix direction: state in P1 that the owner's policy file gains a per-workspace entry listing the verb's read paths. It has the same owner and checks as A1, and it is separate from the cp jail and its prefixes. Either name the entry or leave its name to the build, but say it is new and lives only in that file. A matching clause at the end of A3 would work too, though that edits an existing section, and the body says additive only.

Checked and fine at this head:

  • P2 matches A1's checks and A2's no-default rule. "daemon-writable" is covered by "the same checks", which include A1's ancestor rule.
  • P3 builds in no component path. It cites ADR-005.
  • P4 matches A6's next-call effect.
  • No cp method is added. The only path is the <owner-listed path> placeholder.
  • The quoted card text matches the card: "marvel verb, run by the daemon on a schedule." and "as option 2, and it publishes with no owner at the keyboard".
  • The commit is signed. The diff is +13 in one file, which matches "additive only". The body leads with why. No em dashes or banned words, and nothing private.

Not mine to decide: the ruling itself, the ready flip, or the merge.

Review of the section 9a draft found that P1 cited A3 for the verb's
read paths, but A3 names only the jail and its prefixes. P1 now says
the policy file gains a per-workspace entry for the verb's read paths,
separate from the jail and under the same A1 checks.

@arcaven arcaven left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The round 1 finding is closed at 8c80a3d. The bound now has a defined place in the owner's file, and nothing else moved, so this is ready from my side.

  • P1 now says the owner's policy file gains a per-workspace entry for the verb's read paths, kept separate from the jail and its prefixes (A3) and under the same A1 checks. It also says the paths are named there and nowhere else. That gives the read set a home that only the owner can write, which was the gap.
  • The delta is 1 line in docs/design/marvel-cp.md, replacing P1 only. Against main the PR is still +13 in one file, and the body's P1 line matches the new text.
  • The new commit is signed. The scan passes on the changed line, the commit message, the body and this review. No em dashes, banned words or private names.

Not mine to decide: the ready flip or the merge.

@arcaven
arcaven marked this pull request as ready for review November 2, 2026 20:00
@arcaven
arcaven merged commit 6172fe1 into main Nov 2, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants