Define one Porcelain boundary over dirty tool output

[isomorphisms]

Current status — 2026-09-02

RESEARCH. The Porcelain envelope is an architectural proposal over heterogeneous evidence, not permission to rewrite every producer. Retain raw plumbing evidence and keep any future stable envelope additive and inspectable.

---

Idea

Use one final model/human/CI-facing Porcelain boundary over heterogeneous plumbing output instead of teaching every compiler, linker, device runner, provider adapter, test harness, and command wrapper to emit polished diagnostics.

The plumbing is allowed to stay rough. Porcelain makes the envelope stable while preserving the original evidence.

Conceptually:

compiler ─┐
linker   ─┤
adb      ─┤
device   ─┤
tests    ─┤──> Porcelain ──> model / human / CI
git      ─┘

Boundary rule

Porcelain should normalize metadata, not erase the payload.

A useful envelope should be able to carry things like:

• source/tool and operation;
• exit/run status;
• stdout;
• stderr;
• recognized diagnostics/facts when available;
• produced artifacts/receipts;
• explicit failure / skipped / unknown state using the repository's existing result dimensions.

The raw stdout/stderr or equivalent evidence must remain available verbatim. A lossy rewrite such as turning a real linker diagnostic into only link failed defeats the purpose.

Optional summaries are derivative; they must not replace the evidence.

Relation to current ai-ci work

PR #51 already establishes the right precedent for one provider-neutral stdin/stdout/stderr/exit-status boundary, raw receipts, and explicit failure/unknown separation. Porcelain should generalize that architectural idea without changing #51's canonical Blackball verdict vocabulary or creating a second result vocabulary.

This should fit the existing ai-ci ownership boundary: ai-ci owns the stable contract/validation; producer repositories emit evidence into it rather than each inventing their own model-facing cleanup layer.

Acceptance direction

• one documented stable envelope/contract;
• raw evidence preserved exactly enough for a model or human to inspect the original failure;
• normalized facts kept separate from diagnosis/summary;
• failure and epistemic unknown remain distinct;
• hostile fixtures include ugly, partial, interleaved, or unfamiliar diagnostics;
• adapters are not required to prettify their native messages;
• no silent fallback from unrecognized output to success;
• existing result/verdict contracts remain authoritative rather than being duplicated.

Working name: Porcelain, in the Git sense: stable upper-layer output over heterogeneous plumbing.

Cross-repository Catfood integration note: isomorphisms/catfood#21.