@wirecat/cli-core 0.418.0 → 0.420.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ shape of this file.
 
 ## Unreleased
 
+## 0.420.0 — 25.10.2026
+
+### Changed — may break callers
+
+- **A meeting links to an event by its room, with exclusive ends, and two candidate events make no link** (`eventCandidates`, `linkEvent`; available from the cli-core release that carries store versions 30 to 33). Rooms are compared by `join_key`, never by the raw link with its passcode; an event a calendar entry holds is a candidate though it has no meeting yet; back-to-back events no longer both match. With two or more candidates `linkEvent` links none and creates none, and `MeetingStore.reviewMeetingLink` (optional; the store's own implements it) puts the meeting on the owner's review list. Before, it created a new automatic event: a second event for a meeting the calendar already held.
+- **`Event` gains optional `status`, `allDay` and `sourceDeletedAt`, and `origin` on `Event` and `EventSeries` may be `calendar`** (store version 33; available from the cli-core release that carries store versions 30 to 33). The stored event answer (`events list`, its MCP tool; a strict schema) gains `status`, `all_day` and `source_deleted_at`, and its `origin` takes `calendar`. A caller that switches over `origin` or validates the answer against the old schema must take the new value and fields.
+- **Notes import finds a file by its place in `files`, and a new file with one document's content is that document** (requirements 3.3, rule 2; available from the cli-core release that carries store versions 30 to 33). `saveFileNote`, `renameFileNote`, `deleteFileNotes` and `notes({ folderId })` work through each folder's `files` rows, so one document can live in several folders, each listing it under its own path. A new local file whose content hash equals one document's is a copy of it — a live one, else a deleted one no file holds any more, so a file moved between folders keeps its document in whichever order the folders sync; two such documents give a new document and one review entry; empty text never joins. A document stays live while any of its files is, and its own `account_id` and `external_id` follow the file it shows (the owner's pin, else the latest changed); Drive's documents keep theirs. A file renamed and edited in one sync is a new document, and the old one stays, deleted. `saveFileNote` and `renameFileNote` answer the note as the saving folder sees it: its `folderId` and `path` are that file's.
+- **Reviewed tag consolidation (store version 30)** (available from the cli-core release that carries store versions 30 to 33). Tag and automatic-claim
+  tables move behind a structural compatibility boundary with `minCompatible: 30`: `tags` becomes `canonical_tags`
+  and `auto_tag_claims` becomes `canonical_auto_tag_claims`, so an older SDK refuses the migrated file, including a
+  handle it already holds open. Later migrations must keep that minimum; the manifest refuses one that omits or
+  lowers it. Version 30 ships in one breaking release with versions 31 to 33. Consolidated tag groups refuse
+  document annotation transfer before copying; existing destinations need current schema maintenance for a
+  read-only preview.
+- **Drive documents move from their stand-in notes folder to the `google-drive` account (store version 31, `minCompatible` 31)** (available from the cli-core release that carries store versions 30 to 33). The store moves every Drive file of a `folder` named `google-drive:<principal>` to the `{ provider: "google-drive", account: <principal> }` account by `UPDATE`, so `document:<id>` references, chunks, tags, notes and links keep pointing where they did; the folder row goes, saved profiles `{ provider: "folder", account: "google-drive:<p>" }` become `{ provider: "google-drive", account: "<p>" }`, and group entries `notes:<folder id>` follow to the account's id. A CLI on an older cli-core refuses the store until it is upgraded. `notes.folders()` no longer lists Drive; `notes.documentsAccount(key, create)` and `notes.documentsAccounts()` find it, and `documentIngestion({ provider: "google-drive" })` writes into it (`collectionName` is now optional). `folder:<id>`, `--source drive:<profile>`, `--source google-drive:<principal>` and annotation transfers (`google-drive:<principal>`, from a store on either side of version 31) name the account. Ships in the same release as store version 30.
+- **A deleted document keeps its tags** (store version 32; available from the cli-core release that carries store versions 30 to 33). The version-1 trigger that dropped a document's tags when it was marked deleted is gone; its tags go when the row itself is purged. `knowledge.labelled` and the vocabulary's `usageCount` leave out a deleted document's taggings, and search already did. A document revived by a later sync, such as a file moved to another folder, comes back with its tags.
+- **Notes folders are accounts of provider `obsidian` (a vault) or `local` (a plain folder), no longer `folder`** (store version 32; available from the cli-core release that carries store versions 30 to 33). The migration renames each by its `settings.format`; A Drive stand-in folder (`google-drive:<principal>`) that version 31 left behind keeps `folder`. `FOLDER_PROVIDER` is replaced by `FOLDER_PROVIDERS` and `isFolderProvider`, both exported from the package root; `local` and `obsidian` are built-in providers of kind `notes`, and `--source obsidian` / `--source local` name the folders of that provider. Saved profile keys and annotation export files that say `folder` still resolve and import. **Version 32 raises `minCompatible` to 32**: a CLI on an older cli-core refuses the store and says to upgrade, instead of finding no folders and importing them a second time.
+
+### Added
+
+- **`knowledge.applyTagConsolidation`** (available from the cli-core release that carries store versions 30 to 33) applies an owner-reviewed complete preview
+  atomically, retains independent assignment/claim/alias/link provenance, follows inherited names in reads and
+  search, and returns a text-free idempotent receipt. Label removal respects requested origin scope across retained
+  members. [The consolidation guide](docs/dev/TAG-CONSOLIDATION.md) describes review, compatibility and the explicit
+  transfer limitation.
+- **Files: the source records of documents** (store version 32; available from the cli-core release that carries store versions 30 to 33). A new `files` table holds one row per item in one place: a file under a local folder or an Obsidian vault, a Drive file or folder. Each row has the item's `path` from its account's root, a `parent_id` to its folder's own row (local folders get rows made from the path), `path_folded` for prefix and substring search, and the `document_id` it is a copy of. A Drive item is keyed by its Drive file id and takes its link, type, size, edit time and version from the document's columns or, for rows saved before those columns, from its front matter; a Markdown file's front matter is `metadata.front_matter`. Every documents writer in cli-core keeps its row current (`saveFileNote`, `renameFileNote`, `deleteFileNotes`, `catalog.upsert`, `catalog.reconcile`, annotation transfers), and the first open after the upgrade writes the rows of every existing document in short batches, resuming where it stopped. `documents` stays the entity: no document is re-inserted and every `document:<id>` keeps working.
+- **The owner pins the file a document shows** (store version 32; same release). `documents.pinned_file_id` (nullable) holds the owner's choice; `store.files.pin(document, fileId)` takes one of the document's own files and `store.files.unpin(document)` clears it, so the document shows its most recently changed file again. `FilesStore` from `@wirecat/cli-core/store`.
+- **`EventStore`, the calendar's store** (`store.calendar`; types from `@wirecat/cli-core/meetings`; available from the cli-core release that carries store versions 30 to 33). `saveCalendars` (a calendar the owner owns syncs, others are listed), `calendars`, `setCalendarSynced`, `saveEntries` (one sync page in one transaction, matched by rules 1–5 of requirements 3.4: the same calendar and id; the same series slot, so a plain occurrence and its exception are one entry, in whichever order the series and its occurrences arrive; another calendar's copy by iCalUID; a Zoom meeting's automatic event by room and overlapping time, which the entry adopts as origin `calendar`; else a new event), `markUnseen` (after a full list; plain occurrences only inside the window fetched), `events(filter)` by time, account, calendar or person, `event(id)` with its entries, participants and revisions, `linkEntry` / `unlinkEntry` (the owner's, which no rule replaces), `reviews` and `resolveReview` (choose a candidate, or none of them). An event shows its owner-organized copy, else the latest edited; it is cancelled only when every live entry is. A deleted single event, occurrence or whole series keeps its past as history (`source_deleted_at`) and cancels its future. Each change of an entry's or meeting's event is logged in `entity_link_events`. Text is stored with HTML reduced to text, passcode, password and PIN lines dropped and every link without its query string; `metadata` keeps only `ENTRY_METADATA_KEYS`. `eventStoreContract` (`@wirecat/cli-core/meetings/testing`) runs the rules against any `EventStore`.
+- **Calendars in the store** (store version 33; available from the cli-core release that carries store versions 30 to 33). `calendars` (an account's calendars, `synced` for those whose entries sync), `calendar_entries` (one calendar's copy of a single event, a series or one occurrence: the source records of `events` and `event_series`, with `ical_uid`, `original_starts_at`, `recurrence`, `recurrence_ends_at` — NULL for a series that repeats indefinitely —, `join_url` without its query string and `join_key`; a trigger refuses an entry that ends before it starts), `calendar_entry_revisions` (tracked fields before a change) and `calendar_entry_participants` (who an entry lists, by address). Events gain `status`, `all_day` and `source_deleted_at` (below). Events have a words index of their own (`event_words`, `event_stems`, queue `event_index_pending`) over title, description, location and attendee names, leaving out working-location, focus-time, out-of-office and birthday entries; every existing event is queued. Nothing writes calendars yet: `EventStore` comes next.
+- **`meetings.join_key`** (store version 33; same release): the room a meeting is held in without its passcode — `zoom:<number>`, `meet:<code>`, else host and path — written with every meeting and filled on open for those stored before, so a calendar entry can be matched to its Zoom meeting by room rather than by a link carrying `pwd=`. `joinKeyOf` and `joinUrlWithoutQuery` (`src/meetings/join-key.ts`).
+- **`store.files`, where each document is kept** (available from the cli-core release that carries store versions 30 to 33). `list(accountId, { under, pathContains, kind, includeDeleted, limit, offset })` reads one account's files by path: `under` is a subtree, one range over the folded path's index; `pathContains` is any case and accent. `byPath(accountId, path)` and `ofDocument(reference)`, which answers the most recently changed live file first: the one the document shows. Types `FilesStore`, `StoredFile` and `FileListQuery` from `@wirecat/cli-core/store`. The account is always named; there is no default place.
+- **Search hits read a document's link and edit time from its file** (same release): `search notes`, `search all` and context evidence prefer the preferred file's `url` and `external_updated_at`, then the document's columns, then Drive's front matter. A document whose account's provider is registered with kind `documents` is a document with no front matter, labelled with the command whose profile names that account.
+- **`identities.email`** (store version 32; same release). A mail contact's address, lower case, filled for every existing mail contact and by a trigger for every new one, whatever writes it. A contact saved with an address (`savePeople`'s `email`, a Drive owner or editor) carries it too, and the same-email join finds the mail contact by this column.
+- **`entity_link_events` and `link_reviews`** (store version 32; same release): the log of every change of the entity a source record belongs to (each file's link to its document now, method `import`; calendar entries and meetings to events next), and the owner's review list of source records with two equally good entities, which nothing writes yet.
+- **`NoteFolder.provider`**: `obsidian`, `local`, or `folder` for Drive's stand-in folders.
+
+## 0.419.0 — 25.10.2026
+
+### Fixed
+
+- **`cli-core-parity` reads a large piped program again.** `<cli> commands --json | cli-core-parity <cli>` stopped with `EAGAIN: resource temporarily unavailable, read` once the program was larger than the pipe buffer and the writer was still writing: a module it loads makes a piped stdin non-blocking, and the tool read stdin with a call that cannot wait for more. It now reads stdin as a stream to the end.
+
 ## 0.418.0 — 25.10.2026
 
 ### Added

package/dist/domain/providers.d.ts

@@ -11,8 +11,26 @@ export interface ProviderEntry {
 }
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export declare const PROVIDERS: readonly ProviderEntry[];
-/** The store keeps a notes folder as an `accounts` row of this provider; people call it `notes`. */
-export declare const FOLDER_PROVIDER = "folder";
+/**
+ * A notes folder is an `accounts` row of one of these providers; people call every one `notes`. `obsidian` is a vault,
+ * `local` a plain folder (store version 32). `folder` is what they were before, and what Drive's stand-in folders and
+ * profile keys saved before that still say.
+ */
+export declare const FOLDER_PROVIDERS: readonly ["local", "obsidian", "folder"];
+export declare const isFolderProvider: (provider: string) => boolean;
+/** The same test in SQL, over an `accounts` row's `provider` column. */
+export declare const folderProviderSql: (column?: string) => string;
+/** The provider a new folder of this format gets. */
+export declare const folderProviderOf: (format: "obsidian" | "markdown") => "obsidian" | "local";
+/**
+ * Providers whose account holds documents the way a notes folder does: one account per remote principal, its
+ * files as `documents` rows (store version 31 moved Drive here from a `folder` named `google-drive:<principal>`).
+ * The provider registry's `documents` kind replaces this list when Drive leaves `notes` (Wave 3 R2).
+ */
+export declare const DOCUMENT_ACCOUNT_PROVIDERS: readonly ["google-drive"];
+export declare const isDocumentAccountProvider: (provider: string) => boolean;
+/** A folder or a documents account, in SQL over an `accounts` row's `provider` column. */
+export declare const filesAccountSql: (column?: string) => string;
 /** Notes written in memo have no account row; this is their account. */
 export declare const INTERNAL_NOTES = "internal";
 /** The reason a search gives for an account whose provider no entry names. */

package/dist/domain/providers.js

@@ -11,10 +11,30 @@ export const PROVIDERS = [
     { name: "whatsapp-bot", kind: "messages", aliases: ["wa-bot"] },
     { name: "email", kind: "mail", aliases: [] },
     { name: "notes", kind: "notes", aliases: [] },
+    { name: "local", kind: "notes", aliases: [] },
+    { name: "obsidian", kind: "notes", aliases: [] },
     { name: "zoom", kind: "meetings", aliases: [] },
 ];
-/** The store keeps a notes folder as an `accounts` row of this provider; people call it `notes`. */
-export const FOLDER_PROVIDER = "folder";
+/**
+ * A notes folder is an `accounts` row of one of these providers; people call every one `notes`. `obsidian` is a vault,
+ * `local` a plain folder (store version 32). `folder` is what they were before, and what Drive's stand-in folders and
+ * profile keys saved before that still say.
+ */
+export const FOLDER_PROVIDERS = ["local", "obsidian", "folder"];
+export const isFolderProvider = (provider) => FOLDER_PROVIDERS.includes(provider);
+/** The same test in SQL, over an `accounts` row's `provider` column. */
+export const folderProviderSql = (column = "provider") => `${column} IN (${FOLDER_PROVIDERS.map((name) => `'${name}'`).join(", ")})`;
+/** The provider a new folder of this format gets. */
+export const folderProviderOf = (format) => format === "markdown" ? "local" : "obsidian";
+/**
+ * Providers whose account holds documents the way a notes folder does: one account per remote principal, its
+ * files as `documents` rows (store version 31 moved Drive here from a `folder` named `google-drive:<principal>`).
+ * The provider registry's `documents` kind replaces this list when Drive leaves `notes` (Wave 3 R2).
+ */
+export const DOCUMENT_ACCOUNT_PROVIDERS = ["google-drive"];
+export const isDocumentAccountProvider = (provider) => DOCUMENT_ACCOUNT_PROVIDERS.includes(provider);
+/** A folder or a documents account, in SQL over an `accounts` row's `provider` column. */
+export const filesAccountSql = (column = "provider") => `${column} IN (${[...FOLDER_PROVIDERS, ...DOCUMENT_ACCOUNT_PROVIDERS].map((name) => `'${name}'`).join(", ")})`;
 /** Notes written in memo have no account row; this is their account. */
 export const INTERNAL_NOTES = "internal";
 /** The reason a search gives for an account whose provider no entry names. */
@@ -105,6 +125,6 @@ export const providerNamed = (word) => {
     return registry.find((entry) => wordsOf(entry).includes(wanted));
 };
 /** The kind of a provider the registry knows; `undefined` for one no entry names, which a search skips. */
-export const kindIn = (provider) => provider === FOLDER_PROVIDER ? "notes" : registry.find(({ name }) => name === provider)?.kind;
+export const kindIn = (provider) => isFolderProvider(provider) ? "notes" : registry.find(({ name }) => name === provider)?.kind;
 /** A provider the registry does not list counts as a messenger here; a search asks `kindIn` and skips it. */
 export const kindOf = (provider) => kindIn(provider) ?? "messages";

package/dist/domain/tag-consolidation.d.ts

@@ -16,6 +16,8 @@ export interface TagConsolidationPreview {
         id: string;
         name: string;
     };
+    sourceMemberIds: string[];
+    survivorMemberIds: string[];
     vocabularyFingerprint: string;
     previewFingerprint: string;
     assignments: {
@@ -69,9 +71,36 @@ export interface TagConsolidationPreview {
         rows: number;
         readBytes: number;
         samplesComplete: boolean;
-        applySupported: false;
+        applySupported: true;
     };
 }
 export interface TagConsolidationStore {
     previewTagConsolidation(options: TagConsolidationOptions): Promise<TagConsolidationPreview>;
+    applyTagConsolidation(options: TagConsolidationApplyOptions): Promise<TagConsolidationReceipt>;
+}
+export interface TagConsolidationApplyOptions extends Omit<TagConsolidationOptions, "sampleLimit"> {
+    by: "owner";
+    expectedPreviewFingerprint: string;
+    idempotencyKey: string;
+}
+export interface TagConsolidationReceipt {
+    id: string;
+    sourceId: string;
+    survivorId: string;
+    sourceMemberIds: string[];
+    survivorMemberIds: string[];
+    actor: {
+        type: "person";
+        id: string;
+    };
+    createdAt: string;
+    idempotencyKey: string;
+    vocabularyFingerprint: string;
+    previewFingerprint: string;
+    counts: {
+        assignments: number;
+        aliases: number;
+        automaticClaims: number;
+        links: number;
+    };
 }

package/dist/entities/index.d.ts

@@ -6783,7 +6783,10 @@ export declare const ENTITIES: {
         readonly starts_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
         readonly ends_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
         readonly timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
-        readonly origin: v.PicklistSchema<["auto", "owner"], undefined>;
+        readonly origin: v.PicklistSchema<["auto", "owner", "calendar"], undefined>;
+        readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly all_day: v.BooleanSchema<undefined>;
+        readonly source_deleted_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
         readonly deleted_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
         readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
         readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export type { MessageLink, MessagePermalink } from "./domain/message-link.js";
 export type * from "./domain/models.js";
 export { countedPoll } from "./domain/polls.js";
-export { isKind, KINDS, type Kind, kindIn, kindOf, PROVIDERS, type ProviderEntry, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
+export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, type Kind, kindIn, kindOf, PROVIDERS, type ProviderEntry, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export type { RankingGraphEvidence, RankingGraphLink } from "./domain/rankings-graph.js";
 export type { RankingComponent, RankingInput, RankingMeasure, RankingOptions, RankingTarget, RankingWeights, ScorePreset, } from "./domain/rankings-options.js";
 export { rankingOptions } from "./domain/rankings-options.js";

package/dist/index.js

@@ -5,7 +5,7 @@ export { formatLocator, isLocator, parseLocator } from "./domain/locator.js";
 export { parseMarkdown } from "./domain/markdown.js";
 export { parseMarkdownSpans } from "./domain/markdown-spans.js";
 export { countedPoll } from "./domain/polls.js";
-export { isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
+export { FOLDER_PROVIDERS, isFolderProvider, isKind, KINDS, kindIn, kindOf, PROVIDERS, providerNamed, providers, UNKNOWN_PROVIDER, useProviders, } from "./domain/providers.js";
 export { rankingOptions } from "./domain/rankings-options.js";
 export { canonicalReference, formatReference, parseReference } from "./domain/references.js";
 export { normalizeTag, TAG_TYPES } from "./domain/tags.js";

package/dist/meetings/calendar-text.d.ts

@@ -0,0 +1,13 @@
+/** Every web link without its query string or fragment, which is where passcodes ride (`pwd=`). */
+export declare const withoutLinkQueries: (text: string) => string;
+/**
+ * A calendar's text as the store keeps it: HTML reduced to text, links without their query strings, and each line
+ * naming a passcode, password or PIN dropped — except from a title, where "PIN reset review" is a meeting's name.
+ * `null` when nothing is left.
+ */
+export declare const calendarText: (text: string | null | undefined, { dropSecretLines }?: {
+    dropSecretLines?: boolean;
+}) => string | null;
+/** The provider fields a calendar entry may keep in `metadata`: none of them can open a meeting. */
+export declare const ENTRY_METADATA_KEYS: readonly ["colorId", "guestsCanInviteOthers", "guestsCanModify", "guestsCanSeeOtherGuests", "hangoutLink", "locked", "privateCopy", "recurring_event_id"];
+export declare const entryMetadata: (metadata: Record<string, unknown> | null | undefined) => Record<string, unknown>;

package/dist/meetings/calendar-text.js

@@ -0,0 +1,57 @@
+import { joinUrlWithoutQuery } from "./join-key.js";
+const ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', "#39": "'", apos: "'", nbsp: " " };
+/**
+ * A line that gives a way into a meeting: a passcode, a password, a PIN or an access code. Bounded by letters and
+ * digits, not `\b`, which knows only ASCII and would never match a Cyrillic word.
+ */
+const SECRET_LINE = /(?<![\p{L}\p{N}])(pass ?codes?|passwords?|pwd|pins?|access ?codes?|meeting ?codes?|kennwort|пароль|пин-?код|код доступа)(?![\p{L}\p{N}])|pwd=/iu;
+const htmlToText = (html) => html
+    .replace(/<\s*br\s*\/?>/giu, "\n")
+    .replace(/<\/\s*(p|div|li|tr|h[1-6])\s*>/giu, "\n")
+    .replace(/<a\s[^>]*href\s*=\s*"([^"]*)"[^>]*>/giu, " $1 ")
+    .replace(/<[^>]+>/gu, "")
+    .replace(/&(amp|lt|gt|quot|#39|apos|nbsp);/gu, (_, name) => ENTITIES[name] ?? "");
+/** Every web link without its query string or fragment, which is where passcodes ride (`pwd=`). */
+export const withoutLinkQueries = (text) => text.replace(/https?:\/\/[^\s<>"')\]]+/giu, (url) => joinUrlWithoutQuery(url) ?? "");
+/**
+ * A calendar's text as the store keeps it: HTML reduced to text, links without their query strings, and each line
+ * naming a passcode, password or PIN dropped — except from a title, where "PIN reset review" is a meeting's name.
+ * `null` when nothing is left.
+ */
+export const calendarText = (text, { dropSecretLines = true } = {}) => {
+    if (!text)
+        return null;
+    const kept = htmlToText(text)
+        .split(/\r?\n/u)
+        .map((line) => withoutLinkQueries(line)
+        .replace(/[ \t]+/gu, " ")
+        .trim())
+        .filter((line) => !dropSecretLines || !SECRET_LINE.test(line));
+    const joined = kept
+        .join("\n")
+        .replace(/\n{3,}/gu, "\n\n")
+        .trim();
+    return joined || null;
+};
+/** The provider fields a calendar entry may keep in `metadata`: none of them can open a meeting. */
+export const ENTRY_METADATA_KEYS = [
+    "colorId",
+    "guestsCanInviteOthers",
+    "guestsCanModify",
+    "guestsCanSeeOtherGuests",
+    "hangoutLink",
+    "locked",
+    "privateCopy",
+    "recurring_event_id",
+];
+export const entryMetadata = (metadata) => {
+    const kept = {};
+    for (const key of ENTRY_METADATA_KEYS) {
+        const value = metadata?.[key];
+        if (typeof value === "string")
+            kept[key] = withoutLinkQueries(value);
+        else if (typeof value === "number" || typeof value === "boolean")
+            kept[key] = value;
+    }
+    return kept;
+};

package/dist/meetings/event-store.d.ts

@@ -0,0 +1,202 @@
+import type { Event } from "./model.js";
+/** One calendar as a provider lists it. */
+export interface CalendarInput {
+    externalId: string;
+    title: string | null;
+    timezone: string | null;
+    /** owner, writer, reader, freeBusyReader. A calendar the owner owns syncs by default. */
+    accessRole: string | null;
+    primary: boolean;
+}
+export interface StoredCalendar {
+    id: number;
+    accountId: number;
+    externalId: string;
+    title: string | null;
+    timezone: string | null;
+    accessRole: string | null;
+    primary: boolean;
+    synced: boolean;
+    seenAt: number | null;
+    deletedAt: number | null;
+}
+export interface EntryParticipantInput {
+    email: string;
+    name?: string | null;
+    response?: string | null;
+    optional?: boolean;
+    organizer?: boolean;
+    self?: boolean;
+    /** A room or a piece of equipment: listed, never a contact. */
+    resource?: boolean;
+}
+export type EntryKind = "single" | "series" | "occurrence";
+export type EntryStatus = "confirmed" | "tentative" | "cancelled";
+/**
+ * One calendar entry as the provider returns it. Times are epoch milliseconds, `endsAt` exclusive. Text is cleaned
+ * before it is stored; there is no field for a conference's entry points, so no passcode or PIN can be given.
+ */
+export interface EntryInput {
+    externalId: string;
+    kind: EntryKind;
+    /** An occurrence's series, by the series entry's `externalId` (Google's `recurringEventId`). */
+    seriesExternalId?: string | null;
+    icalUid?: string | null;
+    /** An occurrence's slot in its series (Google's `originalStartTime`). */
+    originalStartsAt?: number | null;
+    exception?: boolean;
+    status: EntryStatus;
+    title?: string | null;
+    description?: string | null;
+    location?: string | null;
+    startsAt?: number | null;
+    endsAt?: number | null;
+    allDay?: boolean;
+    startDate?: string | null;
+    endDate?: string | null;
+    timezone?: string | null;
+    recurrence?: string[] | null;
+    /** A series' last slot; `null` repeats indefinitely. */
+    recurrenceEndsAt?: number | null;
+    eventType?: string | null;
+    transparency?: string | null;
+    visibility?: string | null;
+    ownResponse?: string | null;
+    organizer?: {
+        email: string;
+        name?: string | null;
+    } | null;
+    participants?: EntryParticipantInput[];
+    joinUrl?: string | null;
+    conference?: string | null;
+    url?: string | null;
+    sequence?: number | null;
+    etag?: string | null;
+    externalUpdatedAt?: number | null;
+    /** Only the keys `ENTRY_METADATA_KEYS` names are kept. */
+    metadata?: Record<string, unknown> | null;
+}
+export interface StoredEntry {
+    id: number;
+    calendarId: number;
+    kind: EntryKind;
+    seriesEntryId: number | null;
+    eventId: number | null;
+    eventSeriesId: number | null;
+    externalId: string;
+    icalUid: string | null;
+    originalStartsAt: number | null;
+    exception: boolean;
+    status: EntryStatus;
+    title: string | null;
+    description: string | null;
+    location: string | null;
+    startsAt: number | null;
+    endsAt: number | null;
+    allDay: boolean;
+    startDate: string | null;
+    endDate: string | null;
+    timezone: string | null;
+    recurrence: string[] | null;
+    recurrenceEndsAt: number | null;
+    eventType: string | null;
+    ownResponse: string | null;
+    organizerIdentityId: number | null;
+    joinUrl: string | null;
+    joinKey: string | null;
+    url: string | null;
+    externalUpdatedAt: number | null;
+    seenAt: number | null;
+    deletedAt: number | null;
+}
+export interface StoredParticipant {
+    entryId: number;
+    identityId: number | null;
+    email: string;
+    name: string | null;
+    response: string | null;
+    optional: boolean;
+    organizer: boolean;
+    self: boolean;
+    resource: boolean;
+}
+/** An entry's tracked fields as they were before one change. */
+export interface EntryRevision {
+    entryId: number;
+    title: string | null;
+    startsAt: number | null;
+    endsAt: number | null;
+    location: string | null;
+    status: string | null;
+    recurrence: string[] | null;
+    recurrenceEndsAt: number | null;
+    externalUpdatedAt: number | null;
+    createdAt: number;
+}
+export interface EventDetails {
+    event: Event;
+    entries: StoredEntry[];
+    participants: StoredParticipant[];
+    revisions: EntryRevision[];
+}
+export interface EventFilter {
+    /** Events that end after this instant (exclusive end). */
+    from?: number;
+    /** Events that start before this instant. */
+    to?: number;
+    accountId?: number;
+    calendarId?: number;
+    /** Events whose entries list one of this person's contacts. */
+    personId?: number;
+    limit?: number;
+    offset?: number;
+}
+/** Pairs the rules left unlinked because two or more entities fit equally well (requirements 3.6). */
+export interface LinkReview {
+    id: number;
+    linkableType: string;
+    linkableId: number;
+    entityType: string;
+    candidates: number[];
+    reason: string;
+    status: "open" | "linked" | "apart";
+    chosenId: number | null;
+    decidedBy: string | null;
+    decidedAt: number | null;
+    createdAt: number;
+}
+export type ReviewDecision = {
+    choose: number;
+} | {
+    apart: true;
+};
+/**
+ * Calendars and their entries, the source records of events (requirements 3.4). Apart from `MeetingStore`: a
+ * calendar CLI implements this one, a meeting app the other. Every write is one transaction; an owner's link is never
+ * replaced by a rule, and two equally good candidates make no link and one review entry.
+ */
+export interface EventStore {
+    saveCalendars(accountId: number, calendars: CalendarInput[], now: number): Promise<StoredCalendar[]>;
+    calendars(accountId: number): Promise<StoredCalendar[]>;
+    setCalendarSynced(calendarId: number, synced: boolean, now: number): Promise<void>;
+    /** One sync page, matched by rules 1–5, in one transaction. */
+    saveEntries(calendarId: number, entries: EntryInput[], now: number): Promise<StoredEntry[]>;
+    /**
+     * After a full list (`410 Gone`): entries not seen since `seenBefore` get `deleted_at`. Plain occurrences come only
+     * from the window fetched, so only those inside it count. Events, series and links stay.
+     */
+    markUnseen(calendarId: number, seenBefore: number, window: {
+        from: number;
+        to: number;
+    }, now: number): Promise<number>;
+    events(filter?: EventFilter): Promise<Event[]>;
+    event(id: number): Promise<EventDetails | null>;
+    /** The owner's link of an entry to an event; no rule replaces it. */
+    linkEntry(entryId: number, eventId: number, now: number): Promise<void>;
+    /** The owner's unlink: the rules leave the entry alone after it. */
+    unlinkEntry(entryId: number, now: number): Promise<void>;
+    reviews(filter?: {
+        status?: LinkReview["status"];
+    }): Promise<LinkReview[]>;
+    resolveReview(id: number, decision: ReviewDecision, now: number): Promise<LinkReview>;
+}

package/dist/meetings/event-store.js

@@ -0,0 +1 @@
+export {};

package/dist/meetings/events.js

@@ -13,7 +13,11 @@ export const linkEvent = async (store, details, now = Date.now()) => {
             startsAt: meeting.startedAt,
             endsAt: meeting.endedAt ?? meeting.startedAt,
         });
-    let event = candidates.length === 1 ? candidates[0] : undefined;
+    if (candidates.length > 1) {
+        await store.reviewMeetingLink?.(meeting.id, candidates.map(({ id }) => id), now);
+        return null;
+    }
+    let event = candidates[0];
     if (!event) {
         let eventSeriesId = series?.eventSeriesId ?? null;
         if (series?.kind === "recurring" && eventSeriesId === null) {

package/dist/meetings/index.d.ts

@@ -1,8 +1,10 @@
 export { MEETING_STEPS, type MeetingDetailsItem, type MeetingHitItem, type MeetingItemBody, type MeetingListBody, type MeetingSummaryItem, type MeetingTranscriptItem, meetingDetails, meetingHit, meetingHitsList, meetingSummary, meetingTranscript, } from "./answers.js";
 export type { MeetingBatchReader } from "./batch.js";
+export { calendarText, ENTRY_METADATA_KEYS, entryMetadata, withoutLinkQueries } from "./calendar-text.js";
 export type { MeetingContextStore, MeetingEventLinkInput, MeetingEventLinkReceipt, ParticipantPerson, ParticipantPersonInput, ParticipantPersonLinkInput, ParticipantPersonLinkReceipt, } from "./context-store.js";
 export { type MeetingCueIdentity, meetingCueFingerprint } from "./cue-fingerprint.js";
 export { EVENT_QUERY } from "./event-query.js";
+export type { CalendarInput, EntryInput, EntryKind, EntryParticipantInput, EntryRevision, EntryStatus, EventDetails, EventFilter, EventStore, LinkReview, ReviewDecision, StoredCalendar, StoredEntry, StoredParticipant, } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, type MeetingExport, type MeetingExportFormat, type MeetingExportOptions, serializeVtt, } from "./export.js";
 export { type FindingEvidence, type FindingOutcome, findingHash, MEETING_FINDINGS_KIND, type MeetingFactFinding, type MeetingFinding, type MeetingFindingsInput, type MeetingFindingsReceipt, type MeetingTaskFinding, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";
@@ -10,6 +12,7 @@ export { type Finding, type FindingsInput, type FindingsReceipt, type FindingsRu
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { type ImportFile, importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, type MeetingIssue, type MeetingItem, type MeetingOwner, meeting, meetingIssuesOf, meetingItem, } from "./item.js";
+export { joinKeyOf, joinUrlWithoutQuery } from "./join-key.js";
 export { CHAT_MESSAGES_READ, type MeetingChatLine, type MeetingChatLinesInput, type MeetingChatLinesStore, type MeetingLink, } from "./links.js";
 export { createMeetingContext, MEETING_FACT_TYPES, type MeetingContextAction, type MeetingContextChange, type MeetingContextOperation, type MeetingContextPorts, type MeetingContextReceipt, validateMeetingContextChange, } from "./meeting-context.js";
 export { createMeetingManagement, dispatchMeetingMutation, type ManagedMeeting, type ManagedMeetingChange, type MeetingManagement, type MeetingManagementPorts, type MeetingMutationOptions, type MeetingMutationProposal, type MeetingMutationReceipt, type MeetingOperationOptions, type MeetingProviderContext, validateMeetingChange, } from "./meeting-management.js";

package/dist/meetings/index.js

@@ -1,4 +1,5 @@
 export { MEETING_STEPS, meetingDetails, meetingHit, meetingHitsList, meetingSummary, meetingTranscript, } from "./answers.js";
+export { calendarText, ENTRY_METADATA_KEYS, entryMetadata, withoutLinkQueries } from "./calendar-text.js";
 export { meetingCueFingerprint } from "./cue-fingerprint.js";
 export { EVENT_QUERY } from "./event-query.js";
 export { linkEvent } from "./events.js";
@@ -8,6 +9,7 @@ export { findingFingerprint, validateFindings, } from "./findings-rules.js";
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, meeting, meetingIssuesOf, meetingItem, } from "./item.js";
+export { joinKeyOf, joinUrlWithoutQuery } from "./join-key.js";
 export { CHAT_MESSAGES_READ, } from "./links.js";
 export { createMeetingContext, MEETING_FACT_TYPES, validateMeetingContextChange, } from "./meeting-context.js";
 export { createMeetingManagement, dispatchMeetingMutation, validateMeetingChange, } from "./meeting-management.js";

package/dist/meetings/join-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * What one meeting room is, whatever link it was shared by: `zoom:<number>`, `meet:<code>`, else the host and path.
+ * A query string carries passcodes (`pwd=`), so it never reaches the key or a stored link.
+ */
+export declare const joinKeyOf: (url: string | null | undefined) => string | null;
+/** The link without its query string or fragment, which may hold a passcode. */
+export declare const joinUrlWithoutQuery: (url: string | null | undefined) => string | null;

package/dist/meetings/join-key.js

@@ -0,0 +1,38 @@
+/**
+ * What one meeting room is, whatever link it was shared by: `zoom:<number>`, `meet:<code>`, else the host and path.
+ * A query string carries passcodes (`pwd=`), so it never reaches the key or a stored link.
+ */
+export const joinKeyOf = (url) => {
+    const parsed = urlOf(url);
+    if (!parsed)
+        return null;
+    const host = parsed.hostname.toLowerCase().replace(/^www\./u, "");
+    const path = parsed.pathname.replace(/\/+$/u, "");
+    if (host === "zoom.us" || host.endsWith(".zoom.us") || host === "zoomgov.com" || host.endsWith(".zoomgov.com")) {
+        const number = /^\/(?:j|w|s|wc\/join|wc)\/(\d{9,12})(?:\/|$)/u.exec(path)?.[1];
+        if (number)
+            return `zoom:${number}`;
+    }
+    if (host === "meet.google.com") {
+        const code = /^\/([a-z]{3}-[a-z]{4}-[a-z]{3})$/iu.exec(path)?.[1];
+        if (code)
+            return `meet:${code.toLowerCase()}`;
+    }
+    return `${host}${path}`;
+};
+/** The link without its query string or fragment, which may hold a passcode. */
+export const joinUrlWithoutQuery = (url) => {
+    const parsed = urlOf(url);
+    return parsed ? `${parsed.origin}${parsed.pathname}` : null;
+};
+const urlOf = (url) => {
+    if (!url?.trim())
+        return null;
+    try {
+        const parsed = new URL(url.trim());
+        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/meetings/model.d.ts

@@ -13,7 +13,8 @@ export interface EventSeries extends RecordTimes {
     id: number;
     title: string | null;
     recurrence: string | null;
-    origin: "auto" | "owner";
+    /** `auto` from a meeting, `owner`, or `calendar` from a calendar's entries. */
+    origin: "auto" | "owner" | "calendar";
 }
 export interface Event extends RecordTimes {
     id: number;
@@ -24,8 +25,13 @@ export interface Event extends RecordTimes {
     startsAt: number | null;
     endsAt: number | null;
     timezone: string | null;
-    origin: "auto" | "owner";
+    origin: "auto" | "owner" | "calendar";
     deletedAt: number | null;
+    /** confirmed, tentative, cancelled: cancelled only when every live calendar entry of it is. */
+    status?: string | null;
+    allDay?: boolean | null;
+    /** When its calendar deleted it; a past event stays as a meeting that happened. */
+    sourceDeletedAt?: number | null;
 }
 export interface MeetingSeries extends RecordTimes {
     id: number;

package/dist/meetings/read-answers.d.ts

@@ -176,8 +176,12 @@ export declare const event: v.StrictObjectSchema<{
     readonly starts_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
     readonly ends_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
     readonly timezone: v.NullableSchema<v.StringSchema<undefined>, undefined>;
-    /** `auto`: made from a meeting; `owner`: made by hand. */
-    readonly origin: v.PicklistSchema<["auto", "owner"], undefined>;
+    /** `auto`: made from a meeting; `owner`: made by hand; `calendar`: from a calendar's entries. */
+    readonly origin: v.PicklistSchema<["auto", "owner", "calendar"], undefined>;
+    readonly status: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    readonly all_day: v.BooleanSchema<undefined>;
+    /** When its calendar deleted it: shown as "deleted in Google", kept as history. */
+    readonly source_deleted_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
     readonly deleted_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
     readonly created_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;
     readonly updated_at: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>;