Pipeline partner: Perseus Vault → CoalWash = clean context from write to read

[tcconnally]

Hey! I build Perseus Vault (github.com/Perseus-Computing-LLC/perseus-vault) — we write typed markdown memory files for AI agents (deterministic, bi-temporal, crypto-chained audit).

CoalWash defragments/cleans memory files. Perseus writes them. Natural pipeline.

I'd like to add a Perseus directive that points CoalWash at the vault directory so the full pipeline is: Perseus writes structured memories → CoalWash keeps them lean → agent gets clean context.

No obligation — just saw the adjacency and wanted to reach out. The transactional apply + zero-fact-loss gate is exactly the right approach 🤝

[HetCreep]

Really appreciate you opening an issue rather than forking and wiring it up quietly - that's the right way to do this, and it's noted. Coming from someone who's built bi-temporal history and crypto-chained audit into a memory store, "the transactional apply + zero-fact-loss gate is the right approach" means a lot - that's the exact seam we sweated, so hearing it from your side of the domain lands well.

The adjacency is real: you're the store, CoalWash is the cleaner - different layers, natural pipeline.

The way we'd like to keep it clean: think of CoalWash as a standard IC that publishes its own pinout. It works standalone, and it composes - but it stays deliberately store-neutral, so any store can wire to the same contract and neither of us ends up tailing the other's release cadence (you ship fast - 35 releases - respect).

One thing that shapes the bridge: CoalWash washes prose markdown. Its whole safety model (that fidelity gate you called out) diffs structured tokens inside human-accreted prose, and it deliberately scopes OUT machine-parsed formats. A Perseus export's body is JSON in frontmatter ({"content":"..."}), so CoalWash's discovery would skip the vault rather than clean it - washing a JSON blob would corrupt your schema, not lean it. Not a no - just the honest shape of the seam.

So the bridge belongs on the side that knows both ends: a Perseus prose-export mode that meets CoalWash's input contract. You read our pinout, you wire to it - we don't reach into your schema, you don't wait on our internals. If Perseus grows that export, CoalWash washes it with zero special-casing on our side.

Next step from us: we'll publish the input-contract spec (the datasheet - exactly what CoalWash eats, the 4-test, the fidelity guarantees) so it's a fixed target you can build against without asking us anything. No rush - worth scoping right before either side writes code. Thanks again for the good-faith reach-out.

[tcconnally]

Really appreciate the thoughtful reply, and the IC/pinout framing is exactly the right mental model. Store-neutral composability beats tight coupling every time, and I'd rather build against a clean contract than have either of us chasing the other's release train.

The JSON-in-frontmatter point is well-taken and honestly helpful. You just saved me from wiring up an integration that would've silently skipped the vault and left us both scratching our heads. A perseus export --prose mode that flattens to clean markdown (stripping the machine layer, keeping the human-accreted prose) is the obvious seam. Perseus already knows where its own schema boundaries are, so that's a natural feature to add on our side with zero special-casing needed from yours.

Looking forward to the datasheet whenever it lands. No rush, worth scoping right. Happy to iterate once it's up. Thanks again for the good-faith engagement 🤝

[HetCreep]

Quick progress note from our side: CoalWash just shipped v0.2.0-rc.4 — that was the version line we wanted settled before freezing the input contract, so the datasheet is now the immediate next step.

It's drafted here now — the pinout covers the four washability tests (local · user-owned · prose · accreted), the structured-token fidelity guarantee (what the code-enforced gate proves by diff vs. what the semantic layer covers), and the discovery shape (how CoalWash decides what it will and won't touch — which is exactly why a JSON-in-frontmatter body gets skipped, not corrupted). We'll publish it as a fixed target your perseus export --prose can build against without asking us anything — store-neutral by construction: you read the pinout, you wire to it, neither of us tails the other's release train.

I'll ping this thread the moment it's up. Thanks again for scoping it right before either side wrote code 🤝

[HetCreep]

Status update, because eleven days of silence after "I'll ping the moment it's up" deserves an actual reason rather than another "soon".

Not forgotten. Deliberately held — and the hold is the datasheet's own fault, in a way worth explaining.

The point of a pinout is that you can build against it without asking us anything. That only works if the thing it describes has stopped moving. It hadn't. Since rc.4 we have shipped rc.5, rc.6 and rc.7, and a large share of that is security work on the destruction path — including the pin semantics themselves, the exact contract a datasheet would freeze. One predicate — is this file pinned and therefore untouchable — took five separate repairs, each one closing what the previous one had reported and leaving the class open. The last one was not a bigger list of cases; it was changing which side an unclassified input falls on, so that the answer which authorises a delete has to be earned rather than fallen into.

Publishing a pinout mid-way through that would have handed you a fixed target that then moved. For an integration, a spec that changes under you is worse than a spec that is late.

The honest gate, instead of a date: CoalWash is not graduated. It is a tool that destroys bytes on someone else's machine, so we hold it to a convergence bar — repeated adversarial rounds that must stop finding anything new — and it has not cleared that yet. The datasheet lands when the engine underneath it has stopped changing, because that is the only condition under which the document is worth reading.

What you can build against today, because this half has NOT moved: the four washability tests are unchanged since launch and are the whole of what perseus export --prose has to satisfy — the output must be (1) a local file, (2) user-owned/authored, (3) prose — tolerates rewording, never machine-parsed and never executed as instructions, and (4) accreted — grows by accumulation rather than by deliberate versioned edits. Fail any one and CoalWash skips it by construction, which is exactly why a JSON-in-frontmatter body is passed over rather than mangled. Those four are the stable part of the contract; the datasheet will make them precise and add the fidelity and discovery detail around them, but it will not contradict them.

So: build the flattener against those four now if it is useful to you, and the datasheet will confirm rather than surprise. Thanks for the patience — and for the framing that made this the right call to explain instead of quietly slip.

[tcconnally]

This is exactly the right reason to hold a datasheet. A late contract is recoverable; a published contract that moves underneath an integration is not—especially when the movement is in the predicate that authorizes destruction.

We actually went ahead and built against the stable half you described: feat(#816): add perseus vault export --prose mode for CoalWash integration now strips the machine frontmatter and emits local, user-authored, prose-only markdown intended to grow by accumulation. It shipped with seven golden tests, with no CoalWash-specific handling required on your side.

We’re treating that as the flattener, not as a claim of final contract conformance. Once the datasheet lands, we’ll validate the output against the precise discovery and fidelity rules and adjust on our side if needed.

And for what it’s worth, changing the destructive predicate so permission must be earned rather than inherited from an unclassified case is exactly the right security boundary. Keep the convergence bar. No pressure from us to freeze it early. 🤝

[HetCreep]

Shipping the flattener against the stable half — with golden tests, and with no special-casing for us — is exactly the outcome the store-neutral framing was supposed to produce. Treating it as the flattener rather than as conformance is the right posture too; that distinction is the datasheet's job to close, not yours to guess at.

One thing worth stating plainly, because the hold could easily be read as a freeze coming: the datasheet freezes the CONTRACT, not the CODE. That is the whole reason the IC framing earned its keep. A pinout stays valid across die revisions — the part gets faster, the process shrinks, bugs get fixed, and the pinout does not move, because a pinout that tracked the silicon would be useless to anyone building around it. Same here: once the contract is published, the engine underneath goes right on changing. It has to.

And it will keep changing, structurally rather than by good intentions. We run standing processes that pull improvement in continuously: an antenna on what the outside world ships and publishes, a periodic re-audit of our own rules against current best-in-class rather than against the version of us that wrote them, and an independent multi-perspective review reserved for the calls where being wrong is not recoverable. That is why the pin predicate got repaired five times instead of once — each round was a process finding what the last one left, not a person remembering to look. The same machinery is what keeps the logic adapting era to era.

So the commitment that matters to your side is not "this will never change" — it is: the four tests are the contract, and if anything in the contract ever does have to move, it moves as a version event with notice, never as silent drift. Improvements to how we honour the contract need no announcement at all. Those are ours to make and yours to ignore.

Thanks for building it before the paperwork. That is the right order when the stable half is genuinely stable, and it means the datasheet arrives as confirmation rather than as homework.

[HetCreep]

Sorry for the long silence — that's on us, and thank you for reaching out.

Quick honest status. CoalWash reached v1.0.0 on 2026-08-03. The pipeline shape you described (Perseus writes structured memories → CoalWash keeps them lean → the agent gets clean context) still reads right to us, and the adjacency you spotted is real.

What exists on our side today: CoalWash has a two-lane model — class-B (memory/governance files, semantic wash behind a fidelity gate) and class-A (transcripts/estate, byte-identity only). The fidelity gate is the part most relevant to a writer upstream of us: it proves zero structured-token loss by diff, and blocks an apply if any link, date, version or frontmatter key would be dropped.

What does not exist yet, stated plainly: we have no published input-contract datasheet — the document that would tell you what shape a file must be in for our gate to accept it cleanly. That is our ball, it is on our board, and it is not written. Until it is, any integration would be you guessing at our expectations, which is not a good trade for you.

One thing worth knowing before you invest: CoalWash proves fidelity, not truth — that nothing was silently dropped, not that what remains is correct. If Perseus Vault's value is in typed/structured guarantees at write time, that is genuinely complementary rather than overlapping.

No timeline promised. When the datasheet lands I will post it here.

[HetCreep]

EDITED 2026-08-11 — §6's first bullet is corrected below, and this note is here so the edit is visible rather than silent.

It read “one file per accreted unit” — a proxy for the wrong constraint. The real one is file-level addressability: pin, rewrite, delete and diagnosis are all file-scoped in this engine, so a single concatenated file is contract-valid and always was. The corrected bullet states the why, which is the half the old text left out.

And the reason this edit is late. Over in Perseus-Computing-LLC/perseus#937 I wrote “we'll fix §6 on our side” and you read it as done. It wasn't — the text you were looking at, this comment, still carried the old bullet at the moment you thanked us for the fix. That is on my phrasing, not your reading, and it is the exact failure the corrected bullet exists to prevent: a claim about the artifact outrunning the artifact. Fixed now, here, in the thing you actually read.

---

The datasheet is below. Before it, one correction to something I said in this thread, because it needs saying by name rather than quietly superseded.

On 07-27 I wrote: "the four washability tests are unchanged since launch and are the whole of what perseus export --prose has to satisfy." That was wrong when I wrote it — a UTF-8 validity requirement had landed in the engine 54 minutes earlier, before I posted the comment, and two more checks landed within the following 12 hours. I hadn't re-derived the claim from the code at the moment I made it; I was working from what had been true a day or two before. Retracting it here rather than letting the datasheet silently replace it.

What actually moved: not the four tests — those are genuinely untouched since launch, and §1 below still opens with them. What moved is the layer underneath them: the check that decides whether an admitted file is actually safe to write or delete. It gained five requirements on the bytes themselves (no NUL byte, valid UTF-8, a clean 64-character head regardless of frontmatter, a well-formed opening fence where one is present, and — where a fence closes cleanly — a provably-readable block, six enumerated refusal classes) and a change to how a refusal's blast radius works. Both are in §4/§6 below, named precisely so you can self-check.

The surface has been frozen since 2026-07-28 (13 days as of this comment) — no further changes to anything a caller sees. That is the condition I said the datasheet was waiting on, and it has now held long enough that publishing is confirmation, not a moving target.

This is also the notice I promised on 07-27: "if anything in the contract ever does have to move, it moves as a version event with notice, never as silent drift." This is that notice, thirteen days later than it should have been — better to say so plainly than to pretend the timing was planned.

---

The datasheet (v1.1.0)

SCOPE = the auto-load prose-wash contract ONLY — the pin a memory STORE wires to. CoalWash's .jsonl session-estate (ULTRA) is CC-session-internal and out of scope for a store integration; a prose store never touches it.

Build against this fixed target; you never have to ask us anything.

1. The 4-test input contract (a file is washed only if it passes ALL FOUR)

1. local file — on disk, not a remote/streamed resource.
2. user-owned / authored — the user's own accreted content, not vendor-installed.
3. PROSE — tolerates rewording; never machine-parsed, never executed as instructions. A JSON/YAML body fails this. A prose markdown file with a thin frontmatter passes (frontmatter KEYS are guarded, see §3).
4. ACCRETED — grows by accumulation over time, not deliberate versioned edits.
   Fail any one → never washed (still safe — it just rides untouched). Excluded by construction: skills/commands/hooks/agent-defs (programs) · configs/state/locks/journals (machine-parsed) · other tools' artifacts.

These four are NECESSARY, not SUFFICIENT. Passing all four gets a file considered — whether an individual write/delete actually goes through is a separate, code-enforced admission check on the file's bytes. See §6 for that check in full.

2. Discovery layout (what CoalWash admits — .md only)

CoalWash discovers class-B by structure, admitting .md files in exactly four fixed roles — nothing outside them is ever looked at:

• global governance (CLAUDE.md + its @import closure)
• project governance (the CLAUDE.md up-tree walk)
• rules tree (.claude/rules/**/*.md, cap 500)
• memory store (<projects>/<slug>/memory/*.md; the index is the always-loaded entry)
  Two separate cases for a vault whose file BODY is JSON-in-frontmatter ({"content":"…"}): a vault living in its own directory is in none of the four roles above, so it is never discovered and never touched — no risk, nothing to guard against. If a copy of that same file is placed INSIDE a discovered role (e.g. dropped into the memory store above), it IS discovered — and then refused, not cleaned, at refusal class 6 in §6 (a frontmatter block opening with { is a YAML flow-mapping indicator, not a plain key). To be washed at all, an export must present a PROSE .md body (the machine layer stripped) and land inside one of the four roles above.

3. Fidelity guarantee — the CODE gate (zero STRUCTURED-token loss, proven by mechanical diff)

Every rewrite is diffed; the apply BLOCKS unless every one of these survives (or is named in approvedDrops):

wikilinks (keyed by target) · dates (ISO + DD-Mon-YYYY, canonicalized so a reformat of the same day is not a drop) · versions · links (md-link destination / autolink / bare URL) · frontmatter KEYS (values may be reworded) · fenced code-block content lines · code-spans (backtick, keyed verbatim) · quotes (curly + straight, keyed by the quoted text) · numbers (ratio / percent / ~Nk-N.N forms / comma-grouped counts, keyed comma-less / bare integers ≥2 digits).

MULTISET, not set, semantics: losing a value entirely is a drop, and a value surviving on fewer distinct lines than it occupied is a drop too — an exact-duplicate line is free to remove (it is the mechanical broom's own charter), but three distinct occurrences collapsing to one is caught.

Two named sub-classes ride the same gate: number-precision — an exact numeric token (≥2 significant digits) whose quantity survives only as a strictly coarser rounded/approximated form is reported named (44,192 surviving only as ~44k), not treated as a silent match. evidence-anchor — an evidence token (issue ref, hex id, filename) sitting near a proof-marker ("proven"/"verified"/"measured"/"confirmed"/"100%") in the original must not vanish while the marker still stands in the new text.

Plus encoding-corruption tripwires on the rewritten text: a rewrite must never introduce a decomposed Thai sara-am, a BOM, a zero-width space, or a bidi/zero-width control character. Pre-existing occurrences in the original are warnings, not failures — the gate blocks NEW corruption, it does not punish inherited state.

THE CEILING, stated plainly: the gate is a positionless mention-grain compare. It cannot see two surviving values trading places — a file whose structured tokens read pass 878 / fail 0 rewritten to pass 0 / fail 878 reports zero drops, because nothing vanished and nothing lost a line. Re-pairing/value-swap is out of this gate's reach by construction; it is the semantic layer's job (a human/reviewer read), never something a mechanical diff can catch. Do not read "the gate passed" as "nothing changed meaning."

4. Safety / transactional model

snapshot (verified-at-creation) → external-writer re-read (any foreign change aborts + rolls back) → atomic writes → verify → deletes LAST → commit. Whole-run rollback on any failure.

The pin gate is two-tier, and both tiers refuse — they differ only in blast radius:

• MARKER — pinned: true is actually present and read (matched directly in the block, or as a parsed top-level key — either is enough). This refuses the file and aborts the whole plan (a plan containing an action against an explicit pin is malformed; nothing else in it runs either).
• INCAPACITY — the file's frontmatter block cannot be certified readable (see §6's six refusal classes), or the read itself fails. This refuses that file only; the rest of the plan proceeds unaffected. No pin needs to be present for this to fire — an ordinary file can be incapacity-refused purely on the shape of its bytes.

Either way the refused file is left untouched and safe; nothing is silently degraded. Recovery is by REFERENCE (a bin id / snapshot restores byte-exact; content is never re-authored from memory). Per-project, session-exclusive (.coalwash.lock).

5. Never-do

CoalWash rewrites no program, reads no .jsonl/config/state as wash input, makes no network call, and never reaches into your schema. Store-neutral by construction — it reads THIS pinout, it does not read your internals.

6. What a prose-export mode must present (your side of the bridge)

A --prose export that meets this contract:

• .md file, human-accreted PROSE body (machine/JSON layer stripped). One file per unit you may ever want to pin independently or diagnose precisely — because pin, rewrite, delete and diagnosis are all file-scoped operations in this engine, with no sub-file address anywhere in it: pinned: true is read from exactly ONE frontmatter block per physical file (pin is whole-file or nothing), every mutation targets a whole file (a merge is composite — a delete of the source plus a rewrite of the destination — never a partial in-file edit), and §3's gate diffs at file scope, so a drop inside a 400-entry concatenated file is still CAUGHT but reported as “a drop happened in this file,” not which entry. A single concatenated file is contract-valid — it passes all four tests in §1 and washes correctly; pin and diagnostics then simply apply to the whole file rather than to one entry inside it. Split only where you want that finer grain.
• No NUL bytes anywhere in the file. Refused outright as binary content — flagged, not rewritten. Named for completeness; not a realistic risk for a text export.
• Valid UTF-8, whole file. CoalWash decodes a rewrite target as text, re-encodes, and compares bytes; any byte that does not round trip refuses the WHOLE FILE from rewriting (Thai, CJK and emoji pass by construction — this is a validity check, not a script restriction).
• The file's first 64 characters must be clean — regardless of whether the file has frontmatter at all. CoalWash always reads a fixed 64-character head looking for a frontmatter fence, and refuses the whole file if that head contains a NUL byte or a U+FFFD replacement character — the exact marker a lossy re-encode from another source encoding leaves behind, and the most likely byte a flattener converting FROM another format emits — or a second U+FEFF (byte-order-mark) sitting right after a first, legal one is stripped.
• If the file opens with ---, the opening fence line itself is checked before any block content. It is refused if the tail after --- contains a byte that is neither whitespace nor a printable-ASCII glyph (an invisible or stray byte, such as a non-breaking space — a plain trailing space or tab is fine), if that line ends in a bare CR, or if no matching closing --- is ever found anywhere in the file. A single, unclosed --- at the top of a file is refused HERE, at the fence — it never reaches the six block checks below.
• If the frontmatter block DOES close cleanly, its content is then checked against six readability classes (per-file refusal, §4 INCAPACITY tier):
  1. a bare CR anywhere in the block (mixed line endings)
  2. a TAB in the indentation
  3. a line readable as neither a key, a comment, nor a list item — for example, TWO --- lines with colon-less prose between them (a single UNCLOSED --- is the earlier, fence-level refusal above — not this one)
  4. a key indented less than the block's first line (mixed indentation)
  5. a top-level key containing a character outside printable ASCII
  6. a top-level key opening with a YAML indicator (, [ ] { } & * ! | > % @ ` ?) — a JSON body wrapped as frontmatter ({"content": "..."}) fails here immediately, since the opening { is a flow-mapping indicator, not a plain key
• A file that never opens with --- at all skips every frontmatter check above — but NOT the NUL / UTF-8 / 64-character-head requirements above, which apply to every file regardless of frontmatter.
• Keys present in a passing frontmatter block are preserved verbatim (see §3); values are free prose.

Then CoalWash washes it with zero special-casing on our side.

7. Encrypt-on-export (if your store encrypts at rest)

CoalWash washes plaintext prose. If your vault is encrypted at rest, decrypt on export → hand CoalWash plaintext inside the trust zone → re-encrypt on the way back. The key never enters CoalWash; we hold no key, no ciphertext.

8. Report channel — if CoalWash breaks against your export

File an issue immediately — a wrong skip, a false gate block, anything. No ceremony, no waiting on a release. A partner store's integration report is first-class input.

---

If perseus export --prose (PR #824) needs anything adjusted against §6's requirements, or anything above reads ambiguous, say so here — no ceremony, per §8.