commonsformat-lockfile

Lockfile generation and verification for Commons Format. Records the resolved state of a consumer's dependency tree — pinned commits, checksums, and verification results — so that subsequent operations are reproducible and tampering is detectable.

Premise

The lockfile records the resolved state of a consumer's dependency tree. It pins each transitive dependency to a specific commit SHA, records content checksums for tamper detection, and captures verification results so that subsequent regenerations or audits can confirm the same contract was used.

The lockfile structure is specified by format-spec §14. This module specifies the operations that produce and verify lockfiles.

There are two operations:

• Generate: given a resolved dependency tree (modules at specific commits with their content), produce a lockfile.
• Verify: given a lockfile and a set of fetched modules, confirm that the modules match the lockfile's recorded checksums and pinned commits.

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. A lockfile is canonically a TOML
-- file on disk (per the intent and format-spec §14); the tables below
-- are the shape that TOML serializes, not a database the lockfile
-- tool maintains.

CREATE TABLE lockfiles (
    root_module_name     TEXT    NOT NULL PRIMARY KEY,
    root_spec_hash       TEXT    NOT NULL,
    lock_format_version  TEXT    NOT NULL,
    generated_at         TEXT    NOT NULL,
    generator_tool       TEXT    NOT NULL
);

CREATE TABLE locked_modules (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    declared_version     TEXT    NOT NULL,
    resolved_commit_sha  TEXT    NOT NULL,
    fetched_from         TEXT    NOT NULL,
    content_checksum     TEXT    NOT NULL,
    fetched_at           TEXT    NOT NULL,
    PRIMARY KEY (root_module_name, spec_url),
    FOREIGN KEY (root_module_name) REFERENCES lockfiles (root_module_name)
);

CREATE TABLE module_verification (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    deployment_tier      TEXT    NOT NULL CHECK (deployment_tier IN ('D0', 'D1', 'D2', 'D3')),
    PRIMARY KEY (root_module_name, spec_url),
    FOREIGN KEY (root_module_name, spec_url) REFERENCES locked_modules (root_module_name, spec_url)
);

CREATE TABLE module_verification_results (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    generator_id         TEXT    NOT NULL,
    functional           TEXT    NOT NULL CHECK (functional IN ('pass', 'fail', 'skipped', 'unverified')),
    adversarial          TEXT    NOT NULL CHECK (adversarial IN ('pass', 'fail', 'skipped', 'unverified')),
    generator_adversary  TEXT    NOT NULL CHECK (generator_adversary IN ('pass', 'fail', 'skipped', 'unverified')),
    PRIMARY KEY (root_module_name, spec_url, generator_id),
    FOREIGN KEY (root_module_name, spec_url) REFERENCES locked_modules (root_module_name, spec_url)
);

CREATE TABLE module_prose_review (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    reviewed             BOOLEAN NOT NULL,
    reviewed_at          TEXT,
    reviewer             TEXT,
    prose_hash           TEXT,
    PRIMARY KEY (root_module_name, spec_url),
    FOREIGN KEY (root_module_name, spec_url) REFERENCES locked_modules (root_module_name, spec_url)
);

CREATE TABLE module_applied_packs (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    pack_name            TEXT    NOT NULL,
    pack_version         TEXT    NOT NULL,
    pack_commit_sha      TEXT    NOT NULL,
    PRIMARY KEY (root_module_name, spec_url, pack_name),
    FOREIGN KEY (root_module_name, spec_url) REFERENCES locked_modules (root_module_name, spec_url)
);

CREATE TABLE module_applied_overrides (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    element_path         TEXT    NOT NULL,
    override_value       TEXT    NOT NULL,
    PRIMARY KEY (root_module_name, spec_url, element_path),
    FOREIGN KEY (root_module_name, spec_url) REFERENCES locked_modules (root_module_name, spec_url)
);

CREATE TABLE verify_results (
    root_module_name     TEXT    NOT NULL,
    spec_url             TEXT    NOT NULL,
    status               TEXT    NOT NULL CHECK (status IN ('match', 'content-tampered', 'commit-moved', 'missing')),
    detail               TEXT,
    PRIMARY KEY (root_module_name, spec_url)
);

CREATE INDEX locked_modules_by_commit ON locked_modules (resolved_commit_sha);

What the lockfile tool must do

What the lockfile tool must NOT do

Lockfile format

The lockfile structure is fully specified in format-spec §14. Implementations of this module produce and verify lockfiles conforming to that specification.

The lockfile is itself a TOML file (§4 subset). It is hand-readable in principle — for audit and debugging — but is generated and modified by tooling, not edited directly by consumers.

Threat model

Verification

This module's eval suite tests lockfile generation against known inputs (does the produced lockfile have the right structure and content?) and verification against synthetic divergent states (does verify catch a tampered checksum, a moved tag, etc.?).

A consumer generating a lockfile implementation iterates against this eval suite. Once it conforms, the implementation can be composed with the consumer's resolver and fetcher to produce a complete dependency-management toolchain.

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