Model Revisions & Lockfiles
Relevant source files
The following files were used as context for generating this wiki page:
Model Revisions and Lockfiles manage the evolution and integrity of Crucible service models over time. These components ensure that generated SDKs and server runtimes remain synchronized with specific versions of the IR (Intermediate Representation). Revisions track the specific Git commit of the tooling, while lockfiles and snapshots preserve the state of the model to prevent accidental breaking changes and verify consistency across builds.
The system uses snapshots to record the IR state of a service, which is then used for compatibility checks and documentation generation, such as upgrade guides. Lockfiles verify that frozen releases have not been tampered with or corrupted after being committed to the repository.
Project Revision Tracking
The project records the specific tooling revision to ensure traceability of generated code. This information includes the Git commit hash and whether the local checkout was dirty during the build process.
Revision Metadata Structure
The system captures the following revision data:
| Field | Type | Description |
|---|---|---|
REVISION | &str | The Git commit hash from which the tooling was built. |
DIRTY | bool | Indicates if the source tree had uncommitted changes at build time. |
Sources: crates/crucible-revision/src/lib.rs:4-7, AGENTS.md
Model Snapshots
A snapshot is a serialized form of the service IR at a specific point in time. The system uses these snapshots as a baseline for directional compatibility checks and to document the history of an API.
Snapshot Content
Snapshots contain the complete lowered IR of a service. This includes:
- Service Metadata: Identification, protocol, and authentication settings.
- Shapes: The data structures, enums, and unions that define the data model.
- Operations: The functional endpoints of the service.
- History: Records of when elements were added, changed, or retired.
Sources: crates/crucible-ir/src/snapshot.rs, AGENTS.md
The diagram shows the flow from model source files to a serialized snapshot and its primary consumers. Sources: AGENTS.md, crates/crucible-ir/src/snapshot.rs
Lockfiles
Lockfiles maintain the integrity of frozen model releases. They act as a security and consistency mechanism to ensure that serialized IR snapshots in a repository match the expected state verified by the developer.
Integrity Verification
A lockfile typically records cryptographic hashes of release files. The crucible-cli uses these to verify that a release has not changed after being "frozen." If the content of a frozen release file deviates from the entry in the lockfile, the system generates a diagnostic error.
Lockfile Operations
- Freeze: Captures the current IR as a JSON snapshot and records its hash.
- Verify: Compares the hash of current snapshot files against the lockfile entries.
- Check: Identifies missing releases that are present on disk but not in the lock.
Sources: crates/crucible-cli/src/sdk/lockfile.rs:1-15, crates/crucible-lsp/tests/protocol.rs:985-1005
Versioning and Upgrades
The system uses snapshots of older releases to generate documentation describing the migration path between versions.
Upgrade Guides
When multiple releases are available, the system compares snapshots to determine what changed. It identifies:
- Renames: Members or shapes that changed names.
- New Requirements: Previously optional members that are now required.
- Additions: New enum values, errors, or operations.
- Retirements: Operations that are no longer served in newer releases.
Sources: crates/crucible-codegen-docs/src/markdown/upgrade.rs, crates/crucible-codegen-docs/tests/upgrade.rs:250-300
The sequence diagram illustrates the process of generating an upgrade guide by comparing two IR snapshots. Sources: crates/crucible-codegen-docs/src/markdown/upgrade.rs
Summary
Model Revisions and Lockfiles provide the foundation for API stability in Crucible. By recording the Git revision of the generator and using lockfiles to verify frozen release snapshots, the project ensures that the evolution of a service model is deterministic and documented. This system enables robust compatibility checking and automated generation of upgrade guides, allowing clients to transition between service versions safely.