@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/bin/check.js

@@ -0,0 +1,99 @@
+import { formatDiagnostics } from "../diagnostics.js";
+import { formatManifest } from "../manifest.js";
+import { renderCatalog } from "../render.js";
+import { describeError, EXIT_CODES } from "./output.js";
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+function listed(count, names) {
+    return names.length === 0 ? String(count) : `${count} (${names.join(", ")})`;
+}
+/** Counts and names of what the manifest declares, the built-in `User` and `member` included. */
+export function catalogSummary(manifest) {
+    const entities = manifest.entities.map((entity) => entity.name);
+    const properties = manifest.entities.reduce((count, entity) => count + entity.properties.length, 0);
+    const relationships = manifest.entities.flatMap((entity) => entity.relationships.map((relationship) => `${entity.name}.${relationship.name}`));
+    const actions = manifest.entities.flatMap((entity) => entity.actions.map((action) => `${entity.name}.${action.name}`));
+    const roles = manifest.roles.map((role) => role.name);
+    const workflows = (manifest.workflows ?? []).map((workflow) => workflow.name);
+    return [
+        `Entities: ${listed(entities.length, entities)}`,
+        `Properties: ${properties}`,
+        `Relationships: ${listed(relationships.length, relationships)}`,
+        `Actions: ${listed(actions.length, actions)}`,
+        `Roles: ${listed(roles.length, roles)}`,
+        ...(manifest.feedback === undefined
+            ? []
+            : [
+                `Feedback: ${manifest.feedback.enabled ? "enabled" : "disabled"}; ` +
+                    `files: ${manifest.feedback.files ? "enabled" : "disabled"} ` +
+                    "(explicit setting or another non-feedback blob); " +
+                    `builders: ${manifest.feedback.builders.join(", ") || "none"}`,
+            ]),
+        ...(workflows.length > 0 ? [`Workflows: ${listed(workflows.length, workflows)}`] : []),
+        `Manifest hash: ${manifest.hash}`,
+        "",
+    ].join("\n");
+}
+function reportDiagnostics(entry, diagnostics, output) {
+    if (diagnostics.length === 0) {
+        return;
+    }
+    const count = (severity) => diagnostics.filter((diagnostic) => diagnostic.severity === severity).length;
+    const notes = count("info");
+    const counts = [
+        plural(count("error"), "error"),
+        plural(count("warning"), "warning"),
+        ...(notes > 0 ? [plural(notes, "note")] : []),
+    ];
+    output.stderr(`${formatDiagnostics(diagnostics)}\n`);
+    output.stderr(`${entry}: ${counts.join(", ")}.\n`);
+}
+/**
+ * Loads the ontology and reports every diagnostic on stderr. Returns the loaded ontology, or
+ * undefined when it does not load or has errors.
+ */
+export async function loadCheckedOntology(entry, dependencies) {
+    const { load, output } = dependencies;
+    const loaded = await load(entry);
+    if (loaded._tag === "Failed") {
+        const lines = [
+            loaded.reason,
+            ...(loaded.error === undefined ? [] : [describeError(loaded.error, { stack: true })]),
+            ...(loaded.hint === undefined ? [] : [loaded.hint]),
+        ];
+        output.stderr(`${lines.join("\n")}\n`);
+        return undefined;
+    }
+    const hasErrors = loaded.diagnostics.some((diagnostic) => diagnostic.severity === "error");
+    reportDiagnostics(entry, loaded.diagnostics, output);
+    return loaded._tag === "Loaded" && !hasErrors ? loaded : undefined;
+}
+/**
+ * `segmentstream-ontology check`: loads the ontology as the deploy pipeline does, reports what
+ * `check` found and prints the catalog summary, the manifest or the catalog prose. Diagnostics go to
+ * stderr; any error fails the command.
+ */
+export async function checkCommand(input, dependencies) {
+    const { output } = dependencies;
+    const loaded = await loadCheckedOntology(input.entry, dependencies);
+    if (loaded === undefined) {
+        return EXIT_CODES.failed;
+    }
+    if (Object.values(loaded.ontology.signIn.channels ?? {}).includes("open")) {
+        output.stderr("Agent notice/limits checks skipped: agent config is not visible to ontology check.\n");
+    }
+    switch (input.format) {
+        case "manifest":
+            // As `defineOntology` built it, with any field this SDK's contract does not know.
+            output.stdout(formatManifest(loaded.ontology.manifest));
+            break;
+        case "catalog":
+            output.stdout(renderCatalog(loaded.manifest));
+            break;
+        case "summary":
+            output.stdout(catalogSummary(loaded.manifest));
+            break;
+    }
+    return EXIT_CODES.ok;
+}

package/dist/bin/load.d.ts

@@ -0,0 +1,48 @@
+import { Diagnostic } from "../diagnostics.js";
+import { OntologyManifest } from "../manifest.js";
+import type { Ontology } from "../ontology.js";
+/** The entry the commands load when none is given: run them in the workspace's `ontology/` folder. */
+export declare const DEFAULT_ENTRY = "./index.ts";
+/** Imports an ES module by its file URL and returns its namespace. */
+export type ModuleImport = (url: string) => Promise<unknown>;
+export type LoadResult = {
+    readonly _tag: "Loaded";
+    readonly entry: string;
+    readonly ontology: Ontology;
+    /** The default export's manifest, validated against this SDK's model contract. */
+    readonly manifest: OntologyManifest;
+    /** What `check` reported while `defineOntology` ran: warnings only, since it did not throw. */
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+} | {
+    /** `defineOntology` threw: the definition has errors. */
+    readonly _tag: "Invalid";
+    readonly entry: string;
+    readonly diagnostics: ReadonlyArray<Diagnostic>;
+} | {
+    readonly _tag: "Failed";
+    readonly entry: string;
+    readonly reason: string;
+    /** The original error, when there is one: a module that does not compile or throws. */
+    readonly error?: unknown;
+    /** A likely cause the original error does not name. */
+    readonly hint?: string;
+};
+export type OntologyLoader = (entry: string) => Promise<LoadResult>;
+/**
+ * Imports a module the way the deploy pipeline's evaluator does under `node --import tsx`: the
+ * pinned tsx loader's ES module and CommonJS hooks are registered for the whole process, without a
+ * namespace, so TypeScript and extensionless relative imports resolve alike, and the ontology's
+ * `@segmentstream/ontology` and `effect` imports load the same modules as the binary's when
+ * they resolve to the same files.
+ */
+export declare const importWithTsx: ModuleImport;
+/**
+ * Loads the module at `entry`, relative to `cwd`, and returns its default export when it is an
+ * ontology. The diagnostics are those `check` reported inside `defineOntology`, in the copy of the
+ * SDK the ontology imports, which is the copy the deploy pipeline evaluates it with; when
+ * `defineOntology` threw, those of `InvalidOntology`. Any other failure keeps the original error.
+ */
+export declare function loadOntology(input: {
+    readonly entry: string;
+    readonly cwd: string;
+}, importModule: ModuleImport): Promise<LoadResult>;

package/dist/bin/load.js

@@ -0,0 +1,139 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Result, Schema } from "effect";
+import { Diagnostic } from "../diagnostics.js";
+import { OntologyManifest } from "../manifest.js";
+/** The entry the commands load when none is given: run them in the workspace's `ontology/` folder. */
+export const DEFAULT_ENTRY = "./index.ts";
+const Diagnostics = Schema.Array(Diagnostic);
+// defineOntology exposes the decoded model, not the snake_case JSON written to disk.
+const validateManifest = Schema.decodeUnknownResult(Schema.toType(OntologyManifest));
+let registration;
+/**
+ * Imports a module the way the deploy pipeline's evaluator does under `node --import tsx`: the
+ * pinned tsx loader's ES module and CommonJS hooks are registered for the whole process, without a
+ * namespace, so TypeScript and extensionless relative imports resolve alike, and the ontology's
+ * `@segmentstream/ontology` and `effect` imports load the same modules as the binary's when
+ * they resolve to the same files.
+ */
+export const importWithTsx = async (url) => {
+    registration ??= Promise.all([
+        import("tsx/esm/api").then((tsx) => tsx.register()),
+        import("tsx/cjs/api").then((tsx) => tsx.register()),
+    ]);
+    await registration;
+    return import(url);
+};
+/** The `type` of the package that holds `path`: `commonjs` when its package.json has none. */
+async function packageType(path) {
+    let directory = dirname(path);
+    for (;;) {
+        const manifest = await readFile(join(directory, "package.json"), "utf8").catch(() => undefined);
+        if (manifest !== undefined) {
+            const type = JSON.parse(manifest)?.type;
+            return typeof type === "string" ? type : "commonjs";
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            return undefined;
+        }
+        directory = parent;
+    }
+}
+/**
+ * Outside an ES module package, tsx compiles the entry to CommonJS, which cannot import the SDK;
+ * the errors Node reports then do not say so. The deploy pipeline fails the same way.
+ */
+async function moduleTypeHint(path) {
+    const type = await packageType(path).catch(() => undefined);
+    if (type === "module") {
+        return undefined;
+    }
+    return 'The ontology is an ES module: its package.json must set "type": "module".';
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/** `defineOntology` throws `InvalidOntology`; another copy of the SDK may have thrown it. */
+function invalidOntologyDiagnostics(error) {
+    if (!isRecord(error) || error._tag !== "InvalidOntology") {
+        return undefined;
+    }
+    return Schema.is(Diagnostics)(error.diagnostics) ? error.diagnostics : undefined;
+}
+/**
+ * The shape of `defineOntology`'s result. The ontology may import another copy of the SDK than the
+ * binary's, so neither `instanceof` nor entity identity can tell.
+ */
+function isOntology(value) {
+    if (!isRecord(value) || !isRecord(value.config) || !isRecord(value.manifest)) {
+        return false;
+    }
+    return (Array.isArray(value.config.entities) &&
+        Array.isArray(value.entities) &&
+        Schema.is(Diagnostics)(value.warnings));
+}
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Loads the module at `entry`, relative to `cwd`, and returns its default export when it is an
+ * ontology. The diagnostics are those `check` reported inside `defineOntology`, in the copy of the
+ * SDK the ontology imports, which is the copy the deploy pipeline evaluates it with; when
+ * `defineOntology` threw, those of `InvalidOntology`. Any other failure keeps the original error.
+ */
+export async function loadOntology(input, importModule) {
+    const { entry } = input;
+    const path = resolve(input.cwd, entry);
+    if (!(await isFile(path))) {
+        return { _tag: "Failed", entry, reason: `${entry} does not exist or is not a file.` };
+    }
+    let namespace;
+    try {
+        namespace = await importModule(pathToFileURL(path).href);
+    }
+    catch (error) {
+        const diagnostics = invalidOntologyDiagnostics(error);
+        if (diagnostics !== undefined) {
+            return { _tag: "Invalid", entry, diagnostics };
+        }
+        const hint = await moduleTypeHint(path);
+        return {
+            _tag: "Failed",
+            entry,
+            reason: `${entry} failed to load.`,
+            error,
+            ...(hint === undefined ? {} : { hint }),
+        };
+    }
+    const ontology = isRecord(namespace) ? namespace.default : undefined;
+    if (!isOntology(ontology)) {
+        return {
+            _tag: "Failed",
+            entry,
+            reason: `${entry} must default-export the result of defineOntology(...).`,
+        };
+    }
+    const manifest = validateManifest(ontology.manifest);
+    if (Result.isFailure(manifest)) {
+        return {
+            _tag: "Failed",
+            entry,
+            reason: `The manifest of ${entry} does not match this SDK's manifest contract.`,
+            error: manifest.failure,
+        };
+    }
+    return {
+        _tag: "Loaded",
+        entry,
+        ontology,
+        manifest: manifest.success,
+        diagnostics: ontology.warnings,
+    };
+}

package/dist/bin/main.d.ts

@@ -0,0 +1,31 @@
+import { Redacted } from "effect";
+import { type CheckFormat } from "./check.js";
+import { type OntologyLoader } from "./load.js";
+import { type OwnerConnection } from "./migrate.js";
+import { type ExitCode, type Output } from "./output.js";
+export declare const USAGE = "Usage: segmentstream-ontology <command> [entry] [options]\n\nRun the commands in the workspace's ontology/ folder. The entry is the module that\ndefault-exports defineOntology(...); it defaults to ./index.ts.\n\nCommands:\n  check [entry]      Load the ontology, report its diagnostics and summarize the catalog.\n    --manifest       Print the manifest JSON instead of the summary.\n    --catalog        Print the catalog as prose instead of the summary.\n\n  migrate [entry]    Plan the migration against the catalog recorded in the database and\n                     apply it. Dropping entities, properties or relationships is refused.\n    --database-url <url>\n                     The owner connection string (ontology_owner, direct). Defaults to\n                     SEGMENTSTREAM_ONTOLOGY_MIGRATE_URL.\n    --plan           Print the plan with its SQL and apply nothing.\n                     With SEGMENTSTREAM_WORKSPACE_ID set, it also reconciles the workflow\n                     users with the ontology's workflows, as deploy does.\n\nOptions:\n  -h, --help         Show this help.\n\nExit codes: 0 success, 1 errors or failure, 2 migration refused, 64 usage error.\n";
+export type CommandLine = {
+    readonly _tag: "Help";
+} | {
+    readonly _tag: "Usage";
+    readonly message: string;
+} | {
+    readonly _tag: "Check";
+    readonly entry: string;
+    readonly format: CheckFormat;
+} | {
+    readonly _tag: "Migrate";
+    readonly entry: string;
+    readonly planOnly: boolean;
+    readonly databaseUrl: Redacted.Redacted<string> | undefined;
+};
+/** Reads the command line. Errors name options and commands, never a value. */
+export declare function parseCommandLine(args: ReadonlyArray<string>): CommandLine;
+export interface MainDependencies {
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    readonly output: Output;
+    readonly load: OntologyLoader;
+    readonly connect: OwnerConnection;
+}
+/** Runs one command line and returns the process exit code. */
+export declare function runMain(args: ReadonlyArray<string>, dependencies: MainDependencies): Promise<ExitCode>;

package/dist/bin/main.js

@@ -0,0 +1,121 @@
+import { parseArgs } from "node:util";
+import { Redacted } from "effect";
+import { checkCommand } from "./check.js";
+import { DEFAULT_ENTRY } from "./load.js";
+import { MIGRATE_URL_VARIABLE, migrateCommand, WORKSPACE_ID_VARIABLE, } from "./migrate.js";
+import { EXIT_CODES } from "./output.js";
+export const USAGE = `Usage: segmentstream-ontology <command> [entry] [options]
+
+Run the commands in the workspace's ontology/ folder. The entry is the module that
+default-exports defineOntology(...); it defaults to ${DEFAULT_ENTRY}.
+
+Commands:
+  check [entry]      Load the ontology, report its diagnostics and summarize the catalog.
+    --manifest       Print the manifest JSON instead of the summary.
+    --catalog        Print the catalog as prose instead of the summary.
+
+  migrate [entry]    Plan the migration against the catalog recorded in the database and
+                     apply it. Dropping entities, properties or relationships is refused.
+    --database-url <url>
+                     The owner connection string (ontology_owner, direct). Defaults to
+                     ${MIGRATE_URL_VARIABLE}.
+    --plan           Print the plan with its SQL and apply nothing.
+                     With ${WORKSPACE_ID_VARIABLE} set, it also reconciles the workflow
+                     users with the ontology's workflows, as deploy does.
+
+Options:
+  -h, --help         Show this help.
+
+Exit codes: 0 success, 1 errors or failure, 2 migration refused, 64 usage error.
+`;
+const OPTIONS = {
+    help: { type: "boolean", short: "h" },
+    manifest: { type: "boolean" },
+    catalog: { type: "boolean" },
+    plan: { type: "boolean" },
+    "database-url": { type: "string" },
+};
+/** The options each command accepts besides `--help`. */
+const COMMAND_OPTIONS = new Map([
+    ["check", ["manifest", "catalog"]],
+    ["migrate", ["plan", "database-url"]],
+]);
+function usage(message) {
+    return { _tag: "Usage", message };
+}
+/** A connection string in place of a command or entry would be echoed back; it is a credential. */
+function looksLikeUrl(argument) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(argument);
+}
+function checkFormat(values) {
+    if (values.manifest === true) {
+        return "manifest";
+    }
+    return values.catalog === true ? "catalog" : "summary";
+}
+const parse = (args) => parseArgs({ args, options: OPTIONS, allowPositionals: true, strict: true });
+/** Reads the command line. Errors name options and commands, never a value. */
+export function parseCommandLine(args) {
+    let parsed;
+    try {
+        parsed = parse([...args]);
+    }
+    catch (error) {
+        // parseArgs names the option, never its value.
+        return usage(error instanceof Error ? error.message : String(error));
+    }
+    const { values, positionals } = parsed;
+    const [command, ...entries] = positionals;
+    if (values.help === true || command === "help") {
+        return { _tag: "Help" };
+    }
+    if (positionals.some(looksLikeUrl)) {
+        return usage("Commands and entries are not URLs. Pass the connection string with --database-url.");
+    }
+    if (command === undefined) {
+        return usage("Name a command: check or migrate.");
+    }
+    const accepted = COMMAND_OPTIONS.get(command);
+    if (accepted === undefined) {
+        return usage(`Unknown command "${command}". The commands are check and migrate.`);
+    }
+    const given = Object.keys(values).filter((name) => name !== "help");
+    const foreign = given.find((name) => !accepted.includes(name));
+    if (foreign !== undefined) {
+        return usage(`${command} does not take --${foreign}.`);
+    }
+    if (entries.length > 1) {
+        return usage(`${command} takes one entry at most.`);
+    }
+    const entry = entries[0] ?? DEFAULT_ENTRY;
+    if (command === "check") {
+        if (values.manifest === true && values.catalog === true) {
+            return usage("check takes --manifest or --catalog, not both.");
+        }
+        return { _tag: "Check", entry, format: checkFormat(values) };
+    }
+    const databaseUrl = values["database-url"];
+    return {
+        _tag: "Migrate",
+        entry,
+        planOnly: values.plan === true,
+        databaseUrl: databaseUrl === undefined ? undefined : Redacted.make(databaseUrl),
+    };
+}
+/** Runs one command line and returns the process exit code. */
+export async function runMain(args, dependencies) {
+    const { output } = dependencies;
+    const commandLine = parseCommandLine(args);
+    switch (commandLine._tag) {
+        case "Help":
+            output.stdout(USAGE);
+            return EXIT_CODES.ok;
+        case "Usage":
+            output.stderr(`${commandLine.message}\n\n${USAGE}`);
+            return EXIT_CODES.usage;
+        case "Check":
+            return checkCommand(commandLine, dependencies);
+        case "Migrate":
+            return migrateCommand({ ...commandLine, environment: dependencies.environment }, dependencies);
+    }
+}

package/dist/bin/migrate.d.ts

@@ -0,0 +1,57 @@
+import { type Layer, Redacted } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { type SqlError } from "effect/unstable/sql/SqlError";
+import { type MigrationPlan } from "../migrate/model.js";
+import type { OntologyLoader } from "./load.js";
+import { type ExitCode, type Output } from "./output.js";
+/**
+ * The owner connection string `migrate` reads when `--database-url` is not given: `ontology_owner`
+ * over a direct connection. `SEGMENTSTREAM_ONTOLOGY_DATABASE_URL`, the service's pooled
+ * `ontology_app` role, cannot change the schema and is never read here.
+ */
+export declare const MIGRATE_URL_VARIABLE = "SEGMENTSTREAM_ONTOLOGY_MIGRATE_URL";
+/**
+ * The workspace whose workflow users `migrate` reconciles with the ontology's workflows, as deploy
+ * does. Without it, workflow users are left as they are.
+ */
+export declare const WORKSPACE_ID_VARIABLE = "SEGMENTSTREAM_WORKSPACE_ID";
+/** A dedicated connection for one migration, closed when the command ends. */
+export type OwnerConnection = (url: Redacted.Redacted<string>) => Layer.Layer<SqlClient.SqlClient, SqlError>;
+export interface MigrateInput {
+    readonly entry: string;
+    /** Print the plan and apply nothing. */
+    readonly planOnly: boolean;
+    /** `--database-url`; it takes precedence over the environment. */
+    readonly databaseUrl: Redacted.Redacted<string> | undefined;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+}
+export interface MigrateDependencies {
+    readonly load: OntologyLoader;
+    readonly connect: OwnerConnection;
+    readonly output: Output;
+}
+/** `@effect/sql-pg` on the owner connection string, configured as the deploy pipeline's migrator. */
+export declare const connectOwnerDatabase: OwnerConnection;
+type ResolvedUrl = {
+    readonly _tag: "Resolved";
+    readonly url: Redacted.Redacted<string>;
+} | {
+    readonly _tag: "Unusable";
+    readonly message: string;
+};
+/**
+ * The connection string from `--database-url`, else from the environment. Messages name where it
+ * came from, never its value.
+ */
+export declare function resolveDatabaseUrl(input: MigrateInput): ResolvedUrl;
+/** Where the plan starts and ends, and each step; with `sql`, each step's statements too. */
+export declare function formatPlan(plan: MigrationPlan, options: {
+    readonly sql: boolean;
+}): string;
+/**
+ * `segmentstream-ontology migrate`: checks the ontology, plans the migration against the catalog
+ * recorded in the database and applies it with the SDK's planner and applier, the code the deploy
+ * pipeline runs. Removed declarations retain their storage. Nothing it writes contains the connection string.
+ */
+export declare function migrateCommand(input: MigrateInput, dependencies: MigrateDependencies): Promise<ExitCode>;
+export {};

package/dist/bin/migrate.js

@@ -0,0 +1,170 @@
+import * as PgClient from "@effect/sql-pg/PgClient";
+import { Cause, Effect, Redacted } from "effect";
+import { SqlClient } from "effect/unstable/sql";
+import { isSqlError } from "effect/unstable/sql/SqlError";
+import { applyMigration, readCatalog, readRetainedStorage, readRuntimeTables, readHistoryActivityIndexes, readStorageNames, } from "../migrate/apply.js";
+import { MigrationRefused } from "../migrate/errors.js";
+import { isNoopMigration } from "../migrate/model.js";
+import { planMigration } from "../migrate/plan.js";
+import { loadCheckedOntology } from "./check.js";
+import { postgresTls } from "../runtime/postgres-tls.js";
+import { describeError, EXIT_CODES, redactedOutput } from "./output.js";
+/**
+ * The owner connection string `migrate` reads when `--database-url` is not given: `ontology_owner`
+ * over a direct connection. `SEGMENTSTREAM_ONTOLOGY_DATABASE_URL`, the service's pooled
+ * `ontology_app` role, cannot change the schema and is never read here.
+ */
+export const MIGRATE_URL_VARIABLE = "SEGMENTSTREAM_ONTOLOGY_MIGRATE_URL";
+/**
+ * The workspace whose workflow users `migrate` reconciles with the ontology's workflows, as deploy
+ * does. Without it, workflow users are left as they are.
+ */
+export const WORKSPACE_ID_VARIABLE = "SEGMENTSTREAM_WORKSPACE_ID";
+/** `@effect/sql-pg` on the owner connection string, configured as the deploy pipeline's migrator. */
+export const connectOwnerDatabase = (url) => PgClient.layer({
+    url,
+    ssl: postgresTls(url),
+    maxConnections: 1,
+    applicationName: "segmentstream-ontology-migrate",
+    transformJson: false,
+});
+/**
+ * The connection string from `--database-url`, else from the environment. Messages name where it
+ * came from, never its value.
+ */
+export function resolveDatabaseUrl(input) {
+    const fromFlag = input.databaseUrl === undefined ? undefined : Redacted.value(input.databaseUrl);
+    const value = (fromFlag ?? input.environment[MIGRATE_URL_VARIABLE] ?? "").trim();
+    const source = fromFlag === undefined ? MIGRATE_URL_VARIABLE : "--database-url";
+    if (value === "") {
+        return {
+            _tag: "Unusable",
+            message: "migrate needs the owner connection string: pass --database-url <url> or set " +
+                `${MIGRATE_URL_VARIABLE}. It never reads SEGMENTSTREAM_ONTOLOGY_DATABASE_URL, the ` +
+                "service's role, which cannot change the schema.",
+        };
+    }
+    const protocol = URL.canParse(value) ? new URL(value).protocol : undefined;
+    if (protocol !== "postgres:" && protocol !== "postgresql:") {
+        return {
+            _tag: "Unusable",
+            message: `${source} must be a postgres:// or postgresql:// connection string.`,
+        };
+    }
+    return { _tag: "Resolved", url: Redacted.make(value) };
+}
+function indent(text, prefix) {
+    return text
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
+}
+function stepNoun(steps) {
+    return steps === 1 ? "step" : "steps";
+}
+function formatRefusals(refusals) {
+    const lines = refusals.map((refusal) => `refused ${refusal.path}: ${refusal.message} [${refusal.code}]`);
+    const noun = refusals.length === 1 ? "refusal" : "refusals";
+    return `${lines.join("\n")}\nThe plan has ${refusals.length} ${noun}; nothing was applied.\n`;
+}
+/** Where the plan starts and ends, and each step; with `sql`, each step's statements too. */
+export function formatPlan(plan, options) {
+    const lines = [
+        `Current: ${plan.currentHash ?? "none (the database has no ontology catalog)"}`,
+        `Target: ${plan.target.hash}`,
+        plan.steps.length === 0
+            ? "No schema steps."
+            : `${plan.steps.length} ${stepNoun(plan.steps.length)}:`,
+    ];
+    for (const [index, step] of plan.steps.entries()) {
+        const traits = [
+            step.classification,
+            ...(step.transactional ? [] : ["outside the transaction"]),
+        ];
+        lines.push(`  ${index + 1}. [${traits.join(", ")}] ${step.description}`);
+        if (options.sql) {
+            lines.push(...step.sql.map((statement) => `${indent(statement.trim(), "       ")};`));
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function migrateDatabase(input) {
+    const { output, target } = input;
+    const options = input.workspaceId === undefined ? {} : { workspaceId: input.workspaceId };
+    return Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const current = yield* readCatalog({ sql });
+        const retained = yield* readRetainedStorage({ sql });
+        const existingTables = yield* readRuntimeTables({ sql });
+        const existingHistoryActivityIndexes = yield* readHistoryActivityIndexes({ sql });
+        const existingStorage = yield* readStorageNames({ sql });
+        const plan = planMigration({
+            current,
+            retained,
+            target,
+            existingTables,
+            existingHistoryActivityIndexes,
+            existingStorage,
+        });
+        output.stdout(formatPlan(plan, { sql: input.planOnly }));
+        if (plan.refusals.length > 0) {
+            output.stderr(formatRefusals(plan.refusals));
+            return EXIT_CODES.refused;
+        }
+        if (input.planOnly) {
+            output.stdout(isNoopMigration(plan)
+                ? `The database already records ${plan.target.hash}; nothing to apply.\n`
+                : "Nothing was applied (--plan).\n");
+            return EXIT_CODES.ok;
+        }
+        if (isNoopMigration(plan)) {
+            // Like deploy, a no-op plan still reconciles the workflow users.
+            yield* applyMigration(plan, { sql, ...options });
+            output.stdout(`The database already records ${plan.target.hash}; nothing to apply.\n`);
+            return EXIT_CODES.ok;
+        }
+        const result = yield* applyMigration(plan, { sql, ...options });
+        output.stdout(`Applied ${result.appliedSteps} ${stepNoun(result.appliedSteps)}. ` +
+            `The database records ${result.hash}.\n`);
+        return EXIT_CODES.ok;
+    });
+}
+/** Reports a failure with its original explanation; the output it writes to is redacted. */
+function reportFailure(error, output) {
+    if (error instanceof MigrationRefused) {
+        output.stderr(formatRefusals(error.refusals));
+        return EXIT_CODES.refused;
+    }
+    if (isSqlError(error)) {
+        output.stderr(`The migration failed: ${describeError(error)}\n`);
+        return EXIT_CODES.failed;
+    }
+    // MigrationFailed names the step and keeps the database's explanation as its cause;
+    // CatalogMismatch asks to plan again; CatalogInvalid keeps what did not decode.
+    output.stderr(`${describeError(error)}\n`);
+    return EXIT_CODES.failed;
+}
+/**
+ * `segmentstream-ontology migrate`: checks the ontology, plans the migration against the catalog
+ * recorded in the database and applies it with the SDK's planner and applier, the code the deploy
+ * pipeline runs. Removed declarations retain their storage. Nothing it writes contains the connection string.
+ */
+export async function migrateCommand(input, dependencies) {
+    const databaseUrl = resolveDatabaseUrl(input);
+    if (databaseUrl._tag === "Unusable") {
+        dependencies.output.stderr(`${databaseUrl.message}\n`);
+        return EXIT_CODES.usage;
+    }
+    const output = redactedOutput(dependencies.output, Redacted.value(databaseUrl.url));
+    const loaded = await loadCheckedOntology(input.entry, { load: dependencies.load, output });
+    if (loaded === undefined) {
+        return EXIT_CODES.failed;
+    }
+    const migration = migrateDatabase({
+        target: loaded.manifest,
+        planOnly: input.planOnly,
+        workspaceId: input.environment[WORKSPACE_ID_VARIABLE]?.trim() || undefined,
+        output,
+    }).pipe(Effect.provide(dependencies.connect(databaseUrl.url)), Effect.catchCause((cause) => Effect.sync(() => reportFailure(Cause.squash(cause), output))));
+    return Effect.runPromise(migration);
+}