@nightowlsdev/storage-supabase 1.0.0 → 2.0.0

package/dist/index.cjs

@@ -25,13 +25,19 @@ __export(index_exports, {
   createMastraVectorStore: () => createMastraVectorStore,
   createPostgresFloor: () => createPostgresFloor,
   createSupabaseStorage: () => createSupabaseStorage,
+  ensureAgentVersion: () => ensureAgentVersion,
+  hostOwnedOrgMembershipSql: () => hostOwnedOrgMembershipSql,
+  hostOwnedOrgMigration: () => hostOwnedOrgMigration,
   listAgentVersions: () => listAgentVersions,
+  listTenants: () => listTenants,
   makeBundleRepo: () => makeBundleRepo,
   makeBundleWritableRepo: () => makeBundleWritableRepo,
+  makeThreadStore: () => makeThreadStore,
   makeVersionedRepo: () => makeVersionedRepo,
   nightOwlsPlugin: () => nightOwlsPlugin,
   publishAgentVersion: () => publishAgentVersion,
-  rollbackAgentVersion: () => rollbackAgentVersion
+  rollbackAgentVersion: () => rollbackAgentVersion,
+  supabaseUsageSink: () => supabaseUsageSink
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -308,6 +314,18 @@ function makeScratchpadStore(ctx) {
   };
 }
 
+// src/threads.ts
+function makeThreadStore(ctx) {
+  return {
+    async ensure({ id, orgId, userId, projectId }) {
+      await ctx.pool.query(
+        "insert into threads(id, org_id, user_id, project_id) values($1,$2,$3,$4) on conflict (id) do nothing",
+        [id, orgId, userId, projectId ?? null]
+      );
+    }
+  };
+}
+
 // src/agents.ts
 var import_core3 = require("@nightowlsdev/core");
 
@@ -468,6 +486,41 @@ async function publishAgentVersion(ctx, def) {
     client.release();
   }
 }
+async function ensureAgentVersion(ctx, def) {
+  const actor = def.actor ?? SEED_ACTOR;
+  (0, import_core3.assertActorMayMutateDefinition)(actor);
+  const client = await ctx.pool.connect();
+  try {
+    await client.query("begin");
+    await client.query("select pg_advisory_xact_lock(hashtext($1), hashtext($2))", ["ensure_agent", `${def.tenantId}:${def.slug}`]);
+    const head = (await client.query(
+      `select v.version from agents a join agent_versions v on v.id = a.current_version_id where a.org_id=$1 and a.slug=$2 and a.project_id is null`,
+      [def.tenantId, def.slug]
+    )).rows[0];
+    if (head) {
+      await client.query("commit");
+      return { version: head.version, created: false };
+    }
+    const agent = (await client.query(
+      `insert into agents(org_id, slug, is_orchestrator) values($1,$2,$3)
+       on conflict (org_id, project_id, slug) do update set slug=excluded.slug returning id`,
+      [def.tenantId, def.slug, def.role === "orchestrator"]
+    )).rows[0];
+    const version = await commitVersion(client, agent.id, def.tenantId, def, "publish", auditActor(actor), { slug: def.slug });
+    await client.query("commit");
+    await notifyInvalidate(client, def.tenantId, def.slug);
+    return { version, created: true };
+  } catch (e) {
+    await client.query("rollback");
+    throw e;
+  } finally {
+    client.release();
+  }
+}
+async function listTenants(ctx) {
+  const rows = await many(ctx.pool, "select id::text as id from orgs order by created_at asc");
+  return rows.map((r) => r.id);
+}
 async function listAgentVersions(ctx, tenantId, slug) {
   const rows = await many(
     ctx.pool,
@@ -633,6 +686,78 @@ function createMastraVectorStore(opts) {
   return new import_pg2.PgVector({ id: "nightowls-vector", connectionString: opts.dbUrl, schemaName: "nightowls" });
 }
 
+// src/usage-sink.ts
+var IDENT = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var TABLE = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
+function defaultMap(ev, ctx) {
+  const b = ev.data.breakdown;
+  return {
+    generation_id: ev.data.generationId,
+    run_id: ctx.runId,
+    org_id: ctx.tenantId,
+    agent_slug: ev.data.slug,
+    model_id: ev.data.modelId,
+    input_tokens: b.inputTokens ?? 0,
+    output_tokens: b.outputTokens ?? 0,
+    cost_usd: ev.data.cost.usd
+  };
+}
+function supabaseUsageSink(opts) {
+  const conflict = opts.conflictColumn ?? "generation_id";
+  if (!IDENT.test(conflict)) throw new Error(`supabaseUsageSink: unsafe conflictColumn ${JSON.stringify(conflict)}`);
+  if (!TABLE.test(opts.table)) throw new Error(`supabaseUsageSink: unsafe table ${JSON.stringify(opts.table)}`);
+  const map = opts.map ?? defaultMap;
+  return async (ev, ctx) => {
+    if (ev.type !== "swarm.usage") return;
+    const row = map(ev, ctx);
+    if (!row) return;
+    const cols = Object.keys(row);
+    for (const c of cols) if (!IDENT.test(c)) throw new Error(`supabaseUsageSink: unsafe column ${JSON.stringify(c)}`);
+    const placeholders = cols.map((_c, i) => `$${i + 1}`).join(",");
+    const sql = `insert into ${opts.table}(${cols.join(",")}) values(${placeholders}) on conflict (${conflict}) do nothing`;
+    await opts.pool.query(sql, cols.map((c) => row[c]));
+  };
+}
+
+// src/host-org-source.ts
+var QUALIFIED = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
+var PLAIN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertIdent(v, kind, re) {
+  if (!re.test(v)) throw new Error(`hostOwnedOrgMembership: unsafe ${kind} ${JSON.stringify(v)}`);
+}
+function hostOwnedOrgMembershipSql(opts) {
+  const schema = opts.schema ?? "nightowls";
+  const orgIdColumn = opts.orgIdColumn ?? "organization_id";
+  const userIdColumn = opts.userIdColumn ?? "user_id";
+  const userIdExpr = opts.userIdExpr ?? "(select auth.uid())";
+  assertIdent(schema, "schema", PLAIN);
+  assertIdent(opts.membershipTable, "membershipTable", QUALIFIED);
+  assertIdent(orgIdColumn, "orgIdColumn", PLAIN);
+  assertIdent(userIdColumn, "userIdColumn", PLAIN);
+  if (/;|--|\/\*|\$\$/.test(userIdExpr)) throw new Error(`hostOwnedOrgMembership: unsafe userIdExpr ${JSON.stringify(userIdExpr)}`);
+  return `-- FR-015 \u2014 override ${schema}.is_org_member to read the host membership table ${opts.membershipTable}.
+create or replace function ${schema}.is_org_member(p_org uuid)
+  returns boolean language sql stable set search_path = '' as $$
+  select exists (
+    select 1 from ${opts.membershipTable} m
+    where m.${orgIdColumn} = p_org and m.${userIdColumn} = ${userIdExpr}
+  );
+$$;
+-- The Realtime gate calls is_org_member as the AUTHENTICATED role during a private subscribe, so it must be able
+-- to read the membership table. (No-op if you already granted it.)
+grant select on ${opts.membershipTable} to authenticated;
+`;
+}
+function hostOwnedOrgMigration(opts) {
+  const version = opts.version ?? "host_org_source";
+  assertIdent(version, "version", PLAIN);
+  return {
+    version,
+    name: `host-owned org/membership source (is_org_member \u2192 ${opts.membershipTable})`,
+    sql: hostOwnedOrgMembershipSql(opts)
+  };
+}
+
 // src/migrations/0001_core.ts
 var M0001_CORE = {
   version: "0001_core",
@@ -2085,7 +2210,12 @@ function createSupabaseStorage(opts) {
     runs: makeRunStore(ctx),
     events: makeEventStore(ctx),
     messages: makeMessageStore(ctx),
+    // FR-009: the engine ensures this thread row at run start, so a host no longer hand-writes raw SQL against
+    // `nightowls.threads`, and `messages.append` cannot throw `unknown thread` through the supported path.
+    threads: makeThreadStore(ctx),
     scratchpad: makeScratchpadStore(ctx),
+    // FR-016: enumerate the engine's tenants for idempotent per-tenant crew backfill (pairs with ensureAgentVersion).
+    listTenants: () => listTenants(ctx),
     // Record the suspended run in the tenant-scoped followup index so `runs.findSuspended` (the resume
     // authz gate) can resolve it. RE-OPEN on conflict (reset `answered_at`): Mastra REUSES the same
     // `toolCallId` when an agent asks AGAIN after a resume, so the engine's `followupId = runId:toolCallId`
@@ -2155,11 +2285,17 @@ function createSupabaseStorage(opts) {
   createMastraVectorStore,
   createPostgresFloor,
   createSupabaseStorage,
+  ensureAgentVersion,
+  hostOwnedOrgMembershipSql,
+  hostOwnedOrgMigration,
   listAgentVersions,
+  listTenants,
   makeBundleRepo,
   makeBundleWritableRepo,
+  makeThreadStore,
   makeVersionedRepo,
   nightOwlsPlugin,
   publishAgentVersion,
-  rollbackAgentVersion
+  rollbackAgentVersion,
+  supabaseUsageSink
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AgentVersionContent, SwarmActor, AgentVersionInfo, VersionedRepo, BundleRepo, BundleWritableRepo, ContainerFloor, StorageAdapter } from '@nightowlsdev/core';
+import { AgentVersionContent, SwarmActor, AgentVersionInfo, VersionedRepo, ThreadStore, SwarmEvent, SwarmContext, BundleRepo, BundleWritableRepo, ContainerFloor, StorageAdapter } from '@nightowlsdev/core';
 export { AgentVersionInfo } from '@nightowlsdev/core';
 import { Pool } from 'pg';
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -56,6 +56,23 @@ type PublishAgentDef = AgentVersionContent & {
 declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<{
     version: number;
 }>;
+/**
+ * FR-016 — idempotently publish an agent version ONLY if the tenant has no head for that slug yet. The "seed a
+ * crew for tenant X if absent" primitive a host loops over `listTenants()` for backfill, so it never re-publishes
+ * (no version churn) on a tenant that already has the agent. Returns the head version + whether THIS call created
+ * it. (Use `publishAgentVersion` directly when you intentionally want a new version every time.)
+ *
+ * ATOMIC: the existence check + the publish run in ONE transaction under a per-(tenant,slug) advisory lock, so two
+ * concurrent backfill workers for the same slug can't both observe "absent" and each append a version — the second
+ * waiter sees v1 already present and returns `created:false`.
+ */
+declare function ensureAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<{
+    version: number;
+    created: boolean;
+}>;
+/** FR-016 — enumerate the engine's tenants (the `orgs` the engine knows), so a host can backfill each tenant's
+ *  crew without raw SQL against whatever host table happens to hold tenants. Ordered oldest→newest. */
+declare function listTenants(ctx: Ctx$1): Promise<string[]>;
 /** List an agent's versions (oldest→newest), flagging the current head. Tenant-scoped. Read-only — use it to
  *  pick a `toVersion` for `rollbackAgentVersion`. Returns [] for an unknown agent. */
 declare function listAgentVersions(ctx: Ctx$1, tenantId: string, slug: string): Promise<AgentVersionInfo[]>;
@@ -76,15 +93,51 @@ declare function rollbackAgentVersion(ctx: Ctx$1, args: {
     restoredFrom: number;
 }>;
 
-/** The READ-ONLY bundle repo (head/getVersion/listSlugs). The writable surface lives in `makeBundleWritableRepo`. */
-declare function makeBundleRepo(ctx: Ctx$1): BundleRepo;
 /**
- * The WRITABLE bundle definition repo (BN2) — the core `BundleWritableRepo` contract backed by Postgres. Extends
- * the read repo with the append-only `publish`/`rollback`/`listVersions` surface, on the SAME shared
- * `appendVersion` primitive as agents (so a bundle gets the same race-safe append-and-flip + audit + the
- * published-row immutability trigger). Every mutation enforces the non-bypassable agent-bar first.
+ * FR-009 — the supported, schema-private way to create the `threads` row a run FK-references. `runs.thread_id` is
+ * a NOT NULL FK to `threads(id)`, and `messages.append` throws `unknown thread` without it, so a host previously
+ * had to reach into the raw pool and hardcode the engine's private column names. `ensure` does an insert-or-ignore
+ * on the primary key, so it is safe to call before every run (the engine calls it at run start). `org_id` /
+ * `user_id` are NOT NULL in the schema; `project_id` is the optional host-owned sub-scope.
  */
-declare function makeBundleWritableRepo(ctx: Ctx$1): BundleWritableRepo;
+declare function makeThreadStore(ctx: Ctx$1): ThreadStore;
+
+/** A flat row to upsert: column name → value. Column names are HOST code (trusted), validated to a safe identifier. */
+type UsageRow = Record<string, string | number | boolean | null>;
+interface SupabaseUsageSinkOpts {
+    /** The pg pool to write through (e.g. `storage.ctx.pool`). */
+    pool: Pool;
+    /** Destination table (schema-qualified if needed, e.g. `"public.llm_usage_logs"`). */
+    table: string;
+    /**
+     * The column that carries the engine's per-generation `generationId`. The sink upserts `on conflict (<this>) do
+     * nothing`, so a re-delivered usage event (realtime replay, retry) inserts at most once. Must be UNIQUE/PK in
+     * the table. Default `"generation_id"`.
+     */
+    conflictColumn?: string;
+    /**
+     * Map ONE `swarm.usage` event → the row to insert. Defaults to a sensible shape
+     * (`generation_id`, `run_id`, `org_id`, `agent_slug`, `model_id`, `input_tokens`, `output_tokens`, `cost_usd`).
+     * Override to match your table. Return `null` to skip an event.
+     */
+    map?: (ev: Extract<SwarmEvent, {
+        type: "swarm.usage";
+    }>, ctx: SwarmContext) => UsageRow | null;
+}
+/**
+ * FR-004 — an `onEvent` handler that records each per-generation `swarm.usage` into a host Supabase table, keyed
+ * idempotently by the engine's stable `generationId` (no double-count under delegation, no OTel pipeline). Wire it
+ * onto `defineSwarm({ onEvent })` (compose with your own observer if you have one). Failures are the caller's to
+ * handle — the engine swallows a throwing `onEvent` so a sink hiccup never breaks a run, but you should log your own.
+ *
+ * NOTE: this records the engine's METERED (token-priced) cost — the framework never knows a provider's post-hoc
+ * BILLED amount. Use `generationId` to reconcile "actual" cost later if your provider exposes it (see FR-004).
+ *
+ * @example
+ *   const sink = supabaseUsageSink({ pool: storage.ctx.pool, table: "llm_usage_logs" });
+ *   defineSwarm({ ..., onEvent: sink });
+ */
+declare function supabaseUsageSink(opts: SupabaseUsageSinkOpts): (ev: SwarmEvent, ctx: SwarmContext) => Promise<void>;
 
 /** A single Night Owls migration: a stable `version`, a human `name`, and fully-qualified `nightowls.*` SQL.
  *  Night Owls contributes these to the host's `supabase/migrations/` (via `owl install`/`db eject`);
@@ -96,6 +149,37 @@ interface Migration {
 }
 declare const MIGRATIONS: Migration[];
 
+interface HostOrgSourceOpts {
+    /** The engine schema the override targets (the deployed name). Default `"nightowls"`. */
+    schema?: string;
+    /** The host membership table, schema-qualified, e.g. `"public.organization_members"`. */
+    membershipTable: string;
+    /** The org-id column on the membership table. Default `"organization_id"`. */
+    orgIdColumn?: string;
+    /** The user-id column on the membership table (compared to `userIdExpr`). Default `"user_id"`. */
+    userIdColumn?: string;
+    /** The SQL expression for the current user id (must match `userIdColumn`'s type). Default `(select auth.uid())`. */
+    userIdExpr?: string;
+    /** Migration version label. Default `"host_org_source"`. */
+    version?: string;
+}
+/** Generate the SQL that overrides `<schema>.is_org_member` to read the host's membership table (+ the GRANT the
+ *  Realtime gate needs to read it as the `authenticated` role during a private subscribe). */
+declare function hostOwnedOrgMembershipSql(opts: HostOrgSourceOpts): string;
+/** The same override packaged as a `Migration` so a host can append it to its migration set AFTER `0001_core`
+ *  (it `create or replace`s the function the core migration defined). */
+declare function hostOwnedOrgMigration(opts: HostOrgSourceOpts): Migration;
+
+/** The READ-ONLY bundle repo (head/getVersion/listSlugs). The writable surface lives in `makeBundleWritableRepo`. */
+declare function makeBundleRepo(ctx: Ctx$1): BundleRepo;
+/**
+ * The WRITABLE bundle definition repo (BN2) — the core `BundleWritableRepo` contract backed by Postgres. Extends
+ * the read repo with the append-only `publish`/`rollback`/`listVersions` surface, on the SAME shared
+ * `appendVersion` primitive as agents (so a bundle gets the same race-safe append-and-flip + audit + the
+ * published-row immutability trigger). Every mutation enforces the non-bypassable agent-bar first.
+ */
+declare function makeBundleWritableRepo(ctx: Ctx$1): BundleWritableRepo;
+
 /**
  * The Night Owls adapter plugin manifest. `@nightowlsdev/cli` discovers this from the host's installed
  * `@nightowlsdev/*` deps, dynamic-imports it, and acts on it declaratively:
@@ -181,4 +265,4 @@ interface SupabaseStorage extends StorageAdapter {
 }
 declare function createSupabaseStorage(opts: SupabaseStorageOpts): SupabaseStorage;
 
-export { type Ctx$1 as Ctx, MIGRATIONS, type Migration, type PostgresFloorOpts, type PublishAgentDef, type SupabaseStorage, type SupabaseStorageOpts, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, listAgentVersions, makeBundleRepo, makeBundleWritableRepo, makeVersionedRepo, nightOwlsPlugin, publishAgentVersion, rollbackAgentVersion };
+export { type Ctx$1 as Ctx, type HostOrgSourceOpts, MIGRATIONS, type Migration, type PostgresFloorOpts, type PublishAgentDef, type SupabaseStorage, type SupabaseStorageOpts, type SupabaseUsageSinkOpts, type UsageRow, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, ensureAgentVersion, hostOwnedOrgMembershipSql, hostOwnedOrgMigration, listAgentVersions, listTenants, makeBundleRepo, makeBundleWritableRepo, makeThreadStore, makeVersionedRepo, nightOwlsPlugin, publishAgentVersion, rollbackAgentVersion, supabaseUsageSink };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentVersionContent, SwarmActor, AgentVersionInfo, VersionedRepo, BundleRepo, BundleWritableRepo, ContainerFloor, StorageAdapter } from '@nightowlsdev/core';
+import { AgentVersionContent, SwarmActor, AgentVersionInfo, VersionedRepo, ThreadStore, SwarmEvent, SwarmContext, BundleRepo, BundleWritableRepo, ContainerFloor, StorageAdapter } from '@nightowlsdev/core';
 export { AgentVersionInfo } from '@nightowlsdev/core';
 import { Pool } from 'pg';
 import { SupabaseClient } from '@supabase/supabase-js';
@@ -56,6 +56,23 @@ type PublishAgentDef = AgentVersionContent & {
 declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<{
     version: number;
 }>;
+/**
+ * FR-016 — idempotently publish an agent version ONLY if the tenant has no head for that slug yet. The "seed a
+ * crew for tenant X if absent" primitive a host loops over `listTenants()` for backfill, so it never re-publishes
+ * (no version churn) on a tenant that already has the agent. Returns the head version + whether THIS call created
+ * it. (Use `publishAgentVersion` directly when you intentionally want a new version every time.)
+ *
+ * ATOMIC: the existence check + the publish run in ONE transaction under a per-(tenant,slug) advisory lock, so two
+ * concurrent backfill workers for the same slug can't both observe "absent" and each append a version — the second
+ * waiter sees v1 already present and returns `created:false`.
+ */
+declare function ensureAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<{
+    version: number;
+    created: boolean;
+}>;
+/** FR-016 — enumerate the engine's tenants (the `orgs` the engine knows), so a host can backfill each tenant's
+ *  crew without raw SQL against whatever host table happens to hold tenants. Ordered oldest→newest. */
+declare function listTenants(ctx: Ctx$1): Promise<string[]>;
 /** List an agent's versions (oldest→newest), flagging the current head. Tenant-scoped. Read-only — use it to
  *  pick a `toVersion` for `rollbackAgentVersion`. Returns [] for an unknown agent. */
 declare function listAgentVersions(ctx: Ctx$1, tenantId: string, slug: string): Promise<AgentVersionInfo[]>;
@@ -76,15 +93,51 @@ declare function rollbackAgentVersion(ctx: Ctx$1, args: {
     restoredFrom: number;
 }>;
 
-/** The READ-ONLY bundle repo (head/getVersion/listSlugs). The writable surface lives in `makeBundleWritableRepo`. */
-declare function makeBundleRepo(ctx: Ctx$1): BundleRepo;
 /**
- * The WRITABLE bundle definition repo (BN2) — the core `BundleWritableRepo` contract backed by Postgres. Extends
- * the read repo with the append-only `publish`/`rollback`/`listVersions` surface, on the SAME shared
- * `appendVersion` primitive as agents (so a bundle gets the same race-safe append-and-flip + audit + the
- * published-row immutability trigger). Every mutation enforces the non-bypassable agent-bar first.
+ * FR-009 — the supported, schema-private way to create the `threads` row a run FK-references. `runs.thread_id` is
+ * a NOT NULL FK to `threads(id)`, and `messages.append` throws `unknown thread` without it, so a host previously
+ * had to reach into the raw pool and hardcode the engine's private column names. `ensure` does an insert-or-ignore
+ * on the primary key, so it is safe to call before every run (the engine calls it at run start). `org_id` /
+ * `user_id` are NOT NULL in the schema; `project_id` is the optional host-owned sub-scope.
  */
-declare function makeBundleWritableRepo(ctx: Ctx$1): BundleWritableRepo;
+declare function makeThreadStore(ctx: Ctx$1): ThreadStore;
+
+/** A flat row to upsert: column name → value. Column names are HOST code (trusted), validated to a safe identifier. */
+type UsageRow = Record<string, string | number | boolean | null>;
+interface SupabaseUsageSinkOpts {
+    /** The pg pool to write through (e.g. `storage.ctx.pool`). */
+    pool: Pool;
+    /** Destination table (schema-qualified if needed, e.g. `"public.llm_usage_logs"`). */
+    table: string;
+    /**
+     * The column that carries the engine's per-generation `generationId`. The sink upserts `on conflict (<this>) do
+     * nothing`, so a re-delivered usage event (realtime replay, retry) inserts at most once. Must be UNIQUE/PK in
+     * the table. Default `"generation_id"`.
+     */
+    conflictColumn?: string;
+    /**
+     * Map ONE `swarm.usage` event → the row to insert. Defaults to a sensible shape
+     * (`generation_id`, `run_id`, `org_id`, `agent_slug`, `model_id`, `input_tokens`, `output_tokens`, `cost_usd`).
+     * Override to match your table. Return `null` to skip an event.
+     */
+    map?: (ev: Extract<SwarmEvent, {
+        type: "swarm.usage";
+    }>, ctx: SwarmContext) => UsageRow | null;
+}
+/**
+ * FR-004 — an `onEvent` handler that records each per-generation `swarm.usage` into a host Supabase table, keyed
+ * idempotently by the engine's stable `generationId` (no double-count under delegation, no OTel pipeline). Wire it
+ * onto `defineSwarm({ onEvent })` (compose with your own observer if you have one). Failures are the caller's to
+ * handle — the engine swallows a throwing `onEvent` so a sink hiccup never breaks a run, but you should log your own.
+ *
+ * NOTE: this records the engine's METERED (token-priced) cost — the framework never knows a provider's post-hoc
+ * BILLED amount. Use `generationId` to reconcile "actual" cost later if your provider exposes it (see FR-004).
+ *
+ * @example
+ *   const sink = supabaseUsageSink({ pool: storage.ctx.pool, table: "llm_usage_logs" });
+ *   defineSwarm({ ..., onEvent: sink });
+ */
+declare function supabaseUsageSink(opts: SupabaseUsageSinkOpts): (ev: SwarmEvent, ctx: SwarmContext) => Promise<void>;
 
 /** A single Night Owls migration: a stable `version`, a human `name`, and fully-qualified `nightowls.*` SQL.
  *  Night Owls contributes these to the host's `supabase/migrations/` (via `owl install`/`db eject`);
@@ -96,6 +149,37 @@ interface Migration {
 }
 declare const MIGRATIONS: Migration[];
 
+interface HostOrgSourceOpts {
+    /** The engine schema the override targets (the deployed name). Default `"nightowls"`. */
+    schema?: string;
+    /** The host membership table, schema-qualified, e.g. `"public.organization_members"`. */
+    membershipTable: string;
+    /** The org-id column on the membership table. Default `"organization_id"`. */
+    orgIdColumn?: string;
+    /** The user-id column on the membership table (compared to `userIdExpr`). Default `"user_id"`. */
+    userIdColumn?: string;
+    /** The SQL expression for the current user id (must match `userIdColumn`'s type). Default `(select auth.uid())`. */
+    userIdExpr?: string;
+    /** Migration version label. Default `"host_org_source"`. */
+    version?: string;
+}
+/** Generate the SQL that overrides `<schema>.is_org_member` to read the host's membership table (+ the GRANT the
+ *  Realtime gate needs to read it as the `authenticated` role during a private subscribe). */
+declare function hostOwnedOrgMembershipSql(opts: HostOrgSourceOpts): string;
+/** The same override packaged as a `Migration` so a host can append it to its migration set AFTER `0001_core`
+ *  (it `create or replace`s the function the core migration defined). */
+declare function hostOwnedOrgMigration(opts: HostOrgSourceOpts): Migration;
+
+/** The READ-ONLY bundle repo (head/getVersion/listSlugs). The writable surface lives in `makeBundleWritableRepo`. */
+declare function makeBundleRepo(ctx: Ctx$1): BundleRepo;
+/**
+ * The WRITABLE bundle definition repo (BN2) — the core `BundleWritableRepo` contract backed by Postgres. Extends
+ * the read repo with the append-only `publish`/`rollback`/`listVersions` surface, on the SAME shared
+ * `appendVersion` primitive as agents (so a bundle gets the same race-safe append-and-flip + audit + the
+ * published-row immutability trigger). Every mutation enforces the non-bypassable agent-bar first.
+ */
+declare function makeBundleWritableRepo(ctx: Ctx$1): BundleWritableRepo;
+
 /**
  * The Night Owls adapter plugin manifest. `@nightowlsdev/cli` discovers this from the host's installed
  * `@nightowlsdev/*` deps, dynamic-imports it, and acts on it declaratively:
@@ -181,4 +265,4 @@ interface SupabaseStorage extends StorageAdapter {
 }
 declare function createSupabaseStorage(opts: SupabaseStorageOpts): SupabaseStorage;
 
-export { type Ctx$1 as Ctx, MIGRATIONS, type Migration, type PostgresFloorOpts, type PublishAgentDef, type SupabaseStorage, type SupabaseStorageOpts, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, listAgentVersions, makeBundleRepo, makeBundleWritableRepo, makeVersionedRepo, nightOwlsPlugin, publishAgentVersion, rollbackAgentVersion };
+export { type Ctx$1 as Ctx, type HostOrgSourceOpts, MIGRATIONS, type Migration, type PostgresFloorOpts, type PublishAgentDef, type SupabaseStorage, type SupabaseStorageOpts, type SupabaseUsageSinkOpts, type UsageRow, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, ensureAgentVersion, hostOwnedOrgMembershipSql, hostOwnedOrgMigration, listAgentVersions, listTenants, makeBundleRepo, makeBundleWritableRepo, makeThreadStore, makeVersionedRepo, nightOwlsPlugin, publishAgentVersion, rollbackAgentVersion, supabaseUsageSink };

package/dist/index.js

@@ -271,6 +271,18 @@ function makeScratchpadStore(ctx) {
   };
 }
 
+// src/threads.ts
+function makeThreadStore(ctx) {
+  return {
+    async ensure({ id, orgId, userId, projectId }) {
+      await ctx.pool.query(
+        "insert into threads(id, org_id, user_id, project_id) values($1,$2,$3,$4) on conflict (id) do nothing",
+        [id, orgId, userId, projectId ?? null]
+      );
+    }
+  };
+}
+
 // src/agents.ts
 import { assertActorMayMutateDefinition } from "@nightowlsdev/core";
 
@@ -431,6 +443,41 @@ async function publishAgentVersion(ctx, def) {
     client.release();
   }
 }
+async function ensureAgentVersion(ctx, def) {
+  const actor = def.actor ?? SEED_ACTOR;
+  assertActorMayMutateDefinition(actor);
+  const client = await ctx.pool.connect();
+  try {
+    await client.query("begin");
+    await client.query("select pg_advisory_xact_lock(hashtext($1), hashtext($2))", ["ensure_agent", `${def.tenantId}:${def.slug}`]);
+    const head = (await client.query(
+      `select v.version from agents a join agent_versions v on v.id = a.current_version_id where a.org_id=$1 and a.slug=$2 and a.project_id is null`,
+      [def.tenantId, def.slug]
+    )).rows[0];
+    if (head) {
+      await client.query("commit");
+      return { version: head.version, created: false };
+    }
+    const agent = (await client.query(
+      `insert into agents(org_id, slug, is_orchestrator) values($1,$2,$3)
+       on conflict (org_id, project_id, slug) do update set slug=excluded.slug returning id`,
+      [def.tenantId, def.slug, def.role === "orchestrator"]
+    )).rows[0];
+    const version = await commitVersion(client, agent.id, def.tenantId, def, "publish", auditActor(actor), { slug: def.slug });
+    await client.query("commit");
+    await notifyInvalidate(client, def.tenantId, def.slug);
+    return { version, created: true };
+  } catch (e) {
+    await client.query("rollback");
+    throw e;
+  } finally {
+    client.release();
+  }
+}
+async function listTenants(ctx) {
+  const rows = await many(ctx.pool, "select id::text as id from orgs order by created_at asc");
+  return rows.map((r) => r.id);
+}
 async function listAgentVersions(ctx, tenantId, slug) {
   const rows = await many(
     ctx.pool,
@@ -596,6 +643,78 @@ function createMastraVectorStore(opts) {
   return new PgVector({ id: "nightowls-vector", connectionString: opts.dbUrl, schemaName: "nightowls" });
 }
 
+// src/usage-sink.ts
+var IDENT = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var TABLE = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
+function defaultMap(ev, ctx) {
+  const b = ev.data.breakdown;
+  return {
+    generation_id: ev.data.generationId,
+    run_id: ctx.runId,
+    org_id: ctx.tenantId,
+    agent_slug: ev.data.slug,
+    model_id: ev.data.modelId,
+    input_tokens: b.inputTokens ?? 0,
+    output_tokens: b.outputTokens ?? 0,
+    cost_usd: ev.data.cost.usd
+  };
+}
+function supabaseUsageSink(opts) {
+  const conflict = opts.conflictColumn ?? "generation_id";
+  if (!IDENT.test(conflict)) throw new Error(`supabaseUsageSink: unsafe conflictColumn ${JSON.stringify(conflict)}`);
+  if (!TABLE.test(opts.table)) throw new Error(`supabaseUsageSink: unsafe table ${JSON.stringify(opts.table)}`);
+  const map = opts.map ?? defaultMap;
+  return async (ev, ctx) => {
+    if (ev.type !== "swarm.usage") return;
+    const row = map(ev, ctx);
+    if (!row) return;
+    const cols = Object.keys(row);
+    for (const c of cols) if (!IDENT.test(c)) throw new Error(`supabaseUsageSink: unsafe column ${JSON.stringify(c)}`);
+    const placeholders = cols.map((_c, i) => `$${i + 1}`).join(",");
+    const sql = `insert into ${opts.table}(${cols.join(",")}) values(${placeholders}) on conflict (${conflict}) do nothing`;
+    await opts.pool.query(sql, cols.map((c) => row[c]));
+  };
+}
+
+// src/host-org-source.ts
+var QUALIFIED = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
+var PLAIN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+function assertIdent(v, kind, re) {
+  if (!re.test(v)) throw new Error(`hostOwnedOrgMembership: unsafe ${kind} ${JSON.stringify(v)}`);
+}
+function hostOwnedOrgMembershipSql(opts) {
+  const schema = opts.schema ?? "nightowls";
+  const orgIdColumn = opts.orgIdColumn ?? "organization_id";
+  const userIdColumn = opts.userIdColumn ?? "user_id";
+  const userIdExpr = opts.userIdExpr ?? "(select auth.uid())";
+  assertIdent(schema, "schema", PLAIN);
+  assertIdent(opts.membershipTable, "membershipTable", QUALIFIED);
+  assertIdent(orgIdColumn, "orgIdColumn", PLAIN);
+  assertIdent(userIdColumn, "userIdColumn", PLAIN);
+  if (/;|--|\/\*|\$\$/.test(userIdExpr)) throw new Error(`hostOwnedOrgMembership: unsafe userIdExpr ${JSON.stringify(userIdExpr)}`);
+  return `-- FR-015 \u2014 override ${schema}.is_org_member to read the host membership table ${opts.membershipTable}.
+create or replace function ${schema}.is_org_member(p_org uuid)
+  returns boolean language sql stable set search_path = '' as $$
+  select exists (
+    select 1 from ${opts.membershipTable} m
+    where m.${orgIdColumn} = p_org and m.${userIdColumn} = ${userIdExpr}
+  );
+$$;
+-- The Realtime gate calls is_org_member as the AUTHENTICATED role during a private subscribe, so it must be able
+-- to read the membership table. (No-op if you already granted it.)
+grant select on ${opts.membershipTable} to authenticated;
+`;
+}
+function hostOwnedOrgMigration(opts) {
+  const version = opts.version ?? "host_org_source";
+  assertIdent(version, "version", PLAIN);
+  return {
+    version,
+    name: `host-owned org/membership source (is_org_member \u2192 ${opts.membershipTable})`,
+    sql: hostOwnedOrgMembershipSql(opts)
+  };
+}
+
 // src/migrations/0001_core.ts
 var M0001_CORE = {
   version: "0001_core",
@@ -2048,7 +2167,12 @@ function createSupabaseStorage(opts) {
     runs: makeRunStore(ctx),
     events: makeEventStore(ctx),
     messages: makeMessageStore(ctx),
+    // FR-009: the engine ensures this thread row at run start, so a host no longer hand-writes raw SQL against
+    // `nightowls.threads`, and `messages.append` cannot throw `unknown thread` through the supported path.
+    threads: makeThreadStore(ctx),
     scratchpad: makeScratchpadStore(ctx),
+    // FR-016: enumerate the engine's tenants for idempotent per-tenant crew backfill (pairs with ensureAgentVersion).
+    listTenants: () => listTenants(ctx),
     // Record the suspended run in the tenant-scoped followup index so `runs.findSuspended` (the resume
     // authz gate) can resolve it. RE-OPEN on conflict (reset `answered_at`): Mastra REUSES the same
     // `toolCallId` when an agent asks AGAIN after a resume, so the engine's `followupId = runId:toolCallId`
@@ -2117,11 +2241,17 @@ export {
   createMastraVectorStore,
   createPostgresFloor,
   createSupabaseStorage,
+  ensureAgentVersion,
+  hostOwnedOrgMembershipSql,
+  hostOwnedOrgMigration,
   listAgentVersions,
+  listTenants,
   makeBundleRepo,
   makeBundleWritableRepo,
+  makeThreadStore,
   makeVersionedRepo,
   nightOwlsPlugin,
   publishAgentVersion,
-  rollbackAgentVersion
+  rollbackAgentVersion,
+  supabaseUsageSink
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nightowlsdev/storage-supabase",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -33,7 +33,7 @@
   "peerDependencies": {
     "@mastra/core": "^1.38.0",
     "@mastra/pg": "^1.12.0",
-    "@nightowlsdev/core": "0.4.0"
+    "@nightowlsdev/core": "0.5.0"
   },
   "devDependencies": {
     "@mastra/core": "^1.38.0",
@@ -46,9 +46,9 @@
     "typescript": "6.0.3",
     "vitest": "^3.2.0",
     "zod": "^4.0.0",
-    "@nightowlsdev/tsconfig": "0.0.0",
-    "@nightowlsdev/core": "0.4.0",
-    "@nightowlsdev/eslint-config": "0.0.0"
+    "@nightowlsdev/core": "0.5.0",
+    "@nightowlsdev/eslint-config": "0.0.0",
+    "@nightowlsdev/tsconfig": "0.0.0"
   },
   "scripts": {
     "build": "tsup",