@makerclay/conformance

License: First Million Stays Yours License. Free to use, no matter who you are or what you use it for. It only ever costs money if you sell or host a product built on this software and that product makes you more than $1M in a year. Under that line you owe nothing, sign nothing, register nowhere.

| Free under | Above it | Becomes MIT | |---|---|---| | $1M/year from products built on it | 3% of the excess | 2028-02-20 (this version) |

Plain answers: hyperclay.com/host-program · binding text in LICENSE · questions: [email protected]

The Malleable Document host conformance suite, as a headless runner any host in any language can point at itself.

npx --package @makerclay/conformance host-conformance http://localhost:4321

It talks nothing but HTTP. If your host answers POST /_/save and serves the document back, this will tell you whether it is a conformant host or merely a server that happens to write files.

What it checks

| | | |---|---| | H1 | the bytes a save sends are the bytes a read returns, across every canonical fixture | | H2 | serving never mutates the stored document (200 reads, digest unchanged) | | H3 | an injected savetoken round-trips and never reaches the stored document | | H4 | documentid round-trips, and a copy gets a fresh one | | H5 | /_/meta answers a capability document or a clean 404, never anything else | | H6 | /_/meta cannot be used to probe for documents a caller cannot see | | H7 | a stale If-Match refuses with 412 and writes nothing | | H8 | cross-origin saves are refused, and Origin: null without a token is refused | | H9 | path traversal is refused in every spelling | | H10 | a non-HTML body is 422 and a JSON envelope is 415 | | H11 | an over-limit body is 413 with no partial write | | H12 | a kill mid-write leaves the previous document intact |

Assertions for capabilities a host does not advertise report SKIP rather than FAIL: H7 is skipped by a host without conditional, H3 by a host that mints no save tokens, H11 by a host that advertises no size limit. H12 needs to kill the host process, which no HTTP client can do, so it is always skipped remotely and belongs in the host's own test suite as fault injection.

Options

host-conformance <base-url> [options]

  --doc <path>        probe document to write (default /_conformance-probe.html)
  --fixtures <dir>    conformance fixtures directory
  --only <ids>        comma-separated assertion ids, e.g. --only H1,H7
  --json              print the report as JSON

It writes. The probe document is saved to repeatedly and a -copy sibling is created. Point it at a development host.

As a library

import { runConformance, formatReport } from '@makerclay/conformance';

const report = await runConformance({ base: 'http://localhost:4321', doc: '/probe.html' });
console.log(formatReport(report));
process.exit(report.ok ? 0 : 1);

runConformance also takes a faultInjector, which is how a host runs H12 against a process it controls.