@segmentstream-cloud/ontology 0.6.0 → 0.8.0

package/dist/migrate/model.d.ts

@@ -42,7 +42,117 @@ export type MigrationRefusal = typeof MigrationRefusal.Type;
 export declare const MigrationPlan: Schema.Struct<{
     /** The hash of the applied manifest the plan starts from; absent for a fresh database. */
     readonly currentHash: Schema.optionalKey<Schema.String>;
-    readonly target: Schema.Struct<{
+    readonly target: Schema.Union<readonly [Schema.encodeKeys<Schema.Struct<{
+        readonly entities: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+            readonly properties: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+                readonly column: Schema.optionalKey<Schema.String>;
+                readonly scope: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly name: Schema.String;
+                readonly type: Schema.Literals<readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json"]>;
+                readonly label: Schema.String;
+                readonly description: Schema.optionalKey<Schema.String>;
+                readonly optional: Schema.Boolean;
+                readonly unique: Schema.Boolean;
+                readonly managed: Schema.Boolean;
+                readonly default: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly display: Schema.optionalKey<Schema.String>;
+                readonly renamedFrom: Schema.optionalKey<Schema.String>;
+                readonly min: Schema.optionalKey<Schema.Number>;
+                readonly max: Schema.optionalKey<Schema.Number>;
+                readonly maxLength: Schema.optionalKey<Schema.Number>;
+                readonly options: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                    readonly value: Schema.String;
+                    readonly label: Schema.String;
+                    readonly description: Schema.String;
+                }>>>;
+            }>, {
+                readonly renamedFrom: "renamed_from";
+                readonly maxLength: "max_length";
+            }>>;
+            readonly relationships: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+                readonly on: Schema.optionalKey<Schema.encodeKeys<Schema.Struct<{
+                    readonly property: Schema.String;
+                    readonly targetProperty: Schema.String;
+                }>, {
+                    readonly targetProperty: "target_property";
+                }>>;
+                readonly onDelete: Schema.optionalKey<Schema.decodeTo<Schema.Literals<readonly ["setNull", "cascade", "restrict"]>, Schema.Literals<readonly ["set_null", "cascade", "restrict"]>, never, never>>;
+                readonly name: Schema.String;
+                readonly to: Schema.String;
+                readonly inverse: Schema.String;
+                readonly cardinality: Schema.Literals<readonly ["one", "many"]>;
+                readonly optional: Schema.optionalKey<Schema.Boolean>;
+                readonly ordered: Schema.optionalKey<Schema.Boolean>;
+                readonly phrase: Schema.Tuple<readonly [Schema.String, Schema.String]>;
+                readonly description: Schema.String;
+            }>, {
+                readonly onDelete: "on_delete";
+            }>>;
+            readonly source: Schema.optionalKey<Schema.Struct<{
+                readonly asset: Schema.String;
+                readonly key: Schema.$Array<Schema.String>;
+                readonly currency: Schema.optionalKey<Schema.String>;
+            }>>;
+            readonly measures: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly label: Schema.String;
+                readonly description: Schema.String;
+                readonly unit: Schema.Literals<readonly ["number", "currency", "ratio", "percent"]>;
+                readonly format: Schema.Literals<readonly ["decimal", "currency", "percent"]>;
+                readonly expression: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            }>>>;
+            readonly id: Schema.String;
+            readonly name: Schema.String;
+            readonly label: Schema.String;
+            readonly plural: Schema.String;
+            readonly title: Schema.String;
+            readonly description: Schema.String;
+            readonly builtIn: Schema.Boolean;
+            readonly renamedFrom: Schema.optionalKey<Schema.String>;
+            readonly guide: Schema.optionalKey<Schema.String>;
+            readonly indexes: Schema.$Array<Schema.Struct<{
+                readonly properties: Schema.$Array<Schema.String>;
+                readonly unique: Schema.Boolean;
+            }>>;
+            readonly actions: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.String;
+                readonly description: Schema.String;
+                readonly permission: Schema.optionalKey<Schema.String>;
+                readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+                readonly connections: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            }>>;
+            readonly permissions: Schema.optionalKey<Schema.Struct<{
+                readonly read: Schema.String;
+                readonly create: Schema.optionalKey<Schema.String>;
+                readonly update: Schema.optionalKey<Schema.String>;
+                readonly delete: Schema.optionalKey<Schema.String>;
+                readonly link: Schema.optionalKey<Schema.String>;
+                readonly unlink: Schema.optionalKey<Schema.String>;
+            }>>;
+        }>, {
+            readonly builtIn: "built_in";
+            readonly renamedFrom: "renamed_from";
+        }>>;
+        readonly roles: Schema.$Array<Schema.encodeKeys<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly description: Schema.String;
+            readonly builtIn: Schema.Boolean;
+            readonly permissions: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        }>, {
+            readonly builtIn: "built_in";
+        }>>;
+        readonly version: Schema.Int;
+        readonly hash: Schema.String;
+        readonly signIn: Schema.optionalKey<Schema.Struct<{
+            readonly policy: Schema.String;
+        }>>;
+        readonly connections: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly key: Schema.String;
+            readonly description: Schema.String;
+        }>>>;
+    }>, {
+        readonly signIn: "sign_in";
+    }>, Schema.Struct<{
         readonly version: Schema.Int;
         readonly hash: Schema.String;
         readonly entities: Schema.$Array<Schema.Struct<{
@@ -138,7 +248,7 @@ export declare const MigrationPlan: Schema.Struct<{
             readonly key: Schema.String;
             readonly description: Schema.String;
         }>>>;
-    }>;
+    }>]>;
     /** Non-transactional steps first, then the steps of the one transaction, in execution order. */
     readonly steps: Schema.$Array<Schema.Struct<{
         readonly kind: Schema.Literals<readonly ["createCatalog", "createEntity", "renameEntity", "dropEntities", "addProperty", "renameProperty", "dropProperty", "changeOptional", "changeDefault", "changeCheck", "addSelectOption", "rebuildSelect", "addRelationship", "dropRelationship", "changeOnDelete", "addForeignKey", "addIndex", "dropIndex"]>;

package/dist/migrate/plan.js

@@ -1,4 +1,4 @@
-import { CAMEL_CASE_NAME, SNAKE_CASE_NAME, isSystemProperty } from "../names.js";
+import { SNAKE_CASE_NAME, isSystemProperty, toSnakeCase } from "../names.js";
 import { CATALOG_TABLE_DDL, MAX_IDENTIFIER_LENGTH, USER_TABLE, addConstraintStatement, columnDefinition, constraintDefinition, createEnumStatement, createIndexStatement, createTableStatement, defaultExpression, entityStorage, enumTypeName, fieldColumnName, joinTable, propertyCheck, propertyColumn, propertyEnum, quoteIdentifier, quoteLiteral, relationshipColumn, RUNTIME_TABLES_DDL, relationshipForeignKey, SYSTEM_COLUMNS, tableName, } from "./storage.js";
 const GLOBAL_KINDS = new Set(["table", "type", "index"]);
 function step(input) {
@@ -158,10 +158,11 @@ function validateEntity(entity, entityNames, invalid) {
     for (const property of entity.properties) {
         const path = `${entity.name}.properties.${property.name}`;
         const values = (property.options ?? []).map((option) => option.value);
-        if (!CAMEL_CASE_NAME.test(property.name) || isSystemProperty(property.name)) {
-            invalid(path, "property names are lower camelCase and cannot be system properties.");
+        if (!SNAKE_CASE_NAME.test(property.name) || isSystemProperty(property.name)) {
+            invalid(path, "property names are lowercase snake_case and cannot be system properties.");
         }
-        if (property.type === "select" && (values.length === 0 || values.some((value) => !value))) {
+        if (property.type === "select" &&
+            (values.length === 0 || values.some((value) => !SNAKE_CASE_NAME.test(value)))) {
             invalid(path, "a select property needs at least one non-empty option.");
         }
         if (new Set(values).size !== values.length) {
@@ -173,8 +174,8 @@ function validateEntity(entity, entityNames, invalid) {
     }
     for (const relationship of entity.relationships) {
         const path = `${entity.name}.relationships.${relationship.name}`;
-        if (!CAMEL_CASE_NAME.test(relationship.name) || isSystemProperty(relationship.name)) {
-            invalid(path, "relationship names are lower camelCase and cannot be system properties.");
+        if (!SNAKE_CASE_NAME.test(relationship.name) || isSystemProperty(relationship.name)) {
+            invalid(path, "relationship names are lowercase snake_case and cannot be system properties.");
         }
         if (!entityNames.has(relationship.to)) {
             invalid(path, `it points at ${relationship.to}, which is not an entity.`);
@@ -295,9 +296,10 @@ function matchProperties(current, target) {
     const addedProperties = [];
     for (const property of target.properties) {
         const sameName = byName.get(property.name);
-        const previous = property.renamedFrom !== undefined && !claimed.has(property.renamedFrom)
-            ? byName.get(property.renamedFrom)
-            : undefined;
+        const source = property.renamedFrom === undefined
+            ? undefined
+            : (byName.get(property.renamedFrom) ?? byName.get(toSnakeCase(property.renamedFrom)));
+        const previous = source !== undefined && !claimed.has(source.name) ? source : undefined;
         const match = sameName ?? previous;
         if (match === undefined) {
             addedProperties.push(property);

package/dist/migrate/storage.d.ts

@@ -12,10 +12,10 @@ export declare const USER_TABLE = "user";
 /** System properties and their columns, present on every entity table. */
 export declare const SYSTEM_COLUMNS: {
     readonly id: "id";
-    readonly createdAt: "created_at";
-    readonly updatedAt: "updated_at";
-    readonly createdBy: "created_by";
-    readonly updatedBy: "updated_by";
+    readonly created_at: "created_at";
+    readonly updated_at: "updated_at";
+    readonly created_by: "created_by";
+    readonly updated_by: "updated_by";
 };
 /** The kinds of change a history row records. */
 export declare const HISTORY_KINDS: readonly ["create", "update", "delete", "link", "unlink"];
@@ -85,7 +85,7 @@ export interface EntityStorage {
 export declare function quoteIdentifier(name: string): string;
 /** `'value'`, with embedded quotes doubled (standard_conforming_strings is on). */
 export declare function quoteLiteral(value: string): string;
-/** `fitScore` → `fit_score`. Property and relationship names are camelCase, so the mapping is one-to-one. */
+/** `fitScore` → `fit_score`. New property names already use snake_case; conversion remains for historical manifests. */
 export declare function snakeCase(name: string): string;
 /** An entity's table is named after the entity: `lead`, `user`. */
 export declare function tableName(entity: string): string;
@@ -119,7 +119,7 @@ export declare function primaryKeyName(table: string): string;
 /** An index over columns: `lead` + `status, created_at` → `lead_status_created_at_idx`. */
 export declare function indexName(table: string, columns: ReadonlyArray<string>): string;
 /**
- * The column of an index field: a system property (`createdAt` → `created_at`), a property, or a
+ * The column of an index field: a system property (`created_at` → `created_at`), a property, or a
  * `rel.one` (`owner` → `owner_id`). Returns undefined for anything else.
  */
 export declare function fieldColumnName(entity: EntityManifest, field: string): string | undefined;

package/dist/migrate/storage.js

@@ -11,10 +11,10 @@ export const USER_TABLE = "user";
 /** System properties and their columns, present on every entity table. */
 export const SYSTEM_COLUMNS = {
     id: "id",
-    createdAt: "created_at",
-    updatedAt: "updated_at",
-    createdBy: "created_by",
-    updatedBy: "updated_by",
+    created_at: "created_at",
+    updated_at: "updated_at",
+    created_by: "created_by",
+    updated_by: "updated_by",
 };
 /** The kinds of change a history row records. */
 export const HISTORY_KINDS = ["create", "update", "delete", "link", "unlink"];
@@ -43,7 +43,7 @@ export function quoteIdentifier(name) {
 export function quoteLiteral(value) {
     return `'${value.replaceAll("'", "''")}'`;
 }
-/** `fitScore` → `fit_score`. Property and relationship names are camelCase, so the mapping is one-to-one. */
+/** `fitScore` → `fit_score`. New property names already use snake_case; conversion remains for historical manifests. */
 export function snakeCase(name) {
     return name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
@@ -100,10 +100,20 @@ export function indexName(table, columns) {
     return `${table}_${columns.join("_")}_idx`;
 }
 /**
- * The column of an index field: a system property (`createdAt` → `created_at`), a property, or a
+ * The column of an index field: a system property (`created_at` → `created_at`), a property, or a
  * `rel.one` (`owner` → `owner_id`). Returns undefined for anything else.
  */
 export function fieldColumnName(entity, field) {
+    // Applied manifests may still name system fields in camelCase.
+    const historical = {
+        createdAt: "created_at",
+        updatedAt: "updated_at",
+        createdBy: "created_by",
+        updatedBy: "updated_by",
+    };
+    if (Object.hasOwn(historical, field)) {
+        return historical[field];
+    }
     if (Object.hasOwn(SYSTEM_COLUMNS, field)) {
         return SYSTEM_COLUMNS[field];
     }
@@ -228,8 +238,8 @@ export function joinTable(entity, relationship) {
         columns: [
             { name: keys.source, type: "uuid", notNull: true },
             { name: keys.target, type: "uuid", notNull: true },
-            { name: SYSTEM_COLUMNS.createdAt, type: "timestamptz", notNull: true, default: "now()" },
-            { name: SYSTEM_COLUMNS.createdBy, type: "uuid", notNull: false },
+            { name: SYSTEM_COLUMNS.created_at, type: "timestamptz", notNull: true, default: "now()" },
+            { name: SYSTEM_COLUMNS.created_by, type: "uuid", notNull: false },
         ],
         primaryKey: { name: primaryKeyName(name), columns: [keys.source, keys.target] },
         constraints: [
@@ -253,7 +263,7 @@ export function joinTable(entity, relationship) {
                 }),
                 references: tableName(relationship.to),
             },
-            userReference(name, SYSTEM_COLUMNS.createdBy),
+            userReference(name, SYSTEM_COLUMNS.created_by),
         ],
         indexes: [
             {
@@ -311,10 +321,10 @@ export function historyTable(entity) {
 function systemColumns() {
     return [
         { name: SYSTEM_COLUMNS.id, type: "uuid", notNull: true, default: "gen_random_uuid()" },
-        { name: SYSTEM_COLUMNS.createdAt, type: "timestamptz", notNull: true, default: "now()" },
-        { name: SYSTEM_COLUMNS.updatedAt, type: "timestamptz", notNull: true, default: "now()" },
-        { name: SYSTEM_COLUMNS.createdBy, type: "uuid", notNull: false },
-        { name: SYSTEM_COLUMNS.updatedBy, type: "uuid", notNull: false },
+        { name: SYSTEM_COLUMNS.created_at, type: "timestamptz", notNull: true, default: "now()" },
+        { name: SYSTEM_COLUMNS.updated_at, type: "timestamptz", notNull: true, default: "now()" },
+        { name: SYSTEM_COLUMNS.created_by, type: "uuid", notNull: false },
+        { name: SYSTEM_COLUMNS.updated_by, type: "uuid", notNull: false },
     ];
 }
 /**
@@ -376,8 +386,8 @@ export function entityStorage(entity) {
             ],
             primaryKey: { name: primaryKeyName(table), columns: [SYSTEM_COLUMNS.id] },
             constraints: [
-                userReference(table, SYSTEM_COLUMNS.createdBy),
-                userReference(table, SYSTEM_COLUMNS.updatedBy),
+                userReference(table, SYSTEM_COLUMNS.created_by),
+                userReference(table, SYSTEM_COLUMNS.updated_by),
                 ...checks,
                 ...ones.map((relationship) => relationshipForeignKey(entity.name, relationship)),
             ],

package/dist/names.d.ts

@@ -1,19 +1,19 @@
-/** Entity and role names: lowercase snake_case. They become table names and API path segments. */
+/** Ontology names: lowercase snake_case. */
 export declare const SNAKE_CASE_NAME: RegExp;
-/**
- * Property, relationship and action names: lower camelCase, as the API and the TypeScript records spell
- * them. Each one maps to exactly one snake_case column name.
- */
-export declare const CAMEL_CASE_NAME: RegExp;
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export declare function toSnakeCase(name: string): string;
+export declare function toCamelCase(name: string): string;
+/** Historical property names accepted only as explicit rename sources. */
+export declare const LEGACY_MEMBER_NAME: RegExp;
 /** Stable entity identities, for example `ent_01J9Q4M8ZK`. */
 export declare const ENTITY_ID: RegExp;
 /** Properties every entity has. They are never declared and cannot be redeclared. */
-export declare const SYSTEM_PROPERTIES: readonly ["id", "createdAt", "updatedAt", "createdBy", "updatedBy"];
-export type SystemProperty = (typeof SYSTEM_PROPERTIES)[number];
+export declare const SYSTEM_PROPERTIES: readonly ["id", "created_at", "updated_at", "created_by", "updated_by"];
+export type SystemProperty = "id" | "createdAt" | "updatedAt" | "createdBy" | "updatedBy";
 /** Actions the platform generates for every entity; authored actions cannot use these names. */
 export declare const GENERATED_ACTIONS: readonly ["create", "update", "delete", "link", "unlink"];
-/** Prefix of the generated `upsertBy<Property>` actions. */
-export declare const GENERATED_UPSERT_PREFIX = "upsertBy";
+/** Prefix of the generated `upsert_by_<property>` actions. */
+export declare const GENERATED_UPSERT_PREFIX = "upsert_by_";
 /** The built-in role every active app user holds. */
 export declare const MEMBER_ROLE = "member";
 /** Suffix reserved for the history table each entity gets. */
@@ -25,5 +25,5 @@ export declare const RESERVED_ENTITY_NAMES: readonly ["graph", "status", "descri
 /** `/api/ontology/<entity>/{id}/history`, which a relationship's traversal would shadow. */
 export declare const RESERVED_RELATIONSHIP_NAMES: readonly ["history"];
 export declare function isSystemProperty(name: string): boolean;
-/** `createdAt` → `Created at`, `pilot_request` → `Pilot request`. */
+/** `created_at` → `Created at`, `pilot_request` → `Pilot request`. */
 export declare function humanize(name: string): string;

package/dist/names.js

@@ -1,24 +1,47 @@
-/** Entity and role names: lowercase snake_case. They become table names and API path segments. */
+/** Ontology names: lowercase snake_case. */
 export const SNAKE_CASE_NAME = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
-/**
- * Property, relationship and action names: lower camelCase, as the API and the TypeScript records spell
- * them. Each one maps to exactly one snake_case column name.
- */
-export const CAMEL_CASE_NAME = /^[a-z][a-zA-Z0-9]*$/;
+/** TypeScript names are converted only at the ontology's serialization boundary. */
+function isUppercase(letter) {
+    return letter !== undefined && letter >= "A" && letter <= "Z";
+}
+function isLowercase(letter) {
+    return letter !== undefined && letter >= "a" && letter <= "z";
+}
+/** Convert each character once, including acronym boundaries such as HTTPClient. */
+export function toSnakeCase(name) {
+    const characters = [];
+    for (let index = 0; index < name.length; index++) {
+        const current = name[index];
+        const previous = name[index - 1];
+        const next = name[index + 1];
+        const followsWord = isLowercase(previous) || (previous !== undefined && previous >= "0" && previous <= "9");
+        const endsAcronym = isUppercase(previous) && isLowercase(next);
+        if (isUppercase(current) && (followsWord || endsAcronym)) {
+            characters.push("_");
+        }
+        characters.push(current);
+    }
+    return characters.join("").toLowerCase();
+}
+export function toCamelCase(name) {
+    return name.replace(/_([a-z0-9])/g, (_, letter) => letter.toUpperCase());
+}
+/** Historical property names accepted only as explicit rename sources. */
+export const LEGACY_MEMBER_NAME = /^(?:[a-z][a-zA-Z0-9]*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
 /** Stable entity identities, for example `ent_01J9Q4M8ZK`. */
 export const ENTITY_ID = /^ent_[A-Za-z0-9_]+$/;
 /** Properties every entity has. They are never declared and cannot be redeclared. */
 export const SYSTEM_PROPERTIES = [
     "id",
-    "createdAt",
-    "updatedAt",
-    "createdBy",
-    "updatedBy",
+    "created_at",
+    "updated_at",
+    "created_by",
+    "updated_by",
 ];
 /** Actions the platform generates for every entity; authored actions cannot use these names. */
 export const GENERATED_ACTIONS = ["create", "update", "delete", "link", "unlink"];
-/** Prefix of the generated `upsertBy<Property>` actions. */
-export const GENERATED_UPSERT_PREFIX = "upsertBy";
+/** Prefix of the generated `upsert_by_<property>` actions. */
+export const GENERATED_UPSERT_PREFIX = "upsert_by_";
 /** The built-in role every active app user holds. */
 export const MEMBER_ROLE = "member";
 /** Suffix reserved for the history table each entity gets. */
@@ -39,7 +62,7 @@ export const RESERVED_RELATIONSHIP_NAMES = ["history"];
 export function isSystemProperty(name) {
     return SYSTEM_PROPERTIES.includes(name);
 }
-/** `createdAt` → `Created at`, `pilot_request` → `Pilot request`. */
+/** `created_at` → `Created at`, `pilot_request` → `Pilot request`. */
 export function humanize(name) {
     const words = name
         .replace(/([a-z0-9])([A-Z])/g, "$1 $2")

package/dist/permissions.d.ts

@@ -1,6 +1,6 @@
 /**
  * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
- * `delete`, `link` and `unlink`, and the camelCase name of an authored action. A role may use `*` for
+ * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
  * the entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
  * holds a wildcard.
  */
@@ -34,7 +34,7 @@ export declare function isAllowed(required: string, principal: PermissionHolder)
 /** The first of the required permissions the principal lacks, or `undefined` when it holds all. */
 export declare function missingPermission(required: ReadonlyArray<string>, principal: PermissionHolder): string | undefined;
 /**
- * What a generated action requires: `<entity>:<action>`, except `upsertBy<Property>`, which may
+ * What a generated action requires: `<entity>:<action>`, except `upsert_by_<property>`, which may
  * create or update and so requires both `<entity>:create` and `<entity>:update`.
  */
 export declare function generatedActionPermissions(entity: string, action: string): ReadonlyArray<string>;

package/dist/permissions.js

@@ -1,7 +1,7 @@
-import { GENERATED_UPSERT_PREFIX } from "./names.js";
+import { GENERATED_UPSERT_PREFIX, toSnakeCase } from "./names.js";
 /**
  * Permissions are `<entity>:<verb>` strings. The verbs are `read`, the generated `create`, `update`,
- * `delete`, `link` and `unlink`, and the camelCase name of an authored action. A role may use `*` for
+ * `delete`, `link` and `unlink`, and the snake_case name of an authored action. A role may use `*` for
  * the entity (`*:read`), the verb (`lead:*`) or both (`*:*`); what an action or a read requires never
  * holds a wildcard.
  */
@@ -11,8 +11,8 @@ export const WILDCARD = "*";
 export const READ_VERB = "read";
 /** What the built-in `member` role holds when `defineOntology` does not say: reading everything. */
 export const DEFAULT_MEMBER_PERMISSIONS = [`${WILDCARD}:${READ_VERB}`];
-/** `<entity>:<verb>` with lowercase snake_case entities and lower camelCase verbs, or `*` for either. */
-const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*)$/;
+/** `<entity>:<verb>` with lowercase snake_case entities and lowercase snake_case verbs, or `*` for either. */
+const PERMISSION = /^(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-zA-Z0-9]*(?:_[a-z0-9]+)*)$/;
 /** The entity and verb of a permission, or `undefined` when the value is not one. */
 export function parsePermission(value) {
     if (typeof value !== "string") {
@@ -32,8 +32,8 @@ export function grants(granted, required) {
     if (held === undefined || wanted === undefined) {
         return false;
     }
-    return ((held.entity === WILDCARD || held.entity === wanted.entity) &&
-        (held.verb === WILDCARD || held.verb === wanted.verb));
+    return ((held.entity === WILDCARD || toSnakeCase(held.entity) === toSnakeCase(wanted.entity)) &&
+        (held.verb === WILDCARD || toSnakeCase(held.verb) === toSnakeCase(wanted.verb)));
 }
 /**
  * Whether the principal may do what `required` names: one of its permissions equals it, or covers it
@@ -47,11 +47,11 @@ export function missingPermission(required, principal) {
     return required.find((permission) => !isAllowed(permission, principal));
 }
 /**
- * What a generated action requires: `<entity>:<action>`, except `upsertBy<Property>`, which may
+ * What a generated action requires: `<entity>:<action>`, except `upsert_by_<property>`, which may
  * create or update and so requires both `<entity>:create` and `<entity>:update`.
  */
 export function generatedActionPermissions(entity, action) {
-    return action.startsWith(GENERATED_UPSERT_PREFIX)
+    return toSnakeCase(action).startsWith(GENERATED_UPSERT_PREFIX)
         ? [permissionOf(entity, "create"), permissionOf(entity, "update")]
         : [permissionOf(entity, action)];
 }

package/dist/property.js

@@ -1,5 +1,6 @@
 import { Schema } from "effect";
 import { humanize } from "./names.js";
+import { nameToWire } from "./authoring-names.js";
 /** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
 export const PROPERTY_TYPES = [
     "text",
@@ -171,7 +172,7 @@ function ref(target, options) {
         ...(settings.label !== undefined ? { title: settings.label } : {}),
         description: settings.description ?? `The id of a ${entityName} record.`,
         format: "uuid",
-        [REFERENCE_ANNOTATION]: entityName,
+        [REFERENCE_ANNOTATION]: nameToWire(entityName),
     }).check(Schema.isPattern(UUID));
     return (settings.optional === true ? Schema.optionalKey(schema) : schema);
 }

package/dist/query.d.ts

@@ -2,7 +2,7 @@ import { Schema } from "effect";
 import type { JsonSchemaObject } from "./analyze.js";
 import type { EntityManifest, OntologyManifest } from "./manifest.js";
 import type { PropertyType } from "./property.js";
-/** How a record field is stored: a property type, or a UUID for ids and `<relationship>Id` keys. */
+/** How a record field is stored: a property type, or a UUID for ids and `<relationship>_id` keys. */
 export type StorageType = PropertyType | "uuid";
 /**
  * The query language of `find` and of the HTTP API's list and query endpoints.
@@ -15,7 +15,7 @@ export type StorageType = PropertyType | "uuid";
  *     "tags": { "some": { "name": { "eq": "priority" } } },
  *     "or": [{ "fitScore": { "gte": 80 } }, { "source": "pilot_request" }]
  *   },
- *   "orderBy": [{ "field": "createdAt", "direction": "desc" }],
+ *   "orderBy": [{ "field": "created_at", "direction": "desc" }],
  *   "include": { "owner": true },
  *   "limit": 50
  * }
@@ -114,7 +114,7 @@ export declare function queryResultSchema<S extends Schema.Top>(record: S): Sche
     readonly items: Schema.$Array<S>;
     readonly nextCursor: Schema.NullOr<Schema.String>;
 }>;
-/** A field a query can filter and sort on: a system field, a property, or a `<relationship>Id`. */
+/** A field a query can filter and sort on: a system field, a property, or a `<relationship>_id`. */
 export interface QueryField {
     readonly name: string;
     readonly storage: StorageType;
@@ -170,12 +170,12 @@ export interface EntityQuerySchemas {
  * include. Every struct is closed: an unknown field, operator or key is an issue whatever the parse
  * options, never a silently ignored filter.
  */
-export declare function entityQuerySchemas(manifest: OntologyManifest, entityName: string): EntityQuerySchemas;
+export declare function entityQuerySchemas(manifest: OntologyManifest, entityName: string, wire?: boolean): EntityQuerySchemas;
 /** The query schema of one entity; see {@link entityQuerySchemas}. */
 export declare function entityQuerySchema(manifest: OntologyManifest, entityName: string): Schema.Codec<Query>;
 /**
  * The record of an entity as the runtime returns it: system fields, properties (`null` when empty;
- * dates as `YYYY-MM-DD`, timestamps as ISO 8601 in UTC) and a `<relationship>Id` per `rel.one`. It
+ * dates as `YYYY-MM-DD`, timestamps as ISO 8601 in UTC) and a `<relationship>_id` per `rel.one`. It
  * checks the shape of stored values, not the refinements of the definition (`maxLength`, `min`,
  * patterns), so that tightening a refinement never makes existing records unreadable.
  */
@@ -185,7 +185,7 @@ export type JsonRecord = {
     readonly [field: string]: Schema.Json;
 };
 /** A page of an entity's records, with the relationships a query may include. */
-export declare function entityQueryResultSchema(manifest: OntologyManifest, entityName: string): Schema.Codec<QueryResult<JsonRecord>>;
+export declare function entityQueryResultSchema(manifest: OntologyManifest, entityName: string, wire?: boolean): Schema.Codec<QueryResult<JsonRecord>, unknown>;
 /** The JSON Schema (draft 2020-12) of an entity's queries, for MCP tools, OpenAPI and the console. */
 export declare function queryJsonSchema(manifest: OntologyManifest, entityName: string): JsonSchemaObject;
 /** The JSON Schema (draft 2020-12) of a page of an entity's records. */