One Mediated Door into Memory

Do not build a writer per button

Inline editing, restore, and delegation naturally gain separate save, history, and apply endpoints. They look clean until one permission check becomes stale and another path omits ledger provenance.

The final function touching memory source should be singular. Callers provide intent, actor, expected hash, and proposed bytes; the canonical writer performs scope, permission, stale state, atomic replacement, ledger, and reindex in order.

Ordering is part of the contract

Checking permission after write or leaving source after ledger failure breaks the invariant. The order is target validation, authorization, base comparison, temporary preparation, atomic replace, semantic history, then reindex trigger.

Filesystem, Git, and index cannot share one database transaction. Define failure and repair. If source succeeds and history fails, expose an uncompensated state and let the next sweep plant the missing commit rather than hiding it.

Atomic replacement hides partial bytes

Writing in place lets watchers and editors observe half a document. Prepare a temporary file on the same filesystem, flush it, and replace so readers see either complete old or complete new content.

Do not write frontmatter and body separately. Validate and replace the full logical document, even when an API accepts field updates.

An idempotency key protects retries

A client may retry after timeout. Recording operation identity and proposed hash lets the server return the original result instead of making a duplicate commit.

Do not merge requests merely because content hashes match. Actor, target, and intent belong to idempotency identity, and expired keys must not silently reopen.

When several features mutate one source, one final door must own the invariants. Pass different intent instead of copying safety into every entry point.

Code

The ordering skeleton of a canonical writer·python

def mediated_write(target, proposed, actor, expected_hash):
    assert target.endswith(".md")
    assert actor in {"dad", "pippa"}
    current_hash = "base123"
    if current_hash != expected_hash:
        raise RuntimeError("stale source")
    # atomic_replace(target, proposed)
    # append_semantic_ledger(actor, target, proposed)
    # enqueue_reindex(target)
    return {"status": "written", "actor": actor}

assert mediated_write("memory/a.md", "new", "dad", "base123")["status"] == "written"

Do not build a writer per button

Ordering is part of the contract

Atomic replacement hides partial bytes

An idempotency key protects retries

Code

External links

Exercise

Progress

Comments 0