Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,17 +122,21 @@ licence it arrives under, and it sits with the rest of the header in
[docs/experiment-template.md](docs/experiment-template.md). An experiment that
borrows nothing writes no such line.

Two of those a run refuses and the rest of them it does not, and the difference
is worth knowing before you lean on any of it. A `borrowed/` directory with no
`LICENSE` beside it is refused, and so is a record declaring `Borrowed:` in an
experiment that holds no such directory. A `borrowed/` directory in an
experiment whose record declares nothing passes, because a field added to the
format after
Some of that a run refuses and some of it it does not, and the difference is
worth knowing before you lean on any of it. A `borrowed/` directory with no
`LICENSE` beside it is refused. So is a record declaring `Borrowed:` in an
experiment that holds no such directory. So is a directory named `borrowed`
anywhere else inside an experiment, since `experiments/<slug>/borrowed` is the
one place a quarantine lives and one is all record `0019` allows. A directory
of that name inside the quarantine is not refused: what is in there is somebody
else's code laid out somebody else's way, and this board's rules stop at that
edge.

What still passes is a `borrowed/` directory in an experiment whose record
declares nothing, because a field added to the format after
[docs/decisions/0013-how-the-record-format-changes.md](docs/decisions/0013-how-the-record-format-changes.md)
is never refused for being absent. A second quarantine deeper inside an
experiment passes as well, since the check reads `experiments/<slug>/borrowed`
and no other name, so the one-directory limit above is yours to keep rather
than the gate's.
is never refused for being absent. That one is yours to keep rather than the
gate's.

Nothing opens the licence file. A green run says the layout and the declaration
do not contradict each other, and it says nothing about which licence the code
Expand Down
5 changes: 5 additions & 0 deletions docs/experiment-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,11 @@ almost every experiment borrows nothing. The code itself goes in
terms, and a record declaring the field with no such directory is refused, as is
a borrowed directory with no licence file in it.

That directory is the only place a quarantine may be, and one is all record
`0019` allows, so a directory named `borrowed` anywhere else in the experiment
is refused too. One inside the quarantine is not: the code in there is laid out
by whoever wrote it and this board does not rearrange it.

What that refusal does not do is worth knowing before you rely on it. Nothing
reads the licence file, so a green run says the layout and the declaration agree
and says nothing about which licence the code is actually under or whether the
Expand Down
92 changes: 92 additions & 0 deletions internal/check/borrowed.go
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,24 @@ const (
// The declaration having been made is what this reads, so record 0013 is
// untouched by it: an absent field says nothing and is not refused here.
RecordBorrowedDeclarationNamesNoDirectory = "record-borrowed-declaration-names-no-directory"

// AQuarantineOutsideThePlaceQuarantinesLive refuses a directory named
// borrowed inside an experiment that is not the one record 0019 fixes.
// That record puts the quarantine at experiments/<slug>/borrowed and
// allows one per experiment, and both halves of that are this one
// property: a second quarantine is necessarily somewhere the record does
// not put one.
//
// What it protects is the reason the quarantine exists at all. A person
// promoting the work walks the tree and reads the boundary off the layout,
// so a boundary somewhere below the first means the first one was not the
// boundary, and the reader who stopped at it learned something untrue.
//
// It is refused whatever the record says, for the same reason the licence
// arm is. The declaration names one source and one licence, so a second
// quarantine is undeclared by construction however carefully the header
// was written.
AQuarantineOutsideThePlaceQuarantinesLive = "quarantine-outside-the-place-quarantines-live"
)

// refuseBorrowed holds an experiment's borrowed quarantine and its record's
Expand Down Expand Up @@ -109,6 +127,16 @@ func refuseBorrowed(fsys fs.FS, root, inside, record string, data []byte) ([]Ref
}
}

// Asked whether or not the experiment holds a quarantine of its own, and
// asked before the declaration is read, because the two arms below return
// early on an unparseable record and a directory in the wrong place is not
// a thing a header could excuse.
elsewhere, err := refuseQuarantineElsewhere(fsys, root, inside, quarantine)
if err != nil {
return nil, err
}
refusals = append(refusals, elsewhere...)

parsed, err := ParseRecord(data)
if err != nil {
return refusals, nil
Expand All @@ -125,6 +153,70 @@ func refuseBorrowed(fsys fs.FS, root, inside, record string, data []byte) ([]Ref
}), nil
}

// refuseQuarantineElsewhere walks an experiment for a directory named borrowed
// that is not the one record 0019 fixes. It takes the allowed one as a path
// rather than deriving it a second time, so the place this walks past and the
// place refuseBorrowed judges cannot drift apart.
//
// IT STOPS AT THE QUARANTINE RATHER THAN JUDGING PAST IT. What is inside the
// allowed directory is somebody else's code laid out somebody else's way, and a
// directory named borrowed in there is that code's own business. Descending
// would refuse honest work for the shape of a name this board does not own, and
// the whole point of the quarantine is that this repository's rules stop at its
// edge.
//
// WHERE IT DOES NOT REACH, in three places.
//
// Below WalkDepthBound nothing is examined, which is the bound the stray-record
// walk already carries. A tree deep enough to hide a quarantine there is refused
// by that walk for its depth, so the repair is the same one either way, and a
// second bound here would give one tree two answers about how far a walk goes.
//
// A symbolic link named borrowed is not a directory to fs.WalkDir, so it is
// neither followed nor refused here. That is the same position isDirectory
// takes at its own declaration for the same reason: a link under experiments/
// is already refused where the stray-record walk meets it, by reading the entry
// rather than the target.
//
// Nothing here opens a licence file or reads a word of one, so a quarantine in
// the right place with the wrong terms inside it is not this arm's subject and
// is not any other arm's either.
func refuseQuarantineElsewhere(fsys fs.FS, root, inside, quarantine string) ([]Refusal, error) {
var refusals []Refusal

err := fs.WalkDir(fsys, inside, func(name string, entry fs.DirEntry, err error) error {
if err != nil {
return err
}
if !entry.IsDir() {
return nil
}
if name == quarantine {
return fs.SkipDir
}
if depthOf(name) > WalkDepthBound {
return fs.SkipDir
}
if entry.Name() != BorrowedDir {
return nil
}
// Refused and not descended into. What is under it is code this board
// has already said it will not judge, and the repair is to move the
// directory rather than anything inside it.
refusals = append(refusals, Refusal{
Property: AQuarantineOutsideThePlaceQuarantinesLive,
Subject: at(root, name),
Detail: fmt.Sprintf("a quarantine lives at %s and this one is at %s, so %s holds a second boundary below the first and record 0019 allows one",
quarantine, name, inside),
})
return fs.SkipDir
})
if err != nil {
return nil, fmt.Errorf("cannot walk %s: %w", at(root, inside), err)
}
return refusals, nil
}

// isDirectory says whether a name in the walked filesystem is a directory. A
// name that is not there is not one, and that is the ordinary answer rather
// than an error: almost every experiment borrows nothing.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
directories 1
records 1
experiments present
decisions absent
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
Slug: one
State: asking
Question-Written: 2026-01-01
Needs-Hardware: none
Borrowed: the reference implementation from example.invalid, under the MIT licence

## Question

Does the reference implementation lose a frame when the stream stalls?

## Method

The implementation was read and run from the copy this experiment carries.

## Answer
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The MIT licence, as the reference implementation carries it.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
the reference implementation, as it was copied
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
a directory the borrowed code names itself, which this board does not own
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
directories 1
records 1
experiments present
decisions absent
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
quarantine-outside-the-place-quarantines-live
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
an-experiment-that-borrows-and-declares-it
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
Slug: one
State: asking
Question-Written: 2026-01-01
Needs-Hardware: none
Borrowed: the reference implementation from example.invalid, under the MIT licence

## Question

Does the reference implementation lose a frame when the stream stalls?

## Method

The implementation was read and run from the copy this experiment carries.

## Answer
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The MIT licence, as the reference implementation carries it.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
the reference implementation, as it was copied
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
a second copy of somebody else's code, outside the quarantine
Loading