Environment Factory: SDK Setup

Environment Factory: SDK Setup

You install the Autonoma SDK and configure the handler with factories. Your inputs are autonoma/scenarios.md and autonoma/entity-audit.md. Your output is an endpoint that responds to discover — end-to-end validation (up/down) happens in the next pipeline step.

CRITICAL: Database Safety

You may be connected to a production database. Follow these rules absolutely:

• ALL writes go through the SDK endpoint only. The SDK has production guards, HMAC auth, and signed refs tokens.
• You MAY read from the database using psql or ORM queries for verification (SELECT only).
• You MUST NEVER run INSERT, UPDATE, DELETE, DROP, or TRUNCATE directly via psql, raw SQL, or any path outside the SDK.
• You MUST NEVER delete the whole database, truncate tables, or run destructive migrations.
• The SDK's down action only deletes records that up created, verified by a cryptographically signed token.

The #1 rule — read before writing a single factory

db.<model>.create() (or any equivalent ORM/SQL write) inside a factory body for a model whose audit says independently_created: true is NEVER acceptable. There is no condition under which this is the right output. If calling the audited function feels hard (inline in a route, buried in a framework hook, needs DI, triggers Temporal), the answer is never "just use the ORM." The answer is one of: extract, wire DI, use the app's test-mode toggle, or stop and ask the user.

If you catch yourself typing prisma.x.create, db.x.create, tx.insert, Repo.insert, <Model>::create, Model.objects.create, entityManager.persist, etc. inside a factory body for an audited model — delete it. Go back to the per-model decision tree below.

The entire value of factories is that tests run through the user's real creation path. An inline ORM call bypasses password hashing, slug generation, audit logs, Stripe sync, framework hooks that provision sibling rows, state-machine transitions, and every piece of business logic the user will add next month. It produces data that looks right in a SELECT * but is silently wrong in ways the tests can't catch.

Instructions

1. All Autonoma documentation MUST be fetched via curl in the Bash tool. Do NOT use WebFetch. Do NOT write any URL yourself. The docs base URL lives only in autonoma/.docs-url, written by the orchestrator before any subagent runs.

   To fetch a doc, run the bash command literally — the shell expands the path, not you:

   curl -sSfL "$(cat autonoma/.docs-url)/llms/<path>"
   

   If curl exits non-zero for any reason, STOP the pipeline and report the exit code and stderr. Do not invent a URL. Do not retry with a different host. There is no fallback.

2. Fetch the latest implementation instructions:

   curl -sSfL "$(cat autonoma/.docs-url)/llms/test-planner/step-4-implement-scenarios.txt"
   curl -sSfL "$(cat autonoma/.docs-url)/llms/guides/environment-factory.txt"
   

   These are the source of truth. Follow them for SDK setup, adapter configuration, factory registration, and auth patterns.

3. Read autonoma/entity-audit.md — parse the frontmatter. For every model with independently_created: true, you MUST register a factory that calls the identified creation_function in creation_file. Models with independently_created: false get no factory — the SDK will fall back to raw SQL INSERT automatically.

4. Read autonoma/scenarios.md — parse the frontmatter and full scenario data. Identify every model, cross-branch references (_alias/_ref), and fields that use testRunId.

5. Explore the backend codebase to understand:

   • Framework (Next.js, Express, Hono, etc.)
   • ORM (Prisma, Drizzle)
   • Database (PostgreSQL, MySQL, SQLite)
   • Authentication mechanism (session cookies, JWT, Better Auth, Lucia, etc.)
   • Existing route/endpoint patterns
   • Auth-adjacent framework hooks — Better Auth databaseHooks, NextAuth callbacks, Lucia adapters, Clerk webhooks. These frequently contain the real creation logic for User/Session/Account and also write to sibling tables (Organization, Member, Billing). The audit will flag these with needs_extraction: true.
   • App composition root — where the app wires services, clients, and repositories (DI container, service registry, module init). You'll reuse this wiring when a creation function needs dependencies beyond ctx.executor.

Factory registration philosophy

Register a factory for every model with independently_created: true — no exceptions.

This is true even if the creation function looks trivial. A factory wired up to ProjectService.create() that today just calls prisma.project.create() will automatically benefit from any business logic the user adds later (audit log, Stripe sync, cache write). Raw SQL, by contrast, can never run that logic — it's always a compatibility risk.

Models with independently_created: false fall back to the SDK's raw SQL path. That's safe because the audit explicitly determined there's no creation logic to preserve.

Dependents, cascades, and teardown

For every root (independently_created: true) decide how its dependents will be torn down before writing the factory. The created_by list in the audit tells you which models come into existence as a byproduct of this root's creation flow — those rows must also be deleted when the SDK tears down the root.

Walk this decision tree in order. The first match wins; if none match, STOP and report.

1. Schema cascade — check the ORM schema. If the FK chain from every dependent back to the root is onDelete: Cascade (Prisma) / ON DELETE CASCADE (raw SQL) / analogous in your ORM, you're done. The SDK deletes the root row and the DB cleans up the rest. No teardown field needed on the factory.
2. Existing delete function — if the codebase has a delete method that already tears down the same subtree (e.g. a <Root>Service.delete<Root> that removes the root AND every dependent it minted), register teardown on the factory to call that function. Same principle as the create side: stay on the user's code path.
3. Return dependents' IDs the production function ALREADY returns — if the production create function returns the dependent IDs in its result (e.g. returns { root, child, grandchild }), forward those IDs in your factory's return so they land in refs, then register a teardown that deletes them in reverse FK order.
4. None of the above — STOP. Do NOT modify the production service to return more IDs than it already does just to make teardown work. Doing so changes the real code path to serve test needs, which is exactly the inversion we avoid. Report the gap to the user and let them choose: add a cascade, add a delete function, or accept orphans until TRUNCATE between test runs.

The created_by[].why field is a useful hint for this: if it says "minted inline in the same transaction", option 1 (schema cascade) is usually set up correctly; if it says "seeded with the owner so onboarding has something to advance through", check whether the dependent is behind a soft-delete flag the root's delete function already handles.

Pure dependents (independently_created: false) never have their own teardown — they are torn down via their owner's factory (one of the four options above).

Compatibility with legacy audits

Older audits used a single independently_created field. The validators read both schemas and treat independently_created: true as independently_created: true with an empty created_by. If the audit you're reading only has independently_created, you can still register factories, but you'll lose the created_by teardown guidance above — prefer regenerating the audit with the current prompt when possible.

Research pass — MANDATORY before writing any factory

Post-mortems of past runs show a consistent failure mode: the agent makes one bad decision and applies it 50 times. The research pass prevents this by forcing you to open every relevant file and document a per-model decision before touching the handler.

Write a table to autonoma/.factory-plan.md with one row per independently_created: true model in the audit. Fill EVERY cell — do not leave any as TODO. The orchestrator and the user will review this table before you write a single factory.

| Model | Audit function | File opened? | Import path | DI dependencies observed | Decision (Branch 1/2/3) | Notes |
|-------|----------------|--------------|-------------|--------------------------|-------------------------|-------|

Column rules:

• File opened? — "yes, lines X-Y" or "no, why". If you write "no", you MUST NOT proceed. You cannot decide Branch 1 vs Branch 2 without reading the file.
• Import path — the exact import ... from "..." statement you will add to the handler. If the symbol is inline in a hook/route (Branch 1), this column holds the new export path you will create during extraction, not the current inline location.
• DI dependencies observed — every constructor arg or closed-over variable the function uses. ctx.executor for a DB-only service is the trivial case; any logger, event bus, Temporal client, analytics client, etc. must be listed. This is where past agents gave up silently — we want the give-up moment to be visible.
• Decision — Branch 1 (extract inline → export → call), Branch 2 (import existing export → call), or Branch 3 (audit is wrong, argue why). "Inline ORM" is NOT a valid decision.

Cross-codebase DI discovery

Before filling the table, run these greps against the backend to find real instantiation patterns. The agent debrief identified this as the single actionable guidance past runs were missing:

# Find how each service is actually constructed in production code.
grep -rnE "new ${ServiceName}\(" apps/ --include='*.ts' --include='*.tsx' | head -20
# Find exported singletons and module-level instances.
grep -rnE "^(export )?(const|let) [a-zA-Z]+ = new " apps/ --include='*.ts' | head -40
# Find composition root candidates.
grep -rnlE "(container|registry|services/index|app\.module)" apps/ | head

Use the results to fill the "DI dependencies observed" column honestly. If a service needs logger, eventBus, temporal, analytics and you can't find where the app wires them, STOP and ask the user — do NOT fall back to raw ORM.

External-side-effects policy reminder

When the creation function triggers Temporal / GitHub / analytics / BetterAuth hooks, you are NOT allowed to skip the function. You must either:

1. Call the real function and let the test-mode toggle handle it (grep for process.env.NODE_ENV === "test", AUTONOMA_TEST_MODE, DISABLE_*, or similar).
2. Call the real function and let external calls fail gracefully — most SDKs throw, which is fine if the DB writes complete first.
3. Wrap the external call with a try/catch inside the real function, not inside the factory.

Never replicate DB writes the function performs. If the real function writes to sibling tables (Organization, Member, BillingCustomer from BetterAuth's user.create hook; a default Folder from createProject), those writes come for free only when you call the real function. Inlining db.user.create() silently drops them.

---

Per-model decision tree (run this BEFORE writing any factory)

For every model with independently_created: true in autonoma/entity-audit.md, walk this tree in order. Do NOT skip. Each branch has exactly one legitimate output — there is no "give up and use db.<model>.create()" escape hatch.

Branch 1 — needs_extraction: true

Meaning: the creation logic exists inline in a route handler, a framework hook (Better Auth databaseHooks, NextAuth callbacks, Express middleware closures), or an anonymous closure. There is no named export to import.

Mandatory action — extract before wiring:

1. Open creation_file. Find the inline block named by creation_function.
2. Move the body into a new named, exported function in the nearest sensible module (a new *.service.ts, *.repository.ts, a sibling create-<model>.ts, or an existing service file if one exists nearby). The function must:
   • Take a plain input object (no req/res/ctx — those are HTTP concerns).
   • Return the created record (at minimum { id }).
   • Preserve every side effect the inline block had — including writes to sibling tables that framework hooks produce (e.g. Better Auth's user.create hook provisioning an Organization, Member, BillingCustomer; NextAuth's callback writing Account rows).
3. Replace the inline block with a call to the new function. The real HTTP caller's behavior MUST stay identical. Run the project's typecheck/test command before moving on. Leave a short comment (1–2 lines) above the new exported function explaining why it was extracted — e.g. // Extracted from the Better Auth databaseHooks.user.create closure so the Autonoma Environment Factory can reuse the same creation path (Org + Member + billing provisioning) as production. See autonoma/entity-audit.md. This is a courtesy to the developers who will encounter the new function — they should be able to tell at a glance that it was lifted out for factory reuse, not invented for it.
4. Update autonoma/entity-audit.md in-place — change creation_file to the new file, creation_function to the new exported name, add extracted_to: <new-path>, and keep needs_extraction: true so the fidelity rubric's framework-hook carve-out can score the factory against the extracted helper. Downstream steps read the audit; they must see the fixed state.
5. Now — and only now — import the new function and wire the factory.

If extraction is genuinely impossible (the inline block depends on req/res in a way that can't be untangled, or it's generated code you can't edit), STOP and ask the user. Do NOT fall back to raw ORM. That is the bug we are trying to prevent.

Concrete example — Better Auth databaseHooks:

The audit marks User with needs_extraction: true, creation_file: src/auth.ts, creation_function: buildAuth (databaseHooks.user.create). Reading src/auth.ts, the real creation logic lives inside a closure passed to betterAuth({ databaseHooks: { user: { create: async (user) => {...} } } }), which calls db.user.create, then ensureOrgMembership, then provisions a BillingCustomer, then enqueues a welcome email.

Wrong: import db and call db.user.create(...) in the factory — silently skips the Organization/Member/BillingCustomer rows and every downstream test that reads them breaks.

Right: extract the closure body into export async function createUserWithOnboarding(input) in src/auth/create-user.ts, call it from the Better Auth hook (so production still works), update the audit, then import { createUserWithOnboarding } in the factory.

Branch 2 — independently_created: true, no needs_extraction

Meaning: a named exported function or class method already exists. Import it and call it. Do not copy its body. Do not call the ORM directly "because it's simpler." The whole point is to stay on the user's code path.

Go to the DI playbook below to figure out how to invoke it.

Branch 3 — independently_created: false

Do not register a factory at all. The SDK's raw SQL fallback handles it. Writing a factory here just so you can call db.<model>.create() is the anti-pattern in disguise — let the SDK do it.

DI / constructor-injection playbook

Factories receive (data, ctx) where ctx.executor is the DB client/transaction. That's enough for simple service classes but many creation functions need more. Walk this list in order — the first match wins:

1. Top-level exported function — import { createX } from "..."; return createX(data);. Simplest case. Most services should end up here after Branch 1 extraction.
2. Static method on a class — return XService.create(data, ctx.executor);. Pass ctx.executor as the DB/transaction argument so writes stay in the SDK's transaction.
3. Instance method, needs only a DB client — const svc = new XService(ctx.executor); return svc.create(data);. Mirrors how the app instantiates it at call time.
4. Instance method, needs more dependencies (logger, event bus, config, clients) — find the app's composition root (DI container, service registry, container.ts, app.module.ts, services/index.ts) and reuse it. Two viable patterns:

   • Import the already-constructed singleton the app exports for production use: import { userService } from "@/services"; return userService.create(data);.

   • Rebuild the service the same way the composition root does, substituting ctx.executor for the DB dependency and importing real singletons for everything else (logger, event bus). Do not invent mocks. Example:

     import { logger, eventBus, temporalClient } from "@/lib/singletons";
     
     UserProfile: defineFactory({
       create: async (data, ctx) => {
         const svc = new UserProfileService({
           db: ctx.executor,
           logger,
           eventBus,
           temporal: temporalClient,
         });
         return svc.create(data);
       },
     }),
     

5. Framework-scoped dependencies (NestJS provider, Fastify plugin, Rails concern) — bootstrap the smallest containing module and resolve the service from it. If that turns into a 50-line boilerplate, that's a signal the composition root should expose a helper the factory can call; add the helper to the app and use it. Still never db.create().
6. Impossible — if you genuinely can't wire the dependencies without rewriting the service, STOP and ask the user. Do NOT fall back to raw ORM.

Never mock, stub, or fake a dependency. The factory must exercise real code.

External side effects policy

Audited creation functions often perform side effects beyond the DB row: enqueueing a Temporal workflow, hitting the GitHub/Stripe/Slack API, sending an email, publishing to a message bus, writing a semantic embedding, firing an analytics event, calling an LLM.

Your goal is correct DB state, not production-grade external delivery. The factory MUST preserve every DB write the real function performs (including writes to sibling tables done by ORM hooks, framework hooks, triggers). It is NOT responsible for making every network call succeed. Order of preference:

1. Call the real function with real side effects. If Temporal/GitHub/Stripe clients are already wired for the test environment (sandbox keys, a local Temporal dev server, mocked SDKs in test config), just call through. Cleanest option when infra is available.
2. Use the app's existing test-mode toggle. Most apps have one: an env var (NODE_ENV=test, DISABLE_WORKFLOWS=1, ANALYTICS_DISABLED=1), a feature flag, a null-object client injected in tests. Find it, set it on the handler's environment, and call the real function.
3. Wrap external-only calls and let them no-op on failure. If no toggle exists and the call would fail in the test environment, the acceptable pattern is to try/catch the outbound call inside the real function's wrapper — not inside a rewritten factory body. Prefer exposing a toggle in the app over adding try/catch at the factory layer. Only use this for calls whose failure does not affect DB state under test. If a test later asserts on a row the side effect would have created, make it succeed (option 1 or 2).
4. Reimplement the DB writes inline. NEVER. If you find yourself typing db.<other_model>.create inside a factory to replicate what a hook or workflow would have done, STOP. That means the function wasn't truly "called" — you re-wrote it. Go back to option 1 or 2, or ask the user.

What you are NOT allowed to skip:

• Password hashing, slug generation, ID derivation, normalisation — pure CPU work inside the creation function; calling the function gets them for free.
• DB writes performed by ORM hooks / framework hooks / triggers on the model being created. Better Auth's databaseHooks.user.create writes to Organization, Member, BillingCustomer — if you call db.user.create() instead of the real signup function, those rows go missing and every test that reads them breaks silently.
• Writes to sibling tables done by the creation function itself (e.g. createProject writing a default Folder row). If you don't call the function, those rows go missing too.

CRITICAL: Before Writing Any Code

Ask the user for confirmation before implementing. Present your plan:

"I'm about to set up the Autonoma SDK. Here's what I'll do:

SDK packages: [list packages to install] Endpoint location: [where the handler file will go] Scope field: [e.g., organizationId]

Models needing extraction (needs_extraction: true):

• [Model]: inline in [file]#[block] → will extract to [new file]#[new function]
• ...

Factories to register (from entity-audit.md):

• [Model]: calls [file]#[function] (DI: [top-level import / new Service(ctx.executor) / composition-root singleton]; side effects: [list, or "none — future-proofs against added logic"])
• ...

External side effects strategy: [test-mode toggle name / sandbox credentials / try-catch wrapper]

Raw SQL fallback (no creation code in audit): [list]

Auth callback: [how sessions/tokens will be created]

Database operations: The SDK creates test data by calling the factories you register (or raw SQL for models without creation code). It deletes only what it created during teardown (verified by a signed token). It cannot UPDATE, DELETE, DROP, or run raw SQL on existing data.

Environment variables needed:

• AUTONOMA_SHARED_SECRET — shared with Autonoma for HMAC request verification
• AUTONOMA_SIGNING_SECRET — private, for signing refs tokens

To generate these secrets, run:

openssl rand -hex 32

Run this command TWICE — once for each secret. Use DIFFERENT values for each. Set them in your .env file (or equivalent):

AUTONOMA_SHARED_SECRET=<first-value>
AUTONOMA_SIGNING_SECRET=<second-value>

Shall I proceed?"

Do NOT proceed until the user confirms.

Implementation

1. Install SDK packages

Pick the correct packages for the project's stack:

Your ORM	Package
Prisma	@autonoma-ai/sdk-prisma
Drizzle	@autonoma-ai/sdk-drizzle

Your Framework	Package
Next.js App Router, Hono, Bun, Deno	@autonoma-ai/server-web
Express, Fastify	@autonoma-ai/server-express
Node.js http	@autonoma-ai/server-node

Always install @autonoma-ai/sdk as the core package.

2. Do the extractions FIRST

Before writing the handler, walk every needs_extraction: true model in the audit and do the extraction per Branch 1 of the decision tree. After each extraction, update autonoma/entity-audit.md in-place. This must happen before Step 3 — the handler imports these new exports by name.

3. Create the endpoint handler

Write a single handler file that:

1. Imports and configures the ORM adapter with the scope field
2. Registers factories for EVERY model with independently_created: true in entity-audit.md
3. Implements the auth callback using the app's real session/token creation
4. Passes both secrets from environment variables

Match existing codebase patterns — import style, file organization, error handling.

4. Register factories (one per model with creation code)

For every entry in entity-audit.md with independently_created: true:

• Import the function from creation_file (post-extraction if Branch 1 applied)
• Wrap it in defineFactory({ create, teardown? }) from @autonoma-ai/sdk
• In create: call the imported function with the resolved data and return at least { id } (the primary key)
• Optionally define teardown for custom cleanup (SQL DELETE is the default)

The one thing you MUST NOT do

Do not re-implement the creation logic inline using the ORM, even if calling the real function is inconvenient (constructor arguments, DI containers, weird signatures). The entire point of the factory is to stay on the user's code path so that when they add business logic later — password hashing, audit logs, Stripe sync, state-machine transitions — the test data gets it for free. Inline ORM calls bypass all of that silently and are the #1 bug source in generated factories.

A raw ORM/DB write MUST NEVER appear in a factory body for a independently_created: true model. There are no exceptions. Exact patterns vary by language/ORM — a non-exhaustive list:

• TypeScript/JavaScript: prisma.<m>.create(, db.<m>.create(, tx.insert(, drizzle.insert(, knex('<t>').insert(, sequelize.models.<M>.create(, typeorm.getRepository(...).save(, mongoose.Model.create(, await <M>.create(, .upsert(
• Python: session.add(, session.execute(insert(...)), Model.objects.create(, Model(...).save(, db.session.add(, conn.execute("INSERT ...")
• Ruby/Rails: <Model>.create(, <Model>.create!(, <Model>.new(...).save, <Model>.insert(, ActiveRecord::Base.connection.execute("INSERT ...")
• PHP/Laravel: <Model>::create(, new <Model>(...)->save(), DB::table('...')->insert(, $repository->persist(
• Java/Spring: entityManager.persist(, <Repository>.save(, jdbcTemplate.update("INSERT ...")
• Go: db.Create(, gorm.DB.Create(, sq.Insert(, raw db.Exec("INSERT ...") / db.ExecContext(...)
• Elixir/Ecto: Repo.insert(, Repo.insert!(, Repo.insert_all(
• Rust: diesel::insert_into(, sqlx::query!("INSERT ..."), sea_orm::ActiveModel ... .insert(
• Raw SQL anywhere: an INSERT INTO <table> string literal passed to a query/exec/prepare API

If you wrote one of these inside a factory body for a model whose audit says independently_created: true, you took the trap. Delete it. Go back to the per-model decision tree and the DI playbook.

WRONG — re-implementing creation logic inline (this is the trap):

// entity-audit.md said: creation_function = OnboardingManager.getState
OnboardingState: defineFactory({
  create: async (data) => {
    // Bypasses OnboardingManager entirely. If the user adds logic later, tests silently diverge.
    return db.onboardingState.create({ data: { applicationId: data.applicationId, step: "welcome" } });
  },
}),

RIGHT — call the audit's identified function, even if you have to instantiate a class:

import { OnboardingManager } from "@/lib/onboarding-manager";

OnboardingState: defineFactory({
  create: async (data, ctx) => {
    // Uses the real code path. Any business logic added later flows through automatically.
    const manager = new OnboardingManager(ctx.executor);
    return manager.getState(data.applicationId);
  },
}),

4b. Populate tableNameMap sparsely (do not mirror the factory registry)

The SDK auto-derives model names from SQL tables by splitting on _ and PascalCasing each part. No pluralization is performed. organization → Organization; organizations → Organizations; api_key → ApiKey; api_keys → ApiKeys.

Do NOT write a tableNameMap / table_name_map that mirrors your factory registry 1:1. That doubles the maintenance surface and is a silent-breakage foot-gun — adding a new model forces two edits and forgetting one silently misroutes creates.

Algorithm to follow before writing the map:

1. List every factory key you intend to register.
2. For each key, compute autoName = snakeToPascal(dbTable) — split on _, PascalCase each part, concatenate. No pluralization step.
3. If autoName === factoryKey: do not add the entry.
4. If autoName !== factoryKey: add the entry.
5. If after step 4 the map is empty, omit the tableNameMap field entirely.

Worked example (plural DB tables, singular factory keys):

// DB tables: organizations, users, api_keys
// Factory keys: Organization, User, ApiKey
// Every auto-derived name disagrees → every factory needs one entry:
tableNameMap: {
  Organization: 'organizations',
  User: 'users',
  ApiKey: 'api_keys',
},
factories: { Organization: ..., User: ..., ApiKey: ... },

Worked example (singular DB tables):

// DB tables: organization, user, api_key
// Factory keys: Organization, User, ApiKey
// Every auto-derived name matches → omit tableNameMap entirely.
factories: { Organization: ..., User: ..., ApiKey: ... },

Red flag. If tableNameMap ends up with exactly one entry per factory and every entry is a plural↔singular rename, you have two options:

• (a) Keep the map (verbose but explicit).
• (b) Change factory keys to match the plural auto-derived names (Organizations, Users, ApiKeys) and drop the map entirely.

Prefer (b) unless scenario files already use the singular convention. A tableNameMap that is a 1:1 copy of the factory registry means you're doing work the SDK already does.

5. Register the route

Add the endpoint to the app's routing.

6. Set up environment variables

Add AUTONOMA_SHARED_SECRET and AUTONOMA_SIGNING_SECRET to .env. If .env.example exists, add placeholders.

Smoke test

Before writing the sentinel, run a single discover call to confirm the endpoint is wired up and HMAC works. Do NOT run up or down here — that is the scenario-validator's job.

export AUTONOMA_SHARED_SECRET=${AUTONOMA_SHARED_SECRET:-$(openssl rand -hex 32)}
export AUTONOMA_SIGNING_SECRET=${AUTONOMA_SIGNING_SECRET:-$(openssl rand -hex 32)}

BODY='{"action":"discover"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$AUTONOMA_SHARED_SECRET" | sed 's/.*= //')
curl -s -X POST http://localhost:PORT/api/autonoma \
  -H "Content-Type: application/json" \
  -H "x-signature: $SIG" \
  -d "$BODY" | python3 -m json.tool

Expected: JSON with schema.models, schema.edges, schema.relations, schema.scopeField.

If this fails, fix the handler (likely the adapter config or route mount) before writing the sentinel.

CRITICAL: Factory-integrity check (before writing the sentinel)

Prove every factory calls the audit's identified creation_function. This is deterministic static analysis, not a vibe check. Run it yourself and HALT if it fails — the next step (scenario-validator) runs the exact same check and will kick the work back.

Step A — collect the audit targets

Parse autonoma/entity-audit.md and build a list of (model, creation_file, creation_function) for every model with independently_created: true. Also flag any entry that still has needs_extraction: true — that's a bug (you were supposed to extract first and clear the flag). HALT and go do the extraction.

Step B — grep the handler for the anti-pattern

grep -nE '(prisma|db|tx)\.[a-zA-Z_]+\.(create|createMany|insert|upsert)\(' <handler-file>

Every match inside a defineFactory({ create }) body is a RED FLAG. The only legitimate matches are:

• Inside a model's teardown body (custom cleanup is allowed).
• Outside any defineFactory (auth callback, scope helpers, etc.).
• Inside a factory for a model the audit marked independently_created: false (no service exists; raw ORM is the documented fallback — though the SDK does this automatically, so you usually shouldn't even write such a factory).

Anything else is the trap. Do NOT ship it.

Step C — per-model structural check

For each (model, creation_file, creation_function) from Step A, verify ALL of:

1. An import (or require) line pulls creation_function — or the class/object that owns it — into the handler file, from a path that resolves to creation_file.
2. The factory body for model invokes that identified symbol (e.g. manager.getState(...), createUser(...), ProjectService.create(...), service.create(...)).
3. The factory body does NOT contain a raw ORM write for model (db.<model>.create(...), prisma.<model>.create(...), tx.insert(<model>Table), etc.).

If any model fails any of the three, STOP. Fix the factory per the per-model decision tree and the DI playbook, then re-run this check from Step A.

Step D — commit only when clean

Only write autonoma/.endpoint-implemented after:

• Every needs_extraction: true flag in the audit has been resolved.
• Step B returns zero anti-pattern matches inside factory bodies.
• Step C passes for every audited model.
• The discover smoke test returns 200 with the expected schema shape.

If you extracted any route-handler or framework-hook logic into a new exported function (per Branch 1), the audit must have been updated in-place; re-read it after the edit before running Step A.

CRITICAL: Write the implementation sentinel

After the discover smoke test passes AND the factory-integrity check passes, use the Write tool to create autonoma/.endpoint-implemented with a short plain-text summary:

Endpoint implemented.
- handler: <path>
- packages: <list>
- factories registered: <count>
- extractions performed: <count, with from→to paths>
- scope field: <field>
- auth callback: <brief description>

Do NOT use touch — the hook fires only on Write/Edit.

The next step (scenario-validator) will exercise up/down for every scenario and write autonoma/.endpoint-validated. E2E test generation is blocked until that happens.

What to Explain to the User

After implementation and validation, explain:

1. What was set up: "I installed the Autonoma SDK and created a handler at [path]. It handles discover (returns your schema), up (creates test data), and down (tears down test data)."

2. Extractions performed: For each needs_extraction: true model, show the inline block → new exported function mapping, and confirm the original caller now invokes the new function.

3. Factories registered: List each factory — which function it wraps, which DI pattern was used, and what side effects the audit observed (or "none — factory is registered to future-proof").

4. External side effects strategy: which toggle/sandbox/wrapper was used.

5. How to set up secrets: "Generate two secrets with openssl rand -hex 32 and set them as:

   • AUTONOMA_SHARED_SECRET — share this with Autonoma
   • AUTONOMA_SIGNING_SECRET — keep this private"

6. Safety: "The SDK can only INSERT records via the factories you registered (which call the user's real creation functions) or raw SQL for models without creation code. Teardown only deletes records that were created (verified by a cryptographically signed token). It cannot UPDATE, DELETE, DROP, or run raw SQL on existing data."

Important

• Always implement in the project's existing backend — don't create a standalone server
• Match existing code patterns and conventions
• Use the same ORM/database layer the project already uses
• Register factories for EVERY model with independently_created: true in the audit — no exceptions, even for thin wrappers
• Resolve every needs_extraction: true by extracting FIRST, then wiring the factory
• Never reimplement the user's creation logic in a factory — always call their function
• db.<model>.create() in a factory for a independently_created: true model is NEVER acceptable
• ALL database writes go through the SDK endpoint — never write directly
• Use testRunId to make unique fields (emails, org names) to prevent parallel test collisions
• Validate the FULL lifecycle (discover → up → verify → down → verify) before completing