Run public conformance

The conformance runner is implementation-neutral. It invokes an executable as a process, validates its JSON, exit statuses, and filesystem effects, and does not link to the Rust library.

Obtain an immutable suite

Use the source archive or tag for the contract you claim. For Core 0.7.2:

git clone https://github.com/chalkagents/folderbase.git
cd folderbase
git checkout v0.7.2

The conformance runner uses Node.js built-ins and the checked-in schemas and fixtures, so it does not require a repository-level package install.

Run another implementation

Build your implementation as an executable, then pass its path to the public runner:

node protocol/conformance/cli-json-v1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

The executable may be written in Go, TypeScript, Rust, or another language. It must implement the advertised Compatibility Contract v1 process surface. A passing report exits 0 with failed: 0; any incompatible result exits nonzero.

Verify the reference implementation

cargo build --package folderbase-cli --locked
node protocol/conformance/cli-json-v1/run.mjs \
  --implementation ./target/debug/folderbase

What the suite owns

• JSON schemas and portable valid/invalid fixtures;
• canonical digest vectors and sidecars;
• stable command result shapes and error transport;
• exit meanings 0, 1, and 2;
• black-box filesystem behavior for stable initialization, upgrade, validation, protocol checks, and workspace operations.

Passing one suite proves compatibility only with its named contract and protocol profiles. Query/index, template expansion, Change Sets, root reconstruction, and other capabilities require their own advertised profile and conformance closure before third parties can claim them.

Run advertised capability suites

An implementation advertises optional profiles in protocol contract --json. Run every profile known to this checkout that the executable advertises:

node protocol/conformance/capabilities/run.mjs \
  --implementation /absolute/path/to/your-folderbase

Run only the experimental query/index profile:

node protocol/conformance/capabilities/query-index-0.1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

folderbase.query-index@0.1.0 is separate from Compatibility Contract v1 and Folderbase CLI JSON v1. Passing the base suite does not imply query support, and advertising query support commits the implementation to the complete query/index suite.

Run only the experimental daemon stdio profile:

node protocol/conformance/capabilities/daemon-stdio-0.1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

folderbase.daemon-stdio@0.1.0 has ten implementation-neutral black-box cases. They prove root-pinned startup, exact one-shot query delegation, create/edit/move/delete convergence, bounded event coalescing, missing and corrupt index fallback, nested-root isolation, physical-root replacement, bad-frame recovery, subscription loss, EOF, shutdown, and restart.

Run only the stable template-expansion profile:

node protocol/conformance/capabilities/template-expansion-0.1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

folderbase.template-expansion@0.1.0 has nine implementation-neutral black-box cases. They prove typed parser errors, bounded stdin, read-only planning, 10 GiB metadata-first collision handling, exact-root approval binding, no-clobber application, idempotent replay, portable path handling, and handoff to reorganization. Candidate commands are independently bounded and their descendant process trees are terminated on timeout or output overflow.

Run only the stable Change Set profile:

node protocol/conformance/capabilities/change-set-0.1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

folderbase.change-set@0.1.0 has ten implementation-neutral black-box scenarios. They prove least-authority projection privacy, immutable proposals, three-way conflict detection, real one- and two-parent history, stable Object identity, binary and large-file staging, nested-boundary confinement, three crash recovery points, and idempotent replay.

Run only the stable root-reconstruction profile:

node protocol/conformance/capabilities/root-reconstruction-0.1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

folderbase.root-reconstruction@0.1.0 has twelve implementation-neutral black-box cases. They prove exact canonical and legacy Version reconstruction, closed package and reference fidelity, corrupt-input rejection, no-follow package handling, destination no-clobber, unsupported-filesystem preflight, restart and exact replay, and rejection of ambient authority. A passing report exits 0 with passed: 12 and failed: 0.

This stable capability remains optional. Passing its suite proves the named root-reconstruction contract; it does not widen Compatibility Contract v1.

Run only the stable Folder Scope evidence profile:

node protocol/conformance/capabilities/folder-scope-evidence-0.1/run.mjs \
  --implementation /absolute/path/to/your-folderbase

folderbase.folder-scope-evidence@0.1.0 has eleven implementation-neutral black-box cases. They prove exact arbitrary-folder observation, idempotent journal replay, non-genesis Local Head progress, stale-observation refusal, rename continuity, selected-folder and root replacement refusal, attested nested-boundary identity, unsafe invocation, cross-platform escaping-link and unsupported-node refusal, crash recovery, event and journal-continuity tamper refusal, and the closed aggregate journal namespace. Candidate commands run under a bounded whole-process-tree supervisor: Unix uses a detached process group and Windows uses a kill-on-close Job Object assigned before the candidate payload is released. A passing macOS/Linux report exits 0 with passed: 11, not_applicable: 0, and failed: 0; Windows reports passed: 10, not_applicable: 1, and failed: 0 because the FIFO-specific case has no portable Windows fixture.

This stable capability remains optional. Passing its suite proves local filesystem continuity evidence only; it does not create a Folder Scope ID, share, grant, or Cloud authorization.