Bundle Format

{/* AUTO-GENERATED by scripts/sync-reference-schemas.mjs - do not edit by hand. */}

Source inputs:

• ../greentic-bundle/crates/greentic-bundle-reader/src/lib.rs
• ../greentic-bundle/crates/greentic-bundle-reader/README.md
• ../greentic-bundle/docs/cli.md

Current format version: gtbundle-v1

.gtbundle artifacts are deterministic SquashFS bundles produced by greentic-bundle build. The typed reader also supports normalized unpacked build directories, which are the build-state form used before the final SquashFS artifact is materialized.

Workspace and artifact files

Path	Purpose
bundle.yaml	Authored bundle workspace root.
bundle.lock.json	Resolved lock contract for catalogs, app packs, extension providers, tool version, cache policy, and build markers.
tenants/<tenant>/tenant.gmap	Tenant access map.
tenants/<tenant>/teams/<team>/team.gmap	Team access map.
resolved/... and state/resolved/...	Generated resolved outputs.
state/setup/*.json	Bundle-owned setup state.
state/build/<bundle>/normalized/	Normalized build directory that carries bundle-manifest.json, bundle-lock.json, bundle.yaml, materialized packs, providers, resolved files, and setup files.
dist/<bundle>.gtbundle	Default final SquashFS artifact path.

Reader contract

greentic-bundle-reader is the read-only bundle reader for greentic-bundle.

It currently supports:

• opening built .gtbundle SquashFS artifacts
• opening normalized unpacked build directories
• validating the basic manifest/lock structure
• exposing a stable typed runtime surface for bundle metadata, app packs, extension providers, catalogs, resolved files, and setup state files

The crate is kept inside the workspace for now so operator/runtime consumers can adopt a stable bundle-reading API before it is split or published independently.

The reader validates basic manifest/lock structure before exposing the runtime surface. Validation checks include format version, matching bundle_id, matching requested_mode, .gtbundle artifact extension, expected root file names, and setup-state consistency between manifest and lock.

Typed runtime surface

pub struct BundleManifest {
    pub format_version: String,
    pub bundle_id: String,
    pub bundle_name: String,
    pub requested_mode: String,
    pub locale: String,
    pub artifact_extension: String,
    #[serde(default)]
    pub generated_resolved_files: Vec<String>,
    #[serde(default)]
    pub generated_setup_files: Vec<String>,
    #[serde(default)]
    pub app_packs: Vec<String>,
    #[serde(default)]
    pub extension_providers: Vec<String>,
    #[serde(default)]
    pub catalogs: Vec<String>,
    #[serde(default)]
    pub hooks: Vec<String>,
    #[serde(default)]
    pub subscriptions: Vec<String>,
    #[serde(default)]
    pub capabilities: Vec<String>,
    #[serde(default)]
    pub resolved_targets: Vec<BundleResolvedTargetView>,
}

pub struct BundleLock {
    pub schema_version: u32,
    pub bundle_id: String,
    pub requested_mode: String,
    pub execution: String,
    pub cache_policy: String,
    pub tool_version: String,
    pub build_format_version: String,
    pub workspace_root: String,
    pub lock_file: String,
    pub catalogs: Vec<CatalogLockEntry>,
    pub app_packs: Vec<DependencyLock>,
    pub extension_providers: Vec<DependencyLock>,
    pub setup_state_files: Vec<String>,
}

pub struct BundleRuntimeSurface {
    pub format_version: String,
    pub bundle_id: String,
    pub bundle_name: String,
    pub requested_mode: String,
    pub locale: String,
    pub execution: String,
    pub cache_policy: String,
    pub workspace_root: String,
    pub lock_file: String,
    pub app_packs: Vec<BundleDependencyView>,
    pub extension_providers: Vec<BundleDependencyView>,
    pub catalogs: Vec<BundleCatalogView>,
    pub hooks: Vec<String>,
    pub subscriptions: Vec<String>,
    pub capabilities: Vec<String>,
    pub resolved_targets: Vec<BundleResolvedTargetView>,
    pub generated_resolved_files: Vec<BundleFileView>,
    pub generated_setup_files: Vec<BundleFileView>,
}

pub struct BundleResolvedTargetView {
    pub path: String,
    pub tenant: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub team: Option<String>,
    pub default_policy: String,
    pub tenant_gmap: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub team_gmap: Option<String>,
    #[serde(default)]
    pub app_pack_policies: Vec<BundleResolvedReferencePolicyView>,
}

pub struct BundleResolvedReferencePolicyView {
    pub reference: String,
    pub policy: String,
}

Reader entry points

pub fn open_artifact(path: &Path) -> Result<OpenedBundle, BundleReadError>

pub fn open_build_dir(path: &Path) -> Result<OpenedBundle, BundleReadError>

Build/export notes

The bundle CLI source document currently records these format-relevant semantics:

• build writes normalized metadata under state/build/<bundle>/normalized before creating the final .gtbundle.
• .gtbundle artifacts are real SquashFS artifacts produced via mksquashfs.
• export consumes a normalized build directory instead of rebuilding the workspace.
• doctor validates either a workspace or an artifact.
• inspect reads either a workspace or an artifact and emits stable JSON.
• Artifact reads use greentic-bundle-reader so runtime consumers do not parse raw SquashFS layout directly.

Source CLI notes

This page is generated from the bundle reader plus the bundle CLI baseline document. The source baseline is intentionally not duplicated in full here; rerun the generator when the upstream greentic-bundle reader or CLI notes change.