pyscoped 0.1.0__tar.gz

pyscoped-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Distribution
+*.tar.gz
+*.whl

pyscoped-0.1.0/CLAUDE.md

@@ -0,0 +1,395 @@
+# Scoped — Agent Instructions
+
+## What This Is
+
+Scoped is a universal object-isolation and tenancy framework for Python. It guarantees that 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.
+
+**Repository:** https://github.com/kwip-info/scoped
+**Python:** 3.11+ (developed on 3.13)
+**Dependencies:** None required (SQLite backend included)
+
+## Architecture
+
+16 layers + a compliance engine (Layer 0). Every layer depends on the layers below it.
+
+| Layer | Module | Purpose |
+|-------|--------|---------|
+| 0 | `scoped.testing` | Compliance engine — validates all invariants |
+| 1 | `scoped.registry` | Universal construct registration (URNs) |
+| 2 | `scoped.identity` | Generic principal machinery + ScopedContext |
+| 3 | `scoped.objects` | Versioned, isolated data objects |
+| 4 | `scoped.tenancy` | Scopes, membership, projection (the sharing primitive) |
+| 5 | `scoped.rules` | Deny-overrides policy engine |
+| 6 | `scoped.audit` | Hash-chained, immutable, append-only trace |
+| 7 | `scoped.temporal` | Point-in-time reconstruction + cascading rollback |
+| 8 | `scoped.environments` | Ephemeral workspaces |
+| 9 | `scoped.flow` | Stages, pipelines, flow channels, promotions |
+| 10 | `scoped.deployments` | Graduation to external targets with gate checks |
+| 11 | `scoped.secrets` | Encrypted vault with ref-based zero-trust access |
+| 12 | `scoped.integrations` | Sandboxed plugins, hooks, external systems |
+| 13 | `scoped.connector` | Cross-org meshing, federation, marketplace |
+| 14 | `scoped.events` | Asynchronous scoped event bus + webhooks |
+| 15 | `scoped.notifications` | Principal-targeted messages from events/rules |
+| 16 | `scoped.scheduling` | Recurring schedules, scoped job execution |
+
+9 extensions enrich existing layers: A1 (Migrations), A2 (Contracts), A3 (Rule Extensions), A4 (Blobs), A5 (Config Hierarchy), A6 (Search), A7 (Templates), A8 (Tiering), A9 (Import/Export).
+
+## The 10 Invariants
+
+These are absolute. Never write code that violates them.
+
+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 via scope projection.
+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.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python3.13 -m pytest           # run full suite (1,410 tests)
+python3.13 -m pytest tests/test_objects/  # run one layer
+```
+
+Test fixtures are in `tests/conftest.py`:
+- `sqlite_backend` — in-memory SQLite, initialized with schema, closed after test
+- `registry` — fresh Registry instance per test
+- `_reset_global_state` (autouse) — resets singletons between tests
+
+## Code Conventions
+
+### Dataclasses
+
+All models use `@dataclass(frozen=True, slots=True)` for immutability and memory efficiency. Mutable models (like `Principal`) use `@dataclass(slots=True)` without frozen.
+
+### IDs and Timestamps
+
+```python
+from scoped.types import generate_id, now_utc
+id = generate_id()       # UUID hex string
+ts = now_utc()           # datetime in UTC
+```
+
+### Storage Backend
+
+All persistence goes through `StorageBackend`. Never write raw SQL outside the storage layer.
+
+```python
+from scoped.storage.sqlite import SQLiteBackend
+
+backend = SQLiteBackend(":memory:")
+backend.initialize()  # creates all tables — call once
+
+# Queries
+row = backend.fetch_one("SELECT ...", (param,))
+rows = backend.fetch_all("SELECT ...", (param,))
+
+# Writes (use transactions)
+with backend.transaction() as tx:
+    tx.execute("INSERT ...", (param,))
+    tx.commit()
+```
+
+### Identity & Context
+
+Every operation needs an acting principal. Use `ScopedContext` as a context manager:
+
+```python
+from scoped.identity.context import ScopedContext
+from scoped.identity.principal import PrincipalStore
+
+principals = PrincipalStore(backend)
+user = principals.create_principal(kind="user", display_name="Alice")
+
+with ScopedContext(principal=user):
+    # All operations here are attributed to `user`
+    ctx = ScopedContext.current()  # get active context
+```
+
+### Objects — Creator-Private by Default
+
+```python
+from scoped.objects.manager import ScopedManager
+
+manager = ScopedManager(backend)
+
+# Create (creator-private)
+obj, version = manager.create(object_type="document", owner_id=user.id, data={"title": "Draft"})
+
+# Read (owner-only — returns None if not owner)
+obj = manager.get(obj.id, principal_id=user.id)
+
+# Update (creates new version)
+obj, new_ver = manager.update(obj.id, principal_id=user.id, data={"title": "Final"})
+
+# Soft delete
+tombstone = manager.tombstone(obj.id, principal_id=user.id, reason="obsolete")
+```
+
+**Important:** `ScopedManager.get()` enforces **owner-only** access. Scope projections enable visibility through separate query paths (tenancy engine), not through the manager.
+
+### Sharing via Scopes and Projections
+
+```python
+from scoped.tenancy.lifecycle import ScopeLifecycle
+from scoped.tenancy.projection import ProjectionManager
+from scoped.tenancy.models import ScopeRole, AccessLevel
+
+scopes = ScopeLifecycle(backend)
+projections = ProjectionManager(backend)
+
+# Create scope (owner auto-added as OWNER member)
+scope = scopes.create_scope(name="Team Alpha", owner_id=user.id)
+
+# Add members (requires granted_by and ScopeRole enum)
+scopes.add_member(scope.id, principal_id=bob.id, role=ScopeRole.EDITOR, granted_by=user.id)
+
+# Project object into scope (only owner can project)
+projections.project(scope_id=scope.id, object_id=obj.id, projected_by=user.id)
+
+# Revoke projection
+projections.revoke_projection(scope_id=scope.id, object_id=obj.id, revoked_by=user.id)
+```
+
+### Audit Trail
+
+```python
+from scoped.audit.writer import AuditWriter
+from scoped.types import ActionType
+
+writer = AuditWriter(backend)
+entry = writer.record(
+    actor_id=user.id,
+    action=ActionType.CREATE,
+    target_type="document",
+    target_id=obj.id,
+)
+```
+
+### Rules Engine
+
+```python
+from scoped.rules.engine import RuleStore, RuleEngine
+from scoped.rules.models import RuleType, RuleEffect, BindingTargetType
+
+store = RuleStore(backend)
+rule = store.create_rule(
+    name="deny-external",
+    rule_type=RuleType.ACCESS,
+    effect=RuleEffect.DENY,
+    priority=10,
+    created_by=admin.id,
+)
+store.bind_rule(rule.id, target_type=BindingTargetType.SCOPE, target_id=scope.id, bound_by=admin.id)
+
+engine = RuleEngine(backend)
+result = engine.evaluate(action="read", principal_id=user.id, scope_id=scope.id)
+# result.allowed -> bool
+```
+
+### Events
+
+```python
+from scoped.events import EventBus, EventType, SubscriptionManager
+
+bus = EventBus(backend)
+event = bus.emit(
+    EventType.OBJECT_CREATED,
+    actor_id=user.id,
+    target_type="document",
+    target_id=doc.id,
+)
+```
+
+### Notifications
+
+```python
+from scoped.notifications import NotificationEngine, NotificationChannel
+
+engine = NotificationEngine(backend)
+rule = engine.create_rule(
+    name="Deploy Alerts",
+    owner_id=admin.id,
+    event_types=["deployment_completed"],
+    recipient_ids=[ops.id],
+    channel=NotificationChannel.IN_APP,
+)
+notifications = engine.process_event(event)
+```
+
+### Scheduling
+
+```python
+from scoped.scheduling import Scheduler, JobQueue
+
+scheduler = Scheduler(backend)
+action = scheduler.create_action(
+    name="Nightly cleanup",
+    owner_id=admin.id,
+    action_type="cleanup",
+    action_config={"max_age_hours": 24},
+    next_run_at=tomorrow_2am,
+)
+
+queue = JobQueue(backend, executor=my_executor)
+job = queue.enqueue(name="Cleanup", action_type="cleanup", action_config={}, owner_id=admin.id)
+queue.run_next()
+```
+
+## Common Pitfalls
+
+- **`create_scope()` not `create()`** — `ScopeLifecycle` method is `create_scope()`
+- **`create_principal()` not `create()`** — `PrincipalStore` method is `create_principal()`
+- **`add_member()` requires `granted_by` and `ScopeRole` enum** — not a string role
+- **`revoke_projection()` not `revoke()`** — `ProjectionManager` method name
+- **FK constraints in tests** — to create orphaned data for compliance testing, wrap with `PRAGMA foreign_keys = OFF/ON`
+- **`ScopedManager.get()` is owner-only** — projections don't grant manager-level access
+- **Rollback traces vs DB state** — `RollbackExecutor._apply_rollback_state()` only modifies DB for `target_type == "object"` literally; `ScopedManager` uses the actual object_type (e.g., "document") as target_type
+- **`backend.initialize()` required** — always call after creating `SQLiteBackend`
+
+## Framework Adapters (`scoped.contrib`)
+
+All adapters are optional — install with extras: `pip install scoped[django]`, etc.
+
+### Django
+
+```python
+# settings.py
+INSTALLED_APPS = ["scoped.contrib.django"]
+MIDDLEWARE = ["scoped.contrib.django.middleware.ScopedContextMiddleware"]
+SCOPED_PRINCIPAL_HEADER = "HTTP_X_SCOPED_PRINCIPAL_ID"
+
+# Management commands: scoped_health, scoped_audit, scoped_compliance
+```
+
+### FastAPI
+
+```python
+from fastapi import FastAPI
+from scoped.contrib.fastapi.middleware import ScopedContextMiddleware
+from scoped.contrib.fastapi.router import router as scoped_router
+from scoped.contrib.fastapi.dependencies import get_scoped_context, get_principal
+
+app = FastAPI()
+app.add_middleware(ScopedContextMiddleware, backend=backend)
+app.include_router(scoped_router)  # adds /scoped/health, /scoped/audit
+```
+
+### Flask
+
+```python
+from flask import Flask
+from scoped.contrib.flask.extension import ScopedExtension
+from scoped.contrib.flask.admin import admin_bp
+
+app = Flask(__name__)
+scoped = ScopedExtension(app)       # auto-inits backend, injects g.scoped_context
+app.register_blueprint(admin_bp)     # adds /scoped/health, /scoped/audit
+```
+
+### MCP (Model Context Protocol)
+
+```python
+from scoped.contrib.mcp.server import create_scoped_server
+
+mcp = create_scoped_server(backend)  # registers tools + resources
+mcp.run()
+# Tools: create_principal, create_object, get_object, create_scope, list_audit, health_check
+# Resources: scoped://principals, scoped://health, scoped://audit/recent
+```
+
+## Project Structure
+
+```
+scoped/
+    __init__.py              # version
+    conf.py                  # ScopedConfig
+    exceptions.py            # all framework exceptions
+    types.py                 # generate_id, now_utc, URN, ActionType, Lifecycle
+
+    registry/                # Layer 1
+    identity/                # Layer 2
+    objects/                 # Layer 3 + blobs, search, import/export
+    tenancy/                 # Layer 4 + config hierarchy
+    rules/                   # Layer 5 + redaction, rate limits, quotas, feature flags
+    audit/                   # Layer 6
+    temporal/                # Layer 7
+    environments/            # Layer 8
+    flow/                    # Layer 9
+    deployments/             # Layer 10
+    secrets/                 # Layer 11
+    integrations/            # Layer 12
+    connector/               # Layer 13 + marketplace/
+    events/                  # Layer 14
+    notifications/           # Layer 15
+    scheduling/              # Layer 16
+    testing/                 # Layer 0 (compliance)
+    storage/                 # backends + migrations + tiering
+    contrib/                 # Phase D: Framework adapters
+        _base.py             # shared utilities (build_services, resolve_principal)
+        django/              # D1: Django adapter
+        fastapi/             # D2: FastAPI adapter
+        flask/               # D3: Flask adapter
+        mcp/                 # D4: MCP adapter
+
+tests/
+    conftest.py              # shared fixtures
+    test_registry/           # ... one directory per layer
+    test_compliance/
+    test_contrib/            # adapter tests (D1-D4)
+    test_integration/        # end-to-end tests
+
+docs/
+    architecture.md          # full architecture document
+    layers/                  # per-layer documentation (00-16)
+    extensions/              # A1-A9 extension docs
+```
+
+## Documentation
+
+- [Architecture Overview](docs/architecture.md) — the full system design
+- [Layer Docs](docs/layers/) — one file per layer (00-compliance through 16-scheduling)
+- [Extension Docs](docs/extensions/) — A1-migrations through A9-import-export
+
+## Using Scoped in Another Project
+
+When building an application on Scoped, the typical bootstrap is:
+
+```python
+from scoped.storage.sqlite import SQLiteBackend
+from scoped.identity.principal import PrincipalStore
+from scoped.objects.manager import ScopedManager
+from scoped.tenancy.lifecycle import ScopeLifecycle
+from scoped.tenancy.projection import ProjectionManager
+from scoped.audit.writer import AuditWriter
+from scoped.rules.engine import RuleStore, RuleEngine
+
+# 1. Initialize storage
+backend = SQLiteBackend("app.db")
+backend.initialize()
+
+# 2. Create stores
+principals = PrincipalStore(backend)
+manager = ScopedManager(backend)
+scopes = ScopeLifecycle(backend)
+projections = ProjectionManager(backend)
+audit = AuditWriter(backend)
+rules = RuleStore(backend)
+
+# 3. Create a principal (the acting user)
+user = principals.create_principal(kind="user", display_name="Alice")
+
+# 4. Everything after this requires ScopedContext
+from scoped.identity.context import ScopedContext
+
+with ScopedContext(principal=user):
+    obj, ver = manager.create(object_type="task", owner_id=user.id, data={"title": "Hello"})
+    scope = scopes.create_scope(name="My Team", owner_id=user.id)
+    projections.project(scope_id=scope.id, object_id=obj.id, projected_by=user.id)
+```

pyscoped-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kwip-info
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.