@segmentstream-cloud/ontology 0.17.0 → 0.18.1

package/README.md

@@ -40,6 +40,10 @@ take the `notEquals`, `notIn`, `gt`, `gte`, `lt`, `lte`, `contains`, `startsWith
 SDK 0.14.0 lets the app's own agent call the service as a paired member (see
 [Agents](#agents)). Its migration adds the agent's runtime tables.
 
+SDK 0.18.0 lets blob properties store any file. `accept` is optional and can restrict a
+property to exact MIME types or ranges. Existing explicit restrictions keep their meaning.
+See [File storage](#file-storage).
+
 SDK 0.12.0 adds warehouse replication enabled by default for all stored business entities,
 fields and business relationships. Existing history captures immutable snapshots and the
 service wakes the publisher after commits. Upgrade and redeploy to activate it; workspace
@@ -73,6 +77,62 @@ SDK 0.13.0 also serves aggregates. Upgrade notes:
 See [ontology aggregates](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates.md)
 and [ontology analytics](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-aggregates-spec.md).
 
+## File storage
+
+Use `p.blob({ description: "Original source file." })` to retain a file's original bytes.
+Without `accept`, a blob property accepts every concrete MIME type, including custom formats
+and `application/octet-stream`. `p.blob()` also defaults to all files, though ontology checks
+require a description. The manifest publishes this policy as `accept: ["*/*"]`.
+
+Restrict a property when its business rules require a format:
+
+```ts
+content: p.blob({
+  description: "Original POS report or bank statement.",
+  accept: [
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+    "text/csv",
+    "text/tab-separated-values",
+  ],
+  maxBytes: 10 * 1024 * 1024,
+}),
+```
+
+`accept` takes MIME types, not extensions. Matching ignores case; `image/*` accepts image
+types and `*/*` accepts all types. Empty lists, duplicate entries, invalid MIME types and
+parameters such as `; charset=utf-8` are rejected during ontology checks.
+`BLOB_CONTENT_TYPES` lists common types as a convenience; it is not a global allow-list.
+
+| Source format         | MIME type                                                                 |
+| --------------------- | ------------------------------------------------------------------------- |
+| XLSX                  | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`       |
+| XLS                   | `application/vnd.ms-excel`                                                |
+| CSV                   | `text/csv`                                                                |
+| TSV                   | `text/tab-separated-values`                                               |
+| JSON                  | `application/json`                                                        |
+| TXT                   | `text/plain`                                                              |
+| DOCX                  | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
+| ZIP                   | `application/zip`                                                         |
+| Unknown binary format | `application/octet-stream`                                                |
+
+Uploads still require a valid concrete MIME type, a nonempty file within the property's
+`maxBytes` and the 25 MiB service limit, available workspace quota and action permissions.
+Completion verifies the stored MIME metadata, exact byte count and upload-session binding.
+PDF, JPEG and PNG retain their prefix-signature checks; plain text retains its UTF-8 prefix
+check. Other formats are stored as opaque bytes, without parsing, conversion, archive
+extraction or malware scanning. A MIME declaration does not prove what a file contains.
+Downloads use attachment disposition; only JPEG and PNG may request inline display.
+Agent attachment promotion honors the same `accept` and `maxBytes` restrictions.
+
+Upgrade the ontology SDK to 0.18.0 or later, update any existing `accept` list that should
+allow more types, then check, migrate and redeploy the ontology. The app SDK storage client
+0.13.1 or later uses `application/octet-stream` when the browser supplies no MIME type.
+REST callers should supply that type themselves for unknown formats.
+
+See [blob storage](https://github.com/segmentstream/segmentstream/blob/main/docs/ontology-blob-storage-implementation.md)
+for upload tickets, transfer grants and retained revisions.
+
 ## Define the ontology
 
 ```ts

package/dist/analyze.js

@@ -1,7 +1,7 @@
 import { checkWarehouseSource } from "./warehouse-backed.js";
 import { Schema } from "effect";
 import { BLOB_UPLOAD_ANNOTATION } from "./blob.js";
-import { BLOB_CONTENT_TYPES, MAX_BLOB_BYTES } from "./blob.js";
+import { isBlobAccept, MAX_BLOB_BYTES } from "./blob.js";
 import { isAction } from "./action.js";
 import { CONNECTION_KEY, isConnection } from "./connection.js";
 import { isEntity } from "./entity.js";
@@ -411,12 +411,13 @@ function checkProperty(path, schema, definition, report) {
             report("invalid-property", path, "Blob properties cannot be unique or have a default.");
         }
         if (!definition.accept?.length ||
-            definition.accept.some((type) => !BLOB_CONTENT_TYPES.includes(type)) ||
-            new Set(definition.accept).size !== definition.accept.length ||
+            definition.accept.some((type) => !isBlobAccept(type)) ||
+            new Set(definition.accept.map((type) => type.toLowerCase())).size !==
+                definition.accept.length ||
             !Number.isInteger(definition.maxBytes) ||
             definition.maxBytes < 1 ||
             definition.maxBytes > MAX_BLOB_BYTES) {
-            report("invalid-constraint", path, "Use supported content types and a limit from 1 byte to 25 MiB.");
+            report("invalid-constraint", path, "Use MIME types or ranges and a limit from 1 byte to 25 MiB.");
         }
     }
     if (definition.type === "select") {

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/blob.d.ts

@@ -20,7 +20,14 @@ export declare const BlobUpload: Schema.Struct<{
 export type BlobUpload = typeof BlobUpload.Type;
 export declare const BLOB_UPLOAD_ANNOTATION = "x-ontology-upload";
 export declare const MAX_BLOB_BYTES: number;
-export declare const BLOB_CONTENT_TYPES: readonly ["application/pdf", "image/jpeg", "image/png", "text/plain"];
+/** Common content types for file properties; any valid MIME type may be declared. */
+export declare const BLOB_CONTENT_TYPES: readonly ["application/pdf", "image/jpeg", "image/png", "text/plain", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "application/vnd.ms-excel", "text/csv", "text/tab-separated-values", "application/json", "application/vnd.openxmlformats-officedocument.wordprocessingml.document", "application/zip", "application/octet-stream"];
+/** A concrete MIME type, without wildcards, parameters or header control characters. */
+export declare function isBlobContentType(contentType: string): boolean;
+/** A property's MIME restriction: a concrete type, a type range, or all files. */
+export declare function isBlobAccept(accept: string): boolean;
+/** Omitted restrictions accept every concrete MIME type; an empty list accepts nothing. */
+export declare function acceptsBlobContentType(accept: ReadonlyArray<string> | undefined, contentType: string): boolean;
 type SchemaValue<S> = S extends {
     readonly Type: infer T;
 } ? T : S extends Schema.optionalKey<infer Inner> ? Inner["Type"] : never;

package/dist/blob.js

@@ -28,12 +28,46 @@ function uploadCodec(entity, property) {
 export const BlobUpload = Schema.Struct({ uploadId: Schema.String.check(Schema.isUUID()) });
 export const BLOB_UPLOAD_ANNOTATION = "x-ontology-upload";
 export const MAX_BLOB_BYTES = 25 * 1024 * 1024;
+/** Common content types for file properties; any valid MIME type may be declared. */
 export const BLOB_CONTENT_TYPES = [
     "application/pdf",
     "image/jpeg",
     "image/png",
     "text/plain",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+    "text/csv",
+    "text/tab-separated-values",
+    "application/json",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "application/zip",
+    "application/octet-stream",
 ];
+const CONTENT_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/i;
+const CONTENT_TYPE_RANGE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/\*$/i;
+/** A concrete MIME type, without wildcards, parameters or header control characters. */
+export function isBlobContentType(contentType) {
+    return contentType === contentType.trim() && CONTENT_TYPE.test(contentType);
+}
+/** A property's MIME restriction: a concrete type, a type range, or all files. */
+export function isBlobAccept(accept) {
+    return (accept === accept.trim() &&
+        (accept === "*/*" || CONTENT_TYPE_RANGE.test(accept) || isBlobContentType(accept)));
+}
+/** Omitted restrictions accept every concrete MIME type; an empty list accepts nothing. */
+export function acceptsBlobContentType(accept, contentType) {
+    if (!isBlobContentType(contentType)) {
+        return false;
+    }
+    const normalized = contentType.toLowerCase();
+    return (accept === undefined ||
+        accept.some((candidate) => {
+            const pattern = candidate.toLowerCase();
+            return (pattern === "*/*" ||
+                pattern === normalized ||
+                (CONTENT_TYPE_RANGE.test(pattern) && normalized.startsWith(pattern.slice(0, -1))));
+        }));
+}
 /** Internal wire codec for session tickets and generated action inputs. */
 export function uploadInput(entity, property) {
     return uploadCodec(entity, property);

package/dist/property.d.ts

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-import { BlobValue, type BLOB_CONTENT_TYPES } from "./blob.js";
+import { BlobValue } from "./blob.js";
 /** The closed set of storage types. Each has a known column, JSON Schema, filters and rendering. */
 export declare const PROPERTY_TYPES: readonly ["text", "email", "url", "integer", "number", "boolean", "date", "timestamp", "select", "json", "blob"];
 export type PropertyType = (typeof PROPERTY_TYPES)[number];
@@ -131,10 +131,11 @@ declare function ref<const O extends ReferenceOptions>(target: string | {
 }, options?: O): ReferenceOf<O>;
 /** Property constructors. */
 export interface BlobOptions extends Omit<PropertyOptions<BlobValue>, "default" | "unique"> {
-    readonly accept: ReadonlyArray<(typeof BLOB_CONTENT_TYPES)[number]>;
+    /** MIME types or ranges such as image/*; omitted means any file. */
+    readonly accept?: ReadonlyArray<string>;
     readonly maxBytes?: number;
 }
-declare function blob<const O extends BlobOptions>(options: O): PropertyOf<BlobValue, O>;
+declare function blob<const O extends BlobOptions>(options?: O): PropertyOf<BlobValue, O>;
 export declare const p: {
     readonly text: typeof text;
     readonly email: typeof email;

package/dist/property.js

@@ -181,10 +181,15 @@ function ref(target, options) {
     return (settings.optional === true ? Schema.optionalKey(schema) : schema);
 }
 function blob(options) {
+    const settings = options ?? {};
     return construct({
         type: "blob",
         base: BlobValue,
-        options: { ...options, maxBytes: options.maxBytes ?? MAX_BLOB_BYTES },
+        options: {
+            ...settings,
+            accept: settings.accept ?? ["*/*"],
+            maxBytes: settings.maxBytes ?? MAX_BLOB_BYTES,
+        },
     });
 }
 export const p = {

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/storage/attachments.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { Effect } from "effect";
-import { BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES } from "../blob.js";
+import { acceptsBlobContentType, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES } from "../blob.js";
 import { ActionRejected, Conflict, NotFound } from "../errors.js";
 import { canonicalJson } from "../manifest.js";
 import { actionInputJsonSchema } from "../runtime/generated-actions.js";
@@ -357,7 +357,7 @@ export function attachmentRuntime(ontology, sql, provider) {
             if (row.state !== "ready" || row.expired) {
                 return yield* unavailable("The attachment expired or was discarded.");
             }
-            if (!property.accept?.includes(row.content_type) ||
+            if (!acceptsBlobContentType(property.accept, row.content_type) ||
                 Number(row.size) > (property.maxBytes ?? MAX_BLOB_BYTES)) {
                 return yield* new ActionRejected({
                     message: `${field.entity}.${field.property} accepts ${(property.accept ?? []).join(", ")} ` +

package/dist/storage/sessions.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { Effect, Schema } from "effect";
-import { uploadInput, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES } from "../blob.js";
+import { acceptsBlobContentType, uploadInput, BLOB_UPLOAD_ANNOTATION, MAX_BLOB_BYTES, } from "../blob.js";
 import { wireStruct } from "../wire.js";
 import { ActionRejected, Conflict, NotFound } from "../errors.js";
 import { authorizeBlobOperation } from "./authorization.js";
@@ -50,7 +50,7 @@ function allowsUpload(schema, entity, property) {
 }
 function sniff(bytes, contentType) {
     const starts = (magic) => magic.every((byte, index) => bytes[index] === byte);
-    switch (contentType) {
+    switch (contentType.toLowerCase()) {
         case "application/pdf":
             return starts([37, 80, 68, 70, 45]);
         case "image/png":
@@ -67,7 +67,8 @@ function sniff(bytes, contentType) {
                 return false;
             }
         default:
-            return false;
+            // Other MIME types describe opaque bytes; storage does not parse their formats.
+            return true;
     }
 }
 /** Persisted phases surround every provider call; no external I/O holds a database transaction. */
@@ -108,7 +109,7 @@ export function blobRuntime(ontology, sql, provider) {
             entity.source ||
             !property ||
             !found ||
-            !property.accept?.includes(input.contentType) ||
+            !acceptsBlobContentType(property.accept, input.contentType) ||
             input.size > (property.maxBytes ?? MAX_BLOB_BYTES) ||
             Boolean(input.recordId) === Boolean(input.createIntent) ||
             /[\x00-\x1f\x7f/\\]/.test(input.filename)) {
@@ -334,7 +335,8 @@ export function blobRuntime(ontology, sql, provider) {
             key: blob.key,
             filename: blob.filename,
             contentType: blob.content_type,
-            inline: input.inline === true && blob.content_type.startsWith("image/"),
+            inline: input.inline === true &&
+                ["image/jpeg", "image/png"].includes(blob.content_type.toLowerCase()),
         });
     });
     return { begin, status, part, complete, cancel, download };

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.17.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",