@selvajs/platform 0.16.1-beta.2 → 0.17.0

package/dist/context.d.ts

@@ -1,15 +1,15 @@
 import type { PlatformPermission } from './permissions/types.js';
 import type { OrgPermission } from './organizations/schemas.js';
 /**
- * Per-request identity + scope passed to every data provider call. Built
- * once per HTTP request from the authenticated session.
+ * Per-request identity + scope passed to every data provider call, built once
+ * per HTTP request from the authenticated session.
  *
  * `actingOrgId` is the org the user is currently acting as — NOT "an org the
  * user is a member of." Tenancy checks compare it to the resource's `orgId`.
  *
- * `instance_admin` implies every other permission, everywhere — encoded by
- * `hasPermission`. `system: true` is a trusted server-internal call;
- * adapters with RLS treat it as fully authorized.
+ * `instance_admin` implies every other permission everywhere, via `hasPermission`.
+ * `system: true` marks a trusted server-internal call; adapters with RLS treat it
+ * as fully authorized.
  */
 export interface RequestContext {
     /** Empty string for system contexts. */
@@ -21,28 +21,21 @@ export interface RequestContext {
     orgPermissions: OrgPermission[];
     /** Never derive from a user session. */
     system?: true;
-    /**
-     * Opaque adapter payload. The Supabase adapter passes the user JWT through
-     * for RLS; local ignores it.
-     */
+    /** Opaque adapter payload — the Supabase adapter passes the user JWT through for RLS; local ignores it. */
     adapterContext?: unknown;
 }
-/**
- * For server-internal operations outside any HTTP request (bootstrap,
- * janitors, migrations). Treated as fully authorized.
- */
+/** For server-internal operations outside any HTTP request (bootstrap, janitors, migrations). */
 export declare const SYSTEM_CONTEXT: RequestContext;
 /**
- * Does NOT cross-check `ctx.actingOrgId` — the caller builds a context scoped
- * to the org they're acting on. An org permission against a ctx without
+ * Does not cross-check `ctx.actingOrgId` — the caller must build a context scoped
+ * to the org it's acting on. An org permission against a context without
  * `actingOrgId` returns false unless `instance_admin` or `system`.
  */
 export declare function hasPermission(ctx: RequestContext, permission: PlatformPermission | OrgPermission): boolean;
 /**
- * Return the org the caller is acting as, or throw `ProviderError(403)` when
- * the context has none. Stores that scope every row to an acting org repeat
- * this guard; centralizing it keeps the failure a single, consistent 403
- * rather than a `null` that leaks into a query as `org_id = undefined`.
+ * Returns the org the caller is acting as, or throws `ProviderError(403)`.
+ * Centralizes this guard so every store that scopes rows to an acting org fails
+ * the same consistent way, instead of leaking `org_id = undefined` into a query.
  */
 export declare function requireActingOrg(ctx: RequestContext): string;
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAIhE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;IAC1C,6CAA6C;IAC7C,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,wCAAwC;IACxC,MAAM,CAAC,EAAE,IAAI,CAAC;IACd;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,cAK5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,kBAAkB,GAAG,aAAa,GAC5C,OAAO,CAOT;AAQD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAK5D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAIhE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC9B,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;IAC1C,6CAA6C;IAC7C,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,wCAAwC;IACxC,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,2GAA2G;IAC3G,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,iGAAiG;AACjG,eAAO,MAAM,cAAc,EAAE,cAK5B,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,cAAc,EACnB,UAAU,EAAE,kBAAkB,GAAG,aAAa,GAC5C,OAAO,CAOT;AAQD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAK5D"}

package/dist/context.js

@@ -1,10 +1,7 @@
 import { ALL_PLATFORM_PERMISSIONS } from './permissions/types.js';
 import { ALL_ORG_PERMISSIONS } from './organizations/schemas.js';
 import { ProviderError } from './errors.js';
-/**
- * For server-internal operations outside any HTTP request (bootstrap,
- * janitors, migrations). Treated as fully authorized.
- */
+/** For server-internal operations outside any HTTP request (bootstrap, janitors, migrations). */
 export const SYSTEM_CONTEXT = {
     userId: '',
     platformPermissions: [...ALL_PLATFORM_PERMISSIONS],
@@ -12,8 +9,8 @@ export const SYSTEM_CONTEXT = {
     system: true
 };
 /**
- * Does NOT cross-check `ctx.actingOrgId` — the caller builds a context scoped
- * to the org they're acting on. An org permission against a ctx without
+ * Does not cross-check `ctx.actingOrgId` — the caller must build a context scoped
+ * to the org it's acting on. An org permission against a context without
  * `actingOrgId` returns false unless `instance_admin` or `system`.
  */
 export function hasPermission(ctx, permission) {
@@ -31,10 +28,9 @@ function isPlatformPermission(p) {
     return PLATFORM_PERMISSION_VALUES.has(p);
 }
 /**
- * Return the org the caller is acting as, or throw `ProviderError(403)` when
- * the context has none. Stores that scope every row to an acting org repeat
- * this guard; centralizing it keeps the failure a single, consistent 403
- * rather than a `null` that leaks into a query as `org_id = undefined`.
+ * Returns the org the caller is acting as, or throws `ProviderError(403)`.
+ * Centralizes this guard so every store that scopes rows to an acting org fails
+ * the same consistent way, instead of leaking `org_id = undefined` into a query.
  */
 export function requireActingOrg(ctx) {
     if (!ctx.actingOrgId) {

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA8B5C;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC7C,MAAM,EAAE,EAAE;IACV,mBAAmB,EAAE,CAAC,GAAG,wBAAwB,CAAC;IAClD,cAAc,EAAE,CAAC,GAAG,mBAAmB,CAAC;IACxC,MAAM,EAAE,IAAI;CACZ,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC5B,GAAmB,EACnB,UAA8C;IAE9C,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,IAAI,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,OAAO,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,CAAC;AAE7E,SAAS,oBAAoB,CAAC,CAAS;IACtC,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAmB;IACnD,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACtB,MAAM,IAAI,aAAa,CAAC,mCAAmC,EAAE,GAAG,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,CAAC;AACxB,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2B5C,iGAAiG;AACjG,MAAM,CAAC,MAAM,cAAc,GAAmB;IAC7C,MAAM,EAAE,EAAE;IACV,mBAAmB,EAAE,CAAC,GAAG,wBAAwB,CAAC;IAClD,cAAc,EAAE,CAAC,GAAG,mBAAmB,CAAC;IACxC,MAAM,EAAE,IAAI;CACZ,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC5B,GAAmB,EACnB,UAA8C;IAE9C,IAAI,GAAG,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC5B,IAAI,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,IAAI,oBAAoB,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,OAAO,GAAG,CAAC,mBAAmB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,0BAA0B,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,CAAC;AAE7E,SAAS,oBAAoB,CAAC,CAAS;IACtC,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAmB;IACnD,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;QACtB,MAAM,IAAI,aAAa,CAAC,mCAAmC,EAAE,GAAG,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,GAAG,CAAC,WAAW,CAAC;AACxB,CAAC"}

package/dist/data/interface.d.ts

@@ -1,15 +1,13 @@
 /**
- * `IDataProvider` is the composition root that bundles every store an adapter
- * implements. Individual interfaces (`IOrgStore`, `IProjectStore`, …) live
- * next to their types in their respective subdirs — only the composition
- * lives here.
+ * Composition root bundling every store an adapter implements. Individual
+ * interfaces (`IOrgStore`, `IProjectStore`, …) live next to their types in
+ * their own subdirs.
  *
  * Every store method takes a `RequestContext` first. **The query itself is
  * the security boundary** — adapters MUST scope reads/writes by `ctx`. An
  * unauthorized caller sees an empty page, `null`, or a `ProviderError`.
  *
- * Access-control predicates live in `@selvajs/platform/access` (pure rules).
- * Stores do storage; rules do rules.
+ * Access-control predicates live in `@selvajs/platform/access`, not here.
  */
 import type { IOrgStore } from '../organizations/interface.js';
 import type { IProjectStore } from '../projects/interface.js';
@@ -24,10 +22,10 @@ import type { IAuditQuery } from '../events/audit.js';
 import type { IEventSink } from '../events/interface.js';
 import type { RequestContext } from '../context.js';
 /**
- * Result of the app↔DB schema handshake (audit O3). `expected` is the
- * migration head the running app was built against; `actual` is what the
- * database reports (`null` when the database can't even answer — e.g. the
- * handshake function itself was never migrated in).
+ * Result of the app↔DB schema handshake. `expected` is the migration head
+ * the running app was built against; `actual` is what the database reports
+ * (`null` when the database can't even answer — e.g. the handshake function
+ * itself was never migrated in).
  */
 export interface SchemaVersionReport {
     ok: boolean;
@@ -36,20 +34,15 @@ export interface SchemaVersionReport {
     /** Operator-facing explanation + recovery hint when not ok. */
     message?: string;
 }
-/**
- * Extra identifiers for {@link IDataProvider.onUserDeleted} erasure that are
- * not derivable from the userId alone. Captured by the caller BEFORE the auth
- * user is deleted (see the method's contract).
- */
+/** Extra identifiers {@link IDataProvider.onUserDeleted} needs but can't derive from userId alone. */
 export interface UserErasureOptions {
     /** The deleted user's email, for scrubbing invite/audit rows keyed by it. */
     email?: string;
 }
 /**
- * Sentinel written to `solve_metrics.actor_id` when a user is erased, so the
- * retention telemetry survives (capacity/billing aggregates) without
- * identifying the person. Distinct from `'system'`, which marks solves that
- * were never attributed to a user (share-link / server flows).
+ * Written to `solve_metrics.actor_id` when a user is erased, so capacity/billing
+ * aggregates survive without identifying the person. Distinct from `'system'`,
+ * which marks solves never attributed to a user (share-link / server flows).
  */
 export declare const ERASED_ACTOR_ID = "deleted";
 export interface IDataProvider {
@@ -69,31 +62,27 @@ export interface IDataProvider {
      */
     auditQuery?: IAuditQuery;
     /**
-     * The write-side event sink this provider's stores emit into. Optional —
-     * exposed so app code with no store mutation to piggyback on (e.g. the
-     * self-update route, audit O2) can emit domain events into the same log.
-     * Callers fall back to `NoopEventSink` when absent.
+     * Write-side event sink this provider's stores emit into. Optional — lets app
+     * code with no store mutation to piggyback on (e.g. a self-update route) emit
+     * domain events into the same log. Callers fall back to `NoopEventSink` when absent.
      */
     events?: IEventSink;
     /**
-     * App↔DB schema handshake (audit O3). Optional — implemented by adapters
-     * whose schema is migrated out-of-band (Supabase: `supabase db push` is a
-     * manual operator step the app can't run itself). Boot health calls this
-     * structurally (same pattern as `IComputeServerStore.verifySecrets`) and
-     * drives `/api/health` to 503 when the database is behind the app, so
-     * monitoring — and the self-update runner's health probe — catch schema
-     * skew instead of surfacing it as per-request store errors.
+     * Optional — only adapters whose schema migrates out-of-band (Supabase:
+     * `supabase db push` is a manual operator step) need this. Boot health calls
+     * it and drives `/api/health` to 503 when the database is behind the app,
+     * so schema skew surfaces as a health check instead of per-request store errors.
      *
      * MUST NOT throw: report failure via `ok: false`.
      */
     verifySchemaVersion?(): Promise<SchemaVersionReport>;
     /**
-     * Idempotently register a user in the data layer. Called by `hooks.server.ts`
+     * Idempotently registers a user in the data layer. Called by `hooks.server.ts`
      * after `verifyToken` succeeds, so the data layer always has a row for the
      * authenticated user regardless of which auth provider issued the ID.
      *
      * Adapters with a DB-side trigger that auto-seeds on auth signup (Supabase)
-     * make this a no-op. Adapters that own a separate user-data table without a
+     * make this a no-op. Adapters owning a separate user-data table without a
      * trigger (local-provider) upsert here.
      *
      * MUST be safe to call concurrently and on every request. MUST NOT throw on
@@ -102,26 +91,22 @@ export interface IDataProvider {
     ensureUser(ctx: RequestContext, userId: string): Promise<void>;
     /**
      * Cascade + erasure hook called after the auth provider deletes a user.
-     * Removes or anonymizes any data-layer rows tied to that user (the user-data
-     * row, and any personal data keyed by `userId` or `email` that should not
-     * outlive the identity).
+     * Removes or anonymizes data-layer rows tied to that user.
      *
-     * Most user-owned rows die via FK cascade / `set null` against
-     * `auth.users` (Supabase) or explicit membership cleanup (local). But some
-     * personal data is NOT reachable by those FKs and MUST be scrubbed here:
+     * Most user-owned rows die via FK cascade / `set null` against `auth.users`
+     * (Supabase) or explicit membership cleanup (local). Some personal data is
+     * NOT reachable by those FKs and MUST be scrubbed here:
      *  - audit rows keyed by a plain-text `actor_id` (no FK),
-     *  - invites addressed to the user's `email` (the invitee's PII), and the
-     *    same email embedded in `invite.created` audit payloads,
-     *  - retention telemetry (`solve_metrics`) that is deliberately not
-     *    FK-cascaded — anonymized (actor tombstoned), not deleted.
+     *  - invites addressed to the user's `email`, and that email embedded in
+     *    `invite.created` audit payloads,
+     *  - `solve_metrics`, deliberately not FK-cascaded — anonymized (actor
+     *    tombstoned), not deleted.
      *
-     * `opts.email` is the deleted user's email, which the CALLER must capture
+     * `opts.email` is the deleted user's email; the CALLER must capture it
      * BEFORE `deleteUser` runs (the auth user is already gone by the time this
-     * hook fires, so it cannot be looked up here). When absent, email-keyed
-     * scrubs are skipped — pass it to fully close erasure.
+     * hook fires). When absent, email-keyed scrubs are skipped.
      *
-     * MUST tolerate a missing user and missing rows (idempotent — caller may
-     * retry).
+     * MUST tolerate a missing user and missing rows (idempotent — caller may retry).
      */
     onUserDeleted(ctx: RequestContext, userId: string, opts?: UserErasureOptions): Promise<void>;
 }

package/dist/data/interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/data/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,aAAa,EAAE,mBAAmB,CAAC;IACnC,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,eAAe,CAAC;IAC5B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,WAAW,EAAE,wBAAwB,CAAC;IACtC,qBAAqB,EAAE,0BAA0B,CAAC;IAClD;;;;OAIG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAErD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F"}
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/data/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,sGAAsG;AACtG,MAAM,WAAW,kBAAkB;IAClC,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,aAAa,EAAE,mBAAmB,CAAC;IACnC,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,eAAe,CAAC;IAC5B,WAAW,EAAE,iBAAiB,CAAC;IAC/B,WAAW,EAAE,wBAAwB,CAAC;IACtC,qBAAqB,EAAE,0BAA0B,CAAC;IAClD;;;;OAIG;IACH,UAAU,CAAC,EAAE,WAAW,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IAEpB;;;;;;;OAOG;IACH,mBAAmB,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAErD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7F"}

package/dist/data/interface.js

@@ -1,21 +1,18 @@
 /**
- * `IDataProvider` is the composition root that bundles every store an adapter
- * implements. Individual interfaces (`IOrgStore`, `IProjectStore`, …) live
- * next to their types in their respective subdirs — only the composition
- * lives here.
+ * Composition root bundling every store an adapter implements. Individual
+ * interfaces (`IOrgStore`, `IProjectStore`, …) live next to their types in
+ * their own subdirs.
  *
  * Every store method takes a `RequestContext` first. **The query itself is
  * the security boundary** — adapters MUST scope reads/writes by `ctx`. An
  * unauthorized caller sees an empty page, `null`, or a `ProviderError`.
  *
- * Access-control predicates live in `@selvajs/platform/access` (pure rules).
- * Stores do storage; rules do rules.
+ * Access-control predicates live in `@selvajs/platform/access`, not here.
  */
 /**
- * Sentinel written to `solve_metrics.actor_id` when a user is erased, so the
- * retention telemetry survives (capacity/billing aggregates) without
- * identifying the person. Distinct from `'system'`, which marks solves that
- * were never attributed to a user (share-link / server flows).
+ * Written to `solve_metrics.actor_id` when a user is erased, so capacity/billing
+ * aggregates survive without identifying the person. Distinct from `'system'`,
+ * which marks solves never attributed to a user (share-link / server flows).
  */
 export const ERASED_ACTOR_ID = 'deleted';
 //# sourceMappingURL=interface.js.map

package/dist/data/interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/data/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAuCH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC"}
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/data/interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAmCH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC"}

package/dist/definitions/interface.d.ts

@@ -4,16 +4,15 @@ import type { UISchema } from '@selvajs/schemas';
 import type { DefinitionRecord, DefinitionRecordPatch, DefinitionVersion } from './types.js';
 /**
  * Definition metadata + version store. Blob contents live in `IStorageProvider`;
- * this interface tracks the parent record plus immutable version rows and the
- * `live` / `draft` channel pointers.
+ * this tracks the parent record, immutable version rows, and the `live`/`draft`
+ * channel pointers.
  */
 export interface IDefinitionStore {
     list(ctx: RequestContext, opts?: DefinitionListOptions): Promise<Page<DefinitionRecord>>;
     listByProject(ctx: RequestContext, projectId: string, opts?: DefinitionListOptions): Promise<Page<DefinitionRecord>>;
     /**
-     * List definitions whose parent project has `visibility === 'public'`.
-     * Pass `orgId` to restrict to one org; omit for cross-org listing within
-     * whatever tenant boundary the adapter already enforces.
+     * Lists definitions whose parent project has `visibility === 'public'`.
+     * Pass `orgId` to restrict to one org; omit for cross-org listing.
      */
     listPublic(ctx: RequestContext, opts?: DefinitionListOptions & {
         orgId?: string;
@@ -23,39 +22,35 @@ export interface IDefinitionStore {
     update(ctx: RequestContext, guid: string, patch: DefinitionRecordPatch): Promise<void>;
     delete(ctx: RequestContext, guid: string): Promise<void>;
     /**
-     * Cascade hook: soft-delete every live definition in a project. Called by
-     * `IProjectStore.deleteProject` — a deleted project must never keep serving
-     * its definitions (they surface in the library/public listings independent
-     * of the project row). No-op when the project has none. Mirrors the
-     * `deleteByProject` cascade hooks on `IPlatformProjectGrantStore`.
+     * Cascade hook: soft-deletes every live definition in a project. Called by
+     * `IProjectStore.deleteProject` — definitions surface in library/public
+     * listings independent of the project row, so a deleted project must not
+     * keep serving them. No-op when the project has none.
      */
     deleteByProject(ctx: RequestContext, projectId: string): Promise<void>;
     /** Atomic +1 on the solve counter. No-op if the record doesn't exist. */
     incrementSolveCount(ctx: RequestContext, guid: string): Promise<void>;
     /**
-     * Atomically reserve the next `versionNumber` for a new version: returns the
-     * current `nextVersionNumber` and advances the counter by 1 in a single
-     * operation (so concurrent uploads never collide on a number/fileKey). The
-     * counter is monotonic and NEVER decremented — deleting the latest version
-     * does not free its number, so a delete-then-reupload mints a fresh number and
-     * fresh `fileKey` instead of overwriting the deleted blob's key. Throws if the
-     * definition doesn't exist.
+     * Atomically returns the current `nextVersionNumber` and advances the counter
+     * by 1, so concurrent uploads never collide on a number/fileKey. Never
+     * decremented — deleting the latest version doesn't free its number, so a
+     * delete-then-reupload mints a fresh `fileKey` instead of reusing the deleted
+     * blob's key. Throws if the definition doesn't exist.
      */
     reserveNextVersionNumber(ctx: RequestContext, guid: string): Promise<number>;
     createVersion(ctx: RequestContext, version: DefinitionVersion): Promise<void>;
     /**
-     * Newest first by `versionNumber`. Listed rows carry metadata only — `schema`
-     * is always `undefined` here regardless of what is stored, because it is a
-     * large blob no list caller needs. Use `getVersion` when you need the schema.
+     * Newest first by `versionNumber`. `schema` is always `undefined` on listed
+     * rows regardless of what's stored — it's a large blob no list caller needs.
+     * Use `getVersion` for the schema.
      */
     listVersions(ctx: RequestContext, definitionId: string, opts?: ListOptions): Promise<Page<DefinitionVersion>>;
     /** The full row, including the cached `schema` when one has been extracted. */
     getVersion(ctx: RequestContext, versionId: string): Promise<DefinitionVersion | null>;
     /**
-     * Set the cached compute-extracted schema on a version row. Used by the
-     * upload path (writes the schema validated up-front) and the temporary
-     * solve-time backfill bridge (see selva/specs/SchemaCaching.md). No-op if
-     * the version doesn't exist.
+     * Sets the cached compute-extracted schema on a version row. Used by the
+     * upload path and the solve-time backfill bridge for pre-existing versions.
+     * No-op if the version doesn't exist.
      */
     setVersionSchema(ctx: RequestContext, versionId: string, schema: UISchema): Promise<void>;
     /**
@@ -69,16 +64,14 @@ export interface IDefinitionStore {
     /**
      * Atomic `'pending'` → `'draft'` bootstrap. Sets BOTH `liveVersionId` and
      * `draftVersionId` to `versionId` and flips `status` to `'draft'` in a
-     * single update — used by the create flow so a mid-flight failure can't
-     * leave the record half-promoted (status='draft' with a null channel
-     * pointer, or status='pending' with channels set).
+     * single update, so a mid-flight failure can't leave the record
+     * half-promoted (draft status with a null channel pointer, or pending
+     * status with channels set).
      *
      * Validates that `versionId` belongs to `definitionId` (404 if not).
      *
-     * Does NOT emit `definition.published`. The bootstrap is covered by the
-     * parent's `definition.created` + `definition_version.created` pair;
-     * `definition.published` is reserved for explicit publish ops via
-     * `setLiveVersion`.
+     * Does NOT emit `definition.published` — that event is reserved for
+     * explicit publish via `setLiveVersion`.
      */
     attachInitialVersion(ctx: RequestContext, definitionId: string, versionId: string): Promise<void>;
 }

package/dist/definitions/interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/definitions/interface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/definitions/interface.ts"],"names":[],"mappings":"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"}

package/dist/definitions/schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/definitions/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,QAAoE,CAAC;AAE5F,eAAO,MAAM,UAAU,aAAsD,CAAC;AAO9E,eAAO,MAAM,sBAAsB;;;;EAA6C,CAAC;AAEjF,eAAO,MAAM,uBAAuB;;;EAAwB,CAAC;AAE7D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAclC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;EAA4B,CAAC;AAEjE,oDAAoD;AACpD,eAAO,MAAM,2BAA2B;;;;;;;;iBAQtC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;iBAYpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,uDAAuD;AACvD,eAAO,MAAM,yBAAyB;;kBAIzB,CAAC"}
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/definitions/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,UAAU,QAAoE,CAAC;AAE5F,eAAO,MAAM,UAAU,aAAsD,CAAC;AAK9E,eAAO,MAAM,sBAAsB;;;;EAA6C,CAAC;AAEjF,eAAO,MAAM,uBAAuB;;;EAAwB,CAAC;AAE7D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;iBAalC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;EAA4B,CAAC;AAEjE,oDAAoD;AACpD,eAAO,MAAM,2BAA2B;;;;;;;;iBAQtC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;iBAYpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,uDAAuD;AACvD,eAAO,MAAM,yBAAyB;;kBAIzB,CAAC"}

package/dist/definitions/schemas.js

@@ -1,11 +1,9 @@
 import { z } from 'zod';
 export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const GuidSchema = z.string().regex(UUID_REGEX, 'Invalid GUID format');
-// Intentionally omits `pending` — the fourth real status (see `DefinitionStatus`
-// in ./types.ts). `pending` is a create-internal state that `DefinitionService.create`
-// writes during the metadata-first window; a client must never hand-set it through an
-// update, so it is absent from this input validator by design, not by drift. (`review`
-// was a dead fifth value dropped from the DB CHECK in migration 20260716120000 — audit D2.)
+// Intentionally omits `pending` (see `DefinitionStatus` in ./types.ts): it's a
+// create-internal state `DefinitionService.create` writes during the
+// metadata-first window, and a client must never hand-set it through an update.
 export const DefinitionStatusSchema = z.enum(['draft', 'published', 'archived']);
 export const DefinitionFileExtSchema = z.enum(['gh', 'ghx']);
 export const DefinitionVersionSchema = z.object({
@@ -18,8 +16,7 @@ export const DefinitionVersionSchema = z.object({
     uploadedBy: z.string().min(1),
     uploadedAt: z.string(),
     changeNote: z.string().max(1000).optional(),
-    // Cached compute-extracted UI schema. Structural correctness is validated by
-    // Rhino.Compute at upload, not here — this only asserts it's an object.
+    // Rhino.Compute validates structural correctness at upload; this only asserts it's an object.
     schema: z.record(z.string(), z.unknown()).optional(),
     schemaExtractedAt: z.string().optional()
 });
@@ -48,8 +45,8 @@ export const UpdateMetadataInputSchema = z.object({
     tags: z.array(z.string().max(64)).max(20).nullable().optional(),
     projectId: GuidSchema.optional(),
     computeServerId: GuidSchema.nullable().optional(),
-    // L2 cache quota (R9): 0 = off, N = per-definition entry cap, null = inherit
-    // the global default. Bounded so a settings typo can't request a runaway quota.
+    // 0 = off, N = per-definition entry cap, null = inherit the global default.
+    // Bounded so a settings typo can't request a runaway quota.
     solveCacheLimit: z.number().int().min(0).max(100_000).nullable().optional(),
     status: DefinitionStatusSchema.optional()
 });

package/dist/definitions/schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/definitions/schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../../src/definitions/schemas.ts"],"names":[],"mappings":"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"}

package/dist/definitions/types.d.ts

@@ -8,27 +8,21 @@ export declare const COVER_IMAGE_CONTENT_TYPES: Record<string, string>;
  * - `pending` — internal: metadata written, blob upload may be in flight.
  * - `draft` — work in progress, not visible to runners.
  * - `published` — live, visible to all with solve access.
- * - `archived` — retired but preserved. Versions and channel pointers remain
- *   intact; restore via `update({ status: 'draft' | 'published' })`.
+ * - `archived` — retired but preserved; restore via `update({ status: 'draft' | 'published' })`.
  *
- * List endpoints filter `pending` and `archived` by default (opt in via
- * `DefinitionListOptions.includePending` / `includeArchived`, or pass an
- * explicit `statuses` filter).
+ * List endpoints filter out `pending` and `archived` by default (opt in via
+ * `DefinitionListOptions.includePending`/`includeArchived`, or an explicit `statuses` filter).
  */
 export type DefinitionStatus = 'pending' | 'draft' | 'published' | 'archived';
 /**
  * Immutable snapshot of a definition's `.gh` file at a point in time. New
  * uploads create new versions; rollback re-points the parent's
- * `liveVersionId` (it never mutates the version itself).
+ * `liveVersionId` rather than mutating the version itself.
  */
 export interface DefinitionVersion {
     id: string;
     definitionId: string;
-    /**
-     * Monotonic integer starting at 1; NEVER reused — allocated from the parent
-     * record's `nextVersionNumber` counter, which only ever advances. Deleting the
-     * latest version does not free its number, so `fileKey`s never collide.
-     */
+    /** Allocated from `DefinitionRecord.nextVersionNumber`; see that field for the numbering guarantee. */
     versionNumber: number;
     fileExt: DefinitionFileExt;
     /** Full storage key. Opaque to callers. */
@@ -40,9 +34,8 @@ export interface DefinitionVersion {
     changeNote?: string;
     /**
      * Compute-extracted UI schema, cached at upload so the render path doesn't
-     * re-fetch it from Rhino.Compute on every load. Optional only because of the
-     * lazy-backfill bridge for pre-existing versions (see
-     * selva/specs/SchemaCaching.md); new uploads always set it.
+     * re-fetch it from Rhino.Compute on every load. Optional only for the
+     * lazy-backfill bridge on pre-existing versions; new uploads always set it.
      */
     schema?: UISchema;
     /** ISO timestamp of when `schema` was extracted. */
@@ -58,15 +51,12 @@ export interface DefinitionRecord {
     /** Falls back to the org default, then the platform default. */
     computeServerId?: string;
     /**
-     * Per-definition quota for a shared solve-result cache: `0` = caching off (the
-     * non-determinism / wide-input-space escape hatch), `N` = keep at most N cached
-     * solves, absent = inherit whatever default the backend defines.
+     * Per-definition quota for a shared solve-result cache: `0` = caching off,
+     * `N` = keep at most N cached solves, absent = inherit the backend default.
      *
-     * **Dormant.** No shared backend ships today (see `ISolveResultCache`), so this
-     * currently affects nothing at solve time. It is a persisted column in both
-     * stores plus a shipped Supabase migration, and it is the right per-definition
-     * knob the moment a backend is wired — so it stays rather than becoming a data
-     * migration to remove and re-add.
+     * **Dormant.** No shared backend ships today (see `ISolveResultCache`), so
+     * this affects nothing at solve time yet. Kept as a persisted column rather
+     * than removed, since it's the right knob once a backend exists.
      */
     solveCacheLimit?: number;
     displayName: string;
@@ -78,13 +68,11 @@ export interface DefinitionRecord {
     status: DefinitionStatus;
     solveCount: number;
     /**
-     * Monotonic version-number allocator. The next `uploadVersion` reserves this
-     * value for the new version's `versionNumber` (and `fileKey`) then advances
-     * the counter — it is NEVER decremented, so delete-latest-then-reupload mints
-     * a FRESH number and a FRESH `fileKey` rather than reusing the deleted one.
-     * Reusing a `fileKey` would let a stale storage blob (or any layer keying on
-     * the key) serve the old version's bytes for the new content. Starts at 2
-     * after v1 is created.
+     * Monotonic version-number allocator, never decremented: the next upload
+     * reserves this value then advances the counter, so a delete-latest-then-reupload
+     * mints a fresh number and `fileKey` instead of reusing one — otherwise a stale
+     * storage blob could serve the old version's bytes under the new content's key.
+     * Starts at 2 after v1 is created.
      */
     nextVersionNumber: number;
     /**
@@ -95,19 +83,18 @@ export interface DefinitionRecord {
     draftVersionId: string | null;
     createdAt: string;
     updatedAt: string;
+    /** Soft-delete marker, independent of `status`: a store filters this out regardless of `archived`. */
     deletedAt?: string | null;
 }
 /**
- * The list-row projection of a `DefinitionRecord`, and the shape
- * `GET /api/v1/definitions` returns.
+ * List-row projection of a `DefinitionRecord`; the shape `GET /api/v1/definitions` returns.
  *
- * Deliberately narrower than the full record: `ownerId`, `createdBy`,
- * `updatedBy`, and `solveCacheLimit` are internal and no list view reads them.
- * v1 is additive-only, so a field published here can only be removed in v2 —
- * narrowing is free now and impossible later.
+ * Deliberately narrower than the full record — `ownerId`, `createdBy`,
+ * `updatedBy`, `solveCacheLimit` are internal. v1 is additive-only, so a field
+ * published here can only be removed in v2: narrowing later is not an option.
  *
- * `liveVersionId` is the pointer, not a version number: the number is not a
- * native column and joining for it would cost a query per row in both stores.
+ * `liveVersionId` is the pointer, not a version number — the number isn't a
+ * native column, so resolving it would cost a query per row.
  */
 export interface DefinitionListItem {
     guid: string;
@@ -122,11 +109,10 @@ export interface DefinitionListItem {
     liveVersionId: string | null;
     updatedAt: string;
 }
-/** Project a full record down to the fields v1 publishes. */
 export declare function toDefinitionListItem(r: DefinitionRecord): DefinitionListItem;
 /**
- * Patch omits immutable fields and provider-managed ones (use
- * `setLiveVersion`/`setDraftVersion` for the latter).
+ * Omits immutable fields and provider-managed ones (use
+ * `setLiveVersion`/`setDraftVersion` for channel pointers).
  *
  * - `undefined` — leave unchanged
  * - `null` — clear (only on nullable fields)
@@ -145,9 +131,7 @@ export interface DefinitionRecordPatch {
     /** L2 cache quota (see {@link DefinitionRecord.solveCacheLimit}); `null` clears to inherit. */
     solveCacheLimit?: number | null;
     status?: DefinitionStatus;
-    /** Ownership transfer. */
     ownerId?: string;
 }
-/** Channel for solve dispatch. */
 export type DefinitionChannel = 'live' | 'draft';
 //# sourceMappingURL=types.d.ts.map