commonsformat-resolver

A resolver for Commons Format module dependencies. Takes a root module and produces a merged virtual spec by walking the dependency graph and applying the merge algorithm defined by the format.

Premise

The resolver takes a root module and the set of modules reachable from it via depends_on and extends, and produces a merged virtual spec per the merge algorithm defined by the format.

The resolver does not fetch dependencies from disk or network. It operates on already-loaded modules. Fetching is a separate concern handled by the fetcher (a separate spec module). The resolver assumes its input is a set of parsed modules and a description of which depends on which.

The resolver does not generate implementations. The merged virtual spec it produces is the contract a generator consumes; what the generator does with it is the generator's concern.

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 resolver is a pure function
-- over already-parsed modules; the tables below are the shape of its
-- inputs and outputs, not a persistent store.

CREATE TABLE graph_nodes (
    module_id            TEXT    NOT NULL PRIMARY KEY,
    spec_url             TEXT    NOT NULL,
    version              TEXT    NOT NULL,
    resolved_commit_sha  TEXT
);

CREATE TABLE graph_edges (
    from_module          TEXT    NOT NULL,
    to_module            TEXT    NOT NULL,
    edge_kind            TEXT    NOT NULL CHECK (edge_kind IN ('depends_on', 'extends')),
    PRIMARY KEY (from_module, to_module, edge_kind),
    FOREIGN KEY (from_module) REFERENCES graph_nodes (module_id),
    FOREIGN KEY (to_module)   REFERENCES graph_nodes (module_id)
);

CREATE TABLE merged_specs (
    root_module          TEXT    NOT NULL PRIMARY KEY,
    merged_intent        TEXT    NOT NULL,
    merged_avoid         TEXT    NOT NULL,
    merged_threat_model  TEXT    NOT NULL,
    root_interface       TEXT    NOT NULL,
    completed_at_ms      INTEGER NOT NULL
);

CREATE TABLE merged_constraints (
    root_module          TEXT    NOT NULL,
    constraint_name      TEXT    NOT NULL,
    description          TEXT    NOT NULL,
    contributing_module  TEXT    NOT NULL,
    PRIMARY KEY (root_module, constraint_name),
    FOREIGN KEY (root_module) REFERENCES merged_specs (root_module)
);

CREATE TABLE merged_examples (
    root_module          TEXT    NOT NULL,
    example_name         TEXT    NOT NULL,
    content              TEXT    NOT NULL,
    contributing_module  TEXT    NOT NULL,
    PRIMARY KEY (root_module, example_name),
    FOREIGN KEY (root_module) REFERENCES merged_specs (root_module)
);

CREATE TABLE merged_eval_cases (
    root_module          TEXT    NOT NULL,
    case_name            TEXT    NOT NULL,
    case_class           TEXT    NOT NULL CHECK (case_class IN ('functional', 'adversarial', 'generator_adversary')),
    contributing_module  TEXT    NOT NULL,
    PRIMARY KEY (root_module, case_name),
    FOREIGN KEY (root_module) REFERENCES merged_specs (root_module)
);

CREATE TABLE merged_properties (
    root_module          TEXT    NOT NULL,
    property_name        TEXT    NOT NULL,
    property_value       TEXT    NOT NULL,
    contributing_module  TEXT    NOT NULL,
    PRIMARY KEY (root_module, property_name),
    FOREIGN KEY (root_module) REFERENCES merged_specs (root_module)
);

CREATE TABLE applied_overrides (
    root_module          TEXT    NOT NULL,
    element_path         TEXT    NOT NULL,
    override_value       TEXT    NOT NULL,
    declaring_module     TEXT    NOT NULL,
    PRIMARY KEY (root_module, element_path),
    FOREIGN KEY (root_module) REFERENCES merged_specs (root_module)
);

CREATE TABLE resolution_errors (
    root_module          TEXT    NOT NULL,
    ordinal              INTEGER NOT NULL,
    error_kind           TEXT    NOT NULL CHECK (error_kind IN ('cycle', 'conflict', 'unmet-version', 'missing-dependency', 'merge-bound-exceeded')),
    element_path         TEXT,
    contributing_modules TEXT,
    detail               TEXT    NOT NULL,
    PRIMARY KEY (root_module, ordinal)
);

What the resolver does

What the resolver does not do

Merge contributions

The merge algorithm is specified by format-spec §11.4. The resolver implements that algorithm; the format is canonical.

The resolver-specific concerns — how conflicts are reported, how overrides are applied, how the merge result is structured for downstream consumption — are described in subsequent sections of this spec. Those are implementation contracts the resolver adds on top of the format's algorithmic specification.

Conflicts and overrides

[[depends_on]]
spec = "..."
version = "..."

[depends_on.overrides]
constraints.uses-redis = "ignore"
properties.requires_logging = false

Extension semantics

Threat model

Verification

This module's eval suite tests the resolver on synthetic dependency graphs with known expected merges. Cases cover the merge algorithm itself, conflict detection, override application, cycle detection, and version constraint resolution.

A consumer generating a resolver implementation iterates against this module's evals until conformance. They then have a working resolver that can be composed with their parser and eval runner to form a complete Commons Format toolchain.

describes commonsformat-resolver 0.1.3 · targets commons format 0.2 · generated from release 0.2 · 2026-05-28