@nightowlsdev/storage-supabase 0.3.0 → 2.0.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-import { AgentVersion, 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';
 import { PostgresStore, PgVector } from '@mastra/pg';
@@ -30,23 +31,48 @@ declare function createMastraVectorStore(opts: {
     dbUrl: string;
 }): PgVector;
 
-/** The shape callers pass — `version` is derived, not supplied. */
-type PublishAgentDef = Omit<AgentVersion, "version"> & {
+/**
+ * The WRITABLE agent definition repo (SP6) — the core `VersionedRepo` contract backed by Postgres. Extends the
+ * read-only repo with the append-only `publish`/`rollback`/`listVersions` surface. The supabase adapter wires
+ * its `agents` field to this (a `VersionedRepo` IS an `AgentRepo`) and also surfaces it as `agentsWritable`.
+ *
+ * SECURITY: every mutation calls `assertActorMayMutateDefinition(actor)` FIRST (inside the standalone
+ * functions) — the non-bypassable agent-bar. The removable `guardDefinitionMutation` POLICY hook is layered on
+ * by the caller that owns a `HookDispatcher` (the no-code builder); the storage layer only enforces the
+ * framework invariant, which no hook can weaken.
+ */
+declare function makeVersionedRepo(ctx: Ctx$1): VersionedRepo;
+/** The shape callers pass — `version` is derived, not supplied. `actor` is the typed `SwarmActor` principal
+ *  (the agent-bar inspects it); omit it ⇒ the seed system actor. */
+type PublishAgentDef = AgentVersionContent & {
     tenantId: string;
-    actor?: string;
+    actor?: SwarmActor;
     version?: number;
 };
-/** Insert a new agent version, flip the head pointer, audit. Used by seeding/CLI (not in the core interface).
- *  Takes the typed `Ctx` directly (no `__ctx` any-cast); call via `publishAgentVersion(storage.ctx, def)`. */
-declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<void>;
-/** One row of an agent's version history (for rollback UX). */
-interface AgentVersionInfo {
+/** Insert a new agent version, flip the head pointer, audit. Used by seeding/CLI (and `makeVersionedRepo`).
+ *  Takes the typed `Ctx` directly (no `__ctx` any-cast); call via `publishAgentVersion(storage.ctx, def)`.
+ *  Enforces the non-bypassable agent-bar (SP6): an `agent` principal can NEVER publish. Returns the derived
+ *  (max+1) version number. */
+declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<{
     version: number;
-    role: string;
-    modelId: string;
-    status: string;
-    isCurrent: boolean;
-}
+}>;
+/**
+ * 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[]>;
@@ -61,12 +87,58 @@ declare function rollbackAgentVersion(ctx: Ctx$1, args: {
     tenantId: string;
     slug: string;
     toVersion: number;
-    actor?: string;
+    actor?: SwarmActor;
 }): Promise<{
     version: number;
     restoredFrom: number;
 }>;
 
+/**
+ * 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 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`);
  *  the host applies them with its own tooling — Night Owls never runs DDL itself. */
@@ -77,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:
@@ -162,4 +265,4 @@ interface SupabaseStorage extends StorageAdapter {
 }
 declare function createSupabaseStorage(opts: SupabaseStorageOpts): SupabaseStorage;
 
-export { type AgentVersionInfo, type Ctx$1 as Ctx, MIGRATIONS, type Migration, type PostgresFloorOpts, type SupabaseStorage, type SupabaseStorageOpts, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, listAgentVersions, 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,5 @@
-import { AgentVersion, 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';
 import { PostgresStore, PgVector } from '@mastra/pg';
@@ -30,23 +31,48 @@ declare function createMastraVectorStore(opts: {
     dbUrl: string;
 }): PgVector;
 
-/** The shape callers pass — `version` is derived, not supplied. */
-type PublishAgentDef = Omit<AgentVersion, "version"> & {
+/**
+ * The WRITABLE agent definition repo (SP6) — the core `VersionedRepo` contract backed by Postgres. Extends the
+ * read-only repo with the append-only `publish`/`rollback`/`listVersions` surface. The supabase adapter wires
+ * its `agents` field to this (a `VersionedRepo` IS an `AgentRepo`) and also surfaces it as `agentsWritable`.
+ *
+ * SECURITY: every mutation calls `assertActorMayMutateDefinition(actor)` FIRST (inside the standalone
+ * functions) — the non-bypassable agent-bar. The removable `guardDefinitionMutation` POLICY hook is layered on
+ * by the caller that owns a `HookDispatcher` (the no-code builder); the storage layer only enforces the
+ * framework invariant, which no hook can weaken.
+ */
+declare function makeVersionedRepo(ctx: Ctx$1): VersionedRepo;
+/** The shape callers pass — `version` is derived, not supplied. `actor` is the typed `SwarmActor` principal
+ *  (the agent-bar inspects it); omit it ⇒ the seed system actor. */
+type PublishAgentDef = AgentVersionContent & {
     tenantId: string;
-    actor?: string;
+    actor?: SwarmActor;
     version?: number;
 };
-/** Insert a new agent version, flip the head pointer, audit. Used by seeding/CLI (not in the core interface).
- *  Takes the typed `Ctx` directly (no `__ctx` any-cast); call via `publishAgentVersion(storage.ctx, def)`. */
-declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<void>;
-/** One row of an agent's version history (for rollback UX). */
-interface AgentVersionInfo {
+/** Insert a new agent version, flip the head pointer, audit. Used by seeding/CLI (and `makeVersionedRepo`).
+ *  Takes the typed `Ctx` directly (no `__ctx` any-cast); call via `publishAgentVersion(storage.ctx, def)`.
+ *  Enforces the non-bypassable agent-bar (SP6): an `agent` principal can NEVER publish. Returns the derived
+ *  (max+1) version number. */
+declare function publishAgentVersion(ctx: Ctx$1, def: PublishAgentDef): Promise<{
     version: number;
-    role: string;
-    modelId: string;
-    status: string;
-    isCurrent: boolean;
-}
+}>;
+/**
+ * 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[]>;
@@ -61,12 +87,58 @@ declare function rollbackAgentVersion(ctx: Ctx$1, args: {
     tenantId: string;
     slug: string;
     toVersion: number;
-    actor?: string;
+    actor?: SwarmActor;
 }): Promise<{
     version: number;
     restoredFrom: number;
 }>;
 
+/**
+ * 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 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`);
  *  the host applies them with its own tooling — Night Owls never runs DDL itself. */
@@ -77,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:
@@ -162,4 +265,4 @@ interface SupabaseStorage extends StorageAdapter {
 }
 declare function createSupabaseStorage(opts: SupabaseStorageOpts): SupabaseStorage;
 
-export { type AgentVersionInfo, type Ctx$1 as Ctx, MIGRATIONS, type Migration, type PostgresFloorOpts, type SupabaseStorage, type SupabaseStorageOpts, createMastraPgStore, createMastraVectorStore, createPostgresFloor, createSupabaseStorage, listAgentVersions, 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 };