Avalanche intelligence runtime
The Avalanche AI product group in packages/avalanche hosts seven intelligence domains on one shared DeepSeek Harness runtime: one tool registry, one policy engine, one evidence ledger, and one operator CLI. This page records the service and event vocabulary that the domain packages share. The architecture document owns the execution lifecycle and enforcement points, and each package README owns its own contract.
The shared runtime
A domain is a data descriptor, not a separate process or profile. avalanche-agents registers the descriptors and routes a task deterministically by keyword; avalanche-orchestrator runs the task lifecycle from intent to evidence receipt; avalanche-tooling owns the risk-annotated tool catalog and the executor-level policy gate; and avalanche-policy makes the default-deny decision with fingerprint-bound single-use approvals. Reads flow through the fixed read-only allowlist in avalanche-network, and avalanche-evidence records every tool result in a hash-chained ledger.
Context and memory stay separate from evidence: avalanche-context stores layered values with their origin, and avalanche-memory stores five tiers of durable memory with deterministic lexical recall. avalanche-verification registers named verifiers and keeps unknown verification kinds unverifiable.
Cordis API
Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.
ctx.avalancheCliStartup — AvalancheCliStartup
The invocation the parser accepted.
Source: packages/avalanche/avalanche-cli/src/startup.ts
ctx.avalancheContext — AvalancheContext
Layered, origin-carrying context store.
/**
* Write one value into a layer.
* @param layer - owning layer.
* @param key - context key.
* @param value - JSON value.
* @param origin - where the value came from.
* @returns the stored entry.
*/
set(layer: ContextLayer, key: string, value: JsonValue, origin: Origin): ContextEntry
/**
* Write several values into one layer under a shared origin.
* @param layer - owning layer.
* @param values - key/value pairs.
* @param origin - where the values came from.
* @returns the stored entries, in input order.
*/
merge(layer: ContextLayer, values: Readonly<Record<string, JsonValue>>, origin: Origin): ContextEntry[]
/**
* Remove one value.
* @param layer - owning layer.
* @param key - context key.
* @returns whether an entry existed.
*/
remove(layer: ContextLayer, key: string): boolean
/**
* Read the highest-precedence entry for a key.
* @param key - context key.
* @param layers - candidate layers; defaults to every layer.
* @returns the winning entry, or `undefined`.
*/
get(key: string, layers: readonly ContextLayer[] = CONTEXT_LAYER_ORDER): ContextEntry | undefined
/**
* Resolve a merged view where later layers win.
* @param layers - candidate layers; defaults to every layer.
* @returns key/value view with origin dropped.
*/
resolve(layers: readonly ContextLayer[] = CONTEXT_LAYER_ORDER): Record<string, JsonValue>
/**
* List entries in precedence order.
* @param layers - candidate layers; defaults to every layer.
* @returns entries, lowest authority first.
*/
list(layers: readonly ContextLayer[] = CONTEXT_LAYER_ORDER): ContextEntry[]
/**
* Drop every value in one layer.
* @param layer - layer to clear.
* @returns number of removed entries.
*/
clear(layer: ContextLayer): number
Source: packages/avalanche/avalanche-context/src/index.ts
ctx.avalancheDomains — AvalancheDomains
Registry of Avalanche domain descriptors.
/**
* Register a domain descriptor.
* @param descriptor - domain to register; an existing id is replaced.
* @returns disposer that restores the previous descriptor.
*/
register(descriptor: DomainDescriptor): () => void
/**
* Read one descriptor.
* @param id - domain id.
* @returns the descriptor, or `undefined`.
*/
get(id: string): DomainDescriptor | undefined
/**
* List descriptors in registration order.
* @returns every registered domain.
*/
list(): DomainDescriptor[]
/**
* Rank domains for a request.
* @param text - the objective to route.
* @returns candidates with a positive score, best first; ties break by id.
*/
match(text: string): DomainMatch[]
/**
* Pick the best domain for a request.
* @param text - the objective to route.
* @returns the best candidate, or `undefined` when nothing matches.
*/
best(text: string): DomainMatch | undefined
/**
* Install one domain into an agent's scoped context: its prompt section and
* its tool mask. Called from the orchestrator's agent setup, so the
* restriction applies to that agent only.
* @param agentCtx - the agent's scoped context.
* @param domainId - domain to install.
* @returns the installed descriptor.
*/
install(agentCtx: Context, domainId: string): DomainDescriptor
Source: packages/avalanche/avalanche-agents/src/index.ts
ctx.avalancheEvidence — AvalancheEvidence
Hash-chained evidence ledger.
/**
* Append one record.
* @param input - kind, actor, payload, and optional correlation ids.
* @returns the appended record.
*/
record(input: RecordInput): EvidenceRecord
/**
* Read one record.
* @param id - record id.
* @returns the record, or `undefined`.
*/
get(id: string): EvidenceRecord | undefined
/**
* List records in append order.
* @param filter - optional kind and correlation filters.
* @returns matching records.
*/
list(filter: EvidenceFilter = {}): EvidenceRecord[]
/**
* Verify the whole chain.
* @returns whether every link recomputes, and where it first breaks.
*/
verifyChain(): ChainVerification
/**
* Issue a tamper-evident receipt and append it to the ledger.
* @param input - what was executed and which evidence supports it.
* @returns the issued receipt.
*/
issueReceipt(input: ReceiptInput): ExecutionReceipt
/**
* Read one receipt.
* @param id - receipt id.
* @returns the receipt, or `undefined`.
*/
getReceipt(id: string): ExecutionReceipt | undefined
/**
* List issued receipts, newest first.
* @param taskId - optional task filter.
* @returns matching receipts.
*/
listReceipts(taskId?: string): ExecutionReceipt[]
/**
* Recompute a receipt digest.
* @param receipt - receipt to check.
* @returns whether the stored digest matches the content.
*/
verifyReceipt(receipt: ExecutionReceipt): boolean
/**
* Wait for every mirror append queued so far.
* @returns a promise that settles when the current queue drained.
* @throws the first background write failure, if one occurred.
*/
async flush(): Promise<void>
/**
* Append every new record to the configured file.
* @param path - destination JSONL file.
* @returns a promise that settles when the flush completes.
*/
async persist(path: string): Promise<void>
Source: packages/avalanche/avalanche-evidence/src/index.ts
ctx.avalancheMemory — AvalancheMemory
Layered memory engine.
/**
* Install a durable store and load its contents.
* @param store - backing store.
* @returns the number of loaded entries.
*/
async useStore(store: MemoryStore): Promise<number>
/**
* Bound the number of retained entries.
* @param capacity - maximum entries per layer; must be positive.
*/
setCapacity(capacity: number): void
/**
* Store one memory.
* @param input - layer, content, tags, and origin.
* @returns the stored entry.
*/
remember(input: RememberInput): MemoryEntry
/**
* Read one entry.
* @param id - entry id.
* @returns the entry, or `undefined`.
*/
get(id: string): MemoryEntry | undefined
/**
* Score and return entries for a query.
* @param query - lexical query, optional tier, tags, and task filter.
* @returns matching entries, best first.
*/
recall(query: RecallQuery = {}): MemoryEntry[]
/**
* Promote or copy entries into another tier.
* @param from - source tier.
* @param to - destination tier.
* @param ids - entries to move; defaults to every entry in `from`.
* @returns the destination entries.
*/
consolidate(from: MemoryLayer, to: MemoryLayer, ids?: readonly string[]): MemoryEntry[]
/**
* Drop one entry.
* @param id - entry id.
* @returns whether the entry existed.
*/
forget(id: string): boolean
/**
* Drop one tier.
* @param layer - tier to clear.
* @returns number of removed entries.
*/
clear(layer: MemoryLayer): number
/**
* Count entries, optionally within one tier.
* @param layer - tier filter.
* @returns entry count.
*/
count(layer?: MemoryLayer): number
/**
* Project entries for a report.
* @param layer - tier filter.
* @returns serializable entries.
*/
list(layer?: MemoryLayer): MemoryEntry[]
/**
* Persist the current set when a store is installed.
* @returns a promise that settles when the write completes.
*/
async flush(): Promise<void>
Source: packages/avalanche/avalanche-memory/src/index.ts
ctx.avalancheNetworks — AvalancheNetworks
Operator-registered network registry plus read-only RPC access.
/**
* Replace the transport, for tests or a proxy.
* @param transport - transport to use for every subsequent call.
*/
setTransport(transport: RpcTransport): void
/**
* Register a network descriptor.
* @param descriptor - network to register; an existing id is replaced.
* @returns disposer that removes it.
*/
register(descriptor: NetworkDescriptor): () => void
/**
* Read one descriptor.
* @param id - network id.
* @returns the descriptor, or `undefined`.
*/
get(id: string): NetworkDescriptor | undefined
/**
* List descriptors in registration order.
* @returns every registered network.
*/
list(): NetworkDescriptor[]
/**
* Resolve a descriptor, refusing an unknown id.
* @param id - network id.
* @returns the descriptor.
*/
resolve(id: string): NetworkDescriptor
/**
* Perform one allowlisted read-only JSON-RPC call.
* @param networkId - registered network id.
* @param method - allowlisted method.
* @param params - positional parameters.
* @param signal - caller cancellation.
* @returns the JSON-RPC `result` member.
*/
async rpc(networkId: string, method: ReadOnlyRpcMethod, params: readonly JsonValue[] = [], signal?: AbortSignal): Promise<JsonValue>
/**
* Observe the chain id an endpoint reports and compare it with the descriptor.
* @param networkId - registered network id.
* @param signal - caller cancellation.
* @returns observed chain id, descriptor chain id, and whether they match.
*/
async observeChainId(networkId: string, signal?: AbortSignal): Promise<{ observed: number; expected?: number; matches: boolean }>
/**
* Build the catalogued read-only tool set. Registration is a separate step so
* a caller can inspect the profiles without mutating the shared registry.
* @returns profiles paired with their definitions, in a stable order.
*/
toolSpecs(): AvalancheToolSpec[]
/**
* Register the read-only tool set through the policy catalog.
* @returns disposer that removes every registered tool.
* @throws when no `avalancheTooling` catalog is mounted; an uncatalogued tool
* would bypass the policy gate, so registration fails instead.
*/
registerTools(): () => void
Source: packages/avalanche/avalanche-network/src/index.ts
ctx.avalancheOrchestrator — AvalancheOrchestrator
Lifecycle owner for Avalanche tasks.
/**
* Accept one objective and start its lifecycle.
* @param options - objective, optional domain, network, and constraints.
* @returns the task id and a promise that settles at the task's first resting state.
* @throws when the objective is blank or no domain matches it.
*/
submit(options: SubmitOptions): TaskHandle
/**
* Read one task snapshot.
* @param id - task id.
* @returns the snapshot, or `undefined`.
*/
inspect(id: string): TaskRecord | undefined
/**
* List task snapshots, newest first.
* @returns every task this process knows about.
*/
list(): TaskRecord[]
/**
* Cancel a task that has not finished.
* @param id - task id.
* @param reason - recorded on the task and in the ledger.
* @returns the task snapshot after cancellation.
*/
cancel(id: string, reason: string = 'cancelled by operator'): TaskRecord
Source: packages/avalanche/avalanche-orchestrator/src/index.ts
ctx.avalanchePolicy — AvalanchePolicy
Default-deny policy engine with fingerprint-bound approvals.
/**
* Register or replace a rule.
* @param rule - rule to register.
* @returns disposer that restores the previous rule.
*/
registerRule(rule: PolicyRule): () => void
/**
* List active rules.
* @returns rules in registration order.
*/
listRules(): PolicyRule[]
/**
* Evaluate a request. A prior approved-and-unconsumed approval for the same
* fingerprint turns a parked verdict into an allow.
* @param request - capabilities, actor, and target network.
* @returns the strictest verdict across every requested permission.
*/
evaluate(request: PolicyRequest): PolicyDecision
/**
* Create a pending approval for an exact request.
* @param request - request to park.
* @returns the pending approval.
*/
requestApproval(request: PolicyRequest): ApprovalRecord
/**
* Decide a pending approval.
* @param id - approval id.
* @param status - `approved` or `rejected`.
* @param decision - who decided and an optional note.
* @returns the updated approval.
*/
decide(id: string, status: Exclude<ApprovalStatus, 'pending' | 'expired'>, decision: { decidedBy: string; note?: string; at?: number }): ApprovalRecord
/**
* Create and approve one request in a single explicit operator action.
* @param request - request to approve.
* @param decision - who approved and why.
* @returns the approved record.
*/
grant(request: PolicyRequest, decision: { decidedBy: string; note?: string }): ApprovalRecord
/**
* Read one approval.
* @param id - approval id.
* @returns the approval, or `undefined`.
*/
get(id: string): ApprovalRecord | undefined
/**
* List approvals, newest first.
* @param status - status filter.
* @returns matching approvals.
*/
list(status?: ApprovalStatus): ApprovalRecord[]
/**
* Mark an approval as used so it cannot authorize a second action.
* @param id - approval id.
* @returns the updated approval.
*/
consume(id: string): ApprovalRecord
/**
* Find an approved, unconsumed approval bound to a fingerprint.
* @param fingerprint - action digest.
* @returns the approval, or `undefined`.
*/
findUsableApproval(fingerprint: string): ApprovalRecord | undefined
Source: packages/avalanche/avalanche-policy/src/index.ts
ctx.avalancheTooling — AvalancheTooling
Catalog and enforcement gate for Avalanche tools.
/**
* Install the lookup the gate uses to resolve a call's target network. The
* network registry owns the descriptors, so it supplies this rather than the
* catalog importing the registry.
* @param resolver - maps a network id to its id and environment.
*/
setNetworkResolver(resolver: (id: string) => { id: string; environment: NetworkEnvironment } | undefined): void
/**
* Register a tool and its risk profile.
* @param spec - profile and definition.
* @returns disposer that removes both the tool and its profile.
*/
register(spec: AvalancheToolSpec): () => void
/**
* List catalogued profiles.
* @returns profiles in registration order.
*/
catalog(): ToolRiskProfile[]
/**
* Read one profile.
* @param toolName - registered tool name.
* @returns the profile, or `undefined`.
*/
profile(toolName: string): ToolRiskProfile | undefined
/**
* Build the policy request a tool call implies, resolving the target network
* from the call arguments when the profile is network-parameterized.
* @param profile - catalogued profile.
* @param exec - the pending execution.
* @returns request with an action fingerprint.
* @throws when the profile names a network argument the call did not supply
* or the named network is not registered.
*/
requestFor(profile: ToolRiskProfile, exec: Readonly<ToolExecution>): PolicyRequest
Types: ToolExecution
Source: packages/avalanche/avalanche-tooling/src/index.ts
ctx.avalancheVerification — AvalancheVerification
Registry of named verifiers.
/**
* Register a verifier.
* @param verifier - capability to register.
* @returns disposer that removes it.
*/
register(verifier: Verifier): () => void
/**
* List registered kinds.
* @returns kind and description pairs.
*/
list(): { kind: string; description: string }[]
/**
* Run one verifier.
* @param kind - registered kind.
* @param request - observed input for the verifier.
* @returns the verdict; an unknown kind is `unverifiable`.
*/
async verify(kind: string, request: VerificationRequest): Promise<VerificationResult>
Source: packages/avalanche/avalanche-verification/src/index.ts
avalanche/* events
avalanche/approval-changed — emit
One approval changed state.
/**
* One approval changed state.
* @param approval - the approval after the change.
* @mode emit
*/
'avalanche/approval-changed'(approval: ApprovalRecord): void
Source: packages/avalanche/avalanche-policy/src/index.ts
avalanche/context-changed — emit
One context entry changed.
/**
* One context entry changed.
* @param entry - the entry after the write, or the removed entry.
* @param change - whether the entry was set or removed.
* @mode emit
*/
'avalanche/context-changed'(entry: ContextEntry, change: 'set' | 'removed'): void
Source: packages/avalanche/avalanche-context/src/index.ts
avalanche/domain-registered — emit
One domain descriptor was registered.
/**
* One domain descriptor was registered.
* @param descriptor - the registered descriptor.
* @mode emit
*/
'avalanche/domain-registered'(descriptor: DomainDescriptor): void
Source: packages/avalanche/avalanche-agents/src/index.ts
avalanche/evidence-appended — emit
One ledger entry was appended.
/**
* One ledger entry was appended.
* @param record - the appended record.
* @mode emit
*/
'avalanche/evidence-appended'(record: EvidenceRecord): void
Source: packages/avalanche/avalanche-evidence/src/index.ts
avalanche/network-registered — emit
One network descriptor was registered.
/**
* One network descriptor was registered.
* @param descriptor - the registered descriptor.
* @mode emit
*/
'avalanche/network-registered'(descriptor: NetworkDescriptor): void
Source: packages/avalanche/avalanche-network/src/index.ts
avalanche/policy-decision — emit
One policy verdict was produced.
/**
* One policy verdict was produced.
* @param decision - the verdict.
* @param request - the evaluated request.
* @mode emit
*/
'avalanche/policy-decision'(decision: PolicyDecision, request: PolicyRequest): void
Source: packages/avalanche/avalanche-policy/src/index.ts
avalanche/receipt-issued — emit
One receipt was issued.
/**
* One receipt was issued.
* @param receipt - the issued receipt.
* @mode emit
*/
'avalanche/receipt-issued'(receipt: ExecutionReceipt): void
Source: packages/avalanche/avalanche-evidence/src/index.ts
avalanche/task-changed — emit
One task record changed state.
/**
* One task record changed state.
* @param task - the task after the change.
* @mode emit
*/
'avalanche/task-changed'(task: TaskRecord): void
Source: packages/avalanche/avalanche-orchestrator/src/index.ts