Skip to main content

Module scope

Module scope 

Source
Expand description

Scope records: owned identity records the daemon holds for sessions.

A scope is identified by (owner, ref). The owner is the module whose own registered connection synced it, never a value in the request, and the ref is an opaque string unique within that owner only. The design is docs/designs/daemon-scopes.md; the wire shapes here are the owner-facing half of it (scope.sync, scope.apply, scope.describe).

Every record type refuses unknown fields. A field this daemon does not know may be one that narrows authority in a later version (a carrier’s target list, say), and silently dropping it would widen what the scope grants, so an owner sending one is told its body is malformed instead.

Structs§

ScopeAttributes
The authority-controlled attributes the daemon copies into scope stamps, subject to each field’s target capability gate. Only an owner module named in the daemon config’s scope_authority_owners list (by default the module that owns agent sessions) may set them; a scope owned by any other module must leave them empty.
ScopeCarrier
Who, besides the owner, may open routes under a scope.
ScopeEnd
A request to end one scope session in scope.apply.
ScopeEndResult
The per-end result in a scope.apply reply, in request order.
ScopeEnded
A scope session of the calling owner that ended through omission from scope.sync, an explicit scope.apply end, replacement by a higher epoch for the same ref or expiry.
ScopeParent
A link from a scope to another scope, pinned to that scope’s session by its epoch.
ScopeRecord
One scope as its owner registers it in scope.sync or scope.apply.
ScopeRecordResult
The per-record result in a scope.sync or scope.apply reply, in request order.
ScopeSelector
The scope a route.open asks to be admitted under.
ScopeStamp
The fields the daemon stamps for a live scope. Build with ScopeStamp::new and the setters so future fields are additive.

Enums§

ParentState
The state of a scope’s parent link.
ScopeEndOutcome
What scope.apply did with one requested end.
ScopeKind
What a scope stands for. Closed, and fixed for the life of one scope_epoch: a different kind needs a new epoch, which ends the old scope.
ScopeRecordOutcome
What a scope.sync or scope.apply did with one record.
ScopeStatus
scope.describe’s answer about one (owner, ref).

Constants§

AGENT_RUN_SCOPES_CAPABILITY
Declaring this in a manifest’s capabilities.provides promises that the module recognises run_id as one agent run and does not exercise the agent’s delegated authority under that scope. During migration it admits non-delegating run scopes; delegating runs require crate::call_mode::CALL_MODES_CAPABILITY instead.
BIND_NO_PROJECT_CAPABILITY
A target declares this in capabilities.provides once it no longer reads project fields from route.bind identities. Declaring it makes the daemon omit those identity fields, independently of SCOPE_WORKDIR_CAPABILITY, which gates both workdir and project_id in the admitted ScopeStamp.
CAP_ROUTE_ROLE_VERSIONS_V1
The server.describe capability a daemon advertises when it checks a route.open’s role_versions and forwards them on the module’s bind. A daemon without it drops the field silently, so a consumer that relies on the provider seeing its role versions checks for this first.
CAP_SCOPES_V1
The server.describe capability a daemon advertises when it admits routes under scopes. A carrier that needs a scoped route and does not see it fails the call (scope_unsupported) instead of opening an unscoped route.
FLOW_IDENTITY_SCOPES_CAPABILITY
Declaring this capability promises that a reader accepts the installed flow identity fields in scope stamps. It does not replace flow-scope admission.
FLOW_SCOPES_CAPABILITY
Declaring this in a manifest’s capabilities.provides promises that the module recognises a scope carrying flow_id and applies flow behaviour: it never treats the flow as its owner agent. During migration, either this capability or crate::call_mode::CALL_MODES_CAPABILITY admits flow scopes.
MAX_CARRIER_TARGETS
Most modules one targeted carrier entry may list.
MAX_LIVE_SCOPES_PER_OWNER
Most live scopes one owner may hold. A sync naming more is refused whole.
MAX_SCOPE_ATTRIBUTE_BYTES
Most bytes one scope’s attributes may take, measured as compact JSON. A sync carrying a larger record is refused whole.
MAX_SCOPE_EXPIRY_AHEAD_MS
Most milliseconds a new scope epoch’s deadline may be ahead of the daemon’s current Unix wall clock: 24 hours.
MAX_SCOPE_TOMBSTONES_PER_OWNER
Most ended scopes the daemon remembers per owner. The oldest is forgotten first, and reaching the bound never refuses a sync.
SCOPE_APPLY_OP
Module-to-subc op that upserts or ends scopes without replacing the owner’s full scope set.
SCOPE_DESCRIBE_OP
Module-to-subc op that reads one scope’s current state.
SCOPE_ON_BEHALF_OF_CAPABILITY
Declaring this in a manifest’s capabilities.provides promises that the module recognises on_behalf_of_agent as attribution only, never authority. The daemon also advertises this capability to scope-authority owners.
SCOPE_SERVED_BY_CAPABILITY
The daemon can answer whether a module acknowledged a bind under an owned scope epoch.
SCOPE_SYNC_OP
Module-to-subc op that registers an owner’s full scope set.
SCOPE_WORKDIR_CAPABILITY
Capability declaring that a provider accepts session folder and project stamps.
WORKER_RUNS_CAPABILITY
A worker run is a codemode run scope with run_id and on_behalf_of_agent but no agent_id: it works for an agent without that agent’s authority. Declaring this in a manifest’s capabilities.provides promises that the module handles a codemode bind carrying run_id and no agent_id as attribution only, and never acts as, consents for, or hands out per-agent handles of the attributed agent. A worker run binds only to a target declaring it; call-modes/v1 and agent-run-scopes/v1 alone do not admit one, because those providers assume a run carries its agent’s identity. A declarer receives call_mode: codemode and the stamp’s on_behalf_of_agent on a worker-run bind even without SCOPE_ON_BEHALF_OF_CAPABILITY. The daemon also advertises this capability so owners register worker runs only with a daemon that accepts them.

Functions§

validate_bind_proof_sha256
A scope bind-proof hash is the lowercase hexadecimal SHA-256 digest.
validate_flow_code_hash
Check the approved flow code’s SHA-256. Errors name flow_code_hash.
validate_flow_id
Check a flow id using the shared opaque-token rule: 1–256 printable, non-space ASCII bytes. Errors name flow_id. Scope refs remain opaque and are not subject to this token rule.
validate_flow_install_id
Check an installed flow token using the same opaque-token rule as flow_id. Errors name flow_install_id.
validate_flow_version
Check an installed flow version: 1 through 9007199254740991 (2^53 - 1), the largest integer every JSON reader, including JavaScript, decodes exactly.
validate_on_behalf_of_agent
Check attribution using the agent token rule: 1–256 printable, non-space ASCII bytes. Errors name on_behalf_of_agent.
validate_project_id
Check an Entorhinal project id without interpreting its opaque contents.
validate_run_id
Check a run id using the shared opaque-token rule: 1–256 ASCII bytes in 0x21–0x7E. Errors name run_id.