@marktiderman/genesis-core 1.1.1 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Tiderman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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-C7UVaF87.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-C7UVaF87.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 { s as SortParam, i as FilterParam, m as ListResult, L as ListParams, I as Identifier, B as BaseRecord } from '../types-C7UVaF87.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, C as CreateParams, b as CreateResult, D as DataProvider, c as DataRow, d as DeleteParams, e as DeleteResult, F as FieldPermissions, f as FieldReference, g as FieldSchema, h as FilterOperator, i as FilterParam, G as GetManyParams, j as GetManyResult, k as GetOneParams, l as GetOneResult, I as Identifier, L as ListParams, m as ListResult, N as NullFilter, P as PaginationParam, n as ProviderCapabilities, R as RangeFilter, o as ResourceAccess, p as ResourceContract, q as ResourceSchema, r as ResourceSummary, S as ScalarFilter, s as SortParam, t as StorageType, U as UpdateParams, u as UpdateResult, V as VersionField } from './types-C7UVaF87.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from './write-outcome-D8kjoQ1A.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,9 +7,9 @@ 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/jsx-runtime';
 import 'react';
 import '@tanstack/react-query';
 import 'react-hook-form';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { createSupabaseProvider } from './chunk-RKR5K7Q3.js';
+export { createSupabaseProvider } from './chunk-6AA4ISUA.js';
+export { decodeRecordKey, encodeRecordKey, keyFields } from './chunk-KV2HW4G4.js';
+export { DataWriteError, isDataWriteError } from './chunk-4W4W7F4I.js';
 import './chunk-XCX2TRBL.js';
 import './chunk-65SXNHWE.js';
 import './chunk-EL7YGOTY.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 * as react_jsx_runtime from 'react/jsx-runtime';
+import { D as DataProvider } from '../types-C7UVaF87.js';
+export { A as ArrayFilter, B as BaseRecord, C as CreateParams, b as CreateResult, d as DeleteParams, e as DeleteResult, i as FilterParam, G as GetManyParams, j as GetManyResult, k as GetOneParams, l as GetOneResult, I as Identifier, L as ListParams, m as ListResult, N as NullFilter, P as PaginationParam, R as RangeFilter, S as ScalarFilter, s as SortParam, U as UpdateParams, u as UpdateResult } from '../types-C7UVaF87.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-D8kjoQ1A.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). */
@@ -74,7 +76,7 @@ interface DataProviderRootProps {
     provider: DataProvider;
     children: ReactNode;
 }
-declare function DataProviderRoot({ provider, children }: DataProviderRootProps): react_jsx_runtime.JSX.Element;
+declare function DataProviderRoot({ provider, children }: DataProviderRootProps): react.JSX.Element;
 declare function useDataProvider(): DataProvider;
 declare function useStorage(): StorageAdapter;
 type Row = Record<string, unknown>;
@@ -96,6 +98,6 @@ type GenesisProviderProps = {
     /** Platform-specific storage adapter. Defaults to localStorage (SSR-safe). */
     storage?: StorageAdapter;
 };
-declare function GenesisProvider({ children, provider, mock, storage, }: GenesisProviderProps): react_jsx_runtime.JSX.Element;
+declare function GenesisProvider({ children, provider, mock, storage, }: GenesisProviderProps): react.JSX.Element;
 
 export { DataProvider, DataProviderRoot, type DataProviderRootProps, GenesisProvider, type GenesisProviderProps, type MockProviderOptions, type SupabaseClient, type SupabaseClientInput, createMockProvider, createSupabaseProvider, useDataProvider, useStorage };

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 { p as ResourceContract, I as Identifier, c as DataRow } from '../types-C7UVaF87.js';
+export { a as AuditEntry, F as FieldPermissions, f as FieldReference, g as FieldSchema, h as FilterOperator, n as ProviderCapabilities, o as ResourceAccess, q as ResourceSchema, r as ResourceSummary, t as StorageType, V as VersionField } from '../types-C7UVaF87.js';
+export { D as DataWriteError, a as DataWriteErrorOptions, W as WriteOutcome, i as isDataWriteError } from '../write-outcome-D8kjoQ1A.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-C7UVaF87.d.ts

@@ -0,0 +1,319 @@
+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;
+    /** 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;
+}
+/**
+ * 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;
+    readonly kind: "integer" | "timestamp";
+}
+/**
+ * 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;
+}
+/** 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;
+}
+/** 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;
+    readonly action: "create" | "update" | "delete";
+    /** 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;
+    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> {
+    /**
+     * 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;
+}
+/** 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>;
+    /**
+     * 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>;
+}
+
+export type { ArrayFilter as A, BaseRecord as B, CreateParams as C, DataProvider as D, FieldPermissions 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, VersionField as V, AuditEntry as a, CreateResult as b, DataRow as c, DeleteParams as d, DeleteResult as e, FieldReference as f, FieldSchema as g, FilterOperator as h, FilterParam as i, GetManyResult as j, GetOneParams as k, GetOneResult as l, ListResult as m, ProviderCapabilities as n, ResourceAccess as o, ResourceContract as p, ResourceSchema as q, ResourceSummary as r, SortParam as s, StorageType as t, UpdateResult as u };

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

@@ -0,0 +1,38 @@
+import { c as DataRow } from './types-C7UVaF87.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.1",
+  "version": "1.2.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -10,7 +10,7 @@
     "url": "git+https://github.com/marktiderman/genesis.git",
     "directory": "packages/core"
   },
-  "license": "UNLICENSED",
+  "license": "MIT",
   "publishConfig": {
     "access": "public",
     "provenance": false
@@ -38,6 +38,10 @@
     "./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": [
@@ -52,16 +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",
-    "clean": "rm -rf dist"
+    "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 };