@segmentstream-cloud/ontology 0.7.0 → 0.8.0

package/README.md

@@ -8,12 +8,13 @@ database and the HTTP service under `/api/ontology`. Every read and every action
 a permission that the caller's roles grant, and every change to a record goes through an
 action and is kept in history.
 
-Ontology names and record fields use lowercase snake_case, including relationships,
-actions, measures, select values, and system fields such as `created_at`. Generated
-actions use names such as `upsert_by_email`. TypeScript helpers and configuration
-options retain camelCase (`defineOntology`, `upsertBy`, `orderBy`, `renamedFrom`).
-The generated REST API and version 4 manifest encode their metadata keys in
-snake_case; `formatManifest` is the serializer for that wire contract.
+TypeScript definitions, handler records and SDK calls use camelCase: `jobTitle`,
+`assignedOwnerId`, `createdAt`, and `changeStatus`. The SDK converts ontology names,
+select identifiers and declared action input fields to snake_case for the generated
+REST API, version 4 manifest and storage. TypeScript helpers and options stay
+camelCase. JSON property contents, provider payloads, opaque action results and
+historical change names remain data and are preserved. `formatManifest` serializes
+the canonical wire contract shared by REST, storage and future transports.
 
 ## Install
 
@@ -58,7 +59,7 @@ export const Lead = entity("lead", {
   relationships: {
     owner: rel.one(User, {
       optional: true,
-      inverse: "owned_leads",
+      inverse: "ownedLeads",
       onDelete: "setNull",
       phrase: ["is owned by", "owns"],
       description: "The team member responsible for the next step.",

package/dist/analyze.js

@@ -10,6 +10,8 @@ import { ON_DELETE, isRelationship } from "./relationship.js";
 import { isRole, member, role } from "./role.js";
 import { DEFAULT_SIGN_IN_POLICY, isSignInPolicy } from "./sign-in.js";
 import { User } from "./user.js";
+import { authoringToWire } from "./authoring.js";
+import { nameToWire } from "./authoring-names.js";
 const GENERATED_UPSERT = new RegExp(`^${GENERATED_UPSERT_PREFIX}`);
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -29,7 +31,10 @@ export function analyze(config, options = {}) {
     const report = (code, path, message, severity = "error") => {
         diagnostics.push({ severity, code, path, message });
     };
-    const user = options.user ?? User;
+    const original = config;
+    const normalized = authoringToWire(config, options.user ?? User, report);
+    config = normalized.config;
+    const user = normalized.user;
     const entities = collectEntities(config, user, report);
     const roles = collectRoles(config, report);
     const signIn = signInOptions(config, report);
@@ -45,7 +50,7 @@ export function analyze(config, options = {}) {
         user,
         entitiesByName,
         definitions: new Set(entities.map((candidate) => candidate.definition)),
-        entityProperties: new Set(entities.flatMap((candidate) => Object.values(candidate.definition.properties ?? {}))),
+        entityProperties: new Set([...entities, ...(original.entities ?? []).filter(isEntity)].flatMap((candidate) => Object.values(candidate.definition.properties ?? {}))),
         connections: new Set(connections.map((candidate) => candidate.key)),
     };
     const resolved = entities.map((candidate) => resolveEntity(candidate, scope));
@@ -314,7 +319,10 @@ function resolveProperties(candidate, scope) {
     const properties = [];
     for (const [name, schema] of entries) {
         const path = `${candidate.name}.properties.${name}`;
-        const definition = propertyDefinition(schema);
+        const originalDefinition = propertyDefinition(schema);
+        const definition = !Array.isArray(originalDefinition?.scope)
+            ? originalDefinition
+            : { ...originalDefinition, scope: originalDefinition.scope.map(nameToWire) };
         checkMemberName("property", path, name, report);
         if (definition === undefined) {
             const hint = referenceTarget(schema) === undefined
@@ -603,7 +611,7 @@ function checkInputFields(path, fields, scope) {
     for (const [name, field] of Object.entries(fields)) {
         const fieldPath = `${path}.${name}`;
         const reference = referenceTarget(field);
-        if (reference !== undefined && !scope.entitiesByName.has(reference)) {
+        if (reference !== undefined && !scope.entitiesByName.has(nameToWire(reference))) {
             scope.report("unknown-reference", fieldPath, `references "${reference}", which is not an entity of this ontology.`);
         }
         if (scope.entityProperties.has(field)) {

package/dist/authoring-input.d.ts

@@ -0,0 +1,3 @@
+import { Schema } from "effect";
+/** A schema-aware codec: declared fields convert, JSON/dictionary keys and provider data do not. */
+export declare function actionInputToWire(input: Schema.Top): Schema.Top;

package/dist/authoring-input.js

@@ -0,0 +1,107 @@
+import { Schema, SchemaAST, SchemaTransformation } from "effect";
+import { propertyDefinition } from "./property.js";
+import { isRecord, nameToWire } from "./authoring-names.js";
+function mapChildren(ast, convert) {
+    switch (ast._tag) {
+        case "Objects":
+            return new SchemaAST.Objects(ast.propertySignatures.map((field) => new SchemaAST.PropertySignature(field.name, convert(field.type))), ast.indexSignatures.map((field) => new SchemaAST.IndexSignature(field.parameter, convert(field.type))), ast.annotations, ast.checks, ast.encoding, ast.context);
+        case "Arrays":
+            return new SchemaAST.Arrays(ast.isMutable, ast.elements.map(convert), ast.rest.map(convert), ast.annotations, ast.checks, ast.encoding, ast.context);
+        case "Union":
+            return new SchemaAST.Union(ast.types.map(convert), ast.options, ast.annotations, ast.checks, ast.encoding, ast.context);
+        case "Suspend":
+            return new SchemaAST.Suspend(() => convert(ast.thunk()), ast.annotations, undefined, ast.encoding, ast.context);
+        default:
+            return ast;
+    }
+}
+function selectToWire(ast) {
+    if (ast._tag === "Literal" && typeof ast.literal === "string") {
+        return new SchemaAST.Literal(nameToWire(ast.literal), ast.annotations, ast.checks, ast.encoding, ast.context);
+    }
+    return mapChildren(ast, selectToWire);
+}
+/** A schema-aware codec: declared fields convert, JSON/dictionary keys and provider data do not. */
+export function actionInputToWire(input) {
+    const encoded = Schema.toEncoded(input).ast;
+    const nodes = new WeakMap();
+    const wire = (ast) => {
+        const existing = nodes.get(ast);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const property = propertyDefinition(Schema.make(ast));
+        if (property?.type === "json") {
+            return ast;
+        }
+        if (property?.type === "select") {
+            return selectToWire(ast);
+        }
+        const nested = mapChildren(ast, wire);
+        if (nested._tag !== "Objects") {
+            nodes.set(ast, nested);
+            return nested;
+        }
+        const names = new Set();
+        const fields = nested.propertySignatures.map((field) => {
+            const name = typeof field.name === "string" ? nameToWire(field.name) : field.name;
+            if (names.has(name)) {
+                throw new Error(`Input fields collide on wire name ${String(name)}.`);
+            }
+            names.add(name);
+            return new SchemaAST.PropertySignature(name, field.type);
+        });
+        // Object checks run on the original camelCase shape after decoding below.
+        const result = new SchemaAST.Objects(fields, nested.indexSignatures, nested.annotations, undefined, undefined, nested.context);
+        nodes.set(ast, result);
+        return result;
+    };
+    const rename = (value, ast, decode) => {
+        const property = propertyDefinition(Schema.make(ast));
+        if (property?.type === "json") {
+            return value;
+        }
+        if (property?.type === "select" && typeof value === "string") {
+            return decode
+                ? (property.options?.find((option) => nameToWire(option.value) === value)?.value ?? value)
+                : nameToWire(value);
+        }
+        if (ast._tag === "Suspend") {
+            return rename(value, ast.thunk(), decode);
+        }
+        if (ast._tag === "Union") {
+            const member = ast.types.find((candidate) => Schema.is(Schema.make(decode ? wire(candidate) : candidate))(value));
+            return member === undefined ? value : rename(value, member, decode);
+        }
+        if (ast._tag === "Arrays" && Array.isArray(value)) {
+            return value.map((child, index) => {
+                const member = ast.elements[index] ?? ast.rest[0];
+                return member === undefined ? child : rename(child, member, decode);
+            });
+        }
+        if (ast._tag !== "Objects" || !isRecord(value)) {
+            return value;
+        }
+        return Object.fromEntries(Object.entries(value).map(([name, child]) => {
+            const field = ast.propertySignatures.find((candidate) => (decode && typeof candidate.name === "string"
+                ? nameToWire(candidate.name)
+                : candidate.name) === name);
+            return field === undefined
+                ? [
+                    name,
+                    ast.indexSignatures[0] === undefined
+                        ? child
+                        : rename(child, ast.indexSignatures[0].type, decode),
+                ]
+                : [
+                    decode ? field.name : nameToWire(String(field.name)),
+                    rename(child, field.type, decode),
+                ];
+        }));
+    };
+    const codec = Schema.make(wire(encoded)).pipe(Schema.decodeTo(input, SchemaTransformation.transform({
+        decode: (value) => rename(value, encoded, true),
+        encode: (value) => rename(value, encoded, false),
+    })));
+    return "fields" in input ? Object.assign(codec, { fields: input.fields }) : codec;
+}

package/dist/authoring-names.d.ts

@@ -0,0 +1,4 @@
+/** Leave malformed identifiers intact so validation still reports them. */
+export declare function nameToWire(name: string): string;
+export declare function permissionToWire(permission: string): string;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/authoring-names.js

@@ -0,0 +1,13 @@
+import { toSnakeCase } from "./names.js";
+/** Leave malformed identifiers intact so validation still reports them. */
+export function nameToWire(name) {
+    return typeof name === "string" && /^[a-z][a-zA-Z0-9]*$/.test(name) ? toSnakeCase(name) : name;
+}
+export function permissionToWire(permission) {
+    return typeof permission === "string"
+        ? permission.split(":").map(nameToWire).join(":")
+        : permission;
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/authoring-records.d.ts

@@ -0,0 +1,16 @@
+import { type AnyEntity, type Properties, type Relationships } from "./entity.js";
+import type { Edit } from "./runtime/history.js";
+import type { FindOptions, StoredValues } from "./runtime.js";
+interface Definition {
+    readonly properties: Properties;
+    readonly relationships?: Relationships;
+}
+/** Only record keys and select identifiers convert; property values remain data. */
+export declare function recordFromWire<A>(value: unknown, definition?: Definition): A;
+export declare function valuesToWire(values: StoredValues, definition: Definition): StoredValues;
+export declare function findToWire(options: FindOptions, definition: Definition): FindOptions;
+/** Current action edits use the same property names and values as authored entity records. */
+export declare function editsFromWire(edits: ReadonlyArray<Edit>, entities: ReadonlyArray<AnyEntity>): ReadonlyArray<Edit>;
+/** Generated actions return entity records; authored action results remain application data. */
+export declare function generatedResultFromWire(value: unknown, action: string, definition?: Definition): unknown;
+export {};

package/dist/authoring-records.js

@@ -0,0 +1,144 @@
+import { isEntity } from "./entity.js";
+import { toCamelCase } from "./names.js";
+import { propertyDefinition } from "./property.js";
+import { isRecord, nameToWire } from "./authoring-names.js";
+function targetDefinition(target) {
+    const resolved = typeof target === "function" ? target() : target;
+    return isEntity(resolved) ? resolved.definition : undefined;
+}
+function selectValue(value, property, decode) {
+    const definition = propertyDefinition(property);
+    if (definition?.type !== "select") {
+        return value;
+    }
+    const convert = (child) => typeof child !== "string"
+        ? child
+        : decode
+            ? (definition.options?.find((option) => nameToWire(option.value) === child)?.value ?? child)
+            : nameToWire(child);
+    return Array.isArray(value) ? value.map(convert) : convert(value);
+}
+/** Only record keys and select identifiers convert; property values remain data. */
+export function recordFromWire(value, definition) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, child]) => {
+        const property = Object.entries(definition?.properties ?? {}).find(([key]) => nameToWire(key) === name);
+        if (property !== undefined) {
+            return [property[0], selectValue(child, property[1], true)];
+        }
+        const relationship = Object.entries(definition?.relationships ?? {}).find(([key]) => nameToWire(key) === name);
+        if (relationship !== undefined) {
+            const target = targetDefinition(relationship[1].target);
+            return [
+                relationship[0],
+                Array.isArray(child)
+                    ? child.map((item) => recordFromWire(item, target))
+                    : recordFromWire(child, target),
+            ];
+        }
+        return [toCamelCase(name), child];
+    }));
+}
+export function valuesToWire(values, definition) {
+    return Object.fromEntries(Object.entries(values).map(([name, value]) => [
+        nameToWire(name),
+        selectValue(value, definition.properties[name], false),
+    ]));
+}
+/** Translate query fields and relationships; operands of JSON filters stay opaque. */
+function whereToWire(where, definition) {
+    return Object.fromEntries(Object.entries(where).map(([name, condition]) => {
+        if ((name === "and" || name === "or") && Array.isArray(condition)) {
+            return [name, condition.map((child) => whereToWire(child, definition))];
+        }
+        if (name === "not" && isRecord(condition)) {
+            return [name, whereToWire(condition, definition)];
+        }
+        const property = definition?.properties[name];
+        const relationship = definition?.relationships?.[name];
+        if (relationship !== undefined && isRecord(condition)) {
+            const target = targetDefinition(relationship.target);
+            return [
+                nameToWire(name),
+                relationship.cardinality === "many"
+                    ? Object.fromEntries(Object.entries(condition).map(([quantifier, child]) => [
+                        quantifier,
+                        isRecord(child) ? whereToWire(child, target) : child,
+                    ]))
+                    : whereToWire(condition, target),
+            ];
+        }
+        if (isRecord(condition)) {
+            const operators = [
+                "eq",
+                "ne",
+                "in",
+                "isNull",
+                "contains",
+                "startsWith",
+                "gt",
+                "gte",
+                "lt",
+                "lte",
+                "between",
+            ];
+            if (Object.keys(condition).every((key) => operators.includes(key))) {
+                return [
+                    nameToWire(name),
+                    Object.fromEntries(Object.entries(condition).map(([key, child]) => [
+                        key,
+                        selectValue(child, property, false),
+                    ])),
+                ];
+            }
+            if (propertyDefinition(property)?.type !== "json") {
+                return [nameToWire(name), whereToWire(condition)];
+            }
+        }
+        return [nameToWire(name), selectValue(condition, property, false)];
+    }));
+}
+export function findToWire(options, definition) {
+    return {
+        ...options,
+        ...(options.where === undefined ? {} : { where: whereToWire(options.where, definition) }),
+        ...(options.orderBy === undefined
+            ? {}
+            : {
+                orderBy: options.orderBy.map((order) => ({ ...order, field: nameToWire(order.field) })),
+            }),
+        ...(options.include === undefined
+            ? {}
+            : {
+                include: Object.fromEntries(Object.entries(options.include).map(([name, value]) => [nameToWire(name), value])),
+            }),
+    };
+}
+/** Current action edits use the same property names and values as authored entity records. */
+export function editsFromWire(edits, entities) {
+    return edits.map((edit) => {
+        const definition = entities.find((entity) => nameToWire(entity.name) === edit.entity)?.definition;
+        const before = recordFromWire(Object.fromEntries(Object.entries(edit.changes).map(([field, change]) => [field, change.before])), definition);
+        const after = recordFromWire(Object.fromEntries(Object.entries(edit.changes).map(([field, change]) => [field, change.after])), definition);
+        return {
+            ...edit,
+            entity: toCamelCase(edit.entity),
+            changes: Object.fromEntries(Object.keys(before).map((field) => [
+                field,
+                { before: before[field], after: after[field] },
+            ])),
+        };
+    });
+}
+/** Generated actions return entity records; authored action results remain application data. */
+export function generatedResultFromWire(value, action, definition) {
+    if (action === "create" || action === "update") {
+        return recordFromWire(value, definition);
+    }
+    if (action.startsWith("upsert_by_") && isRecord(value)) {
+        return { ...value, record: recordFromWire(value.record, definition) };
+    }
+    return value;
+}

package/dist/authoring.d.ts

@@ -0,0 +1,12 @@
+import type { OntologyConfig } from "./analyze.js";
+import type { DiagnosticCode } from "./diagnostics.js";
+import { type AnyEntity } from "./entity.js";
+import type { Principal } from "./runtime.js";
+type Report = (code: DiagnosticCode, path: string, message: string) => void;
+export declare function principalFromWire(principal: Principal): Principal;
+/** Canonical definitions feed REST, storage and future transports; the public config stays camelCase. */
+export declare function authoringToWire(config: OntologyConfig, user: AnyEntity, report: Report): {
+    readonly config: OntologyConfig;
+    readonly user: AnyEntity;
+};
+export {};

package/dist/authoring.js

@@ -0,0 +1,237 @@
+import { Schema } from "effect";
+import { isAction } from "./action.js";
+import { actionInputToWire } from "./authoring-input.js";
+import { isRecord, nameToWire, permissionToWire } from "./authoring-names.js";
+import { isEntity } from "./entity.js";
+import { toCamelCase } from "./names.js";
+import { p, propertyDefinition } from "./property.js";
+import { isRelationship } from "./relationship.js";
+import { isRole, member } from "./role.js";
+export function principalFromWire(principal) {
+    return {
+        ...principal,
+        roles: principal.roles.map(toCamelCase),
+        permissions: principal.permissions.map(toCamelCase),
+    };
+}
+function indexToWire(index) {
+    if (Array.isArray(index)) {
+        return index.map(nameToWire);
+    }
+    const definition = index;
+    return { ...definition, properties: (definition.properties ?? []).map(nameToWire) };
+}
+function expressionToWire(value) {
+    if (!isRecord(value)) {
+        return value;
+    }
+    const expression = { ...value };
+    if (typeof value.name === "string" && (value.op === "measure" || value.op === "column")) {
+        expression.name = nameToWire(value.name);
+    }
+    if (Array.isArray(value.args)) {
+        expression.args = value.args.map(expressionToWire);
+    }
+    return expression;
+}
+/** Preserve shared definitions and lazy relationship targets while building the canonical model. */
+class AuthoringEncoder {
+    report;
+    entities = new WeakMap();
+    definitions = new WeakMap();
+    properties = new WeakMap();
+    roles = new WeakMap();
+    constructor(report) {
+        this.report = report;
+    }
+    name(name, path) {
+        const encoded = nameToWire(name);
+        if (typeof name === "string" &&
+            /^[a-z][a-zA-Z0-9]*$/.test(name) &&
+            name !== toCamelCase(encoded)) {
+            this.report("invalid-name", path, `Use lower camelCase ${toCamelCase(encoded)} ` +
+                "so the TypeScript and wire names round-trip.");
+        }
+        return encoded;
+    }
+    named(values, path, convert) {
+        const result = Object.create(null);
+        for (const [name, value] of Object.entries(values ?? {})) {
+            const fieldPath = `${path}.${name}`;
+            const wireName = this.name(name, fieldPath);
+            if (Object.hasOwn(result, wireName)) {
+                this.report("duplicate-name", fieldPath, `Names collide on ${wireName} after snake_case conversion.`);
+            }
+            result[wireName] = convert(value, fieldPath);
+        }
+        return result;
+    }
+    property(value, path) {
+        if (!Schema.isSchema(value)) {
+            return value;
+        }
+        const cached = this.properties.get(value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let normalized = value;
+        const definition = propertyDefinition(value);
+        if (definition?.type === "select") {
+            const options = (definition.options ?? []).map((option) => ({
+                ...option,
+                description: option.description ?? "",
+                value: nameToWire(option.value),
+            }));
+            for (const option of definition.options ?? []) {
+                this.name(option.value, `${path}.options`);
+            }
+            const settings = { ...definition };
+            if (typeof settings.default === "string") {
+                settings.default = nameToWire(settings.default);
+            }
+            normalized = p.select(options, settings);
+        }
+        this.properties.set(value, normalized);
+        return normalized;
+    }
+    target(value) {
+        if (typeof value === "string") {
+            return nameToWire(value);
+        }
+        if (typeof value === "function") {
+            return () => this.entity(value());
+        }
+        return this.entity(value);
+    }
+    relationship(value) {
+        if (!isRelationship(value)) {
+            return value;
+        }
+        const normalized = {
+            ...value,
+            inverse: nameToWire(value.inverse),
+            target: this.target(value.target),
+        };
+        if ("on" in value && value.on !== undefined) {
+            return {
+                ...normalized,
+                on: Object.fromEntries(Object.entries(value.on).map(([property, target]) => [
+                    nameToWire(property),
+                    nameToWire(target),
+                ])),
+            };
+        }
+        return normalized;
+    }
+    definition(entity) {
+        const original = entity.definition;
+        const cached = this.definitions.get(original);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const normalized = {
+            ...original,
+            title: nameToWire(original.title),
+            ...(original.source?.currency === undefined
+                ? {}
+                : { source: { ...original.source, currency: nameToWire(original.source.currency) } }),
+            properties: this.named(original.properties, `${entity.name}.properties`, (value, path) => this.property(value, path)),
+            relationships: this.named(original.relationships ?? {}, `${entity.name}.relationships`, (value) => this.relationship(value)),
+            ...(original.indexes === undefined ? {} : { indexes: original.indexes.map(indexToWire) }),
+            ...(original.measures === undefined
+                ? {}
+                : {
+                    measures: this.named(original.measures, `${entity.name}.measures`, (value) => expressionToWire(value)),
+                }),
+        };
+        this.definitions.set(original, normalized);
+        return normalized;
+    }
+    action(value, path) {
+        if (!isAction(value)) {
+            return value;
+        }
+        let input = value.input;
+        try {
+            if (Schema.isSchema(input)) {
+                input = actionInputToWire(input);
+            }
+        }
+        catch (error) {
+            this.report("invalid-action-input", `${path}.input`, error instanceof Error ? error.message : String(error));
+        }
+        const normalized = {
+            ...value,
+            input,
+            permission: value.permission === undefined ? undefined : permissionToWire(value.permission),
+        };
+        if (typeof value.handler === "function") {
+            normalized.handler = (context) => value.handler({ ...context, principal: principalFromWire(context.principal) });
+        }
+        if (typeof value.prepare === "function") {
+            const prepare = value.prepare;
+            normalized.prepare = (context) => prepare({ ...context, principal: principalFromWire(context.principal) });
+        }
+        return normalized;
+    }
+    entity(value) {
+        if (!isEntity(value)) {
+            return value;
+        }
+        const cached = this.entities.get(value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        // Register the handle before resolving relationships, which can point back to it.
+        const normalized = { ...value, name: this.name(value.name, value.name) };
+        this.entities.set(value, normalized);
+        const definition = this.definition(value);
+        Object.assign(normalized, {
+            definition,
+            properties: definition.properties,
+            relationships: definition.relationships,
+        });
+        if (isRecord(value.actions)) {
+            Object.assign(normalized, {
+                actions: this.named(value.actions, `${value.name}.actions`, (action, path) => this.action(action, path)),
+            });
+        }
+        return normalized;
+    }
+    role(value) {
+        if (!isRole(value) || value === member) {
+            return value;
+        }
+        const cached = this.roles.get(value);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const normalized = {
+            ...value,
+            name: this.name(value.name, `roles.${value.name}`),
+            permissions: Array.isArray(value.permissions)
+                ? value.permissions.map(permissionToWire)
+                : value.permissions,
+        };
+        this.roles.set(value, normalized);
+        return normalized;
+    }
+}
+/** Canonical definitions feed REST, storage and future transports; the public config stays camelCase. */
+export function authoringToWire(config, user, report) {
+    const encoder = new AuthoringEncoder(report);
+    const normalized = {
+        ...config,
+        entities: (config.entities ?? []).map((entity) => encoder.entity(entity)),
+        ...(config.roles === undefined
+            ? {}
+            : { roles: config.roles.map((role) => encoder.role(role)) }),
+    };
+    if (isRecord(config.member) && Array.isArray(config.member.permissions)) {
+        normalized.member = {
+            ...config.member,
+            permissions: config.member.permissions.map(permissionToWire),
+        };
+    }
+    return { config: normalized, user: encoder.entity(user) };
+}

package/dist/entity.d.ts

@@ -3,7 +3,6 @@ import type { Measures } from "./measure.js";
 import type { WarehouseSource } from "./source.js";
 import type { Actions } from "./action.js";
 import type { Conflict, NotFound } from "./errors.js";
-import type { SystemProperty } from "./names.js";
 import { type AnyProperty } from "./property.js";
 import type { AnyRelationship, ManyRelationship, OneRelationship } from "./relationship.js";
 import { OntologyReads, OntologyWrites, type FindOptions, type GetOptions, type UpsertResult } from "./runtime.js";
@@ -20,11 +19,11 @@ export interface SystemFields {
     /** A UUID. */
     readonly id: string;
     /** ISO 8601 timestamps. */
-    readonly created_at: string;
-    readonly updated_at: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
     /** The `user` who created or last updated the record; `null` when the platform wrote it. */
-    readonly created_by: string | null;
-    readonly updated_by: string | null;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
 }
 /** A record id, or a record. */
 export type RecordRef = string | {
@@ -58,9 +57,9 @@ type UniqueKeys<P> = {
     } ? K : never;
 }[keyof P] & string;
 type RelationshipIds<R> = {
-    readonly [K in OneKeys<R> as `${K}_id`]: R[K] extends OneRelationship<true> ? string | null : string;
+    readonly [K in OneKeys<R> as `${K}Id`]: R[K] extends OneRelationship<true> ? string | null : string;
 };
-/** A record of the entity: system fields, declared properties, and `<relationship>_id` per `rel.one`. */
+/** A record of the entity: system fields, declared properties, and `<relationship>Id` per `rel.one`. */
 export type EntityRecord<P, R> = Simplify<SystemFields & {
     readonly [K in keyof P]: ValueOf<P[K]>;
 } & RelationshipIds<R>>;
@@ -88,7 +87,7 @@ export type UpdateValues<P, R> = Simplify<{
     readonly [K in ManyKeys<R>]?: ReadonlyArray<string>;
 }>;
 /** Fields an index may cover: declared properties, system properties and `rel.one` relationships. */
-export type IndexField<P, R> = (keyof P & string) | SystemProperty | OneKeys<R>;
+export type IndexField<P, R> = (keyof P & string) | keyof SystemFields | OneKeys<R>;
 /** An index: the covered fields in order, or the fields with options. */
 export type IndexDefinition<Field extends string = string> = ReadonlyArray<Field> | {
     readonly properties: ReadonlyArray<Field>;

package/dist/entity.js

@@ -1,5 +1,7 @@
 import { Effect } from "effect";
 import { p } from "./property.js";
+import { recordFromWire, valuesToWire, findToWire } from "./authoring-records.js";
+import { toSnakeCase } from "./names.js";
 import { OntologyReads, OntologyWrites, } from "./runtime.js";
 export const EntityTypeId = Symbol.for("@segmentstream-cloud/ontology/Entity");
 function idOf(record) {
@@ -25,17 +27,38 @@ export function entity(name, definition) {
         relationships: definition.relationships ?? {},
         ref: p.ref(name),
         get: (record, options) => withReads((runtime) => runtime.get({
-            entity: name,
+            entity: toSnakeCase(name),
             id: idOf(record),
             ...(options?.forUpdate === true ? { forUpdate: true } : {}),
+        })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        find: (options) => withReads((runtime) => runtime.find({ entity: toSnakeCase(name), options: findToWire(options ?? {}, definition) })).pipe(Effect.map((records) => records.map((record) => recordFromWire(record, definition)))),
+        create: (values) => withWrites((runtime) => runtime.create({ entity: toSnakeCase(name), values: valuesToWire(values, definition) })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        update: (record, values) => withWrites((runtime) => runtime.update({
+            entity: toSnakeCase(name),
+            id: idOf(record),
+            values: valuesToWire(values, definition),
+        })).pipe(Effect.map((record) => recordFromWire(record, definition))),
+        upsertBy: (property, values) => withWrites((runtime) => runtime.upsertBy({
+            entity: toSnakeCase(name),
+            property: toSnakeCase(property),
+            values: valuesToWire(values, definition),
+        })).pipe(Effect.map((result) => ({
+            ...result,
+            record: recordFromWire(result.record, definition),
+        }))),
+        delete: (record) => withWrites((runtime) => runtime.delete({ entity: toSnakeCase(name), id: idOf(record) })),
+        link: (relationship, record, target) => withWrites((runtime) => runtime.link({
+            entity: toSnakeCase(name),
+            relationship: toSnakeCase(relationship),
+            id: idOf(record),
+            targetId: idOf(target),
+        })),
+        unlink: (relationship, record, target) => withWrites((runtime) => runtime.unlink({
+            entity: toSnakeCase(name),
+            relationship: toSnakeCase(relationship),
+            id: idOf(record),
+            targetId: idOf(target),
         })),
-        find: (options) => withReads((runtime) => runtime.find({ entity: name, options: options ?? {} })),
-        create: (values) => withWrites((runtime) => runtime.create({ entity: name, values })),
-        update: (record, values) => withWrites((runtime) => runtime.update({ entity: name, id: idOf(record), values })),
-        upsertBy: (property, values) => withWrites((runtime) => runtime.upsertBy({ entity: name, property, values })),
-        delete: (record) => withWrites((runtime) => runtime.delete({ entity: name, id: idOf(record) })),
-        link: (relationship, record, target) => withWrites((runtime) => runtime.link({ entity: name, relationship, id: idOf(record), targetId: idOf(target) })),
-        unlink: (relationship, record, target) => withWrites((runtime) => runtime.unlink({ entity: name, relationship, id: idOf(record), targetId: idOf(target) })),
     };
     // Every form of the entity shares `definition`, which is how defineOntology recognises them.
     const self = { ...handle, actions: {} };

package/dist/migrate/plan.js

@@ -1,4 +1,4 @@
-import { 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) {
@@ -296,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/names.d.ts

@@ -1,12 +1,15 @@
 /** Ontology names: lowercase snake_case. */
 export declare const SNAKE_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", "created_at", "updated_at", "created_by", "updated_by"];
-export type SystemProperty = (typeof SYSTEM_PROPERTIES)[number];
+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 `upsert_by_<property>` actions. */

package/dist/names.js

@@ -1,5 +1,31 @@
 /** Ontology names: lowercase snake_case. */
 export const SNAKE_CASE_NAME = /^[a-z][a-z0-9]*(?:_[a-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`. */

package/dist/permissions.js

@@ -1,4 +1,4 @@
-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 snake_case name of an authored action. A role may use `*` for
@@ -12,7 +12,7 @@ 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 lowercase snake_case verbs, or `*` for either. */
-const PERMISSION = /^(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*):(\*|[a-z][a-z0-9]*(?:_[a-z0-9]+)*)$/;
+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
@@ -51,7 +51,7 @@ export function missingPermission(required, principal) {
  * 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/runtime/generated-actions.js

@@ -5,7 +5,6 @@ import { generatedActionPermissions } from "../permissions.js";
 import { p, REFERENCE_ANNOTATION } from "../property.js";
 import { isCalendarDate, isInstant } from "../query.js";
 import { OntologyWrites } from "../runtime.js";
-import { User } from "../user.js";
 import { entityModel, ontologyModel, propertyValueSchema, } from "./model.js";
 /** Generated actions, built once per ontology and entity. */
 const builtActions = new WeakMap();
@@ -98,7 +97,7 @@ export function generatedActions(ontology, entityName) {
 }
 function buildGeneratedActions(ontology, entityName) {
     const entity = entityModel(ontologyModel(ontology), entityName);
-    if (entity.resolved.entity.definition === User.definition) {
+    if (entity.resolved.builtIn) {
         return {};
     }
     const label = entity.label.toLowerCase();

package/dist/runtime/principals.js

@@ -6,7 +6,7 @@ import { SqlClient } from "effect/unstable/sql";
 import { isSqlError } from "effect/unstable/sql/SqlError";
 import { entity, } from "../entity.js";
 import { API_KEYS_TABLE, USER_ROLES_TABLE, USER_TABLE } from "../migrate/storage.js";
-import { MEMBER_ROLE } from "../names.js";
+import { MEMBER_ROLE, toSnakeCase } from "../names.js";
 import { buildOntology } from "../ontology.js";
 import { permissionsOf } from "../permissions.js";
 import { EMAIL_PATTERN } from "../property.js";
@@ -318,7 +318,7 @@ function deployedUser(manifest) {
         return User;
     }
     const names = new Set(deployed.properties.map((property) => property.name));
-    const kept = Object.entries(User.definition.properties).filter(([name, property]) => names.has(name) ||
+    const kept = Object.entries(User.definition.properties).filter(([name, property]) => names.has(toSnakeCase(name)) ||
         (propertyDefinition(property)?.renamedFrom !== undefined &&
             names.has(propertyDefinition(property).renamedFrom)));
     if (kept.length === Object.keys(User.definition.properties).length) {

package/dist/service/config.d.ts

@@ -48,7 +48,7 @@ export interface ActionCommitted {
     readonly entity: string;
     readonly action: string;
     readonly principal: Principal;
-    /** The input as the caller sent it. */
+    /** The decoded input, using the authored TypeScript schema. */
     readonly input: unknown;
     readonly result: unknown;
     readonly edits: ReadonlyArray<unknown>;

package/dist/service/handlers.js

@@ -1,6 +1,10 @@
 import { HttpServerResponse } from "effect/unstable/http";
 import { Effect, Layer, Schema } from "effect";
 import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi";
+import { editsFromWire, generatedResultFromWire, recordFromWire } from "../authoring-records.js";
+import { nameToWire } from "../authoring-names.js";
+import { principalFromWire } from "../authoring.js";
+import { toCamelCase } from "../names.js";
 import { PermissionDenied } from "../errors.js";
 import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
 import { EMAIL_PATTERN } from "../property.js";
@@ -141,26 +145,31 @@ function readEnvelope(request) {
  * The configured hook as `runAction` runs it after the commit. A failure is logged with the request
  * id here, so the action's caller still gets the committed result.
  */
-function afterCommitOf(hook, request) {
-    return (committed) => Effect.tryPromise(async () => hook({
-        entity: committed.entity,
-        action: committed.action,
-        principal: committed.principal,
-        input: request.input,
-        result: committed.result,
-        edits: committed.edits,
-        requestId: request.requestId,
-    })).pipe(Effect.catchCause((cause) => Effect.logError("ontology.after_commit.failed", cause).pipe(Effect.annotateLogs({
-        requestId: request.requestId,
-        action: `${committed.entity}.${committed.action}`,
-    }))));
+function afterCommitOf(hook, request, ontology) {
+    return (committed) => {
+        const definition = ontology.config.entities.find((entity) => nameToWire(entity.name) === committed.entity)?.definition;
+        return Effect.tryPromise(async () => hook({
+            entity: toCamelCase(committed.entity),
+            action: toCamelCase(committed.action),
+            principal: principalFromWire(committed.principal),
+            input: request.generated ? recordFromWire(committed.input, definition) : committed.input,
+            result: request.generated
+                ? generatedResultFromWire(committed.result, committed.action, definition)
+                : committed.result,
+            edits: editsFromWire(committed.edits, ontology.config.entities),
+            requestId: request.requestId,
+        })).pipe(Effect.catchCause((cause) => Effect.logError("ontology.after_commit.failed", cause).pipe(Effect.annotateLogs({
+            requestId: request.requestId,
+            action: `${committed.entity}.${committed.action}`,
+        }))));
+    };
 }
 /** The deployment's OIDC token: Vercel sets it on each request, and in the environment of builds. */
 function identityToken(request) {
     const header = request.headers[OIDC_TOKEN_HEADER];
     return typeof header === "string" && header !== "" ? header : process.env.VERCEL_OIDC_TOKEN;
 }
-function runAction(planned, { name }, hook, connections) {
+function runAction(planned, { name, generated }, ontology, hook, connections) {
     return ({ request }) => Effect.gen(function* () {
         const backend = yield* OntologyBackend;
         const principal = yield* CurrentPrincipal;
@@ -180,7 +189,7 @@ function runAction(planned, { name }, hook, connections) {
             }),
             ...(hook === undefined
                 ? {}
-                : { afterCommit: afterCommitOf(hook, { input: envelope.input, requestId }) }),
+                : { afterCommit: afterCommitOf(hook, { requestId, generated }, ontology) }),
         });
         const { issues } = outcome.validation;
         if (!outcome.validation.ok && !validateOnly) {
@@ -214,7 +223,7 @@ function entityHandlers(built, planned, hooks, targets, connections) {
             registered = registered.handle(`related.${traversal.name}`, (request) => traverse(planned, traversal, request, targets).pipe(Effect.provideService(OntologyBackend, backend)));
         }
         for (const action of planned.actions) {
-            const handler = runAction(planned, action, hooks.get(`${planned.name}.${action.name}`), connections);
+            const handler = runAction(planned, action, built.plan.ontology, hooks.get(`${planned.name}.${action.name}`), connections);
             registered = registered.handleRaw(`actions.${action.name}`, (request) => handler(request).pipe(Effect.provideService(OntologyBackend, backend)));
         }
         return registered;

package/dist/service/service.js

@@ -1,6 +1,7 @@
 import { Cause, Context, Effect, Layer } from "effect";
 import { HttpRouter, HttpServer, HttpServerError } from "effect/unstable/http";
 import { HttpApiBuilder } from "effect/unstable/httpapi";
+import { nameToWire } from "../authoring-names.js";
 import { sqlServiceRuntime } from "../runtime/service-binding.js";
 import { ErrorResponsesLive, buildApi } from "./api.js";
 import { authenticationLayer, tokenVerifier } from "./authentication.js";
@@ -15,13 +16,19 @@ export const ONTOLOGY_HASH_HEADER = "x-ontology-hash";
 export const REQUEST_ID_HEADER = "x-request-id";
 function afterCommitHooks(plan, hooks = {}) {
     const actions = new Set(plan.entities.flatMap(({ name, actions: planned }) => planned.map((action) => `${name}.${action.name}`)));
-    const unknown = Object.keys(hooks).filter((key) => !actions.has(key));
+    const entries = Object.entries(hooks).map(([key, hook]) => [key.split(".").map(nameToWire).join("."), hook]);
+    const unknown = Object.keys(hooks).filter((key) => !actions.has(key.split(".").map(nameToWire).join(".")));
     if (unknown.length > 0) {
         throw new OntologyServiceConfigError({
             message: `afterCommit names actions the ontology does not have: ${unknown.join(", ")}.`,
         });
     }
-    return new Map(Object.entries(hooks));
+    if (new Set(entries.map(([key]) => key)).size !== entries.length) {
+        throw new OntologyServiceConfigError({
+            message: "afterCommit names collide after snake_case conversion.",
+        });
+    }
+    return new Map(entries);
 }
 /**
  * Requests that match no route, and defects that escape a route's own error handling, still get a

package/dist/user.d.ts

@@ -13,8 +13,8 @@ export declare const User: import("./entity.js").DraftEntity<"user", {
     readonly email: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, true>>;
     readonly kind: import("./property.js").Property<"member" | "service", false, false>;
     readonly active: import("./property.js").Property<boolean, true, false>;
-    readonly identity_provider: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
-    readonly identity_subject: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
-    readonly last_sign_in_at: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly identityProvider: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly identitySubject: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly lastSignInAt: import("effect/Schema").optionalKey<import("./property.js").Property<string, false, false>>;
 }, import("./entity.js").Relationships>;
 export type User = typeof User.Type;

package/dist/user.js

@@ -41,13 +41,13 @@ export const User = entity("user", {
             managed: true,
             description: "Inactive users cannot sign in or run actions.",
         }),
-        identity_provider: p.text({
+        identityProvider: p.text({
             renamedFrom: "identityProvider",
             optional: true,
             managed: true,
             description: "Who signs the member in, for example neon-auth. Empty for services.",
         }),
-        identity_subject: p.text({
+        identitySubject: p.text({
             renamedFrom: "identitySubject",
             optional: true,
             managed: true,
@@ -55,7 +55,7 @@ export const User = entity("user", {
         }),
         // Optional so that a table created before it gains the column without a backfill: a member
         // who has not signed in since simply has none.
-        last_sign_in_at: p.timestamp({
+        lastSignInAt: p.timestamp({
             renamedFrom: "lastSignInAt",
             optional: true,
             managed: true,
@@ -63,5 +63,5 @@ export const User = entity("user", {
             description: "When the member last signed in to the app. Empty until they do.",
         }),
     },
-    indexes: [{ properties: ["identity_provider", "identity_subject"], unique: true }],
+    indexes: [{ properties: ["identityProvider", "identitySubject"], unique: true }],
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@segmentstream-cloud/ontology",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Define a SegmentStream workspace app's ontology: entities, relationships, roles and actions, written with Effect.",
   "license": "Apache-2.0",
   "author": "SegmentStream",