commonsformat-parser-bootstrap

A minimal parser for Commons Format modules, sized for bootstrapping. Reads enough of the format to load the production parser, runner, and resolver spec modules. Intended for D0 deployment only — local use during initial toolchain bootstrap. The production parser (commonsformat-parser) supersedes this module once available.

Premise

The bootstrap parser exists for one job: read enough of the Commons Format format to load the production parser, eval runner, and resolver spec modules so that those tools can be generated and verified.

It is not a production parser. It does not need to handle every TOML edge case, every Markdown construct, every adversarial input, or any deployment context other than D0. It exists to break the chicken-and-egg of self-hosting and is retired once the production parser is verified.

The bootstrap parser is the only Commons Format module that gets hand-shepherded into existence. Its first instance is generated by a human reading the format-spec prose and prompting a code generator, then iterating against this module's small eval suite until conformance. After that first instance exists, it is used mechanically to read the production parser spec, generate a production parser, and the bootstrap parser retires.

Deployment tier

This module is D0 only. It is intended for local use during toolchain bootstrap. Implementations of this module must not be deployed in any context where they process input from untrusted sources, run as part of CI, or otherwise face adversarial input.

A consumer who needs a parser for production use generates an implementation from commonsformat-parser (the production module), which targets D1 or higher.

Interface

Schema

This module ships a schema.sql declaring the shape of its data. Per §8 this is a shape commitment, not a storage commitment — the generated implementation chooses a runtime representation appropriate to its intent.

-- This DDL describes data shape, not storage. Runtime representation
-- is implementation-defined; choose what is appropriate to the target
-- language and the module's intent. The bootstrap parser is a pure
-- function from a module directory to a partial Module structure;
-- the tables below are the shape of its output, not a database.
--
-- This schema is a deliberate subset of commonsformat-parser's schema.
-- The bootstrap parser handles only the fields needed during bootstrap
-- (metadata, prose with tagged sections, evals, path), as documented in
-- the module's <constraints>.

CREATE TABLE modules (
    path                 TEXT    NOT NULL PRIMARY KEY,
    name                 TEXT    NOT NULL,
    version              TEXT    NOT NULL,
    commonsformat        TEXT    NOT NULL,
    has_eval_suite       BOOLEAN NOT NULL
);

CREATE TABLE tagged_sections (
    module_path          TEXT    NOT NULL,
    tag_name             TEXT    NOT NULL,
    ordinal              INTEGER NOT NULL,
    content              TEXT    NOT NULL,
    PRIMARY KEY (module_path, tag_name, ordinal),
    FOREIGN KEY (module_path) REFERENCES modules (path)
);

CREATE TABLE named_constraints (
    module_path          TEXT    NOT NULL,
    constraint_name      TEXT    NOT NULL,
    description          TEXT    NOT NULL,
    PRIMARY KEY (module_path, constraint_name),
    FOREIGN KEY (module_path) REFERENCES modules (path)
);

CREATE TABLE eval_cases (
    module_path          TEXT    NOT NULL,
    case_name            TEXT    NOT NULL,
    case_class           TEXT    NOT NULL CHECK (case_class IN ('functional', 'adversarial', 'generator_adversary')),
    category             TEXT    NOT NULL,
    input_blob           BLOB    NOT NULL,
    expect_blob          BLOB    NOT NULL,
    PRIMARY KEY (module_path, case_name),
    FOREIGN KEY (module_path) REFERENCES modules (path)
);

CREATE TABLE parse_violations (
    module_path          TEXT    NOT NULL,
    ordinal              INTEGER NOT NULL,
    kind                 TEXT    NOT NULL,
    detail               TEXT    NOT NULL,
    PRIMARY KEY (module_path, ordinal)
);

What the bootstrap parser must handle

What the bootstrap parser is NOT required to handle

Threat model

Bootstrap procedure

A consumer encountering Commons Format for the first time follows this sequence:

1. Clone the canonical repository containing the format-spec, bootstrap parser, parser, runner, and resolver spec modules.
2. Read the format-spec module's commonsformat.md (with eyes, since no parser exists yet).
3. Read this module's commonsformat.md to understand what the bootstrap parser needs to do.
4. Use a code generator to produce a bootstrap parser implementation in the consumer's target language. The format spec provides the grammar; this module provides the narrowed scope.
5. Verify the bootstrap parser against this module's eval suite by running the cases manually (computing expected outputs by hand and comparing) or by writing a simple test harness in the consumer's language.
6. Iterate until the bootstrap parser passes this module's eval suite.
7. Use the bootstrap parser to read the production parser spec module's files.
8. Generate a production parser from the merged spec (format-spec + parser-spec).
9. The production parser inherits the bootstrap eval suite plus the production eval suite, and must pass both. The consumer can verify it manually, by running the bootstrap parser's evals plus the production evals through whatever testing approach they have.
10. Once the production parser passes, retire the bootstrap parser. Subsequent tools (eval runner, resolver) are bootstrapped using the production parser.

The bootstrap parser is a temporary artifact. Its existence is finite and intentional.

Verification

This module's eval suite verifies that a bootstrap parser can correctly read the bootstrap-relevant spec modules (format-spec, production parser, runner, resolver). Cases use real spec module content as fixtures, so a passing bootstrap parser is empirically ready for its narrow job.

A consumer generating a bootstrap parser iterates against this eval suite until conformance. The cases are deliberately few — the bootstrap parser doesn't need extensive testing because it operates on a fixed, trusted set of inputs.

describes commonsformat-parser-bootstrap 0.1.1 · targets commons format 0.2 · generated from release 0.2 · 2026-05-28