Scope and Governance

A Scope is the unit of governance in the SmartPoints architecture (ADR-088 Layer 4). It wraps a sovereign identity (DID), enforces policies, manages actors, and maintains a registry of connectors to external services.

A user's SmartBrain app equals one Scope. One Scope controls one or more SPTOS host instances. Cross-scope relationships require bilateral SmartPoint pair negotiation.

Architecture

Scope (governance boundary)
  +-- ScopePolicy (rules + resource budget)
  +-- ActorRegistry (actor lifecycle)
  +-- ConnectorRegistry (hexagonal adapters)
  +-- RendezvousManager (capability invitations)
  +-- SmartPointPairs (cryptographic channel references)

What a Scope Is

A Scope is a governance boundary that:

• Wraps a sovereign identity (DID via spt-aid)
• Enforces policies on actor creation, connector access, data sharing, and resource budgets
• Manages the lifecycle of SmartPoint pairs (creation, revocation)
• Maintains a registry of Connectors (hexagonal adapters to external services)
• Manages Actor Constellations (groups of agents within the scope)

use sptos_scope::Scope;

let scope = Scope::create("my-brain", "did:said:1:sw:blake3_abc123");

Policy Enforcement

The ScopePolicy governs what actions are permitted within a Scope. Policies are evaluated against a PolicyContext and return a PolicyDecision (allow, deny, or escalate).

use sptos_scope::{ScopePolicy, PolicyRule, PolicyAction, PolicyContext, ResourceBudget};

let policy = ScopePolicy::new()
    .with_rule(PolicyRule::new(
        "agent-creation",
        PolicyAction::RequireApproval,
    ))
    .with_budget(ResourceBudget {
        max_actors: 50,
        max_connectors: 10,
        max_pairs: 100,
    });

Policy Actions

Action	Description
Allow	Permit the operation without restriction
Deny	Block the operation
RequireApproval	Allow with human approval
RateLimit	Allow within rate constraints

Resource Budget

Each Scope has a ResourceBudget that caps the number of actors, connectors, and SmartPoint pairs it can create.

Actor Management

Actors are agents or services operating within a Scope. Each actor has a lifecycle state, a set of capabilities, and is bound to the Scope's policy.

Actor States

Created --> Active --> Suspended --> Terminated
               |                        ^
               +------------------------+

State	Description
Created	Actor registered but not yet active
Active	Operating within the Scope
Suspended	Temporarily paused (policy violation, maintenance)
Terminated	Permanently removed

Creating Actors

use sptos_scope::Scope;

let scope = Scope::create("my-brain", "did:said:1:sw:blake3_abc123");
let actor = scope.add_actor(
    "assistant",           // name
    "agent",               // type
    vec!["read:docs".into(), "write:notes".into()],  // capabilities
)?;

The ActorRegistry tracks all actors within a Scope and enforces the resource budget.

Connector Framework

Connectors are hexagonal adapters that integrate external services into a Scope. Each connector has a configuration, a set of capabilities it provides, and a lifecycle managed by the ConnectorRegistry.

Local Connectors

Local connectors run within the Scope's SPTOS host instance:

use sptos_scope::{Connector, ConnectorConfig, ConnectorRegistry};

let registry = ConnectorRegistry::new();
let config = ConnectorConfig {
    name: "github".into(),
    connector_type: "spt-connector-github".into(),
    capabilities: vec!["repo:read".into(), "pr:create".into()],
    settings: Default::default(),
};
registry.register(Connector::new(config))?;

Connector-as-a-Service (CaaS)

Remote connectors run in a separate Scope and are accessed through a SmartPoint pair. The owning Scope retains the connector service via the marketplace and communicates through the encrypted channel.

Available Connectors

Crate	Service	Capabilities
spt-connector-github	GitHub	Repository, PR, issue operations
spt-entra	Microsoft Entra ID	Authentication, group management
spt-connectors-core	Framework	Base traits and utilities

Rendezvous Protocol

A Rendezvous is a scope-sealed, time-bounded invitation for one Scope to grant capabilities to a target DID. It is the mechanism for establishing new SmartPoint pairs between Scopes.

Security Properties

• Non-transferable: Bound to target_did
• Non-replayable: Nonce + max_activations counter
• Scope-sealed: source_did signs the permissions
• Time-bounded: expires_at checked on every operation
• Revocable: Can be revoked mid-session

Rendezvous States

Dormant --> Active --> Expired
              |
              +--> Revoked

State	Description
Dormant	Created but not yet activated by the target
Active	Activated and in use
Expired	TTL elapsed
Revoked	Explicitly revoked by the source

Creating a Rendezvous

use sptos_scope::{RendezvousManager, RendezvousConfig};

let manager = RendezvousManager::new();

let config = RendezvousConfig {
    source_did: "did:said:1:sw:blake3_alice".into(),
    target_did: "did:said:1:sw:blake3_bob".into(),
    capabilities: vec!["read:docs".into(), "write:notes".into()],
    ttl_seconds: 3600,
    max_activations: 1,
};

let rendezvous = manager.create(config)?;

// Target activates the rendezvous
let activated = manager.activate(&rendezvous.id, "did:said:1:sw:blake3_bob")?;

// Source can revoke at any time
manager.revoke(&rendezvous.id)?;

Audit Trail

Every rendezvous operation (create, activate, revoke, expire) is recorded as an AuditEntry for compliance and debugging.

Federation

The spt-federation crate manages trust policies between Scopes across organizational boundaries. Federation enables cross-scope SmartPoint pairs with policy negotiation.

Key Types

Type	Crate	Description
Scope	sptos-scope	Governance boundary wrapping a DID
ScopePolicy	sptos-scope	Rules, actions, and resource budgets
PolicyRule	sptos-scope	Individual policy rule
PolicyAction	sptos-scope	Allow, Deny, RequireApproval, RateLimit
ResourceBudget	sptos-scope	Actor/connector/pair limits
Actor	sptos-scope	Agent within a Scope
ActorRegistry	sptos-scope	Actor lifecycle management
ActorState	sptos-scope	Created, Active, Suspended, Terminated
Connector	sptos-scope	Hexagonal adapter to external service
ConnectorRegistry	sptos-scope	Connector lifecycle management
Rendezvous	sptos-scope	Time-bounded capability invitation
RendezvousManager	sptos-scope	Rendezvous lifecycle management
RendezvousConfig	sptos-scope	Rendezvous creation parameters
RendezvousState	sptos-scope	Dormant, Active, Expired, Revoked