@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/relationship.d.ts

@@ -0,0 +1,99 @@
+import type { AnyEntity } from "./entity.js";
+export declare const RelationshipTypeId: unique symbol;
+export declare const ON_DELETE: readonly ["setNull", "cascade", "restrict"];
+/** What happens to the declaring record when the record it points at is deleted. */
+export type OnDelete = (typeof ON_DELETE)[number];
+/**
+ * `() => Entity`, for entities in files that import each other. It is typed as `Function` on purpose:
+ * a call signature would make TypeScript infer the thunk's return type while it infers the type of the
+ * entity that declares the relationship, which is circular when the two entities refer to each other.
+ * `defineOntology` checks that the thunk returns an entity.
+ */
+export type LazyEntity = Function;
+/** Where a relationship points: an entity, a thunk returning one, or an entity name. */
+export type EntityTarget = AnyEntity | LazyEntity | string;
+/**
+ * The name of the entity a target points at, as far as its type shows: the given name, or the
+ * entity's name. A thunk is a `Function`, whose `name` is any string, so its target stays unknown.
+ */
+type TargetName<Target> = Target extends string ? Target : Target extends {
+    readonly name: infer Name extends string;
+} ? Name : string;
+/** Names a relationship in both directions, for example `["is owned by", "owns"]`. */
+export type Phrase = readonly [forward: string, inverse: string];
+/**
+ * A many-to-one relationship. Between stored entities it is declared on the side that holds the key
+ * (`owner_id` on `lead`). When either end is warehouse-backed it is value-matched: it declares `on`,
+ * one pair of an own property and a target property, and has no key column, delete rule or
+ * optionality of its own.
+ */
+export interface OneRelationship<Optional extends boolean = boolean, Matched extends boolean = boolean, Target extends string = string> {
+    readonly [RelationshipTypeId]: typeof RelationshipTypeId;
+    readonly cardinality: "one";
+    readonly on?: Readonly<Record<string, string>>;
+    readonly target: EntityTarget;
+    readonly optional: Optional;
+    readonly inverse: string;
+    /** As declared. A stored → stored relationship without one restricts deletes. */
+    readonly onDelete?: OnDelete;
+    readonly phrase?: Phrase;
+    readonly description: string;
+    /**
+     * Exists only in the type: whether `on` was given, which makes the relationship value-matched.
+     * Value-matched relationships add no `<relationship>Id` to records and inputs.
+     */
+    readonly "~ontology.matched": Matched;
+    /**
+     * Exists only in the type: the target entity's name when the target was given as an entity or a
+     * name, and `string` for a thunk. Typed metric query clients resolve relationship paths with it.
+     */
+    readonly "~ontology.target": Target;
+}
+/** A plain many-to-many relationship, stored in a hidden join table. It never carries properties. */
+export interface ManyRelationship {
+    readonly [RelationshipTypeId]: typeof RelationshipTypeId;
+    readonly cardinality: "many";
+    readonly target: EntityTarget;
+    readonly inverse: string;
+    readonly phrase?: Phrase;
+    readonly description: string;
+    readonly ordered: boolean;
+}
+export type AnyRelationship = OneRelationship | ManyRelationship;
+export interface OneOptions {
+    /**
+     * The property pair a relationship with a warehouse-backed end matches on: `{ ownProperty:
+     * targetProperty }`. Required for those relationships and refused between stored entities.
+     */
+    readonly on?: Readonly<Record<string, string>>;
+    /** The record may point at nothing: the key column is nullable. Stored → stored only. */
+    readonly optional?: boolean;
+    /** The name of the relationship as seen from the target, for example `ownedLeads` on `user`. */
+    readonly inverse: string;
+    /** What deleting the target does to this record, `restrict` by default. Stored → stored only. */
+    readonly onDelete?: OnDelete;
+    readonly phrase?: Phrase;
+    readonly description: string;
+}
+export interface ManyOptions {
+    readonly inverse: string;
+    readonly phrase?: Phrase;
+    readonly description: string;
+    /** Keep the order in which records were linked. */
+    readonly ordered?: boolean;
+}
+type IsOptional<O> = O extends {
+    readonly optional: true;
+} ? true : false;
+type IsMatched<O> = O extends {
+    readonly on: Readonly<Record<string, string>>;
+} ? true : false;
+declare function one<const Target extends EntityTarget, const O extends OneOptions>(target: Target, options: O): OneRelationship<IsOptional<O>, IsMatched<O>, TargetName<Target>>;
+declare function many(target: EntityTarget, options: ManyOptions): ManyRelationship;
+/** Relationship constructors. */
+export declare const rel: {
+    readonly one: typeof one;
+    readonly many: typeof many;
+};
+export declare function isRelationship(value: unknown): value is AnyRelationship;
+export {};

package/dist/relationship.js

@@ -0,0 +1,33 @@
+export const RelationshipTypeId = Symbol.for("@segmentstream/ontology/Relationship");
+export const ON_DELETE = ["setNull", "cascade", "restrict"];
+function one(target, options) {
+    // `onDelete` stays absent unless declared, so that check can refuse it where it means nothing.
+    const relationship = {
+        [RelationshipTypeId]: RelationshipTypeId,
+        cardinality: "one",
+        target,
+        optional: options.optional === true,
+        inverse: options.inverse,
+        ...(options.onDelete !== undefined ? { onDelete: options.onDelete } : {}),
+        ...(options.on !== undefined ? { on: options.on } : {}),
+        ...(options.phrase !== undefined ? { phrase: options.phrase } : {}),
+        description: options.description,
+    };
+    return relationship;
+}
+function many(target, options) {
+    return {
+        [RelationshipTypeId]: RelationshipTypeId,
+        cardinality: "many",
+        target,
+        inverse: options.inverse,
+        ...(options.phrase !== undefined ? { phrase: options.phrase } : {}),
+        description: options.description,
+        ordered: options.ordered === true,
+    };
+}
+/** Relationship constructors. */
+export const rel = { one, many };
+export function isRelationship(value) {
+    return typeof value === "object" && value !== null && RelationshipTypeId in value;
+}

package/dist/render.d.ts

@@ -0,0 +1,81 @@
+import type { ActionManifest, EntityManifest, MetricManifest, ModelMetricManifest, OntologyManifest } from "./manifest.js";
+export interface RenderOptions {
+    /**
+     * The permissions of the reader. Only the actions these permissions may run are listed, and only
+     * the metrics and routes of entities they may read. Without it, every action is listed with the
+     * permission it requires and the roles that grant it, and every metric and route.
+     */
+    readonly as?: ReadonlyArray<string>;
+}
+/** What an action of the manifest requires; version 1 manifests leave it implicit. */
+export declare function actionPermission(entity: string, action: ActionManifest): string;
+/**
+ * A metric's description followed by its conditions and balance note, as `describe`, the MCP
+ * metric list and the console show it: `Revenue of won orders. Where status = "won".`
+ */
+export declare function metricDescription(entity: EntityManifest, metric: MetricManifest): string;
+/**
+ * Renders the catalog as prose for agents and people: each entity with its properties, both
+ * directions of its relationships and its actions, then the roles with their permissions and the
+ * `where`, in wire form, of each scoped one. Without a reader, each action and each entity's reads
+ * say which permission they require and which roles grant it; with one, only the actions the reader
+ * may run are listed. A pure function of the manifest, so the console, the CLI and the service
+ * describe the same ontology.
+ */
+export declare function renderCatalog(manifest: OntologyManifest, options?: RenderOptions): string;
+/**
+ * The catalog as `describe` answers a reader: {@link renderCatalog} with the reader's permissions,
+ * or everything without them.
+ */
+export declare function describeCatalog(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;
+/** A metric as metric queries name it: `<entity>.<metric>`. */
+export interface NamedMetric {
+    readonly name: string;
+    readonly entity: EntityManifest;
+    readonly metric: MetricManifest;
+}
+/**
+ * An entity a metric entity reaches, and the shortest routes there the reader may follow:
+ * `product.region`. `ambiguous` when the resolver finds several shortest routes, readable or not,
+ * so a request must write the route.
+ */
+export interface Reach {
+    readonly target: string;
+    readonly routes: ReadonlyArray<string>;
+    readonly ambiguous: boolean;
+}
+/**
+ * The rule every surface repeats (docs/ontology-aggregates-spec.md, "Three ways to ask"), naming
+ * the tool that computes metrics.
+ */
+export declare const RECORDS_OR_METRIC_QUERIES = "look at or change records through find and actions; count, sum or compare through query_metrics";
+/**
+ * Every metric of the entities the reader may read, warehouse-backed and stored alike, in
+ * declaration order. Without permissions, every metric.
+ */
+export declare function metricsFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): ReadonlyArray<NamedMetric>;
+/**
+ * The metrics of the model whose every input entity the reader may read, in declaration order.
+ * Reading a model metric is reading its inputs. Without permissions, every one.
+ */
+export declare function modelMetricsFor(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): ReadonlyArray<ModelMetricManifest>;
+/**
+ * A metric of the model as `describe`, the MCP tool and the instructions show it: its description,
+ * the entity metrics it reads and how their properties align. `Ordered over planned units. Reads
+ * sales.ordered and plans.planned_units; sales.order_date aligns with plans.month.`
+ */
+export declare function modelMetricDescription(metric: ModelMetricManifest): string;
+/**
+ * The entities one entity reaches, with the shortest routes to each: exactly the routes metric query
+ * resolution weighs ({@link shortestRoutesFrom}). Only then is the reader applied: a target they may
+ * not read is left out, and so is any route through an entity they may not read, which the service
+ * would refuse. A target keeps `ambiguous` from before that filter, so a route is never shown as the
+ * only one when the resolver would ask for it to be written.
+ */
+export declare function reachesOf(manifest: OntologyManifest, from: string, permissions?: ReadonlyArray<string>): ReadonlyArray<Reach>;
+/**
+ * The metric query part of the catalog's prose: every metric the reader may read, model-wide, the
+ * metrics of the model whose every input they may read, and per metric entity the entities it
+ * reaches. Empty when the reader may read no metric.
+ */
+export declare function renderMetricQueries(manifest: OntologyManifest, permissions?: ReadonlyArray<string>): string;