@withpica/mcp-server 2.97.5 → 2.98.0

package/dist/tools/works.js

@@ -21,9 +21,12 @@
 import { ApiError, EntityNotFoundError, } from "@withpica/mcp-sdk";
 import { formatSuccess, formatDeletion, formatStructuredList, withBillingGate, buildDecision, mapGapsToHints, pushSectionError, } from "@withpica/mcp-utils";
 import { buildCustodyHints } from "./custody-hints.js";
+import { typedError } from "./error-envelope.js";
 import { computeWorkGapHints } from "./gap-hints.js";
 import { buildIntegrityPressure } from "./integrity-hints.js";
 import { detectVersionOfExistingWork, buildVersionWarning, parseVersionTitle, } from "./version-guard.js";
+import { WORK_TYPE_VALUES } from "./catalog-enums.js";
+import { VERBOSE_PROPERTY, RECEIPT_NOTE, changedFields, newHintsOnly, slimIntegrity, takeVerbose, } from "./write-receipt.js";
 /**
  * Canonical write-schema for `works`. Every property below must
  * correspond to a real column on `public.works` — verified against
@@ -41,7 +44,7 @@ export const WORK_WRITE_PROPERTIES = {
     work_type: {
         type: "string",
         description: "Type of work",
-        enum: ["song", "instrumental", "library", "demo", "sample"],
+        enum: [...WORK_TYPE_VALUES],
     },
     work_status: {
         type: "string",
@@ -120,6 +123,15 @@ export const WORK_WRITE_PROPERTIES = {
         type: "string",
         description: "Primary artist person ID (FK to people)",
     },
+    disambiguation: {
+        type: ["string", "null"],
+        maxLength: 200,
+        description: "A short note that tells apart two DIFFERENT songs with the same title and primary artist — e.g. 'theme', '2019 song', 'live-only composition' (MusicBrainz's term). " +
+            "Set it ONLY when two genuinely different songs share title + artist; the cue is a WORK_ALREADY_EXISTS refusal for a song you know is not the existing one. " +
+            "Leave it unset otherwise — it is part of the duplicate check, so an invented note would let a real duplicate in. " +
+            "If the two are the same song, use or merge the existing work instead. Not a version label: recording versions (live, remix, acoustic) belong on pica_recordings_create. " +
+            "null or '' clears it.",
+    },
     display_artist: {
         type: "string",
         description: "Display-friendly artist string (e.g. 'Jane Doe ft. John Smith')",
@@ -142,7 +154,7 @@ export const WORK_WRITE_PROPERTIES = {
     },
     notes: {
         type: "string",
-        description: "Internal notes",
+        description: "Internal notes. Setting this REPLACES the whole field — to add a line, use append_notes on pica_works_update instead.",
     },
     metadata: {
         type: "object",
@@ -200,6 +212,14 @@ function summariseDossier(dossier) {
         `Consent: ${consentState}${consentLevel}. Completeness: ${completeness}. ` +
         `(Full payload under structuredContent.data.dossier; PDF / multi-work ZIP: pica_export_song_dossiers.)`);
 }
+/**
+ * Page caps for the two health_filter branches of pica_works_query — the
+ * routes' own maxima (app/api/admin/quality/works-health/route.ts and
+ * .../completeness/low-score/route.ts). Hand-copied (this package cannot
+ * import the app); no test ties them — change both together.
+ */
+const WORKS_HEALTH_MAX_PAGE = 50;
+const LOW_COMPLETENESS_MAX_PAGE = 200;
 export class WorksTools {
     pica;
     constructor(pica) {
@@ -247,7 +267,7 @@ export class WorksTools {
                         properties: {
                             query: {
                                 type: "string",
-                                description: "Search by title, ISWC, or artist name",
+                                description: "Search by title, ISWC, or artist name. An artist name also finds works linked to that artist through a recording's artist or a credited person, even when the work's primary_artist is empty or spelled differently (appended after the direct matches, up to 300).",
                             },
                             verified: {
                                 type: "boolean",
@@ -256,7 +276,7 @@ export class WorksTools {
                             health_filter: {
                                 type: "string",
                                 enum: ["needs_attention", "low_completeness"],
-                                description: "Filter by health status — needs_attention (cross-org reconciliation problems: unreconciled composition/master chains, split discrepancies) or low_completeness (below completeness score threshold: missing ISWC, credits, etc.)",
+                                description: "Filter by health status — needs_attention (cross-org reconciliation problems: unreconciled composition/master chains, split discrepancies) or low_completeness (below completeness score threshold: missing ISWC, credits, etc.). Both honour limit/offset. low_completeness reports `total` = works below the threshold by their stored score (max 200 per page). needs_attention checks at most 50 works per call and `offset` counts works CHECKED, not rows returned — a page can hold fewer rows than limit while more remain, so continue from next_offset until it is null; its `total` is set only when one call from offset 0 checks every candidate, otherwise it is null and the answer is the rows counted across pages.",
                             },
                             has_statement_data: {
                                 type: "boolean",
@@ -304,7 +324,7 @@ export class WorksTools {
                             },
                             work_type: {
                                 type: "string",
-                                enum: ["song", "instrumental", "library", "demo", "sample"],
+                                enum: [...WORK_TYPE_VALUES],
                                 description: "Filter by work type. 'instrumental' answers 'my instrumentals'.",
                             },
                             work_status: {
@@ -337,11 +357,11 @@ export class WorksTools {
                             },
                             primary_artist: {
                                 type: "string",
-                                description: "Exact primary-artist name match.",
+                                description: "Exact primary-artist name match. Misses works whose primary_artist is empty — use `query` to include works linked by recording artist or credits.",
                             },
                             artist: {
                                 type: "string",
-                                description: "Exact primary-artist name match (alias).",
+                                description: "Exact primary-artist name match (alias). Misses works whose primary_artist is empty — use `query` to include works linked by recording artist or credits.",
                             },
                             label: {
                                 type: "string",
@@ -468,7 +488,7 @@ export class WorksTools {
                                         "dossier",
                                     ],
                                 },
-                                description: 'Which data sections to include. Omit for all sections. Use ["basic"] for lightweight lookup. "licensing" surfaces the AI-disclosure / training-rights / provenance-attestation compliance fields (work_licensing satellite) in one scoped view. "dossier" assembles the full song dossier (recordings, releases, credits, people, provenance, AI disclosure, consent) — heavy, so it is opt-in only (never part of the default all-sections response); for the PDF, or several works in one ZIP, use pica_export_song_dossiers.',
+                                description: 'Which data sections to include. Omit for all sections. Use ["basic"] for lightweight lookup. "health" is a short summary of THIS work\'s completeness (score, missing critical fields, suggestions) — opt-in, since "completeness" carries the full breakdown; for works across the catalogue needing attention use pica_works_query health_filter. "licensing" surfaces the AI-disclosure / training-rights / provenance-attestation compliance fields (work_licensing satellite) in one scoped view. "dossier" assembles the full song dossier (recordings, releases, credits, people, provenance, AI disclosure, consent) — heavy, so it is opt-in only (never part of the default all-sections response); for the PDF, or several works in one ZIP, use pica_export_song_dossiers.',
                             },
                         },
                         required: [],
@@ -515,7 +535,9 @@ export class WorksTools {
                         "mastering human-made, AI-assisted, or AI-generated? (Those four " +
                         "are set independently on ai_disclosure.) Always run " +
                         "pica_works_query first to check for a duplicate — two same-title " +
-                        "works cause split and registration trouble. Album, artwork, " +
+                        "works cause split and registration trouble. If a refusal says the " +
+                        "work already exists but it really is a different song with the same " +
+                        "title and artist, retry with disambiguation (e.g. 'theme'). Album, artwork, " +
                         "track number, UPC, and Spotify URL live on the release " +
                         "(pica_releases_create/update), not here; label too, via the " +
                         "release (resolve the label name with pica_labels_query first). " +
@@ -570,6 +592,7 @@ export class WorksTools {
                         "MCP; set them through a release or recording path. " +
                         "Three jsonb compliance fields (ai_disclosure, provenance_attestation, training_rights) route " +
                         "to that same work_licensing satellite table and ARE set-able here. " +
+                        "Answers with a compact receipt — the id, each field you sent with the value now stored, and only the gaps this write opened; pass verbose: true for the full work. " +
                         "→ then: pica_works_inspect (verify changes persisted)",
                     workflows: ["work-required"],
                     vernacular_kind: "specialist",
@@ -582,6 +605,14 @@ export class WorksTools {
                                 description: "Work ID (required)",
                             },
                             ...WORK_WRITE_PROPERTIES,
+                            ...VERBOSE_PROPERTY,
+                            append_notes: {
+                                type: "string",
+                                maxLength: 10000,
+                                description: "Text to add to the end of the work's notes, on a new line, without reading or rewriting what is there. " +
+                                    "Safe when someone else edits the work at the same time (a conflict is retried, never overwritten). " +
+                                    "Cannot be sent together with notes.",
+                            },
                         },
                         required: ["id"],
                     },
@@ -609,7 +640,7 @@ export class WorksTools {
                     description: "Delete a musical work. It is automatically unlinked from any " +
                         "releases it appears on (the release keeps its track). If the work " +
                         "still has dependent records (recordings, royalty payments, version " +
-                        "links, claims) it is archived instead — hidden from the catalog but " +
+                        "links, claims, signed split sheets) it is archived instead — hidden from the catalog but " +
                         "preserved — and the result tells you exactly what to remove to " +
                         "delete it permanently. A work with registry identifiers " +
                         "(ISRC/ISWC/MLC) is always archived, never destroyed. The result " +
@@ -637,8 +668,11 @@ export class WorksTools {
                     scope: "write:catalog",
                     audiences: ["stdio", "http", "public"],
                     tier: "write",
-                    description: "Mark a work's metadata as human-verified after user review — a catalog quality flag, " +
-                        "not a registration check (that's pica_works_verify_registrations).",
+                    description: "Writes nothing: PICA keeps no single 'verified' flag on a work. Returns " +
+                        "NO_WORK_VERIFIED_FLAG naming what the person can confirm themselves, signed in, " +
+                        "on /inspect — the human-made stamp, their own writer credit, their own master " +
+                        "share. Not a registration check (that's pica_works_verify_registrations). To " +
+                        "review a work, use pica_works_inspect.",
                     workflows: "infrastructure",
                     vernacular_kind: "specialist",
                     vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
@@ -669,7 +703,11 @@ export class WorksTools {
                         "how, and an optional signature hash (the raw signature itself is " +
                         "never stored). Sync libraries and provenance certificates use it " +
                         "to prove human authorship. To change or undo one, use the " +
-                        "provenance revocation tools. After stamping, read it back with " +
+                        "provenance revocation tools. Only a signed-in person can make " +
+                        "this statement: an API key, connected app or agent is refused " +
+                        "with ATTESTATION_REQUIRES_HUMAN_SESSION — do not retry; tell the " +
+                        "user to use 'stamp as human-made' at /inspect/works/<id>#human-made. " +
+                        "After stamping, read it back with " +
                         "pica_works_inspect (sections: ['provenance']). → then: " +
                         "pica_works_inspect (verify it persisted), " +
                         "pica_provenance_certificate (generate a PDF)",
@@ -743,7 +781,7 @@ export class WorksTools {
                         "mode 'confirm_unregistered' records the user's own confirmation instead (no lookup; " +
                         "society_code optional — omitted means 'not registered with any society'). " +
                         "Idempotent — re-running refreshes checked_at. " +
-                        "For a human-verified metadata flag rather than a registration check, use pica_works_verify.",
+                        "This is a registration check, not a human sign-off — a person's own statement that a human made the work is pica_works_attest (signed-in only).",
                     workflows: ["work-required"],
                     vernacular_kind: "specialist",
                     vernacular_reason: "Specialist context; not yet covered by the Creator Question Atlas — pending telemetry-driven addition per ADR-226 Phase 4 substrate writes.",
@@ -859,21 +897,68 @@ export class WorksTools {
     async queryWorks(args) {
         const limit = args.limit || 50;
         const offset = args.offset || 0;
-        // Health filter routes to health/completeness APIs
+        // Health filter routes to health/completeness APIs.
+        //
+        // ⚠️ Both branches used to call the bare SDK method with no arguments,
+        // so `limit`/`offset` were ignored (the routes' own default of 20 won)
+        // and `total` was the length of that page — an agent asking for 100
+        // low-completeness works got 20 and was told there were 20 (ops issue
+        // 314325eb, 2026-09-25). Both now thread limit/offset through and report
+        // only the totals the server can actually vouch for.
         if (args.health_filter === "needs_attention") {
-            const result = await this.pica.health.getWorksHealth();
-            const works = Array.isArray(result) ? result : result?.works || [];
+            // Each candidate is a full cross-org chain assembly, so the route caps
+            // a page at 50 candidates; `offset` pages candidates, not results.
+            const page = await this.pica.health.getWorksHealthPage({
+                limit: Math.min(limit, WORKS_HEALTH_MAX_PAGE),
+                offset,
+                unreconciledOnly: true,
+            });
+            const works = page.data;
+            const meta = page.meta;
+            // No meta (an older server) means nothing is known about the rest of
+            // the set: treat it as "more may remain" rather than "done".
+            const hasMore = meta ? meta.has_more : works.length > 0;
+            // A total is only claimed when THIS call, starting at offset 0, checked
+            // every candidate and the server said so (meta.has_more false).
+            // Otherwise the page length is not passed off as the total.
+            const wholeSetScanned = offset === 0 && meta !== undefined && !hasMore;
             return formatStructuredList(works, "work", {
                 filter: "needs_attention",
-                total: works.length,
+                total: wholeSetScanned ? works.length : null,
+                ...(wholeSetScanned
+                    ? {}
+                    : {
+                        total_note: hasMore
+                            ? "no total yet — the number needing attention is known only after every candidate work is checked; keep paging with next_offset and count the rows across pages"
+                            : "this was the last page — the number needing attention is the rows counted across the pages you fetched",
+                    }),
+                limit: meta?.limit ?? Math.min(limit, WORKS_HEALTH_MAX_PAGE),
+                offset,
+                scanned: meta?.scanned ?? null,
+                candidates_total: meta?.candidates_total ?? null,
+                hasMore,
+                next_offset: meta?.next_offset ?? null,
             });
         }
         if (args.health_filter === "low_completeness") {
-            const result = await this.pica.health.getLowScoreWorks();
-            const works = Array.isArray(result) ? result : result?.works || [];
+            const page = await this.pica.health.getLowScoreWorksPage({
+                limit: Math.min(limit, LOW_COMPLETENESS_MAX_PAGE),
+                offset,
+            });
+            const works = page.data;
+            const meta = page.meta;
+            const appliedLimit = meta?.limit ?? Math.min(limit, LOW_COMPLETENESS_MAX_PAGE);
+            const total = meta?.total ?? null;
+            const hasMore = meta?.has_more ??
+                (total === null ? works.length >= appliedLimit : false);
             return formatStructuredList(works, "work", {
                 filter: "low_completeness",
-                total: works.length,
+                threshold: meta?.threshold,
+                total,
+                limit: appliedLimit,
+                offset,
+                hasMore,
+                next_offset: hasMore ? offset + appliedLimit : null,
             });
         }
         // ADR-244 PR (c) §3.8 / §3.9 — queryable + sortable signals threaded
@@ -1008,8 +1093,12 @@ export class WorksTools {
         const allSections = !sections || sections.length === 0;
         // Sections kept OFF the default `allSections` surface but still callable
         // via explicit `sections`:
-        //  - ADR-201 closeout (2026-04-27): `health` and `score` are org-wide
-        //    metrics that don't take a workId and cost ~25s / ~2s on staging.
+        //  - `health` is a summary of THIS work's completeness (the same
+        //    single-work read as `completeness`), so on the default surface it
+        //    would only repeat that section. Until 2026-09-26 it read the
+        //    ORG-WIDE works-health scan instead — ~25s, and about other works.
+        //  - `score` (ADR-201 closeout, 2026-04-27) is the org-wide PICA score;
+        //    it takes no workId.
         //  - `dossier` (2026-07-12) assembles the whole song (recordings,
         //    releases, credits, people, provenance, consent) — a heavy superset of
         //    the other sections, redundant on the default surface and worth its
@@ -1103,7 +1192,8 @@ export class WorksTools {
             }
         }
         // ADR-201 closeout (2026-04-27): the section sub-calls used to run
-        // sequentially. With ~8 calls each taking ~1s and one (works-health)
+        // sequentially. With ~8 calls each taking ~1s and one (the org-wide
+        // works-health scan `health` read until 2026-09-26)
         // sometimes 25s+, the function would frequently exceed Vercel's 30s
         // maxDuration on the default `allSections` path. Fan out everything
         // in parallel — each branch still owns its own try/catch fallback so
@@ -1145,11 +1235,22 @@ export class WorksTools {
                 })());
             }
         }
-        // Quality sections — fan out in parallel.
+        // Quality sections — fan out in parallel. `health` and `completeness`
+        // share ONE read of this work's completeness route.
+        let completenessRead = null;
+        const readCompleteness = () => (completenessRead ??= this.pica.health.getWorkCompleteness(workId));
         if (has("health")) {
             sectionTasks.push((async () => {
                 try {
-                    result.health = await this.pica.health.getWorksHealth();
+                    const c = await readCompleteness();
+                    result.health = {
+                        scope: "work",
+                        work_id: workId,
+                        score: c?.score ?? null,
+                        missing_field_count: c?.missing_field_count ?? null,
+                        missing_critical: c?.missingCritical ?? [],
+                        suggestions: c?.suggestions ?? [],
+                    };
                 }
                 catch (e) {
                     result.health = null;
@@ -1160,9 +1261,34 @@ export class WorksTools {
         if (has("completeness")) {
             sectionTasks.push((async () => {
                 try {
-                    const completeness = await this.pica.health.getWorkCompleteness(workId);
+                    const completeness = await readCompleteness();
                     result.completeness = completeness;
                     hints.push(...mapGapsToHints(completeness?.gaps || completeness?.missing || []));
+                    // ops_issue 1bc63a6d — only an instrumental/PA is attached. The
+                    // candidates (unassigned files whose name matches the title) sit
+                    // in completeness.audio.gap; they are for the user to confirm.
+                    if (completeness?.audio?.checked === false) {
+                        hints.push({
+                            gap: "audio_check_unavailable",
+                            suggestion: "PICA could not check this work's attached audio just now, so an 'only an instrumental is attached' gap may be missing from this answer.",
+                            severity: "nice_to_have",
+                        });
+                    }
+                    const vocalGap = completeness?.audio?.gap;
+                    if (vocalGap && typeof vocalGap.label === "string") {
+                        const ids = Array.isArray(vocalGap.candidates)
+                            ? vocalGap.candidates
+                                .map((c) => c.audio_file_id)
+                                .filter(Boolean)
+                            : [];
+                        hints.push({
+                            gap: "only_instrumental_attached",
+                            suggestion: ids.length > 0
+                                ? `${vocalGap.label} (${ids.join(", ")}). If the user confirms one is the vocal master, it can be attached with pica_audio_assign.`
+                                : `${vocalGap.label}.`,
+                            severity: "important",
+                        });
+                    }
                 }
                 catch (e) {
                     result.completeness = null;
@@ -1426,13 +1552,33 @@ export class WorksTools {
      * Update work
      */
     async updateWork(args) {
-        const { id, ...updates } = args;
+        const { verbose, rest } = takeVerbose(args);
+        const { id, ...updates } = rest;
+        // Compact receipt (ops 61ce1dcc): read the gaps open BEFORE the write so
+        // the answer can name only the ones this write opened. Skipped when the
+        // caller asked for the full record, which repeats every gap anyway.
+        const before = verbose
+            ? null
+            : await buildIntegrityPressure(this.pica, "work", id);
         const work = await this.pica.works.update(id, updates);
         // Registration integrity floor (Task 9) — same pressure rendering as
         // createWork, so an update that clears (or introduces) a gap keeps the
         // agent informed without a separate inspect round-trip.
         const pressure = await buildIntegrityPressure(this.pica, "work", work.id);
-        return formatSuccess("Work updated successfully", { ...work, integrity: pressure.integrity }, pressure.hints);
+        if (verbose) {
+            return formatSuccess("Work updated successfully", { ...work, integrity: pressure.integrity }, pressure.hints);
+        }
+        const openBefore = before?.integrity
+            ? new Set(before.integrity.gaps.map((g) => g.code))
+            : null;
+        const { changed, unconfirmed } = changedFields(updates, work);
+        return formatSuccess("Work updated successfully", {
+            id: work?.id ?? id,
+            changed,
+            ...(unconfirmed.length > 0 ? { unconfirmed } : {}),
+            integrity: slimIntegrity(pressure.integrity, openBefore),
+            receipt: RECEIPT_NOTE,
+        }, newHintsOnly(before?.integrity ? before.hints : null, pressure.hints));
     }
     /**
      * Delete work
@@ -1442,44 +1588,28 @@ export class WorksTools {
         return formatDeletion("work", args.id, outcome);
     }
     /**
-     * Verify work
+     * pica_works_verify — writes nothing, and says so.
+     *
+     * It used to PATCH `is_verified: true` onto the work. `works` has no such
+     * column (no applied migration adds one), so the route's allowed-field check
+     * refused it on every call — its only two calls ever both failed (DonnySavv,
+     * feedback 86e26f75, 2026-09-28). PICA keeps no work-level "metadata
+     * verified" flag, and inventing one would record an agreement nobody made.
+     * What a person CAN confirm lives on specific records, each refused to
+     * agents and each done by the person on /inspect — this names them.
      */
     async verifyWork(args) {
-        const work = await this.pica.works.verify(args.id);
-        // ADR-146: Also check export readiness
-        let exportReadiness;
-        try {
-            const baseUrl = this.pica.works["baseUrl"];
-            const apiKey = this.pica.works["apiKey"];
-            const res = await fetch(`${baseUrl}/admin/export-readiness/${args.id}`, {
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
-            });
-            if (res.ok) {
-                const json = (await res.json());
-                exportReadiness = json.data ?? json;
-            }
-        }
-        catch {
-            // Readiness check is best-effort — don't fail verification
-        }
-        const summaryParts = ["Work verified successfully"];
-        if (exportReadiness) {
-            summaryParts.push(`Export readiness: ${exportReadiness.ready ? "ready" : "not ready"}`, `Evidence: ${exportReadiness.evidenceStrength}`, `Attestation: ${exportReadiness.attestationCoverage}%`);
-            if (Array.isArray(exportReadiness.blockers) &&
-                exportReadiness.blockers.length > 0) {
-                summaryParts.push(`Blockers (${exportReadiness.blockers.length}):`);
-                for (const b of exportReadiness.blockers) {
-                    summaryParts.push(`  ${b.type}: ${b.resolutionHint}`);
-                }
-            }
+        const workId = typeof args.id === "string" ? args.id.trim() : "";
+        if (!workId) {
+            return typedError("VALIDATION_ERROR", "id is required.");
         }
-        return formatSuccess(summaryParts.join("\n"), {
-            ...work,
-            exportReadiness,
-        });
+        return typedError("NO_WORK_VERIFIED_FLAG", "PICA does not keep a single 'verified' flag on a work, so nothing was written. " +
+            "What a person can confirm, each while signed in to PICA (an assistant cannot do these for them): " +
+            `(1) the human-made stamp — "stamp as human-made" at /inspect/works/${workId}#human-made; ` +
+            `(2) their own writer credit — confirm it in the credits table on /inspect/works/${workId}; ` +
+            '(3) their own master ownership share — "confirm my share" under ownership splits at ' +
+            "/inspect/recordings/<recording_id>#ownership-splits. " +
+            "To review what is missing or unconfirmed on the work, use pica_works_inspect.");
     }
     /**
      * Bulk delete works