@brydio/manifest 0.1.0-alpha.0

package/src/field-types.js

@@ -0,0 +1,298 @@
+import { z } from 'zod';
+/**
+ * The bounds a schema and a record are held to (A3-F01-S03).
+ *
+ * `stringChars` is 1,000 (E1, 16 Sep: the feature file wins over contracts'
+ * old 512), the same as `bry-input`'s `INPUT_MAX`, so nothing a person can
+ * type into a text field is refused by the store.
+ */
+export const FIELD_LIMITS = {
+    /** Collections one app may keep. */
+    collections: 20,
+    /** Fields one collection may have. */
+    fields: 40,
+    /** Values one choice may allow. */
+    enumValues: 50,
+    /** Characters in one of a choice's values. */
+    enumValueChars: 64,
+    /** Characters in a `string` value, the same as `bry-input` lets a person type. */
+    stringChars: 1_000,
+    /** Characters in a `text` value. */
+    textChars: 100_000,
+    /** Entries in a `string[]` value. */
+    listEntries: 100,
+    /** Characters in a collection, label, field or screen name. */
+    nameChars: 40,
+};
+/**
+ * The colours a `token` field may hold, by design-token name.
+ *
+ * The status roles `DESIGN_SYSTEM.md` already gives a solid, a text, a tint
+ * and an edge, plus the brand and a neutral. A label picks one by name and
+ * the host draws it in the current theme, so an app never holds a colour
+ * value it could get wrong in dark mode (ADR-A13). `@brydio/manifest` carries
+ * the same list.
+ */
+export const COLOUR_TOKENS = ['neutral', 'brand', 'success', 'warn', 'danger'];
+/**
+ * Names Brydio keeps on every record, or that the generated tools already
+ * use for their own arguments. A field called `version` would be ambiguous in
+ * `update_issue`, and one called `instance` would shadow ADR-A09's argument.
+ */
+export const RESERVED_FIELDS = new Set([
+    'id',
+    'version',
+    'instance',
+    'createdAt',
+    'createdBy',
+    'updatedAt',
+    'deletedAt',
+]);
+/** A field, collection or label name: an identifier the tools can use as-is. */
+export const FIELD_NAME = /^[a-z][a-zA-Z0-9_]*$/;
+export const COLLECTION_NAME = /^[a-z][a-z0-9_]*$/;
+/**
+ * Kept in the plain `fields` column: filterable and sortable. Words never
+ * are: `string`, `text` and `string[]` live only in the encrypted body
+ * (A3-F01-S02, A3-F02-S01; E1, 16 Sep), so a list of labels is found by
+ * search, not by a filter.
+ */
+const STRUCTURED = new Set([
+    'enum',
+    'member',
+    'project',
+    'date',
+    'number',
+    'boolean',
+    'token',
+]);
+/** Only the words in these may one day be searched (A3-F01-S02). */
+const SEARCHABLE = new Set(['string', 'text', 'string[]']);
+const SCALARS = new Set(['string', 'text', 'member', 'project', 'date', 'number', 'boolean', 'token']);
+/** A field type the manifest wrote that Brydio does not have, or a bad list. */
+export class FieldTypeInvalid extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FieldTypeInvalid';
+    }
+}
+/**
+ * One field's manifest spelling, as a type.
+ *
+ * Throws `FieldTypeInvalid` with a code rather than returning null, because
+ * "unknown type" and "a choice with 51 values" are different mistakes and the
+ * import report has to say which.
+ */
+export function parseFieldType(raw) {
+    if (Array.isArray(raw))
+        return parseEnumeration(raw);
+    if (raw && typeof raw === 'object')
+        return parseFieldObject(raw);
+    if (typeof raw !== 'string') {
+        throw new FieldTypeInvalid('data_field_type_unknown', 'A field type is a name such as "string?" or a list of allowed values.');
+    }
+    const optional = raw.endsWith('?');
+    const name = optional ? raw.slice(0, -1) : raw;
+    if (name === 'string[]')
+        return { kind: 'string[]', optional };
+    if (name === 'token')
+        return { kind: 'token', optional, values: COLOUR_TOKENS };
+    if (SCALARS.has(name))
+        return { kind: name, optional };
+    throw new FieldTypeInvalid('data_field_type_unknown', `"${raw}" is not a field type.`);
+}
+const FIELD_KEYS = new Set(['type', 'optional', 'default', 'labels']);
+/** How long a choice value's label may be. */
+export const LABEL_CHARS = 60;
+/** The object form: the short form under `type`, and what it may add. */
+function parseFieldObject(raw) {
+    const unknown = Object.keys(raw).find(key => !FIELD_KEYS.has(key));
+    if (unknown) {
+        throw new FieldTypeInvalid('data_field_key_unknown', `"${unknown}" is not something a field may say; use type, optional, default and labels.`);
+    }
+    if (typeof raw.type !== 'string' && !Array.isArray(raw.type)) {
+        throw new FieldTypeInvalid('data_field_type_unknown', 'A field written as an object names its type under "type".');
+    }
+    if (raw.optional !== undefined && typeof raw.optional !== 'boolean') {
+        throw new FieldTypeInvalid('data_field_key_unknown', '"optional" is true or false.');
+    }
+    const inner = parseFieldType(raw.type);
+    const type = { ...inner, optional: inner.optional || raw.optional === true, ...labelsOf(inner, raw) };
+    if (!('default' in raw))
+        return type;
+    const value = raw.default;
+    if (type.kind !== 'enum' && type.kind !== 'boolean') {
+        throw new FieldTypeInvalid('data_default_not_allowed', `Only a choice or a boolean may have a default, not a ${type.kind}.`);
+    }
+    if (!type.optional) {
+        throw new FieldTypeInvalid('data_default_on_required', 'A field with a default is one a create may leave out: add "optional": true (or write "boolean?").');
+    }
+    if (type.kind === 'enum' ? typeof value !== 'string' || !(type.values ?? []).includes(value) : typeof value !== 'boolean') {
+        throw new FieldTypeInvalid('data_default_invalid', type.kind === 'enum'
+            ? `The default must be one of ${quoted(type.values ?? [])}.`
+            : 'The default of a boolean is true or false.');
+    }
+    return { ...type, default: value };
+}
+/** A choice's `labels`, checked: one short label per value it names, and only values the choice has. */
+function labelsOf(type, raw) {
+    if (!('labels' in raw))
+        return {};
+    if (type.kind !== 'enum') {
+        throw new FieldTypeInvalid('data_labels_not_allowed', `Only a choice may label its values, not a ${type.kind}.`);
+    }
+    const labels = raw.labels;
+    if (!labels || typeof labels !== 'object' || Array.isArray(labels)) {
+        throw new FieldTypeInvalid('data_label_invalid', '"labels" maps each value to how it reads, such as { "todo": "To do" }.');
+    }
+    for (const [value, label] of Object.entries(labels)) {
+        if (!(type.values ?? []).includes(value)) {
+            throw new FieldTypeInvalid('data_label_unknown_value', `"${value}" is not one of ${quoted(type.values ?? [])}, so it can't have a label.`);
+        }
+        if (typeof label !== 'string' || !label.trim() || label.length > LABEL_CHARS) {
+            throw new FieldTypeInvalid('data_label_invalid', `The label for "${value}" is 1 to ${LABEL_CHARS} characters of text.`);
+        }
+    }
+    return { labels: { ...labels } };
+}
+/** How a choice's value reads to a person: its label, or the value itself. */
+export const labelOfValue = (type, value) => type.labels?.[value] ?? value;
+function parseEnumeration(values) {
+    if (!values.length) {
+        throw new FieldTypeInvalid('data_enum_empty', 'A choice needs at least one allowed value.');
+    }
+    if (values.length > FIELD_LIMITS.enumValues) {
+        throw new FieldTypeInvalid('data_enum_too_many', `A choice may have at most ${FIELD_LIMITS.enumValues} values.`);
+    }
+    for (const value of values) {
+        if (typeof value !== 'string' || !value.trim() || value.length > FIELD_LIMITS.enumValueChars) {
+            throw new FieldTypeInvalid('data_enum_value_invalid', `Each allowed value is a word or two of text, at most ${FIELD_LIMITS.enumValueChars} characters.`);
+        }
+    }
+    if (new Set(values).size !== values.length) {
+        throw new FieldTypeInvalid('data_enum_duplicate', 'A choice names the same value twice.');
+    }
+    return { kind: 'enum', optional: false, values: values };
+}
+/** True for a type whose value lands in the plain `fields` column. */
+export const isStructured = (type) => STRUCTURED.has(type.kind);
+/** True for a type a list can be ordered by: structured, and one value. */
+export const isSortable = (type) => STRUCTURED.has(type.kind);
+export const isSearchable = (type) => SEARCHABLE.has(type.kind);
+/**
+ * The names of a schema's structured fields: the ones kept in plain beside the
+ * encrypted body, and so the ones a list may filter on.
+ *
+ * One function, imported by the store and by the tools, so what is written
+ * plainly and what may be filtered cannot drift apart (A3-F01's note). Accepts
+ * the manifest's spelling or parsed types.
+ */
+export function structuredFields(schema) {
+    return Object.entries(schema)
+        .filter(([, raw]) => isStructured(asType(raw)))
+        .map(([name]) => name);
+}
+const asType = (raw) => raw && typeof raw === 'object' && !Array.isArray(raw) && 'kind' in raw && !('type' in raw)
+    ? raw
+    : parseFieldType(raw);
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:\d{2}))?$/;
+/**
+ * What one value of this type may be, as zod.
+ *
+ * The same schema checks a record in the store and describes the argument to
+ * the model, so the tool never accepts something the store then refuses.
+ * Always the required form: callers add `.optional()` where they mean it.
+ */
+export function valueSchema(type) {
+    switch (type.kind) {
+        case 'string':
+            return z.string().max(FIELD_LIMITS.stringChars);
+        case 'text':
+            return z.string().max(FIELD_LIMITS.textChars);
+        case 'enum':
+        case 'token':
+            return z.enum(type.values);
+        case 'member':
+        case 'project':
+            return z.string().min(1).max(200);
+        case 'date':
+            return z
+                .string()
+                .regex(ISO_DATE)
+                .refine(value => !Number.isNaN(Date.parse(value)));
+        case 'number':
+            return z.number().finite();
+        case 'boolean':
+            return z.boolean();
+        case 'string[]':
+            return z.array(z.string().max(FIELD_LIMITS.stringChars)).max(FIELD_LIMITS.listEntries);
+    }
+}
+/**
+ * Why a value is not one of this type, in words the assistant can repeat to
+ * the person, naming the field. Null when it is fine.
+ */
+export function valueProblem(field, type, value) {
+    if (valueSchema(type).safeParse(value).success)
+        return null;
+    switch (type.kind) {
+        case 'string':
+            return typeof value === 'string'
+                ? `${field} is longer than ${FIELD_LIMITS.stringChars.toLocaleString('en-GB')} characters.`
+                : `${field} must be text.`;
+        case 'text':
+            return typeof value === 'string'
+                ? `${field} is longer than ${FIELD_LIMITS.textChars.toLocaleString('en-GB')} characters.`
+                : `${field} must be text.`;
+        case 'enum':
+        case 'token':
+            return `${field} must be one of ${quoted(type.values ?? [])}.`;
+        case 'member':
+            return `${field} must be a workspace member's user id.`;
+        case 'project':
+            return `${field} must be a project id.`;
+        case 'date':
+            return `${field} must be a date, written YYYY-MM-DD.`;
+        case 'number':
+            return `${field} must be a number.`;
+        case 'boolean':
+            return `${field} must be true or false.`;
+        case 'string[]':
+            return Array.isArray(value) && value.length > FIELD_LIMITS.listEntries
+                ? `${field} may hold at most ${FIELD_LIMITS.listEntries} entries.`
+                : `${field} must be a list of short texts, each at most ${FIELD_LIMITS.stringChars.toLocaleString('en-GB')} characters.`;
+    }
+}
+/** A type in a few words, for a tool's description: every allowed value named. */
+export function describeType(type) {
+    switch (type.kind) {
+        case 'string':
+            return 'short text';
+        case 'text':
+            return 'long text';
+        case 'enum':
+            return `one of ${quoted(type.values ?? [])}${labelWords(type)}`;
+        case 'token':
+            return `a colour, one of ${quoted(type.values ?? [])}`;
+        case 'member':
+            return "a workspace member's user id";
+        case 'project':
+            return 'a project id';
+        case 'date':
+            return 'a date, YYYY-MM-DD';
+        case 'number':
+            return 'a number';
+        case 'boolean':
+            return 'true or false';
+        case 'string[]':
+            return 'a list of short texts';
+    }
+}
+/** ", read as \"todo\" is To do, \"done\" is Done", for a choice with labels. */
+const labelWords = (type) => {
+    const pairs = Object.entries(type.labels ?? {});
+    return pairs.length ? ` (${pairs.map(([value, label]) => `"${value}" reads as ${label}`).join(', ')})` : '';
+};
+export const quoted = (values) => values.map(value => `"${value}"`).join(', ');

package/src/grants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The host grants Brydio has a meaning for, and its refusal of any other
+ * (A5-F04-S03, A8-F04-S03).
+ *
+ * Copies of `HOST_CAPABILITIES` and `isHostCapability` in Brydio's
+ * `apps/api/src/apps/manifest/grants.ts`, and the `grant_unknown` sentence in
+ * `apps/api/src/apps/publishing/app-publish.service.ts`.
+ */
+/** The host grants with a name of their own. A connection's is `connection:<name>`. */
+export declare const HOST_CAPABILITIES: readonly ["navigate", "message", "members", "projects"];
+/** The older name for `HOST_CAPABILITIES`, kept for what already imports it. */
+export declare const KNOWN_HOST_GRANTS: readonly string[];
+/** True for a host grant Brydio knows how to honour: a named capability, or one connection. */
+export declare const isHostCapability: (value: string) => boolean;
+/** The server's refusal of the first host grant it does not know, or null. */
+export declare function unknownHostGrant(manifest: unknown): {
+    code: 'grant_unknown';
+    message: string;
+    path: 'grants.host';
+} | null;

package/src/grants.js

@@ -0,0 +1,30 @@
+/**
+ * The host grants Brydio has a meaning for, and its refusal of any other
+ * (A5-F04-S03, A8-F04-S03).
+ *
+ * Copies of `HOST_CAPABILITIES` and `isHostCapability` in Brydio's
+ * `apps/api/src/apps/manifest/grants.ts`, and the `grant_unknown` sentence in
+ * `apps/api/src/apps/publishing/app-publish.service.ts`.
+ */
+import { BUNDLE_MANIFEST } from "./bundle.js";
+/** The host grants with a name of their own. A connection's is `connection:<name>`. */
+export const HOST_CAPABILITIES = ['navigate', 'message', 'members', 'projects'];
+/** The older name for `HOST_CAPABILITIES`, kept for what already imports it. */
+export const KNOWN_HOST_GRANTS = HOST_CAPABILITIES;
+const CONNECTION = /^connection:[a-z0-9][a-z0-9_-]{0,59}$/;
+/** True for a host grant Brydio knows how to honour: a named capability, or one connection. */
+export const isHostCapability = (value) => HOST_CAPABILITIES.includes(value) || CONNECTION.test(value);
+/** The server's refusal of the first host grant it does not know, or null. */
+export function unknownHostGrant(manifest) {
+    const grants = manifest?.grants;
+    const host = grants?.host;
+    const unknown = (Array.isArray(host) ? host : []).find(grant => typeof grant !== 'string' || !isHostCapability(grant));
+    if (unknown === undefined)
+        return null;
+    return {
+        code: 'grant_unknown',
+        message: `${BUNDLE_MANIFEST} asks for "${String(unknown)}", which Brydio does not grant. ` +
+            `An app may ask for ${HOST_CAPABILITIES.join(', ')} or connection:<name>.`,
+        path: 'grants.host',
+    };
+}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@brydio/manifest`: the shape of `.brydio/app.json`, its collections' field
+ * types, the tools Brydio generates from them, and the bundle rules. Each is
+ * a copy of the server's own, so an app that passes here passes there.
+ */
+export { APP_NAME_FORMAT, MANIFEST_LIMITS, SEMVER_FORMAT, baseManifestSchema } from './base.js';
+export { BUNDLE_MANIFEST, BUNDLE_MAX_BYTES, BUNDLE_PATH_MAX_CHARS, bundleBytes, bundleHash, bundleProblem, codeOf, isBundlePath, isScriptPath, sizeOf, type BundleFiles, type BundleProblem, type BundleProblemCode, } from './bundle.js';
+export { COLOUR_TOKENS, FIELD_LIMITS, RESERVED_FIELDS, describeType, isSearchable, isSortable, isStructured, parseFieldType, structuredFields, valueProblem, valueSchema, FieldTypeInvalid, type DocumentOf, type FieldKind, type FieldType, type FieldValue, type FieldsOf, } from './field-types.js';
+export { appManifestSchema, collectionOf, collectionsOf, dataProblems, labelOf, manifestExtensionsSchema, storedExtensionsSchema, type AppManifestWithData, type CollectionSpec, type DataProblem, type DataProblemCode, type ManifestExtensions, } from './schema.js';
+export { DOCUMENT_LIMITS } from './document-limits.js';
+export { HOST_CAPABILITIES, KNOWN_HOST_GRANTS, isHostCapability, unknownHostGrant } from './grants.js';
+export { diffSchemas, migrationProblems, migrationSchema, migrationStepSchema, migrationsSchema, publishedMigrationProblems, schemaOf, type Migration, type MigrationCode, type MigrationProblem, type MigrationStep, type SchemaChange, } from './migrations.js';
+export { SECRET_MESSAGE, findSecrets, secretsInJson, type SecretFound } from './secrets.js';
+export { compareVersions, sdkRefusal, type SdkSupport } from './sdk.js';
+export { TOOL_WRITES, generatedToolsOf, toolNames, type GeneratedTool, type ToolVerb } from './tools.js';
+export { validateManifest, validateManifestText, type ManifestProblem, type ManifestProblemCode, type ManifestValidation, } from './validate.js';
+export { defineManifest, type ManifestShape, type ScreenNameOf, type WithDeclaredScreens } from './define.js';

package/src/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@brydio/manifest`: the shape of `.brydio/app.json`, its collections' field
+ * types, the tools Brydio generates from them, and the bundle rules. Each is
+ * a copy of the server's own, so an app that passes here passes there.
+ */
+export { APP_NAME_FORMAT, MANIFEST_LIMITS, SEMVER_FORMAT, baseManifestSchema } from "./base.js";
+export { BUNDLE_MANIFEST, BUNDLE_MAX_BYTES, BUNDLE_PATH_MAX_CHARS, bundleBytes, bundleHash, bundleProblem, codeOf, isBundlePath, isScriptPath, sizeOf, } from "./bundle.js";
+export { COLOUR_TOKENS, FIELD_LIMITS, RESERVED_FIELDS, describeType, isSearchable, isSortable, isStructured, parseFieldType, structuredFields, valueProblem, valueSchema, FieldTypeInvalid, } from "./field-types.js";
+export { appManifestSchema, collectionOf, collectionsOf, dataProblems, labelOf, manifestExtensionsSchema, storedExtensionsSchema, } from "./schema.js";
+export { DOCUMENT_LIMITS } from "./document-limits.js";
+export { HOST_CAPABILITIES, KNOWN_HOST_GRANTS, isHostCapability, unknownHostGrant } from "./grants.js";
+export { diffSchemas, migrationProblems, migrationSchema, migrationStepSchema, migrationsSchema, publishedMigrationProblems, schemaOf, } from "./migrations.js";
+export { SECRET_MESSAGE, findSecrets, secretsInJson } from "./secrets.js";
+export { compareVersions, sdkRefusal } from "./sdk.js";
+export { TOOL_WRITES, generatedToolsOf, toolNames } from "./tools.js";
+export { validateManifest, validateManifestText, } from "./validate.js";
+export { defineManifest } from "./define.js";

package/src/migrations.d.ts

@@ -0,0 +1,142 @@
+import { z } from 'zod';
+import { type FieldType } from './field-types.js';
+export declare const migrationStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    op: z.ZodLiteral<"add">;
+    collection: z.ZodString;
+    field: z.ZodString;
+    default: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"rename">;
+    collection: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"drop">;
+    collection: z.ZodString;
+    field: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"dropCollection">;
+    collection: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"replace">;
+    collection: z.ZodString;
+    field: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>], "op">;
+export declare const migrationSchema: z.ZodObject<{
+    version: z.ZodString;
+    steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        op: z.ZodLiteral<"add">;
+        collection: z.ZodString;
+        field: z.ZodString;
+        default: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"rename">;
+        collection: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"drop">;
+        collection: z.ZodString;
+        field: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"dropCollection">;
+        collection: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"replace">;
+        collection: z.ZodString;
+        field: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>], "op">>;
+}, z.core.$strip>;
+export declare const migrationsSchema: z.ZodArray<z.ZodObject<{
+    version: z.ZodString;
+    steps: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        op: z.ZodLiteral<"add">;
+        collection: z.ZodString;
+        field: z.ZodString;
+        default: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"rename">;
+        collection: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"drop">;
+        collection: z.ZodString;
+        field: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"dropCollection">;
+        collection: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        op: z.ZodLiteral<"replace">;
+        collection: z.ZodString;
+        field: z.ZodString;
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>], "op">>;
+}, z.core.$strip>>;
+export type MigrationStep = z.infer<typeof migrationStepSchema>;
+export type Migration = z.infer<typeof migrationSchema>;
+type Schema = Map<string, Map<string, FieldType>>;
+/** A version's collections and their field types, read tolerantly: a stored manifest was checked when published. */
+export declare function schemaOf(manifest: unknown): Schema;
+export type SchemaChange = {
+    kind: 'collection_added' | 'collection_removed';
+    collection: string;
+} | {
+    kind: 'field_added' | 'field_removed';
+    collection: string;
+    field: string;
+    type: FieldType;
+} | {
+    kind: 'field_type_changed';
+    collection: string;
+    field: string;
+    from: FieldType;
+    to: FieldType;
+} | {
+    kind: 'field_now_required' | 'field_now_optional';
+    collection: string;
+    field: string;
+} | {
+    kind: 'values_added' | 'values_removed';
+    collection: string;
+    field: string;
+    values: string[];
+};
+/**
+ * Every way the records one schema describes differ from another's, collection
+ * by collection and field by field, in a fixed order.
+ *
+ * About storage only: labels, search lists and everything outside `data` are
+ * Hodler's `diffManifests` to show, and none of them moves a record.
+ */
+export declare function diffSchemas(from: unknown, to: unknown): SchemaChange[];
+export type MigrationCode = 'migration_step_invalid' | 'migration_step_pointless' | 'migration_default_missing' | 'migration_default_invalid' | 'migration_unexplained' | 'migration_type_changed' | 'migration_value_removed';
+export interface MigrationProblem {
+    code: MigrationCode;
+    collection: string;
+    field?: string;
+    message: string;
+}
+/**
+ * Whether `steps` take the records `from` describes to the records `to`
+ * describes: every difference explained by a step, every step making one.
+ *
+ * Worked out by running the steps over a copy of the old schema and
+ * comparing what comes out with the new one, so a rename followed by an add
+ * under the old name is judged as the two moves it is, not as "nothing
+ * changed". An empty list means the steps are right.
+ */
+export declare function migrationProblems(from: unknown, to: unknown, steps: readonly MigrationStep[]): MigrationProblem[];
+/**
+ * What is wrong with a version's migration against the version published
+ * before it (A3-F07-S01): the check the publish route runs, so a version
+ * that could never be pinned never reaches a workspace. `previous` is null
+ * for an app's first version, which has nothing to migrate.
+ */
+export declare function publishedMigrationProblems(previous: unknown, next: unknown): MigrationProblem[];
+export {};