@openinc/parse-server-opendash 4.1.1 → 4.1.2

package/dist/scripts/migration/lib/latest.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reading v1's side tables without the N+1.
+ *
+ * v1 keeps each ticket attribute in its own class as append-only rows, and
+ * "current" means the newest row for that ticket. The v1 cloud function
+ * (`functions/openinc-openservice-ticket-data.ts`) reads that with one point query
+ * per ticket per attribute — roughly ten round-trips per ticket, so ~100k for a
+ * 10k-ticket tenant.
+ *
+ * These helpers load a whole side table in pages once, then group in memory.
+ * ~10k rows of a handful of fields is nothing to hold, and it turns the read cost
+ * from per-ticket into per-table.
+ */
+/** All rows of a side table, grouped by the ticket they belong to. */
+export declare function groupByTicket<T extends Parse.Object>(build: () => Parse.Query<T>, batchSize: number, ticketField?: string): Promise<Map<string, T[]>>;
+/**
+ * When a side-table row took effect.
+ *
+ * v1 resolves "current" with `descending("updatedAt")`, so `updatedAt` — not
+ * `createdAt` — is the clock that decides which row wins. A row edited in place
+ * beats an older-created row under v1's rules.
+ *
+ * **The fold (pass 08) and the replay (pass 12) must use this same function.** If
+ * the fold picked by `updatedAt` while the replay ordered by `createdAt`, the two
+ * would disagree whenever any row was edited in place: the replay's final snapshot
+ * would end on a different row than the ticket carries, breaking the
+ * replay-reproduces-the-ticket invariant for a reason that is not a real bug.
+ */
+export declare function effectiveAt(row: Parse.Object): Date | undefined;
+/** The newest row per ticket, by {@link effectiveAt}. */
+export declare function latestOf<T extends Parse.Object>(rows: T[] | undefined): T | undefined;
+/** Chronological order by {@link effectiveAt} — the sequence the replay walks. */
+export declare function chronological<T extends Parse.Object>(rows: T[]): T[];
+/**
+ * Read a Parse Relation completely.
+ *
+ * Relations cannot be included in a query, so this is unavoidably one round trip
+ * per owner (plus one more to confirm the end). Only used where the relation is
+ * small and per-owner — assignees, an item's sources, a form config's roles.
+ *
+ * Pages rather than taking a single `limit(1000)`: a fixed cap would drop the
+ * 1001st assignee or source with nothing in the log to say so, which is precisely
+ * the silent-loss failure mode this migration is built to avoid.
+ */
+export declare function relationObjects(owner: Parse.Object, field: string, batchSize?: number): Promise<Parse.Object[]>;
+/** The objectIds of a relation, read completely. */
+export declare function relationIds(owner: Parse.Object, field: string, batchSize?: number): Promise<string[]>;

package/dist/scripts/migration/lib/latest.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupByTicket = groupByTicket;
+exports.effectiveAt = effectiveAt;
+exports.latestOf = latestOf;
+exports.chronological = chronological;
+exports.relationObjects = relationObjects;
+exports.relationIds = relationIds;
+const env_js_1 = require("./env.js");
+const pass_js_1 = require("./pass.js");
+/**
+ * Reading v1's side tables without the N+1.
+ *
+ * v1 keeps each ticket attribute in its own class as append-only rows, and
+ * "current" means the newest row for that ticket. The v1 cloud function
+ * (`functions/openinc-openservice-ticket-data.ts`) reads that with one point query
+ * per ticket per attribute — roughly ten round-trips per ticket, so ~100k for a
+ * 10k-ticket tenant.
+ *
+ * These helpers load a whole side table in pages once, then group in memory.
+ * ~10k rows of a handful of fields is nothing to hold, and it turns the read cost
+ * from per-ticket into per-table.
+ */
+/** All rows of a side table, grouped by the ticket they belong to. */
+async function groupByTicket(build, batchSize, ticketField = "ticket") {
+    const byTicket = new Map();
+    let skip = 0;
+    for (;;) {
+        const page = await build()
+            .limit(batchSize)
+            .skip(skip)
+            // Ascending, so each ticket's bucket comes out in chronological order —
+            // which is exactly what the history replay (pass 12) needs, and the last
+            // element is what the fold (pass 08) needs.
+            .ascending("createdAt")
+            .find(env_js_1.MK);
+        if (page.length === 0)
+            break;
+        for (const row of page) {
+            const ticketId = (0, pass_js_1.refId)(row.get(ticketField));
+            if (!ticketId)
+                continue;
+            const bucket = byTicket.get(ticketId);
+            if (bucket)
+                bucket.push(row);
+            else
+                byTicket.set(ticketId, [row]);
+        }
+        // Stop only on an empty page — a short page does not mean the end. See the
+        // paging note in lib/pass.ts.
+        skip += page.length;
+    }
+    return byTicket;
+}
+/**
+ * When a side-table row took effect.
+ *
+ * v1 resolves "current" with `descending("updatedAt")`, so `updatedAt` — not
+ * `createdAt` — is the clock that decides which row wins. A row edited in place
+ * beats an older-created row under v1's rules.
+ *
+ * **The fold (pass 08) and the replay (pass 12) must use this same function.** If
+ * the fold picked by `updatedAt` while the replay ordered by `createdAt`, the two
+ * would disagree whenever any row was edited in place: the replay's final snapshot
+ * would end on a different row than the ticket carries, breaking the
+ * replay-reproduces-the-ticket invariant for a reason that is not a real bug.
+ */
+function effectiveAt(row) {
+    return row.updatedAt ?? row.createdAt;
+}
+/** The newest row per ticket, by {@link effectiveAt}. */
+function latestOf(rows) {
+    if (!rows || rows.length === 0)
+        return undefined;
+    return rows.reduce((best, row) => {
+        const a = effectiveAt(row)?.getTime() ?? 0;
+        const b = effectiveAt(best)?.getTime() ?? 0;
+        return a > b ? row : best;
+    });
+}
+/** Chronological order by {@link effectiveAt} — the sequence the replay walks. */
+function chronological(rows) {
+    return [...rows].sort((a, b) => (effectiveAt(a)?.getTime() ?? 0) - (effectiveAt(b)?.getTime() ?? 0));
+}
+/**
+ * Read a Parse Relation completely.
+ *
+ * Relations cannot be included in a query, so this is unavoidably one round trip
+ * per owner (plus one more to confirm the end). Only used where the relation is
+ * small and per-owner — assignees, an item's sources, a form config's roles.
+ *
+ * Pages rather than taking a single `limit(1000)`: a fixed cap would drop the
+ * 1001st assignee or source with nothing in the log to say so, which is precisely
+ * the silent-loss failure mode this migration is built to avoid.
+ */
+async function relationObjects(owner, field, batchSize = 500) {
+    const relation = owner.relation(field);
+    if (!relation)
+        return [];
+    const out = [];
+    let skip = 0;
+    for (;;) {
+        const page = await relation.query().limit(batchSize).skip(skip).find(env_js_1.MK);
+        if (page.length === 0)
+            break;
+        out.push(...page);
+        skip += page.length;
+    }
+    return out;
+}
+/** The objectIds of a relation, read completely. */
+async function relationIds(owner, field, batchSize = 500) {
+    const rows = await relationObjects(owner, field, batchSize);
+    return rows.map((r) => r.id).filter((id) => !!id);
+}

package/dist/scripts/migration/lib/map.d.ts

@@ -0,0 +1,53 @@
+import { type MigrationConfig } from "./env.js";
+/** Exported so the orchestrator can name it in a connection error. */
+export declare const MIGRATION_MAP_CLASS = "OD3_Service_MigrationMap";
+/**
+ * The v1 → v2 id map (`OD3_Service_MigrationMap`).
+ *
+ * New Parse classes mean new objectIds, and plenty of things reference a ticket by
+ * id *string* rather than by pointer — the chat context, meta entries, asset
+ * contexts. Those can only be rewritten if we remember what became what.
+ *
+ * Keeping the map in its own class rather than as a `legacyId` column on every
+ * model keeps the domain models clean, makes each pass idempotent (look up by
+ * source, update instead of insert) and leaves an audit trail for spot-checks.
+ *
+ * Tickets are the exception: `Ticket.origin` is already a free-form traceability
+ * marker on the v2 model, so they carry `"legacy:<oldId>"` there as well. The map
+ * still records them, so one lookup path works for every class.
+ *
+ * Addressed by raw className because the generated typed subclass only appears
+ * after `pnpm schema-ts` runs against a server that has the class.
+ */
+export declare class MigrationMap {
+    private readonly config;
+    /** `sourceClass|sourceId` → target objectId, loaded up front. */
+    private readonly cache;
+    private loaded;
+    constructor(config: MigrationConfig);
+    private static key;
+    /**
+     * Load the whole map into memory once.
+     *
+     * Safe at this scale: ~10k rows per class per tenant means the map tops out in
+     * the low hundreds of thousands of short strings, and every pass would otherwise
+     * do a point query per row.
+     */
+    load(): Promise<void>;
+    /** The v2 objectId a v1 object already became, if any. */
+    get(sourceClass: string, sourceId: string): string | undefined;
+    /** Convenience: resolve to a pointer of the target class, or undefined. */
+    pointer(sourceClass: string, sourceId: string | undefined, targetClass: string): Parse.Pointer | undefined;
+    /**
+     * Placeholder target id used during a dry run.
+     *
+     * A dry run writes nothing, so no real target id exists — but later passes
+     * resolve their references *through this map*, and without an entry every one of
+     * them would report "no migrated counterpart" for every single row. That would
+     * bury the genuine findings the dry run exists to surface. A recognisable
+     * placeholder keeps the pipeline resolvable and the report readable.
+     */
+    static dryId(sourceId: string): string;
+    /** Record a mapping. No-op in dry-run mode beyond the in-memory cache. */
+    record(sourceClass: string, sourceId: string, targetClass: string, targetId: string): Promise<void>;
+}

package/dist/scripts/migration/lib/map.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MigrationMap = exports.MIGRATION_MAP_CLASS = void 0;
+const node_1 = __importDefault(require("parse/node"));
+const env_js_1 = require("./env.js");
+/** Exported so the orchestrator can name it in a connection error. */
+exports.MIGRATION_MAP_CLASS = "OD3_Service_MigrationMap";
+const CLASS_NAME = exports.MIGRATION_MAP_CLASS;
+/**
+ * The v1 → v2 id map (`OD3_Service_MigrationMap`).
+ *
+ * New Parse classes mean new objectIds, and plenty of things reference a ticket by
+ * id *string* rather than by pointer — the chat context, meta entries, asset
+ * contexts. Those can only be rewritten if we remember what became what.
+ *
+ * Keeping the map in its own class rather than as a `legacyId` column on every
+ * model keeps the domain models clean, makes each pass idempotent (look up by
+ * source, update instead of insert) and leaves an audit trail for spot-checks.
+ *
+ * Tickets are the exception: `Ticket.origin` is already a free-form traceability
+ * marker on the v2 model, so they carry `"legacy:<oldId>"` there as well. The map
+ * still records them, so one lookup path works for every class.
+ *
+ * Addressed by raw className because the generated typed subclass only appears
+ * after `pnpm schema-ts` runs against a server that has the class.
+ */
+class MigrationMap {
+    config;
+    /** `sourceClass|sourceId` → target objectId, loaded up front. */
+    cache = new Map();
+    loaded = false;
+    constructor(config) {
+        this.config = config;
+    }
+    static key(sourceClass, sourceId) {
+        return `${sourceClass}|${sourceId}`;
+    }
+    /**
+     * Load the whole map into memory once.
+     *
+     * Safe at this scale: ~10k rows per class per tenant means the map tops out in
+     * the low hundreds of thousands of short strings, and every pass would otherwise
+     * do a point query per row.
+     */
+    async load() {
+        if (this.loaded)
+            return;
+        let skip = 0;
+        for (;;) {
+            const page = await new node_1.default.Query(CLASS_NAME)
+                .limit(1000)
+                .skip(skip)
+                .ascending("createdAt")
+                .find(env_js_1.MK);
+            if (page.length === 0)
+                break;
+            for (const row of page) {
+                this.cache.set(MigrationMap.key(row.get("sourceClass"), row.get("sourceId")), row.get("targetId"));
+            }
+            // Stop only on an empty page — a short page does not mean the end. See the
+            // paging note in lib/pass.ts.
+            skip += page.length;
+        }
+        this.loaded = true;
+        console.log(`   map: ${this.cache.size} existing mapping(s) loaded`);
+    }
+    /** The v2 objectId a v1 object already became, if any. */
+    get(sourceClass, sourceId) {
+        return this.cache.get(MigrationMap.key(sourceClass, sourceId));
+    }
+    /** Convenience: resolve to a pointer of the target class, or undefined. */
+    pointer(sourceClass, sourceId, targetClass) {
+        if (!sourceId)
+            return undefined;
+        const targetId = this.get(sourceClass, sourceId);
+        if (!targetId)
+            return undefined;
+        return {
+            __type: "Pointer",
+            className: targetClass,
+            objectId: targetId,
+        };
+    }
+    /**
+     * Placeholder target id used during a dry run.
+     *
+     * A dry run writes nothing, so no real target id exists — but later passes
+     * resolve their references *through this map*, and without an entry every one of
+     * them would report "no migrated counterpart" for every single row. That would
+     * bury the genuine findings the dry run exists to surface. A recognisable
+     * placeholder keeps the pipeline resolvable and the report readable.
+     */
+    static dryId(sourceId) {
+        return `dry-${sourceId}`;
+    }
+    /** Record a mapping. No-op in dry-run mode beyond the in-memory cache. */
+    async record(sourceClass, sourceId, targetClass, targetId) {
+        this.cache.set(MigrationMap.key(sourceClass, sourceId), targetId);
+        if (this.config.dryRun)
+            return;
+        const row = new node_1.default.Object(CLASS_NAME);
+        row.set("run", this.config.runId);
+        row.set("sourceClass", sourceClass);
+        row.set("sourceId", sourceId);
+        row.set("targetClass", targetClass);
+        row.set("targetId", targetId);
+        await row.save(null, { ...env_js_1.MK, context: { skipChangelog: true } });
+    }
+}
+exports.MigrationMap = MigrationMap;

package/dist/scripts/migration/lib/material.d.ts

@@ -0,0 +1,47 @@
+import type { TicketMaterial } from "../../../types/custom/TicketMaterial.js";
+import type { MigrationMap } from "./map.js";
+/**
+ * Reading v1's `OD3_Maintenance_Ticket_Material.itemList`.
+ *
+ * v1 stored consumed material as an append-only side table like every other
+ * ticket attribute, except that each row carries the **whole list** as a JSON
+ * blob rather than a single value. So "current" is the newest row's `itemList`,
+ * and the history is the sequence of whole-list snapshots — which is exactly the
+ * shape `Ticket.material` and the changelog both want.
+ *
+ * Shared by pass 08 (the fold) and pass 12 (the replay) so the two cannot drift:
+ * if they converted differently, the replay's final snapshot would not equal the
+ * migrated ticket and `verify.ts` would fail for a reason that is not a bug.
+ */
+/** One entry of a v1 `itemList`. */
+export interface LegacyMaterial {
+    /** `Maintenance_Item` objectId, or a synthetic marker for an ad-hoc line. */
+    id?: string | number;
+    name?: string;
+    quantity?: number;
+    unit?: string;
+}
+export interface MaterialConversion {
+    entries: TicketMaterial[];
+    /**
+     * v1 ids that named something with no migrated `Article`. Not an error — v1
+     * let users type material that was never in the item catalogue, and those
+     * carry markers like `"manual-1"`. They become ad-hoc lines; the caller
+     * reports the count so a real broken reference is still visible.
+     */
+    unresolved: string[];
+}
+/**
+ * Convert a v1 `itemList` into `Ticket.material`.
+ *
+ * The entry is deliberately a **snapshot**: `name` and `unit` are copied across
+ * rather than looked up from the article at read time, because changelog entries
+ * render the stored value directly and a bare id would show as an opaque string
+ * in the timeline. See `types/custom/TicketMaterial.ts`.
+ *
+ * An entry with no usable name is dropped — v1 allowed a blank row, and carrying
+ * it over would put an empty line in the ticket.
+ */
+export declare function toMaterial(itemList: unknown, map: MigrationMap): MaterialConversion;
+/** The class the resolved ids point at — kept here so call sites stay honest. */
+export declare const MATERIAL_TARGET_CLASS: string;

package/dist/scripts/migration/lib/material.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MATERIAL_TARGET_CLASS = void 0;
+exports.toMaterial = toMaterial;
+const index_js_1 = require("../../../types/index.js");
+/**
+ * Convert a v1 `itemList` into `Ticket.material`.
+ *
+ * The entry is deliberately a **snapshot**: `name` and `unit` are copied across
+ * rather than looked up from the article at read time, because changelog entries
+ * render the stored value directly and a bare id would show as an opaque string
+ * in the timeline. See `types/custom/TicketMaterial.ts`.
+ *
+ * An entry with no usable name is dropped — v1 allowed a blank row, and carrying
+ * it over would put an empty line in the ticket.
+ */
+function toMaterial(itemList, map) {
+    if (!Array.isArray(itemList))
+        return { entries: [], unresolved: [] };
+    const entries = [];
+    const unresolved = [];
+    for (const raw of itemList) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const name = typeof raw.name === "string" ? raw.name.trim() : "";
+        if (!name)
+            continue;
+        const legacyId = raw.id === undefined || raw.id === null ? "" : String(raw.id);
+        // Pass 05 maps Maintenance_Item onto OD3_BDE_Article, so a v1 item id
+        // resolves to an article id through the same map as everything else.
+        const articleId = legacyId
+            ? map.get(index_js_1.Maintenance_Item.className, legacyId)
+            : undefined;
+        if (legacyId && !articleId)
+            unresolved.push(legacyId);
+        const entry = {
+            name,
+            // v1's column is a free-form blob, so a non-numeric quantity is possible.
+            quantity: typeof raw.quantity === "number" ? raw.quantity : 0,
+        };
+        if (articleId)
+            entry.article = articleId;
+        const unit = typeof raw.unit === "string" ? raw.unit.trim() : "";
+        if (unit)
+            entry.unit = unit;
+        entries.push(entry);
+    }
+    return { entries, unresolved };
+}
+/** The class the resolved ids point at — kept here so call sites stay honest. */
+exports.MATERIAL_TARGET_CLASS = index_js_1.BDE_Article.className;

package/dist/scripts/migration/lib/message.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Reading a v1 `OD3_Maintenance_Message`.
+ *
+ * Two traps, both of which produce visibly wrong output if ignored — and both are
+ * shared by the comment pass (10) and the checklist part of the ticket pass (08),
+ * which is why this lives here rather than in either of them.
+ *
+ * **1. `title` is often an i18n key, not text.** When the user left the subject
+ * blank, `ArticleCollapsable` stores the literal string
+ * `"maintenance:article.create.default_subject.todo"` (or `…userinput`), and the v1
+ * UI renders it through `t(...)`. Copying it verbatim would put that key on screen
+ * as a checklist label or a comment heading.
+ *
+ * **2. completion lives in `data.todoCompleted`**, not `data.done` — see
+ * `features/tickets/messages/hooks/useTodoMessage.ts`.
+ */
+/** v1's `MessageData` blob, as far as the migration cares. */
+export interface LegacyMessageData {
+    type?: "userinput" | "system" | "todo" | "media";
+    todoCompleted?: boolean;
+    /** Set on machine-generated messages: the side-table row that caused it. */
+    origin?: {
+        id?: string | number;
+        classname?: string;
+    };
+}
+export declare function messageData(message: Parse.Object): LegacyMessageData;
+export declare function isTodo(message: Parse.Object): boolean;
+/**
+ * A machine-generated change-log message, not something a person wrote.
+ *
+ * v1 recorded its own edit history *as messages*: every side-table write triggered
+ * an afterSave that wrote a `Maintenance_Message` with `data.type: "system"`,
+ * `data.origin` naming the row that caused it, and **i18n keys in both `title` and
+ * `content`** — e.g. `maintenance:ticket.message.priority.changed.content`, with
+ * the actual values in `data.translation`.
+ *
+ * These are deliberately **not** migrated to chat. v2 expresses that same history
+ * as `OD3_Changelog` entries, which pass 12 reconstructs from the side tables
+ * directly — with structured before/after values, the real author and the original
+ * timestamp. Carrying the messages across as well would duplicate the timeline in a
+ * strictly worse form and fill the ticket's comment thread with untranslated keys.
+ *
+ * Found by running against real data: a hand-written seed had readable content, so
+ * this only showed up once v1's own hooks had generated the messages.
+ */
+export declare function isSystemGenerated(message: Parse.Object): boolean;
+export declare function isTodoDone(message: Parse.Object): boolean;
+/**
+ * An i18n key rather than human text.
+ *
+ * v1's keys are all `namespace:dotted.path`, and a real subject line would not
+ * normally contain a colon followed immediately by a lowercase dotted path — so
+ * this is narrow enough not to eat legitimate titles like `"Fehler: Lager heiß"`
+ * (space after the colon).
+ */
+export declare function looksLikeI18nKey(value: unknown): boolean;
+/**
+ * The human-readable title of a message, or undefined when v1 only had a
+ * placeholder key there.
+ */
+export declare function realTitle(message: Parse.Object): string | undefined;
+/**
+ * Label for a checklist item derived from a todo message.
+ *
+ * Prefers a real subject, falls back to the body (which is what the user actually
+ * typed when they left the subject blank), and returns undefined when there is
+ * nothing usable — the caller drops those rather than creating a blank item.
+ */
+export declare function checklistLabel(message: Parse.Object): string | undefined;
+/**
+ * Body text for a chat message derived from a v1 comment.
+ *
+ * A real subject becomes a bold first line; a placeholder key is dropped rather
+ * than rendered. Returns undefined when there is no text at all — `Chat_Message.text`
+ * is required, so the caller must skip those.
+ */
+export declare function chatText(message: Parse.Object): string | undefined;

package/dist/scripts/migration/lib/message.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Reading a v1 `OD3_Maintenance_Message`.
+ *
+ * Two traps, both of which produce visibly wrong output if ignored — and both are
+ * shared by the comment pass (10) and the checklist part of the ticket pass (08),
+ * which is why this lives here rather than in either of them.
+ *
+ * **1. `title` is often an i18n key, not text.** When the user left the subject
+ * blank, `ArticleCollapsable` stores the literal string
+ * `"maintenance:article.create.default_subject.todo"` (or `…userinput`), and the v1
+ * UI renders it through `t(...)`. Copying it verbatim would put that key on screen
+ * as a checklist label or a comment heading.
+ *
+ * **2. completion lives in `data.todoCompleted`**, not `data.done` — see
+ * `features/tickets/messages/hooks/useTodoMessage.ts`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.messageData = messageData;
+exports.isTodo = isTodo;
+exports.isSystemGenerated = isSystemGenerated;
+exports.isTodoDone = isTodoDone;
+exports.looksLikeI18nKey = looksLikeI18nKey;
+exports.realTitle = realTitle;
+exports.checklistLabel = checklistLabel;
+exports.chatText = chatText;
+function messageData(message) {
+    return message.get("data") ?? {};
+}
+function isTodo(message) {
+    return messageData(message).type === "todo";
+}
+/**
+ * A machine-generated change-log message, not something a person wrote.
+ *
+ * v1 recorded its own edit history *as messages*: every side-table write triggered
+ * an afterSave that wrote a `Maintenance_Message` with `data.type: "system"`,
+ * `data.origin` naming the row that caused it, and **i18n keys in both `title` and
+ * `content`** — e.g. `maintenance:ticket.message.priority.changed.content`, with
+ * the actual values in `data.translation`.
+ *
+ * These are deliberately **not** migrated to chat. v2 expresses that same history
+ * as `OD3_Changelog` entries, which pass 12 reconstructs from the side tables
+ * directly — with structured before/after values, the real author and the original
+ * timestamp. Carrying the messages across as well would duplicate the timeline in a
+ * strictly worse form and fill the ticket's comment thread with untranslated keys.
+ *
+ * Found by running against real data: a hand-written seed had readable content, so
+ * this only showed up once v1's own hooks had generated the messages.
+ */
+function isSystemGenerated(message) {
+    return messageData(message).type === "system";
+}
+function isTodoDone(message) {
+    return messageData(message).todoCompleted === true;
+}
+/**
+ * An i18n key rather than human text.
+ *
+ * v1's keys are all `namespace:dotted.path`, and a real subject line would not
+ * normally contain a colon followed immediately by a lowercase dotted path — so
+ * this is narrow enough not to eat legitimate titles like `"Fehler: Lager heiß"`
+ * (space after the colon).
+ */
+function looksLikeI18nKey(value) {
+    return typeof value === "string" && /^[a-z0-9_-]+:[a-z0-9_.-]+$/i.test(value.trim());
+}
+/**
+ * The human-readable title of a message, or undefined when v1 only had a
+ * placeholder key there.
+ */
+function realTitle(message) {
+    const title = message.get("title");
+    if (typeof title !== "string")
+        return undefined;
+    const trimmed = title.trim();
+    if (!trimmed || looksLikeI18nKey(trimmed))
+        return undefined;
+    return trimmed;
+}
+/**
+ * Label for a checklist item derived from a todo message.
+ *
+ * Prefers a real subject, falls back to the body (which is what the user actually
+ * typed when they left the subject blank), and returns undefined when there is
+ * nothing usable — the caller drops those rather than creating a blank item.
+ */
+function checklistLabel(message) {
+    const title = realTitle(message);
+    if (title)
+        return title;
+    const content = message.get("content");
+    if (typeof content === "string" && content.trim())
+        return content.trim();
+    return undefined;
+}
+/**
+ * Body text for a chat message derived from a v1 comment.
+ *
+ * A real subject becomes a bold first line; a placeholder key is dropped rather
+ * than rendered. Returns undefined when there is no text at all — `Chat_Message.text`
+ * is required, so the caller must skip those.
+ */
+function chatText(message) {
+    const title = realTitle(message);
+    const content = message.get("content");
+    const body = typeof content === "string" ? content.trim() : "";
+    if (title && body)
+        return `**${title}**\n\n${body}`;
+    if (title)
+        return title;
+    if (body)
+        return body;
+    return undefined;
+}