Arcoders · Arcoders · Jul 5, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,7 +2,10 @@ name: CI
 
 on:
   push:
-    branches: [master, main]
+    # TEMP (WS-AI 1.0 branch review): run the full CI matrix on this feature
+    # branch so the whole suite is exercised on the branch before the single 1.0
+    # PR is opened. REVERT this extra branch entry before merging to master.
+    branches: [master, main, LASAGNA-020726/ws-ai-3-vector-store]
   pull_request:
     branches: [master, main]
 
@@ -706,7 +709,10 @@ jobs:
 
     services:
       postgres:
-        image: postgres:16-alpine
+        # pgvector image (drop-in superset of postgres:16) so the AI e2e that need
+        # the `vector` extension run here; the non-AI demo e2e are unaffected, and
+        # the AI e2e self-skip on any plain-postgres runner (WS-AI-8).
+        image: pgvector/pgvector:pg16
         env:
           POSTGRES_USER: app
           POSTGRES_PASSWORD: app

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -126,6 +126,7 @@ const sidebar = [
           { text: 'Metrics', link: '/guides/satellites/metrics' },
           { text: 'Reporting', link: '/guides/satellites/reporting' },
           { text: 'AI', link: '/guides/satellites/ai' },
+          { text: 'AI security', link: '/guides/satellites/ai-security' },
           { text: 'Quotas', link: '/guides/satellites/quotas' },
           { text: 'Billing', link: '/guides/satellites/billing' },
           { text: 'Backup', link: '/guides/satellites/backup' },

diff --git a/docs/guides/satellites/ai-security.md b/docs/guides/satellites/ai-security.md
diff --git a/docs/guides/satellites/ai.md b/docs/guides/satellites/ai.md
diff --git a/docs/guides/satellites/index.md b/docs/guides/satellites/index.md
@@ -60,14 +60,16 @@ To build your own, see [Creating a satellite](/guides/cookbook/creating-a-satell
 
 <Callout type="note" title="Also documented in this section">
 [Backup](/guides/satellites/backup), [Admin](/guides/satellites/admin),
-[Reporting](/guides/satellites/reporting) and [AI](/guides/satellites/ai) appear in
+[Reporting](/guides/satellites/reporting), [AI](/guides/satellites/ai) and
+[AI security](/guides/satellites/ai-security) appear in
 this section's sidebar but aren't tenant-attached feature satellites like the ten
 above. Backup is an operational concern (`pg_dump` with retention tiers, shipped as
 `@adonisjs-lasagna/backup`); Admin is the shared REST surface the satellites expose,
 not a feature of its own; Reporting is the cross-tenant analytics layer that
 aggregates what the metrics pipeline writes into the backoffice schema; AI is the
 multi-provider streaming spine (`@adonisjs-lasagna/ai`) and ships no tenant table in
-this release. They live here because that's where you'll look for them.
+this release; AI security is that satellite's consolidated threat model and hardening
+checklist. They live here because that's where you'll look for them.
 </Callout>
 
 ## Cross-satellite invariants

diff --git a/docs/guides/security.md b/docs/guides/security.md
@@ -105,6 +105,7 @@ guarantee table above is a good reference). We will acknowledge within
 ## Related
 
 - [Compliance (SOC2 & GDPR)](/guides/compliance); how these guarantees map to SOC2/GDPR/ISO/HIPAA controls, plus audit export, anonymization, and the posture report.
+- [AI security & threat model](/guides/satellites/ai-security); the AI satellite's 18 threat vectors, invariants, fail-closed postures, and hardening checklist.
 - [Concepts](/start/concepts); connection routing, schema model, the boundary the guarantees sit on.
 - [Audit logs](/guides/satellites/audit); append-only enforcement details.
 - [Quotas](/guides/satellites/quotas); atomic enforcement details.

diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -87,15 +87,22 @@ For hosts using the vector store (embeddings), the PostgreSQL `vector`
 extension must exist before any migration declares a `vector(N)` column.
 `CREATE EXTENSION` needs a privileged role, so it runs under a separate
 provisioning connection (`isolation.provisionConnectionName`), never the app's
-request-serving role.
+request-serving role. The extension is installed into a dedicated `extensions`
+schema, which `schema-pg` tenant connections append to their `search_path` after
+the tenant's own schema — so a bare `vector(N)` column and its operators resolve
+while `public` (which holds central-connection data) stays off the tenant path,
+keeping physical tenant isolation (I1) intact. A hand-rolled tenant model that
+registers its own connection must append that schema too (see the demo's
+`app/models/backoffice/tenant.ts`).
 
 | Command | What it does |
 |---|---|
-| `tenant:vector:provision` | Install the pgvector extension idempotently under the privileged provisioning connection. Dispatched by driver: once on the shared database for `schema-pg`/`rowscope-pg`, per tenant database for `database-pg` (honouring `--tenant`). Run it before any embeddings migration; it doubles as the backfill for existing databases. `--dry-run` previews. |
+| `tenant:vector:provision` | Install the pgvector extension idempotently, into the dedicated `extensions` schema, under the privileged provisioning connection. Dispatched by driver: once on the shared database for `schema-pg`/`rowscope-pg`, per tenant database for `database-pg` (honouring `--tenant`). Run it before any embeddings migration; it doubles as the backfill for existing databases. `--dry-run` previews. |
 
 The opt-in `pgvector_extension` doctor check verifies the app role is not a
-superuser and that the extension is present where embeddings live. Register it
-with `doctorService.register(pgvectorExtensionCheck)`, then it runs under
+superuser and that the extension is present in the `extensions` schema where
+embeddings resolve it. Register it with
+`doctorService.register(pgvectorExtensionCheck)`, then it runs under
 `tenant:doctor --check=pgvector_extension`.
 
 The requirement is **ordering, not locking**: provision before you migrate a
@@ -193,6 +200,16 @@ Available when `--with=reporting` is configured. Full reference in the
 |---|---|
 | `tenant:report:generate` | Generate and print a cross-tenant usage report. Flags: `--period=day\|week\|month`, `--since=<iso>`, `--until=<iso>`, `--top=<n>`, `--format=table\|json\|csv`, `--out=<file>`, `--extension=<name>` (run a registered report extension instead of the built-in). |
 
+## AI
+
+Available when `--with=ai` is configured. Full reference in the
+[AI satellite](/guides/satellites/ai#audit).
+
+| Command | What it does |
+|---|---|
+| `tenant:ai:audit:verify` | Re-walk the append-only AI audit hash chain and report the first tamper (a broken checksum, a `seq` gap, or a broken prev-link) that got past the DB triggers. Exit 1 on the first break, so it gates a cron or a post-incident check. Flags: `--tenant=<id>` (omit for all), `--json`. |
+| `tenant:ai:purge` | Erase a tenant's AI data for GDPR: conversation memory, the response-cache epoch, and embeddings. Scopes: `--tenant=<uuid> --force` (all), `--tenant=<uuid> --principal=<id>` (one user, Art.17), `--tenant=<uuid> --source=<key>` (one document). `--dry-run` previews the counts and writes nothing; `--verify-chain` also re-walks the audit chain; `--actor=<id>` sets the audited operator. The immutable, non-PII audit chain intentionally survives. |
+
 ## REPL
 
 ```bash

diff --git a/examples/api/adonisrc.ts b/examples/api/adonisrc.ts
@@ -9,6 +9,7 @@ export default defineConfig({
     () => import('@adonisjs-lasagna/backup/commands'),
     () => import('@adonisjs-lasagna/billing/commands'),
     () => import('@adonisjs-lasagna/reporting/commands'),
+    () => import('@adonisjs-lasagna/ai/commands'),
   ],
 
   providers: [
@@ -28,6 +29,7 @@ export default defineConfig({
     () => import('@adonisjs-lasagna/billing/provider'),
     () => import('@adonisjs-lasagna/websockets/provider'),
     () => import('@adonisjs-lasagna/reporting/provider'),
+    () => import('@adonisjs-lasagna/ai/provider'),
     () => import('#app/providers/app_provider'),
   ],
 

diff --git a/examples/api/app/models/backoffice/tenant.ts b/examples/api/app/models/backoffice/tenant.ts
@@ -1,5 +1,8 @@
 import { BackofficeBaseModel } from '@adonisjs-lasagna/saas-tenancy/base-models'
-import { ReadReplicaService } from '@adonisjs-lasagna/saas-tenancy/services'
+import {
+  ReadReplicaService,
+  PGVECTOR_EXTENSION_SCHEMA,
+} from '@adonisjs-lasagna/saas-tenancy/services'
 import { column, scope } from '@adonisjs/lucid/orm'
 import db from '@adonisjs/lucid/services/db'
 import app from '@adonisjs/core/services/app'
@@ -153,7 +156,11 @@ export default class Tenant extends BackofficeBaseModel {
 
     db.manager.add(this.connectionName, {
       ...config,
-      searchPath: [this.schemaName],
+      // The tenant schema stays FIRST (all tenant objects resolve there); the shared
+      // pgvector `extensions` schema is appended so the `ai_embeddings vector(N)`
+      // column + operators resolve, exactly like core's SchemaPgDriver. `public`
+      // (central data) is deliberately kept off the tenant path.
+      searchPath: [this.schemaName, PGVECTOR_EXTENSION_SCHEMA],
     } as PostgreConfig)
 
     connectionLru.set(this.connectionName, Date.now())

diff --git a/examples/api/app/providers/app_provider.ts b/examples/api/app/providers/app_provider.ts
@@ -15,6 +15,8 @@ import {
 } from '@adonisjs-lasagna/reporting'
 import type { ReportExtensionFilters } from '@adonisjs-lasagna/reporting'
 import { adminActionRegistry, ADMIN_CONTRACT_VERSION } from '@adonisjs-lasagna/admin'
+import { AIProviderRegistry, EmbeddingProviderRegistry } from '@adonisjs-lasagna/ai'
+import { MockAIProvider, MockEmbeddingProvider } from '@adonisjs-lasagna/ai/testing'
 import TenantRepository from '#app/repositories/tenant_repository'
 
 export default class AppProvider {
@@ -24,6 +26,37 @@ export default class AppProvider {
     this.bindContainerServices()
     await this.registerReportExtensions()
     this.registerAdminActions()
+    await this.registerAiMockProviders()
+  }
+
+  /**
+   * Register the offline mock AI providers so the demo (and the AI e2e suite) run
+   * with no network. `AiProvider.register()` runs before this provider's `boot()`
+   * (it is listed earlier in adonisrc), so both registries are bound and makeable
+   * here. The chat mock activates as the `mock` provider named in `config.ai`; the
+   * embedding mock overrides the configured default via the WS-AI-8 registry so
+   * `/ai/embed` and `/ai/retrieve` never dial a real embeddings endpoint.
+   */
+  private async registerAiMockProviders() {
+    const chat = await this.app.container.make(AIProviderRegistry)
+    if (!chat.has('mock'))
+      chat.register(
+        // Emit a fake PII token in the streamed output so the demo
+        // `config.ai.redactOutput` DLP hook has something to strip end to end
+        // (proven by the ai_output_redaction e2e). Normal prose is preserved; only
+        // the SSN-shaped token is redacted.
+        new MockAIProvider({
+          name: 'mock',
+          fragments: [
+            { data: 'The record is ', tokens: 1 },
+            { data: 'SSN-000-00-0000', tokens: 1 },
+          ],
+        }),
+        { activate: true }
+      )
+
+    const embedding = await this.app.container.make(EmbeddingProviderRegistry)
+    if (!embedding.has()) embedding.register(new MockEmbeddingProvider({ dimension: 8 }))
   }
 
   /**

diff --git a/examples/api/config/multitenancy.ts b/examples/api/config/multitenancy.ts
@@ -216,4 +216,37 @@ export default {
     rollups: { enabled: true },
     cache: { invalidateOnFlush: true },
   },
+
+  // ─── AI satellite (@adonisjs-lasagna/ai) ─────────────────────────
+  // Fully offline in the demo: AppProvider registers a MockAIProvider (chat) and a
+  // MockEmbeddingProvider (embed/retrieve) so the AI e2e run with no network. The
+  // `dimension: 8` here is baked into the per-tenant `ai_embeddings vector(8)` column
+  // by the satellite migration and matches the mock's vectors. `retrievalFilter`
+  // returns the tenant-wide scope (isolation stays structural, per-tenant schema);
+  // `authorizeAIAccess` is open for the demo; `resolvePrincipal` reads `x-ai-user`.
+  // The AI routes are mounted under TenantGuard in start/routes.ts. `baseUrl` is an
+  // unreachable https placeholder: the mock override means it is never dialed. The
+  // AI e2e self-skip unless Postgres has the pgvector extension.
+  ai: {
+    allowedProviders: ['mock'],
+    defaultProvider: 'mock',
+    authorizeAIAccess: () => true,
+    resolvePrincipal: (ctx: any) => ctx.request.header('x-ai-user') ?? null,
+    rateLimit: { limit: 5, windowSeconds: 60 },
+    audit: { enabled: true },
+    embedding: {
+      provider: 'mock-embedding',
+      apiKey: 'demo-embeddings-key',
+      baseUrl: 'https://embeddings.invalid',
+      dimension: 8,
+      authorizeIngestion: () => true,
+    },
+    retrieval: { retrievalFilter: () => ({ kind: 'all' as const }) },
+    // A demo output-redaction (DLP) hook: strip anything shaped like an SSN from
+    // the model's streamed output. Host-owned defense-in-depth, NEVER the isolation
+    // control (I4/I8 remain the guarantee); the mandatory output bound still runs.
+    // Proven end to end by the ai_output_redaction e2e.
+    redactOutput: (_ctx: any, _tenant: any, chunk: string) =>
+      chunk.replace(/SSN-\d{3}-\d{2}-\d{4}/g, '[redacted]'),
+  },
 } as const
diff --git a/examples/api/database/migrations/backoffice/0018_create_ai_audit_logs_table.ts b/examples/api/database/migrations/backoffice/0018_create_ai_audit_logs_table.ts
@@ -0,0 +1,103 @@
+import { BaseSchema } from '@adonisjs/lucid/schema'
+
+/**
+ * The dedicated AI audit table (WS-AI-7). The demo enables `config.ai.audit`, so
+ * the AI gateway writes a non-PII, append-only, hash-chained row per chat /
+ * embedding / retrieval action; `/ai/embed` and `/ai/retrieve` fail CLOSED when
+ * this write cannot land, so the table must exist. This mirrors the satellite's
+ * `create_ai_audit_logs_table.stub` (the source of truth) that `configure` copies
+ * into a host app; the demo carries it as a real backoffice migration so the AI
+ * e2e run against a provisioned audit chain.
+ */
+export default class extends BaseSchema {
+  protected tableName = 'ai_audit_logs'
+
+  async up() {
+    this.schema.withSchema('backoffice').createTable(this.tableName, (table) => {
+      table.uuid('id').primary().defaultTo(this.db.rawQuery('gen_random_uuid()').knexQuery)
+      table.uuid('tenant_id').notNullable()
+
+      // Per-tenant monotonic sequence + hash chain. `checksum` is computed in the
+      // writer as sha256(canonical(row, seq) + '\n' + prev_checksum), so a
+      // deletion, reorder, or in-place rewrite that slips past the triggers breaks
+      // the chain and `tenant:ai:audit:verify` reports it. `UNIQUE(tenant_id, seq)`
+      // backs the advisory-locked writer.
+      table.bigInteger('seq').notNullable()
+      table.specificType('checksum', 'char(64)').notNullable()
+      table.specificType('prev_checksum', 'char(64)').nullable()
+
+      // Non-PII attribution only (I5): principal and source are one-way SHA-256
+      // hashes; no prompt, response, query, or document text is ever stored. `op`
+      // discriminates the three choke points (chat / embedding / retrieval) whose
+      // frozen events map onto this shared row.
+      table.string('op').notNullable()
+      table.string('outcome').notNullable()
+      table.string('reason').nullable()
+      table.specificType('principal_hash', 'char(64)').nullable()
+      table.specificType('source_hash', 'char(64)').nullable()
+      table.string('provider').nullable()
+      table.string('model').nullable()
+      table.integer('tokens').notNullable().defaultTo(0)
+      table.integer('fragments').notNullable().defaultTo(0)
+      table.integer('embeddings_count').notNullable().defaultTo(0)
+      table.integer('dimension').notNullable().defaultTo(0)
+      table.integer('match_count').notNullable().defaultTo(0)
+      table.boolean('idempotent_replay').notNullable().defaultTo(false)
+
+      table.timestamp('occurred_at', { useTz: true }).notNullable()
+      table.timestamp('created_at', { useTz: true }).notNullable().defaultTo(this.now())
+
+      table.unique(['tenant_id', 'seq'], 'ai_audit_logs_tenant_seq_uq')
+      table.index(['tenant_id', 'created_at'], 'ai_audit_logs_tenant_created_idx')
+    })
+
+    // Append-only, enforced at the database level so a compromised tenant role or a
+    // buggy controller cannot rewrite or erase evidence. The triggers fire on every
+    // UPDATE/DELETE regardless of role; TRUNCATE needs its own statement-level guard.
+    this.defer(async (db) => {
+      await db.rawQuery(`
+        CREATE OR REPLACE FUNCTION backoffice.ai_audit_logs_no_mutate()
+        RETURNS TRIGGER AS $$
+        BEGIN
+          RAISE EXCEPTION 'ai_audit_logs is append-only; UPDATE/DELETE is forbidden'
+            USING ERRCODE = 'insufficient_privilege';
+        END;
+        $$ LANGUAGE plpgsql;
+      `)
+      await db.rawQuery(`
+        DROP TRIGGER IF EXISTS ai_audit_logs_no_update ON backoffice.ai_audit_logs;
+        CREATE TRIGGER ai_audit_logs_no_update
+        BEFORE UPDATE ON backoffice.ai_audit_logs
+        FOR EACH ROW EXECUTE FUNCTION backoffice.ai_audit_logs_no_mutate();
+      `)
+      await db.rawQuery(`
+        DROP TRIGGER IF EXISTS ai_audit_logs_no_delete ON backoffice.ai_audit_logs;
+        CREATE TRIGGER ai_audit_logs_no_delete
+        BEFORE DELETE ON backoffice.ai_audit_logs
+        FOR EACH ROW EXECUTE FUNCTION backoffice.ai_audit_logs_no_mutate();
+      `)
+      await db.rawQuery(`
+        DROP TRIGGER IF EXISTS ai_audit_logs_no_truncate ON backoffice.ai_audit_logs;
+        CREATE TRIGGER ai_audit_logs_no_truncate
+        BEFORE TRUNCATE ON backoffice.ai_audit_logs
+        FOR EACH STATEMENT EXECUTE FUNCTION backoffice.ai_audit_logs_no_mutate();
+      `)
+    })
+  }
+
+  async down() {
+    this.defer(async (db) => {
+      await db.rawQuery(
+        'DROP TRIGGER IF EXISTS ai_audit_logs_no_update ON backoffice.ai_audit_logs'
+      )
+      await db.rawQuery(
+        'DROP TRIGGER IF EXISTS ai_audit_logs_no_delete ON backoffice.ai_audit_logs'
+      )
+      await db.rawQuery(
+        'DROP TRIGGER IF EXISTS ai_audit_logs_no_truncate ON backoffice.ai_audit_logs'
+      )
+      await db.rawQuery('DROP FUNCTION IF EXISTS backoffice.ai_audit_logs_no_mutate()')
+    })
+    this.schema.withSchema('backoffice').dropTable(this.tableName)
+  }
+}
diff --git a/examples/api/package.json b/examples/api/package.json
@@ -27,6 +27,7 @@
   "dependencies": {
     "@adonisjs-lasagna/saas-tenancy": "*",
     "@adonisjs-lasagna/admin": "*",
+    "@adonisjs-lasagna/ai": "*",
     "@adonisjs-lasagna/billing": "*",
     "@adonisjs-lasagna/sso": "*",
     "@adonisjs-lasagna/backup": "*",

diff --git a/examples/api/start/routes.ts b/examples/api/start/routes.ts
@@ -5,6 +5,7 @@ import { multitenancyRoutes } from '@adonisjs-lasagna/saas-tenancy/health'
 import { multitenancyAdminRoutes } from '@adonisjs-lasagna/admin'
 import { multitenancyBillingRoutes } from '@adonisjs-lasagna/billing'
 import { multitenancyReportingRoutes } from '@adonisjs-lasagna/reporting'
+import { multitenancyAiRoutes } from '@adonisjs-lasagna/ai/routes'
 
 /**
  * Lazy controller imports — keeps the route file small and lets the
@@ -59,6 +60,12 @@ multitenancyReportingRoutes({
   cacheTtlMs: 60_000,
 })
 
+/* ─── AI gateway (@adonisjs-lasagna/ai) — tenant-scoped, fail-closed mount ── */
+// POST /ai/chat (SSE), /ai/embed, /ai/retrieve. TenantGuard FIRST per the mount
+// contract; config.ai.authorizeAIAccess is the per-request membership gate. The
+// demo runs fully offline through the mock providers registered in AppProvider.
+multitenancyAiRoutes({ middleware: [middleware.tenantGuard()] })
+
 /* ─── Impersonation verify probe ─────────────────────────────────────────── */
 // Echoes the verified impersonation context attached by ImpersonationMiddleware,
 // so a request carrying a token minted via the admin API can prove it resolves