@wirecat/cli-core 0.372.0 → 0.374.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ shape of this file.
 
 ## Unreleased
 
+## 0.374.0 — 20.10.2026
+
+### Added
+
+- **`readBoundedUtf8File` from `./files`** preflights ordinary-file size, bounds reads even if the input grows,
+  and refuses invalid UTF-8. Snapshot hosts can share this reader and `projectAnnotationSnapshotSchema`
+  from `./store` for transport validation; graph validation still uses the snapshot decoder.
+- **The optional `store.projectAnnotations` port** previews and atomically restores selected version-2
+  annotations into an empty selected target. Restore requires the exact preview fingerprint, rechecks
+  references and namespace under the write lock, preserves historical state and rolls back on failure.
+  It never opens or migrates another store. Hosts must enforce owner authorization; no CLI/MCP mutation
+  host or live reset is included, and omitted facets remain outside this selected format.
+- **`previewProjectAnnotationSnapshot` from `./store`** reads an explicit existing destination natively
+  read-only and checks version-2 bindings against its actual content hashes, selected annotations and
+  project vocabulary. It reports descriptor/namespace conflicts and a preview fingerprint in one coherent
+  bounded read. It neither restores annotations nor authorizes a write.
+- **`planProjectAnnotationSnapshot` from `./store`** validates explicit bindings for version-2 snapshots,
+  including the project's owner, and binds preserved alias/project metadata to the preview fingerprint.
+  Version-1 planning keeps its existing contract. This pure helper opens no store and does not apply records.
+
+## 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/files/bounded-utf8.d.ts

@@ -0,0 +1,4 @@
+/** Preflight size, bound growing input too, and refuse replacement characters in structured input. */
+export declare const readBoundedUtf8File: (path: string, { maxBytes }: {
+    maxBytes: number;
+}) => Promise<string>;

package/dist/files/bounded-utf8.js

@@ -0,0 +1,32 @@
+import { CliError } from "@wirecat/cli-base";
+import { openOrdinaryFile } from "./ordinary-file.js";
+/** Preflight size, bound growing input too, and refuse replacement characters in structured input. */
+export const readBoundedUtf8File = async (path, { maxBytes }) => {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 16 * 1024 * 1024)
+        throw new CliError("validation_error", "file maxBytes takes 1–16777216 bytes");
+    const file = await openOrdinaryFile(path);
+    try {
+        if ((await file.stat()).size > maxBytes)
+            throw new CliError("validation_error", "input file exceeds its byte budget");
+        const chunks = [], buffer = Buffer.alloc(Math.min(65536, maxBytes + 1));
+        let bytes = 0;
+        for (;;) {
+            const { bytesRead } = await file.read(buffer, 0, Math.min(buffer.length, maxBytes - bytes + 1), null);
+            if (bytesRead === 0)
+                break;
+            bytes += bytesRead;
+            if (bytes > maxBytes)
+                throw new CliError("validation_error", "input file exceeds its byte budget");
+            chunks.push(Buffer.from(buffer.subarray(0, bytesRead)));
+        }
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks, bytes));
+        }
+        catch {
+            throw new CliError("validation_error", "input file must contain valid UTF-8");
+        }
+    }
+    finally {
+        await file.close();
+    }
+};

package/dist/files/index.d.ts

@@ -1,4 +1,5 @@
 export { type AtomicWriteOptions, writeFileAtomic } from "./atomic-write.js";
+export { readBoundedUtf8File } from "./bounded-utf8.js";
 export { acquireLock, type FileLock } from "./lock.js";
 export type { NativeWriterLeaseLayout } from "./native-writer-lease.js";
 export { nativeWriterLeaseStore } from "./native-writer-lease.js";

package/dist/files/index.js

@@ -1,4 +1,5 @@
 export { writeFileAtomic } from "./atomic-write.js";
+export { readBoundedUtf8File } from "./bounded-utf8.js";
 export { acquireLock } from "./lock.js";
 export { nativeWriterLeaseStore } from "./native-writer-lease.js";
 export { openOrdinaryFile, sameOrdinaryFile, syncDirectory } from "./ordinary-file.js";

package/dist/store/index.d.ts

@@ -16,6 +16,10 @@ 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 { type ProjectAnnotationPreview, type ProjectAnnotationPreviewOptions, previewProjectAnnotationSnapshot, } from "./project-transfer/preview.js";
+export { decodeProjectAnnotationSnapshot, type ProjectAnnotationSnapshot, type ProjectAnnotationSnapshotOptions, type ProjectAnnotationSnapshotResult, projectAnnotationSnapshotFingerprint, projectAnnotationSnapshotSchema, snapshotProjectAnnotations, } from "./project-transfer/snapshot.js";
+export { planProjectAnnotationSnapshot } from "./project-transfer/snapshot-plan.js";
+export type { ProjectAnnotationRestoreReceipt, ProjectAnnotationRestoreRequest, ProjectAnnotationStore, ProjectAnnotationTargetRequest, } from "./project-transfer/store.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,9 @@ 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 { previewProjectAnnotationSnapshot, } from "./project-transfer/preview.js";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint, projectAnnotationSnapshotSchema, snapshotProjectAnnotations, } from "./project-transfer/snapshot.js";
+export { planProjectAnnotationSnapshot } from "./project-transfer/snapshot-plan.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/plan.d.ts

@@ -23,6 +23,23 @@ export interface ProjectAnnotationsPlan {
     }[];
     ready: boolean;
 }
+export declare const projectAnnotationBindingSources: (manifest: {
+    project: {
+        ref: string;
+    };
+    external: {
+        ref: string;
+    }[];
+}, bindings: Record<string, string>) => Set<string>;
+export declare const planBoundProjectAnnotations: (manifest: {
+    project: {
+        ref: string;
+    };
+    external: {
+        ref: string;
+        content_sha256: string | null;
+    }[];
+}, manifest_fingerprint: string, target: ProjectAnnotationsTarget, bindings: Record<string, string>) => ProjectAnnotationsPlan;
 /** Pure planning over an adapter's complete target snapshot; a ready plan is not write authorization. */
 export declare const planProjectAnnotations: (json: string, target: ProjectAnnotationsTarget, bindings: Record<string, string>) => ProjectAnnotationsPlan;
 export {};

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

@@ -26,12 +26,7 @@ const kind = (ref) => {
 const invalid = (field) => {
     throw new CliError("validation_error", `invalid project annotation plan.${field}`);
 };
-/** Pure planning over an adapter's complete target snapshot; a ready plan is not write authorization. */
-export const planProjectAnnotations = (json, target, bindings) => {
-    const manifest = decodeProjectAnnotations(json);
-    const checked = v.safeParse(targetSchema, target);
-    if (!checked.success)
-        return invalid(checked.issues[0]?.path?.map((p) => String(p.key)).join(".") ?? "target");
+export const projectAnnotationBindingSources = (manifest, bindings) => {
     if (!bindings || typeof bindings !== "object" || Array.isArray(bindings) || Object.keys(bindings).length > 1001)
         return invalid("bindings");
     if (Object.getPrototypeOf(bindings) !== Object.prototype && Object.getPrototypeOf(bindings) !== null)
@@ -40,6 +35,21 @@ export const planProjectAnnotations = (json, target, bindings) => {
     for (const [source, destination] of Object.entries(bindings))
         if (!required.has(source) || typeof destination !== "string" || destination.length > 2048)
             return invalid("bindings");
+    for (const destination of Object.values(bindings)) {
+        try {
+            kind(destination);
+        }
+        catch {
+            return invalid("bindings.reference");
+        }
+    }
+    return required;
+};
+export const planBoundProjectAnnotations = (manifest, manifest_fingerprint, target, bindings) => {
+    const checked = v.safeParse(targetSchema, target);
+    if (!checked.success)
+        return invalid(checked.issues[0]?.path?.map((p) => String(p.key)).join(".") ?? "target");
+    const required = projectAnnotationBindingSources(manifest, bindings);
     const destinations = new Map();
     for (const item of checked.output.external) {
         try {
@@ -84,7 +94,6 @@ export const planProjectAnnotations = (json, target, bindings) => {
     }
     if (target.annotation_count > 0)
         conflicts.push({ reference: target.project, reason: "populated" });
-    const manifest_fingerprint = projectAnnotationsFingerprint(json);
     const fingerprint = createHash("sha256")
         .update(JSON.stringify({
         manifest_fingerprint,
@@ -104,3 +113,5 @@ export const planProjectAnnotations = (json, target, bindings) => {
         ready: missing_bindings.length === 0 && conflicts.length === 0,
     };
 };
+/** Pure planning over an adapter's complete target snapshot; a ready plan is not write authorization. */
+export const planProjectAnnotations = (json, target, bindings) => planBoundProjectAnnotations(decodeProjectAnnotations(json), projectAnnotationsFingerprint(json), target, bindings);

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

@@ -0,0 +1,11 @@
+import type { ProjectAnnotationPreview } from "./snapshot-plan.js";
+export type { ProjectAnnotationPreview } from "./snapshot-plan.js";
+export interface ProjectAnnotationPreviewOptions {
+    snapshot: string;
+    target: string;
+    project: string;
+    bindings: Record<string, string>;
+    maxReadBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare const previewProjectAnnotationSnapshot: (options: ProjectAnnotationPreviewOptions) => Promise<ProjectAnnotationPreview>;

package/dist/store/project-transfer/preview.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 { previewAnnotationSnapshot } from "../sqlite/project-transfer/preview.js";
+import { projectAnnotationBindingSources } from "./plan.js";
+import { decodeProjectAnnotationSnapshot } from "./snapshot-model.js";
+export const previewProjectAnnotationSnapshot = async (options) => {
+    if (!options || typeof options !== "object" || Array.isArray(options))
+        throw new CliError("validation_error", "project preview options are required");
+    for (const field of Object.keys(options))
+        if (!["snapshot", "target", "project", "bindings", "maxReadBytes", "env"].includes(field))
+            throw new CliError("validation_error", `unknown project preview field ${field}`);
+    const snapshot = decodeProjectAnnotationSnapshot(options.snapshot);
+    projectAnnotationBindingSources(snapshot, options.bindings);
+    if (typeof options.target !== "string" || !options.target.trim() || options.target.length > 4096)
+        throw new CliError("validation_error", "project preview target 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", "project preview project is a project:<safe integer id> reference");
+    const budget = new SnapshotBudget(options.maxReadBytes ?? 4 * 1024 * 1024);
+    const context = await openStoreContext({ path: options.target, env: options.env, readOnly: true });
+    try {
+        return previewAnnotationSnapshot(context.database, Number(options.project.slice(8)), snapshot, options.bindings, budget);
+    }
+    finally {
+        context.database.close();
+    }
+};

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

@@ -0,0 +1,76 @@
+import type { ProjectAnnotationTargetRequest } from "./store.js";
+export declare const projectAnnotationRequest: (request: ProjectAnnotationTargetRequest, restore?: boolean) => {
+    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;
+        }[];
+    };
+    projectId: number;
+};

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

@@ -0,0 +1,22 @@
+import { CliError } from "@wirecat/cli-base";
+import { projectAnnotationBindingSources } from "./plan.js";
+import { decodeProjectAnnotationSnapshot } from "./snapshot-model.js";
+export const projectAnnotationRequest = (request, restore = false) => {
+    if (!request || typeof request !== "object" || Array.isArray(request))
+        throw new CliError("validation_error", "project annotation request is required");
+    const fields = ["snapshot", "project", "bindings", "maxReadBytes", ...(restore ? ["fingerprint"] : [])];
+    for (const field of Object.keys(request))
+        if (!fields.includes(field))
+            throw new CliError("validation_error", `unknown project annotation field ${field}`);
+    const snapshot = decodeProjectAnnotationSnapshot(request.snapshot);
+    projectAnnotationBindingSources(snapshot, request.bindings);
+    if (typeof request.project !== "string" ||
+        !/^project:[1-9]\d*$/.test(request.project) ||
+        !Number.isSafeInteger(Number(request.project.slice(8))))
+        throw new CliError("validation_error", "project annotation project is a project:<safe integer id> reference");
+    if (restore &&
+        (typeof request.fingerprint !== "string" ||
+            !/^[a-f0-9]{64}$/.test(request.fingerprint)))
+        throw new CliError("validation_error", "project annotation fingerprint is required");
+    return { snapshot, projectId: Number(request.project.slice(8)) };
+};

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

@@ -0,0 +1,117 @@
+import * as v from "valibot";
+import { type ProjectAnnotations } from "./schema.js";
+export declare const projectAnnotationSnapshotSchema: 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>]>, undefined>;
+        readonly status: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>;
+        readonly owner: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, 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>]>;
+        readonly source: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, 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 projectAnnotationSnapshotSchema>;
+export declare const snapshotGraph: (value: ProjectAnnotationSnapshot) => ProjectAnnotations;
+export declare const decodeProjectAnnotationSnapshot: (json: string) => ProjectAnnotationSnapshot;
+export declare const projectAnnotationSnapshotFingerprint: (json: string) => string;

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

@@ -0,0 +1,99 @@
+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));
+const timestamp = v.pipe(v.number(), v.safeInteger(), v.minValue(0));
+export const projectAnnotationSnapshotSchema = 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(projectAnnotationSnapshotSchema, 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");
+    for (const field of ["description", "status", "owner"])
+        if (snapshot.project[field] !== null && !snapshot.project[field].trim())
+            return invalid(`project.${field}`);
+    for (const alias of snapshot.aliases)
+        for (const field of ["name", "source"])
+            if (!alias[field].trim())
+                return invalid(`aliases.${field}`);
+    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-plan.d.ts

@@ -0,0 +1,12 @@
+import { type ProjectAnnotationsPlan, type ProjectAnnotationsTarget } from "./plan.js";
+export interface ProjectAnnotationPreview {
+    plan: ProjectAnnotationsPlan;
+    descriptor_conflicts: ("key" | "name")[];
+    namespace_conflicts: string[];
+    ready: boolean;
+    fingerprint: string;
+    read_bytes: number;
+    records: number;
+}
+/** Metadata and project-owner bindings participate in the version-2 preview fingerprint. */
+export declare const planProjectAnnotationSnapshot: (json: string, target: ProjectAnnotationsTarget, bindings: Record<string, string>) => ProjectAnnotationsPlan;

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

@@ -0,0 +1,4 @@
+import { planBoundProjectAnnotations } from "./plan.js";
+import { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint } from "./snapshot-model.js";
+/** Metadata and project-owner bindings participate in the version-2 preview fingerprint. */
+export const planProjectAnnotationSnapshot = (json, target, bindings) => planBoundProjectAnnotations(decodeProjectAnnotationSnapshot(json), projectAnnotationSnapshotFingerprint(json), target, bindings);

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, projectAnnotationSnapshotSchema, } 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>;