cleveragents-core/docs/reference/resource_model.md

Resource Domain Model

A Resource is a registered entry in the Resource Registry representing a physical or virtual asset that plans operate on. Resources are organized in a DAG, linked to projects, and sandboxed during plan execution.

PhysVirt

Value	Description
physical	Real, tangible resource (file, directory, git repository)
virtual	Derived or computed resource (git branch, tree entry)

SandboxStrategy

Value	Description
git_worktree	Isolate via Git worktree
copy_on_write	Isolate via filesystem copy
transaction_rollback	Isolate via database transaction rollback
snapshot	Isolate via snapshot/restore
none	No isolation

ResourceCapabilities

Capability flags derived from the resource type:

Field	Type	Default	Description
readable	bool	True	Whether the resource can be read
writable	bool	True	Whether the resource can be modified
sandboxable	bool	True	Whether the resource supports sandbox isolation
checkpointable	bool	False	Whether the resource supports checkpoint/rollback

Resource Fields

Field	Type	Default	Description
resource_id	str	(required)	Unique ULID identifier (primary key)
name	str | None	None	Namespaced name (NULL for auto-discovered children)
resource_type_name	str	(required)	Namespaced type name (e.g., git-checkout)
classification	PhysVirt	(required)	Physical or virtual classification
description	str | None	None	Human-readable description
properties	dict[str, ...]	{}	Type-specific properties (stored as JSON)
location	str | None	None	Physical location (physical resources only)
content_hash	str | None	None	Content hash for equivalence tracking
sandbox_strategy	SandboxStrategy | None	None	Per-resource sandbox strategy override
capabilities	ResourceCapabilities	ResourceCapabilities()	Capability flags
parents	list[str]	[]	Parent resource_id list (DAG upward references)
children	list[str]	[]	Child resource_id list (DAG downward references)
linked_projects	list[str]	[]	Project names this resource is linked to
created_at	datetime	datetime.now(UTC)	Creation timestamp
updated_at	datetime	datetime.now(UTC)	Last modification timestamp

Constraints:

• resource_id must match ULID format (^[0-9A-HJKMNP-TV-Z]{26}$)
• name if provided must not be empty or whitespace-only
• resource_type_name must not be empty
• location if provided must not be empty or whitespace-only

Properties

• resource.is_physical -- True if classification is physical
• resource.is_virtual -- True if classification is virtual
• resource.can_sandbox -- True if capabilities include sandboxable
• resource.can_checkpoint -- True if capabilities include checkpointable
• resource.is_read_only -- True if capabilities do not include writable

Methods

• resource.with_updated_at() -- Return a frozen copy with updated_at set to now (UTC)

Source Location

• Model: src/cleveragents/domain/models/core/resource.py
• Resource type model: src/cleveragents/domain/models/core/resource_type.py

Related

• Resource Type Model -- Resource type schema definitions
• Database Schema -- Persistence layer