Token Broker, Agent Resource Marketplace & Economic Exchange Subsystem Guide
Comprehensive architectural, operational, and protocol reference for the pkg/economy subsystem in ZQK Core.
1. System Architecture
In a multi-agent autonomous mesh, sovereign kernel nodes collaborate, share compute capabilities, and invoke specialized AI reasoning skills across organizational boundaries. Without decentralized economic governance, peer nodes face resource exhaustion, tragedy-of-the-commons query spam, and uncoordinated capacity bottlenecks.
The Token Broker, Agent Resource Marketplace, and Economic Exchange Subsystem (pkg/economy) provides microeconomic accounting, skill directory discovery, and policy-driven credit enforcement for kernel-to-kernel interactions.
Core Architectural Pillars
-
Policy-Driven Credit Accounting (
EconomicBroker): Enforces economic constraints defined in global configuration policies. Tracks account balances, applies dynamic per-query fees, and bounds partner debt through configurable credit limits. -
Dynamic Skill Discovery & Advertisement (
AgentMarketplace): Enables provider nodes to broadcast specialized capabilities into a shared directory with explicit metadata regarding availability, costs, and node provenance. -
Atomic Skill Leasing with Upfront Settlement (
LeaseSkill): Facilitates time-bounded resource leases where consumer nodes acquire execution rights from providers. Settles access charges through theEconomicBrokerprior to issuing valid lease tokens. -
Thread-Safe In-Memory State & Storage Integration: Utilizes fine-grained read-write locks (
sync.RWMutex,sync.Mutex) to prevent double-spending or stale read anomalies during concurrent transactions while persisting ledger balance mutations into the kernel's Content-Addressed Storage (CAS) layer.
2. Mermaid Topology Diagram
flowchart TD
subgraph Consumers["Consumer Kernel Nodes"]
C1["Agent Worker Node A"]
C2["Agent Worker Node B"]
end
subgraph Marketplace["Agent Marketplace (AgentMarketplace)"]
Registry["Skill Catalog (map[string]SkillAdvertisement)"]
LeaseManager["Lease Ledger (map[string]SkillLease)"]
CatalogQuery["GetAvailableSkills()"]
LeaseEngine["LeaseSkill()"]
end
subgraph Broker["Economic Broker (EconomicBroker)"]
BrokerLock["Mutex (mu.Lock)"]
PolicyCheck["Read global_economic_policy"]
QuotaEngine["Credit Balance & Debt Ceiling Evaluation"]
PulseLog["FluentEvent Telemetry (HIVE PULSE)"]
end
subgraph StorageMembrane["Kernel Storage Layer (ObjectStorageProvider)"]
PolicyStore[("global_economic_policy")]
AccountStore[("Partner Account Ledger")]
end
subgraph Providers["Provider Kernel Nodes"]
P1["Skill Provider Node X"]
P2["Skill Provider Node Y"]
end
%% Providers publish
P1 -->|"BroadcastSkill(ad)"| Registry
P2 -->|"BroadcastSkill(ad)"| Registry
%% Consumers discover
C1 -->|"GetAvailableSkills()"| CatalogQuery
CatalogQuery -->|"Filter Available=true"| Registry
%% Consumers lease
C2 -->|"LeaseSkill(consumerID, skillID, duration)"| LeaseEngine
LeaseEngine -->|"1. Lookup & Validate Skill"| Registry
LeaseEngine -->|"2. DeductQueryCredits(consumerID)"| BrokerLock
BrokerLock --> PolicyCheck
PolicyCheck -->|"Read Policy"| PolicyStore
PolicyCheck --> QuotaEngine
QuotaEngine -->|"Read Balance"| AccountStore
QuotaEngine -->|"3. Update Balance (newBalance >= -limit)"| AccountStore
QuotaEngine --> PulseLog
LeaseEngine -->|"4. Issue SkillLease (LeaseID, ExpiresAt)"| LeaseManager
LeaseEngine -->|"5. Return Lease Record"| C2
3. Token Ledger & Allocation Protocols
The economic engine maintains two primary data structures: the Global Economic Policy and the Partner Account Ledger.
Global Economic Policy Schema
The broker inspects the singleton object global_economic_policy in kernel storage.
| Field Name | Type | Description | Default / Fallback |
|---|---|---|---|
cost_per_query |
int |
Number of credits deducted per query or skill lease invocation. | 1 if unspecified or zero. |
max_credit_limit |
int |
Maximum negative balance allowed before a partner is halted. | 0 (debt ceiling enforced strictly at zero). |
Partner Account Ledger Schema
Each partner kernel or consumer identity is tracked via an account object in kernel storage:
| Field Name | Type | Description |
|---|---|---|
credit_balance |
int |
Current net credit balance. May be negative down to -max_credit_limit. |
Deduction Protocol Workflow
When DeductQueryCredits(ctx, partnerID) is invoked:
- Mutex Acquisition: The broker acquires
b.mu.Lock()to serialize account ledger operations. - Policy Resolution: Loads
global_economic_policy. Returns an error if the policy object is missing or unreadable. - Cost Evaluation: Extracts
cost_per_query. If zero or unconfigured, defaults to1. - Account Lookup: Loads the partner account record by
partnerID. Returns an error if not found. - Debt Check: Computes
newBalance = balance - cost. IfnewBalance < -limit, rejects the transaction. - Ledger Update: Writes back
{"credit_balance": newBalance}to storage. - Telemetry Emission: Dispatches a structured
FluentEventlog indicating deducted amount and remaining balance.
4. Quota Enforcement & Rate Limiting
The economic exchange prevents unbounded consumption using credit thresholds and lease duration boundaries:
Debt Ceiling Enforcement
The broker implements a hard floor on negative account balances:
- Positive Balance: Allowed. Balance decreases toward zero.
- Zero Balance: Allowed as long as \(\text{cost} \le \text{limit}\). Partner enters credit debt.
- Exact Boundary: If \(\text{balance} - \text{cost} == -\text{limit}\), deduction succeeds and the account sits at maximum debt.
- Ceiling Breach: If \(\text{balance} - \text{cost} < -\text{limit}\), the operation fails immediately with an
insufficient creditserror, halting upstream lease workflows.
Marketplace Lease Lifecycles
Skill leases are issued with explicit timestamps:
LeaseIDGeneration: Deterministic prefix patternlease-<consumerID>-<skillID>-<unix_nanos>guaranteeing collision-free tracking.- Expiration Stamping:
ExpiresAt = time.Now().Add(duration). Consumer nodes must renew or re-acquire leases upon expiration. - Decoupled Verification: If an
AgentMarketplaceis instantiated without a broker (broker == nil), leasing functions in permissive open-community mode without credit deduction.
5. Failure Modes & Edge Cases
| Failure Mode | Trigger Condition | System Behavior | Recovery / Mitigation |
|---|---|---|---|
| Missing Global Policy | Storage provider returns an error when reading global_economic_policy. |
Returns no active economic policy found. All deductions and broker-backed leases are blocked fail-closed. |
Bootstrap initial global_economic_policy object in storage. |
| Missing Partner Account | Consumer or partner ID not found in storage. | Returns partner account <id> not found. Deduction aborts without modifying policy or other balances. |
Provision partner account with initial credit_balance before leasing. |
| Debt Limit Exceeded | newBalance < -limit. |
Deduction fails with insufficient credits: partner <id> reached credit limit. No storage mutation occurs. |
Partner must replenish credits or operator must adjust max_credit_limit. |
| Storage Write Failure | store.Update returns error on balance persist. |
Error propagated to caller. Mutex unlocks cleanly; in-memory state remains consistent. | Underlying storage retry or disk space recovery. |
| Invalid Skill Advertisement | Broadcast payload missing SkillID or KernelID. |
Rejected synchronously with skill ID is required or kernel ID is required. |
Caller must populate required identification attributes. |
| Unavailable Skill Lease | Consumer requests lease for skill with Available == false. |
Fails immediately with skill <id> is not currently available. No credits are deducted. |
Provider updates advertisement availability status. |
| Unregistered Skill Lease | Consumer requests lease for non-existent skillID. |
Fails immediately with skill <id> not found. No credits are deducted. |
Query available skills via GetAvailableSkills prior to leasing. |
6. Verifiable Invariants
- Non-Negative Cost Invariant: If
cost_per_queryin policy is0or absent, the broker must default cost to1, preventing zero-cost depletion loops. - Fail-Closed Credit Check Invariant: A lease request under an active
EconomicBrokerMUST NOT succeed if credit deduction fails for any reason (policy failure, missing partner, or limit breach). - Zero Balance Leak Invariant: The balance update is strictly atomic under the broker's mutex; concurrent callers cannot race to overdraw partner credit limits.
- Availability Filtering Invariant:
GetAvailableSkillsmust never return advertisements whereAvailable == false. - Coverage Floor Invariant: The
pkg/economypackage maintains a strict statement test coverage floor of \(\ge 85.0\%\) (target \(100.0\%\)), verified by continuous CI gates.