@segmentstream-cloud/ontology 0.6.0 → 0.7.0

package/README.md

@@ -8,6 +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.
+
 ## Install
 
 ```sh
@@ -51,7 +58,7 @@ export const Lead = entity("lead", {
   relationships: {
     owner: rel.one(User, {
       optional: true,
-      inverse: "ownedLeads",
+      inverse: "owned_leads",
       onDelete: "setNull",
       phrase: ["is owned by", "owns"],
       description: "The team member responsible for the next step.",
@@ -121,7 +128,7 @@ entity, the verb or both: `lead:*`, `*:read`, `*:*`.
 - Reads require `<entity>:read`: lists, queries, records, history, and both entities of a
   relationship traversal. `include` and a filter through a relationship require `read` on
   the related entity. A missing permission answers 403 with `<permission> is required.`
-- Each action requires one permission. The generated `upsertBy<Property>` requires both
+- Each action requires one permission. The generated `upsert_by_<property>` requires both
   `<entity>:create` and `<entity>:update`.
 - A principal's permissions are the union of its roles' permissions in the ontology.
   Members hold `member` and their assigned roles; an API key holds exactly the roles it was
@@ -182,7 +189,7 @@ Sign-in finds the user linked to the token's provider and subject, else links th
 invited with the same email, else follows the ontology's `signIn` policy: `invited` answers
 403 `{ "error": "not_invited", "detail": "Ask your administrator for an invitation." }`,
 `open` creates a member. Deactivated members are refused. Each sign-in sets the user's
-`lastSignInAt`, at most once per 15 minutes, so the user's history records it.
+`last_sign_in_at`, at most once per 15 minutes, so the user's history records it.
 
 `GET /api/ontology/me` answers who the caller is, for the app to render what they may do:
 `{ user: { id, name, email, kind, active }, roles, permissions }`. It needs only
@@ -234,3 +241,7 @@ usage error.
 ## License
 
 Apache-2.0
+
+## Entity sources and aggregates
+
+Entities with a warehouse source declare mapped properties and measures without storage tables or record operations. See [ontology aggregates](../../docs/ontology-aggregates.md) for declaration rules, source verification, workspace authorization and the overlap release.

package/dist/analyze.js

@@ -3,14 +3,14 @@ import { Schema } from "effect";
 import { isAction } from "./action.js";
 import { CONNECTION_KEY, isConnection } from "./connection.js";
 import { isEntity } from "./entity.js";
-import { CAMEL_CASE_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MEMBER_ROLE, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
+import { LEGACY_MEMBER_NAME, ENTITY_ID, GENERATED_ACTIONS, GENERATED_UPSERT_PREFIX, HISTORY_SUFFIX, MEMBER_ROLE, RESERVED_ENTITY_NAMES, RESERVED_MEMBER_NAMES, RESERVED_RELATIONSHIP_NAMES, SNAKE_CASE_NAME, SYSTEM_PROPERTIES, isSystemProperty, } from "./names.js";
 import { REFERENCE_ANNOTATION, propertyDefinition, referenceTarget, } from "./property.js";
 import { generatedActionPermissions, parsePermission, permissionOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";
 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";
-const GENERATED_UPSERT = new RegExp(`^${GENERATED_UPSERT_PREFIX}[A-Z]`);
+const GENERATED_UPSERT = new RegExp(`^${GENERATED_UPSERT_PREFIX}`);
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
@@ -293,8 +293,8 @@ function entityPermissions(name, builtIn, relationships) {
     };
 }
 function checkMemberName(kind, path, name, report) {
-    if (!CAMEL_CASE_NAME.test(name)) {
-        report("invalid-name", path, `${kind} names are lower camelCase, for example ownedLeads.`);
+    if (!SNAKE_CASE_NAME.test(name)) {
+        report("invalid-name", path, `${kind} names are lowercase snake_case, for example owned_leads.`);
     }
     else if (isSystemProperty(name)) {
         report("reserved-name", path, `${name} is a system property of every entity.`);
@@ -325,7 +325,7 @@ function resolveProperties(candidate, scope) {
         }
         checkProperty(path, schema, definition, report);
         if (definition.renamedFrom !== undefined) {
-            checkRenamedFrom(path, name, definition.renamedFrom, names, CAMEL_CASE_NAME, report);
+            checkRenamedFrom(path, name, definition.renamedFrom, names, LEGACY_MEMBER_NAME, report);
         }
         properties.push({ name, schema: schema, definition });
     }
@@ -356,8 +356,8 @@ function checkSelectOptions(path, definition, report) {
     }
     options.forEach((option, index) => {
         const optionPath = `${path}.options[${index}]`;
-        if (isBlank(option.value)) {
-            report("invalid-options", optionPath, "option values cannot be empty.");
+        if (!SNAKE_CASE_NAME.test(option.value)) {
+            report("invalid-options", optionPath, "option values must be lowercase snake_case.");
         }
         else if (seen.has(option.value)) {
             report("invalid-options", optionPath, `the option value "${option.value}" is listed twice.`);
@@ -500,8 +500,8 @@ function resolveActions(candidate, scope) {
     const actions = [];
     for (const [name, action] of actionEntries(candidate, report)) {
         const path = `${candidate.name}.actions.${name}`;
-        if (!CAMEL_CASE_NAME.test(name)) {
-            report("invalid-name", path, "action names are lower camelCase, for example changeStatus.");
+        if (!SNAKE_CASE_NAME.test(name)) {
+            report("invalid-name", path, "action names are lowercase snake_case, for example change_status.");
         }
         else if (GENERATED_ACTIONS.includes(name) ||
             GENERATED_UPSERT.test(name)) {
@@ -546,17 +546,23 @@ function resolvePermission(path, fallback, action, scope) {
 }
 function resolveInput(path, input, scope) {
     const inputPath = `${path}.input`;
-    if (!Schema.isSchema(input) || input.ast._tag !== "Objects" || !("fields" in input)) {
+    if (!Schema.isSchema(input) || Schema.toEncoded(input).ast._tag !== "Objects") {
         scope.report("invalid-action-input", inputPath, "must be a Schema.Struct of the action's inputs.");
         return undefined;
     }
-    checkInputFields(inputPath, input.fields, scope);
+    if ("fields" in input) {
+        checkInputFields(inputPath, input.fields, scope);
+    }
     try {
         const document = Schema.toJsonSchemaDocument(input, {
             includeAnnotationKey: (key) => key === REFERENCE_ANNOTATION,
             onExcessProperty: "error",
         });
         const schema = document.schema;
+        checkEncodedInputNames(schema, inputPath, scope, !("fields" in input));
+        for (const definition of Object.values(document.definitions)) {
+            checkEncodedInputNames(definition, inputPath, scope, !("fields" in input));
+        }
         return Object.keys(document.definitions).length === 0
             ? schema
             : { ...schema, $defs: document.definitions };
@@ -566,6 +572,33 @@ function resolveInput(path, input, scope) {
         return undefined;
     }
 }
+/** Check named input fields on the wire side; codecs may decode them to camelCase handler values. */
+function checkEncodedInputNames(schema, path, scope, checkReferences) {
+    const { report } = scope;
+    const reference = schema[REFERENCE_ANNOTATION];
+    if (checkReferences && typeof reference === "string" && !scope.entitiesByName.has(reference)) {
+        report("unknown-reference", path, `references "${reference}", which is not an entity of this ontology.`);
+    }
+    const properties = schema.properties;
+    if (properties !== null && typeof properties === "object" && !Array.isArray(properties)) {
+        for (const [name, child] of Object.entries(properties)) {
+            if (!SNAKE_CASE_NAME.test(name)) {
+                report("invalid-name", `${path}.${name}`, "action input names are lowercase snake_case.");
+            }
+            if (child !== null && typeof child === "object" && !Array.isArray(child)) {
+                checkEncodedInputNames(child, `${path}.${name}`, scope, checkReferences);
+            }
+        }
+    }
+    for (const key of ["items", "additionalProperties", "anyOf", "oneOf", "allOf"]) {
+        const children = schema[key];
+        for (const child of Array.isArray(children) ? children : [children]) {
+            if (child !== null && typeof child === "object" && !Array.isArray(child)) {
+                checkEncodedInputNames(child, path, scope, checkReferences);
+            }
+        }
+    }
+}
 function checkInputFields(path, fields, scope) {
     for (const [name, field] of Object.entries(fields)) {
         const fieldPath = `${path}.${name}`;
@@ -621,7 +654,7 @@ function checkEntityIdentities(entities, report) {
     }
 }
 /**
- * Properties, relationships, `<relationship>Id` fields and the inverses that land on an entity share
+ * Properties, relationships, `<relationship>_id` fields and the inverses that land on an entity share
  * one namespace: they are the record's fields and the API's traversal paths.
  */
 function checkMemberNames(entities, report) {
@@ -666,7 +699,7 @@ function ownMembers(candidate) {
         const path = `${candidate.name}.relationships.${name}`;
         const own = { name, path, inverse: false };
         return relationship.cardinality === "one" && candidate.entity.definition.source === undefined
-            ? [own, { ...own, name: `${name}Id` }]
+            ? [own, { ...own, name: `${name}_id` }]
             : [own];
     });
     return [...properties, ...relationships];

package/dist/connection.js

@@ -1,7 +1,7 @@
 import { Context, Effect, Layer, Schema } from "effect";
 export const ConnectionTypeId = Symbol.for("@segmentstream-cloud/ontology/Connection");
 /** A connection key, as `connections/connections.py` declares it. */
-export const CONNECTION_KEY = /^[a-z][a-z0-9_]{0,63}$/;
+export const CONNECTION_KEY = /^(?=.{1,64}$)[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
 export const CONNECTION_METHODS = [
     "GET",
     "POST",

package/dist/entity.d.ts

@@ -20,11 +20,11 @@ export interface SystemFields {
     /** A UUID. */
     readonly id: string;
     /** ISO 8601 timestamps. */
-    readonly createdAt: string;
-    readonly updatedAt: string;
+    readonly created_at: string;
+    readonly updated_at: string;
     /** The `user` who created or last updated the record; `null` when the platform wrote it. */
-    readonly createdBy: string | null;
-    readonly updatedBy: string | null;
+    readonly created_by: string | null;
+    readonly updated_by: string | null;
 }
 /** A record id, or a record. */
 export type RecordRef = string | {
@@ -58,9 +58,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>>;

package/dist/index.d.ts

@@ -13,7 +13,7 @@ export { entity, isEntity } from "./entity.js";
 export type { ActionsBuilder, AnyEntity, AnyStoredEntity, CreateValues, DraftEntity, Entity, EntityDefinition, EntityRecord, IndexDefinition, IndexField, NoActions, Properties, RecordRef, Relationships, SystemFields, UpdateValues, } from "./entity.js";
 export { ActionRejected, Conflict, NotFound, PermissionDenied } from "./errors.js";
 export type { ActionError } from "./errors.js";
-export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, formatManifest, IndexManifest, MANIFEST_VERSION, manifestHash, OntologyManifest, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
+export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, MANIFEST_VERSION, manifestHash, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
 export { SYSTEM_PROPERTIES } from "./names.js";
 export type { SystemProperty } from "./names.js";
 export { check, defineOntology } from "./ontology.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { CONNECTION_ERROR_REASONS, CONNECTION_KEY, CONNECTION_METHODS, connectio
 export { Diagnostic, DIAGNOSTIC_CODES, formatDiagnostics, InvalidOntology } from "./diagnostics.js";
 export { entity, isEntity } from "./entity.js";
 export { ActionRejected, Conflict, NotFound, PermissionDenied } from "./errors.js";
-export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, formatManifest, IndexManifest, MANIFEST_VERSION, manifestHash, OntologyManifest, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
+export { ActionManifest, actionConnectionKeys, canonicalJson, ConnectionManifest, EntityManifest, EntityPermissionsManifest, decodeManifestDocument, encodeManifest, formatManifest, IndexManifest, MANIFEST_VERSION, manifestHash, OntologyManifest, OntologyManifestWire, PropertyManifest, RelationshipManifest, RoleManifest, SelectOptionManifest, SignInManifest, signInPolicyOf, } from "./manifest.js";
 export { SYSTEM_PROPERTIES } from "./names.js";
 export { check, defineOntology } from "./ontology.js";
 export { DEFAULT_MEMBER_PERMISSIONS, generatedActionPermissions, grants, isAllowed, parsePermission, permissionsOf, READ_VERB, rolesGranting, WILDCARD, } from "./permissions.js";