@withpica/mcp-server 2.102.0 → 2.104.0

package/dist/tools/relationship-change.d.ts

@@ -0,0 +1,16 @@
+import type { ToolResult } from "./index.js";
+export type ChangeOutcome<T> = {
+    kind: "proposed";
+    reference: string;
+    expiresAt: string | null;
+} | {
+    kind: "applied";
+    record: T;
+};
+export declare function readChangeOutcome<T>(answer: unknown): ChangeOutcome<T>;
+/** The answer for a change sent to the client as a proposal. */
+export declare function formatProposedChange(entity: "work" | "recording", id: string, fields: string[], outcome: {
+    reference: string;
+    expiresAt: string | null;
+}): ToolResult;
+//# sourceMappingURL=relationship-change.d.ts.map

package/dist/tools/relationship-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-change.d.ts","sourceRoot":"","sources":["../../src/tools/relationship-change.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,aAAa,CAAC,CAAC,IACvB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC;AAEnC,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,aAAa,CAAC,CAAC,CAAC,CAgCtE;AAED,gEAAgE;AAChE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,WAAW,EAC5B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACvD,UAAU,CAYZ"}

package/dist/tools/relationship-change.js

@@ -0,0 +1,60 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * What a song or recording edit in a CLIENT's catalogue came back as
+ * (ADR-333 PR 1.3).
+ *
+ * PATCH /api/admin/works/:id and /recordings/:id, named for a client
+ * catalogue, answer one of two envelopes (clientCataloguePatch in each route,
+ * lib/services/relationship-proposals.ts changeThroughRelationship):
+ *   - a proposal, 202 `{ applied: false, proposal_reference, expires_at,
+ *     message }`: nothing has changed; the client's owners decide it;
+ *   - a direct change (an administrator), `{ applied: true, result }`: the
+ *     updated record is `result`.
+ * In the caller's own catalogue the answer is the record itself.
+ *
+ * The MCP callers of those two routes (updateWork, updateRecording,
+ * pica_enrichment_clear) read the answer here, so a proposal is not reported
+ * as "updated" and a direct change's record is read from `result` (D2 Gate 2,
+ * holdout run 38435148161: pica_works_update answered "Work updated
+ * successfully" for a representative's proposal). A new caller that skips
+ * this fails tools/__tests__/client-catalogue-replies.test.ts ("every caller
+ * of works.update / recordings.update reads the change outcome").
+ */
+import { currentCatalogue } from "@withpica/mcp-sdk";
+import { formatSuccess } from "@withpica/mcp-utils";
+export function readChangeOutcome(answer) {
+    if (answer && typeof answer === "object" && "applied" in answer) {
+        const a = answer;
+        if (a.applied === false) {
+            // A proposal with no reference cannot be followed up: say so rather
+            // than report either outcome.
+            if (typeof a.proposal_reference !== "string" || !a.proposal_reference)
+                throw new Error("the change was not applied, and no proposal reference came back");
+            return {
+                kind: "proposed",
+                reference: a.proposal_reference,
+                expiresAt: typeof a.expires_at === "string" ? a.expires_at : null,
+            };
+        }
+        if (a.applied === true && "result" in a)
+            return { kind: "applied", record: a.result };
+    }
+    // In a client's catalogue the route always answers one of the two
+    // envelopes. Anything else means the envelope changed: refuse to call it
+    // applied, or a proposal would be reported as "updated" again.
+    if (currentCatalogue() !== undefined)
+        throw new Error("the change's outcome in this client's catalogue could not be read: neither applied nor proposed came back");
+    return { kind: "applied", record: answer };
+}
+/** The answer for a change sent to the client as a proposal. */
+export function formatProposedChange(entity, id, fields, outcome) {
+    return formatSuccess(`Proposed to the client: nothing changes until one of the catalogue's owners approves it`, {
+        id,
+        entity,
+        applied: false,
+        proposed_fields: fields,
+        proposal_reference: outcome.reference,
+        expires_at: outcome.expiresAt,
+    });
+}
+//# sourceMappingURL=relationship-change.js.map

package/dist/tools/relationship-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-change.js","sourceRoot":"","sources":["../../src/tools/relationship-change.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAOpD,MAAM,UAAU,iBAAiB,CAAI,MAAe;IAClD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;QAChE,MAAM,CAAC,GAAG,MAKT,CAAC;QACF,IAAI,CAAC,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;YACxB,oEAAoE;YACpE,8BAA8B;YAC9B,IAAI,OAAO,CAAC,CAAC,kBAAkB,KAAK,QAAQ,IAAI,CAAC,CAAC,CAAC,kBAAkB;gBACnE,MAAM,IAAI,KAAK,CACb,iEAAiE,CAClE,CAAC;YACJ,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,SAAS,EAAE,CAAC,CAAC,kBAAkB;gBAC/B,SAAS,EAAE,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI;aAClE,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,QAAQ,IAAI,CAAC;YACrC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,MAAW,EAAE,CAAC;IACtD,CAAC;IACD,kEAAkE;IAClE,yEAAyE;IACzE,+DAA+D;IAC/D,IAAI,gBAAgB,EAAE,KAAK,SAAS;QAClC,MAAM,IAAI,KAAK,CACb,2GAA2G,CAC5G,CAAC;IACJ,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAW,EAAE,CAAC;AAClD,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,oBAAoB,CAClC,MAA4B,EAC5B,EAAU,EACV,MAAgB,EAChB,OAAwD;IAExD,OAAO,aAAa,CAClB,yFAAyF,EACzF;QACE,EAAE;QACF,MAAM;QACN,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,MAAM;QACvB,kBAAkB,EAAE,OAAO,CAAC,SAAS;QACrC,UAAU,EAAE,OAAO,CAAC,SAAS;KAC9B,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/relationship-copy.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ADR-333 — plain words for a relationship (who looks after whose
+ * catalogue), as the assistant tools say them.
+ *
+ * The MCP package cannot import the app, so this keeps its own copy of what
+ * the screens say: the type labels and statuses (from
+ * lib/services/portfolio-relationship-model.ts), the screen addresses (from
+ * lib/config/relationship-paths.ts), and the status and history sentences
+ * (from app/inspect/lib/relationship-copy.ts). The tools and the screens
+ * cannot say different things without
+ * lib/services/__tests__/relationship-scope-mcp-parity.test.ts failing: it
+ * compares every constant here with the app's and runs both sentence
+ * builders over every status and event kind.
+ *
+ * Pure: no imports.
+ */
+export declare const GRANTABLE_RELATIONSHIP_TYPES: readonly ["co_owner", "administrator", "representative", "viewer"];
+export type RelationshipTypeName = (typeof GRANTABLE_RELATIONSHIP_TYPES)[number];
+export declare const RELATIONSHIP_TYPE_LABELS: Record<RelationshipTypeName, string>;
+export declare const RELATIONSHIP_STATUSES: readonly ["proposed", "active", "declined", "revoked", "stepped_down", "expired", "suspended"];
+export type RelationshipStatusName = (typeof RELATIONSHIP_STATUSES)[number];
+/** What a type may do, said to the catalogue's owner. */
+export declare const TYPE_DOES: Record<RelationshipTypeName, string>;
+/** The same allowances, said to the organisation that holds them. */
+export declare const TYPE_DOES_FOR_ORG: Record<RelationshipTypeName, string>;
+export declare const RELATIONSHIPS_PATH = "/inspect/relationships";
+export declare function relationshipPath(relationshipId: string): string;
+export declare const INVITATIONS_FOR_YOU_PATH = "/inspect/relationships#invitations-for-you";
+export declare function relationshipActivityPath(granteeOrgId?: string): string;
+/** Hand-overs (ADR-333 D5); the app's are lib/config/handover-paths.ts. */
+export declare const HANDOVERS_PATH = "/inspect/handovers";
+export declare function handoverPath(handoverId: string): string;
+export declare const NEW_HANDOVER_PATH = "/inspect/handovers/new";
+export type ReaderSide = "grantor" | "grantee";
+/** The fields statusLine reads (a RelationshipRecord satisfies it). */
+export interface RelationshipForCopy {
+    status: RelationshipStatusName;
+    proposedBySide: ReaderSide;
+    grantorOrgName: string;
+    granteeOrgName: string;
+    proposedAt: string;
+    respondedAt: string | null;
+    endedAt: string | null;
+    endReason: string | null;
+    proposalExpiresAt: string | null;
+    suspendedAt: string | null;
+    scope: {
+        termEndsOn: string | null;
+    };
+}
+export interface StatusLine {
+    text: string;
+    /** The reader has to answer it. */
+    needsYou: boolean;
+}
+/** Where a relationship stands, for the side reading it. */
+export declare function statusLine(r: RelationshipForCopy, reader: ReaderSide): StatusLine;
+/** The fields eventLine reads (a RelationshipEventRecord satisfies it). */
+export interface RelationshipEventForCopy {
+    kind: string;
+    actorSide: "grantor" | "grantee" | "system" | "platform";
+    actorDisplayName: string | null;
+    grantorOrgName: string;
+    granteeOrgName: string;
+    type: RelationshipTypeName;
+    reason: string | null;
+    action: string | null;
+    entityType: string | null;
+    scope: {
+        termEndsOn: string | null;
+    };
+    detail?: Record<string, unknown>;
+}
+/** One audit row as a sentence: who did what, through which relationship. */
+export declare function eventLine(e: RelationshipEventForCopy): string;
+/** The fields scopeSummary reads. */
+export interface ScopeForCopy {
+    half: "both" | "composition" | "master";
+    territories: string[];
+    termStartsOn: string | null;
+    termEndsOn: string | null;
+    money: boolean;
+    directory: boolean;
+    catalogue: "whole" | "chosen";
+    workIds?: string[];
+    recordingIds?: string[];
+    songsChosen?: number;
+    recordingsChosen?: number;
+}
+/**
+ * The scope in one line for the side reading it: what, which side, where,
+ * when, money and (administrators) the directory. Territories are ISO codes
+ * here ("GB, IE"); the screens spell the country names.
+ */
+export declare function scopeSummary(scope: ScopeForCopy, type: RelationshipTypeName, reader: {
+    side: ReaderSide;
+    grantorName: string;
+}): string;
+//# sourceMappingURL=relationship-copy.d.ts.map

package/dist/tools/relationship-copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-copy.d.ts","sourceRoot":"","sources":["../../src/tools/relationship-copy.ts"],"names":[],"mappings":"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"}

package/dist/tools/relationship-copy.js

@@ -0,0 +1,213 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * ADR-333 — plain words for a relationship (who looks after whose
+ * catalogue), as the assistant tools say them.
+ *
+ * The MCP package cannot import the app, so this keeps its own copy of what
+ * the screens say: the type labels and statuses (from
+ * lib/services/portfolio-relationship-model.ts), the screen addresses (from
+ * lib/config/relationship-paths.ts), and the status and history sentences
+ * (from app/inspect/lib/relationship-copy.ts). The tools and the screens
+ * cannot say different things without
+ * lib/services/__tests__/relationship-scope-mcp-parity.test.ts failing: it
+ * compares every constant here with the app's and runs both sentence
+ * builders over every status and event kind.
+ *
+ * Pure: no imports.
+ */
+export const GRANTABLE_RELATIONSHIP_TYPES = [
+    "co_owner",
+    "administrator",
+    "representative",
+    "viewer",
+];
+export const RELATIONSHIP_TYPE_LABELS = {
+    co_owner: "co-owner with a share",
+    administrator: "administrator",
+    representative: "representative",
+    viewer: "viewer",
+};
+export const RELATIONSHIP_STATUSES = [
+    "proposed",
+    "active",
+    "declined",
+    "revoked",
+    "stepped_down",
+    "expired",
+    "suspended",
+];
+/** What a type may do, said to the catalogue's owner. */
+export const TYPE_DOES = {
+    administrator: "can edit and register your songs and send exports for you. changes to splits or custody come to you to approve.",
+    representative: "can see and export what's in scope, and suggest changes. every change to your record comes to you to approve first.",
+    viewer: "can see and export what's in scope, and nothing else.",
+    co_owner: "can see the songs and recordings it has a share in. it can't change your facts.",
+};
+/** The same allowances, said to the organisation that holds them. */
+export const TYPE_DOES_FOR_ORG = {
+    administrator: "can edit and register their songs and send exports for them. changes to splits or custody go to them to approve.",
+    representative: "can see and export what's in scope, and suggest changes. every change to their record goes to them to approve first.",
+    viewer: "can see and export what's in scope, and nothing else.",
+    co_owner: "can see the songs and recordings it has a share in. it can't change their facts.",
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Screen addresses (paths; the tools prefix the web origin)
+// ─────────────────────────────────────────────────────────────────────────────
+export const RELATIONSHIPS_PATH = "/inspect/relationships";
+export function relationshipPath(relationshipId) {
+    return `${RELATIONSHIPS_PATH}/${encodeURIComponent(relationshipId)}`;
+}
+export const INVITATIONS_FOR_YOU_PATH = `${RELATIONSHIPS_PATH}#invitations-for-you`;
+export function relationshipActivityPath(granteeOrgId) {
+    return granteeOrgId
+        ? `${RELATIONSHIPS_PATH}/activity?org=${encodeURIComponent(granteeOrgId)}`
+        : `${RELATIONSHIPS_PATH}/activity`;
+}
+/** Hand-overs (ADR-333 D5); the app's are lib/config/handover-paths.ts. */
+export const HANDOVERS_PATH = "/inspect/handovers";
+export function handoverPath(handoverId) {
+    return `${HANDOVERS_PATH}/${encodeURIComponent(handoverId)}`;
+}
+export const NEW_HANDOVER_PATH = `${HANDOVERS_PATH}/new`;
+/** Where a relationship stands, for the side reading it. */
+export function statusLine(r, reader) {
+    const other = reader === "grantor" ? r.granteeOrgName : r.grantorOrgName;
+    const day = (iso) => (iso ? iso.slice(0, 10) : "");
+    switch (r.status) {
+        case "proposed": {
+            const lapses = r.proposalExpiresAt
+                ? ` · expires ${day(r.proposalExpiresAt)}`
+                : "";
+            return r.proposedBySide === reader
+                ? { text: `waiting for ${other} to answer${lapses}`, needsYou: false }
+                : {
+                    text: `${other} is asking · needs your answer${lapses}`,
+                    needsYou: true,
+                };
+        }
+        case "suspended":
+            return {
+                text: `paused by pica ${day(r.suspendedAt)} · it grants nothing while paused. ask pica if you have questions.`,
+                needsYou: false,
+            };
+        case "active":
+            return {
+                text: `active since ${day(r.respondedAt) || day(r.proposedAt)}${r.scope.termEndsOn ? ` · ends ${r.scope.termEndsOn}` : ""}`,
+                needsYou: false,
+            };
+        case "declined":
+            return { text: `declined ${day(r.respondedAt)}`, needsYou: false };
+        case "revoked":
+            return { text: `ended by the owner ${day(r.endedAt)}`, needsYou: false };
+        case "stepped_down":
+            return {
+                text: `${r.granteeOrgName} stepped down ${day(r.endedAt)}`,
+                needsYou: false,
+            };
+        case "expired":
+            return {
+                text: r.endReason === "proposal_unanswered"
+                    ? `lapsed unanswered ${day(r.endedAt)}`
+                    : `term ended ${day(r.endedAt)}`,
+                needsYou: false,
+            };
+    }
+}
+/** One audit row as a sentence: who did what, through which relationship. */
+export function eventLine(e) {
+    const org = e.actorSide === "grantor"
+        ? e.grantorOrgName
+        : e.actorSide === "grantee"
+            ? e.granteeOrgName
+            : null;
+    // The PICA team acts as PICA: its people are not named to customers.
+    const who = e.actorSide === "platform"
+        ? "pica"
+        : e.actorDisplayName
+            ? org
+                ? `${e.actorDisplayName} (${org})`
+                : e.actorDisplayName
+            : (org ?? "pica");
+    const type = RELATIONSHIP_TYPE_LABELS[e.type] ?? humanise(e.type);
+    switch (e.kind) {
+        case "proposed":
+            return `${who} proposed ${e.granteeOrgName} as ${type}`;
+        case "accepted":
+            return `${who} accepted ${e.granteeOrgName} as ${type}`;
+        case "declined":
+            return `${who} declined`;
+        case "scope_changed":
+            return `${who} changed what's covered`;
+        case "revoked":
+            return `${who} ended the relationship`;
+        case "stepped_down":
+            return `${who} stepped down`;
+        case "expired":
+            return e.reason === "proposal_unanswered"
+                ? "the request lapsed unanswered"
+                : "the term ended";
+        case "term_ending_soon": {
+            const on = detailDate(e, "term_ends_on") ?? e.scope.termEndsOn;
+            return `the term ends on ${on ?? "its end date"}`;
+        }
+        case "proposal_expiring_soon": {
+            const on = detailDate(e, "proposal_expires_at");
+            return `the request lapses${on ? ` on ${on}` : " soon"} if nobody answers`;
+        }
+        case "suspended":
+            return "pica paused it: it grants nothing while paused";
+        case "reinstated":
+            return "pica resumed it";
+        case "acted":
+            return `${who} ${humanise(e.action) || "acted"}${e.entityType ? ` · ${humanise(e.entityType)}` : ""}`;
+        default:
+            // A kind added after this copy: said by its name, never dropped.
+            return `${who} · ${humanise(e.kind)}`;
+    }
+}
+function detailDate(e, key) {
+    const v = e.detail?.[key];
+    return typeof v === "string" && v.length >= 10 ? v.slice(0, 10) : null;
+}
+function humanise(s) {
+    return (s ?? "").replace(/_/g, " ").trim();
+}
+/**
+ * The scope in one line for the side reading it: what, which side, where,
+ * when, money and (administrators) the directory. Territories are ISO codes
+ * here ("GB, IE"); the screens spell the country names.
+ */
+export function scopeSummary(scope, type, reader) {
+    const whose = reader.side === "grantor" ? "your" : `${reader.grantorName}'s`;
+    const songs = scope.workIds?.length ?? scope.songsChosen ?? 0;
+    const recordings = scope.recordingIds?.length ?? scope.recordingsChosen ?? 0;
+    const count = (n, one) => `${n} ${one}${n === 1 ? "" : "s"}`;
+    const what = scope.catalogue === "whole"
+        ? `${whose} whole catalogue`
+        : [
+            songs > 0 ? count(songs, "song") : null,
+            recordings > 0 ? count(recordings, "recording") : null,
+        ]
+            .filter(Boolean)
+            .join(" and ") + ` from ${whose} catalogue`;
+    const half = scope.half === "both"
+        ? "songs and recordings"
+        : scope.half === "composition"
+            ? "the song side only"
+            : "the recording side only";
+    const where = scope.territories.includes("WW")
+        ? "worldwide"
+        : scope.territories.join(", ");
+    const when = (scope.termStartsOn ? `from ${scope.termStartsOn}` : "from acceptance") +
+        (scope.termEndsOn ? ` until ${scope.termEndsOn}` : ", no end date");
+    const money = scope.money
+        ? "can see statements"
+        : "can't see statements or earnings";
+    const directory = type === "administrator"
+        ? scope.directory
+            ? "; can list songs in the public directory"
+            : "; can't list songs in the public directory"
+        : "";
+    return `${what}, ${half}, ${where}, ${when}; ${money}${directory}`;
+}
+//# sourceMappingURL=relationship-copy.js.map

package/dist/tools/relationship-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-copy.js","sourceRoot":"","sources":["../../src/tools/relationship-copy.ts"],"names":[],"mappings":"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"}

package/dist/tools/relationship-scope.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The scope of a portfolio relationship, as the assistant tools accept it
+ * (ADR-333 D3). The main MCP server cannot import the app, so this mirrors
+ * `relationshipScopeSchema` in lib/services/portfolio-relationship-model.ts
+ * with snake_case names. lib/services/__tests__/relationship-scope-mcp-
+ * parity.test.ts fails if a field, an allowed value or a limit drifts.
+ *
+ * Every field is optional: the app fills the defaults (whole catalogue, both
+ * halves, worldwide, no end date, money on only for an administrator,
+ * directory off). The rules that join two fields (for example "worldwide
+ * cannot be combined with other territories") are enforced by the app, which
+ * refuses with a plain reason; the descriptions below state them.
+ *
+ * Deliberately has no imports, so the parity test can load it directly.
+ */
+export declare const SCOPE_HALVES: readonly ["both", "composition", "master"];
+export declare const SCOPE_CATALOGUES: readonly ["whole", "chosen"];
+export declare const SCOPE_MAX_TERRITORIES = 300;
+export declare const SCOPE_MAX_ITEMS = 5000;
+export declare const SCOPE_TERRITORY_PATTERN = "^[A-Z]{2}$";
+export declare const SCOPE_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+/** The tool argument name for each field of the app's scope. */
+export declare const SCOPE_FIELD_NAMES: {
+    readonly half: "half";
+    readonly territories: "territories";
+    readonly term_starts_on: "termStartsOn";
+    readonly term_ends_on: "termEndsOn";
+    readonly money: "money";
+    readonly directory: "directory";
+    readonly catalogue: "catalogue";
+    readonly work_ids: "workIds";
+    readonly recording_ids: "recordingIds";
+};
+export type ScopeArgName = keyof typeof SCOPE_FIELD_NAMES;
+/** JSON Schema for the optional `scope` argument of grant, invite and answer. */
+export declare const RELATIONSHIP_SCOPE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly half: {
+            readonly type: "string";
+            readonly enum: readonly ["both", "composition", "master"];
+            readonly description: "Which half of the songs: both, composition (the song and its publishing) or master (the recordings).";
+        };
+        readonly territories: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly pattern: "^[A-Z]{2}$";
+            };
+            readonly minItems: 1;
+            readonly maxItems: 300;
+            readonly description: "Countries covered. Only [\"WW\"] (worldwide) is accepted today: limiting a relationship to some countries is not available yet, and any other value is refused.";
+        };
+        readonly term_starts_on: {
+            readonly type: readonly ["string", "null"];
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+            readonly description: "First day covered, YYYY-MM-DD (UTC). Leave out or null to start when it is accepted.";
+        };
+        readonly term_ends_on: {
+            readonly type: readonly ["string", "null"];
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+            readonly description: "Last day covered, YYYY-MM-DD (UTC), inclusive. Leave out or null for until revoked. On that date access ends by itself.";
+        };
+        readonly money: {
+            readonly type: "boolean";
+            readonly description: "true lets the organisation see statements and earnings in scope.";
+        };
+        readonly directory: {
+            readonly type: "boolean";
+            readonly description: "true lets an administrator list or hide songs in the public directory and answer enquiries. Administrators only.";
+        };
+        readonly catalogue: {
+            readonly type: "string";
+            readonly enum: readonly ["whole", "chosen"];
+            readonly description: "whole for the whole catalogue, or chosen for only the songs and recordings named in work_ids and recording_ids.";
+        };
+        readonly work_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly maxItems: 5000;
+            readonly description: "Songs covered when catalogue is chosen (ids from pica_works_query). Not allowed for a master-only scope.";
+        };
+        readonly recording_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly maxItems: 5000;
+            readonly description: "Recordings covered when catalogue is chosen (ids from pica_recordings_query). Not allowed for a composition-only scope.";
+        };
+    };
+};
+/**
+ * Convert the tool's `scope` argument to the app's field names. Unknown keys
+ * are dropped here; the schema above already refuses them at the MCP layer.
+ */
+export declare function scopeArgToApi(scope: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+//# sourceMappingURL=relationship-scope.d.ts.map

package/dist/tools/relationship-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-scope.d.ts","sourceRoot":"","sources":["../../src/tools/relationship-scope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,YAAY,4CAA6C,CAAC;AACvE,eAAO,MAAM,gBAAgB,8BAA+B,CAAC;AAC7D,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,uBAAuB,eAAe,CAAC;AACpD,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAE3D,gEAAgE;AAChE,eAAO,MAAM,iBAAiB;;;;;;;;;;CAUpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiElC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOrC"}

package/dist/tools/relationship-scope.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * The scope of a portfolio relationship, as the assistant tools accept it
+ * (ADR-333 D3). The main MCP server cannot import the app, so this mirrors
+ * `relationshipScopeSchema` in lib/services/portfolio-relationship-model.ts
+ * with snake_case names. lib/services/__tests__/relationship-scope-mcp-
+ * parity.test.ts fails if a field, an allowed value or a limit drifts.
+ *
+ * Every field is optional: the app fills the defaults (whole catalogue, both
+ * halves, worldwide, no end date, money on only for an administrator,
+ * directory off). The rules that join two fields (for example "worldwide
+ * cannot be combined with other territories") are enforced by the app, which
+ * refuses with a plain reason; the descriptions below state them.
+ *
+ * Deliberately has no imports, so the parity test can load it directly.
+ */
+export const SCOPE_HALVES = ["both", "composition", "master"];
+export const SCOPE_CATALOGUES = ["whole", "chosen"];
+export const SCOPE_MAX_TERRITORIES = 300;
+export const SCOPE_MAX_ITEMS = 5000;
+export const SCOPE_TERRITORY_PATTERN = "^[A-Z]{2}$";
+export const SCOPE_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+/** The tool argument name for each field of the app's scope. */
+export const SCOPE_FIELD_NAMES = {
+    half: "half",
+    territories: "territories",
+    term_starts_on: "termStartsOn",
+    term_ends_on: "termEndsOn",
+    money: "money",
+    directory: "directory",
+    catalogue: "catalogue",
+    work_ids: "workIds",
+    recording_ids: "recordingIds",
+};
+/** JSON Schema for the optional `scope` argument of grant, invite and answer. */
+export const RELATIONSHIP_SCOPE_INPUT_SCHEMA = {
+    type: "object",
+    description: "What the relationship covers. Leave out any field to use the default: the whole catalogue, " +
+        "both halves, worldwide, until revoked, statements hidden (shown by default only to an " +
+        "administrator), directory off.",
+    additionalProperties: false,
+    properties: {
+        half: {
+            type: "string",
+            enum: [...SCOPE_HALVES],
+            description: "Which half of the songs: both, composition (the song and its publishing) or master (the recordings).",
+        },
+        territories: {
+            type: "array",
+            items: { type: "string", pattern: SCOPE_TERRITORY_PATTERN },
+            minItems: 1,
+            maxItems: SCOPE_MAX_TERRITORIES,
+            description: 'Countries covered. Only ["WW"] (worldwide) is accepted today: limiting a relationship to some countries is not available yet, and any other value is refused.',
+        },
+        term_starts_on: {
+            type: ["string", "null"],
+            pattern: SCOPE_DATE_PATTERN,
+            description: "First day covered, YYYY-MM-DD (UTC). Leave out or null to start when it is accepted.",
+        },
+        term_ends_on: {
+            type: ["string", "null"],
+            pattern: SCOPE_DATE_PATTERN,
+            description: "Last day covered, YYYY-MM-DD (UTC), inclusive. Leave out or null for until revoked. On that date access ends by itself.",
+        },
+        money: {
+            type: "boolean",
+            description: "true lets the organisation see statements and earnings in scope.",
+        },
+        directory: {
+            type: "boolean",
+            description: "true lets an administrator list or hide songs in the public directory and answer enquiries. Administrators only.",
+        },
+        catalogue: {
+            type: "string",
+            enum: [...SCOPE_CATALOGUES],
+            description: "whole for the whole catalogue, or chosen for only the songs and recordings named in work_ids and recording_ids.",
+        },
+        work_ids: {
+            type: "array",
+            items: { type: "string", format: "uuid" },
+            maxItems: SCOPE_MAX_ITEMS,
+            description: "Songs covered when catalogue is chosen (ids from pica_works_query). Not allowed for a master-only scope.",
+        },
+        recording_ids: {
+            type: "array",
+            items: { type: "string", format: "uuid" },
+            maxItems: SCOPE_MAX_ITEMS,
+            description: "Recordings covered when catalogue is chosen (ids from pica_recordings_query). Not allowed for a composition-only scope.",
+        },
+    },
+};
+/**
+ * Convert the tool's `scope` argument to the app's field names. Unknown keys
+ * are dropped here; the schema above already refuses them at the MCP layer.
+ */
+export function scopeArgToApi(scope) {
+    if (!scope)
+        return undefined;
+    const out = {};
+    for (const [arg, api] of Object.entries(SCOPE_FIELD_NAMES)) {
+        if (scope[arg] !== undefined)
+            out[api] = scope[arg];
+    }
+    return out;
+}
+//# sourceMappingURL=relationship-scope.js.map

package/dist/tools/relationship-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-scope.js","sourceRoot":"","sources":["../../src/tools/relationship-scope.ts"],"names":[],"mappings":"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"}