@wirecat/cli-core 0.373.0 → 0.374.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ 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

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,7 +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 { decodeProjectAnnotationSnapshot, type ProjectAnnotationSnapshot, type ProjectAnnotationSnapshotOptions, type ProjectAnnotationSnapshotResult, projectAnnotationSnapshotFingerprint, snapshotProjectAnnotations, } from "./project-transfer/snapshot.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,7 +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 { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint, snapshotProjectAnnotations, } from "./project-transfer/snapshot.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/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

@@ -1,6 +1,6 @@
 import * as v from "valibot";
 import { type ProjectAnnotations } from "./schema.js";
-declare const schema: v.StrictObjectSchema<{
+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>]>;
@@ -91,15 +91,15 @@ declare const schema: v.StrictObjectSchema<{
         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 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>, 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 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>]>;
@@ -111,8 +111,7 @@ declare const schema: v.StrictObjectSchema<{
         updated_at: number;
     }[], 1000, undefined>]>;
 }, undefined>;
-export type ProjectAnnotationSnapshot = v.InferOutput<typeof schema>;
+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;
-export {};

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

@@ -3,9 +3,9 @@ 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 text = (max) => v.pipe(v.string(), v.minLength(1), v.maxLength(max));
 const timestamp = v.pipe(v.number(), v.safeInteger(), v.minValue(0));
-const schema = v.strictObject({
+export const projectAnnotationSnapshotSchema = v.strictObject({
     ...projectAnnotationsSchema.entries,
     version: v.literal(2),
     coverage: v.strictObject({
@@ -60,12 +60,19 @@ export const decodeProjectAnnotationSnapshot = (json) => {
     catch {
         return invalid("json");
     }
-    const checked = v.safeParse(schema, value);
+    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)

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

@@ -1,6 +1,6 @@
 import { type ProjectAnnotationSnapshot } from "./snapshot-model.js";
 export type { ProjectAnnotationSnapshot } from "./snapshot-model.js";
-export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint } from "./snapshot-model.js";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint, projectAnnotationSnapshotSchema, } from "./snapshot-model.js";
 export interface ProjectAnnotationSnapshotOptions {
     source: string;
     project: string;

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

@@ -3,7 +3,7 @@ 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";
+export { decodeProjectAnnotationSnapshot, projectAnnotationSnapshotFingerprint, projectAnnotationSnapshotSchema, } 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))

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

@@ -0,0 +1,25 @@
+import type { ProjectAnnotationPreview } from "./snapshot-plan.js";
+export interface ProjectAnnotationTargetRequest {
+    snapshot: string;
+    project: string;
+    bindings: Record<string, string>;
+    maxReadBytes?: number;
+}
+export interface ProjectAnnotationRestoreRequest extends ProjectAnnotationTargetRequest {
+    fingerprint: string;
+}
+export interface ProjectAnnotationRestoreReceipt {
+    project: string;
+    fingerprint: string;
+    mappings: Record<string, string>;
+    counts: {
+        aliases: number;
+        facts: number;
+        links: number;
+    };
+}
+/** Hosts authorize restore before calling; historical accepted state is not a new agent decision. */
+export interface ProjectAnnotationStore {
+    preview(request: ProjectAnnotationTargetRequest): Promise<ProjectAnnotationPreview>;
+    restore(request: ProjectAnnotationRestoreRequest): Promise<ProjectAnnotationRestoreReceipt>;
+}

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

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

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

@@ -0,0 +1,12 @@
+import type { CacheDatabase } from "../../driver.js";
+import { type ProjectAnnotationSnapshot } from "../../project-transfer/snapshot-model.js";
+import type { SnapshotBudget } from "./budget.js";
+export declare const previewAnnotationSnapshot: (database: CacheDatabase, projectId: number, manifest: ProjectAnnotationSnapshot, bindings: Record<string, string>, budget: SnapshotBudget) => {
+    plan: import("../../index.js").ProjectAnnotationsPlan;
+    descriptor_conflicts: ("key" | "name")[];
+    namespace_conflicts: string[];
+    ready: boolean;
+    fingerprint: string;
+    read_bytes: number;
+    records: number;
+};

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

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { normalizeVocabularyName } from "../../../domain/vocabulary.js";
+import { projectAnnotationSnapshotFingerprint, } from "../../project-transfer/snapshot-model.js";
+import { planProjectAnnotationSnapshot } from "../../project-transfer/snapshot-plan.js";
+import { thingOf } from "../things.js";
+import { read } from "../transaction.js";
+import { projectAnnotationSnapshot } from "./snapshot.js";
+import { ProjectSnapshotSources } from "./sources.js";
+export const previewAnnotationSnapshot = (database, projectId, manifest, bindings, budget) => read(database, () => {
+    const current = projectAnnotationSnapshot(database, projectId, budget).snapshot;
+    const sources = new ProjectSnapshotSources(database, budget);
+    for (const ref of new Set(Object.values(bindings))) {
+        if (ref === current.project.ref)
+            continue;
+        const thing = thingOf(database, ref);
+        if (thing)
+            sources.ref(thing.type, thing.id);
+    }
+    const external = sources.external(new Set([current.project.ref]));
+    const projectFields = ["id", "key", "name", "account_id", "deleted_at"];
+    const aliasFields = ["aliasable_id", "name", "account_id"];
+    const projectFrom = "FROM projects ORDER BY id";
+    const aliasFrom = "FROM aliases WHERE aliasable_type='project' ORDER BY id";
+    budget.rows(database, projectFrom, projectFields, []);
+    budget.rows(database, aliasFrom, aliasFields, []);
+    const projects = database.prepare(`SELECT ${projectFields.join(",")} ${projectFrom} LIMIT 1001`).all();
+    const aliases = database.prepare(`SELECT ${aliasFields.join(",")} ${aliasFrom} LIMIT 1001`).all();
+    const names = new Set([manifest.project.key, manifest.project.name, ...manifest.aliases.map((a) => a.name)].map(normalizeVocabularyName));
+    const namespace = new Set();
+    for (const project of projects) {
+        if (project.id === projectId)
+            continue;
+        const keyMatches = names.has(normalizeVocabularyName(String(project.key)));
+        const nameMatches = project.account_id === null &&
+            project.deleted_at === null &&
+            names.has(normalizeVocabularyName(String(project.name)));
+        if (keyMatches || nameMatches)
+            namespace.add(`project:${project.id}`);
+    }
+    for (const alias of aliases) {
+        if (alias.aliasable_id === projectId || alias.account_id !== null)
+            continue;
+        const project = projects.find((p) => p.id === alias.aliasable_id && p.account_id === null && p.deleted_at === null);
+        if (project && names.has(normalizeVocabularyName(String(alias.name))))
+            namespace.add(`project:${project.id}`);
+    }
+    const descriptor_conflicts = ["key", "name"].filter((field) => current.project[field] !== manifest.project[field]);
+    const target = {
+        project: current.project.ref,
+        annotation_count: current.aliases.length + current.facts.length + current.links.length,
+        revision_sha256: createHash("sha256")
+            .update(JSON.stringify({
+            snapshot: projectAnnotationSnapshotFingerprint(JSON.stringify(current)),
+            projects,
+            aliases,
+            external: external.toSorted((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0)),
+        }))
+            .digest("hex"),
+        external,
+    };
+    const plan = planProjectAnnotationSnapshot(JSON.stringify(manifest), target, bindings);
+    const namespace_conflicts = [...namespace].sort();
+    return {
+        plan,
+        descriptor_conflicts,
+        namespace_conflicts,
+        ready: plan.ready && descriptor_conflicts.length === 0 && namespace_conflicts.length === 0,
+        fingerprint: createHash("sha256")
+            .update(JSON.stringify({ plan: plan.fingerprint, descriptor_conflicts, namespace_conflicts }))
+            .digest("hex"),
+        read_bytes: budget.bytes,
+        records: budget.records,
+    };
+});

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

@@ -0,0 +1,5 @@
+import type { CacheDatabase } from "../../driver.js";
+import type { ProjectAnnotationSnapshot } from "../../project-transfer/snapshot-model.js";
+export declare const restoreAnnotationRecords: (database: CacheDatabase, projectId: number, snapshot: ProjectAnnotationSnapshot, bindings: Record<string, string>) => {
+    [x: string]: string;
+};

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

@@ -0,0 +1,53 @@
+import { CliError } from "@wirecat/cli-base";
+import { fold } from "../../normalize.js";
+import { thingOf } from "../things.js";
+export const restoreAnnotationRecords = (database, projectId, snapshot, bindings) => {
+    const mappings = { ...bindings };
+    const resolve = (ref) => {
+        if (ref === null)
+            return null;
+        const mapped = mappings[ref], thing = mapped === undefined ? undefined : thingOf(database, mapped);
+        if (!thing)
+            throw new CliError("validation_error", "project annotation binding became unavailable");
+        return thing;
+    };
+    const organization = resolve(snapshot.project.organization), owner = resolve(snapshot.project.owner);
+    database
+        .prepare("UPDATE projects SET description=?,type=?,scope=?,organization_id=?,owner_type=?,owner_id=?,status=?,created_at=?,updated_at=? WHERE id=?")
+        .run(snapshot.project.description, snapshot.project.type, snapshot.project.scope, organization?.id ?? null, owner?.type ?? null, owner?.id ?? null, snapshot.project.status, snapshot.project.created_at, snapshot.project.updated_at, projectId);
+    for (const alias of snapshot.aliases)
+        database
+            .prepare("INSERT INTO aliases(aliasable_type,aliasable_id,account_id,name,name_folded,display,source,created_at,updated_at) VALUES('project',?,NULL,?,?,?,?,?,?)")
+            .run(projectId, alias.name, fold(alias.name), Number(alias.display), alias.source, alias.created_at, alias.updated_at);
+    for (const fact of snapshot.facts) {
+        const author = resolve(fact.author), confirmed = resolve(fact.confirmed_by);
+        if (!author)
+            throw new CliError("validation_error", "project annotation author is required");
+        const row = database
+            .prepare("INSERT INTO facts(type,statement,status,project_id,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) VALUES(?,?,?,?,NULL,NULL,?,NULL,?,?,?,?,?,?,?,?,?) RETURNING id")
+            .get(fact.type, fact.statement, fact.status, projectId, fact.occurred_at, author.type, author.id, fact.model, confirmed?.type ?? null, confirmed?.id ?? null, fact.scope, fact.source, fact.created_at, fact.updated_at);
+        if (!row)
+            throw new CliError("configuration_error", "project annotation fact insertion failed");
+        mappings[fact.ref] = `fact:${row.id}`;
+    }
+    for (const fact of snapshot.facts) {
+        const subject = resolve(fact.subject), previous = resolve(fact.supersedes), target = resolve(fact.ref);
+        if (!target)
+            throw new CliError("configuration_error", "project annotation fact mapping is missing");
+        database
+            .prepare("UPDATE facts SET subject_type=?,subject_id=?,supersedes_id=? WHERE id=?")
+            .run(subject?.type ?? null, subject?.id ?? null, previous?.id ?? null, target.id);
+    }
+    for (const link of snapshot.links) {
+        const from = resolve(link.from), to = resolve(link.to);
+        if (!from)
+            throw new CliError("validation_error", "project annotation link source is required");
+        const row = database
+            .prepare("INSERT INTO links(from_type,from_id,to_type,to_id,kind,anchor,source,target_text,target_folded,role,evidence,metadata,confirmed,created_at,author,updated_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?) RETURNING id")
+            .get(from.type, from.id, to?.type ?? null, to?.id ?? null, link.kind, link.anchor, link.origin, link.target_text, link.target_text === null ? null : fold(link.target_text), link.role, link.evidence, link.provenance === null ? null : JSON.stringify({ provenance: link.provenance }), Number(link.confirmed), link.created_at, link.author, link.updated_at);
+        if (!row)
+            throw new CliError("configuration_error", "project annotation link insertion failed");
+        mappings[link.ref] = `link:${row.id}`;
+    }
+    return mappings;
+};

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

@@ -0,0 +1,3 @@
+import type { ProjectAnnotationStore } from "../../project-transfer/store.js";
+import type { StoreContext } from "../open.js";
+export declare const projectAnnotationStoreOver: ({ database }: StoreContext) => ProjectAnnotationStore;

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

@@ -0,0 +1,35 @@
+import { CliError } from "@wirecat/cli-base";
+import { projectAnnotationRequest } from "../../project-transfer/request.js";
+import { write } from "../transaction.js";
+import { SnapshotBudget } from "./budget.js";
+import { previewAnnotationSnapshot } from "./preview.js";
+import { restoreAnnotationRecords } from "./records.js";
+export const projectAnnotationStoreOver = ({ database }) => ({
+    async preview(request) {
+        const { snapshot, projectId } = projectAnnotationRequest(request);
+        return previewAnnotationSnapshot(database, projectId, snapshot, request.bindings, new SnapshotBudget(request.maxReadBytes ?? 4 * 1024 * 1024));
+    },
+    async restore(request) {
+        const { snapshot, projectId } = projectAnnotationRequest(request, true);
+        const budget = new SnapshotBudget(request.maxReadBytes ?? 4 * 1024 * 1024);
+        try {
+            return write(database, () => {
+                const preview = previewAnnotationSnapshot(database, projectId, snapshot, request.bindings, budget);
+                if (!preview.ready || preview.fingerprint !== request.fingerprint)
+                    throw new CliError("validation_error", "project annotation preview is stale or has conflicts; preview again");
+                const mappings = restoreAnnotationRecords(database, projectId, snapshot, request.bindings);
+                return {
+                    project: request.project,
+                    fingerprint: preview.fingerprint,
+                    mappings,
+                    counts: { aliases: snapshot.aliases.length, facts: snapshot.facts.length, links: snapshot.links.length },
+                };
+            });
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError("configuration_error", "project annotation restore failed; its transaction was rolled back");
+        }
+    },
+});

package/dist/store/store.d.ts

@@ -10,6 +10,7 @@ import type { MeetingFindingsStore } from "./meeting-findings.js";
 import { type MentionsStore } from "./mentions.js";
 import { type MessagesStore } from "./messages.js";
 import { type PeopleStore } from "./people.js";
+import type { ProjectAnnotationStore } from "./project-transfer/store.js";
 import { type QueriesStore } from "./queries.js";
 import { type RosterStore } from "./roster.js";
 import { type SearchIndexStore } from "./search-index.js";
@@ -34,6 +35,7 @@ import { type TagsStore } from "./tags.js";
 import type { AccountKey } from "./types.js";
 import { type VectorsStore } from "./vectors.js";
 export interface MessageStore {
+    readonly projectAnnotations?: ProjectAnnotationStore;
     readonly contextEvidence?: ContextEvidenceReader;
     readonly contextIndex?: ContextIndex;
     readonly contextRecords?: ContextRecordReader;

package/dist/store/store.js

@@ -31,6 +31,7 @@ import { sourceMentionStoreOver } from "./sqlite/mention-sources.js";
 import { noteSearchOver } from "./sqlite/note-search.js";
 import { notesStoreOver } from "./sqlite/notes.js";
 import { openStoreContext } from "./sqlite/open-store.js";
+import { projectAnnotationStoreOver } from "./sqlite/project-transfer/store.js";
 import { proposedActionsStoreOver } from "./sqlite/proposed-actions.js";
 import * as stems from "./sqlite/stems.js";
 import { taskStoreOver } from "./sqlite/tasks.js";
@@ -82,6 +83,7 @@ const storeOver = (context) => {
         mentions: areaOf(() => accountMentionsOver(context), (keyed) => mentionsStoreOver(context, keyed)),
     };
     const contextEvidence = once(() => contextEvidenceOver(context));
+    const projectAnnotations = once(() => projectAnnotationStoreOver(context));
     const contextIndex = once(() => contextIndexOver(context, stemmerFor));
     const contextRecords = once(() => contextRecordsOver(context));
     const searches = once(() => searchesStoreOver(context));
@@ -102,6 +104,9 @@ const storeOver = (context) => {
     const agentActions = once(() => agentActionsStoreOver(context, pruneLogsWhenDue));
     const meetings = once(() => meetingStoreOver(context));
     const store = {
+        get projectAnnotations() {
+            return projectAnnotations();
+        },
         get contextEvidence() {
             return contextEvidence();
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.373.0",
+  "version": "0.374.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",