@wirecat/cli-core 0.369.0 → 0.371.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ shape of this file.
 
 ## Unreleased
 
+## 0.371.0 — 20.10.2026
+
+### Added
+
+- **Project annotation manifest validation from `./store`** checks a bounded, versioned JSON graph of
+  project aliases, facts and direct links with explicit external dependencies and omitted facets.
+  `decodeProjectAnnotations` validates it, `projectAnnotationsFingerprint` hashes its normalized
+  form, and `planProjectAnnotations` checks explicit bindings against a complete target snapshot.
+  These helpers do not export a store, restore records or authorize confirmation.
+- **`documentPassage` from `./services`** gives hosts the same bounded paragraph context that project gathering
+  uses, so a findings review can show the paragraphs around its cited document without copying that logic.
+
+## 0.370.0 — 20.10.2026
+
+### Changed — may break callers
+
+- **`checkGuide` finds a scenario step a shell would change**, so a tool's guide test that passed may now fail. It
+  splits each step as a POSIX shell does and reports `>`, `<`, `|`, `&`, `;`, `` ` ``, `$(` and the globs `*`, `?`,
+  `[` left outside quotes (`` ` `` and `$(` also inside double quotes), and a quote never closed. `max review
+  date>1d` passed before, though a shell writes a file named `1d` and drops the filter. Quote the word:
+  `'date>1d'`. `shellProblems(run)` gives the same check for one step.
+
+### Added
+
+- **`MEMO_SCENARIOS` holds the titles of memo's cross-tool scenarios** (`personBrief`, `decisionTrail`), so every
+  tool's "Works with" list takes them from one place instead of typing its own copy.
+
 ## 0.369.0 — 20.10.2026
 
 ### Fixed

package/dist/cli/guide.d.ts

@@ -18,6 +18,19 @@ export interface GuideReference {
     name: string;
     title: string;
 }
+/** memo's cross-tool scenarios: the one source of the titles every tool lists, and memo's files must carry. */
+export declare const MEMO_SCENARIOS: {
+    readonly personBrief: {
+        readonly tool: "memo";
+        readonly name: "person-brief";
+        readonly title: "One person across every tool";
+    };
+    readonly decisionTrail: {
+        readonly tool: "memo";
+        readonly name: "decision-trail";
+        readonly title: "What did we decide about X, across every source";
+    };
+};
 export interface GuideOptions {
     /** Absolute path of the tool's scenario files: `fileURLToPath(new URL("../scenarios", import.meta.url))`. */
     directory: string;
@@ -40,6 +53,8 @@ export declare const loadScenarios: (directory: string) => Promise<{
  * program is built. `checkGuide` validates them in the tool's CI.
  */
 export declare const guideCommand: (app: Pick<AppIdentity, "command">, options: GuideOptions) => Command;
+/** Characters in a step that a shell would act on: the person who copies it would run something else. */
+export declare const shellProblems: (run: string) => string[];
 /** What is wrong with one step on this program: the path, each option and its value, the arguments. Never runs it. */
 export declare const checkStep: (program: Command, run: string) => string[];
 /**

package/dist/cli/guide.js

@@ -7,6 +7,11 @@ import { environmentOf, outputFor } from "./context.js";
 import { NO_EFFECTS } from "./effects.js";
 import { itemOf, listOf, renderAnswer } from "./envelope.js";
 import { PROFILE_FREE } from "./profile.js";
+/** memo's cross-tool scenarios: the one source of the titles every tool lists, and memo's files must carry. */
+export const MEMO_SCENARIOS = {
+    personBrief: { tool: "memo", name: "person-brief", title: "One person across every tool" },
+    decisionTrail: { tool: "memo", name: "decision-trail", title: "What did we decide about X, across every source" },
+};
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const FIELDS = new Set(["title", "goal", "steps", "look"]);
 const NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -157,17 +162,49 @@ export const guideCommand = (app, options) => {
     guides.set(command, options);
     return command;
 };
-/** A step's words, split as a shell would on spaces, with "…" and '…' kept together. */
-const words = (line) => {
+const OPERATORS = {
+    ">": "redirects output to a file",
+    "<": "reads input from a file",
+    "|": "pipes into another command",
+    "&": "runs the command in the background",
+    ";": "ends the command there",
+    "`": "runs it as a command",
+    "$(": "runs it as a command",
+    "*": "expands it to file names",
+    "?": "expands it to file names",
+    "[": "expands it to file names",
+};
+/**
+ * A step split into words as a POSIX shell would — '…' literal, "…" with \ escapes, \ outside quotes — and the
+ * characters a shell would act on instead of passing them to the tool. `` ` `` and `$(` still act inside "…".
+ */
+const scan = (line) => {
     const found = [];
+    const live = new Set();
     let word;
     let quote;
-    for (const char of line) {
-        if (quote) {
-            if (char === quote)
+    for (let index = 0; index < line.length; index++) {
+        const char = line[index];
+        const next = line[index + 1];
+        if (quote === "'") {
+            if (char === "'")
                 quote = undefined;
             else
-                word = (word ?? "") + char;
+                word += char;
+            continue;
+        }
+        if (char === "\\" && next !== undefined && (quote === undefined || '$`"\\'.includes(next))) {
+            word = (word ?? "") + next;
+            index++;
+            continue;
+        }
+        if (char === "`" || (char === "$" && next === "("))
+            live.add(char === "`" ? "`" : "$(");
+        if (quote === '"') {
+            if (char === '"')
+                quote = undefined;
+            else
+                word += char;
         }
         else if (char === '"' || char === "'") {
             quote = char;
@@ -178,12 +215,24 @@ const words = (line) => {
                 found.push(word);
             word = undefined;
         }
-        else
+        else {
+            if (OPERATORS[char])
+                live.add(char);
             word = (word ?? "") + char;
+        }
     }
     if (word !== undefined)
         found.push(word);
-    return found;
+    return { words: found, live: [...live], open: quote !== undefined };
+};
+const words = (line) => scan(line).words;
+/** Characters in a step that a shell would act on: the person who copies it would run something else. */
+export const shellProblems = (run) => {
+    const { live, open } = scan(run);
+    return [
+        ...live.map((char) => `a shell acts on ${char}: it ${OPERATORS[char]}; put the word in single quotes`),
+        ...(open ? ["a quote is never closed"] : []),
+    ];
 };
 const silent = (command) => command.exitOverride().configureOutput({ writeOut: () => { }, writeErr: () => { }, outputError: () => { } });
 const ownerOf = (chain, flag) => {
@@ -295,7 +344,7 @@ export const checkGuide = async (build, { packageRoot } = {}) => {
     const { scenarios, problems } = await loadScenarios(options.directory);
     for (const scenario of scenarios)
         scenario.steps.forEach((step, index) => {
-            for (const problem of checkStep(build(), step.run))
+            for (const problem of [...shellProblems(step.run), ...checkStep(build(), step.run)])
                 problems.push(`${scenario.name}.md step ${index + 1} (${step.run}): ${problem}`);
         });
     for (const reference of options.worksWith ?? [])

package/dist/cli/index.d.ts

@@ -56,7 +56,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, type Scenario, } from "./guide.js";
+export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";
 export { type CommandHelp, commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, type NextChoice, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
 export { type FirstScreen, type FirstScreenLine, firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";

package/dist/cli/index.js

@@ -51,7 +51,7 @@ export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
-export { checkGuide, checkStep, guideCommand, loadScenarios, } from "./guide.js";
+export { checkGuide, checkStep, guideCommand, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";
 export { commandHelp, commandHelpMarkdown, commandHelpText, exampleReport, nextUsually, } from "./help/command-help.js";
 export { commandsText } from "./help/commands-text.js";
 export { firstScreen, installHelp, WIRECAT_TOOLS, } from "./help/first-screen.js";

package/dist/services/index.d.ts

@@ -6,7 +6,7 @@ export { type DownloadedModel, downloadImageModel, downloadTextModel, type Model
 export type { ProjectEvidenceItem, ProjectGathering, ProjectGatheringPorts, ProjectGatheringStop, ProjectIndexCatchUp, ProjectSourceFetcher, } from "./project-gathering.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
 export type { ProjectNeighbour, ProjectNeighbourReader } from "./project-gathering-around.js";
-export { storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
+export { documentPassage, storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
 export type { EvidenceMention, EvidenceMentions } from "./project-gathering-mentions.js";
 export { findEvidenceMentions } from "./project-gathering-mentions.js";
 export type { ProjectFetchState, ProjectGatheringBudgets, ProjectGatheringRequest, ProjectLane, ProjectLaneKind, ProjectUnitState, } from "./project-gathering-request.js";

package/dist/services/index.js

@@ -3,7 +3,7 @@ export { contextEvidenceFingerprint, createContextEvidenceReader } from "./conte
 export { excerpt } from "./excerpt.js";
 export { downloadImageModel, downloadTextModel, } from "./model-downloads.js";
 export { gatherProjectEvidence } from "./project-gathering.js";
-export { storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
+export { documentPassage, storedMessageNeighbours, storedNeighbours } from "./project-gathering-around.js";
 export { findEvidenceMentions } from "./project-gathering-mentions.js";
 import { accountService } from "./account.js";
 import { adminService } from "./admin.js";

package/dist/store/index.d.ts

@@ -14,6 +14,8 @@ export type { MeetingFindingsBatch, MeetingFindingsStore } from "./meeting-findi
 export { MIGRATIONS, type Migration, migrate } from "./migrations.js";
 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 { 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

@@ -6,6 +6,8 @@ export { EVIDENCE_FINDINGS_KIND, validateEvidenceFindings, } from "./evidence-fi
 export { MIGRATIONS, migrate } from "./migrations.js";
 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 { 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

@@ -0,0 +1,6 @@
+import { type ProjectAnnotations } from "./schema.js";
+export type { ProjectAnnotations } from "./schema.js";
+export declare const PROJECT_ANNOTATIONS_MAX_BYTES: number;
+/** 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

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { canonicalReference, parseReference } from "../../domain/references.js";
+import { normalizeVocabularyName } from "../../domain/vocabulary.js";
+import { canonicalMeetingReference } from "../../meetings/index.js";
+import { projectAnnotationsSchema } from "./schema.js";
+export const PROJECT_ANNOTATIONS_MAX_BYTES = 4 * 1024 * 1024;
+const invalid = (field) => {
+    throw new CliError("validation_error", `invalid project annotations.${field}`);
+};
+const canonical = (ref) => {
+    try {
+        return ref.startsWith("meeting:") ? canonicalMeetingReference(ref) : canonicalReference(ref);
+    }
+    catch {
+        return invalid("reference");
+    }
+};
+const graph = (manifest) => {
+    const owned = new Set([manifest.project.ref]);
+    const external = new Set();
+    const used = new Set();
+    const kind = (ref, kinds) => {
+        if (canonical(ref) !== ref || !kinds.includes(parseReference(ref).type) || !/^[a-z]+:[1-9]\d*$/.test(ref))
+            invalid("reference kind");
+    };
+    kind(manifest.project.ref, ["project"]);
+    for (const fact of manifest.facts) {
+        kind(fact.ref, ["fact"]);
+        if (owned.has(fact.ref))
+            invalid("facts.duplicate");
+        owned.add(fact.ref);
+        kind(fact.author, ["person", "bot"]);
+        if (fact.confirmed_by !== null)
+            kind(fact.confirmed_by, ["person", "bot"]);
+        if (fact.updated_at < fact.created_at)
+            invalid("facts.updated_at");
+        if (fact.type !== "decision" && (fact.supersedes !== null || ["superseded", "reversed"].includes(fact.status)))
+            invalid("facts.lifecycle");
+        if (fact.supersedes === fact.ref)
+            invalid("facts.supersedes");
+    }
+    for (const item of manifest.external) {
+        if (canonical(item.ref) !== item.ref || owned.has(item.ref) || external.has(item.ref))
+            invalid("external.ref");
+        external.add(item.ref);
+        const body = /^(msg|document|note|meeting):/.test(item.ref);
+        if (body !== (item.content_sha256 !== null))
+            invalid("external.content_sha256");
+    }
+    const dependency = (ref) => {
+        if (ref === null)
+            return;
+        if (canonical(ref) !== ref || (!owned.has(ref) && !external.has(ref)))
+            invalid("missing dependency");
+        used.add(ref);
+    };
+    if (manifest.project.organization !== null)
+        kind(manifest.project.organization, ["organization"]);
+    dependency(manifest.project.organization);
+    const aliases = new Set([manifest.project.name, manifest.project.key].map(normalizeVocabularyName));
+    for (const alias of manifest.aliases) {
+        const name = normalizeVocabularyName(alias);
+        if (aliases.has(name))
+            invalid("aliases.duplicate");
+        aliases.add(name);
+    }
+    for (const fact of manifest.facts) {
+        for (const ref of [fact.author, fact.confirmed_by, fact.subject, fact.supersedes])
+            dependency(ref);
+        if (fact.supersedes !== null) {
+            kind(fact.supersedes, ["fact"]);
+            if (!manifest.facts.some((previous) => previous.ref === fact.supersedes && previous.type === "decision"))
+                invalid("facts.supersedes outside project");
+        }
+    }
+    const previous = new Map(manifest.facts.map((fact) => [fact.ref, fact.supersedes]));
+    for (const fact of manifest.facts) {
+        const path = new Set();
+        let ref = fact.ref;
+        while (ref) {
+            if (path.has(ref))
+                invalid("facts.supersedes cycle");
+            path.add(ref);
+            ref = previous.get(ref);
+        }
+    }
+    const links = new Set();
+    for (const link of manifest.links) {
+        if (!/^link:[1-9]\d*$/.test(link.ref) || links.has(link.ref))
+            invalid("links.ref");
+        links.add(link.ref);
+        if (!owned.has(link.from) && (link.to === null || !owned.has(link.to)))
+            invalid("links.outside project");
+        if (link.to === null && link.target_text === null)
+            invalid("links.target_text");
+        if (link.updated_at < link.created_at)
+            invalid("links.updated_at");
+        for (const ref of [link.from, link.to])
+            dependency(ref);
+    }
+    for (const ref of external)
+        if (!used.has(ref))
+            invalid("external.unused");
+};
+/** Decode bounded JSON, never a row/column importer or an implicit whole-project backup. */
+export const decodeProjectAnnotations = (json) => {
+    if (typeof json !== "string" || Buffer.byteLength(json) > PROJECT_ANNOTATIONS_MAX_BYTES)
+        invalid("bytes");
+    let input;
+    try {
+        input = JSON.parse(json);
+    }
+    catch {
+        return invalid("json");
+    }
+    const parsed = v.safeParse(projectAnnotationsSchema, input);
+    if (!parsed.success)
+        return invalid(parsed.issues[0]?.path?.map((part) => String(part.key)).join(".") ?? "manifest");
+    const manifest = parsed.output;
+    if (manifest.aliases.length + manifest.facts.length + manifest.links.length + manifest.external.length > 1000)
+        invalid("record budget");
+    graph(manifest);
+    return manifest;
+};
+export const projectAnnotationsFingerprint = (json) => {
+    const manifest = decodeProjectAnnotations(json);
+    const normalized = {
+        ...manifest,
+        aliases: manifest.aliases.toSorted(),
+        facts: manifest.facts.toSorted((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0)),
+        links: manifest.links.toSorted((a, b) => a.ref.localeCompare(b.ref)),
+        external: manifest.external.toSorted((a, b) => a.ref.localeCompare(b.ref)),
+    };
+    // Strict decoding fixes object key order; record arrays have identity, unlike text and timestamps.
+    return createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+};

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

@@ -0,0 +1,28 @@
+import * as v from "valibot";
+declare const targetSchema: v.StrictObjectSchema<{
+    readonly project: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    readonly revision_sha256: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>;
+    readonly annotation_count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.SafeIntegerAction<number, undefined>, v.MinValueAction<number, 0, 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, 2048, 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>]>;
+}, undefined>;
+export type ProjectAnnotationsTarget = v.InferOutput<typeof targetSchema>;
+export interface ProjectAnnotationsPlan {
+    fingerprint: string;
+    manifest_fingerprint: string;
+    target_revision_sha256: string;
+    missing_bindings: string[];
+    conflicts: {
+        reference: string;
+        reason: "missing" | "wrong_kind" | "changed" | "populated" | "duplicate";
+    }[];
+    ready: boolean;
+}
+/** 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

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { CliError } from "@wirecat/cli-base";
+import * as v from "valibot";
+import { canonicalReference, parseReference } from "../../domain/references.js";
+import { canonicalMeetingReference } from "../../meetings/index.js";
+import { decodeProjectAnnotations, projectAnnotationsFingerprint } from "./manifest.js";
+const hash = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/));
+const ref = v.pipe(v.string(), v.minLength(1), v.maxLength(2048));
+const targetSchema = v.strictObject({
+    project: v.pipe(v.string(), v.regex(/^project:[1-9]\d*$/)),
+    revision_sha256: hash,
+    annotation_count: v.pipe(v.number(), v.safeInteger(), v.minValue(0)),
+    external: v.pipe(v.array(v.strictObject({ ref, content_sha256: v.nullable(hash) })), v.maxLength(1000)),
+});
+const kind = (ref) => {
+    if (ref.startsWith("meeting:")) {
+        if (canonicalMeetingReference(ref) !== ref)
+            throw new Error("noncanonical");
+        return `meeting:${ref.split("/").length}`;
+    }
+    if (canonicalReference(ref) !== ref)
+        throw new Error("noncanonical");
+    const parsed = parseReference(ref);
+    return "provider" in parsed ? `${parsed.type}:${parsed.provider}` : parsed.type;
+};
+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");
+    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)
+        return invalid("bindings");
+    const required = new Set([manifest.project.ref, ...manifest.external.map((item) => item.ref)]);
+    for (const [source, destination] of Object.entries(bindings))
+        if (!required.has(source) || typeof destination !== "string" || destination.length > 2048)
+            return invalid("bindings");
+    const destinations = new Map();
+    for (const item of checked.output.external) {
+        try {
+            kind(item.ref);
+        }
+        catch {
+            return invalid("target.external.ref");
+        }
+        if (destinations.has(item.ref) || item.ref === target.project)
+            return invalid("target.external.duplicate");
+        destinations.set(item.ref, item.content_sha256);
+    }
+    const missing_bindings = [], conflicts = [];
+    const used = new Set();
+    for (const source of required) {
+        const destination = bindings[source];
+        if (destination === undefined) {
+            missing_bindings.push(source);
+            continue;
+        }
+        try {
+            if (kind(source) !== kind(destination)) {
+                conflicts.push({ reference: source, reason: "wrong_kind" });
+                continue;
+            }
+        }
+        catch {
+            return invalid("bindings.reference");
+        }
+        if (used.has(destination))
+            conflicts.push({ reference: source, reason: "duplicate" });
+        used.add(destination);
+        if (source === manifest.project.ref) {
+            if (destination !== target.project)
+                conflicts.push({ reference: source, reason: "missing" });
+            continue;
+        }
+        if (!destinations.has(destination))
+            conflicts.push({ reference: source, reason: "missing" });
+        else if (destinations.get(destination) !== manifest.external.find((item) => item.ref === source)?.content_sha256)
+            conflicts.push({ reference: source, reason: "changed" });
+    }
+    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,
+        target: {
+            ...checked.output,
+            external: checked.output.external.toSorted((a, b) => (a.ref < b.ref ? -1 : a.ref > b.ref ? 1 : 0)),
+        },
+        bindings: Object.fromEntries(Object.entries(bindings).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
+    }))
+        .digest("hex");
+    return {
+        fingerprint,
+        manifest_fingerprint,
+        target_revision_sha256: target.revision_sha256,
+        missing_bindings,
+        conflicts,
+        ready: missing_bindings.length === 0 && conflicts.length === 0,
+    };
+};

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

@@ -0,0 +1,94 @@
+import * as v from "valibot";
+export declare const projectAnnotationsSchema: v.StrictObjectSchema<{
+    readonly format: v.LiteralSchema<"wirecat.project-annotations", undefined>;
+    readonly version: v.LiteralSchema<1, 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>]>;
+    }, 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>;
+    }, undefined>;
+    readonly aliases: v.SchemaWithPipe<readonly [v.ArraySchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>, v.MaxLengthAction<string, number, undefined>]>, undefined>, v.MaxLengthAction<string[], 1000, 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>]>;
+}, undefined>;
+export type ProjectAnnotations = v.InferOutput<typeof projectAnnotationsSchema>;

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

@@ -0,0 +1,68 @@
+import * as v from "valibot";
+import { FACT_STATUSES, FACT_TYPES, MEMORY_SCOPES } from "../../domain/knowledge.js";
+import { LINK_KINDS } from "../sqlite/link-kinds.js";
+import { LINK_ORIGINS } from "../sqlite/notes.js";
+const text = (max) => v.pipe(v.string(), v.minLength(1), v.maxLength(max));
+const ref = text(2048);
+const timestamp = v.pipe(v.number(), v.safeInteger(), v.minValue(0));
+const nullableRef = v.nullable(ref);
+const bounded = (schema) => v.pipe(v.array(schema), v.maxLength(1000));
+export const projectAnnotationsSchema = v.strictObject({
+    format: v.literal("wirecat.project-annotations"),
+    version: v.literal(1),
+    project: v.strictObject({
+        ref,
+        key: v.pipe(v.string(), v.regex(/^[A-Z][A-Z0-9]{2,3}$/)),
+        name: text(200),
+        type: v.picklist(["work", "client", "personal", "oss", "other"]),
+        scope: v.picklist(MEMORY_SCOPES),
+        organization: nullableRef,
+        created_at: timestamp,
+    }),
+    coverage: v.strictObject({
+        aliases: v.literal("complete"),
+        facts: v.literal("complete"),
+        links: v.literal("complete"),
+        memories: v.literal("omitted"),
+        tasks: v.literal("omitted"),
+        labels: v.literal("omitted"),
+        findings: v.literal("omitted"),
+    }),
+    aliases: bounded(text(200)),
+    facts: bounded(v.strictObject({
+        ref,
+        type: v.picklist(FACT_TYPES),
+        statement: text(2000),
+        status: v.picklist(FACT_STATUSES),
+        subject: nullableRef,
+        occurred_at: v.nullable(timestamp),
+        supersedes: nullableRef,
+        author: ref,
+        model: v.nullable(text(200)),
+        confirmed_by: nullableRef,
+        scope: v.nullable(v.picklist(MEMORY_SCOPES)),
+        source: text(200),
+        created_at: timestamp,
+        updated_at: timestamp,
+    })),
+    links: bounded(v.strictObject({
+        ref: text(200),
+        from: ref,
+        to: nullableRef,
+        kind: v.picklist(LINK_KINDS),
+        origin: v.picklist(LINK_ORIGINS),
+        anchor: v.nullable(text(2000)),
+        target_text: v.nullable(text(2000)),
+        role: v.nullable(text(200)),
+        evidence: v.nullable(text(2000)),
+        confirmed: v.boolean(),
+        provenance: v.nullable(text(2000)),
+        created_at: timestamp,
+        updated_at: timestamp,
+        author: v.nullable(text(200)),
+    })),
+    external: bounded(v.strictObject({
+        ref,
+        content_sha256: v.nullable(v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/))),
+    })),
+});

package/package.json

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