@segmentstream-cloud/ontology 0.7.0 → 0.9.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.",
@@ -134,7 +135,7 @@ entity, the verb or both: `lead:*`, `*:read`, `*:*`.
   Members hold `member` and their assigned roles; an API key holds exactly the roles it was
   created with. A role the ontology no longer declares grants nothing.
 - The catalog, `describe`, `graph`, `openapi.json` and `me` need only authentication;
-  `status` and `sign-in/check` need none. `?as=me` lists only the actions the caller may run.
+  `status`, `sign-in/check` and the `docs` page need none. `?as=me` lists only the actions the caller may run.
 - `check` fails on a role without permissions, on a permission whose entity or verb does not
   exist, and on `allow`, which version 0.2 replaced. It warns on an action no role may run
   and on `*:*`.
@@ -154,6 +155,12 @@ export function handleOntologyRequest(request: Request): Promise<Response> {
 }
 ```
 
+`GET /api/ontology/docs` serves a Scalar API reference over `openapi.json`. A browser signed
+in to the app authenticates with the app's Neon Auth session cookie
+(`__Secure-neon-auth.session_token`), which the service exchanges at Neon Auth for the
+session's token and verifies like a bearer token. A bearer token always takes precedence. The
+cookie authenticates a `POST` only when its `Origin` is the app's own.
+
 `handler(request)` takes a web `Request` and returns a `Response`. `dispose()` closes the
 database pool. `configFromEnv()` reads these variables (`ENVIRONMENT_VARIABLES`, and the
 optional `NEON_AUTH_ENVIRONMENT_VARIABLES`). It throws `OntologyServiceConfigError` when

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) };
+}