One Door Out

Many Ways In, One Way Out

Oriel has many ways to look: looks, replays, crops, frames, the play stream, the watchers. It has exactly one way for anything to leave: a class called Exports. It is the only code that writes into Oriel's exports folder, and a test holds that: it scans every backend module and fails if any file other than the marks module (and the settings that define the path) mentions the exports location. Today the door exports a single frame, through the export_frame action or Dad's page. Every later outward path (an edit timeline, a clip, a thumbnail, a handoff to the family's video workshop) is required to call the same door's check_range first.

One door is not a tidiness preference. It is what makes the next sentence true: if the door refuses, nothing leaves. With two doors, that sentence needs "and the other one checks the same things", forever.

What the Door Checks

Exports.check_range(input, t0, t1) refuses in three cases, and the order of the first two is the design:

Nothing was recorded there. Refused; there is nothing to export.
Any segment in the range has not been checked for people yet. Refused: "nothing leaves before they are". This is the fail-closed choice. The background pass checks segments some time after they are recorded; a range that has not been reached yet is not "clear", it is unknown, and unknown does not leave.
Any segment in the range is marked and Dad has not cleared it. Refused, with the reason and the times of the marked stretches, and the rule: it leaves Oriel only when Dad clears it.

And before any of that, an export passes the eyes gate, like any read. A frame Pippa may not look at right now is a frame she may not export right now either.

Clearing Is Dad's

A mark is lifted in only two ways: Dad's "Clear for use" on Oriel's page (with his PIN session), or the clear_mark action carrying his own words, which, like open_eyes, refuses outright without publish and his instruction. Pippa cannot clear a mark on her own judgment that the person in it would not mind. The clearing is recorded with the words that cleared it.

The Same Answer for Pictures Already Seen

There is one more outward-looking question, and it is subtle. cwkPippa keeps every picture a look returns, so Dad can see what Pippa saw. That kept picture is inside the family's own app, not an export, but it is a copy, and the family wants to know whether it shows someone. So cwkPippa asks Oriel, by the look's id, about the person marks over exactly the frames that look showed. Each input gets one of five answers: marked, cleared, clear, not_watched, or not_checked.

The last one carries the whole philosophy. A live look or a one-shot peek shows a frame that no indexed segment holds yet, because the background pass reads a segment only after it is recorded. The answer is not_checked, with that reason, and it is never read as clear. A cached frame with no capture timestamp gets the same answer: checking the segments at the time of a later request could clear a different picture. Unknown is never clear.

Code

The only door out, and the order of its refusals (trimmed excerpt, backend/marks.py)·python

class Exports:
    def check_range(self, input_id: str, t0: float, t1: float) -> None:
        """Refuse a range that holds a marked segment Dad has not cleared, or
        a recorded stretch not checked for people yet."""
        segments = self.engine.store.segments_between(input_id, t0, t1)
        if not segments:
            raise ExportRefused("nothing was recorded there")
        marks = {m["segment_path"]: m for m in self.engine.store.marks_between(input_id, t0, t1)}
        unchecked = [s for s in segments if s["path"] not in marks]
        if unchecked:
            raise ExportRefused(f"{len(unchecked)} segment(s) in that range are not checked for people yet; "
                                "nothing leaves before they are")
        held = [m for m in marks.values() if m["marked"] and not m["cleared_at"]]
        if held:
            raise ExportRefused(f"marked: {held[0]['reason']} ...; it leaves Oriel only when Dad clears it")

    def frame(self, input_id: str, at: float, *, actor: str) -> dict:
        """One frame out, checked: marks first, then what its text would give away."""
        row = self.engine.store.input(input_id)
        self.engine.gate.check(row, "export")      # the eyes gate holds for an export too
        self.check_range(input_id, at, at + 0.001)
        ...  # write the frame, read its text, report findings

A test that keeps the door single (trimmed excerpt, backend/tests/test_marks.py)·python

def test_no_other_code_writes_where_exports_go():
    repo = Path(__file__).resolve().parents[2]
    for path in (repo / "backend").glob("*.py"):
        if path.name in ("marks.py", "settings.py"):
            continue
        assert "settings.exports" not in path.read_text() and ".exports /" not in path.read_text(), path.name

Unknown is never clear: a five-state answer for one picture (runnable sketch)·python

def picture_status(watched, segments, marks):
    """segments: paths that hold the picture's frames; marks: path -> mark dict."""
    if not watched:
        return "not_watched"
    held = [m for m in marks.values() if m["marked"] and not m["cleared"]]
    if held:
        return "marked"                 # one held mark outweighs anything still unchecked
    if not segments or any(s not in marks for s in segments):
        return "not_checked"            # a live frame, or a segment the pass has not reached
    if any(m["marked"] for m in marks.values()):
        return "cleared"
    return "clear"


print(picture_status(True, [], {}))                                         # not_checked
print(picture_status(True, ["a"], {"a": {"marked": True, "cleared": False}}))   # marked
print(picture_status(True, ["a"], {"a": {"marked": True, "cleared": True}}))    # cleared
print(picture_status(True, ["a"], {"a": {"marked": False, "cleared": False}}))  # clear

Exercise

Find every way data can leave one system you know (an export button, an email report, an API that returns files, a backup to a third party). Count them. Then sketch how you would route all of them through one check_range-like function, and write the order of its refusals the way Oriel does: nothing there, not checked yet, held and not cleared.

Hint

The order matters because of what each refusal tells the caller. "Not checked yet" says "wait"; "held" says "ask the owner". If you check holds first and skip unchecked ranges, a range the checker never reached slips through as if it were clear.