@segmentstream/ontology 0.0.0-stage → 0.92.0

package/dist/migrate/model.js

@@ -0,0 +1,148 @@
+import { Schema } from "effect";
+import { canonicalJson, IndexManifest, OntologyManifest, PropertyManifestWire, RelationshipManifestWire, } from "../manifest.js";
+/** What a step does, at the level of the ontology. */
+export const MIGRATION_STEP_KINDS = [
+    "createCatalog",
+    "createEntity",
+    "restoreEntity",
+    "renameEntity",
+    "dropEntities",
+    "removeEntities",
+    "addProperty",
+    "restoreProperty",
+    "renameProperty",
+    "dropProperty",
+    "removeProperty",
+    "changeOptional",
+    "changeDefault",
+    "changeCheck",
+    "addSelectOption",
+    "rebuildSelect",
+    "addRelationship",
+    "restoreRelationship",
+    "dropRelationship",
+    "removeRelationship",
+    "changeOnDelete",
+    "addForeignKey",
+    "addIndex",
+    "dropIndex",
+];
+/**
+ * - `additive`: creates something new; existing rows are untouched.
+ * - `rename`: renames tables, columns and the objects named after them.
+ * - `change`: changes a definition in place, removes it from the ontology while retaining data, or
+ *   declares retained data again.
+ * - `destructive`: drops stored data. Planned only with `allowDrops`.
+ */
+export const MIGRATION_STEP_CLASSIFICATIONS = [
+    "additive",
+    "rename",
+    "change",
+    "destructive",
+];
+export const MigrationStep = Schema.Struct({
+    kind: Schema.Literals(MIGRATION_STEP_KINDS),
+    classification: Schema.Literals(MIGRATION_STEP_CLASSIFICATIONS),
+    /**
+     * False for statements Postgres cannot run in a transaction block (`CREATE INDEX CONCURRENTLY`,
+     * `ALTER TYPE … ADD VALUE`). They come first in the plan and run, in order, before the transaction.
+     */
+    transactional: Schema.Boolean,
+    /** The step fails when existing rows violate the new definition, for example nulls under `NOT NULL`. */
+    validatesData: Schema.Boolean,
+    description: Schema.String,
+    /** One statement per entry, run in order. */
+    sql: Schema.Array(Schema.String),
+});
+export const MIGRATION_REFUSAL_CODES = [
+    "invalid-manifest",
+    "type-change",
+    "relationship-change",
+    "drop-refused",
+    "name-collision",
+    "identifier-too-long",
+    "rename-conflict",
+    // @legacy ontology.replication-older-source-protocols
+    // Decode historical SDK refusals; current replication evolution does not emit this code.
+    "replication-rebuild-required",
+    "replication-publication-pending",
+];
+/** A change the planner will not make. A plan with refusals cannot be applied. */
+export const MigrationRefusal = Schema.Struct({
+    code: Schema.Literals(MIGRATION_REFUSAL_CODES),
+    /** Where, in the style of `check` diagnostics: `lead.properties.status`. */
+    path: Schema.String,
+    message: Schema.String,
+});
+/**
+ * Storage the database keeps for an entity the ontology no longer declares, or for the fields a
+ * declared entity no longer declares. Its names derive from it as from a declared entity's, and
+ * renames keep them current. Kept storage holds no foreign keys; kept fields are also nullable and
+ * have no default or index. Declaring the entity again with its id, or the field again under its
+ * name, restores it.
+ */
+export const RetainedEntity = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    /** The entity is no longer declared: its table, history table, enum types and join tables are kept. */
+    removed: Schema.Boolean,
+    /** A removed entity's members and indexes as they were declared; none for a declared entity. */
+    properties: Schema.Array(PropertyManifestWire),
+    relationships: Schema.Array(RelationshipManifestWire),
+    indexes: Schema.Array(IndexManifest),
+    /** The fields removed while the entity was declared, as their storage keeps them. */
+    fields: Schema.Struct({
+        properties: Schema.Array(PropertyManifestWire),
+        relationships: Schema.Array(RelationshipManifestWire),
+    }),
+});
+/** What the catalog records beside the applied manifest about the storage it keeps. */
+export const RetainedStorage = Schema.Struct({ entities: Schema.Array(RetainedEntity) });
+export const NO_RETAINED_STORAGE = { entities: [] };
+/** A removed entity's declared definition, as an entity: its kept fields are not included. */
+export function retainedEntityManifest(retained) {
+    return {
+        id: retained.id,
+        name: retained.name,
+        label: retained.name,
+        plural: retained.name,
+        title: "id",
+        description: "",
+        builtIn: false,
+        properties: retained.properties,
+        relationships: retained.relationships,
+        indexes: retained.indexes,
+        actions: [],
+    };
+}
+const encodeRetainedStorage = Schema.encodeSync(RetainedStorage);
+/** The record in its stored JSON form, with keys in a canonical order. */
+export function retainedStorageJson(retained) {
+    return canonicalJson(encodeRetainedStorage(retained));
+}
+/**
+ * The ordered steps that take a database from the applied manifest to the target. Plain data: it can be
+ * shown, journaled and applied later; the applier refuses it if the database moved on in between.
+ */
+export const MigrationPlan = Schema.Struct({
+    /** The hash of the applied manifest the plan starts from; absent for a fresh database. */
+    currentHash: Schema.optionalKey(Schema.String),
+    target: OntologyManifest,
+    /** Non-transactional steps first, then the steps of the one transaction, in execution order. */
+    steps: Schema.Array(MigrationStep),
+    refusals: Schema.Array(MigrationRefusal),
+    /**
+     * The kept storage the catalog records before the plan and after it; absent from a plan made
+     * without the record, which neither restores nor records kept storage. The applier refuses the
+     * plan when the catalog no longer records `current`, and records `target`.
+     */
+    retained: Schema.optionalKey(Schema.Struct({ current: RetainedStorage, target: RetainedStorage })),
+});
+/** Nothing to run and the catalog already records the target: applying the plan changes nothing. */
+export function isNoopMigration(plan) {
+    return (plan.refusals.length === 0 &&
+        plan.steps.length === 0 &&
+        plan.currentHash === plan.target.hash &&
+        (plan.retained === undefined ||
+            retainedStorageJson(plan.retained.current) === retainedStorageJson(plan.retained.target)));
+}

package/dist/migrate/plan.d.ts

@@ -0,0 +1,51 @@
+import { type OntologyManifest } from "../manifest.js";
+import { type MigrationPlan, type RetainedStorage } from "./model.js";
+export interface MigrationOptions {
+    /**
+     * Drop entities, properties and relationships that are no longer declared, with their data.
+     * Without it, their storage is retained. Removing select options always validates existing
+     * records and fails transactionally while any record holds a removed value.
+     */
+    readonly allowDrops?: boolean;
+}
+export interface PlanMigrationInput {
+    /** The applied manifest from `readCatalog`, or undefined for a fresh database. */
+    readonly current: OntologyManifest | undefined;
+    readonly target: OntologyManifest;
+    readonly options?: MigrationOptions;
+    /**
+     * The runtime tables the database has, from `readRuntimeTables`. A database migrated by an earlier
+     * SDK lacks the tables added since, and the plan creates them. Without it, the plan assumes the
+     * database has every runtime table.
+     */
+    readonly existingTables?: ReadonlySet<string>;
+    /** Valid activity indexes from readHistoryActivityIndexes; omitted assumes current SDK storage. */
+    readonly existingHistoryActivityIndexes?: ReadonlySet<string>;
+    /**
+     * The storage the catalog records as kept, from `readRetainedStorage`. Declaring a kept entity
+     * again with its id, or a kept field under its name, restores it, and the plan records what it
+     * keeps. Without it, the plan neither restores nor records kept storage, as before the catalog
+     * recorded any.
+     */
+    readonly retained?: RetainedStorage;
+    /**
+     * The names in the database's schema, from `readStorageNames`. With them, the plan refuses to
+     * create or rename into a name that neither the applied ontology nor its kept storage accounts
+     * for, such as storage an earlier SDK kept, and forgets kept storage that is no longer there.
+     * Without them, it trusts the catalog.
+     */
+    readonly existingStorage?: StorageNames;
+}
+/** The names a database's schema holds, from `readStorageNames`. */
+export interface StorageNames {
+    /** Tables, indexes, sequences, views and types, which share one namespace. */
+    readonly names: ReadonlyArray<string>;
+    /** The columns of each table. */
+    readonly columns: Readonly<Record<string, ReadonlyArray<string>>>;
+}
+/**
+ * Plans the migration from the applied manifest, the storage the catalog keeps and the observed
+ * storage to the target. It is pure: the same inputs give the same plan. An unchanged manifest can
+ * still need runtime storage upgrades.
+ */
+export declare function planMigration(input: PlanMigrationInput): MigrationPlan;