@marktiderman/genesis-core 1.1.2 → 1.3.0

package/dist/chunk-4W4W7F4I.js

@@ -0,0 +1,20 @@
+// src/schema/write-outcome.ts
+var DataWriteError = class extends Error {
+  outcome;
+  current;
+  currentVersion;
+  constructor(outcome, message, options = {}) {
+    super(message);
+    this.name = "DataWriteError";
+    this.outcome = outcome;
+    this.current = options.current;
+    this.currentVersion = options.currentVersion;
+  }
+};
+function isDataWriteError(error) {
+  return error instanceof Error && error.name === "DataWriteError" && typeof error.outcome === "string";
+}
+
+export { DataWriteError, isDataWriteError };
+//# sourceMappingURL=chunk-4W4W7F4I.js.map
+//# sourceMappingURL=chunk-4W4W7F4I.js.map

package/dist/chunk-4W4W7F4I.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/write-outcome.ts"],"names":[],"mappings":";AAyCO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAC/B,OAAA;AAAA,EACA,OAAA;AAAA,EACA,cAAA;AAAA,EAET,WAAA,CAAY,OAAA,EAAuB,OAAA,EAAiB,OAAA,GAAiC,EAAC,EAAG;AACvF,IAAA,KAAA,CAAM,OAAO,CAAA;AACb,IAAA,IAAA,CAAK,IAAA,GAAO,gBAAA;AACZ,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAA,CAAK,UAAU,OAAA,CAAQ,OAAA;AACvB,IAAA,IAAA,CAAK,iBAAiB,OAAA,CAAQ,cAAA;AAAA,EAChC;AACF;AAMO,SAAS,iBAAiB,KAAA,EAAyC;AACxE,EAAA,OACE,iBAAiB,KAAA,IACjB,KAAA,CAAM,SAAS,gBAAA,IACf,OAAQ,MAAgC,OAAA,KAAY,QAAA;AAExD","file":"chunk-4W4W7F4I.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Why a write did not save (DATA-STUDIO.md \"Write safety\")\n//\n// A write that changes nothing is never reported as \"permission denied\" by\n// assumption. The provider re-reads the row and says what actually happened.\n// ---------------------------------------------------------------------------\n\nimport type { DataRow } from \"./types\";\n\n/**\n * - `conflict`: someone else changed the row since it was read. `current`\n *   carries the row as it is now.\n * - `gone`: the row was deleted, or is no longer visible to this user. The\n *   two cannot be told apart without a privileged look at the table, which\n *   would show this user a fact about a row they cannot see.\n * - `forbidden`: the row is visible and unchanged, but the app or the\n *   database does not let this user make this change. Only reported when\n *   that is proven, never assumed from \"zero rows changed\".\n * - `invalid`: the store rejected the value (type, constraint, not-null).\n * - `audit_failed`: the audit entry could not be written, so the edit was\n *   rolled back with it.\n * - `unauthenticated`: no signed-in user, or the session expired.\n * - `error`: anything else. The edit did not commit.\n */\nexport type WriteOutcome =\n  | \"conflict\"\n  | \"gone\"\n  | \"forbidden\"\n  | \"invalid\"\n  | \"audit_failed\"\n  | \"unauthenticated\"\n  | \"error\";\n\nexport interface DataWriteErrorOptions {\n  /** The row as it is now, for a `conflict`. Only fields the user may read. */\n  current?: DataRow;\n  /** The row's current version token, for a `conflict`. */\n  currentVersion?: string | null;\n}\n\n/** Thrown by a provider when a write did not commit. */\nexport class DataWriteError extends Error {\n  readonly outcome: WriteOutcome;\n  readonly current?: DataRow;\n  readonly currentVersion?: string | null;\n\n  constructor(outcome: WriteOutcome, message: string, options: DataWriteErrorOptions = {}) {\n    super(message);\n    this.name = \"DataWriteError\";\n    this.outcome = outcome;\n    this.current = options.current;\n    this.currentVersion = options.currentVersion;\n  }\n}\n\n/**\n * `instanceof` fails when two copies of this package are installed, so check\n * the shape instead.\n */\nexport function isDataWriteError(error: unknown): error is DataWriteError {\n  return (\n    error instanceof Error &&\n    error.name === \"DataWriteError\" &&\n    typeof (error as { outcome?: unknown }).outcome === \"string\"\n  );\n}\n"]}

package/dist/{chunk-RKR5K7Q3.js → chunk-6AA4ISUA.js}

@@ -121,5 +121,5 @@ function createSupabaseProvider(client) {
 }
 
 export { createSupabaseProvider };
-//# sourceMappingURL=chunk-RKR5K7Q3.js.map
-//# sourceMappingURL=chunk-RKR5K7Q3.js.map
+//# sourceMappingURL=chunk-6AA4ISUA.js.map
+//# sourceMappingURL=chunk-6AA4ISUA.js.map

package/dist/{chunk-RKR5K7Q3.js.map → chunk-6AA4ISUA.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/provider/supabase-provider.ts"],"names":[],"mappings":"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","file":"chunk-RKR5K7Q3.js","sourcesContent":["import type {\n  DataProvider,\n  FilterParam,\n} from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Minimal Supabase client shape — no hard dependency on @supabase/supabase-js\n// ---------------------------------------------------------------------------\n\n/** A chainable query builder returned by `client.from(table)`. */\ninterface SupabaseQueryBuilder {\n  select(\n    columns?: string,\n    options?: { count?: \"exact\" | \"planned\" | \"estimated\" },\n  ): SupabaseQueryBuilder;\n  insert(data: Record<string, unknown> | Record<string, unknown>[]): SupabaseQueryBuilder;\n  update(data: Record<string, unknown>): SupabaseQueryBuilder;\n  delete(): SupabaseQueryBuilder;\n  eq(column: string, value: unknown): SupabaseQueryBuilder;\n  neq(column: string, value: unknown): SupabaseQueryBuilder;\n  gt(column: string, value: unknown): SupabaseQueryBuilder;\n  lt(column: string, value: unknown): SupabaseQueryBuilder;\n  gte(column: string, value: unknown): SupabaseQueryBuilder;\n  lte(column: string, value: unknown): SupabaseQueryBuilder;\n  ilike(column: string, value: string): SupabaseQueryBuilder;\n  in(column: string, values: unknown[]): SupabaseQueryBuilder;\n  is(column: string, value: null): SupabaseQueryBuilder;\n  not(column: string, operator: string, value: unknown): SupabaseQueryBuilder;\n  or(filters: string): SupabaseQueryBuilder;\n  order(column: string, options?: { ascending?: boolean }): SupabaseQueryBuilder;\n  range(from: number, to: number): SupabaseQueryBuilder;\n  single(): SupabaseQueryBuilder;\n  then: Promise<{ data: unknown; error: unknown; count?: number | null }>[\"then\"];\n}\n\n/**\n * Minimal Supabase client interface — the public shape this package has\n * always exposed for a caller that wants to type its own client or a\n * wrapper around one. Unchanged: `from()` still returns `SupabaseQueryBuilder`\n * so existing consumers that annotate a variable with this type and chain\n * off it keep type-checking exactly as before.\n */\nexport interface SupabaseClient {\n  from(table: string): SupabaseQueryBuilder;\n}\n\n/**\n * What `createSupabaseProvider` actually requires from its `client` argument\n * — deliberately looser than the public `SupabaseClient` above, and used\n * ONLY for that one parameter. A real `@supabase/supabase-js` client's\n * `from()` returns a generic, table-typed `PostgrestQueryBuilder` whose chain\n * methods don't structurally match `SupabaseQueryBuilder`, which used to\n * force callers to pass their client through `as never`. Since `unknown` is\n * a supertype of everything, any real client's `from(table: string)`\n * satisfies THIS shape without a cast; `createSupabaseProvider` narrows to\n * `SupabaseQueryBuilder` internally, once, right after each `from()` call.\n * Loosening only the input here — rather than `SupabaseClient` itself —\n * means a caller relying on `SupabaseClient`'s stricter return type for\n * their own chaining is unaffected.\n */\nexport interface SupabaseClientInput {\n  from(table: string): unknown;\n}\n\n// ---------------------------------------------------------------------------\n// Provider factory\n// ---------------------------------------------------------------------------\n\nfunction escapeIlike(value: string): string {\n  return value.replace(/[%_\\\\]/g, (char) => `\\\\${char}`);\n}\n\nexport function createSupabaseProvider(client: SupabaseClientInput): DataProvider {\n  // ---------------------------------------------------------------------------\n  // Helpers\n  // ---------------------------------------------------------------------------\n\n  function applyFilters(\n    query: SupabaseQueryBuilder,\n    filters: FilterParam[] | undefined,\n  ): SupabaseQueryBuilder {\n    if (!filters) return query;\n    for (const f of filters) {\n      switch (f.operator) {\n        case \"eq\":\n          query = query.eq(f.field, f.value);\n          break;\n        case \"neq\":\n          query = query.neq(f.field, f.value);\n          break;\n        case \"gt\":\n          query = query.gt(f.field, f.value);\n          break;\n        case \"lt\":\n          query = query.lt(f.field, f.value);\n          break;\n        case \"gte\":\n          query = query.gte(f.field, f.value);\n          break;\n        case \"lte\":\n          query = query.lte(f.field, f.value);\n          break;\n        case \"contains\":\n          query = query.ilike(f.field, `%${escapeIlike(String(f.value))}%`);\n          break;\n        case \"in\":\n          query = query.in(f.field, f.value);\n          break;\n        case \"is_null\":\n          query = query.is(f.field, null);\n          break;\n        case \"is_not_null\":\n          query = query.not(f.field, \"is\", null);\n          break;\n        case \"between\": {\n          const [lo, hi] = f.value;\n          query = query.gte(f.field, lo).lte(f.field, hi);\n          break;\n        }\n        default:\n          throw new Error(`[SupabaseProvider] Unknown filter operator \"${(f as FilterParam).operator}\"`);\n          break;\n      }\n    }\n    return query;\n  }\n\n  function throwIfError(result: { error: unknown }): void {\n    if (result.error) {\n      const pgError = result.error as { message?: string; code?: string; hint?: string };\n      const message = pgError.message ?? String(result.error);\n      const err = new Error(message, { cause: result.error });\n      Object.assign(err, { code: pgError.code, hint: pgError.hint });\n      throw err;\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // DataProvider implementation\n  // ---------------------------------------------------------------------------\n\n  const provider: DataProvider = {\n    async getList(resource, params) {\n      let query = (client.from(resource) as SupabaseQueryBuilder).select(\n        params.select ?? \"*\",\n        { count: \"exact\" },\n      );\n\n      query = applyFilters(query, params.filters);\n\n      // Search — convert to OR of ilike.\n      if (params.search && params.search.query && params.search.fields.length > 0) {\n        const escaped = escapeIlike(params.search.query);\n        const safeFieldPattern = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;\n        const clauses = params.search.fields\n          .filter((f) => safeFieldPattern.test(f))\n          .map((f) => `${f}.ilike.%${escaped}%`)\n          .join(\",\");\n        if (clauses) {\n          query = query.or(clauses);\n        }\n      }\n\n      // Sort.\n      if (params.sort) {\n        query = query.order(params.sort.field, {\n          ascending: params.sort.order === \"asc\",\n        });\n      }\n\n      // Pagination (offset).\n      if (params.pagination) {\n        const { page, perPage } = params.pagination;\n        const from = (page - 1) * perPage;\n        const to = from + perPage - 1;\n        query = query.range(from, to);\n      }\n\n      const result = (await query) as {\n        data: unknown[];\n        error: unknown;\n        count?: number | null;\n      };\n      throwIfError(result);\n\n      return { data: result.data ?? [], total: result.count ?? 0 } as never;\n    },\n\n    async getOne(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .select(params.select ?? \"*\")\n        .eq(\"id\", params.id)\n        .single()) as { data: unknown; error: unknown };\n      throwIfError(result);\n      return { data: result.data } as never;\n    },\n\n    async getMany(resource, params) {\n      if (params.ids.length === 0) return { data: [] } as never;\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .select(\"*\")\n        .in(\"id\", params.ids)) as { data: unknown[]; error: unknown };\n      throwIfError(result);\n      return { data: result.data ?? [] } as never;\n    },\n\n    async create(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .insert(params.data as Record<string, unknown>)\n        .select(\"*\")\n        .single()) as { data: unknown; error: unknown };\n      throwIfError(result);\n      return { data: result.data } as never;\n    },\n\n    async update(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .update(params.data as Record<string, unknown>)\n        .eq(\"id\", params.id)\n        .select(\"*\")\n        .single()) as { data: unknown; error: unknown };\n      throwIfError(result);\n      return { data: result.data } as never;\n    },\n\n    async deleteOne(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .delete()\n        .eq(\"id\", params.id)\n        .select(\"id\")\n        .single()) as { data: { id: string | number } | null; error: unknown };\n      throwIfError(result);\n      if (!result.data) {\n        throw new Error(`[SupabaseProvider] Delete failed: no row found with id \"${params.id}\" in \"${resource}\"`);\n      }\n      return { data: result.data };\n    },\n  };\n\n  return provider;\n}\n"]}
+{"version":3,"sources":["../src/provider/supabase-provider.ts"],"names":[],"mappings":"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","file":"chunk-6AA4ISUA.js","sourcesContent":["import type {\n  DataProvider,\n  FilterParam,\n} from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Minimal Supabase client shape — no hard dependency on @supabase/supabase-js\n// ---------------------------------------------------------------------------\n\n/** A chainable query builder returned by `client.from(table)`. */\ninterface SupabaseQueryBuilder {\n  select(\n    columns?: string,\n    options?: { count?: \"exact\" | \"planned\" | \"estimated\" },\n  ): SupabaseQueryBuilder;\n  insert(data: Record<string, unknown> | Record<string, unknown>[]): SupabaseQueryBuilder;\n  update(data: Record<string, unknown>): SupabaseQueryBuilder;\n  delete(): SupabaseQueryBuilder;\n  eq(column: string, value: unknown): SupabaseQueryBuilder;\n  neq(column: string, value: unknown): SupabaseQueryBuilder;\n  gt(column: string, value: unknown): SupabaseQueryBuilder;\n  lt(column: string, value: unknown): SupabaseQueryBuilder;\n  gte(column: string, value: unknown): SupabaseQueryBuilder;\n  lte(column: string, value: unknown): SupabaseQueryBuilder;\n  ilike(column: string, value: string): SupabaseQueryBuilder;\n  in(column: string, values: unknown[]): SupabaseQueryBuilder;\n  is(column: string, value: null): SupabaseQueryBuilder;\n  not(column: string, operator: string, value: unknown): SupabaseQueryBuilder;\n  or(filters: string): SupabaseQueryBuilder;\n  order(column: string, options?: { ascending?: boolean }): SupabaseQueryBuilder;\n  range(from: number, to: number): SupabaseQueryBuilder;\n  single(): SupabaseQueryBuilder;\n  then: Promise<{ data: unknown; error: unknown; count?: number | null }>[\"then\"];\n}\n\n/**\n * Minimal Supabase client interface — the public shape this package has\n * always exposed for a caller that wants to type its own client or a\n * wrapper around one. Unchanged: `from()` still returns `SupabaseQueryBuilder`\n * so existing consumers that annotate a variable with this type and chain\n * off it keep type-checking exactly as before.\n */\nexport interface SupabaseClient {\n  from(table: string): SupabaseQueryBuilder;\n}\n\n/**\n * What `createSupabaseProvider` actually requires from its `client` argument\n * — deliberately looser than the public `SupabaseClient` above, and used\n * ONLY for that one parameter. A real `@supabase/supabase-js` client's\n * `from()` returns a generic, table-typed `PostgrestQueryBuilder` whose chain\n * methods don't structurally match `SupabaseQueryBuilder`, which used to\n * force callers to pass their client through `as never`. Since `unknown` is\n * a supertype of everything, any real client's `from(table: string)`\n * satisfies THIS shape without a cast; `createSupabaseProvider` narrows to\n * `SupabaseQueryBuilder` internally, once, right after each `from()` call.\n * Loosening only the input here — rather than `SupabaseClient` itself —\n * means a caller relying on `SupabaseClient`'s stricter return type for\n * their own chaining is unaffected.\n */\nexport interface SupabaseClientInput {\n  from(table: string): unknown;\n}\n\n// ---------------------------------------------------------------------------\n// Provider factory\n// ---------------------------------------------------------------------------\n\nfunction escapeIlike(value: string): string {\n  return value.replace(/[%_\\\\]/g, (char) => `\\\\${char}`);\n}\n\nexport function createSupabaseProvider(client: SupabaseClientInput): DataProvider {\n  // ---------------------------------------------------------------------------\n  // Helpers\n  // ---------------------------------------------------------------------------\n\n  function applyFilters(\n    query: SupabaseQueryBuilder,\n    filters: FilterParam[] | undefined,\n  ): SupabaseQueryBuilder {\n    if (!filters) return query;\n    for (const f of filters) {\n      switch (f.operator) {\n        case \"eq\":\n          query = query.eq(f.field, f.value);\n          break;\n        case \"neq\":\n          query = query.neq(f.field, f.value);\n          break;\n        case \"gt\":\n          query = query.gt(f.field, f.value);\n          break;\n        case \"lt\":\n          query = query.lt(f.field, f.value);\n          break;\n        case \"gte\":\n          query = query.gte(f.field, f.value);\n          break;\n        case \"lte\":\n          query = query.lte(f.field, f.value);\n          break;\n        case \"contains\":\n          query = query.ilike(f.field, `%${escapeIlike(String(f.value))}%`);\n          break;\n        case \"in\":\n          query = query.in(f.field, f.value);\n          break;\n        case \"is_null\":\n          query = query.is(f.field, null);\n          break;\n        case \"is_not_null\":\n          query = query.not(f.field, \"is\", null);\n          break;\n        case \"between\": {\n          const [lo, hi] = f.value;\n          query = query.gte(f.field, lo).lte(f.field, hi);\n          break;\n        }\n        default:\n          throw new Error(`[SupabaseProvider] Unknown filter operator \"${(f as FilterParam).operator}\"`);\n          break;\n      }\n    }\n    return query;\n  }\n\n  function throwIfError(result: { error: unknown }): void {\n    if (result.error) {\n      const pgError = result.error as { message?: string; code?: string; hint?: string };\n      const message = pgError.message ?? String(result.error);\n      const err = new Error(message, { cause: result.error });\n      Object.assign(err, { code: pgError.code, hint: pgError.hint });\n      throw err;\n    }\n  }\n\n  // ---------------------------------------------------------------------------\n  // DataProvider implementation\n  // ---------------------------------------------------------------------------\n\n  const provider: DataProvider = {\n    async getList(resource, params) {\n      let query = (client.from(resource) as SupabaseQueryBuilder).select(\n        params.select ?? \"*\",\n        { count: \"exact\" },\n      );\n\n      query = applyFilters(query, params.filters);\n\n      // Search — convert to OR of ilike.\n      if (params.search && params.search.query && params.search.fields.length > 0) {\n        const escaped = escapeIlike(params.search.query);\n        const safeFieldPattern = /^[a-zA-Z_][a-zA-Z0-9_.]*$/;\n        const clauses = params.search.fields\n          .filter((f) => safeFieldPattern.test(f))\n          .map((f) => `${f}.ilike.%${escaped}%`)\n          .join(\",\");\n        if (clauses) {\n          query = query.or(clauses);\n        }\n      }\n\n      // Sort.\n      if (params.sort) {\n        query = query.order(params.sort.field, {\n          ascending: params.sort.order === \"asc\",\n        });\n      }\n\n      // Pagination (offset).\n      if (params.pagination) {\n        const { page, perPage } = params.pagination;\n        const from = (page - 1) * perPage;\n        const to = from + perPage - 1;\n        query = query.range(from, to);\n      }\n\n      const result = (await query) as {\n        data: unknown[];\n        error: unknown;\n        count?: number | null;\n      };\n      throwIfError(result);\n\n      return { data: result.data ?? [], total: result.count ?? 0 } as never;\n    },\n\n    async getOne(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .select(params.select ?? \"*\")\n        .eq(\"id\", params.id)\n        .single()) as { data: unknown; error: unknown };\n      throwIfError(result);\n      return { data: result.data } as never;\n    },\n\n    async getMany(resource, params) {\n      if (params.ids.length === 0) return { data: [] } as never;\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .select(\"*\")\n        .in(\"id\", params.ids)) as { data: unknown[]; error: unknown };\n      throwIfError(result);\n      return { data: result.data ?? [] } as never;\n    },\n\n    async create(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .insert(params.data as Record<string, unknown>)\n        .select(\"*\")\n        .single()) as { data: unknown; error: unknown };\n      throwIfError(result);\n      return { data: result.data } as never;\n    },\n\n    async update(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .update(params.data as Record<string, unknown>)\n        .eq(\"id\", params.id)\n        .select(\"*\")\n        .single()) as { data: unknown; error: unknown };\n      throwIfError(result);\n      return { data: result.data } as never;\n    },\n\n    async deleteOne(resource, params) {\n      const result = (await (client.from(resource) as SupabaseQueryBuilder)\n        .delete()\n        .eq(\"id\", params.id)\n        .select(\"id\")\n        .single()) as { data: { id: string | number } | null; error: unknown };\n      throwIfError(result);\n      if (!result.data) {\n        throw new Error(`[SupabaseProvider] Delete failed: no row found with id \"${params.id}\" in \"${resource}\"`);\n      }\n      return { data: result.data };\n    },\n  };\n\n  return provider;\n}\n"]}

package/dist/chunk-KV2HW4G4.js

@@ -0,0 +1,41 @@
+// src/schema/keys.ts
+function keyFields(contract) {
+  return typeof contract.key === "string" ? [contract.key] : contract.key;
+}
+function keyValue(row, field) {
+  const value = row[field];
+  if (typeof value === "string" || typeof value === "number") return value;
+  if (typeof value === "bigint" || typeof value === "boolean") return String(value);
+  throw new Error(
+    `Record key field "${field}" is ${value === null ? "null" : typeof value}; a key value must be a string or a number.`
+  );
+}
+function encodeRecordKey(contract, row) {
+  const fields = keyFields(contract);
+  if (fields.length === 0) throw new Error("This resource has no key, so its rows cannot be addressed.");
+  if (fields.length === 1) return keyValue(row, fields[0]);
+  return JSON.stringify(fields.map((field) => keyValue(row, field)));
+}
+function decodeRecordKey(contract, id) {
+  const fields = keyFields(contract);
+  if (fields.length === 0) throw new Error("This resource has no key, so its rows cannot be addressed.");
+  if (fields.length === 1) return { [fields[0]]: id };
+  let parsed;
+  try {
+    parsed = JSON.parse(String(id));
+  } catch {
+    throw new Error(`"${String(id)}" is not a composite key for (${fields.join(", ")}).`);
+  }
+  if (!Array.isArray(parsed) || parsed.length !== fields.length || !parsed.every((v) => typeof v === "string" || typeof v === "number")) {
+    throw new Error(`"${String(id)}" is not a composite key for (${fields.join(", ")}).`);
+  }
+  const out = {};
+  fields.forEach((field, i) => {
+    out[field] = parsed[i];
+  });
+  return out;
+}
+
+export { decodeRecordKey, encodeRecordKey, keyFields };
+//# sourceMappingURL=chunk-KV2HW4G4.js.map
+//# sourceMappingURL=chunk-KV2HW4G4.js.map

package/dist/chunk-KV2HW4G4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema/keys.ts"],"names":[],"mappings":";AAYO,SAAS,UAAU,QAAA,EAA4D;AACpF,EAAA,OAAO,OAAO,SAAS,GAAA,KAAQ,QAAA,GAAW,CAAC,QAAA,CAAS,GAAG,IAAI,QAAA,CAAS,GAAA;AACtE;AAEA,SAAS,QAAA,CAAS,KAAc,KAAA,EAAgC;AAC9D,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAK,CAAA;AACvB,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,OAAO,KAAA,KAAU,UAAU,OAAO,KAAA;AACnE,EAAA,IAAI,OAAO,UAAU,QAAA,IAAY,OAAO,UAAU,SAAA,EAAW,OAAO,OAAO,KAAK,CAAA;AAChF,EAAA,MAAM,IAAI,KAAA;AAAA,IACR,qBAAqB,KAAK,CAAA,KAAA,EAAQ,UAAU,IAAA,GAAO,MAAA,GAAS,OAAO,KAAK,CAAA,2CAAA;AAAA,GAE1E;AACF;AASO,SAAS,eAAA,CACd,UACA,GAAA,EACY;AACZ,EAAA,MAAM,MAAA,GAAS,UAAU,QAAQ,CAAA;AACjC,EAAA,IAAI,OAAO,MAAA,KAAW,CAAA,EAAG,MAAM,IAAI,MAAM,4DAA4D,CAAA;AACrG,EAAA,IAAI,MAAA,CAAO,WAAW,CAAA,EAAG,OAAO,SAAS,GAAA,EAAK,MAAA,CAAO,CAAC,CAAE,CAAA;AACxD,EAAA,OAAO,IAAA,CAAK,SAAA,CAAU,MAAA,CAAO,GAAA,CAAI,CAAC,UAAU,QAAA,CAAS,GAAA,EAAK,KAAK,CAAC,CAAC,CAAA;AACnE;AAQO,SAAS,eAAA,CACd,UACA,EAAA,EACiC;AACjC,EAAA,MAAM,MAAA,GAAS,UAAU,QAAQ,CAAA;AACjC,EAAA,IAAI,OAAO,MAAA,KAAW,CAAA,EAAG,MAAM,IAAI,MAAM,4DAA4D,CAAA;AACrG,EAAA,IAAI,MAAA,CAAO,MAAA,KAAW,CAAA,EAAG,OAAO,EAAE,CAAC,MAAA,CAAO,CAAC,CAAE,GAAG,EAAA,EAAG;AAEnD,EAAA,IAAI,MAAA;AACJ,EAAA,IAAI;AACF,IAAA,MAAA,GAAS,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,EAAE,CAAC,CAAA;AAAA,EAChC,CAAA,CAAA,MAAQ;AACN,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,CAAA,EAAI,MAAA,CAAO,EAAE,CAAC,CAAA,8BAAA,EAAiC,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,EAAA,CAAI,CAAA;AAAA,EACtF;AACA,EAAA,IACE,CAAC,MAAM,OAAA,CAAQ,MAAM,KACrB,MAAA,CAAO,MAAA,KAAW,OAAO,MAAA,IACzB,CAAC,OAAO,KAAA,CAAM,CAAC,MAAM,OAAO,CAAA,KAAM,YAAY,OAAO,CAAA,KAAM,QAAQ,CAAA,EACnE;AACA,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,CAAA,EAAI,MAAA,CAAO,EAAE,CAAC,CAAA,8BAAA,EAAiC,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA,EAAA,CAAI,CAAA;AAAA,EACtF;AACA,EAAA,MAAM,MAAuC,EAAC;AAC9C,EAAA,MAAA,CAAO,OAAA,CAAQ,CAAC,KAAA,EAAO,CAAA,KAAM;AAC3B,IAAA,GAAA,CAAI,KAAK,CAAA,GAAI,MAAA,CAAO,CAAC,CAAA;AAAA,EACvB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT","file":"chunk-KV2HW4G4.js","sourcesContent":["// ---------------------------------------------------------------------------\n// Record identity for single and composite keys (DATA-STUDIO.md decision 13)\n//\n// `DataProvider` methods take one `Identifier`. A composite key travels\n// through that same slot as a canonical string, so every existing provider\n// signature stays as it is and a junction table still has one id per row.\n// ---------------------------------------------------------------------------\n\nimport type { Identifier } from \"../provider/types\";\nimport type { DataRow, ResourceContract } from \"./types\";\n\n/** The key of a contract as a list, whichever form `key` was declared in. */\nexport function keyFields(contract: Pick<ResourceContract, \"key\">): readonly string[] {\n  return typeof contract.key === \"string\" ? [contract.key] : contract.key;\n}\n\nfunction keyValue(row: DataRow, field: string): string | number {\n  const value = row[field];\n  if (typeof value === \"string\" || typeof value === \"number\") return value;\n  if (typeof value === \"bigint\" || typeof value === \"boolean\") return String(value);\n  throw new Error(\n    `Record key field \"${field}\" is ${value === null ? \"null\" : typeof value}; ` +\n      \"a key value must be a string or a number.\",\n  );\n}\n\n/**\n * One `Identifier` for a row.\n *\n * A single-field key returns the raw value, so `id`-keyed resources look\n * exactly as they always have. A composite key returns a JSON array of the\n * values in key order, e.g. `'[\"c-1\",\"u-7\"]'`.\n */\nexport function encodeRecordKey(\n  contract: Pick<ResourceContract, \"key\">,\n  row: DataRow,\n): Identifier {\n  const fields = keyFields(contract);\n  if (fields.length === 0) throw new Error(\"This resource has no key, so its rows cannot be addressed.\");\n  if (fields.length === 1) return keyValue(row, fields[0]!);\n  return JSON.stringify(fields.map((field) => keyValue(row, field)));\n}\n\n/**\n * The inverse of {@link encodeRecordKey}: field name → value.\n *\n * Throws on an id that does not fit the key, rather than guessing, because a\n * guessed key addresses the wrong row.\n */\nexport function decodeRecordKey(\n  contract: Pick<ResourceContract, \"key\">,\n  id: Identifier,\n): Record<string, string | number> {\n  const fields = keyFields(contract);\n  if (fields.length === 0) throw new Error(\"This resource has no key, so its rows cannot be addressed.\");\n  if (fields.length === 1) return { [fields[0]!]: id };\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(String(id));\n  } catch {\n    throw new Error(`\"${String(id)}\" is not a composite key for (${fields.join(\", \")}).`);\n  }\n  if (\n    !Array.isArray(parsed) ||\n    parsed.length !== fields.length ||\n    !parsed.every((v) => typeof v === \"string\" || typeof v === \"number\")\n  ) {\n    throw new Error(`\"${String(id)}\" is not a composite key for (${fields.join(\", \")}).`);\n  }\n  const out: Record<string, string | number> = {};\n  fields.forEach((field, i) => {\n    out[field] = parsed[i] as string | number;\n  });\n  return out;\n}\n"]}

package/dist/hooks/index.d.ts

@@ -3,6 +3,6 @@ export { UseOneOptions, useOne } from './use-one.js';
 export { UseResourceFormOptions, UseResourceFormReturn, buildArrayItemDefaults, useResourceForm } from './use-resource-form.js';
 export { UseWizardReturn, WizardStep, useWizard } from './use-wizard.js';
 import '@tanstack/react-query';
-import '../types-BzcZrTjl.js';
-import 'react-hook-form';
+import '../types-DUbRb8qV.js';
 import '../form-types.js';
+import 'react-hook-form';

package/dist/hooks/use-one.d.ts

@@ -1,5 +1,6 @@
 import { UseQueryResult } from '@tanstack/react-query';
-import { B as BaseRecord, I as Identifier } from '../types-BzcZrTjl.js';
+import { B as BaseRecord, I as Identifier } from '../types-DUbRb8qV.js';
+import '../form-types.js';
 
 interface UseOneOptions {
     /** Supabase select/join syntax, e.g. "*, author:profiles(name)". */

package/dist/hooks/use-resource.d.ts

@@ -1,5 +1,6 @@
 import { UseQueryResult, UseMutationResult } from '@tanstack/react-query';
-import { h as SortParam, F as FilterParam, g as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-BzcZrTjl.js';
+import { z as SortParam, k as FilterParam, p as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-DUbRb8qV.js';
+import '../form-types.js';
 
 interface UseResourceOptions<T> {
     defaultSort?: SortParam;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { A as ArrayFilter, B as BaseRecord, C as CreateParams, a as CreateResult, D as DataProvider, b as DeleteParams, c as DeleteResult, F as FilterParam, G as GetManyParams, d as GetManyResult, e as GetOneParams, f as GetOneResult, I as Identifier, L as ListParams, g as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, S as ScalarFilter, h as SortParam, U as UpdateParams, i as UpdateResult } from './types-BzcZrTjl.js';
+export { A as ArrayFilter, a as AuditEntry, B as BaseRecord, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, D as DataProvider, e as DataRow, f as DeleteParams, g as DeleteResult, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, I as Identifier, o as ImportParams, L as ListParams, p as ListResult, N as NullFilter, P as PaginationParam, q as ProviderCapabilities, R as RangeFilter, r as RecordComment, s as ResourceAccess, t as ResourceContract, u as ResourceRelation, v as ResourceSchema, w as ResourceSummary, x as RowAction, y as RowFailure, S as ScalarFilter, z as SortParam, E as StorageType, U as UpdateParams, J as UpdateResult, V as VersionField } from './types-DUbRb8qV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-aYToY3dK.js';
 export { DataProviderRoot, DataProviderRootProps, GenesisProvider, GenesisProviderProps, MockProviderOptions, SupabaseClient, SupabaseClientInput, createMockProvider, createSupabaseProvider, useDataProvider, useStorage } from './provider/index.js';
 export { S as StorageAdapter } from './types-DKcxHXxq.js';
 export { createLocalStorageAdapter, createMemoryStorageAdapter, createNoopStorageAdapter } from './storage/index.js';
@@ -6,7 +7,8 @@ export { UseResourceOptions, UseResourceReturn, useResource } from './hooks/use-
 export { UseOneOptions, useOne } from './hooks/use-one.js';
 export { UseResourceFormOptions, UseResourceFormReturn, buildArrayItemDefaults, useResourceForm } from './hooks/use-resource-form.js';
 export { UseWizardReturn, WizardStep, useWizard } from './hooks/use-wizard.js';
-export { FieldType, ResourceFormFieldDef, SelectOption } from './form-types.js';
+export { FieldType, ResourceFormFieldDef, SelectOption, FieldType as WidgetHint } from './form-types.js';
+export { decodeRecordKey, encodeRecordKey, keyFields } from './schema/index.js';
 export { titleCase } from './utils.js';
 import 'react';
 import '@tanstack/react-query';

package/dist/index.js

@@ -1,5 +1,7 @@
-export { createSupabaseProvider } from './chunk-RKR5K7Q3.js';
+export { createSupabaseProvider } from './chunk-6AA4ISUA.js';
 import './chunk-XCX2TRBL.js';
+export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
+export { DataWriteError, isDataWriteError } from './chunk-4W4W7F4I.js';
 import './chunk-65SXNHWE.js';
 import './chunk-EL7YGOTY.js';
 export { buildArrayItemDefaults, useResourceForm } from './chunk-5FTUB2M6.js';

package/dist/provider/index.d.ts

@@ -1,8 +1,10 @@
-import { D as DataProvider } from '../types-BzcZrTjl.js';
-export { A as ArrayFilter, B as BaseRecord, C as CreateParams, a as CreateResult, b as DeleteParams, c as DeleteResult, F as FilterParam, G as GetManyParams, d as GetManyResult, e as GetOneParams, f as GetOneResult, I as Identifier, L as ListParams, g as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, S as ScalarFilter, h as SortParam, U as UpdateParams, i as UpdateResult } from '../types-BzcZrTjl.js';
+import { D as DataProvider } from '../types-DUbRb8qV.js';
+export { A as ArrayFilter, B as BaseRecord, b as BulkChange, c as BulkResult, C as CreateParams, d as CreateResult, f as DeleteParams, g as DeleteResult, k as FilterParam, G as GetManyParams, l as GetManyResult, m as GetOneParams, n as GetOneResult, H as HistoryParams, I as Identifier, o as ImportParams, L as ListParams, p as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, y as RowFailure, S as ScalarFilter, z as SortParam, U as UpdateParams, J as UpdateResult } from '../types-DUbRb8qV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-aYToY3dK.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
 import { S as StorageAdapter } from '../types-DKcxHXxq.js';
+import '../form-types.js';
 
 interface MockProviderOptions {
     /** Simulated latency in ms (default 0). */

package/dist/provider/index.js

@@ -1,4 +1,5 @@
-export { createSupabaseProvider } from '../chunk-RKR5K7Q3.js';
+export { createSupabaseProvider } from '../chunk-6AA4ISUA.js';
+export { DataWriteError, isDataWriteError } from '../chunk-4W4W7F4I.js';
 export { DataProviderRoot, GenesisProvider, createMockProvider, useDataProvider, useStorage } from '../chunk-6V2TIN3G.js';
 import '../chunk-ZYJUEJ4Z.js';
 //# sourceMappingURL=index.js.map

package/dist/schema/index.d.ts

@@ -0,0 +1,24 @@
+import { t as ResourceContract, I as Identifier, e as DataRow } from '../types-DUbRb8qV.js';
+export { a as AuditEntry, F as FieldPermissions, h as FieldReference, i as FieldSchema, j as FilterOperator, q as ProviderCapabilities, r as RecordComment, s as ResourceAccess, u as ResourceRelation, v as ResourceSchema, w as ResourceSummary, x as RowAction, E as StorageType, V as VersionField } from '../types-DUbRb8qV.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-aYToY3dK.js';
+export { FieldType as WidgetHint } from '../form-types.js';
+
+/** The key of a contract as a list, whichever form `key` was declared in. */
+declare function keyFields(contract: Pick<ResourceContract, "key">): readonly string[];
+/**
+ * One `Identifier` for a row.
+ *
+ * A single-field key returns the raw value, so `id`-keyed resources look
+ * exactly as they always have. A composite key returns a JSON array of the
+ * values in key order, e.g. `'["c-1","u-7"]'`.
+ */
+declare function encodeRecordKey(contract: Pick<ResourceContract, "key">, row: DataRow): Identifier;
+/**
+ * The inverse of {@link encodeRecordKey}: field name → value.
+ *
+ * Throws on an id that does not fit the key, rather than guessing, because a
+ * guessed key addresses the wrong row.
+ */
+declare function decodeRecordKey(contract: Pick<ResourceContract, "key">, id: Identifier): Record<string, string | number>;
+
+export { DataRow, ResourceContract, decodeRecordKey, encodeRecordKey, keyFields };

package/dist/schema/index.js

@@ -0,0 +1,4 @@
+export { decodeRecordKey, encodeRecordKey, keyFields } from '../chunk-KV2HW4G4.js';
+export { DataWriteError, isDataWriteError } from '../chunk-4W4W7F4I.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/schema/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/types-DUbRb8qV.d.ts

@@ -0,0 +1,516 @@
+import { FieldType } from './form-types.js';
+
+/**
+ * Portable storage type of a field — what kind of value the store holds,
+ * independent of how a UI should edit it. The exact native type, when the
+ * store reports one, is on {@link FieldSchema.dbType}.
+ *
+ * Exactly the six types the switchboard shipped as `FieldType`, so existing
+ * exhaustive maps over it keep compiling. Finer distinctions (date versus
+ * timestamp, enum, uuid) live in `dbType` and `widget`, not here.
+ */
+type StorageType = "string" | "number" | "boolean" | "datetime" | "json" | "relation";
+/** A canonical, provider-agnostic row. Keys are field names from the schema. */
+type DataRow = Record<string, unknown>;
+/**
+ * What the CURRENT user may do with one field. Reported by a provider's
+ * `describe()`; never inferred in the browser.
+ *
+ * `read: false` means the value is never sent to this user, so the column
+ * must not render at all (an answer key, a payout amount). `update: false`
+ * with `read: true` renders the column read-only.
+ */
+interface FieldPermissions {
+    readonly read: boolean;
+    readonly update: boolean;
+    /** Why `update` (or `read`) is false, in one human sentence. */
+    readonly reason?: string;
+}
+/** A foreign-key style link from this field to another resource's field. */
+interface FieldReference {
+    readonly resource: string;
+    readonly field: string;
+}
+interface FieldSchema {
+    /** Canonical field name in the resource's shape (provider-agnostic). */
+    readonly name: string;
+    /** Portable storage type. */
+    readonly type: StorageType;
+    /** True when a row may omit this field. */
+    readonly optional?: boolean;
+    /**
+     * True when the field holds an ORDERED LIST of `type` values (e.g. a
+     * multi-relation like `deps`/`serves`). Promotion emits a Postgres ARRAY
+     * column (`<base>[]`) instead of a lossy scalar, so the cardinality survives
+     * L1→L3 (CMT-1742-014).
+     */
+    readonly array?: boolean;
+    /** Human note (surfaces in describe()/drift reports). */
+    readonly description?: string;
+    /** Human label, e.g. "Date of birth". Absent means a UI derives one from `name`. */
+    readonly label?: string;
+    /** The store's exact type, e.g. `timestamp with time zone` or `public.status`. */
+    readonly dbType?: string;
+    /** Which control fits this field. A hint: a UI may still choose another. */
+    readonly widget?: FieldType;
+    /** True when the store accepts null for this field. */
+    readonly nullable?: boolean;
+    /** True when the store fills the field itself on insert. */
+    readonly hasDefault?: boolean;
+    /** True when the store computes the field; it is never written. */
+    readonly generated?: boolean;
+    /** Allowed values, for enum-like fields. */
+    readonly enumValues?: readonly string[];
+    /** The resource and field this one points at, when it is a link. */
+    readonly references?: FieldReference;
+    /** The current user's rights on this field, when a provider reports them. */
+    readonly permissions?: FieldPermissions;
+}
+/**
+ * One declaration of a resource: its fields and its identity.
+ *
+ * `key` names the identity field, or several for a composite key (a junction
+ * table keyed on `(coach_id, client_id)`). Use {@link keyFields} to read it as
+ * a list without caring which form it took.
+ */
+interface ResourceContract<Row extends DataRow = DataRow> {
+    /** Resource name the app addresses, e.g. "tickets" or "public.tickets". */
+    readonly name: string;
+    /**
+     * Identity field name, or names for a composite key, in key order.
+     *
+     * Typed `string` (not `keyof Row & string`) on purpose: `keyof Row` is a
+     * dependent type that TypeScript checks contravariantly, which would make
+     * `ResourceContract<WorkCycleRow>` non-assignable to the erased
+     * `ResourceContract<DataRow>` that generic consumers accept. The key is
+     * validated against the field schema at runtime instead.
+     */
+    readonly key: string | readonly string[];
+    readonly fields: readonly FieldSchema[];
+    /** Optional doc string. */
+    readonly description?: string;
+    /** Phantom marker so `Row` is inferable from a contract. */
+    readonly __row?: Row;
+}
+/** What the current user may do with a whole resource. */
+interface ResourceAccess {
+    readonly read: boolean;
+    /** True when at least one field can be updated on rows this user can see. */
+    readonly update: boolean;
+    /** Why `update` (or `read`) is false, in one human sentence. */
+    readonly reason?: string;
+    /** True when this user may add rows. Absent means the provider doesn't say. */
+    readonly create?: boolean;
+    /** True when this user may delete rows they can see. */
+    readonly delete?: boolean;
+    /** True when this user may read a row's audit history. */
+    readonly history?: boolean;
+    /** True when this user may read and add comments on rows they can see. */
+    readonly comment?: boolean;
+    /** Why `create`, `delete`, `history` or `comment` is false, in one human sentence each. */
+    readonly reasons?: {
+        readonly create?: string;
+        readonly delete?: string;
+        readonly history?: string;
+        readonly comment?: string;
+    };
+}
+/**
+ * How another resource relates to this one, from the store's foreign keys.
+ *
+ * - `one`: a field on THIS resource points at one row of `resource`.
+ * - `many`: rows of `resource` point at this row through their `field`.
+ * - `through`: many rows of `resource`, linked by the junction resource in
+ *   `through` (a table whose key is two foreign keys).
+ */
+interface ResourceRelation {
+    readonly kind: "one" | "many" | "through";
+    /** The related resource. */
+    readonly resource: string;
+    /**
+     * `one`: the field on this resource. `many`: the field on `resource` that
+     * holds this row's key. `through`: the junction's field holding this row's key.
+     */
+    readonly field: string;
+    /** For `through`: the junction resource, and its field pointing at `resource`. */
+    readonly through?: {
+        readonly resource: string;
+        readonly otherField: string;
+    };
+    /** True when at most one related row can exist (a unique foreign key). */
+    readonly unique?: boolean;
+}
+/**
+ * The column a provider checks on every update so an edit never silently
+ * overwrites someone else's. Only reported when the store itself advances it
+ * on every successful update (a trigger such as `moddatetime`), because a
+ * column nothing advances detects nothing.
+ */
+interface VersionField {
+    /**
+     * The field holding the version. A provider with versioned writes returns
+     * each row with its exact version token in this field, as a string, and
+     * `expectedVersion` echoes `String(row[field])` back unchanged.
+     */
+    readonly field: string;
+    /**
+     * `row`: no column tracks versions, so the token is a fingerprint of the
+     * row's values, and `field` is a name the provider adds to each record
+     * (it is not one of the resource's fields).
+     */
+    readonly kind: "integer" | "timestamp" | "row";
+}
+/**
+ * A resource as `describe()` reports it for the CURRENT user: the contract,
+ * plus what this user may do. Fields the user may not read are left out
+ * entirely, not marked hidden.
+ */
+interface ResourceSchema<Row extends DataRow = DataRow> extends ResourceContract<Row> {
+    /** Human label, e.g. "Clients". */
+    readonly label?: string;
+    readonly access: ResourceAccess;
+    /** Present only when writes can be version-checked. */
+    readonly version?: VersionField;
+    /** The field that best names a row to a person (a name or title), for links and pickers. */
+    readonly labelField?: string;
+    /** Resources this one links to or is linked from. Only ones this user may see. */
+    readonly relations?: readonly ResourceRelation[];
+    /** Fields the user may set when creating a row. Absent when creating isn't allowed. */
+    readonly createFields?: readonly string[];
+    /** Row actions this user may run: each calls the app's own function on one row. */
+    readonly actions?: readonly RowAction[];
+}
+/** A named operation on one row, carried out by the app's own database function. */
+interface RowAction {
+    readonly name: string;
+    readonly label: string;
+    /** Ask before running, with this question. */
+    readonly confirm?: string;
+    /** One sentence on what it does. */
+    readonly description?: string;
+}
+/** A comment on a record. */
+interface RecordComment {
+    readonly id: string;
+    /** The signed-in user who wrote it (the token's `sub`). */
+    readonly author: string;
+    readonly body: string;
+    /** ISO 8601, as the store recorded it. */
+    readonly createdAt: string;
+}
+/** One entry of `listResources()`: enough to draw a sidebar. */
+interface ResourceSummary {
+    readonly name: string;
+    readonly label?: string;
+    readonly description?: string;
+    readonly access: ResourceAccess;
+}
+/** Filter operators a provider may support. Mirrors `FilterParam["operator"]`. */
+type FilterOperator = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains" | "in" | "between" | "is_null" | "is_not_null";
+/**
+ * What a provider can do. A UI hides any control the provider cannot serve,
+ * instead of letting it error (DATA-STUDIO.md decision 9).
+ */
+interface ProviderCapabilities {
+    /** Server-side text search across fields. */
+    readonly search: boolean;
+    /** Server-side sort. */
+    readonly sort: boolean;
+    /** Server-side filter operators. Empty means no server filtering. */
+    readonly filterOperators: readonly FilterOperator[];
+    /** `updateMany` / `deleteMany` in one transaction. */
+    readonly bulkWrites: boolean;
+    /** Updates honour `expectedVersion` and reject stale writes. */
+    readonly versionedWrites: boolean;
+    /** Records may be keyed by more than one field. */
+    readonly compositeKeys: boolean;
+    /** Server-side sort by several fields at once (`ListParams.sorts`). */
+    readonly multiSort?: boolean;
+    /** `create` and `deleteOne` are served, subject to each resource's access. */
+    readonly create?: boolean;
+    readonly delete?: boolean;
+    /** `history` is served, subject to each resource's access. */
+    readonly history?: boolean;
+    /** `importRows` is served, with a dry run. */
+    readonly import?: boolean;
+    /** `undo` is served. */
+    readonly undo?: boolean;
+    /** `runAction` is served. */
+    readonly actions?: boolean;
+    /** `comments` and `addComment` are served. */
+    readonly comments?: boolean;
+}
+/** One audit record, as committed alongside the edit it describes. */
+interface AuditEntry {
+    readonly id: string;
+    /** ISO 8601 timestamp, as the store recorded it. */
+    readonly occurredAt: string;
+    /** The signed-in user who made the edit (the token's `sub`). */
+    readonly actor: string | null;
+    readonly resource: string;
+    /** The record's key, field name → value. */
+    readonly key: DataRow;
+    /** `run` is a row action; `rowAction` names it. */
+    readonly action: "create" | "update" | "delete" | "run";
+    /** For `run`: which row action. */
+    readonly rowAction?: string;
+    /** Values of the changed fields before the edit. */
+    readonly before: DataRow | null;
+    /** Values of the changed fields after the edit. */
+    readonly after: DataRow | null;
+}
+
+/** Record identifier — supports both string UUIDs and numeric auto-increment IDs. */
+type Identifier = string | number;
+/** Base record type — all resources must have an id. */
+type BaseRecord = {
+    id: Identifier;
+    [key: string]: unknown;
+};
+/** Pagination parameters (offset-based, with optional cursor for future use). */
+interface PaginationParam {
+    page: number;
+    perPage: number;
+    cursor?: string;
+}
+/** Sort direction for a single field. */
+interface SortParam {
+    field: string;
+    order: "asc" | "desc";
+}
+/**
+ * Filter expressions — discriminated union by operator.
+ * Filters are AND-ed together in queries.
+ */
+/** Operators that compare a field against a single scalar value. */
+interface ScalarFilter {
+    field: string;
+    operator: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
+    value: string | number | boolean;
+}
+/** Operator that checks field membership in a list. */
+interface ArrayFilter {
+    field: string;
+    operator: "in";
+    value: (string | number | boolean)[];
+}
+/** Operator that checks field is within a range. */
+interface RangeFilter {
+    field: string;
+    operator: "between";
+    value: [string | number, string | number];
+}
+/** Operators that check for null/non-null — no value needed. */
+interface NullFilter {
+    field: string;
+    operator: "is_null" | "is_not_null";
+}
+type FilterParam = ScalarFilter | ArrayFilter | RangeFilter | NullFilter;
+/** Parameters for `getList`. */
+interface ListParams {
+    pagination?: PaginationParam;
+    sort?: SortParam;
+    /**
+     * Sort by several fields, first one first. Wins over `sort` on a provider
+     * whose capabilities report `multiSort`; others use only `sort`.
+     */
+    sorts?: SortParam[];
+    filters?: FilterParam[];
+    /** Supabase select syntax, e.g. "*, author:profiles(name)". Mock provider ignores this. */
+    select?: string;
+    /** Multi-field text search (case-insensitive). */
+    search?: {
+        query: string;
+        fields: string[];
+    };
+}
+/** Result of `getList`. */
+interface ListResult<T> {
+    data: T[];
+    total: number;
+}
+/** Parameters for `getOne`. */
+interface GetOneParams {
+    id: Identifier;
+    /** Supabase select syntax, e.g. "*, author:profiles(name)". Defaults to "*". */
+    select?: string;
+}
+/** Result of `getOne`. */
+interface GetOneResult<T> {
+    data: T;
+}
+/** Parameters for `getMany`. */
+interface GetManyParams {
+    ids: Identifier[];
+}
+/** Result of `getMany`. */
+interface GetManyResult<T> {
+    data: T[];
+}
+/** Parameters for `create`. */
+interface CreateParams<T> {
+    data: Partial<T>;
+}
+/** Result of `create`. */
+interface CreateResult<T> {
+    data: T;
+    /** The audit entry committed with the new row, from a provider that audits. */
+    audit?: AuditEntry;
+}
+/** Parameters for `update`. */
+interface UpdateParams<T> {
+    /**
+     * The record's identifier. For a composite key, the canonical string from
+     * `encodeRecordKey` (`@marktiderman/genesis-core/schema`).
+     */
+    id: Identifier;
+    data: Partial<T>;
+    /**
+     * The version token the caller read the row at. A provider that reports
+     * `versionedWrites` in its capabilities rejects the update with a
+     * `DataWriteError` (`conflict`) when the row has moved on since, instead of
+     * overwriting someone else's edit. Providers without versioned writes
+     * ignore it.
+     */
+    expectedVersion?: string | null;
+}
+/** Result of `update`. */
+interface UpdateResult<T> {
+    data: T;
+    /** The row's new version token, from a provider with versioned writes. */
+    version?: string | null;
+    /** The audit entry committed with the edit, from a provider that audits. */
+    audit?: AuditEntry;
+}
+/** Parameters for `deleteOne`. */
+interface DeleteParams {
+    id: Identifier;
+    /** The version token the row was read at; see `UpdateParams.expectedVersion`. */
+    expectedVersion?: string | null;
+}
+/** Result of `deleteOne`. */
+interface DeleteResult {
+    data: {
+        id: Identifier;
+    };
+    /** The audit entry committed with the deletion, from a provider that audits. */
+    audit?: AuditEntry;
+}
+/** One row's change in a bulk update. */
+interface BulkChange {
+    id: Identifier;
+    data: Record<string, unknown>;
+    /** The version token the row was read at. */
+    expectedVersion?: string | null;
+}
+/** Why one row of a bulk write or import didn't go through. */
+interface RowFailure {
+    /** The row's position in the request, from 0. */
+    index: number;
+    id?: Identifier;
+    outcome: string;
+    message: string;
+}
+/** Result of a bulk write: every row changed, or none did. */
+interface BulkResult {
+    /** Rows changed; always the number requested when `ok`. */
+    count: number;
+    ok: boolean;
+    /** Present when `ok` is false: every row that failed, so the caller can fix them all at once. */
+    failures?: RowFailure[];
+    /** One audit entry per row changed. */
+    audit?: AuditEntry[];
+}
+/** Parameters for `importRows`. */
+interface ImportParams {
+    rows: Record<string, unknown>[];
+    /** Check every row against the database and change nothing. */
+    dryRun: boolean;
+}
+/** Parameters for `history`. */
+interface HistoryParams {
+    id: Identifier;
+    /** Most recent first; default and maximum are the provider's. */
+    limit?: number;
+}
+interface DataProvider {
+    getList<T extends BaseRecord = BaseRecord>(resource: string, params: ListParams): Promise<ListResult<T>>;
+    getOne<T extends BaseRecord = BaseRecord>(resource: string, params: GetOneParams): Promise<GetOneResult<T>>;
+    getMany<T extends BaseRecord = BaseRecord>(resource: string, params: GetManyParams): Promise<GetManyResult<T>>;
+    create<T extends BaseRecord = BaseRecord>(resource: string, params: CreateParams<T>): Promise<CreateResult<T>>;
+    update<T extends BaseRecord = BaseRecord>(resource: string, params: UpdateParams<T>): Promise<UpdateResult<T>>;
+    deleteOne(resource: string, params: DeleteParams): Promise<DeleteResult>;
+    /**
+     * The resource's real shape for the CURRENT user: fields, key, version
+     * field, and per-field read and update rights. Fields the user may not read
+     * are omitted entirely.
+     */
+    describe?(resource: string): Promise<ResourceSchema>;
+    /** Every resource this user may see, for a sidebar or a picker. */
+    listResources?(): Promise<ResourceSummary[]>;
+    /**
+     * What this provider can do, optionally for one resource. A UI hides the
+     * controls a provider cannot serve instead of letting them error.
+     */
+    capabilities?(resource?: string): Promise<ProviderCapabilities>;
+    /**
+     * A record's audit history, most recent first, limited to the fields this
+     * user may read.
+     */
+    history?(resource: string, params: HistoryParams): Promise<AuditEntry[]>;
+    /**
+     * Update many rows in ONE transaction. All of them change or none do: a
+     * single conflict, refusal or invalid value rolls back the rest, and the
+     * result lists every row that failed.
+     */
+    updateMany?(resource: string, params: {
+        changes: BulkChange[];
+    }): Promise<BulkResult>;
+    /** Delete many rows in one transaction, all or none, each at its version. */
+    deleteMany?(resource: string, params: {
+        items: {
+            id: Identifier;
+            expectedVersion?: string | null;
+        }[];
+    }): Promise<BulkResult>;
+    /**
+     * Add rows from an import. With `dryRun`, every row is tried against the
+     * database and nothing is kept, so the result lists every row that would
+     * fail; without it, all rows are added in one transaction or none are.
+     */
+    importRows?(resource: string, params: ImportParams): Promise<BulkResult>;
+    /**
+     * Undo one audited change with a compensating write: put the changed
+     * fields back, remove an added row, or restore a deleted one. Refused when
+     * the row has changed since.
+     */
+    undo?(resource: string, params: {
+        auditId: string;
+    }): Promise<{
+        audit?: AuditEntry;
+    }>;
+    /**
+     * Run one of the resource's row actions (`ResourceSchema.actions`) on a
+     * row, at the version it was read. The app's function does the work; the
+     * row's change is audited.
+     */
+    runAction?(resource: string, params: {
+        id: Identifier;
+        action: string;
+        expectedVersion?: string | null;
+    }): Promise<{
+        data: Record<string, unknown> | null;
+        audit?: AuditEntry;
+    }>;
+    /** A record's comments, oldest first. */
+    comments?(resource: string, params: {
+        id: Identifier;
+    }): Promise<RecordComment[]>;
+    /** Add a comment to a record, as the signed-in user. */
+    addComment?(resource: string, params: {
+        id: Identifier;
+        body: string;
+    }): Promise<RecordComment>;
+}
+
+export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, StorageType as E, FieldPermissions as F, GetManyParams as G, HistoryParams as H, Identifier as I, UpdateResult as J, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, VersionField as V, AuditEntry as a, BulkChange as b, BulkResult as c, CreateResult as d, DataRow as e, DeleteParams as f, DeleteResult as g, FieldReference as h, FieldSchema as i, FilterOperator as j, FilterParam as k, GetManyResult as l, GetOneParams as m, GetOneResult as n, ImportParams as o, ListResult as p, ProviderCapabilities as q, RecordComment as r, ResourceAccess as s, ResourceContract as t, ResourceRelation as u, ResourceSchema as v, ResourceSummary as w, RowAction as x, RowFailure as y, SortParam as z };

package/dist/write-outcome-aYToY3dK.d.ts

@@ -0,0 +1,38 @@
+import { e as DataRow } from './types-DUbRb8qV.js';
+
+/**
+ * - `conflict`: someone else changed the row since it was read. `current`
+ *   carries the row as it is now.
+ * - `gone`: the row was deleted, or is no longer visible to this user. The
+ *   two cannot be told apart without a privileged look at the table, which
+ *   would show this user a fact about a row they cannot see.
+ * - `forbidden`: the row is visible and unchanged, but the app or the
+ *   database does not let this user make this change. Only reported when
+ *   that is proven, never assumed from "zero rows changed".
+ * - `invalid`: the store rejected the value (type, constraint, not-null).
+ * - `audit_failed`: the audit entry could not be written, so the edit was
+ *   rolled back with it.
+ * - `unauthenticated`: no signed-in user, or the session expired.
+ * - `error`: anything else. The edit did not commit.
+ */
+type WriteOutcome = "conflict" | "gone" | "forbidden" | "invalid" | "audit_failed" | "unauthenticated" | "error";
+interface DataWriteErrorOptions {
+    /** The row as it is now, for a `conflict`. Only fields the user may read. */
+    current?: DataRow;
+    /** The row's current version token, for a `conflict`. */
+    currentVersion?: string | null;
+}
+/** Thrown by a provider when a write did not commit. */
+declare class DataWriteError extends Error {
+    readonly outcome: WriteOutcome;
+    readonly current?: DataRow;
+    readonly currentVersion?: string | null;
+    constructor(outcome: WriteOutcome, message: string, options?: DataWriteErrorOptions);
+}
+/**
+ * `instanceof` fails when two copies of this package are installed, so check
+ * the shape instead.
+ */
+declare function isDataWriteError(error: unknown): error is DataWriteError;
+
+export { DataWriteError as D, type WriteOutcome as W, type DataWriteErrorOptions as a, isDataWriteError as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marktiderman/genesis-core",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -38,16 +38,16 @@
     "./storage": {
       "types": "./dist/storage/index.d.ts",
       "import": "./dist/storage/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js"
     }
   },
   "files": [
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "clean": "rm -rf dist"
-  },
   "peerDependencies": {
     "react": "^19.0.0",
     "@tanstack/react-query": "^5.0.0",
@@ -56,12 +56,19 @@
     "@hookform/resolvers": "^3.0.0 || ^4.0.0 || ^5.0.0"
   },
   "devDependencies": {
+    "@hookform/resolvers": "^5.0.1",
     "@tanstack/react-query": "^5.75.0",
     "@types/react": "^19.2.14",
     "react-hook-form": "^7.56.4",
-    "zod": "^3.25.67",
-    "@hookform/resolvers": "^5.0.1",
     "tsup": "^8.3.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.0",
+    "zod": "^3.25.67"
+  },
+  "scripts": {
+    "build": "tsup && node ../../scripts/check-exports-resolve.mjs",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}

package/dist/types-BzcZrTjl.d.ts

@@ -1,119 +0,0 @@
-/** Record identifier — supports both string UUIDs and numeric auto-increment IDs. */
-type Identifier = string | number;
-/** Base record type — all resources must have an id. */
-type BaseRecord = {
-    id: Identifier;
-    [key: string]: unknown;
-};
-/** Pagination parameters (offset-based, with optional cursor for future use). */
-interface PaginationParam {
-    page: number;
-    perPage: number;
-    cursor?: string;
-}
-/** Sort direction for a single field. */
-interface SortParam {
-    field: string;
-    order: "asc" | "desc";
-}
-/**
- * Filter expressions — discriminated union by operator.
- * Filters are AND-ed together in queries.
- */
-/** Operators that compare a field against a single scalar value. */
-interface ScalarFilter {
-    field: string;
-    operator: "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "contains";
-    value: string | number | boolean;
-}
-/** Operator that checks field membership in a list. */
-interface ArrayFilter {
-    field: string;
-    operator: "in";
-    value: (string | number | boolean)[];
-}
-/** Operator that checks field is within a range. */
-interface RangeFilter {
-    field: string;
-    operator: "between";
-    value: [string | number, string | number];
-}
-/** Operators that check for null/non-null — no value needed. */
-interface NullFilter {
-    field: string;
-    operator: "is_null" | "is_not_null";
-}
-type FilterParam = ScalarFilter | ArrayFilter | RangeFilter | NullFilter;
-/** Parameters for `getList`. */
-interface ListParams {
-    pagination?: PaginationParam;
-    sort?: SortParam;
-    filters?: FilterParam[];
-    /** Supabase select syntax, e.g. "*, author:profiles(name)". Mock provider ignores this. */
-    select?: string;
-    /** Multi-field text search (case-insensitive). */
-    search?: {
-        query: string;
-        fields: string[];
-    };
-}
-/** Result of `getList`. */
-interface ListResult<T> {
-    data: T[];
-    total: number;
-}
-/** Parameters for `getOne`. */
-interface GetOneParams {
-    id: Identifier;
-    /** Supabase select syntax, e.g. "*, author:profiles(name)". Defaults to "*". */
-    select?: string;
-}
-/** Result of `getOne`. */
-interface GetOneResult<T> {
-    data: T;
-}
-/** Parameters for `getMany`. */
-interface GetManyParams {
-    ids: Identifier[];
-}
-/** Result of `getMany`. */
-interface GetManyResult<T> {
-    data: T[];
-}
-/** Parameters for `create`. */
-interface CreateParams<T> {
-    data: Partial<T>;
-}
-/** Result of `create`. */
-interface CreateResult<T> {
-    data: T;
-}
-/** Parameters for `update`. */
-interface UpdateParams<T> {
-    id: Identifier;
-    data: Partial<T>;
-}
-/** Result of `update`. */
-interface UpdateResult<T> {
-    data: T;
-}
-/** Parameters for `deleteOne`. */
-interface DeleteParams {
-    id: Identifier;
-}
-/** Result of `deleteOne`. */
-interface DeleteResult {
-    data: {
-        id: Identifier;
-    };
-}
-interface DataProvider {
-    getList<T extends BaseRecord = BaseRecord>(resource: string, params: ListParams): Promise<ListResult<T>>;
-    getOne<T extends BaseRecord = BaseRecord>(resource: string, params: GetOneParams): Promise<GetOneResult<T>>;
-    getMany<T extends BaseRecord = BaseRecord>(resource: string, params: GetManyParams): Promise<GetManyResult<T>>;
-    create<T extends BaseRecord = BaseRecord>(resource: string, params: CreateParams<T>): Promise<CreateResult<T>>;
-    update<T extends BaseRecord = BaseRecord>(resource: string, params: UpdateParams<T>): Promise<UpdateResult<T>>;
-    deleteOne(resource: string, params: DeleteParams): Promise<DeleteResult>;
-}
-
-export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, FilterParam as F, GetManyParams as G, Identifier as I, ListParams as L, NullFilter as N, PaginationParam as P, RangeFilter as R, ScalarFilter as S, UpdateParams as U, CreateResult as a, DeleteParams as b, DeleteResult as c, GetManyResult as d, GetOneParams as e, GetOneResult as f, ListResult as g, SortParam as h, UpdateResult as i };