@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/app-feedback.d.ts

@@ -0,0 +1,167 @@
+import { Schema } from "effect";
+/** A feedback file's limit: screenshots, logs and documents, not archives of a whole project. */
+export declare const APP_FEEDBACK_FILE_MAX_BYTES: number;
+/**
+ * Feedback the app's members send its builders through their clients, enabled by default
+ * unless `defineOntology({ feedback: false })` disables it. Only the actions below change it; submit always captures the caller
+ * the client acts for, including a service with deliberately authored named grants.
+ */
+export declare const AppFeedback: import("./entity.js").Entity<"app_feedback", {
+    readonly title: import("./property.js").Property<string, false, false>;
+    readonly body: import("./property.js").Property<string, false, false>;
+    readonly status: import("./property.js").Property<"open" | "done" | "declined", false, false>;
+    readonly response: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly respondedAt: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly seenAt: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+}, {
+    readonly reporter: import("./relationship.js").OneRelationship<false, false, "user">;
+}, import("./entity.js").InvocableActions<{
+    readonly submit: import("./action.js").Action<Schema.Struct<{
+        readonly title: import("./property.js").Property<string, false, false>;
+        readonly body: import("./property.js").Property<string, false, false>;
+    }>, {
+        feedback: string;
+    }>;
+    readonly respond: import("./action.js").Action<Schema.Struct<{
+        readonly feedback: Schema.Codec<string, string, never, never>;
+        readonly status: import("./property.js").Property<"done" | "declined", false, false>;
+        readonly response: import("./property.js").Property<string, false, false>;
+    }>, {
+        feedback: string;
+    }>;
+    readonly acknowledge: import("./action.js").Action<Schema.Struct<{
+        readonly feedback: Schema.Codec<string, string, never, never>;
+        readonly respondedAt: import("./property.js").Property<string, false, false>;
+    }>, {
+        feedback: string;
+        acknowledged: boolean;
+    }>;
+}, "app_feedback", {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
+    readonly title: string;
+    readonly body: string;
+    readonly status: "open" | "done" | "declined";
+    readonly response: string | null;
+    readonly respondedAt: string | null;
+    readonly seenAt: string | null;
+    readonly reporterId: string;
+}>, Readonly<Record<never, never>>, "generated">;
+export type AppFeedback = typeof AppFeedback.Type;
+/** A screenshot, log or document attached to feedback; an item has any number of them. */
+export declare const AppFeedbackFile: import("./entity.js").Entity<"app_feedback_file", {
+    readonly file: import("./property.js").Property<{
+        readonly id: string;
+        readonly filename: string;
+        readonly contentType: string;
+        readonly size: number;
+        readonly createdAt: string;
+    }, false, false>;
+}, {
+    readonly feedback: import("./relationship.js").OneRelationship<false, false, "app_feedback">;
+}, import("./entity.js").InvocableActions<{
+    readonly attach: import("./action.js").Action<Schema.Struct<{
+        readonly feedback: Schema.Codec<string, string, never, never>;
+        readonly file: Schema.Struct<{
+            readonly uploadId: Schema.String;
+        }>;
+    }>, {
+        file: string;
+    }>;
+}, "app_feedback_file", {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
+    readonly file: {
+        readonly id: string;
+        readonly filename: string;
+        readonly contentType: string;
+        readonly size: number;
+        readonly createdAt: string;
+    };
+    readonly feedbackId: string;
+}>, Readonly<Record<never, never>>, "generated">;
+export type AppFeedbackFile = typeof AppFeedbackFile.Type;
+/** The entities `feedback: true` adds, in the order their tables are created. */
+export declare const APP_FEEDBACK_ENTITIES: readonly [import("./entity.js").Entity<"app_feedback", {
+    readonly title: import("./property.js").Property<string, false, false>;
+    readonly body: import("./property.js").Property<string, false, false>;
+    readonly status: import("./property.js").Property<"open" | "done" | "declined", false, false>;
+    readonly response: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly respondedAt: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+    readonly seenAt: Schema.optionalKey<import("./property.js").Property<string, false, false>>;
+}, {
+    readonly reporter: import("./relationship.js").OneRelationship<false, false, "user">;
+}, import("./entity.js").InvocableActions<{
+    readonly submit: import("./action.js").Action<Schema.Struct<{
+        readonly title: import("./property.js").Property<string, false, false>;
+        readonly body: import("./property.js").Property<string, false, false>;
+    }>, {
+        feedback: string;
+    }>;
+    readonly respond: import("./action.js").Action<Schema.Struct<{
+        readonly feedback: Schema.Codec<string, string, never, never>;
+        readonly status: import("./property.js").Property<"done" | "declined", false, false>;
+        readonly response: import("./property.js").Property<string, false, false>;
+    }>, {
+        feedback: string;
+    }>;
+    readonly acknowledge: import("./action.js").Action<Schema.Struct<{
+        readonly feedback: Schema.Codec<string, string, never, never>;
+        readonly respondedAt: import("./property.js").Property<string, false, false>;
+    }>, {
+        feedback: string;
+        acknowledged: boolean;
+    }>;
+}, "app_feedback", {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
+    readonly title: string;
+    readonly body: string;
+    readonly status: "open" | "done" | "declined";
+    readonly response: string | null;
+    readonly respondedAt: string | null;
+    readonly seenAt: string | null;
+    readonly reporterId: string;
+}>, Readonly<Record<never, never>>, "generated">, import("./entity.js").Entity<"app_feedback_file", {
+    readonly file: import("./property.js").Property<{
+        readonly id: string;
+        readonly filename: string;
+        readonly contentType: string;
+        readonly size: number;
+        readonly createdAt: string;
+    }, false, false>;
+}, {
+    readonly feedback: import("./relationship.js").OneRelationship<false, false, "app_feedback">;
+}, import("./entity.js").InvocableActions<{
+    readonly attach: import("./action.js").Action<Schema.Struct<{
+        readonly feedback: Schema.Codec<string, string, never, never>;
+        readonly file: Schema.Struct<{
+            readonly uploadId: Schema.String;
+        }>;
+    }>, {
+        file: string;
+    }>;
+}, "app_feedback_file", {
+    readonly id: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly createdBy: string | null;
+    readonly updatedBy: string | null;
+    readonly file: {
+        readonly id: string;
+        readonly filename: string;
+        readonly contentType: string;
+        readonly size: number;
+        readonly createdAt: string;
+    };
+    readonly feedbackId: string;
+}>, Readonly<Record<never, never>>, "generated">];

package/dist/app-feedback.js

@@ -0,0 +1,176 @@
+import { Effect, Schema } from "effect";
+import { action } from "./action.js";
+import { uploads } from "./blob.js";
+import { entity } from "./entity.js";
+import { p } from "./property.js";
+import { rel } from "./relationship.js";
+/** A feedback file's limit: screenshots, logs and documents, not archives of a whole project. */
+export const APP_FEEDBACK_FILE_MAX_BYTES = 25 * 1024 * 1024;
+const STATUS = [
+    { value: "open", description: "Waiting for the builders' answer." },
+    { value: "done", description: "The builders did what was asked; the response says what." },
+    { value: "declined", description: "The builders will not do it; the response says why." },
+];
+const RESPONSE_STATUS = STATUS.filter((option) => option.value !== "open");
+/**
+ * Feedback the app's members send its builders through their clients, enabled by default
+ * unless `defineOntology({ feedback: false })` disables it. Only the actions below change it; submit always captures the caller
+ * the client acts for, including a service with deliberately authored named grants.
+ */
+export const AppFeedback = entity("app_feedback", {
+    id: "ent_app_feedback",
+    label: "App feedback",
+    plural: "App feedback",
+    title: "title",
+    description: "Feedback a member sent the app's builders through an agent: something the app cannot do, a " +
+        "failure, or a change they want. Each member sees their own; the builders answer with a " +
+        "response, and the member's agent reports it to them.",
+    properties: {
+        title: p.text({ managed: true, maxLength: 200, description: "What the feedback is about." }),
+        body: p.text({
+            managed: true,
+            maxLength: 20000,
+            display: "multiline",
+            description: "Markdown in the member's language: what they wanted and what happened, the steps, the " +
+                "record or page involved, and the request_id and error code of any failure.",
+        }),
+        status: p.select(STATUS, { managed: true, description: "Whether the builders answered." }),
+        response: p.text({
+            optional: true,
+            managed: true,
+            maxLength: 20000,
+            display: "multiline",
+            description: "The builders' answer to the member, in the member's language.",
+        }),
+        respondedAt: p.timestamp({
+            optional: true,
+            managed: true,
+            label: "Responded",
+            description: "When the builders last answered.",
+        }),
+        seenAt: p.timestamp({
+            optional: true,
+            managed: true,
+            label: "Seen",
+            description: "When the member's agent told them the latest response; empty while it is unseen.",
+        }),
+    },
+    relationships: {
+        // By name, so that an ontology rebuilt with the deployed `user` still resolves it.
+        reporter: rel.one("user", {
+            inverse: "sentFeedback",
+            phrase: ["was sent by", "sent"],
+            description: "The member the agent acted for.",
+        }),
+    },
+}).actions((self) => ({
+    submit: action({
+        description: "Send the app's builders feedback for the member you act for: something no permitted tool or " +
+            "data provides, a refused or failing operation, or a change they want. Offer it first, once per " +
+            "problem, after checking their open app_feedback for the same subject; submit only when the " +
+            "member agrees to the title and summary you showed them, unless the published workspace " +
+            "feedback policy preauthorizes minimal technical failure reports during requested work.",
+        hints: { destructive: false },
+        input: Schema.Struct({
+            title: p.text({ maxLength: 200, description: "What the feedback is about." }),
+            body: p.text({
+                maxLength: 20000,
+                description: "Markdown in the member's language: what they wanted and what happened, the steps, the " +
+                    "record or page involved, and the request_id and error code of any failure. No credentials.",
+            }),
+        }),
+        handler: ({ input, principal }) => Effect.gen(function* () {
+            const feedback = yield* self.create({
+                title: input.title,
+                body: input.body,
+                status: "open",
+                response: null,
+                respondedAt: null,
+                seenAt: null,
+                reporter: principal.id,
+            });
+            return { feedback: feedback.id };
+        }),
+    }),
+    respond: action({
+        description: "Answer a member's feedback as the app's builders: done or declined, with a response in the " +
+            "member's language that says what changed, or why not. Their agent reports it.",
+        hints: { destructive: false },
+        input: Schema.Struct({
+            feedback: self.ref,
+            status: p.select(RESPONSE_STATUS, { description: "The answer." }),
+            response: p.text({
+                maxLength: 20000,
+                description: "The answer to the member, in their language, with a link to what changed.",
+            }),
+        }),
+        handler: ({ input }) => Effect.gen(function* () {
+            const feedback = yield* self.get(input.feedback, { forUpdate: true });
+            yield* self.update(feedback, {
+                status: input.status,
+                response: input.response,
+                respondedAt: new Date().toISOString(),
+                seenAt: null,
+            });
+            return { feedback: feedback.id };
+        }),
+    }),
+    acknowledge: action({
+        description: "Record that the member has been told the builders' response to their feedback, passing the " +
+            "responded_at of the response you reported. Find their feedback with responded_at set and " +
+            "seen_at empty at the start of a conversation, tell them what was done, then call this. " +
+            "acknowledged is false when there is no such response, as when the builders answered again " +
+            "meanwhile: read the item again and report the newer response.",
+        hints: { destructive: false, idempotent: true },
+        input: Schema.Struct({
+            feedback: self.ref,
+            respondedAt: p.timestamp({ description: "The responded_at of the response you reported." }),
+        }),
+        handler: ({ input }) => Effect.gen(function* () {
+            const feedback = yield* self.get(input.feedback, { forUpdate: true });
+            // Only the response the agent reported is seen; a later one stays unseen until reported.
+            const reported = typeof feedback.respondedAt === "string" &&
+                Date.parse(feedback.respondedAt) === Date.parse(input.respondedAt);
+            if (reported) {
+                yield* self.update(feedback, { seenAt: new Date().toISOString() });
+            }
+            return { feedback: feedback.id, acknowledged: reported };
+        }),
+    }),
+}));
+/** A screenshot, log or document attached to feedback; an item has any number of them. */
+export const AppFeedbackFile = entity("app_feedback_file", {
+    id: "ent_app_feedback_file",
+    label: "App feedback file",
+    plural: "App feedback files",
+    title: "file",
+    description: "A screenshot, log or document a member attached to their feedback.",
+    properties: {
+        file: p.blob({
+            managed: true,
+            maxBytes: APP_FEEDBACK_FILE_MAX_BYTES,
+            description: "The file, of any type, up to 25 MiB.",
+        }),
+    },
+    relationships: {
+        feedback: rel.one(AppFeedback, {
+            inverse: "files",
+            phrase: ["is attached to", "has"],
+            description: "The feedback the file belongs to.",
+        }),
+    },
+}).actions((self) => ({
+    attach: action({
+        description: "Add one screenshot, log or document to feedback, after app_feedback_submit: a completed " +
+            "files_upload for this action, or a chat attachment through attachments_promote. Call once " +
+            "per file.",
+        hints: { destructive: false, idempotent: true },
+        input: Schema.Struct({ feedback: AppFeedback.ref, file: uploads.for(self, "file") }),
+        handler: ({ input }) => Effect.gen(function* () {
+            const file = yield* self.create({ feedback: input.feedback, file: input.file });
+            return { file: file.id };
+        }),
+    }),
+}));
+/** The entities `feedback: true` adds, in the order their tables are created. */
+export const APP_FEEDBACK_ENTITIES = [AppFeedback, AppFeedbackFile];

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,35 @@
+import { type AnyEntity, type Properties, type Relationships } from "./entity.js";
+import type { Edit } from "./runtime/history.js";
+import type { FindOptions, FreshMetricQueryOptions, StoredRecord, StoredValues } from "./runtime.js";
+interface Definition {
+    readonly properties: Properties;
+    readonly relationships?: Relationships;
+}
+/**
+ * A select property's values as stored, the option values' wire names, or as authored when
+ * `decode`. Other properties' values are data and stay as they are.
+ */
+export declare function selectValue(value: unknown, property: unknown, decode: boolean): unknown;
+/** 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;
+/**
+ * The `where` of a scoped permission as the manifest writes it: the wire form of a query, with
+ * snake_case fields, relationships and operators, select values as stored, and `me` and paths as
+ * `{ "$me": [...] }` with snake_case hops. A relationship compared with `me`, a path or operators
+ * stays under its name. Converting a wire `where` again changes nothing.
+ */
+export declare function scopeWhereToWire(where: unknown, definition?: Definition): unknown;
+export declare function findToWire(options: FindOptions, definition: Definition): FindOptions;
+/** A fresh metric query's metrics, grouped fields and `where` in wire names. */
+export declare function metricQueryToWire(options: FreshMetricQueryOptions<unknown, string>, definition: Definition): FreshMetricQueryOptions;
+/**
+ * A fresh metric query's row in authored names: the grouped fields as a record's, the metrics by the
+ * names the handler asked for.
+ */
+export declare function metricQueryRowFromWire(row: StoredRecord, metrics: ReadonlyArray<string>, definition: Definition): StoredRecord;
+/** 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 {};