Metadata-Version: 2.4
Name: pyscoped
Version: 0.1.0
Summary: Universal object-isolation and tenancy-scoping framework
Project-URL: Homepage, https://github.com/kwip-info/scoped
Project-URL: Repository, https://github.com/kwip-info/scoped
Author: kwip-info
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.2; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Requires-Dist: pydantic>=2.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=3.0; extra == 'flask'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
Description-Content-Type: text/markdown

# 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

```bash
pip install scoped
```

### Basic Usage

```python
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

```bash
# 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/`](docs/) directory:

- [Architecture Overview](docs/architecture.md)
- [Layer Documentation](docs/layers/) (Layers 0-16)
- [Extension Documentation](docs/extensions/) (A1-A9)

## License

MIT License. See [LICENSE](LICENSE) for details.
