@segmentstream-cloud/ontology 0.18.0 → 0.18.1

package/dist/authoring-records.js

@@ -1,6 +1,7 @@
 import { isEntity } from "./entity.js";
 import { toCamelCase } from "./names.js";
 import { propertyDefinition } from "./property.js";
+import { isIncludeList } from "./query.js";
 import { isRecord, nameToWire } from "./authoring-names.js";
 function targetDefinition(target) {
     const resolved = typeof target === "function" ? target() : target;
@@ -113,13 +114,15 @@ export function findToWire(options, definition) {
             : {
                 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])),
-            }),
+        ...(options.include === undefined ? {} : { include: includeToWire(options.include) }),
     };
 }
+/** The relationships a find includes, by wire name, in the form the handler gave them. */
+function includeToWire(include) {
+    return isIncludeList(include)
+        ? include.map(nameToWire)
+        : Object.fromEntries(Object.entries(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) => {

package/dist/query.d.ts

@@ -16,14 +16,15 @@ export type StorageType = PropertyType | "uuid";
  *     "or": [{ "fitScore": { "gte": 80 } }, { "source": "pilot_request" }]
  *   },
  *   "orderBy": [{ "field": "created_at", "direction": "desc" }],
- *   "include": { "owner": true },
+ *   "include": ["owner"],
  *   "limit": 50
  * }
  * ```
  *
  * {@link Query} checks the structure for any entity; {@link entityQuerySchema} builds the precise
  * schema of one entity from the manifest, with its fields, their operators and its relationships.
- * The runtime validates every query with the precise schema.
+ * The runtime validates every query with the precise schema. `include` also takes the object form
+ * `{ "owner": true }`, which a list of names decodes into.
  */
 export declare const DEFAULT_QUERY_LIMIT = 50;
 export declare const MAX_QUERY_LIMIT = 200;
@@ -78,6 +79,14 @@ export declare const OrderBy: Schema.Struct<{
     readonly direction: Schema.optionalKey<Schema.Literals<readonly ["asc", "desc"]>>;
 }>;
 export type OrderBy = typeof OrderBy.Type;
+/** The relationships to include, once decoded: `{ owner: true, tags: true }`. */
+export type Included = {
+    readonly [relationship: string]: true;
+};
+/** Whether an `include` is the list form, `["owner", "tags"]`. */
+export declare function isIncludeList<L extends string>(include: ReadonlyArray<L> | object): include is ReadonlyArray<L>;
+/** The relationship names an `include` lists, in either form. */
+export declare function includedRelationships(include: Query["include"]): ReadonlyArray<string>;
 /** A query on any entity. The runtime checks the fields against the entity. */
 export declare const Query: Schema.Struct<{
     readonly where: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
@@ -85,17 +94,18 @@ export declare const Query: Schema.Struct<{
         readonly field: Schema.String;
         readonly direction: Schema.optionalKey<Schema.Literals<readonly ["asc", "desc"]>>;
     }>>>;
-    readonly include: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Literal<true>>>;
+    readonly include: Schema.optionalKey<Schema.Codec<Included, readonly string[] | Included, never, never>>;
     readonly after: Schema.optionalKey<Schema.String>;
     readonly limit: Schema.optionalKey<Schema.Int>;
 }>;
-/** A query. `where` follows {@link Where}; `include` adds related records by relationship name. */
+/**
+ * A query. `where` follows {@link Where}; `include` adds related records by relationship name, as a
+ * list, `["owner", "tags"]`, or as an object, `{ owner: true, tags: true }`.
+ */
 export interface Query {
     readonly where?: Where;
     readonly orderBy?: ReadonlyArray<OrderBy>;
-    readonly include?: {
-        readonly [relationship: string]: true;
-    };
+    readonly include?: ReadonlyArray<string> | Included;
     readonly after?: string;
     readonly limit?: number;
 }
@@ -160,9 +170,7 @@ export declare function isOrderable(field: QueryField): boolean;
 export interface EntityQuerySchemas {
     readonly where: Schema.Codec<Where>;
     readonly orderBy: Schema.Codec<ReadonlyArray<OrderBy>>;
-    readonly include: Schema.Codec<{
-        readonly [relationship: string]: true;
-    }>;
+    readonly include: Schema.Codec<Included, ReadonlyArray<string> | Included>;
     readonly limit: Schema.Codec<number>;
     readonly after: Schema.Codec<string>;
     readonly query: Schema.Codec<Query>;

package/dist/query.js

@@ -1,5 +1,5 @@
-import { Schema } from "effect";
-import { wireStruct } from "./wire.js";
+import { Schema, SchemaTransformation } from "effect";
+import { expectedOneOf, wireStruct } from "./wire.js";
 import { isValueMatched } from "./manifest.js";
 import { BlobValue } from "./blob.js";
 /**
@@ -14,14 +14,15 @@ import { BlobValue } from "./blob.js";
  *     "or": [{ "fitScore": { "gte": 80 } }, { "source": "pilot_request" }]
  *   },
  *   "orderBy": [{ "field": "created_at", "direction": "desc" }],
- *   "include": { "owner": true },
+ *   "include": ["owner"],
  *   "limit": 50
  * }
  * ```
  *
  * {@link Query} checks the structure for any entity; {@link entityQuerySchema} builds the precise
  * schema of one entity from the manifest, with its fields, their operators and its relationships.
- * The runtime validates every query with the precise schema.
+ * The runtime validates every query with the precise schema. `include` also takes the object form
+ * `{ "owner": true }`, which a list of names decodes into.
  */
 export const DEFAULT_QUERY_LIMIT = 50;
 export const MAX_QUERY_LIMIT = 200;
@@ -56,11 +57,32 @@ const Limit = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: MAX_QUERY
 const After = Schema.String.annotate({
     description: "The nextCursor of the previous page. It is only valid for the same where and orderBy.",
 });
+/** Whether an `include` is the list form, `["owner", "tags"]`. */
+export function isIncludeList(include) {
+    return Array.isArray(include);
+}
+/** The relationship names an `include` lists, in either form. */
+export function includedRelationships(include) {
+    if (include === undefined) {
+        return [];
+    }
+    return isIncludeList(include) ? [...new Set(include)] : Object.keys(include);
+}
+/** `["owner", "tags"]` decoded as `{ owner: true, tags: true }`; duplicate names are harmless. */
+function includeList(names, included) {
+    return Schema.Array(names).pipe(Schema.decodeTo(included, SchemaTransformation.transform({
+        decode: (list) => Object.fromEntries(list.map((name) => [name, true])),
+        encode: (relationships) => Object.keys(relationships),
+    })));
+}
+const AnyIncluded = Schema.Record(Schema.String, Schema.Literal(true));
 /** A query on any entity. The runtime checks the fields against the entity. */
 export const Query = Schema.Struct({
     where: Schema.optionalKey(Schema.Record(Schema.String, Schema.Json)),
     orderBy: Schema.optionalKey(Schema.Array(OrderBy)),
-    include: Schema.optionalKey(Schema.Record(Schema.String, Schema.Literal(true))),
+    include: Schema.optionalKey(
+    // The list member decodes into the object; the union's static type cannot say so.
+    Schema.Union([AnyIncluded, includeList(Schema.String, AnyIncluded)])),
     after: Schema.optionalKey(After),
     limit: Schema.optionalKey(Limit),
 }).annotate({ identifier: "Query" });
@@ -260,7 +282,7 @@ function fieldFilterSchema(field, identifier, wire) {
         operators.between = Schema.optionalKey(Schema.Tuple([value, value]));
     }
     const filter = wire
-        ? wireStruct(operators, { isNull: "is_null", startsWith: "starts_with" })
+        ? wireStruct(operators, { isNull: "is_null", startsWith: "starts_with" }, "Unknown operator")
         : closedStruct(operators, "Unknown operator");
     const note = wire
         ? FILTER_DESCRIPTIONS[identifier]?.replaceAll("startsWith", "starts_with")
@@ -330,7 +352,7 @@ function manyFilterSchema(link, target) {
         some: Schema.optionalKey(target),
         none: Schema.optionalKey(target),
         every: Schema.optionalKey(target),
-    }, "Unknown quantifier; use some, none or every").annotate({
+    }, "Unknown quantifier").annotate({
         description: `Whether some, none or every one of the related ${link.target} records match.`,
     });
 }
@@ -351,18 +373,13 @@ export function entityQuerySchemas(manifest, entityName, wire = false) {
     const entity = requireEntity(manifest, entityName);
     const pascal = pascalCase(entityName);
     const fields = queryFields(entity).filter(isOrderable);
-    const include = {};
-    for (const link of queryLinks(manifest, entityName)) {
-        include[link.name] = Schema.optionalKey(Schema.Literal(true));
-    }
+    const relationships = queryLinks(manifest, entityName).map((link) => link.name);
     const where = whereSchema(manifest, entity, true, new Map(), wire);
     const orderBy = Schema.Array(closedStruct({
         field: Schema.Literals(fields.map((field) => field.name)),
         direction: Schema.optionalKey(SortDirection),
-    }, "Unknown key; use field and direction")).annotate({ description: "Sort keys in order; the id breaks ties. Ascending by default." });
-    const included = closedStruct(include, "Unknown relationship").annotate({
-        description: "Related records to add to each record, by relationship name.",
-    });
+    }, "Unknown key")).annotate({ description: "Sort keys in order; the id breaks ties. Ascending by default." });
+    const included = includeSchema(relationships);
     const queryMembers = {
         where: Schema.optionalKey(where),
         orderBy: Schema.optionalKey(orderBy),
@@ -372,7 +389,7 @@ export function entityQuerySchemas(manifest, entityName, wire = false) {
     };
     const query = (wire
         ? wireStruct(queryMembers, { orderBy: "order_by" })
-        : closedStruct(queryMembers, "Unknown key; use where, orderBy, include, after or limit")).annotate({ identifier: `${pascal}Query`, description: `A query on ${entity.plural}.` });
+        : closedStruct(queryMembers, "Unknown key")).annotate({ identifier: `${pascal}Query`, description: `A query on ${entity.plural}.` });
     // The structs are assembled from the manifest, so their static types are too wide to name; they
     // accept exactly the Query shape and decode it unchanged.
     const schemas = {
@@ -388,6 +405,28 @@ export function entityQuerySchemas(manifest, entityName, wire = false) {
     cache.set(manifest, byEntity);
     return schemas;
 }
+/**
+ * The relationships a query includes: a list of names, `["owner", "tags"]`, or the object form
+ * `{ owner: true, tags: true }` that the list decodes into. Both reject an unknown relationship and
+ * name the ones there are.
+ */
+function includeSchema(relationships) {
+    const fields = {};
+    for (const name of relationships) {
+        fields[name] = Schema.optionalKey(Schema.Literal(true));
+    }
+    const included = closedStruct(fields, "Unknown relationship");
+    const name = Schema.String.check(Schema.makeFilter((candidate) => relationships.includes(candidate) ||
+        expectedOneOf(`Unknown relationship "${candidate}"`, relationships), { toJsonSchema: () => (relationships.length > 0 ? { enum: relationships } : { not: {} }) }));
+    const example = relationships[0];
+    const forms = example === undefined
+        ? "a list of relationship names; there are none"
+        : `a list of relationship names, as in ["${example}"], or an object, as in {"${example}": true}`;
+    return Schema.Union([included, includeList(name, included)]).annotate({
+        description: `Related records to add to each record: ${forms}.`,
+        message: `Expected ${forms}`,
+    });
+}
 /** The query schema of one entity; see {@link entityQuerySchemas}. */
 export function entityQuerySchema(manifest, entityName) {
     return entityQuerySchemas(manifest, entityName).query;
@@ -401,10 +440,11 @@ function escapeRegExp(value) {
  * same with a `patternProperties` entry that matches every undeclared key.
  */
 function closedStruct(fields, unknownKey) {
-    const declared = Object.keys(fields).map(escapeRegExp).join("|");
+    const keys = Object.keys(fields);
+    const declared = keys.map(escapeRegExp).join("|");
     const undeclared = Schema.String.check(Schema.isPattern(new RegExp(`^(?!(?:${declared})$)`)));
     return Schema.StructWithRest(Schema.Struct(fields), [
-        Schema.Record(undeclared, Schema.Never.annotate({ message: unknownKey })),
+        Schema.Record(undeclared, Schema.Never.annotate({ message: expectedOneOf(unknownKey, keys) })),
     ]);
 }
 function recordValueSchema(field) {

package/dist/runtime/reads.js

@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 import { NotFound } from "../errors.js";
-import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, isInstant, } from "../query.js";
+import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, includedRelationships, isInstant, } from "../query.js";
 import { quoteIdentifier } from "../migrate/storage.js";
 import { afterCondition, decodeCursor, encodeCursor, orderByClause, sortKeys } from "./cursor.js";
 import { InvalidQuery } from "./errors.js";
@@ -120,7 +120,7 @@ export function runQuery(context, entity, query, options = {}) {
 export const MAX_INCLUDED = MAX_QUERY_LIMIT;
 function includeRelated(context, entity, records, include) {
     return Effect.gen(function* () {
-        const names = Object.keys(include ?? {});
+        const names = includedRelationships(include);
         let items = [...records];
         if (records.length === 0) {
             return items;

package/dist/runtime.d.ts

@@ -60,7 +60,8 @@ export interface FindOptions<R = StoredRecord, L extends string = never> {
         readonly field: keyof R & string;
         readonly direction?: "asc" | "desc";
     }>;
-    readonly include?: {
+    /** Relationships to add to each record: `["owner", "tags"]`, or `{ owner: true, tags: true }`. */
+    readonly include?: ReadonlyArray<L> | {
         readonly [K in L]?: true;
     };
     readonly after?: string;

package/dist/service/mcp/tools.js

@@ -88,7 +88,7 @@ function relatedHint(planned, traversal) {
     const find = mcpToolName(traversal.target, "find");
     switch (traversal.kind) {
         case "one":
-            return (`${traversal.name}: include {"${traversal.name}": true}, or ` +
+            return (`${traversal.name}: include ["${traversal.name}"], or ` +
                 `${mcpToolName(traversal.target, "get")} with ${traversal.name}_id.`);
         case "inverseOfOne":
             return `${traversal.name}: ${find} with where {"${traversal.opposite}": {"id": {"eq": "${id}"}}}.`;
@@ -122,12 +122,17 @@ function readTools(planned, schemas, built) {
         ...planned.traversals.map((traversal) => relatedHint(planned, traversal)),
         ...matchedHints(planned),
     ].map((hint) => `- ${hint}`);
+    const includable = planned.traversals.slice(0, 2).map((traversal) => `"${traversal.name}"`);
+    const including = includable.length === 0
+        ? ""
+        : ` Pass include as a list of relationship names, as in [${includable.join(", ")}].`;
     return [
         {
             name: mcpToolName(planned.name, "find"),
             title: `Find ${definition.plural.toLowerCase()}`,
             description: `Filter, sort and page through ${definition.plural.toLowerCase()}, at most 200 at a ` +
-                `time; pass next_cursor as after to read the next page. ${definition.description}\n\n` +
+                `time; pass next_cursor as after to read the next page.${including} ` +
+                `${definition.description}\n\n` +
                 `${requires([read])} Including a relationship, or filtering through one, requires ` +
                 "reading its entity too." +
                 (related.length > 0 ? `\n\nRelated records:\n${related.join("\n")}` : ""),

package/dist/service/operations.d.ts

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 import type { HttpServerRequest } from "effect/unstable/http";
 import { PermissionDenied } from "../errors.js";
-import type { Query, QueryResult } from "../query.js";
+import { type Query, type QueryResult } from "../query.js";
 import { CurrentPrincipal } from "./authentication.js";
 import type { AfterCommitHook } from "./config.js";
 import type { ReplicationKick } from "./replication.js";

package/dist/service/operations.js

@@ -5,6 +5,7 @@ import { principalFromWire } from "../authoring.js";
 import { PermissionDenied } from "../errors.js";
 import { toCamelCase } from "../names.js";
 import { missingPermission, permissionOf, READ_VERB } from "../permissions.js";
+import { includedRelationships } from "../query.js";
 import { CurrentPrincipal } from "./authentication.js";
 import { AgentChannel } from "../agent-chat.js";
 import { OIDC_TOKEN_HEADER } from "./connections.js";
@@ -18,7 +19,7 @@ import { InvalidActionInput, RequestId } from "./errors.js";
 /** The query the runtime receives: every key present only when set, and no empty `include`. */
 export function toQuery(decoded) {
     const { include, ...rest } = decoded;
-    return include !== undefined && Object.keys(include).length > 0 ? { ...rest, include } : rest;
+    return includedRelationships(include).length > 0 ? { ...rest, include } : rest;
 }
 function page(result) {
     return { items: result.items, nextCursor: result.nextCursor ?? null };
@@ -55,7 +56,7 @@ function filterReads(where, targets, reads) {
 function queryReads(entity, query, targets) {
     const own = targets.get(entity) ?? new Map();
     const reads = new Set([entity]);
-    for (const name of Object.keys(query.include ?? {})) {
+    for (const name of includedRelationships(query.include)) {
         const target = own.get(name);
         if (target !== undefined) {
             reads.add(target);

package/dist/service/schemas.js

@@ -194,7 +194,7 @@ function schemasOf(plan, planned, recordOf) {
             include: Schema.optionalKey(includeParam(query.include)),
             after: Schema.optionalKey(query.after),
             limit: Schema.optionalKey(query.limit),
-        }, { orderBy: "order_by" }),
+        }, { orderBy: "order_by" }, "Unknown parameter"),
         includeParams: {
             include: Schema.optionalKey(includeParam(query.include)),
         },

package/dist/wire.d.ts

@@ -1,5 +1,10 @@
 import { Schema } from "effect";
+/**
+ * `Unknown operator. Expected one of: eq, ne, in`: what a closed struct reports for a key it does
+ * not declare, so that a caller can correct the key without guessing. Long lists are cut short.
+ */
+export declare function expectedOneOf(problem: string, accepted: ReadonlyArray<string>): string;
 /** A closed wire object with explicit key mappings and an unchanged decoded TypeScript shape. */
 export declare function wireStruct<const F extends Schema.Struct.Fields, const M extends {
     readonly [K in keyof F]?: string;
-}>(fields: F, mapping: M): Schema.encodeKeys<Schema.Struct<F>, M>;
+}>(fields: F, mapping: M, unknownKey?: string): Schema.encodeKeys<Schema.Struct<F>, M>;

package/dist/wire.js

@@ -1,17 +1,31 @@
 import { Schema, SchemaTransformation } from "effect";
+/** An unknown-key message names at most this many accepted keys and counts the rest. */
+const MAX_LISTED_KEYS = 30;
+/**
+ * `Unknown operator. Expected one of: eq, ne, in`: what a closed struct reports for a key it does
+ * not declare, so that a caller can correct the key without guessing. Long lists are cut short.
+ */
+export function expectedOneOf(problem, accepted) {
+    if (accepted.length === 0) {
+        return `${problem}; there are none`;
+    }
+    const listed = accepted.slice(0, MAX_LISTED_KEYS).join(", ");
+    const rest = accepted.length - MAX_LISTED_KEYS;
+    return `${problem}. Expected one of: ${listed}${rest > 0 ? `, and ${rest} more` : ""}`;
+}
 /** A closed wire object with explicit key mappings and an unchanged decoded TypeScript shape. */
-export function wireStruct(fields, mapping) {
+export function wireStruct(fields, mapping, unknownKey = "Unknown key") {
     const codec = Schema.Struct(fields).pipe(Schema.encodeKeys(mapping));
     const encodedFields = Object.fromEntries(Object.entries(fields).map(([key, field]) => [
         mapping[key] ?? key,
         field,
     ]));
-    const names = Object.keys(encodedFields).join("|");
-    const unknown = Schema.String.check(Schema.isPattern(new RegExp(`^(?!(?:${names})$)`)));
+    const encodedKeys = Object.keys(encodedFields);
+    const unknown = Schema.String.check(Schema.isPattern(new RegExp(`^(?!(?:${encodedKeys.join("|")})$)`)));
     const reverse = Object.fromEntries(Object.entries(mapping).map(([key, value]) => [value, key]));
     const rename = (value, keys) => Object.fromEntries(Object.entries(value).map(([key, child]) => [keys[key] ?? key, child]));
     const encoded = Schema.StructWithRest(Schema.Struct(encodedFields), [
-        Schema.Record(unknown, Schema.Never.annotate({ message: "Unknown wire key" })),
+        Schema.Record(unknown, Schema.Never.annotate({ message: expectedOneOf(unknownKey, encodedKeys) })),
     ]);
     const decoded = Schema.toType(codec);
     return encoded.pipe(Schema.decodeTo(decoded, SchemaTransformation.transform({

package/package.json

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