Struct LockedResource 

pub struct LockedResource {

    pub name: String,
    pub source: Option<String>,
    pub url: Option<String>,
    pub path: String,
    pub version: Option<String>,
    pub resolved_commit: Option<String>,
    pub checksum: String,
    pub context_checksum: Option<String>,
    pub installed_at: String,
    pub dependencies: Vec<String>,
    pub resource_type: ResourceType,
    pub tool: Option<String>,
    pub manifest_alias: Option<String>,
    pub applied_patches: BTreeMap<String, Value>,
    pub install: Option<bool>,
    pub variant_inputs: VariantInputs,
    pub is_private: bool,
    pub approximate_token_count: Option<u64>,
}

A locked resource (agent or snippet) with resolved version and integrity information.

Represents a specific resource file that has been resolved from either a source repository or local filesystem. Contains all information needed to verify the exact version and integrity of the installed resource.

Local vs Remote Resources

Remote resources (from Git repositories) include:

• source: Source repository name
• url: Repository URL
• version: Original version constraint
• resolved_commit: Exact commit containing the resource

Local resources (from filesystem) omit these fields since they don’t involve Git repositories.

Integrity Verification

All resources include a SHA-256 checksum for integrity verification. The checksum is calculated from the file content after installation and can be used to detect corruption or tampering.

Examples

Remote resource in TOML format:

[[agents]]
name = "example-agent"
source = "community"
url = "https://github.com/example/repo.git"
path = "agents/example.md"
version = "^1.0"
resolved_commit = "a1b2c3d4e5f6..."
checksum = "sha256:abcdef123456..."
installed_at = "agents/example-agent.md"

Local resource in TOML format:

[[agents]]
name = "local-helper"
path = "../local/helper.md"
checksum = "sha256:fedcba654321..."
installed_at = "agents/local-helper.md"

Fields

name: String

Resource name from the manifest.

This corresponds to keys in the [agents] or [snippets] sections of the manifest. Resources are uniquely identified by the combination of (name, source), allowing multiple sources to provide resources with the same name.

source: Option<String>

Source repository name for remote resources.

References a source defined in the [sources] section of the manifest. This field is None for local resources that don’t come from Git repositories.

Omitted from TOML serialization when None.

url: Option<String>

Source repository URL for remote resources.

The full Git repository URL where this resource originates. This field is None for local resources.

Omitted from TOML serialization when None.

path: String

Path to the resource file.

For remote resources, this is the relative path within the source repository. For local resources, this is the filesystem path (may be relative or absolute).

version: Option<String>

Resolved version for the resource.

This stores the resolved version tag (e.g., “v1.0.0”, “main”) that was matched by the version constraint in agpm.toml. Like Cargo.lock, this provides human-readable context while resolved_commit ensures reproducibility. For local resources or resources without versions, this field is None.

Omitted from TOML serialization when None.

resolved_commit: Option<String>

Resolved Git commit hash for remote resources.

The exact 40-character SHA-1 commit hash where this resource was found. This ensures reproducible installations even if the version constraint could match multiple commits. For local resources, this field is None.

Omitted from TOML serialization when None.

checksum: String

SHA-256 checksum of the installed file content.

Used for integrity verification to detect file corruption or tampering. The format is “sha256:” followed by the hexadecimal hash.

Example: “sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3”

context_checksum: Option<String>

SHA-256 checksum of the template rendering context (NEW FIELD).

This is None for resources that don’t use templating, and Some(checksum) for templated resources. The checksum is computed from the canonical serialization of the template context (dependencies, variant_inputs, etc.) and is used to detect when template inputs change, even if the rendered output happens to be identical.

installed_at: String

Installation path relative to the project root.

Where the resource file is installed within the project directory. This path is always relative to the project root and uses forward slashes as separators for cross-platform compatibility.

Examples: “agents/example-agent.md”, “snippets/util-snippet.md”

dependencies: Vec<String>

Dependencies of this resource.

Lists the direct dependencies that this resource requires, including both manifest dependencies and transitive dependencies discovered from the resource file itself. Each dependency is identified by its resource type and name (e.g., “agents/helper-agent”, “snippets/utils”).

This field enables dependency graph analysis and ensures all required resources are installed. It follows the same model as Cargo.lock where each package lists its dependencies.

Always included in TOML serialization, even when empty, to match Cargo.lock format.

resource_type: ResourceType

Resource type (agent, snippet, command, etc.)

This field is populated during deserialization based on which TOML section the resource came from ([[agents]], [[snippets]], etc.) and is used internally for determining the correct lockfile section when adding/updating entries.

It is never serialized to the lockfile - the section header provides this information.

tool: Option<String>

Tool type for multi-tool support (claude-code, opencode, agpm, custom).

Specifies which target AI coding assistant tool this resource is for. This determines where the resource is installed and how it’s configured.

When None during deserialization, will be set based on resource type’s default (e.g., snippets default to “agpm”, others to “claude-code”).

Always serialized for clarity and to avoid ambiguity.

manifest_alias: Option<String>

Original manifest alias for pattern-expanded dependencies.

When a pattern dependency (e.g., agents/helpers/*.md with alias “all-helpers”) expands to multiple files, each file gets its own lockfile entry with a unique name (e.g., “helper-alpha”, “helper-beta”). The manifest_alias field preserves the original pattern alias so patches defined under that alias can be correctly applied to all matched files.

For non-pattern dependencies, this field is None since name already represents the manifest alias.

Example lockfile entry for pattern-expanded resource:

[[agents]]
name = "helper-alpha"                    # Individual file name
manifest_alias = "all-helpers"           # Original pattern alias
path = "agents/helpers/helper-alpha.md"
...

This enables pattern patching: all files matched by “all-helpers” pattern can have patches applied via [patch.agents.all-helpers] in the manifest.

Omitted from TOML serialization when None (for non-pattern dependencies).

applied_patches: BTreeMap<String, Value>

Applied patches from manifest configuration.

Contains the key-value pairs that were applied to this resource’s metadata via [patch.<resource-type>.<alias>] sections in agpm.toml or agpm.private.toml.

This enables reproducible installations and provides visibility into which resources have been patched.

Omitted from TOML serialization when empty.

install: Option<bool>

Whether this dependency should be installed to disk.

When false, the dependency is resolved, fetched, and tracked in the lockfile, but the file is not written to the project directory. Instead, its content is made available in template context via agpm.deps.<type>.<name>.content.

This is useful for snippet embedding use cases where you want to include content inline rather than as a separate file.

Defaults to true (install the file) for backwards compatibility.

Omitted from TOML serialization when None or true.

variant_inputs: VariantInputs

Variant inputs for template rendering.

Stores the template variable overrides that were specified in the manifest for this dependency. These overrides are applied when rendering templates to allow customization of generic templates for specific use cases.

Encapsulates both the JSON value and its pre-computed hash for identity comparison. The hash is not serialized and is recomputed after deserialization.

is_private: bool

Whether this resource came from agpm.private.toml.

Private resources:

• Install to {resource_path}/private/ subdirectory
• Are tracked in agpm.private.lock instead of agpm.lock
• Don’t affect team lockfile consistency

Omitted from TOML serialization when false (the default).

approximate_token_count: Option<u64>

Approximate token count of the installed file content.

Computed using cl100k BPE encoding (compatible with Claude/GPT-4). Used for tracking context usage and warning on large resources.

Omitted from TOML serialization when None.

Implementations

impl LockedResource

pub fn id(&self) -> ResourceId

Unique identifier combining name, source, tool, and variant_inputs hash.

Canonical method for resource identification in checksum updates and lookups.

pub fn matches_id(&self, id: &ResourceId) -> bool

Check if resource matches ResourceId by comparing name, source, tool, and variant_inputs hash.

Variant_inputs hash is part of identity - same resource with different variant_inputs produces different artifacts and must be tracked separately.

pub fn parsed_dependencies( &self, ) -> impl Iterator<Item = LockfileDependencyRef> + '_

Parse the dependencies field into structured lockfile dependency references.

Returns an iterator over successfully parsed dependency references. Invalid references are logged as warnings and skipped.

This is the centralized way to parse lockfile dependencies, ensuring consistent handling of the lockfile format across the codebase.

Examples

for dep in resource.parsed_dependencies() {
    println!("Dependency: {} (type: {})", dep.path, dep.resource_type);
}

pub fn display_name(&self) -> &str

Get the display name for user-facing contexts.

Returns the manifest_alias if present (for direct manifest dependencies or pattern-expanded resources), otherwise returns the canonical name. This provides the most user-friendly name for display purposes.

Examples

// Direct dependency with custom manifest name
let resource = LockedResource {
    name: "ai-helper".to_string(),  // canonical name from path
    manifest_alias: Some("my-ai-helper".to_string()),  // user's chosen name
    // ... other fields
};
assert_eq!(resource.display_name(), "my-ai-helper");

// Pattern-expanded dependency
let resource = LockedResource {
    name: "helper-alpha".to_string(),  // canonical name
    manifest_alias: Some("all-helpers".to_string()),  // pattern alias
    // ... other fields
};
assert_eq!(resource.display_name(), "all-helpers");

// Transitive dependency (no manifest_alias)
let resource = LockedResource {
    name: "utils".to_string(),  // canonical name
    manifest_alias: None,
    // ... other fields
};
assert_eq!(resource.display_name(), "utils");

pub fn lookup_name(&self) -> &str

Get the lookup name for patch resolution and manifest lookups.

Returns the manifest_alias if present (for direct manifest dependencies or pattern-expanded resources), otherwise returns the canonical name. This ensures patches are looked up using the correct manifest key.

Examples

// Direct dependency - patches defined under manifest key
let resource = LockedResource {
    name: "ai-helper".to_string(),  // canonical name from path
    manifest_alias: Some("my-ai-helper".to_string()),  // manifest key
    // ... other fields
};
assert_eq!(resource.lookup_name(), "my-ai-helper");

// Transitive dependency - no manifest key
let resource = LockedResource {
    name: "utils".to_string(),  // canonical name
    manifest_alias: None,
    // ... other fields
};
assert_eq!(resource.lookup_name(), "utils");

pub fn is_direct_manifest(&self) -> bool

Check if this resource represents a direct manifest dependency.

Returns true if this resource was directly specified in the manifest (not discovered through transitive dependencies or pattern expansion).

Examples

// Direct dependency from manifest
let resource = LockedResource {
    name: "ai-helper".to_string(),
    manifest_alias: Some("my-ai-helper".to_string()),
    // ... other fields
};
assert!(resource.is_direct_manifest());

// Transitive dependency
let resource = LockedResource {
    name: "utils".to_string(),
    manifest_alias: None,
    // ... other fields
};
assert!(!resource.is_direct_manifest());

pub fn is_pattern_expanded(&self) -> bool

Check if this resource came from a pattern expansion.

Returns true if this resource was created by expanding a pattern dependency from the manifest.

Examples

// Pattern-expanded resource
let resource = LockedResource {
    name: "helper-alpha".to_string(),
    manifest_alias: Some("all-helpers".to_string()),
    // ... other fields
};
assert!(resource.is_pattern_expanded());

// Direct dependency (single file)
let resource = LockedResource {
    name: "ai-helper".to_string(),
    manifest_alias: None,  // Will change after implementation
    // ... other fields
};
assert!(!resource.is_pattern_expanded());

pub fn is_local(&self) -> bool

Check if this is a local resource (not from a Git repository).

Local resources are filesystem-based dependencies that don’t come from Git repositories. They are identified by having no resolved_commit field (or an empty one), indicating they weren’t resolved from a Git ref.

Local resources require different handling:

• Source paths are resolved relative to manifest directory
• No worktree checkouts are needed
• Files are read directly from the filesystem

Examples

// Local resource (no resolved_commit)
let local = LockedResource {
    resolved_commit: None,
    // ... other fields
};
assert!(local.is_local());

// Remote resource (has resolved_commit)
let remote = LockedResource {
    resolved_commit: Some("abc123def456789012345678901234567890abcd".to_string()),
    // ... other fields
};
assert!(!remote.is_local());

Trait Implementations

impl Clone for LockedResource

fn clone(&self) -> LockedResource

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LockedResource

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for LockedResource

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for LockedResource

fn eq(&self, other: &LockedResource) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for LockedResource

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for LockedResource