Architecture Data State and Trust

Data, State, and Trust

Prev: Execution Flow | Up: Architecture | Next: Home

This page explains the persistent data ReqPack keeps, how trust is enforced, and where state lives.

Main State Areas

Config state

• config.lua
• remote.lua

Human-managed baseline behavior.

Registry state

• registry DB under registry.databasePath
• optional registry.lua
• Git-backed registry cache under XDG data repos

This state defines known plugins, aliases, hashes, trust metadata, and source mapping.

Materialized plugin state

• registry.pluginDirectory/<plugin>/...

This is where refreshed plugin bundles end up before loading, typically with metadata.json, reqpack.lua, run.lua, and scripts/.

Transaction state

• transaction DB under execution.transactionDatabasePath

Used for mutating-run recovery and commit tracking.

History state

• history JSONL and installed-state data under history.historyPath

Used for snapshots and ownership tracking.

Native rqp installed state

• rqp.statePath/<name>/<identity>/...

Used only by the built-in native package manager.

Security state

• OSV DB under security.osvDatabasePath
• cache and index under security.cachePath and security.indexPath

Used for vulnerability sync and lookups.

Registry Trust Model

Registry records can carry metadata about what a plugin is allowed or expected to do.

Important fields:

• role
• capabilities
• ecosystemScopes
• writeScopes
• networkScopes
• privilegeLevel
• scriptSha256
• bootstrapSha256

When security.requireThinLayer = true, ReqPack checks more aggressively that:

• the registry record passes thin-layer trust rules,
• the runtime plugin metadata matches the trust record,
• script and bootstrap hashes match expectations.

This is how ReqPack prevents registry metadata and runtime behavior from drifting apart silently.

Runtime exec policy note:

• plugin load-time trust checks use security.requireThinLayer
• command-time exec/write denial only happens when both security.requireThinLayer = true and execution.checkVirtualFileSystemWrite = true

Plugin Identity and Alias Resolution

ReqPack resolves plugin names through:

1. registry aliases,
2. planner systemAliases,
3. normalized lowercase names.

That means naming compatibility can be handled without duplicating plugin implementations.

Native rqp Package State Model

Each installed native package stores:

• original package metadata,
• original reqpack.lua,
• source information in source.json,
• tracked artifact manifest in manifest.json,
• copied scripts in scripts/.

This is what makes remove safe and deterministic for rqp packages.

Audit Data Model

ReqPack audit is driven by:

• planned package graph,
• ecosystem mapping,
• resolved package versions,
• local vulnerability database state,
• security policy thresholds.

Weak spots to be aware of:

• missing ecosystem mapping lowers fidelity,
• unresolved versions lower fidelity,
• stale or unavailable OSV feed can block strict policies.

Repository Data Model for Plugins

Per-ecosystem repository definitions are loaded from config.repositories and passed to plugins via context.repositories.

This lets plugins like Maven or internal wrappers consume:

• custom repo URLs,
• auth config,
• validation policy,
• include/exclude scope,
• ecosystem-specific extra fields.

Snapshot Data Model

snapshot exports from ReqPack's installed-state history, not from arbitrary machine state.

If snapshot output is empty or incomplete, check:

• history.enabled
• history.trackInstalled
• whether the packages were originally installed through ReqPack-managed flows

Transaction Recovery Model

ReqPack keeps at most one active mutating run in transaction DB.

Run states currently used:

• open
• recovered
• failed
• committed

Item statuses currently used:

• planned
• running
• success
• failed
• committed

Recovery flow:

1. executor checks for active run before starting new one
2. items already marked success, failed, or committed are skipped
3. remaining items are reconciled against current desired state through plugin getMissingPackages() where supported
4. items already at desired state are promoted to success
5. remaining items are replayed

Commit flow:

• if every item reaches success, run becomes committed
• committed item statuses are rewritten to committed
• if configured, committed run is then deleted from DB
• any incomplete or failed item leaves run in failed state

Operational Best Practices

• Keep registry hashes populated.
• Keep plugin trust metadata aligned with actual behavior.
• Keep history.trackInstalled = true if you rely on snapshot and restore.
• Use a separate OSV database path during test runs.
• Treat overlay registries as controlled overrides, not as a long-term substitute for upstream registry hygiene.

Related Pages

• Configuration
• Building Registry Entries
• Building rqp Packages and Repositories

Prev: Execution Flow | Up: Architecture | Next: Home