@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/migrate/preview.d.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import type { SqlClient } from "effect/unstable/sql";
+import type { SqlError } from "effect/unstable/sql/SqlError";
+/**
+ * Invalidate copied SDK credentials and runnable state on a verified, unexposed child database.
+ * The caller owns branch verification and provider-side Neon Auth invalidation/configuration.
+ * No provider-owned schema, business record, history, user, role assignment or member block is changed;
+ * of the `user_identity` records, only channel accounts are deleted, as their legacy rows are.
+ * Safe to repeat, including databases created by older SDKs with fewer runtime tables.
+ */
+export declare function preparePreviewDatabase({ sql, }: {
+    readonly sql: SqlClient.SqlClient;
+}): Effect.Effect<void, SqlError>;

package/dist/migrate/preview.js

@@ -0,0 +1,65 @@
+import { Effect } from "effect";
+import { AGENT_TASKS_TABLE, ATTACHMENTS_TABLE, SIGN_IN_EMAILS_TABLE, WORKFLOW_STARTS_TABLE, } from "../storage/tables.js";
+import { CONFIRMATION_TABLE } from "../runtime/confirmations.js";
+import { CHANNEL_ORIGIN_SQL, USER_IDENTITY_TABLE } from "../runtime/user-identity-sql.js";
+import { AGENT_COUNTERS_TABLE, AGENT_IDENTITIES_TABLE, AGENT_PAIRINGS_TABLE, API_KEYS_TABLE, IDENTITY_NOTICES_TABLE, OAUTH_TABLES, quoteIdentifier, } from "./storage.js";
+/**
+ * Invalidate copied SDK credentials and runnable state on a verified, unexposed child database.
+ * The caller owns branch verification and provider-side Neon Auth invalidation/configuration.
+ * No provider-owned schema, business record, history, user, role assignment or member block is changed;
+ * of the `user_identity` records, only channel accounts are deleted, as their legacy rows are.
+ * Safe to repeat, including databases created by older SDKs with fewer runtime tables.
+ */
+export function preparePreviewDatabase({ sql, }) {
+    return sql.withTransaction(Effect.gen(function* () {
+        yield* sql.unsafe("SET LOCAL statement_timeout = '30s'");
+        yield* sql.unsafe("SET LOCAL lock_timeout = '5s'");
+        yield* sql.unsafe("SELECT pg_advisory_xact_lock(hashtextextended('segmentstream.ontology.migration', 0))");
+        const tables = yield* sql.unsafe("SELECT tablename AS name FROM pg_catalog.pg_tables WHERE schemaname = current_schema()");
+        const present = new Set(tables.map(({ name }) => name));
+        // Emptied in one TRUNCATE, which takes the same time at any size: replication bookkeeping
+        // copied from production reaches gigabytes. Without CASCADE it fails when a table outside
+        // this list references one in it, so workspace-owned references are never erased.
+        const clear = [
+            ...[...OAUTH_TABLES].reverse(),
+            "_federation_sessions",
+            API_KEYS_TABLE,
+            // Channel lifecycle and limits are durable policy, including sticky member blocks.
+            // List ephemeral agent state explicitly so new policy tables are never cleared by default.
+            CONFIRMATION_TABLE,
+            AGENT_COUNTERS_TABLE,
+            AGENT_IDENTITIES_TABLE,
+            IDENTITY_NOTICES_TABLE,
+            AGENT_PAIRINGS_TABLE,
+            AGENT_TASKS_TABLE,
+            SIGN_IN_EMAILS_TABLE,
+            WORKFLOW_STARTS_TABLE,
+            ATTACHMENTS_TABLE,
+            "_blob_action_results",
+            "_blob_uploads",
+            "_ontology_replication_delivery",
+            "_ontology_replication_segments",
+            "_ontology_replication_control_jobs",
+            "_ontology_replication_source_replacements",
+            "_ontology_replication_epochs",
+            "_ontology_replication_scans",
+            "_ontology_replication_baselines",
+            "_ontology_replication_receipts",
+            "_ontology_replication_targets",
+        ];
+        if (present.has("_ontology_replication")) {
+            yield* sql.unsafe(`UPDATE _ontology_replication SET enabled=false,
+          source_id=gen_random_uuid(), active_generation=NULL, selection='{}'::jsonb WHERE id`);
+        }
+        const cleared = clear.filter((table) => present.has(table));
+        if (cleared.length > 0) {
+            yield* sql.unsafe(`TRUNCATE ${cleared.map(quoteIdentifier).join(", ")}`);
+        }
+        // Channel accounts are cleared with their legacy rows: the copy's agent acts for no one until
+        // members pair again. Sign-in identities stay, as Neon Auth and the user records do.
+        if (present.has(USER_IDENTITY_TABLE)) {
+            yield* sql.unsafe(`DELETE FROM ${quoteIdentifier(USER_IDENTITY_TABLE)} ` +
+                `WHERE "origin"::text IN ${CHANNEL_ORIGIN_SQL}`);
+        }
+    }));
+}

package/dist/migrate/storage.d.ts

@@ -0,0 +1,226 @@
+import { type EntityManifest, type PropertyManifest, type RelationshipManifest } from "../manifest.js";
+import type { PropertyType } from "../property.js";
+/**
+ * The physical mapping of an ontology onto Postgres. The planner creates exactly these objects and the
+ * runtime reads and writes them, so every name here is part of the storage contract.
+ */
+/** Postgres silently truncates longer identifiers; the planner refuses names that would be truncated. */
+export declare const MAX_IDENTIFIER_LENGTH = 63;
+/** The one-row table that records the applied manifest. */
+export declare const CATALOG_TABLE = "_ontology";
+/** The built-in user entity's table. System columns and history principals refer to it. */
+export declare const USER_TABLE = "user";
+/** System properties and their columns, present on every entity table. */
+export declare const SYSTEM_COLUMNS: {
+    readonly id: "id";
+    readonly created_at: "created_at";
+    readonly updated_at: "updated_at";
+    readonly created_by: "created_by";
+    readonly updated_by: "updated_by";
+};
+/** The kinds of change a history row records. */
+export declare const HISTORY_KINDS: readonly ["create", "update", "delete", "link", "unlink"];
+/**
+ * Column types of every property type except `select`, which gets an enum type of its own, and
+ * `list`, which has no column: the runtime reads it from the platform's tables.
+ */
+export declare const COLUMN_TYPES: {
+    readonly text: "text";
+    readonly email: "text";
+    readonly url: "text";
+    readonly integer: "bigint";
+    readonly number: "double precision";
+    readonly boolean: "boolean";
+    readonly date: "date";
+    readonly timestamp: "timestamptz";
+    readonly json: "jsonb";
+    readonly blob: "uuid";
+};
+/** Whether a property has a column: every type but `list`. */
+export declare function isStoredProperty(property: {
+    readonly type: PropertyType;
+}): boolean;
+/** The entity with only the properties that have a column, as storage and migrations see it. */
+export declare function storedEntity(entity: EntityManifest): EntityManifest;
+export interface ColumnStorage {
+    readonly name: string;
+    /** The SQL type, with enum types quoted. */
+    readonly type: string;
+    readonly notNull: boolean;
+    /** The SQL default expression. */
+    readonly default?: string;
+}
+/** A named `CHECK` or `FOREIGN KEY` table constraint. */
+export interface ConstraintStorage {
+    readonly name: string;
+    readonly kind: "check" | "foreignKey";
+    /** The constraint after `CONSTRAINT <name>`, for example `CHECK ("fit_score" >= 0)`. */
+    readonly definition: string;
+    /** The table a foreign key points at. */
+    readonly references?: string;
+}
+export interface IndexStorage {
+    readonly name: string;
+    readonly table: string;
+    readonly columns: ReadonlyArray<string>;
+    readonly unique: boolean;
+    /** Why the index exists, for plan descriptions. */
+    readonly origin: string;
+}
+export interface TableStorage {
+    readonly name: string;
+    readonly columns: ReadonlyArray<ColumnStorage>;
+    /** The primary key constraint; its index has the same name. */
+    readonly primaryKey: {
+        readonly name: string;
+        readonly columns: ReadonlyArray<string>;
+    };
+    readonly constraints: ReadonlyArray<ConstraintStorage>;
+    readonly indexes: ReadonlyArray<IndexStorage>;
+}
+export interface EnumStorage {
+    readonly name: string;
+    /** The option values in declaration order, which is also their sort order. */
+    readonly values: ReadonlyArray<string>;
+}
+/** Everything one entity stores: its table, its history table, its enum types and its join tables. */
+export interface EntityStorage {
+    readonly entity: string;
+    readonly table: TableStorage;
+    readonly history: TableStorage;
+    readonly enums: ReadonlyArray<EnumStorage>;
+    /** One join table per `rel.many` the entity declares. */
+    readonly joins: ReadonlyArray<TableStorage>;
+}
+/** `"name"`, with embedded quotes doubled. */
+export declare function quoteIdentifier(name: string): string;
+/** `'value'`, with embedded quotes doubled (standard_conforming_strings is on). */
+export declare function quoteLiteral(value: string): string;
+/** `fitScore` → `fit_score`. New property names already use snake_case; conversion remains for historical manifests. */
+export declare function snakeCase(name: string): string;
+/** An entity's table is named after the entity: `lead`, `user`. */
+export declare function tableName(entity: string): string;
+export declare function historyTableName(entity: string): string;
+/** The column of a property: `fitScore` → `fit_score`. */
+export declare function columnName(property: string): string;
+/** The key column of a `rel.one`: `owner` → `owner_id`. */
+export declare function relationshipColumnName(relationship: string): string;
+/** The join table of a `rel.many`: `lead` + `tags` → `lead_tags`. */
+export declare function joinTableName(entity: string, relationship: string): string;
+/**
+ * The two key columns of a join table: `<entity>_id` and `<target>_id`. A relationship from an entity to
+ * itself names the target column after the relationship instead (`lead_id`, `related_id`).
+ */
+export declare function joinColumnNames(input: {
+    readonly entity: string;
+    readonly relationship: string;
+    readonly target: string;
+}): {
+    readonly source: string;
+    readonly target: string;
+};
+/** The enum type of a `select` property: `lead` + `status` → `lead_status`. */
+export declare function enumTypeName(entity: string, property: string): string;
+/** The unique index of a `unique: true` property. */
+export declare function uniqueIndexName(entity: string, property: string): string;
+/** The `CHECK` constraint holding a property's `maxLength`, `min` and `max`. */
+export declare function checkConstraintName(entity: string, property: string): string;
+export declare function foreignKeyName(table: string, column: string): string;
+export declare function primaryKeyName(table: string): string;
+/** An index over columns: `lead` + `status, created_at` → `lead_status_created_at_idx`. */
+export declare function indexName(table: string, columns: ReadonlyArray<string>): string;
+/**
+ * The column of an index field: a system property (`created_at` → `created_at`), a property, or a
+ * stored `rel.one` (`owner` → `owner_id`). Returns undefined for anything else, value-matched
+ * relationships included: they have no column.
+ */
+export declare function fieldColumnName(entity: EntityManifest, field: string): string | undefined;
+/** The SQL default of a property, or undefined when it declares none. */
+export declare function defaultExpression(property: PropertyManifest): string | undefined;
+/** The body of a property's `CHECK` constraint, or undefined when it has no bounds. */
+export declare function checkExpression(property: PropertyManifest): string | undefined;
+export declare function propertyColumn(entity: string, property: PropertyManifest): ColumnStorage;
+export declare function propertyCheck(entity: string, property: PropertyManifest): ConstraintStorage | undefined;
+export declare function propertyEnum(entity: string, property: PropertyManifest): EnumStorage | undefined;
+export declare function blobForeignKey(entity: string, property: PropertyManifest): ConstraintStorage;
+/** The key column of a `rel.one`. */
+export declare function relationshipColumn(relationship: RelationshipManifest): ColumnStorage;
+/** The foreign key of a `rel.one`, with its `onDelete` action. */
+export declare function relationshipForeignKey(entity: string, relationship: RelationshipManifest): ConstraintStorage;
+/** The join table of a `rel.many`: both keys cascade, and the target key is indexed. */
+export declare function joinTable(entity: string, relationship: RelationshipManifest): TableStorage;
+/** Covers rolling activity counts without reading the JSON history payloads. */
+export declare function historyActivityIndex(entity: string): IndexStorage;
+/** `<entity>_history`: one row per change to a record, written by the runtime. */
+export declare function historyTable(entity: string): TableStorage;
+/** The table, history table, enum types and join tables of an entity. */
+export declare function entityStorage(declared: EntityManifest): EntityStorage;
+/** The `_ontology` catalog table. */
+export declare const CATALOG_TABLE_DDL: string;
+/** Role assignments: the roles a user holds beyond the `member` every active member has. */
+export declare const USER_ROLES_TABLE = "_user_roles";
+/**
+ * API keys. A key is `ssk_<key id>.<secret>`: the key id is stored in clear to find the row, the
+ * secret only as a salted PBKDF2 hash.
+ */
+export declare const API_KEYS_TABLE = "_api_keys";
+/** OAuth clients that registered themselves to connect agents to the MCP server. */
+export declare const OAUTH_CLIENTS_TABLE = "_oauth_clients";
+/** Authorization requests waiting for a member's consent, for a few minutes. */
+export declare const OAUTH_REQUESTS_TABLE = "_oauth_requests";
+/** What a member allowed a client to do: revoking a grant stops its tokens. */
+export declare const OAUTH_GRANTS_TABLE = "_oauth_grants";
+/** Authorization codes, access tokens and refresh tokens, stored only as SHA-256 hashes. */
+export declare const OAUTH_TOKENS_TABLE = "_oauth_tokens";
+/** The OAuth tables, in the order they are created. */
+export declare const OAUTH_TABLES: ReadonlyArray<string>;
+/** The OAuth tables of the MCP server's authorization server. Every statement is idempotent. */
+export declare const OAUTH_TABLES_DDL: ReadonlyArray<string>;
+/** Channel accounts waiting, for ten minutes, for a member to claim them with a short code. */
+export declare const AGENT_PAIRINGS_TABLE = "_agent_pairings";
+/**
+ * Channel accounts paired with members, as SDKs before `user_identity` read them. The built-in
+ * `user_identity` entity holds them now, with the same ids; this table is still written beside it
+ * so that an earlier SDK deployed again finds them. See docs/workspace-user-identities.md.
+ */
+export declare const AGENT_IDENTITIES_TABLE = "_agent_identities";
+/**
+ * When a provisioned channel account was last shown the first-contact notice, keyed by its
+ * `user_identity` id: operational state, not identity data. It has no foreign key, so that an
+ * earlier SDK may still drop the `user_identity` table it does not know.
+ */
+export declare const IDENTITY_NOTICES_TABLE = "_identity_notices";
+/** Durable fixed-window admission and turn counters. */
+export declare const AGENT_COUNTERS_TABLE = "_agent_counters";
+/** User-scoped channel lifecycle and trusted effective limits shared across entry points. */
+export declare const CHANNEL_USERS_TABLE = "_channel_users";
+export declare const CHANNEL_LIMITS_TABLE = "_channel_limits";
+/** The agent's tables, in the order they are created. */
+export declare const AGENT_TABLES: ReadonlyArray<string>;
+/**
+ * The tables of the app's agent: pairing codes, stored only as SHA-256 hashes, the legacy channel
+ * identities they create, and the first-contact notices of `user_identity` channel accounts. An
+ * account and a member each have at most one live identity per provider. Every statement is
+ * idempotent.
+ */
+export declare const AGENT_TABLES_DDL: ReadonlyArray<string>;
+/**
+ * The runtime's own tables beside the catalog. They are created with it, after the entity tables
+ * because they refer to the built-in user table, and every statement is idempotent.
+ */
+export declare const ACTION_ATTRIBUTION_TABLE = "_ontology_action_attribution";
+/** Runtime audit metadata deliberately has no foreign key: deleted records retain their history. */
+export declare const ACTION_ATTRIBUTION_DDL: ReadonlyArray<string>;
+export declare const RUNTIME_TABLES_DDL: ReadonlyArray<string>;
+export declare function columnDefinition(column: ColumnStorage): string;
+export declare function constraintDefinition(constraint: {
+    readonly name: string;
+    readonly definition: string;
+}): string;
+/** `CREATE TABLE` with every column, the primary key and the given constraints. */
+export declare function createTableStatement(table: TableStorage, constraints?: ReadonlyArray<ConstraintStorage>): string;
+export declare function createIndexStatement(index: IndexStorage, options?: {
+    readonly concurrently?: boolean;
+}): string;
+export declare function createEnumStatement(storage: EnumStorage): string;
+export declare function addConstraintStatement(table: string, constraint: ConstraintStorage): string;