Package com.egoge.ai.atlas.plugin

Class ReleaseSnapshots

java.lang.Object
com.egoge.ai.atlas.plugin.ReleaseSnapshots
public final class ReleaseSnapshots extends Object
Releases the accepted contract as an immutable snapshot, <releases>/<version>/, and verifies a build's contract against one already released. The engine behind the Gradle plugin's agenticRelease and agenticReleaseVerify; it reads and writes only the files it is given, with no network, database or model call, and writes no timestamp, host or path.

A release directory holds:

  • "api.ir.json": the accepted baseline, byte for byte, which the build's IR must equal;
  • openapi-v<major>.json, the OpenAPI document of the released major, when generated;
  • "mcp-tools.json", when generated;
  • "contract-diff.json": the comparison with the previous release, in the gate's form;
  • "CHANGELOG.md": the release's changelog section;
  • "release.json": the ReleaseManifest, with a SHA-256 of every other file.
Each release keeps the irVersion it was written with; IrJson.read(java.nio.file.Path) migrates an older one in memory, so released files never change when ai-atlas is upgraded.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    ReleaseSnapshots.Outcome
    A release made.
    static final class 
    ReleaseSnapshots.ReleaseException
    A release that cannot be made, or a released snapshot that fails verification.
    static final record 
    ReleaseSnapshots.Request
    What to release.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    CHANGELOG_FILE
    The release's changelog section.
    static final String
    DIFF_FILE
    The comparison with the previous release, in the gate's contract-diff.json form.
    static final String
    IR_FILE
    The released Contract IR, byte-identical to the accepted baseline.
    static final String
    MANIFEST_FILE
    The release manifest.
    static final String
    MCP_TOOLS_FILE
    The MCP tool specifications, when ai.atlas.constraints generated them.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    openApiFile(int apiMajor)
    The file name of a major's OpenAPI document in a release.
    static ReleaseSnapshots.Outcome
    release(Path releases, Path changelog, ReleaseSnapshots.Request request)
    Releases the accepted contract to <releases>/<version>/, then regenerates the aggregate changelog.
    static String
    sha256(byte[] bytes)
    The lowercase hexadecimal SHA-256 of bytes.
    static void
    verifyBuild(Path releases, Path changelog, String version, byte[] emittedIr, Map<String,byte[]> artifacts, String contractResourcesJson)
    Verifies the release history's internal consistency, and that version's release is exactly what the build produced (E2, D8.2, plan §3.5 step 6, OQ-4): the IR canonically equal, every snapshotted artifact byte for byte, the same set of snapshotted files present in both (naming an artifact the build produces the release does not, or the reverse), and the released contractResources.configuration structurally equal to the build's effective configuration.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • IR_FILE

      public static final String IR_FILE
      The released Contract IR, byte-identical to the accepted baseline.
      See Also:

    • DIFF_FILE

      public static final String DIFF_FILE
      The comparison with the previous release, in the gate's contract-diff.json form.
      See Also:

    • CHANGELOG_FILE

      public static final String CHANGELOG_FILE
      The release's changelog section.
      See Also:

    • MANIFEST_FILE

      public static final String MANIFEST_FILE
      The release manifest.
      See Also:

    • MCP_TOOLS_FILE

      public static final String MCP_TOOLS_FILE
      The MCP tool specifications, when ai.atlas.constraints generated them.
      See Also:

  • Method Details

    • openApiFile

      public static String openApiFile(int apiMajor)
      The file name of a major's OpenAPI document in a release.
      Parameters:
      apiMajor - the major
      Returns:
      openapi-v<major>.json

    • release

      public static ReleaseSnapshots.Outcome release(Path releases, Path changelog, ReleaseSnapshots.Request request) throws ReleaseSnapshots.ReleaseException, IOException
      Releases the accepted contract to <releases>/<version>/, then regenerates the aggregate changelog. Nothing is written when the release fails. The release directory is written to a temporary sibling and moved into place in one step.
      Parameters:
      releases - the directory of releases
      changelog - the aggregate changelog to regenerate
      request - what to release
      Returns:
      the release made
      Throws:
      ReleaseSnapshots.ReleaseException - if the version is not a release version or is already released, the build's IR is not the accepted baseline, a released snapshot fails verification, the version or major goes backwards, or the policy fails
      IOException - if a file cannot be read or written

    • verifyBuild

      public static void verifyBuild(Path releases, Path changelog, String version, byte[] emittedIr, Map<String,byte[]> artifacts, String contractResourcesJson) throws ReleaseSnapshots.ReleaseException, IOException
      Verifies the release history's internal consistency, and that version's release is exactly what the build produced (E2, D8.2, plan §3.5 step 6, OQ-4): the IR canonically equal, every snapshotted artifact byte for byte, the same set of snapshotted files present in both (naming an artifact the build produces the release does not, or the reverse), and the released contractResources.configuration structurally equal to the build's effective configuration. Reads no git; agenticReleaseVerify proves the tag and HEAD separately, in the plugin.
      Parameters:
      releases - the directory of releases
      changelog - the aggregate changelog, checked by ReleaseSnapshotHistory.checkConsistency(java.nio.file.Path, java.nio.file.Path)
      version - the version the build claims to be, MAJOR.MINOR.PATCH
      emittedIr - the IR the build emitted, or the empty document when it declares nothing
      artifacts - the build's snapshotted artifacts ( ContractResources.snapshotted), keyed by snapshot file name, the IR included under "api.ir.json"
      contractResourcesJson - the build's class output's contract-resources manifest, verbatim
      Throws:
      ReleaseSnapshots.ReleaseException - if the history is inconsistent, the version is not released, or the build differs from its release, each naming the difference
      IOException - if a file cannot be read

    • sha256

      public static String sha256(byte[] bytes)
      The lowercase hexadecimal SHA-256 of bytes.
      Parameters:
      bytes - the content
      Returns:
      64 hexadecimal digits