@popoverai/dotrequirements 0.32.1 → 0.34.0

package/dist/schema/schemas.d.ts

@@ -86,6 +86,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         title: z.ZodOptional<z.ZodString>;
         defaultPrefix: z.ZodOptional<z.ZodString>;
+        solution: z.ZodOptional<z.ZodString>;
+        outcome: z.ZodOptional<z.ZodString>;
         attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
             url: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
@@ -112,6 +114,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -120,6 +124,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -133,6 +139,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -146,6 +154,8 @@ export declare const MetadataSchema: z.ZodObject<{
         id?: string | undefined;
         title?: string | undefined;
         defaultPrefix?: string | undefined;
+        solution?: string | undefined;
+        outcome?: string | undefined;
         attachments?: {
             url: string;
             title?: string | undefined;
@@ -213,6 +223,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            solution: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
             attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
                 url: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
@@ -239,6 +251,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -247,6 +261,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -260,6 +276,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -273,6 +291,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -288,6 +308,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            solution: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
             attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
                 url: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
@@ -314,6 +336,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -322,6 +346,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -335,6 +361,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -348,6 +376,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -363,6 +393,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             title: z.ZodOptional<z.ZodString>;
             defaultPrefix: z.ZodOptional<z.ZodString>;
+            solution: z.ZodOptional<z.ZodString>;
+            outcome: z.ZodOptional<z.ZodString>;
             attachments: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
                 url: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
@@ -389,6 +421,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -397,6 +431,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -410,6 +446,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;
@@ -423,6 +461,8 @@ export declare const RequirementsFileSchema: z.ZodObject<{
             id?: string | undefined;
             title?: string | undefined;
             defaultPrefix?: string | undefined;
+            solution?: string | undefined;
+            outcome?: string | undefined;
             attachments?: {
                 url: string;
                 title?: string | undefined;

package/dist/schema/schemas.js

@@ -147,6 +147,10 @@ export const MetadataSchema = z.object({
         id: z.string().optional(), // Cloud document link - filled by push when creating
         title: z.string().optional(), // Legacy fallback — the body's leading H1 is the title
         defaultPrefix: z.string().optional(), // Editor hint for new requirement keys
+        // SOLDOC-5: the solution (by id) and the outcome (by name) this document
+        // belongs to. Written by the sync; the truth once present.
+        solution: z.string().optional(),
+        outcome: z.string().optional(),
         // ATTACH-10: links attached to the document (a Miro board, a reference
         // page). Round-trips through sync — the cloud stores them as document
         // metadata, the file carries them here.

package/dist/sync/execute.d.ts

@@ -9,6 +9,7 @@
  */
 import type { PlannedAction, SyncMode } from "./plan.js";
 import type { CloudAuth } from "./snapshot.js";
+import { type SolutionForSync } from "./solution-documents.js";
 import type { CloudSnapshot, DocumentComparison } from "./types.js";
 export interface SyncOutcome {
     cloudCreated: number;
@@ -59,6 +60,8 @@ export interface SyncOutcome {
         name: string;
         warning: string;
     }>;
+    /** SOLDOC-5.1/5.2: a file whose path and frontmatter disagree about where it belongs. Optional so an outcome built before the field existed still reads. */
+    belongingWarnings?: string[];
     /** SYNC-CLI-EDIT-3.1: files whose notation the cloud changed on storing —
      * list markers, emphasis characters, spacing. Counted so the sync can say
      * the reformatting happened and why, instead of leaving Jaime to discover
@@ -85,5 +88,11 @@ export interface SyncOutcome {
  * writes require a project slug in `auth`; a read-only share run has none and
  * its plan carries no cloud-writing actions.
  */
-export declare function executePlan(plan: PlannedAction[], cloud: CloudSnapshot, auth: CloudAuth, workspaceRoot: string, mode: SyncMode): Promise<SyncOutcome>;
+export declare function executePlan(plan: PlannedAction[], cloud: CloudSnapshot, auth: CloudAuth, workspaceRoot: string, mode: SyncMode, 
+/**
+ * The project's solutions, as `projectSolutions` read them; null (the
+ * default) when the project's team doesn't have solutions
+ * (SOLACCESS-2.2), so no file is placed as a solution's.
+ */
+solutions?: SolutionForSync[] | null): Promise<SyncOutcome>;
 //# sourceMappingURL=execute.d.ts.map

package/dist/sync/execute.js

@@ -10,13 +10,15 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
-import { getConvexUrl } from "../config.js";
+import { convexUrl } from "../cloud.js";
 import { api } from "../convex.js";
 import { parseFilesForPushIndividually, WEB_APP_URL } from "../push/core.js";
 import { composeMarkdownWithTitle, splitLeadingH1, writeRequirementsFile, } from "../schema/index.js";
+import { commandErrorMessage } from "../utils/command-error.js";
 import { cloudAttachmentRemovals, resolveAttachments } from "./attachments.js";
-import { resolveLocalPath } from "./local-files.js";
+import { resolveLocalPath, sanitizeFileName } from "./local-files.js";
 import { publishToCloud } from "./publish.js";
+import { requirementsDocByName, resolveBelonging, solutionDirOf, solutionDocumentPath, } from "./solution-documents.js";
 function emptyOutcome() {
     return {
         cloudCreated: 0,
@@ -34,6 +36,7 @@ function emptyOutcome() {
         writeBackWarnings: [],
         importWarnings: [],
         publishWarnings: [],
+        belongingWarnings: [],
         normalized: [],
         renames: [],
         inferredPrefixes: [],
@@ -44,9 +47,15 @@ function emptyOutcome() {
  * writes require a project slug in `auth`; a read-only share run has none and
  * its plan carries no cloud-writing actions.
  */
-export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
+export async function executePlan(plan, cloud, auth, workspaceRoot, mode, 
+/**
+ * The project's solutions, as `projectSolutions` read them; null (the
+ * default) when the project's team doesn't have solutions
+ * (SOLACCESS-2.2), so no file is placed as a solution's.
+ */
+solutions = null) {
     const outcome = emptyOutcome();
-    const client = new ConvexHttpClient(getConvexUrl());
+    const client = new ConvexHttpClient(convexUrl());
     const cloudById = new Map(cloud.documents.map((d) => [d.documentId, d]));
     const requirementsDir = path.join(workspaceRoot, ".requirements");
     const usedPaths = new Set();
@@ -63,7 +72,7 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
                     outcome.invalid.push(doc);
                     break;
                 case "cloud_write":
-                    await cloudWrite(auth, doc, cloudById, outcome, mode);
+                    await cloudWrite(auth, doc, cloudById, outcome, mode, solutions);
                     break;
                 case "cloud_delete":
                     await cloudDelete(client, auth, doc, outcome);
@@ -83,14 +92,14 @@ export async function executePlan(plan, cloud, auth, workspaceRoot, mode) {
             await syncResidualAttachments(client, auth, doc, action, outcome, mode);
         }
         catch (err) {
-            outcome.errors.push({ name, error: errorDisplayMessage(err) });
+            outcome.errors.push({ name, error: commandErrorMessage(err) });
         }
     }
     return outcome;
 }
 /**
  * Attachment-only operations for whatever the body action didn't cover.
- * The push goes through setAttachmentsForSync — a metadata patch, never the
+ * The push goes through syncAttachments — a metadata patch, never the
  * publish path, so naming a link cannot displace anyone's working document.
  */
 async function syncResidualAttachments(client, auth, doc, action, outcome, mode) {
@@ -110,12 +119,11 @@ async function syncResidualAttachments(client, auth, doc, action, outcome, mode)
         if (!auth.projectSlug) {
             throw new Error("Cannot sync attachments without project credentials.");
         }
-        await client.mutation(api.documents.mutations.setAttachmentsForSync, {
+        await client.mutation(api.documents.mutations.syncAttachments, {
             projectAuth: {
                 projectSlug: auth.projectSlug,
                 projectSecret: auth.projectSecret,
             },
-            target: { type: "project", slug: auth.projectSlug },
             documentId: doc.documentId,
             attachments: res.cloudFinal,
             // Compare-and-set: the resolution was computed from the snapshot's
@@ -161,18 +169,7 @@ async function syncResidualAttachments(client, auth, doc, action, outcome, mode)
         outcome.attachmentWrites++;
     }
 }
-/**
- * Servers throw ConvexError({kind, message}) for expected failures; production
- * redacts the Error message to "Server Error" but preserves error.data.
- * Surface the human-readable message rather than the blob.
- */
-function errorDisplayMessage(err) {
-    const data = err.data;
-    if (data && typeof data.message === "string")
-        return data.message;
-    return err instanceof Error ? err.message : String(err);
-}
-async function cloudWrite(auth, doc, cloudById, outcome, mode) {
+async function cloudWrite(auth, doc, cloudById, outcome, mode, solutions) {
     if (!auth.projectSlug || !doc.filePath) {
         throw new Error("Cannot write to the cloud without project credentials.");
     }
@@ -181,6 +178,24 @@ async function cloudWrite(auth, doc, cloudById, outcome, mode) {
     if (!parsed)
         throw new Error(`Could not parse ${path.basename(doc.filePath)}`);
     const meta = parsed.metadata.document;
+    // SOLDOC-3/4/5: what the file's name and place say about it. A file in a
+    // solution directory with no frontmatter declares its belonging by its
+    // path; one with frontmatter keeps that, and a disagreeing path is reported.
+    // SOLACCESS-2.2: without solutions, a file is placed as it was before them.
+    const withSolutions = solutions !== null;
+    const resolved = withSolutions
+        ? resolveBelonging(doc.filePath, { solution: meta?.solution, outcome: meta?.outcome }, solutionDirOf(doc.filePath), solutions)
+        : { belonging: undefined, warning: undefined };
+    if (resolved.warning) {
+        outcome.belongingWarnings = [
+            ...(outcome.belongingWarnings ?? []),
+            resolved.warning,
+        ];
+    }
+    const belonging = resolved.belonging;
+    const isRequirementsDoc = withSolutions
+        ? requirementsDocByName(doc.filePath)
+        : undefined;
     // SYNC-TITLE-1.1: a legacy file whose title lives only in frontmatter (no body
     // H1) must reach the cloud self-describing. Materialize the title as the body's
     // leading H1 BEFORE the push — so the cloud row carries the H1 on first write
@@ -225,6 +240,8 @@ async function cloudWrite(auth, doc, cloudById, outcome, mode) {
                 : []
             : undefined,
         runMarker: parsed.metadata.ctsRun,
+        solution: belonging,
+        isRequirementsDoc,
     });
     const documentId = saveResult.documentId;
     // ATTACH-10.3.1.0: the publish above is the push that removes cloud
@@ -330,6 +347,9 @@ async function cloudWrite(auth, doc, cloudById, outcome, mode) {
         // the title.
         writeRequirementsFile(doc.filePath, {
             documentId,
+            // SOLDOC-4.1: the belonging the path declared is written into the
+            // frontmatter, where it is the truth from now on.
+            belonging,
             // The prefix just pushed is the file's own (or the one inferred from
             // its first key, DOC-HEADER-11.4, which the write-back materializes).
             defaultPrefix: meta?.defaultPrefix
@@ -361,12 +381,11 @@ async function cloudDelete(client, auth, doc, outcome) {
     if (!auth.projectSlug || !doc.documentId) {
         throw new Error("Cannot delete from the cloud without project credentials.");
     }
-    await client.mutation(api.documents.mutations.deleteForCli, {
+    await client.mutation(api.documents.mutations.deleteForSync, {
         projectAuth: {
             projectSlug: auth.projectSlug,
             projectSecret: auth.projectSecret,
         },
-        target: { type: "project", slug: auth.projectSlug },
         documentId: doc.documentId,
     });
     outcome.cloudDeleted++;
@@ -377,8 +396,9 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
         throw new Error(`No cloud content for ${doc.title}`);
     if (!fs.existsSync(requirementsDir))
         fs.mkdirSync(requirementsDir, { recursive: true });
-    const filePath = resolveLocalPath(cloudDoc, doc.filePath, usedPaths, requirementsDir);
+    const filePath = placeCloudDocument(cloudDoc, doc.filePath, usedPaths, requirementsDir);
     usedPaths.add(filePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
     // DOC-HEADER-11.6/11.7: a cloud document with no prefix means "nothing to
     // impose" under an additive sync and "no prefix" under cloud-wins authority
     // — so a prefix Jaime wrote is only ever removed by the mode they ran to
@@ -402,10 +422,42 @@ function localWrite(doc, cloudById, usedPaths, requirementsDir, outcome, mode) {
         defaultPrefix,
         attachments,
         version: cloudDoc.version,
+        belonging: cloudDoc.solution
+            ? {
+                solutionId: cloudDoc.solution.solutionId,
+                outcome: cloudDoc.solution.outcome,
+            }
+            : undefined,
     }, cloudDoc.body);
     if (changed)
         outcome.localWritten++;
 }
+/**
+ * SOLDOC-6: where a pulled document lands. A file it is already linked to
+ * keeps its path (SYNC-DISCOVERY-2.0); a document that belongs to a solution
+ * lands in that solution's directory, named for its outcome; a document
+ * that is not a requirements document and belongs to no solution has no
+ * place, and the pull says so rather than guessing.
+ */
+function placeCloudDocument(cloudDoc, existingPath, usedPaths, requirementsDir) {
+    if (existingPath)
+        return existingPath;
+    const isRequirementsDoc = cloudDoc.isRequirementsDoc !== false;
+    if (cloudDoc.solution) {
+        // SOLDOC-9: the solution's own directory name; a backend from before it
+        // was sent leaves it out, and the title's slug stands in.
+        const candidate = solutionDocumentPath(requirementsDir, cloudDoc.solution.directory ??
+            sanitizeFileName(cloudDoc.solution.title ?? cloudDoc.solution.solutionId), cloudDoc.solution.outcome, isRequirementsDoc);
+        if (usedPaths.has(candidate) || fs.existsSync(candidate)) {
+            throw new Error(`"${cloudDoc.title}" belongs at ${path.relative(path.dirname(requirementsDir), candidate)}, but another file is already there.`);
+        }
+        return candidate;
+    }
+    if (!isRequirementsDoc) {
+        throw new Error(`"${cloudDoc.title}" is not a requirements document and belongs to no solution, so the pull has nowhere to put it.`);
+    }
+    return resolveLocalPath(cloudDoc, existingPath, usedPaths, requirementsDir);
+}
 function localDelete(doc, outcome) {
     if (!doc.filePath)
         return;

package/dist/sync/index.d.ts

@@ -6,7 +6,7 @@ import type { ComparisonResult, DocumentComparison } from "./types.js";
 export { compareSnapshots, duplicateIdAbortMessage, duplicateLocalDocumentIds, } from "./compare.js";
 export { displayName, formatUnitDetail, formatVerdictLine, resolutionHint, scopeToken, } from "./render.js";
 export { segmentBody } from "./segment.js";
-export { acquireCloudSnapshot, acquireLocalSnapshot, type CloudAuth, readLocalDocument, } from "./snapshot.js";
+export { acquireCloudSnapshot, acquireLocalSnapshot, type CloudAuth, foreignDocumentNotes, projectSolutions, readLocalDocument, } from "./snapshot.js";
 export type { CloudDocument, CloudSnapshot, ComparisonResult, DocumentComparison, LocalDocument, LocalSnapshot, UnitDetail, Verdict, } from "./types.js";
 export { verdictLabel } from "./types.js";
 /**

package/dist/sync/index.js

@@ -6,7 +6,7 @@ import * as path from "node:path";
 export { compareSnapshots, duplicateIdAbortMessage, duplicateLocalDocumentIds, } from "./compare.js";
 export { displayName, formatUnitDetail, formatVerdictLine, resolutionHint, scopeToken, } from "./render.js";
 export { segmentBody } from "./segment.js";
-export { acquireCloudSnapshot, acquireLocalSnapshot, readLocalDocument, } from "./snapshot.js";
+export { acquireCloudSnapshot, acquireLocalSnapshot, foreignDocumentNotes, projectSolutions, readLocalDocument, } from "./snapshot.js";
 export { verdictLabel } from "./types.js";
 /**
  * Does a document match one scope token? A token may name a local file (path or

package/dist/sync/publish.d.ts

@@ -32,6 +32,13 @@ export interface PublishParams {
         title?: string;
     }>;
     runMarker?: string;
+    /** SOLDOC-4/5: the belonging the file declares. */
+    solution?: {
+        solutionId: string;
+        outcome: string;
+    };
+    /** SOLDOC-3: what the file's name says; undefined where the rule doesn't reach. */
+    isRequirementsDoc?: boolean;
 }
 /**
  * What the server reports back: the document, any run-marker complaint, and any

package/dist/sync/publish.js

@@ -11,7 +11,7 @@
  * repo unable to push. Recoverable rather than lossy — see
  * docs/working/publishing-and-unpublished-changes.md.
  */
-import { DEFAULT_API_BASE_URL } from "../requirements/cloud-ai.js";
+import { webApiUrl } from "../cloud.js";
 /**
  * POST to `/api/publish`. Returns the saved document; throws with the server's
  * own message on failure, which is what Jaime reads in the sync output.
@@ -21,7 +21,7 @@ import { DEFAULT_API_BASE_URL } from "../requirements/cloud-ai.js";
  * apply next time.
  */
 export async function publishToCloud(params) {
-    const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
+    const apiBaseUrl = webApiUrl();
     const response = await fetch(`${apiBaseUrl}/api/publish`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },

package/dist/sync/segment.js

@@ -6,7 +6,10 @@
  * normalized text (prose has no stable id, so a reworded passage reads as a
  * removal-plus-addition — a conflict, per DIFF-4.3).
  */
-import { canonicalRequirementKey, canonicalRequirementPath, getAllRequirements, parseRequirementBlock, splitRequirementFenceContent, } from "../schema/index.js";
+// From the fs-free modules, not the schema index, so the backend can bundle
+// the comparator for merging a solution's branch (BRANCH-7).
+import { getAllRequirements, parseRequirementBlock, splitRequirementFenceContent, } from "../schema/parser-core.js";
+import { canonicalRequirementKey, canonicalRequirementPath, } from "../schema/schemas.js";
 /** Matches a fenced dotrequirements block; group 1 is its inner content. */
 const FENCE = /```dotrequirements\n([\s\S]*?)```/gm;
 /**

package/dist/sync/snapshot.d.ts

@@ -1,8 +1,9 @@
 /**
  * Snapshot acquisition for the comparator — kept separate from comparison so
  * the comparator stays a pure function (compare.ts). The local half reads the
- * workspace; the cloud half is one exportProjectForCli query.
+ * workspace; the cloud half is one export query.
  */
+import type { SolutionForSync } from "./solution-documents.js";
 import type { CloudSnapshot, LocalDocument, LocalSnapshot } from "./types.js";
 /**
  * Read and classify one requirements file into a LocalDocument. A file whose
@@ -15,16 +16,37 @@ export declare function readLocalDocument(filePath: string): LocalDocument;
  * Build the local snapshot from the workspace, or from an explicit set of file
  * paths (scope). Files are always read fresh from disk.
  */
-export declare function acquireLocalSnapshot(workspaceRoot: string, filePaths?: string[]): Promise<LocalSnapshot>;
+export declare function acquireLocalSnapshot(workspaceRoot: string, filePaths?: string[], options?: {
+    solutions?: boolean;
+}): Promise<LocalSnapshot>;
+/**
+ * The project's solutions as the sync places files by them (SOLDOC-4), or
+ * null when the project's team doesn't have solutions, so the sync behaves
+ * as it did before solutions (SOLACCESS-2.2). Whether it has them is the
+ * export's answer — the one the cloud side was read with — so the local
+ * side can't follow a different one. A share run places nothing, so it
+ * needs no list. A failure to fetch the list fails the sync, as does a
+ * switch flipped between the two reads: guessing would leave solution
+ * documents out of the repo's side, and a repo-wins sync would delete them
+ * from the cloud.
+ */
+export declare function projectSolutions(auth: CloudAuth, cloud: CloudSnapshot): Promise<SolutionForSync[] | null>;
 export interface CloudAuth {
     /** projectSlug + projectSecret for full access, or a bare share token. */
     projectSlug?: string;
     projectSecret: string;
 }
 /**
- * Build the cloud snapshot with one exportProjectForCli query. A share token is
- * passed as the projectSecret with no slug (the read-only wrapper resolves the
- * project from the token) — the read-only path never writes back.
+ * Build the cloud snapshot with one export query: the project's own, with a
+ * project secret, or the share endpoint, with a bare share token (the token
+ * names the project) — the read-only path never writes back.
  */
 export declare function acquireCloudSnapshot(auth: CloudAuth): Promise<CloudSnapshot>;
+/**
+ * SYNC-FAIL-5: of the ids the workspace's files carry, the ones that name
+ * another project's document, each with the words a push of that file gets,
+ * so `dotreq diff` says what `dotreq sync` will. A backend that can't answer
+ * leaves the diff as it was rather than failing it.
+ */
+export declare function foreignDocumentNotes(auth: CloudAuth, documentIds: string[]): Promise<Map<string, string>>;
 //# sourceMappingURL=snapshot.d.ts.map