@wirecat/cli-core 0.372.0 → 0.373.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ shape of this file.
 
 ## Unreleased
 
+## 0.373.0 — 20.10.2026
+
+### Added
+
+- **Read-only project annotation snapshots from `./store`** preserve project metadata, alias provenance
+  and timestamps, facts and direct links in a version-2 manifest. `snapshotProjectAnnotations` reads one
+  explicit project from an existing current-schema store in a consistent SQLite transaction, with
+  bounded source hashing and no migration or source text in the result. The decoder and fingerprint
+  helpers validate that format independently. Notes, meeting memberships, tasks, memories, labels
+  and findings remain explicitly omitted; restore and CLI commands are not included.
+
 ## 0.372.0 — 20.10.2026
 
 ### Added

package/dist/store/index.d.ts

@@ -16,6 +16,7 @@ export { openCache } from "./open.js";
 export { storePath } from "./path.js";
 export { decodeProjectAnnotations, PROJECT_ANNOTATIONS_MAX_BYTES, type ProjectAnnotations, projectAnnotationsFingerprint, } from "./project-transfer/manifest.js";
 export { type ProjectAnnotationsPlan, type ProjectAnnotationsTarget, planProjectAnnotations, } from "./project-transfer/plan.js";
+export { decodeProjectAnnotationSnapshot, type ProjectAnnotationSnapshot, type ProjectAnnotationSnapshotOptions, type ProjectAnnotationSnapshotResult, projectAnnotationSnapshotFingerprint, snapshotProjectAnnotations, } from "./project-transfer/snapshot.js";
 export type { AgentAction, AgentActionInput, AgentActionsStore } from "./sqlite/agent-actions.js";
 export { resetAttachmentWords } from "./sqlite/attachment-texts.js";
 export { backfillNormalized, pendingNormalization } from "./sqlite/backfill.js";

package/dist/store/index.js

@@ -8,6 +8,7 @@ export { openCache } from "./open.js";
 export { storePath } from "./path.js";
 export { decodeProjectAnnotations, PROJECT_ANNOTATIONS_MAX_BYTES, projectAnnotationsFingerprint, } from "./project-transfer/manifest.js";
 export { planProjectAnnotations, } from "./project-transfer/plan.js";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint, snapshotProjectAnnotations, } from "./project-transfer/snapshot.js";
 export { resetAttachmentWords } from "./sqlite/attachment-texts.js";
 export { backfillNormalized, pendingNormalization } from "./sqlite/backfill.js";
 export { CATALOG_QUERY } from "./sqlite/catalog.js";

package/dist/store/project-transfer/manifest.d.ts

@@ -1,6 +1,7 @@
 import { type ProjectAnnotations } from "./schema.js";
 export type { ProjectAnnotations } from "./schema.js";
 export declare const PROJECT_ANNOTATIONS_MAX_BYTES: number;
+export declare const validateProjectAnnotationsGraph: (manifest: ProjectAnnotations, additionalActors?: string[]) => void;
 /** Decode bounded JSON, never a row/column importer or an implicit whole-project backup. */
 export declare const decodeProjectAnnotations: (json: string) => ProjectAnnotations;
 export declare const projectAnnotationsFingerprint: (json: string) => string;

package/dist/store/project-transfer/manifest.js

@@ -17,7 +17,7 @@ const canonical = (ref) => {
         return invalid("reference");
     }
 };
-const graph = (manifest) => {
+export const validateProjectAnnotationsGraph = (manifest, additionalActors = []) => {
     const owned = new Set([manifest.project.ref]);
     const external = new Set();
     const used = new Set();
@@ -59,6 +59,10 @@ const graph = (manifest) => {
     if (manifest.project.organization !== null)
         kind(manifest.project.organization, ["organization"]);
     dependency(manifest.project.organization);
+    for (const actor of additionalActors) {
+        kind(actor, ["person", "bot"]);
+        dependency(actor);
+    }
     const aliases = new Set([manifest.project.name, manifest.project.key].map(normalizeVocabularyName));
     for (const alias of manifest.aliases) {
         const name = normalizeVocabularyName(alias);
@@ -121,7 +125,7 @@ export const decodeProjectAnnotations = (json) => {
     const manifest = parsed.output;
     if (manifest.aliases.length + manifest.facts.length + manifest.links.length + manifest.external.length > 1000)
         invalid("record budget");
-    graph(manifest);
+    validateProjectAnnotationsGraph(manifest);
     return manifest;
 };
 export const projectAnnotationsFingerprint = (json) => {

package/dist/store/project-transfer/snapshot-model.d.ts

@@ -0,0 +1,118 @@
+import * as v from "valibot";
+import { type ProjectAnnotations } from "./schema.js";
+declare const schema: v.StrictObjectSchema<{
+    readonly format: v.LiteralSchema<"wirecat.project-annotations", undefined>;
+    readonly facts: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly type: v.PicklistSchema<readonly ["fact", "statement", "question", "decision", "promise"], undefined>;
+        readonly statement: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly status: v.PicklistSchema<readonly ["proposed", "accepted", "superseded", "reversed"], undefined>;
+        readonly subject: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly occurred_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly supersedes: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly author: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly model: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly confirmed_by: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly scope: v.NullableSchema<v.PicklistSchema<readonly ["personal", "work"], undefined>, undefined>;
+        readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly updated_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        type: "decision" | "fact" | "promise" | "question" | "statement";
+        statement: string;
+        status: "accepted" | "proposed" | "reversed" | "superseded";
+        subject: string | null;
+        occurred_at: number | null;
+        supersedes: string | null;
+        author: string;
+        model: string | null;
+        confirmed_by: string | null;
+        scope: "personal" | "work" | null;
+        source: string;
+        created_at: number;
+        updated_at: number;
+    }[], 1000, undefined>]>;
+    readonly links: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly from: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly to: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly kind: v.PicklistSchema<readonly ["links-to", "blocked-by", "follow-up-of", "about", "member-of", "labelled", "answered-by", "evidence", "created-from", "duplicate-of", "related-to", "assigned-to"], undefined>;
+        readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message"], undefined>;
+        readonly anchor: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly target_text: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly role: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly evidence: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly confirmed: v.BooleanSchema<undefined>;
+        readonly provenance: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly updated_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly author: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        from: string;
+        to: string | null;
+        kind: "about" | "answered-by" | "assigned-to" | "blocked-by" | "created-from" | "duplicate-of" | "evidence" | "follow-up-of" | "labelled" | "links-to" | "member-of" | "related-to";
+        origin: "file" | "message" | "owner" | "suggested";
+        anchor: string | null;
+        target_text: string | null;
+        role: string | null;
+        evidence: string | null;
+        confirmed: boolean;
+        provenance: string | null;
+        created_at: number;
+        updated_at: number;
+        author: string | null;
+    }[], 1000, undefined>]>;
+    readonly external: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly content_sha256: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        ref: string;
+        content_sha256: string | null;
+    }[], 1000, undefined>]>;
+    readonly version: v.LiteralSchema<2, undefined>;
+    readonly coverage: v.StrictObjectSchema<{
+        readonly aliases: v.LiteralSchema<"complete", undefined>;
+        readonly facts: v.LiteralSchema<"complete", undefined>;
+        readonly links: v.LiteralSchema<"complete", undefined>;
+        readonly memories: v.LiteralSchema<"omitted", undefined>;
+        readonly tasks: v.LiteralSchema<"omitted", undefined>;
+        readonly labels: v.LiteralSchema<"omitted", undefined>;
+        readonly findings: v.LiteralSchema<"omitted", undefined>;
+        readonly meeting_memberships: v.LiteralSchema<"omitted", undefined>;
+        readonly notes: v.LiteralSchema<"omitted", undefined>;
+    }, undefined>;
+    readonly project: v.StrictObjectSchema<{
+        readonly ref: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly key: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>;
+        readonly type: v.PicklistSchema<["work", "client", "personal", "oss", "other"], undefined>;
+        readonly scope: v.PicklistSchema<readonly ["personal", "work"], undefined>;
+        readonly organization: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly description: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>, v.CheckAction<string, undefined>]>, undefined>;
+        readonly status: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>, v.CheckAction<string, undefined>]>, undefined>;
+        readonly owner: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>, v.CheckAction<string, undefined>]>, undefined>;
+        readonly updated_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly account_scope: v.LiteralSchema<"owner", undefined>;
+    }, undefined>;
+    readonly aliases: v.SchemaWithPipe<readonly [v.ArraySchema<v.StrictObjectSchema<{
+        readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>, v.CheckAction<string, undefined>]>;
+        readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>, v.CheckAction<string, undefined>]>;
+        readonly display: v.BooleanSchema<undefined>;
+        readonly created_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly updated_at: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>, v.MaxLengthAction<{
+        name: string;
+        source: string;
+        display: boolean;
+        created_at: number;
+        updated_at: number;
+    }[], 1000, undefined>]>;
+}, undefined>;
+export type ProjectAnnotationSnapshot = v.InferOutput<typeof schema>;
+export declare const snapshotGraph: (value: ProjectAnnotationSnapshot) => ProjectAnnotations;
+export declare const decodeProjectAnnotationSnapshot: (json: string) => ProjectAnnotationSnapshot;
+export declare const projectAnnotationSnapshotFingerprint: (json: string) => string;
+export {};

package/dist/store/project-transfer/snapshot-model.js

@@ -0,0 +1,92 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { PROJECT_ANNOTATIONS_MAX_BYTES, validateProjectAnnotationsGraph } from "./manifest.js";
+import { projectAnnotationsSchema } from "./schema.js";
+const text = (max) => v.pipe(v.string(), v.minLength(1), v.maxLength(max), v.check((s) => !!s.trim()));
+const timestamp = v.pipe(v.number(), v.safeInteger(), v.minValue(0));
+const schema = v.strictObject({
+    ...projectAnnotationsSchema.entries,
+    version: v.literal(2),
+    coverage: v.strictObject({
+        ...projectAnnotationsSchema.entries.coverage.entries,
+        meeting_memberships: v.literal("omitted"),
+        notes: v.literal("omitted"),
+    }),
+    project: v.strictObject({
+        ...projectAnnotationsSchema.entries.project.entries,
+        description: v.nullable(text(20000)),
+        status: v.nullable(text(200)),
+        owner: v.nullable(text(2048)),
+        updated_at: timestamp,
+        account_scope: v.literal("owner"),
+    }),
+    aliases: v.pipe(v.array(v.strictObject({
+        name: text(200),
+        source: text(200),
+        display: v.boolean(),
+        created_at: timestamp,
+        updated_at: timestamp,
+    })), v.maxLength(1000)),
+});
+export const snapshotGraph = (value) => ({
+    format: value.format,
+    version: 1,
+    project: {
+        ref: value.project.ref,
+        key: value.project.key,
+        name: value.project.name,
+        type: value.project.type,
+        scope: value.project.scope,
+        organization: value.project.organization,
+        created_at: value.project.created_at,
+    },
+    coverage: value.coverage,
+    aliases: value.aliases.map((alias) => alias.name),
+    facts: value.facts,
+    links: value.links,
+    external: value.external,
+});
+export const decodeProjectAnnotationSnapshot = (json) => {
+    const invalid = (field) => {
+        throw new CliError("validation_error", `invalid project annotation snapshot.${field}`);
+    };
+    if (typeof json !== "string" || Buffer.byteLength(json) > PROJECT_ANNOTATIONS_MAX_BYTES)
+        return invalid("bytes");
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch {
+        return invalid("json");
+    }
+    const checked = v.safeParse(schema, value);
+    if (!checked.success)
+        return invalid(checked.issues[0]?.path?.map((p) => String(p.key)).join(".") ?? "manifest");
+    const snapshot = checked.output;
+    if (snapshot.aliases.length + snapshot.facts.length + snapshot.links.length + snapshot.external.length > 1000)
+        return invalid("record budget");
+    if (snapshot.project.updated_at < snapshot.project.created_at)
+        return invalid("project.updated_at");
+    for (const alias of snapshot.aliases)
+        if (alias.updated_at < alias.created_at)
+            return invalid("aliases.updated_at");
+    for (const fact of snapshot.facts)
+        if (!fact.statement.trim())
+            return invalid("facts.statement");
+    validateProjectAnnotationsGraph(snapshotGraph(snapshot), snapshot.project.owner === null ? [] : [snapshot.project.owner]);
+    return snapshot;
+};
+export const projectAnnotationSnapshotFingerprint = (json) => {
+    const snapshot = decodeProjectAnnotationSnapshot(json);
+    const order = (a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0);
+    return createHash("sha256")
+        .update(JSON.stringify({
+        ...snapshot,
+        aliases: snapshot.aliases.toSorted((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+        facts: snapshot.facts.toSorted(order),
+        links: snapshot.links.toSorted(order),
+        external: snapshot.external.toSorted(order),
+    }))
+        .digest("hex");
+};

package/dist/store/project-transfer/snapshot.d.ts

@@ -0,0 +1,17 @@
+import { type ProjectAnnotationSnapshot } from "./snapshot-model.js";
+export type { ProjectAnnotationSnapshot } from "./snapshot-model.js";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint } from "./snapshot-model.js";
+export interface ProjectAnnotationSnapshotOptions {
+    source: string;
+    project: string;
+    env?: NodeJS.ProcessEnv;
+    maxReadBytes?: number;
+}
+export interface ProjectAnnotationSnapshotResult {
+    snapshot: ProjectAnnotationSnapshot;
+    fingerprint: string;
+    read_bytes: number;
+    records: number;
+}
+/** No source maintenance, source fetching or output-file publication belongs to a snapshot read. */
+export declare const snapshotProjectAnnotations: (options: ProjectAnnotationSnapshotOptions) => Promise<ProjectAnnotationSnapshotResult>;

package/dist/store/project-transfer/snapshot.js

@@ -0,0 +1,29 @@
+import { CliError } from "@wirecat/cli-base";
+import { openStoreContext } from "../sqlite/open-store.js";
+import { SnapshotBudget } from "../sqlite/project-transfer/budget.js";
+import { projectAnnotationSnapshot } from "../sqlite/project-transfer/snapshot.js";
+import { projectAnnotationSnapshotFingerprint } from "./snapshot-model.js";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint } from "./snapshot-model.js";
+/** No source maintenance, source fetching or output-file publication belongs to a snapshot read. */
+export const snapshotProjectAnnotations = async (options) => {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new CliError("validation_error", "snapshot options are required");
+    for (const field of Object.keys(options))
+        if (!["source", "project", "env", "maxReadBytes"].includes(field))
+            throw new CliError("validation_error", `unknown snapshot field ${field}`);
+    if (typeof options.source !== "string" || !options.source.trim() || options.source.length > 4096)
+        throw new CliError("validation_error", "snapshot source is an explicit existing store path");
+    if (typeof options.project !== "string" ||
+        !/^project:[1-9]\d*$/.test(options.project) ||
+        !Number.isSafeInteger(Number(options.project.slice(8))))
+        throw new CliError("validation_error", "snapshot project is a project:<safe integer id> reference");
+    const budget = new SnapshotBudget(options.maxReadBytes ?? 4 * 1024 * 1024);
+    const context = await openStoreContext({ path: options.source, env: options.env, readOnly: true });
+    try {
+        const result = projectAnnotationSnapshot(context.database, Number(options.project.slice(8)), budget);
+        return { ...result, fingerprint: projectAnnotationSnapshotFingerprint(JSON.stringify(result.snapshot)) };
+    }
+    finally {
+        context.database.close();
+    }
+};

package/dist/store/sqlite/project-transfer/budget.d.ts

@@ -0,0 +1,9 @@
+import type { CacheDatabase, SqlValue } from "../../driver.js";
+export declare class SnapshotBudget {
+    readonly maxBytes: number;
+    records: number;
+    bytes: number;
+    constructor(maxBytes: number);
+    reserve(records: number, bytes: number): void;
+    rows(database: CacheDatabase, from: string, fields: string[], parameters: SqlValue[]): void;
+}

package/dist/store/sqlite/project-transfer/budget.js

@@ -0,0 +1,27 @@
+import { CliError } from "@wirecat/cli-base";
+export class SnapshotBudget {
+    maxBytes;
+    records = 0;
+    bytes = 0;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 4 * 1024 * 1024)
+            throw new CliError("validation_error", "snapshot maxReadBytes takes 1–4194304 bytes");
+    }
+    reserve(records, bytes) {
+        if (!Number.isSafeInteger(records) ||
+            records < 0 ||
+            !Number.isSafeInteger(bytes) ||
+            bytes < 0 ||
+            this.records + records > 1000 ||
+            this.bytes + bytes > this.maxBytes)
+            throw new CliError("validation_error", "project annotation snapshot exceeds its record or input byte budget");
+        this.records += records;
+        this.bytes += bytes;
+    }
+    rows(database, from, fields, parameters) {
+        const bytes = fields.map((field) => `coalesce(length(CAST(${field} AS BLOB)),0)`).join("+");
+        const sized = database.prepare(`SELECT ${bytes} AS bytes ${from} LIMIT 1001`).all(...parameters);
+        this.reserve(sized.length, sized.reduce((sum, row) => sum + Number(row.bytes) + 128, 0));
+    }
+}

package/dist/store/sqlite/project-transfer/snapshot.d.ts

@@ -0,0 +1,78 @@
+import type { CacheDatabase } from "../../driver.js";
+import type { SnapshotBudget } from "./budget.js";
+export declare const projectAnnotationSnapshot: (database: CacheDatabase, projectId: number, budget: SnapshotBudget) => {
+    snapshot: {
+        format: "wirecat.project-annotations";
+        facts: {
+            ref: string;
+            type: "decision" | "fact" | "promise" | "question" | "statement";
+            statement: string;
+            status: "accepted" | "proposed" | "reversed" | "superseded";
+            subject: string | null;
+            occurred_at: number | null;
+            supersedes: string | null;
+            author: string;
+            model: string | null;
+            confirmed_by: string | null;
+            scope: "personal" | "work" | null;
+            source: string;
+            created_at: number;
+            updated_at: number;
+        }[];
+        links: {
+            ref: string;
+            from: string;
+            to: string | null;
+            kind: "about" | "answered-by" | "assigned-to" | "blocked-by" | "created-from" | "duplicate-of" | "evidence" | "follow-up-of" | "labelled" | "links-to" | "member-of" | "related-to";
+            origin: "file" | "message" | "owner" | "suggested";
+            anchor: string | null;
+            target_text: string | null;
+            role: string | null;
+            evidence: string | null;
+            confirmed: boolean;
+            provenance: string | null;
+            created_at: number;
+            updated_at: number;
+            author: string | null;
+        }[];
+        external: {
+            ref: string;
+            content_sha256: string | null;
+        }[];
+        version: 2;
+        coverage: {
+            aliases: "complete";
+            facts: "complete";
+            links: "complete";
+            memories: "omitted";
+            tasks: "omitted";
+            labels: "omitted";
+            findings: "omitted";
+            meeting_memberships: "omitted";
+            notes: "omitted";
+        };
+        project: {
+            ref: string;
+            key: string;
+            name: string;
+            type: "client" | "oss" | "other" | "personal" | "work";
+            scope: "personal" | "work";
+            organization: string | null;
+            created_at: number;
+            description: string | null;
+            status: string | null;
+            owner: string | null;
+            updated_at: number;
+            account_scope: "owner";
+        };
+        aliases: {
+            name: string;
+            source: string;
+            display: boolean;
+            created_at: number;
+            updated_at: number;
+        }[];
+    };
+    read_bytes: number;
+    records: number;
+};

package/dist/store/sqlite/project-transfer/snapshot.js

@@ -0,0 +1,183 @@
+import { CliError } from "@wirecat/cli-base";
+import { MIGRATIONS } from "../../migrations.js";
+import { decodeProjectAnnotationSnapshot } from "../../project-transfer/snapshot-model.js";
+import { read } from "../transaction.js";
+import { ProjectSnapshotSources } from "./sources.js";
+const unsupported = () => {
+    throw new CliError("configuration_error", "project snapshot has unsupported metadata, deletion or account scope");
+};
+const nullableText = (value) => (value === null ? null : String(value));
+const flag = (value) => {
+    if (value !== 0 && value !== 1)
+        return unsupported();
+    return value === 1;
+};
+const provenance = (raw) => {
+    if (raw === null)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(String(raw));
+    }
+    catch {
+        return unsupported();
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.keys(value).some((key) => key !== "provenance"))
+        return unsupported();
+    const text = value.provenance;
+    if (text !== undefined && text !== null && typeof text !== "string")
+        return unsupported();
+    return text ?? null;
+};
+export const projectAnnotationSnapshot = (database, projectId, budget) => read(database, () => {
+    if (database.prepare("SELECT max(version) AS version FROM schema_migrations").get()?.version !==
+        MIGRATIONS.at(-1)?.version)
+        throw new CliError("configuration_error", "project snapshots require the SDK's current store schema without source migration");
+    const sources = new ProjectSnapshotSources(database, budget);
+    const rows = (from, fields, params) => {
+        budget.rows(database, from, fields, params);
+        return database.prepare(`SELECT ${fields.join(",")} ${from} LIMIT 1001`).all(...params);
+    };
+    const descriptor = database.prepare("SELECT account_id,deleted_at FROM projects WHERE id=?").get(projectId);
+    if (!descriptor)
+        throw new CliError("not_found", "the source project does not exist");
+    if (descriptor.account_id !== null || descriptor.deleted_at !== null)
+        return unsupported();
+    const project = rows("FROM projects WHERE id=?", [
+        "id",
+        "key",
+        "name",
+        "description",
+        "type",
+        "scope",
+        "organization_id",
+        "owner_type",
+        "owner_id",
+        "status",
+        "created_at",
+        "updated_at",
+    ], [projectId])[0];
+    if (!project)
+        throw new CliError("not_found", "the source project does not exist");
+    const aliases = rows("FROM aliases WHERE aliasable_type='project' AND aliasable_id=? ORDER BY id", ["name", "source", "display", "account_id", "created_at", "updated_at"], [projectId]);
+    if (aliases.some((alias) => alias.account_id !== null))
+        return unsupported();
+    if (database
+        .prepare("SELECT 1 FROM facts WHERE project_id=? AND (metadata IS NOT NULL OR deleted_at IS NOT NULL) LIMIT 1")
+        .get(projectId))
+        return unsupported();
+    const facts = rows("FROM facts WHERE project_id=? ORDER BY id", [
+        "id",
+        "type",
+        "statement",
+        "status",
+        "subject_type",
+        "subject_id",
+        "occurred_at",
+        "supersedes_id",
+        "author_type",
+        "author_id",
+        "model",
+        "confirmed_by_type",
+        "confirmed_by_id",
+        "scope",
+        "source",
+        "created_at",
+        "updated_at",
+    ], [projectId]);
+    const links = rows("FROM links WHERE (from_type='project' AND from_id=?) OR (to_type='project' AND to_id=?) OR " +
+        "(from_type='fact' AND from_id IN (SELECT id FROM facts WHERE project_id=?)) OR " +
+        "(to_type='fact' AND to_id IN (SELECT id FROM facts WHERE project_id=?)) ORDER BY id", [
+        "id",
+        "from_type",
+        "from_id",
+        "to_type",
+        "to_id",
+        "kind",
+        "anchor",
+        "source",
+        "target_text",
+        "role",
+        "evidence",
+        "metadata",
+        "confirmed",
+        "author",
+        "created_at",
+        "updated_at",
+    ], [projectId, projectId, projectId, projectId]);
+    const projectRef = `project:${projectId}`;
+    const owned = new Set([projectRef, ...facts.map((row) => `fact:${row.id}`)]);
+    const data = {
+        format: "wirecat.project-annotations",
+        version: 2,
+        project: {
+            ref: projectRef,
+            key: project.key,
+            name: project.name,
+            type: project.type,
+            scope: project.scope,
+            organization: project.organization_id === null ? null : sources.ref("organization", project.organization_id),
+            created_at: project.created_at,
+            description: project.description,
+            status: project.status,
+            owner: sources.ref(project.owner_type, project.owner_id),
+            updated_at: project.updated_at,
+            account_scope: "owner",
+        },
+        coverage: {
+            aliases: "complete",
+            facts: "complete",
+            links: "complete",
+            memories: "omitted",
+            tasks: "omitted",
+            labels: "omitted",
+            findings: "omitted",
+            meeting_memberships: "omitted",
+            notes: "omitted",
+        },
+        aliases: aliases.map((row) => ({
+            name: row.name,
+            source: row.source,
+            display: flag(row.display),
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        })),
+        facts: facts.map((row) => ({
+            ref: `fact:${row.id}`,
+            type: row.type,
+            statement: row.statement,
+            status: row.status,
+            subject: sources.ref(row.subject_type, row.subject_id),
+            occurred_at: row.occurred_at,
+            supersedes: row.supersedes_id === null ? null : sources.ref("fact", row.supersedes_id),
+            author: sources.ref(row.author_type, row.author_id),
+            model: row.model,
+            confirmed_by: sources.ref(row.confirmed_by_type, row.confirmed_by_id),
+            scope: row.scope,
+            source: row.source,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        })),
+        links: links.map((row) => ({
+            ref: `link:${row.id}`,
+            from: sources.ref(row.from_type, row.from_id),
+            to: sources.ref(row.to_type, row.to_id),
+            kind: row.kind,
+            origin: row.source,
+            anchor: nullableText(row.anchor),
+            target_text: nullableText(row.target_text),
+            role: nullableText(row.role),
+            evidence: nullableText(row.evidence),
+            confirmed: flag(row.confirmed),
+            provenance: provenance(row.metadata),
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+            author: nullableText(row.author),
+        })),
+    };
+    const snapshot = decodeProjectAnnotationSnapshot(JSON.stringify({ ...data, external: sources.external(owned) }));
+    return { snapshot, read_bytes: budget.bytes, records: budget.records };
+});

package/dist/store/sqlite/project-transfer/sources.d.ts

@@ -0,0 +1,18 @@
+import type { CacheDatabase } from "../../driver.js";
+import { type Thing } from "../things.js";
+import type { SnapshotBudget } from "./budget.js";
+export declare class ProjectSnapshotSources {
+    private readonly database;
+    private readonly budget;
+    readonly references: Map<string, Thing>;
+    private readonly byThing;
+    constructor(database: CacheDatabase, budget: SnapshotBudget);
+    ref(type: unknown, id: unknown): string | null;
+    external(owned: Set<string>): {
+        ref: string;
+        content_sha256: string | null;
+    }[];
+    private fingerprint;
+    private transcript;
+    private digest;
+}

package/dist/store/sqlite/project-transfer/sources.js

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import { referenceOfThing, storedThing } from "../things.js";
+const invalid = () => {
+    throw new CliError("configuration_error", "project snapshot has an unavailable or unsupported dependency");
+};
+const scalar = new Set([
+    "person",
+    "bot",
+    "organization",
+    "project",
+    "fact",
+    "memory",
+    "task",
+    "note",
+    "document",
+    "message",
+    "email",
+    "chat",
+    "identity",
+    "account",
+    "meeting",
+    "meeting_transcript",
+    "meeting_transcript_row",
+]);
+const noText = new Set(["person", "bot", "organization", "project", "chat", "identity", "account"]);
+const texts = {
+    document: {
+        table: "documents",
+        fields: ["n.title", "n.body"],
+        where: "n.deleted_at IS NULL AND n.body IS NOT NULL AND CASE WHEN json_valid(n.metadata) THEN coalesce(json_extract(n.metadata,'$.catalog.active'),1) ELSE 1 END=1",
+    },
+    note: { table: "notes", fields: ["n.title", "n.body"], where: "n.deleted_at IS NULL" },
+    message: {
+        table: "messages",
+        fields: ["n.text", "n.sent_at", "n.sender_name", "n.sender_chat_external_id", "i.provider", "i.external_id"],
+        join: "LEFT JOIN identities i ON i.id=n.sender_identity_id",
+        where: "n.deleted_at IS NULL",
+    },
+    email: {
+        table: "emails",
+        fields: ["n.subject", "coalesce(n.body_text,'')", "n.sent_at", "n.from_address", "n.from_name"],
+        where: "n.deleted_at IS NULL",
+    },
+    meeting: {
+        table: "meetings",
+        fields: ["n.title", "n.description", "n.location", "n.started_at", "n.ended_at", "n.duration_ms", "n.timezone"],
+        where: "n.deleted_at IS NULL",
+    },
+    meeting_transcript_row: {
+        table: "meeting_transcript_rows",
+        fields: ["n.position", "n.start_ms", "n.end_ms", "n.speaker_name", "n.text"],
+        join: "JOIN meeting_transcripts t ON t.id=n.meeting_transcript_id JOIN meetings m ON m.id=t.meeting_id",
+        where: "t.deleted_at IS NULL AND m.deleted_at IS NULL",
+    },
+};
+export class ProjectSnapshotSources {
+    database;
+    budget;
+    references = new Map();
+    byThing = new Map();
+    constructor(database, budget) {
+        this.database = database;
+        this.budget = budget;
+    }
+    ref(type, id) {
+        if (type === null && id === null)
+            return null;
+        if (typeof type !== "string" || !scalar.has(type) || typeof id !== "number" || !Number.isSafeInteger(id) || id < 1)
+            return invalid();
+        const key = `${type}:${id}`, cached = this.byThing.get(key);
+        if (cached)
+            return cached;
+        if (type === "project" || type === "organization") {
+            const table = type === "project" ? "projects" : "organizations";
+            if (!this.database.prepare(`SELECT 1 FROM ${table} WHERE id=? AND deleted_at IS NULL`).get(id))
+                return invalid();
+        }
+        const identifier = {
+            message: [
+                "FROM messages n JOIN chats c ON c.id=n.chat_id JOIN accounts a ON a.id=n.account_id WHERE n.id=?",
+                ["n.external_id", "c.external_id", "a.external_id", "a.provider"],
+            ],
+            email: [
+                "FROM emails n JOIN email_threads c ON c.id=n.email_thread_id JOIN accounts a ON a.id=n.account_id WHERE n.id=?",
+                ["n.external_id", "c.external_id", "a.external_id", "a.provider"],
+            ],
+            chat: [
+                "FROM chats n JOIN accounts a ON a.id=n.account_id WHERE n.id=?",
+                ["n.external_id", "a.external_id", "a.provider"],
+            ],
+            identity: ["FROM identities n WHERE n.id=?", ["n.external_id", "n.provider"]],
+        };
+        const selection = identifier[type];
+        if (selection)
+            this.budget.rows(this.database, selection[0], [...selection[1]], [id]);
+        const thing = storedThing(type, id), ref = referenceOfThing(this.database, thing);
+        if (!ref)
+            return invalid();
+        this.byThing.set(key, ref);
+        this.references.set(ref, thing);
+        return ref;
+    }
+    external(owned) {
+        return [...this.references]
+            .filter(([ref]) => !owned.has(ref))
+            .map(([ref, thing]) => ({
+            ref,
+            content_sha256: this.fingerprint(thing),
+        }));
+    }
+    fingerprint(thing) {
+        this.budget.reserve(1, 128);
+        if (noText.has(thing.type))
+            return null;
+        if (thing.type === "meeting_transcript")
+            return this.transcript(thing.id);
+        const spec = texts[thing.type];
+        if (!spec)
+            return invalid();
+        const from = `FROM ${spec.table} n ${spec.join ?? ""} WHERE n.id=? AND ${spec.where}`;
+        this.budget.rows(this.database, from, spec.fields, [thing.id]);
+        const row = this.database
+            .prepare(`SELECT ${spec.fields.map((f, i) => `${f} AS v${i}`).join(",")} ${from}`)
+            .get(thing.id);
+        if (!row)
+            return invalid();
+        return this.digest(thing.type, spec.fields.map((_f, i) => row[`v${i}`]));
+    }
+    transcript(id) {
+        const from = "FROM meeting_transcripts n JOIN meetings m ON m.id=n.meeting_id WHERE n.id=? AND n.deleted_at IS NULL AND m.deleted_at IS NULL";
+        this.budget.rows(this.database, from, ["n.format", "n.language", "n.source"], [id]);
+        const header = this.database.prepare(`SELECT n.format,n.language,n.source ${from}`).get(id);
+        if (!header)
+            return invalid();
+        const rows = "FROM meeting_transcript_rows n WHERE n.meeting_transcript_id=?";
+        this.budget.rows(this.database, rows, ["n.position", "n.start_ms", "n.end_ms", "n.speaker_name", "n.text"], [id]);
+        const cues = this.database
+            .prepare(`SELECT n.position,n.start_ms,n.end_ms,n.speaker_name,n.text ${rows} ORDER BY n.position LIMIT 1001`)
+            .all(id);
+        return this.digest("meeting_transcript", [header, cues]);
+    }
+    digest(kind, content) {
+        return createHash("sha256")
+            .update(JSON.stringify(["wirecat.project-source", 1, kind, content]))
+            .digest("hex");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.372.0",
+  "version": "0.373.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",