pyscoped 0.1.0

Universal object-isolation and tenancy-scoping framework

Scoped

Universal object-isolation and tenancy framework for Python.

Scoped makes one guarantee: anything built on it can be isolated, shared, traced, and rolled back — to any degree, at any time, by anyone with the right to do so.

Why Scoped

Today a single person can spin up an AI conversation, do a throwaway task, and move on. That works for individuals. It does not work for organizations — teams that need to collaborate on throwaway work, share results selectively, enforce who sees what, and maintain a complete audit trail of everything that happened.

Scoped makes the throwaway-task pattern work at organizational scale. It is the base layer that any application can build on to inherit strict isolation, tenancy, traceability, and flow control by default.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        COMPLIANCE ENGINE (Layer 0)                  │
│          Validates every invariant across all layers below          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                  PLATFORM CONNECTOR (Layer 13)                │   │
│  │         Cross-org meshing, federation, marketplace            │   │
│  │  ┌────────────────────────────────────────────────────────┐   │   │
│  │  │              INTEGRATIONS & PLUGINS (Layer 12)          │   │   │
│  │  │       Sandboxed extensions, hooks, external systems     │   │   │
│  │  │  ┌──────────────────────────────────────────────────┐   │   │   │
│  │  │  │                  SECRETS (Layer 11)               │   │   │   │
│  │  │  │       Encrypted vault, refs, zero-trust access    │   │   │   │
│  │  │  ├──────────────────────────────────────────────────┤   │   │   │
│  │  │  │               DEPLOYMENTS (Layer 10)              │   │   │   │
│  │  │  │      Graduation to external targets, gates        │   │   │   │
│  │  │  ├──────────────────────────────────────────────────┤   │   │   │
│  │  │  │              STAGES & FLOW (Layer 9)              │   │   │   │
│  │  │  │    Pipelines, channels, promotions — the river    │   │   │   │
│  │  │  ├──────────────────────────────────────────────────┤   │   │   │
│  │  │  │              ENVIRONMENTS (Layer 8)               │   │   │   │
│  │  │  │   Ephemeral workspaces — the unit of work         │   │   │   │
│  │  │  └──────────────┬───────────────────────────────────┘   │   │   │
│  │  │                 │                                        │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │ TEMPORAL (Layer 7)│  Point-in-time rollback      │   │   │
│  │  │       └─────────┬─────────┘                              │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │  AUDIT (Layer 6)  │  Hash-chained trace of ALL   │   │   │
│  │  │       └─────────┬─────────┘                              │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │  RULES (Layer 5)  │  Deny-overrides policy       │   │   │
│  │  │       └─────────┬─────────┘                              │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │ TENANCY (Layer 4) │  Scopes, projections         │   │   │
│  │  │       └─────────┬─────────┘                              │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │ OBJECTS (Layer 3) │  Versioned, isolated          │   │   │
│  │  │       └─────────┬─────────┘                              │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │IDENTITY (Layer 2) │  Generic principals           │   │   │
│  │  │       └─────────┬─────────┘                              │   │   │
│  │  │       ┌─────────┴─────────┐                              │   │   │
│  │  │       │REGISTRY (Layer 1) │  Everything registered        │   │   │
│  │  │       └───────────────────┘                              │   │   │
│  │  └──────────────────────────────────────────────────────────┘   │   │
│  └──────────────────────────────────────────────────────────────┘   │
│  └──────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                    STORAGE BACKEND                            │   │
│  │            SQLite │ Django ORM │ Postgres │ ...               │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Core Layers

Layer	Name	Purpose
1	Registry	Universal construct registration — nothing exists without a URN
2	Identity	Generic principal machinery — every operation requires an actor
3	Objects	Versioned, isolated data objects — creator-private by default
4	Tenancy	Scopes, membership, and projection — the sharing primitive
5	Rules	Deny-overrides policy engine with redaction, rate limits, quotas, feature flags
6	Audit	Hash-chained, immutable, append-only trace of every action
7	Temporal	Point-in-time reconstruction and cascading rollback
8	Environments	Ephemeral workspaces — the throwaway unit of work
9	Flow	Stages, pipelines, flow channels, and promotions
10	Deployments	Graduation to external targets with gate checks
11	Secrets	Encrypted vault with ref-based zero-trust access
12	Integrations	Sandboxed plugins, hooks, and external system connectors
13	Connector	Cross-organization meshing, federation, and marketplace
14	Events	Asynchronous scoped event bus with webhook delivery
15	Notifications	Principal-targeted messages from events and rules
16	Scheduling	Recurring schedules, time-based actions, scoped job execution

Extensions

ID	Name	Extends	Purpose
A1	Migrations	Storage	Versioned schema evolution with up/down migrations
A2	Contracts	L1 + L3	Declared object schemas and field-level validation
A3	Rule Extensions	L5	Redaction, rate limiting, quotas, feature flags
A4	Blobs	L3 + Storage	Binary content with versioning and isolation
A5	Config Hierarchy	L4	Per-scope settings with hierarchical inheritance
A6	Search	L3	Scope-aware full-text search over object data
A7	Templates	L1	Reusable blueprints for any construct type
A8	Tiering	Storage	Hot/warm/cold/glacial storage tiers with retention policies
A9	Import/Export	L3	Portable object packages with ID remapping

The Invariants

1. Nothing exists without registration. Every construct must have a registry entry with a URN.
2. Nothing happens without identity. Every operation requires a ScopedContext with an acting principal.
3. Nothing is shared by default. Every object starts creator-private. Sharing is always explicit.
4. Nothing happens without a trace. Every action produces an immutable, hash-chained audit entry.
5. Nothing is truly deleted. Objects are tombstoned. Versions are retained. Audit is append-only.
6. Deny always wins. When rules conflict, DENY overrides ALLOW.
7. Revocation is immediate. Same-transaction enforcement, not eventual consistency.
8. Everything is versioned. Every mutation creates a new version.
9. Everything is rollbackable. Any action can be reversed to any point in time.
10. Secrets never leak. Values never appear in audit trails, snapshots, or connector traffic.

Quick Start

Install

pip install scoped

Basic Usage

from scoped.storage.sqlite import SQLiteBackend
from scoped.registry.sqlite_store import SQLiteRegistryStore
from scoped.identity.principal import PrincipalStore
from scoped.objects.manager import ScopedManager
from scoped.tenancy.lifecycle import ScopeLifecycle
from scoped.audit.writer import AuditWriter

# Initialize with SQLite
backend = SQLiteBackend(":memory:")

# Register a principal
principals = PrincipalStore(backend)
user = principals.create(kind="user", display_name="Alice")

# Create an isolated object
manager = ScopedManager(backend)
obj = manager.create(
    object_type="document",
    data={"title": "Draft Report", "content": "..."},
    owner_id=user.id,
)

# Object is creator-private — no one else can see it
# To share, create a scope and project the object into it
scopes = ScopeLifecycle(backend)
scope = scopes.create(name="Team Alpha", owner_id=user.id)

Requirements

• Python 3.11+
• No required dependencies (SQLite backend included)

Development

# Clone
git clone https://github.com/kwip-info/scoped.git
cd scoped

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Test Coverage

Component	Tests
Layers 1-13 (core)	820
Extensions (A1-A9)	386
Layer 14: Events	61
Layer 15: Notifications	29
Layer 16: Scheduling	27
Layer 0: Compliance	87
Framework Adapters (D1-D4)	83
Total	1,493

Framework Adapters

Adapter	Framework	Module	Purpose
D1	Django	scoped.contrib.django	ORM backend, middleware, management commands
D2	FastAPI	scoped.contrib.fastapi	Middleware, dependencies, Pydantic schemas, admin routes
D3	Flask	scoped.contrib.flask	Extension, before/after hooks, admin blueprint
D4	FastMCP	scoped.contrib.mcp	MCP server with tools and resources for AI agents

Install with extras: pip install scoped[django], pip install scoped[fastapi], etc.

Documentation

Full architecture documentation is in the docs/ directory:

• Architecture Overview
• Layer Documentation (Layers 0-16)
• Extension Documentation (A1-A9)

License

MIT License. See LICENSE for details.