autonoma-ai 0.2.8.dev1784101031__tar.gz → 0.2.9__tar.gz

{autonoma_ai-0.2.8.dev1784101031 → autonoma_ai-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autonoma-ai
-Version: 0.2.8.dev1784101031
+Version: 0.2.9
 Summary: Autonoma SDK — automate the Autonoma Environment Factory endpoint
 License: MIT
 License-File: LICENSE

{autonoma_ai-0.2.8.dev1784101031 → autonoma_ai-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "autonoma-ai"
-version = "0.2.8.dev1784101031"
+version = "0.2.9"
 description = "Autonoma SDK — automate the Autonoma Environment Factory endpoint"
 authors = ["Autonoma AI <eng@autonoma.ai>"]
 license = "MIT"
@@ -27,6 +27,12 @@ packages = [
     { include = "autonoma_fastapi", from = "src" },
     { include = "autonoma_django", from = "src" },
 ]
+# Bundle the agent-facing docs (Markdown) as package data inside `autonoma`, so
+# they land at site-packages/autonoma/docs/ on install.
+include = [
+    { path = "src/autonoma/docs/**/*", format = ["sdist", "wheel"] },
+    { path = "src/autonoma/AGENTS.md", format = ["sdist", "wheel"] },
+]
 
 [tool.poetry.extras]
 flask = ["flask"]

autonoma_ai-0.2.9/src/autonoma/AGENTS.md

@@ -0,0 +1,21 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/languages/python/AGENTS.md. Edit the source, not this copy. -->
+<!-- BEGIN:autonoma-agent-rules -->
+
+# Autonoma SDK: read the bundled docs before wiring the endpoint
+
+This package implements the **Autonoma Environment Factory** - a backend endpoint that creates and tears down isolated test data. If you are integrating it, the accurate, version-matched docs ship inside this package. Read them before writing code; your training data may describe an older, adapter-based API that no longer exists.
+
+**Start here:** `./docs/implement.md` (in `site-packages/autonoma/docs/implement.md` once installed).
+
+Reading order:
+
+1. `docs/overview.md` - what the Environment Factory is and why it is factory-driven.
+2. `docs/implement.md` - step-by-step setup: install, factories, handler, auth, validate.
+3. `docs/factories.md` - the `define_factory` contract in Python.
+4. `docs/scenarios.md` - the `create` data format (`_alias`/`_ref`).
+5. `docs/protocol.md` - the HTTP wire protocol and error codes.
+6. `docs/validation.md` - dry-running scenarios with `check_scenario`.
+
+Key facts that differ from older docs: the SDK is **factory-driven** (register factories with `define_factory`; there is no `prisma_adapter`/SQLAlchemy adapter and no ORM adapter package). The distribution is `autonoma-ai`; the import package is `autonoma`. Each factory declares a Pydantic v2 `input_model` (there is no database introspection). The main entry is `handle_request`, wrapped by a server adapter (`create_fastapi_handler`, `create_flask_handler`, `create_django_handler`). The auth callback returns a dict with `cookies`, `headers`, and/or `credentials` - there is no `token` field.
+
+<!-- END:autonoma-agent-rules -->

{autonoma_ai-0.2.8.dev1784101031 → autonoma_ai-0.2.9}/src/autonoma/check.py

@@ -51,7 +51,6 @@ async def check_scenario(
         signing_secret=signing_secret,
         auth=options.get("auth", lambda _user, _ctx: {"headers": {"Authorization": "Bearer check-token"}}),
         factories=factories,
-        allow_production=True,
     )
 
     up_body = json.dumps({"action": "up", "create": scenario.get("create", {})})

autonoma_ai-0.2.9/src/autonoma/docs/factories.md

@@ -0,0 +1,128 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/languages/python/factories.md. Edit the source, not this copy. -->
+# Writing factories (Python)
+
+A factory tells the SDK how to create and delete one model using your own code. You register one factory per model the platform can create, and pass them all to the handler as `factories`. This page is the exact contract; read it before writing any.
+
+## The shape
+
+```python
+# factories/organization.py
+from pydantic import BaseModel, ConfigDict
+from autonoma import define_factory
+from app.db import db   # your app's real database client
+
+class OrganizationInput(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    name: str
+    slug: str
+
+def _create(data, ctx):
+    org = db.create_organization(name=data.name, slug=data.slug)
+    return {"id": str(org.id), "name": org.name, "slug": org.slug}
+
+def _teardown(record, ctx):
+    db.delete_organization(record["id"])
+
+Organization = define_factory(
+    create=_create,
+    input_model=OrganizationInput,
+    teardown=_teardown,
+)
+```
+
+`define_factory(create, input_model, teardown=None, ref_model=None)` validates the shape at startup and returns a `FactoryDefinition`. Import it from the top-level `autonoma` package. `input_model` is a Pydantic v2 class - Pydantic ships as a hard dependency of the SDK, so there is nothing extra to install.
+
+## input_model (required)
+
+A Pydantic v2 `BaseModel` describing the fields this model accepts in the create payload. It does two jobs:
+
+1. The SDK validates each incoming record with `input_model.model_validate(...)` before calling `create`.
+2. The SDK derives the discover schema from it - there is no database introspection, so this model is how the platform learns your model exists and what fields it has.
+
+Set `model_config = ConfigDict(extra="ignore")` so recipe-only metadata the platform may attach does not trip validation.
+
+**Include every foreign key in the input model, including the scope field.** By the time `create` runs, the SDK has already resolved every `_ref` to the real ID of the referenced record, so a FK arrives as a plain value:
+
+```python
+# factories/user.py
+from pydantic import BaseModel, ConfigDict
+from autonoma import define_factory
+from app.signup import create_user   # reuse your real signup code
+
+class UserInput(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+    name: str
+    email: str
+    organizationId: str   # arrives as the real Organization id, not a _ref
+
+def _create(data, ctx):
+    user = create_user(name=data.name, email=data.email, org_id=data.organizationId)
+    return {"id": str(user.id), "email": user.email}
+
+User = define_factory(create=_create, input_model=UserInput)
+```
+
+## create(data, ctx)
+
+Creates exactly one record and returns it. It may be a plain `def` or an `async def` - the SDK awaits the result when it is a coroutine.
+
+- `data` - a validated **instance** of `input_model`, so read fields as attributes (`data.name`, `data.organizationId`). FK fields are already real IDs.
+- `ctx` - a `FactoryContext` with `refs`, `scenario_name`, and `test_run_id`. `refs` holds every record created so far this run, keyed by model, if you need to look something up.
+- **Return value** - a `dict` that includes at least the primary key `id`, or a Pydantic instance (the SDK calls `model_dump()` on it). If the returned record has no `id`, the SDK fails the request with `FACTORY_MISSING_PK`. Everything you return is stored in `refs`, passed to the auth callback, and later handed to `teardown` - so return whatever teardown or auth will need (typically the id, plus fields like `email`).
+
+Reuse your application's real creation path (`create_user`, `create_organization`, a service method). That is the entire point: the test user gets the same password hash, defaults, and side effects a real user would.
+
+## teardown(record, ctx) - optional
+
+Deletes one record. The SDK calls it once per created record, in reverse dependency order, during `down`. It may be sync or async.
+
+- `record` - exactly what your `create` returned: a `dict` (so `record["id"]`), unless you set `ref_model`, in which case it is a validated instance (so `record.id`).
+- If you omit `teardown`, the model is never deleted on `down` - the SDK has no SQL fallback. Provide it for every model you create, or those rows leak.
+
+```python
+# factories/user.py
+def _teardown(record, ctx):
+    db.delete_user(record["id"])
+
+User = define_factory(create=_create, input_model=UserInput, teardown=_teardown)
+```
+
+## ref_model - optional
+
+A Pydantic v2 class for the record `create` returns. When set, the SDK validates the stored record through `ref_model.model_validate(record)` before `teardown`, and `record` arrives as an instance (attribute access, no dict lookups):
+
+```python
+# factories/user.py
+class UserRef(BaseModel):
+    id: str
+    email: str
+
+def _teardown(record, ctx):
+    db.delete_user(record.id)   # record is a UserRef instance
+
+User = define_factory(
+    create=_create,
+    input_model=UserInput,
+    teardown=_teardown,
+    ref_model=UserRef,
+)
+```
+
+## Registering factories
+
+Collect every factory into one `dict` keyed by model name - the key must match the model name the platform sends in `create`:
+
+```python
+# factories/__init__.py
+from factories.organization import Organization
+from factories.user import User
+from factories.member import Member
+
+factories = {
+    "Organization": Organization,
+    "User": User,
+    "Member": Member,
+}
+```
+
+Pass that dict as `factories` when you create the handler (see `implement.md`). Every model that appears in a scenario must have an entry here, or the request fails with `INVALID_BODY` ("no factory registered for model ...").

autonoma_ai-0.2.9/src/autonoma/docs/implement.md

@@ -0,0 +1,196 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/languages/python/implement.md. Edit the source, not this copy. -->
+# Implement the endpoint (Python)
+
+Follow these steps to stand up a working Environment Factory endpoint. This is written for a coding agent doing the integration; do the steps in order and do not skip the validation step.
+
+## Prerequisites
+
+- A Python 3.10+ backend on FastAPI, Flask, or Django.
+- The database client your app already uses (SQLAlchemy, Django ORM, raw `psycopg` - it does not matter; your factories call it).
+- Pydantic v2. It ships as a hard dependency of the SDK, so it installs automatically.
+
+## Step 1 - Detect the stack and pick packages
+
+Install the core distribution `autonoma-ai` with the extra that matches the app's HTTP framework. There is no ORM adapter package to install - the SDK is factory-driven.
+
+| Framework | Install command | Handler module | Handler function |
+|-----------|-----------------|----------------|------------------|
+| FastAPI | `pip install "autonoma-ai[fastapi]"` | `autonoma_fastapi` | `create_fastapi_handler` |
+| Flask | `pip install "autonoma-ai[flask]"` | `autonoma_flask` | `create_flask_handler` |
+| Django | `pip install "autonoma-ai[django]"` | `autonoma_django` | `create_django_handler` |
+
+```bash
+# terminal - example: FastAPI
+pip install "autonoma-ai[fastapi]"
+```
+
+The import package is `autonoma` (plus the framework module), even though the distribution is named `autonoma-ai`. Use the project's package manager (pip, poetry, uv) as appropriate; `pip install "autonoma-ai[all]"` pulls every adapter.
+
+## Step 2 - Generate the two secrets
+
+```bash
+# terminal
+openssl rand -hex 32   # AUTONOMA_SHARED_SECRET
+openssl rand -hex 32   # AUTONOMA_SIGNING_SECRET  (must be different)
+```
+
+Add both to your environment (and placeholders to `.env.example` if it exists). The SDK raises `SAME_SECRETS` if they match.
+
+```bash
+# .env
+AUTONOMA_SHARED_SECRET=...   # shared with Autonoma
+AUTONOMA_SIGNING_SECRET=...  # private, never shared
+```
+
+## Step 3 - Find the scope field
+
+Read the database schema. Find the foreign key that appears on the most models and points at a single root entity - commonly `organizationId`, `orgId`, `tenantId`, or `workspaceId`. That is the scope field. The root model itself (e.g. `Organization`) does not carry it.
+
+Confirm the field, the endpoint path, and the app's auth mechanism with the user before writing code.
+
+## Step 4 - Write a factory per model
+
+Write one factory for each model the platform will create, calling your app's real creation code. See `factories.md` for the full contract. Collect them into one registry keyed by model name:
+
+```python
+# factories/__init__.py
+from factories.organization import Organization
+from factories.user import User
+from factories.member import Member
+
+factories = {"Organization": Organization, "User": User, "Member": Member}
+```
+
+## Step 5 - Wire the handler
+
+Create one `HandlerConfig` and pass it to your adapter's handler function. The config carries the scope field, both secrets, the factory registry, and the auth callback. All config fields are `snake_case`.
+
+```python
+# app/autonoma_endpoint.py  (FastAPI)
+import os
+from autonoma import HandlerConfig
+from autonoma_fastapi import create_fastapi_handler
+from factories import factories
+from app.auth import create_session   # your app's real session code
+
+config = HandlerConfig(
+    scope_field="organizationId",
+    shared_secret=os.environ["AUTONOMA_SHARED_SECRET"],
+    signing_secret=os.environ["AUTONOMA_SIGNING_SECRET"],
+    factories=factories,
+    auth=lambda user, ctx: {
+        "cookies": [
+            {"name": "session", "value": create_session(user["id"]),
+             "httpOnly": True, "sameSite": "lax", "path": "/"}
+        ],
+    },
+)
+
+router = create_fastapi_handler(config)
+app.include_router(router, prefix="/api/autonoma")
+```
+
+Other frameworks use the same `config` object; only the mounting differs:
+
+```python
+# app/autonoma_endpoint.py  (Flask)
+from autonoma_flask import create_flask_handler
+
+bp = create_flask_handler(config)
+app.register_blueprint(bp, url_prefix="/api/autonoma")
+```
+
+```python
+# urls.py  (Django)
+from django.urls import path
+from autonoma_django import create_django_handler
+from app.autonoma_endpoint import config
+
+urlpatterns = [
+    path("api/autonoma", create_django_handler(config)),
+]
+```
+
+The Flask and FastAPI adapters register their route at `/`, so with a `/api/autonoma` prefix the live path is `/api/autonoma/` (trailing slash). With Django you control the exact path in `urls.py`.
+
+FastAPI also accepts `create_fastapi_handler(config_factory=make_config)` - a zero-arg callable that returns a fresh `HandlerConfig` per request, useful when a factory needs per-request state such as a database session.
+
+## Step 6 - Implement the auth callback
+
+This is the part that most often breaks tests, so get it right. The callback receives the first created `User` record as a `dict` (or `None` if the scenario made none) and an `AuthContext` with `scope_value` and `refs`. It must return **real, working credentials** using the app's actual auth mechanism. If it returns a fake or hardcoded token, every test fails at login. The callback may be sync or async (`async def`).
+
+The return type is a dict with any of `cookies`, `headers`, `credentials` - there is no top-level `token` field. Pick the shape that matches how your app authenticates:
+
+```python
+# app/autonoma_endpoint.py
+# Session cookie (most web apps)
+def auth(user, ctx):
+    token = create_session(user["id"])
+    return {"cookies": [
+        {"name": "session", "value": token, "httpOnly": True, "sameSite": "lax", "path": "/"}
+    ]}
+
+# JWT bearer token (APIs, SPAs) - the token goes in a header
+def auth(user, ctx):
+    token = jwt.encode({"sub": user["id"]}, os.environ["JWT_SECRET"], algorithm="HS256")
+    return {"headers": {"Authorization": f"Bearer {token}"}}
+
+# Email + password (the runner logs in through the UI, e.g. mobile)
+def auth(user, ctx):
+    return {"credentials": {"email": user["email"], "password": "test-password-123"}}
+```
+
+For the email/password shape, the `User` factory must create the record with a matching password hash, so a real login succeeds.
+
+## Step 7 - The endpoint is always enabled
+
+There is no on/off switch: HMAC signing is the gate, so unsigned or tampered requests get `401` no matter where the endpoint runs. On Autonoma preview environments (`AUTONOMA_PREVIEWKIT` is set) no extra guard is needed - previews are isolated and never production. If you deploy the factory in your own environments and want it dark in production anyway, gate it in your handler with your own condition:
+
+```python
+# app/autonoma_endpoint.py  (your route, before delegating to the SDK)
+if os.environ.get("APP_ENV") == "production":
+    raise HTTPException(status_code=404)   # or your framework's 404
+```
+
+The old `allow_production` config option is deprecated and ignored - passing it changes nothing.
+
+## Step 8 - Validate before deploying
+
+Dry-run your scenarios against a real database with `check_scenario` and iterate until they pass. See `validation.md`. Never ship a scenario you have not validated.
+
+## Step 9 - Smoke-test with curl
+
+```bash
+# terminal
+SECRET="your-shared-secret"
+BODY='{"action":"discover"}'
+SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/.*= //')
+curl -s -X POST http://localhost:8000/api/autonoma/ \
+  -H "Content-Type: application/json" -H "x-signature: $SIG" -d "$BODY" | jq .
+```
+
+Expected: a JSON schema listing your models and `scopeField`. A `404` means the route is not mounted; a `401` means the secret does not match.
+
+## Step 10 - Report and connect
+
+Tell the user the endpoint path, confirm all scenarios pass, and hand off:
+
+1. Set `AUTONOMA_SHARED_SECRET` and `AUTONOMA_SIGNING_SECRET` in staging/production env.
+2. Deploy the endpoint.
+3. Paste `AUTONOMA_SHARED_SECRET` into the Autonoma dashboard when connecting the app.
+
+## Rules
+
+**Do:**
+- Reuse the app's existing DB client and real creation code inside factories.
+- Return real credentials from `auth` using the app's own session/JWT logic.
+- Register a factory (with a `teardown`) for every model any scenario creates.
+- Match the project's conventions: import style, file layout, naming.
+- Validate every scenario with `check_scenario` before deploying.
+
+**Do not:**
+- Implement HMAC, token signing, or teardown ordering yourself - the SDK owns all of it.
+- Return a hardcoded token like `"test-token"` from `auth`.
+- Use the same value for `shared_secret` and `signing_secret`.
+- Set `id`, defaulted fields, or auto timestamps in scenario data.
+- Expect the SDK to inject the scope field or wire any FK - you set every FK as a `_ref`.

autonoma_ai-0.2.9/src/autonoma/docs/llms.txt

@@ -0,0 +1,14 @@
+# Autonoma Environment Factory SDK
+
+> This package implements the Autonoma Environment Factory: a single backend endpoint that creates isolated, factory-driven test data before an end-to-end test run and tears it down afterward. These docs are bundled inside the installed package so a coding agent can read the API that matches this exact version, instead of relying on training data.
+
+If you are setting up the endpoint, read `implement.md` and follow it step by step. The other files are reference.
+
+## Reading order
+
+1. overview.md - What the Environment Factory is, the three actions (discover/up/down), the scope field, the two secrets, and why it is factory-driven. Start here.
+2. implement.md - Step-by-step setup for this language: install, register factories, wire the handler, implement the auth callback, enable the endpoint, and validate. This is the doc to follow when integrating.
+3. factories.md - How to write a factory in this language: the `create`/`teardown` contract, the input schema, and what `create` receives and must return.
+4. scenarios.md - The `create` data format: the flat map, `_alias`/`_ref` links, the scope field, and the three standard scenarios. Language-agnostic.
+5. protocol.md - The HTTP wire protocol: authentication, the three actions, the refs token, the safety model, and every error code. Language-agnostic. Reach for this when debugging.
+6. validation.md - How to dry-run a scenario against a real database in this language before deploying.

autonoma_ai-0.2.9/src/autonoma/docs/overview.md

@@ -0,0 +1,83 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/shared/overview.md. Edit the source, not this copy. -->
+# Overview
+
+The Autonoma Environment Factory is a single endpoint in your backend that creates fresh, isolated test data before an end-to-end test run and deletes it afterward. This SDK implements that endpoint for you.
+
+## Why it exists
+
+Every end-to-end test needs data. A test for "user adds an item to the cart" needs a user, some products, and a cart. A test for "admin views analytics" needs an organization with users, runs, and history.
+
+Tests cannot share data. If one test deletes a product, another test that expects ten products fails. Running tests in parallel makes this worse. The Environment Factory gives each test run its own organization, its own users, and its own records, then tears all of it down when the run finishes. No interference, no leftover rows.
+
+## How it works
+
+The platform talks to one HTTP POST endpoint that you mount in your app (you choose the path, e.g. `/api/autonoma`). The endpoint handles three actions:
+
+| Action | What the platform asks | What the SDK does |
+|--------|------------------------|-------------------|
+| `discover` | "What models can you create?" | Returns the model + field list, derived from your registered factories. |
+| `up` | "Create this data." | Runs each record through its factory in dependency order, returns login credentials and a signed teardown token. |
+| `down` | "Delete what you created." | Verifies the token and calls each factory's teardown in reverse order. |
+
+You do not write routing, signature checks, dependency sorting, or teardown logic. You write factories and an auth callback, and the SDK does the rest.
+
+## Factory-driven: you own every write
+
+This SDK never runs SQL and never touches your database directly. Every model it creates goes through a factory you register - a small function that calls your own code to make one record. This is the core design decision, and it has two consequences worth internalizing before you write anything:
+
+- **Test data is created the way production data is.** If your app hashes passwords in `createUser`, your factory calls `createUser`, so the test user has a real password hash. A raw database seed could never reproduce that. Factories reuse your real creation logic - password hashing, external-service calls, state-machine defaults - instead of guessing at column values.
+- **The endpoint is safe by construction.** `up` can only insert (through your factories). `down` can only delete records that `up` created (proven by a signed token). The SDK has no code path that can `UPDATE`, `DROP`, `TRUNCATE`, or run an arbitrary query. See [protocol.md](protocol.md) for the full safety model.
+
+There is no ORM adapter, no schema introspection, and no SQL fallback. A model with no registered factory simply cannot be created.
+
+## What you provide
+
+Four things, passed as configuration when you create the handler:
+
+| Config | What it is |
+|--------|------------|
+| `scopeField` | The single column name that isolates test data (e.g. `organizationId`). |
+| `factories` | One factory per model the platform can create. |
+| `sharedSecret` | Shared with Autonoma. Verifies that incoming requests are authentic (HMAC). |
+| `signingSecret` | Known only to you. Signs the teardown token so it cannot be forged. |
+| `auth` | A callback that returns real login credentials for the created test user. |
+
+## The scope field
+
+Most multi-tenant apps have one foreign key on nearly every model - `organizationId`, `orgId`, `tenantId`, `workspaceId`. That column is your scope field: the boundary that keeps one test run's data separate from another's.
+
+Two things to know:
+
+- **You set it; the SDK does not.** The SDK never injects the scope field into a record. Every model that has it must set it explicitly in the create payload, normally as a `_ref` pointing at the scope record. Your factory writes it. The SDK only *reads* the scope field after creation, to derive the value it hands your auth callback.
+- **It must be a single column.** Compound scope keys (e.g. `organizationId` + `countryId`) are not supported. If your app scopes by several fields, use one root entity whose ID the child models reference. If your app is not multi-tenant at all, add a dedicated field like `testRunId` to every model and use that.
+
+## The two secrets
+
+You need two different secret values. The SDK throws `SAME_SECRETS` at startup if they match.
+
+- **Shared secret** - both you and Autonoma hold it. Autonoma signs every request with it (HMAC-SHA256); your endpoint verifies the signature. This stops anyone else from calling your endpoint.
+- **Signing secret** - only you hold it. During `up` the SDK signs a token listing every created record's ID. During `down` it verifies that token before deleting. Autonoma stores the token opaquely and passes it back; it can neither read nor forge it.
+
+Generate them as two distinct random values:
+
+```bash
+openssl rand -hex 32   # AUTONOMA_SHARED_SECRET
+openssl rand -hex 32   # AUTONOMA_SIGNING_SECRET (must differ)
+```
+
+## Language availability
+
+The SDK ships for eight languages, each an independent implementation that passes the same conformance suite. The protocol behavior is identical everywhere; only package names and syntax differ.
+
+| Language | Server adapters |
+|----------|-----------------|
+| TypeScript | Web standard (Next.js App Router, Bun, Deno), Express, Hono, Node http |
+| Python | FastAPI, Flask, Django |
+| Elixir | Plug (Phoenix) |
+| PHP | Laravel |
+| Java | Spring Boot |
+| Ruby | Rails / Rack |
+| Rust | Actix, Axum |
+| Go | Gin |
+
+See `implement.md` for the step-by-step setup in your language, `factories.md` for how to write factories, `scenarios.md` for the data format, and `protocol.md` for the wire protocol.

autonoma_ai-0.2.9/src/autonoma/docs/protocol.md

@@ -0,0 +1,136 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/shared/protocol.md. Edit the source, not this copy. -->
+# Protocol
+
+The Environment Factory protocol is a request-response protocol over a single HTTP POST endpoint, authenticated with HMAC-SHA256. It is identical across every language SDK. This page is the wire contract; you rarely need it to integrate, but it is the source of truth when debugging.
+
+Protocol version: `1.0`
+
+## Transport and authentication
+
+All communication is HTTP POST to one URL that you choose. Requests and responses are JSON.
+
+Every request carries an `x-signature` header: the HMAC-SHA256 of the raw request body, keyed with the shared secret, as a hex digest. The SDK recomputes the HMAC over the exact request bytes (before any JSON parsing) and compares in constant time. A missing or wrong signature is rejected with `401`.
+
+```
+x-signature: HMAC-SHA256(raw_request_body_bytes, sharedSecret)  ->  hex
+```
+
+Because the signature is over the raw bytes, a server adapter must read the body as an untouched string before framework middleware reparses it. This is the one subtle requirement server adapters exist to satisfy.
+
+## Response metadata
+
+Every successful response includes:
+
+```json
+{
+  "version": "1.0",
+  "sdk": { "language": "typescript", "orm": "unknown", "server": "web" }
+}
+```
+
+`orm` is `"unknown"` in factory-driven mode - the SDK does not talk to an ORM. Error responses replace the payload with `{ "error": "...", "code": "..." }`.
+
+## Actions
+
+### discover
+
+```json
+// request
+{ "action": "discover" }
+```
+
+```json
+// response 200
+{
+  "version": "1.0",
+  "sdk": { "language": "typescript", "orm": "unknown", "server": "web" },
+  "schema": {
+    "models": [
+      { "name": "Organization", "tableName": "organization", "fields": [
+        { "name": "name", "type": "string", "isRequired": true, "isId": false, "hasDefault": false }
+      ] }
+    ],
+    "edges": [],
+    "relations": [],
+    "scopeField": "organizationId"
+  }
+}
+```
+
+The schema is built from your factories' input schemas, not from database introspection. `models` and `scopeField` are the meaningful parts. `edges` and `relations` are always empty arrays - the SDK does not introspect foreign keys, so it emits nothing there. Dependency order is not carried in the schema; it is derived per request from the `_alias`/`_ref` graph in the `up` payload.
+
+### up
+
+```json
+// request
+{
+  "action": "up",
+  "testRunId": "optional-uuid",
+  "create": {
+    "Organization": [{ "_alias": "org", "name": "Acme", "slug": "acme" }],
+    "User": [{ "_alias": "alice", "email": "alice@test.com", "organizationId": { "_ref": "org" } }],
+    "Member": [{ "role": "owner", "organizationId": { "_ref": "org" }, "userId": { "_ref": "alice" } }]
+  }
+}
+```
+
+`create` is a flat map keyed by model name; each value is an array of records. Cross-model links use `_alias`/`_ref` (see [scenarios.md](scenarios.md)). If `testRunId` is omitted the SDK generates a UUID.
+
+```json
+// response 200
+{
+  "version": "1.0",
+  "sdk": { "language": "typescript", "orm": "unknown", "server": "web" },
+  "auth": { "cookies": [], "headers": {}, "credentials": {} },
+  "refs": { "Organization": [{ "id": "..." }], "User": [{ "id": "..." }] },
+  "refsToken": "header.payload.signature"
+}
+```
+
+- `auth` - whatever your auth callback returned: `cookies`, `headers`, and/or `credentials`. There is no top-level `token` field; a bearer token goes in `headers` (e.g. `{ "Authorization": "Bearer ..." }`).
+- `refs` - every created record, keyed by model, exactly as each factory returned it.
+- `refsToken` - a signed token encoding the created IDs, passed back on `down`.
+
+### down
+
+```json
+// request
+{ "action": "down", "refsToken": "header.payload.signature" }
+```
+
+```json
+// response 200
+{ "version": "1.0", "sdk": { ... }, "ok": true }
+```
+
+The SDK verifies the token, then calls each factory's `teardown` in reverse dependency order. A model whose factory defines no teardown is skipped.
+
+## The refs token
+
+The refs token is a JWT-like structure (`header.payload.signature`) signed with your signing secret. It carries the scope value, every created record ID keyed by model, and the alias dependency graph needed to reverse the create order. Because only your backend knows the signing secret, neither the platform nor any third party can forge or alter it. This is what guarantees `down` can only delete what `up` created.
+
+## Safety model
+
+The protocol enforces five hard constraints:
+
+1. **The production guard is yours.** The SDK has no on/off switch - on Autonoma preview environments (`AUTONOMA_PREVIEWKIT` is set) no guard is needed, previews are isolated and never production. In your own deployments, mount the route only outside production with a condition you own (for example, register the endpoint only when `NODE_ENV` is not `production`). The old `allowProduction` option is deprecated and ignored.
+2. **Up can only create.** Every record routes through a factory's `create`. The SDK never updates, deletes, drops, truncates, or runs SQL of its own.
+3. **Down can only delete what up created.** The signed token names the exact record IDs. `down` verifies it before deleting and touches nothing else.
+4. **Requests are authenticated.** Every request is HMAC-signed with the shared secret. Unsigned or tampered requests get `401` - the endpoint serves no unauthenticated caller.
+5. **Factory-driven writes.** There is no executor and no SQL fallback. A factory body may run a raw insert internally, but that code is yours, not the SDK's.
+
+## Error codes
+
+| Code | HTTP | Meaning |
+|------|------|---------|
+| `INVALID_SIGNATURE` | 401 | HMAC signature missing or does not match the shared secret. |
+| `INVALID_BODY` | 400 | Body is not valid JSON, is missing `action`/`create`, or references an unknown alias. |
+| `UNKNOWN_ACTION` | 400 | `action` is not `discover`, `up`, or `down`. |
+| `UNKNOWN_ENVIRONMENT` | 400 | The requested environment name does not exist. |
+| `INVALID_REFS_TOKEN` | 403 | The refs token is missing, malformed, or failed signature verification. |
+| `UNRESOLVED_TOKEN` | 400 | A literal `{{...}}` placeholder reached the SDK unresolved. |
+| `FACTORY_MISSING_PK` | 500 | A factory's `create` returned a record without its primary key. |
+| `SAME_SECRETS` | 500 | `sharedSecret` and `signingSecret` are the same value. |
+| `INTERNAL_ERROR` | 500 | Unexpected error, or a create payload failed a factory's input schema. |
+
+These are the shared codes. A given language may surface an extra, more specific code for a failure another language folds into `INTERNAL_ERROR` (for example, some SDKs emit `FACTORY_TEARDOWN_ERROR` when a factory's teardown throws). See your language's `validation.md` for any language-specific codes.

autonoma_ai-0.2.9/src/autonoma/docs/scenarios.md

@@ -0,0 +1,109 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/shared/scenarios.md. Edit the source, not this copy. -->
+# Scenario data
+
+Scenario data describes the records a test run needs. The platform generates it from your discover schema, but you write it yourself for integration tests and when debugging. The format is identical across every language SDK.
+
+## The shape: a flat map
+
+Data is a flat map. Top-level keys are model names; each value is an array of records to create for that model.
+
+```json
+{
+  "create": {
+    "Organization": [{ "_alias": "org", "name": "Test Org", "slug": "test-org" }],
+    "User": [{ "_alias": "admin", "name": "Admin", "email": "admin@test.com", "organizationId": { "_ref": "org" } }],
+    "Member": [{ "role": "owner", "organizationId": { "_ref": "org" }, "userId": { "_ref": "admin" } }]
+  }
+}
+```
+
+Two rules cover almost everything:
+
+- **A model is created only when it is a top-level key.** There is no nesting. You never place one model's records inside another model's fields. (If you do, the SDK treats that array as opaque field data and hands it to the factory verbatim - it is not created as separate records.)
+- **Every cross-model link is an `_alias`/`_ref` pair.** Name a record with `_alias`, then point a foreign key at it with `{ "_ref": "alias" }`. This is the only way to link records.
+
+## How ordering works
+
+The SDK builds a dependency graph purely from the `_alias`/`_ref` edges in the payload and topologically sorts it: a record that another record `_ref`s is created first. Key order in the JSON is irrelevant. There is no relation introspection - the graph comes entirely from the `_ref` edges you write.
+
+By the time your factory's `create` runs, every `_ref` has already been replaced with the real ID of the referenced record. Your factory receives a plain FK value (a string or number), never a `_ref` object and never a temporary ID.
+
+A `_ref` to an alias that no record in the same payload declares fails with `INVALID_BODY` ("references unknown alias(es)").
+
+## Setting foreign keys and the scope field
+
+You set every foreign key yourself, including the scope field. There is no "FK direction" to reason about - every link, up or across, is just a `_ref` from the record holding the column to the record it depends on. Use the exact column name from your schema, whatever you called it (`organizationId`, `orgId`, `tenant_fk`).
+
+```json
+{
+  "create": {
+    "Organization": [{ "_alias": "org", "name": "Acme", "slug": "acme" }],
+    "Application": [{ "name": "Marketing Site", "architecture": "WEB", "organizationId": { "_ref": "org" } }],
+    "Member": [
+      { "role": "owner", "organizationId": { "_ref": "org" }, "userId": { "_ref": "alice" } }
+    ],
+    "User": [{ "_alias": "alice", "name": "Alice", "email": "alice@test.com", "organizationId": { "_ref": "org" } }]
+  }
+}
+```
+
+The scope field is a foreign key like any other. The SDK does not inject it - set it explicitly on every model that has it.
+
+## What to include and omit in a record
+
+Include every field your factory's input schema marks required and does not default:
+
+- Required fields with no default value.
+- Every foreign key, as a `{ "_ref": "alias" }`.
+- The scope field, as a `_ref`.
+- Unique fields, with values distinct across records so parallel runs do not collide.
+
+Omit anything the factory or database fills in:
+
+- Primary keys / IDs - generated by your creation code.
+- Fields with default values.
+- Auto-managed timestamps (`createdAt`, `updatedAt`).
+
+## Built-in placeholder tokens
+
+The platform normally resolves all values before calling `up`, but the SDK also understands three placeholder tokens inside string values, as defense in depth:
+
+| Token | Resolves to |
+|-------|-------------|
+| `{{testRunId}}` | The current run's ID - useful for making unique values. |
+| `{{index}}` | The record's zero-based position within its model array. |
+| `{{cycle(a,b,c)}}` | `a`, `b`, `c` in turn, cycling by record index. |
+
+Any other `{{...}}` that reaches the SDK fails loudly with `UNRESOLVED_TOKEN` rather than being inserted as a literal string.
+
+## More link examples
+
+Join table (each row references two aliases):
+
+```json
+{
+  "create": {
+    "Tag": [
+      { "_alias": "tag1", "name": "Critical", "color": "#DC2626", "organizationId": { "_ref": "org" } },
+      { "_alias": "tag2", "name": "Flaky", "color": "#EAB308", "organizationId": { "_ref": "org" } }
+    ],
+    "Test": [{ "_alias": "t1", "name": "Homepage", "testGenerationId": { "_ref": "gen1" } }],
+    "TestTag": [
+      { "testId": { "_ref": "t1" }, "tagId": { "_ref": "tag1" } },
+      { "testId": { "_ref": "t1" }, "tagId": { "_ref": "tag2" } }
+    ]
+  }
+}
+```
+
+Distinct users for distinct members (the common "one member per user" case): give each `User` its own `_alias`, then point each `Member.userId` at a different one. A shared alias would try to make the same user a member twice and hit a unique constraint.
+
+## The three standard scenarios
+
+When setting up a project, create three scenarios as a baseline. Name files after the shape, not the test.
+
+- **empty** - organization + one user + their membership. Tests empty states, onboarding, and "no data yet" screens.
+- **standard** - realistic variety: several users with different roles, at least one record per enum value, descriptive names ("Marketing Website", not "App 1"), enough data to exercise every filter and status.
+- **large** - high volume: many explicitly listed records so pagination, sort stability, and filter performance get tested.
+
+Add more targeted scenarios later, only when a specific test needs a data shape these three do not cover. Do not generate dozens up front.

autonoma_ai-0.2.9/src/autonoma/docs/validation.md

@@ -0,0 +1,110 @@
+<!-- Generated by scripts/build-sdk-docs.mjs from docs/languages/python/validation.md. Edit the source, not this copy. -->
+# Validating scenarios (Python)
+
+Scenario data is often generated by an LLM, so validate it against a real database before it reaches production. `check_scenario` runs the full `up` then `down` cycle through the same handler the platform hits, using your real factories, and reports exactly where it failed.
+
+## check_scenario(factories, scenario, options=None)
+
+`check_scenario` is an async coroutine - `await` it (or run it under pytest with `pytest-asyncio`).
+
+```python
+# tests/test_scenarios.py
+import pytest
+from autonoma import check_scenario
+from factories import factories
+
+@pytest.mark.asyncio
+async def test_standard_scenario():
+    result = await check_scenario(factories, {
+        "create": {
+            "Organization": [{"_alias": "org", "name": "Test Org", "slug": "test-org"}],
+            "User": [{"_alias": "admin", "name": "Admin", "email": "admin@test.com",
+                      "organizationId": {"_ref": "org"}}],
+            "Member": [{"role": "owner", "organizationId": {"_ref": "org"},
+                        "userId": {"_ref": "admin"}}],
+        },
+    }, {"scopeField": "organizationId"})
+
+    if not result.valid:
+        for err in result.errors:
+            print(f"[{err.phase}] {err.message} - {err.fix}")
+    assert result.valid
+```
+
+The first argument is your **factory registry**, not an adapter - `check_scenario` calls the real factories, so they must point at a real (test) database. The third argument is an options `dict` whose keys are **camelCase**: `scopeField`, `auth`, `sharedSecret`, `signingSecret`. All have safe defaults for a dry run, so `{"scopeField": "organizationId"}` is usually all you need.
+
+### The result
+
+`check_scenario` returns a `CheckResult` dataclass:
+
+| Field | Meaning |
+|-------|---------|
+| `valid` | `True` if the full create + teardown cycle succeeded. |
+| `phase` | `"ok"` if it passed, else `"up"` (create rejected) or `"down"` (teardown failed). |
+| `errors` | List of `CheckError`, each with `phase`, `message`, and a suggested `fix` string. |
+| `timing` | `dict` with `"upMs"` and `"downMs"` in milliseconds. |
+
+`message` is the underlying database or SDK error; `fix` is a heuristic hint the SDK derives from common failures (unique constraint, foreign key, null column).
+
+## The testcontainers harness
+
+The reliable way to validate locally is a real Postgres in Docker. Point your factories' database client at the container, drop every scenario file into a folder, and parametrize one test over all of them.
+
+```python
+# tests/test_validate_scenarios.py
+import json
+from pathlib import Path
+import pytest
+from testcontainers.postgres import PostgresContainer
+from autonoma import check_scenario
+
+SCENARIOS_DIR = Path(__file__).parent.parent / "scenarios"
+
+@pytest.fixture(scope="session")
+def database_url():
+    with PostgresContainer("postgres:16-alpine") as pg:
+        url = pg.get_connection_url()
+        # run your migrations against `url` here (alembic upgrade head,
+        # django migrate, create_all, ...)
+        yield url
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "scenario_file", sorted(SCENARIOS_DIR.glob("*.json")), ids=lambda p: p.name
+)
+async def test_scenario(scenario_file, database_url):
+    from factories import build_factories   # build factories bound to database_url
+    factories = build_factories(database_url)
+    scenario = json.loads(scenario_file.read_text())
+    result = await check_scenario(factories, scenario, {"scopeField": "organizationId"})
+    for err in result.errors:
+        print(f"[{err.phase}] {err.message} - {err.fix}")
+    assert result.valid
+```
+
+```bash
+# terminal
+pip install pytest pytest-asyncio "testcontainers[postgres]"
+pytest tests/test_validate_scenarios.py
+```
+
+There is no `check_all_scenarios` helper in the Python SDK - loop or `parametrize` over your scenario files yourself and call `check_scenario` once per file, as above.
+
+## The fix loop
+
+Validation is iterative, especially for LLM-generated data:
+
+1. Run `check_scenario`.
+2. If it fails, read `result.errors[i].message` (and the `fix` hint).
+3. Edit the scenario JSON and re-run.
+4. Repeat until `valid` is `True`.
+
+Common failures and fixes:
+
+| Message contains | Cause | Fix |
+|------------------|-------|-----|
+| `unique constraint ... slug` | Two records share a unique value | Make each unique field distinct across records (add `{{index}}` or `{{testRunId}}`). |
+| `references unknown alias(es)` | A `_ref` targets an alias no record declares | Add the target record with that `_alias`, or fix the name. |
+| `validation error` / `field required` | A required field is missing or the wrong type | Add the field; check it is declared on the factory's `input_model`. |
+| `no factory registered for model "X"` | Model in `create` has no factory | Register a factory for `X` and add it to the registry. |
+| `must return a record dict with "id"` | A factory's `create` returned no primary key | Return `{"id": ...}` (or a Pydantic instance with `id`). |

{autonoma_ai-0.2.8.dev1784101031 → autonoma_ai-0.2.9}/src/autonoma/errors.py

@@ -24,6 +24,7 @@ def unknown_action(action: str) -> AutonomaError:
 
 
 def production_blocked(detail: Optional[str] = None) -> AutonomaError:
+    """Deprecated - the SDK no longer gates on production; this is never raised."""
     return AutonomaError(
         "Environment factory is disabled"
         + ("" if detail is None else f". {detail}"),

{autonoma_ai-0.2.8.dev1784101031 → autonoma_ai-0.2.9}/src/autonoma/handler.py

@@ -22,7 +22,6 @@ from autonoma.errors import (
     invalid_body,
     invalid_refs_token,
     invalid_signature,
-    production_blocked,
     same_secrets,
     unknown_action,
 )
@@ -113,11 +112,6 @@ async def handle_request(config: HandlerConfig, req: HandlerRequest) -> HandlerR
         if config.shared_secret == config.signing_secret:
             raise same_secrets()
 
-        if not config.allow_production:
-            raise production_blocked(
-                "Set allow_production=True to enable the endpoint."
-            )
-
         signature: str = (
             req.headers.get("x-signature") or req.headers.get("X-Signature") or ""
         )

{autonoma_ai-0.2.8.dev1784101031 → autonoma_ai-0.2.9}/src/autonoma/types.py

@@ -19,6 +19,7 @@ The types in this module fall into two groups:
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass, field
 from typing import Any, Callable, Union
 
@@ -138,11 +139,22 @@ class HandlerConfig:
         Callable[[dict[str, Any] | None, AuthContext], Any],  # async callables
     ]
     factories: FactoryRegistry = field(default_factory=dict)
+    # Deprecated - ignored; the endpoint is always enabled and HMAC signing is
+    # the gate. On Autonoma previews (AUTONOMA_PREVIEWKIT set) no guard is
+    # needed; gate manually in your handler for your own production deployments.
     allow_production: bool = False
     sdk: dict[str, str] | None = None
     before_down: Callable[[HookContext], Any] | None = None
     after_up: Callable[[HookContext, dict[str, Any]], dict[str, Any]] | None = None
 
+    def __post_init__(self) -> None:
+        if self.allow_production:
+            warnings.warn(
+                "allow_production is deprecated and ignored - the endpoint is always enabled",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
 
 @dataclass
 class HandlerRequest: