@frihet/mcp-server 2.0.0 → 2.0.2

package/dist/canary/mcp-harness.d.ts

@@ -15,7 +15,7 @@
  */
 export declare const HARNESS_CONTRACT_VERSION = 1;
 export declare const INSPECTOR_PINNED_VERSION = "2.3.0";
-export declare const CANONICAL_OPERATIONS_COUNT = 156;
+export declare const CANONICAL_OPERATIONS_COUNT = 158;
 export declare const FISCAL_ALIASES_COUNT: number;
 export type CheckStatus = "PASS" | "FAIL" | "UNSUPPORTED" | "NOT_EXERCISED";
 export type OverallStatus = "PASS" | "PASS_WITH_GAPS" | "FAIL";

package/dist/canary/mcp-harness.js

@@ -24,8 +24,9 @@ export const HARNESS_CONTRACT_VERSION = 1;
 export const INSPECTOR_PINNED_VERSION = "2.3.0";
 // Updated 2026-10-10 by issue #124 (IGIC-pattern withdraw of dead onboarding_status /
 // onboarding_persona_set — the Frihet-ERP /v1/onboarding/* family is absent, so the
-// MCP catalogue now declares 156 canonical operations, down from 158).
-export const CANONICAL_OPERATIONS_COUNT = 156;
+// MCP catalogue then declared 156 canonical operations, down from 158; the two read-only
+// purchase-order tools (ADR 0027 S2) bring it to 158).
+export const CANONICAL_OPERATIONS_COUNT = 158;
 export const FISCAL_ALIASES_COUNT = Object.keys(FISCAL_MODELO_ALIASES).length;
 /**
  * Executes the complete compatibility harness in-process and returns

package/dist/claude-output-privacy.js

@@ -164,6 +164,7 @@ const SAFE_META_FLAGS = [
     "io.frihet/transportOutcomeUnknown", "io.frihet/retryable", "io.frihet/operationMayHaveCompleted",
     "io.frihet/resourceNotFound", "io.frihet/accessDenied",
     "io.frihet/confirmationRequired", "io.frihet/localValidationRejected", "io.frihet/requestRejected",
+    "io.frihet/searchScanTruncated", "io.frihet/cursorWithQueryUnsupported",
 ];
 /** Claude does not expose opaque tool metadata as an actionable error message.
  * Render fixed text from the typed flags, never provider text, codes or IDs.
@@ -185,6 +186,12 @@ function claudeErrorText(meta) {
     if (meta["io.frihet/resourceNotFound"] === true) {
         return "NOT_FOUND: No record is available with this ID in the authorized workspace. Check the ID; after deletion, verify absence with a list. Do not automatically repeat a write.";
     }
+    if (meta["io.frihet/cursorWithQueryUnsupported"] === true) {
+        return "CURSOR_WITH_QUERY_UNSUPPORTED: Text search ('q') cannot be combined with cursor pagination ('after') because the ERP backend slices search results by 'offset'/'limit' and ignores 'after'. No action was performed. Use 'offset' and 'limit' when searching with 'q', or omit 'q' when paginating with 'after'.";
+    }
+    if (meta["io.frihet/searchScanTruncated"] === true) {
+        return "SEARCH_SCAN_TRUNCATED: The text search hit the ERP 500-document scan cap (truncated=true) and was withheld so an incomplete scan is never mistaken for an exhaustive list. Narrow 'q' with a more specific term or paginate without 'q' using 'after'.";
+    }
     if (meta["io.frihet/localValidationRejected"] === true) {
         return "VALIDATION_FAILED: The ID or input parameters were rejected before sending the request. No action was performed. Correct the ID and parameters before retrying.";
     }
@@ -203,6 +210,8 @@ export function claudeToolResult(result, toolName) {
     const fixedRemediation = error && (safeMeta["io.frihet/confirmationRequired"] === true
         || safeMeta["io.frihet/localValidationRejected"] === true
         || safeMeta["io.frihet/requestRejected"] === true
+        || safeMeta["io.frihet/cursorWithQueryUnsupported"] === true
+        || safeMeta["io.frihet/searchScanTruncated"] === true
         || safeMeta["io.frihet/operationOutcomeUnknown"] === true
         || safeMeta["io.frihet/transportOutcomeUnknown"] === true
         || safeMeta["io.frihet/operationMayHaveCompleted"] === true);

package/dist/claude-profile.js

@@ -170,7 +170,9 @@ export const CLAUDE_EXCLUDED_TOOLS = {
     "period_reopen": "The handler deliberately defers execution; capability truth marks this deferred.",
     "refund_sale": "Executes an actual Stripe money transfer; excluded under Directory policy section 4.A.",
     "send_quote": "Previewed recipient is not atomically bound and delivery is not retry-safe.",
-    "sync_channel": "The handler deliberately defers execution; capability truth marks this deferred."
+    "sync_channel": "The handler deliberately defers execution; capability truth marks this deferred.",
+    "get_purchase_order": "Added after the 176de12 Claude operational candidate freeze; not yet admitted to the Claude profile.",
+    "list_purchase_orders": "Added after the 176de12 Claude operational candidate freeze; not yet admitted to the Claude profile."
 };
 export const CLAUDE_CANDIDATE_RESOURCES = new Set([
     "frihet://config/currencies",

package/dist/client-interface.d.ts

@@ -101,6 +101,13 @@ export interface IFrihetClient {
     createVendor(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateVendor(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
     deleteVendor(id: string): Promise<void>;
+    listPurchaseOrders(params?: {
+        status?: string;
+        vendorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<Record<string, unknown>>>;
+    getPurchaseOrder(id: string): Promise<Record<string, unknown>>;
     sendInvoice(id: string, to?: string): Promise<Record<string, unknown>>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
     getInvoicePdf(id: string): Promise<import("./client.js").BinaryDocument>;

package/dist/client.d.ts

@@ -275,6 +275,13 @@ export declare class FrihetClient {
     createVendor(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateVendor(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
     deleteVendor(id: string): Promise<void>;
+    listPurchaseOrders(params?: {
+        status?: string;
+        vendorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<Record<string, unknown>>>;
+    getPurchaseOrder(id: string): Promise<Record<string, unknown>>;
     sendInvoice(id: string, to?: string): Promise<Record<string, unknown>>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
     getInvoicePdf(id: string): Promise<BinaryDocument>;

package/dist/client.js

@@ -850,6 +850,22 @@ export class FrihetClient {
     async deleteVendor(id) {
         return this.request("DELETE", `/vendors/${pathSegment(id)}`);
     }
+    // ---------------------------------------------------------------- Purchase Orders
+    // ----------------------------------------------------------------
+    // ADR 0027 S2, server-owned lifecycle. Routes are read-only here; the
+    // write surface (create draft, send, confirm, cancel, receive,
+    // reverse-receipt, bill) is deliberately not exposed by the MCP server.
+    async listPurchaseOrders(params) {
+        return this.requestPaginated("GET", "/purchase-orders", undefined, {
+            status: params?.status,
+            vendorId: params?.vendorId,
+            limit: params?.limit,
+            offset: params?.offset,
+        });
+    }
+    async getPurchaseOrder(id) {
+        return this.requestUnwrapped("GET", `/purchase-orders/${pathSegment(id)}`);
+    }
     // ---------------------------------------------------------------- Invoice Actions
     // ----------------------------------------------------------------
     async sendInvoice(id, to) {

package/dist/demo-client.d.ts

@@ -3,12 +3,12 @@
  *
  * A drop-in IFrihetClient that makes ZERO network calls: it serves the canned
  * PII-safe fixtures in demo-fixtures.ts. index.ts swaps this in for FrihetClient
- * when demo mode is on, so tools (which stringify the client's return value)
- * automatically propagate the `_demo`/`_demoNotice` banner without any change
- * under src/tools/.
+ * when demo mode is on. Single-record fixtures carry their own demo stamps;
+ * server-composition.ts stamps paginated MCP results after profile projection
+ * and declares those fields only on demo schemas, preserving live contracts.
  *
  * Response contract (see SPEC-mcp-demo-mode.md option B/C):
- *   - reads/lists → fixture data stamped `_demo:true` (READ notice).
+ *   - reads/lists → MCP fixture data stamped `_demo:true` (READ notice).
  *   - lists without fixtures → EMPTY PaginatedResponse, still stamped.
  *   - writes → plausible fixture-shaped object with a `demo_`-prefixed id
  *     (WRITE notice "…Simulated — not persisted.").
@@ -22,10 +22,8 @@ import type { CreateWebhookInput, CreateWebhookResult, PaginatedResponse, Update
 import { type BinaryDocument, type EInvoiceDocument, type EInvoiceExportResult, type McpEInvoiceExportFormat } from "./client.js";
 type Rec = Record<string, unknown>;
 export declare class DemoFrihetClient implements IFrihetClient {
-    listInvoices(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
+    readonly isDemoClient: true;
+    listInvoices(params?: Parameters<IFrihetClient["listInvoices"]>[0]): Promise<PaginatedResponse<Rec>>;
     getInvoice(id: string): Promise<Rec>;
     createInvoice(data: Rec): Promise<Rec>;
     updateInvoice(id: string, data: Rec): Promise<Rec>;
@@ -34,10 +32,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedResponse<Rec>>;
-    listExpenses(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
+    listExpenses(params?: Parameters<IFrihetClient["listExpenses"]>[0]): Promise<PaginatedResponse<Rec>>;
     getExpense(id: string): Promise<Rec>;
     createExpense(data: Rec): Promise<Rec>;
     updateExpense(id: string, data: Rec): Promise<Rec>;
@@ -74,6 +69,13 @@ export declare class DemoFrihetClient implements IFrihetClient {
     createVendor(data: Rec): Promise<Rec>;
     updateVendor(id: string, data: Rec): Promise<Rec>;
     deleteVendor(_id: string): Promise<void>;
+    listPurchaseOrders(params?: {
+        status?: string;
+        vendorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<Rec>>;
+    getPurchaseOrder(id: string): Promise<Rec>;
     sendInvoice(id: string, to?: string): Promise<Rec>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Rec>;
     getInvoicePdf(id: string): Promise<BinaryDocument>;
@@ -270,10 +272,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         offset?: number;
     }): Promise<PaginatedResponse<Rec>>;
     getBankAccount(id: string): Promise<Rec>;
-    listTransactions(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
+    listTransactions(params?: Parameters<IFrihetClient["listTransactions"]>[0]): Promise<PaginatedResponse<Rec>>;
     categorizeTransaction(id: string, data: {
         category: string;
         notes?: string;

package/dist/demo-client.js

@@ -3,12 +3,12 @@
  *
  * A drop-in IFrihetClient that makes ZERO network calls: it serves the canned
  * PII-safe fixtures in demo-fixtures.ts. index.ts swaps this in for FrihetClient
- * when demo mode is on, so tools (which stringify the client's return value)
- * automatically propagate the `_demo`/`_demoNotice` banner without any change
- * under src/tools/.
+ * when demo mode is on. Single-record fixtures carry their own demo stamps;
+ * server-composition.ts stamps paginated MCP results after profile projection
+ * and declares those fields only on demo schemas, preserving live contracts.
  *
  * Response contract (see SPEC-mcp-demo-mode.md option B/C):
- *   - reads/lists → fixture data stamped `_demo:true` (READ notice).
+ *   - reads/lists → MCP fixture data stamped `_demo:true` (READ notice).
  *   - lists without fixtures → EMPTY PaginatedResponse, still stamped.
  *   - writes → plausible fixture-shaped object with a `demo_`-prefixed id
  *     (WRITE notice "…Simulated — not persisted.").
@@ -19,7 +19,7 @@
  */
 import { toApiEInvoiceExportFormat, } from "./client.js";
 import { Buffer } from "node:buffer";
-import { READ_STAMP, FISCAL_STAMP, DEMO_NOW, demoPage, demoEmptyPage, findOrStub, demoId, simulateWrite, simulateAction, demoClients, demoProducts, demoInvoices, demoExpenses, demoQuotes, demoVendors, demoBankAccounts, demoTransactions, } from "./demo-fixtures.js";
+import { READ_STAMP, FISCAL_STAMP, DEMO_NOW, demoPage, demoEmptyPage, findOrStub, demoId, simulateWrite, simulateAction, demoClients, demoMoney, demoSum, demoTopClients, demoProducts, demoInvoices, demoExpenses, demoQuotes, demoVendors, demoPurchaseOrders, demoBankAccounts, demoTransactions, } from "./demo-fixtures.js";
 const DEMO_RBAC_ROLES = ["owner", "admin", "manager", "sales", "accountant", "employee", "viewer"];
 const DEMO_RBAC_RESOURCES = [
     "workspace", "invoices", "quotes", "expenses", "clients", "products", "accounting",
@@ -75,9 +75,15 @@ const DEMO_OWNER_CAPABILITIES = Object.entries(DEMO_PERMISSION_MATRIX.owner)
     .flatMap(([resource, actions]) => actions.map((action) => `${resource}:${action}`))
     .sort();
 export class DemoFrihetClient {
+    isDemoClient = true;
     // ---------------------------------------------------------------- Invoices
     async listInvoices(params) {
-        return demoPage(demoInvoices, params);
+        const filtered = demoInvoices.filter((row) => (!params?.from || (typeof row.issueDate === "string" && row.issueDate >= params.from))
+            && (!params?.to || (typeof row.issueDate === "string" && row.issueDate <= params.to))
+            && (!params?.status || row.status === params.status)
+            && (!params?.clientId || row.clientId === params.clientId)
+            && (!params?.seriesId || row.seriesId === params.seriesId));
+        return demoPage(filtered, params, ["issueDate", "documentNumber", "id"]);
     }
     async getInvoice(id) {
         return findOrStub(demoInvoices, id);
@@ -108,7 +114,11 @@ export class DemoFrihetClient {
     }
     // ---------------------------------------------------------------- Expenses
     async listExpenses(params) {
-        return demoPage(demoExpenses, params);
+        const filtered = demoExpenses.filter((row) => (!params?.from || (typeof row.date === "string" && row.date >= params.from))
+            && (!params?.to || (typeof row.date === "string" && row.date <= params.to))
+            && (!params?.vendorId || row.vendorId === params.vendorId)
+            && (!params?.category || row.category === params.category));
+        return demoPage(filtered, params, ["date", "id"]);
     }
     async getExpense(id) {
         return findOrStub(demoExpenses, id);
@@ -186,6 +196,21 @@ export class DemoFrihetClient {
     async deleteVendor(_id) {
         return;
     }
+    // ---------------------------------------------------------------- Purchase Orders
+    // Read-only surface (ADR 0027 S2). Write tools are intentionally absent.
+    async listPurchaseOrders(params) {
+        const filtered = demoPurchaseOrders.filter((po) => {
+            if (params?.status && po.status !== params.status)
+                return false;
+            if (params?.vendorId && po.vendorId !== params.vendorId)
+                return false;
+            return true;
+        });
+        return demoPage(filtered, params);
+    }
+    async getPurchaseOrder(id) {
+        return findOrStub(demoPurchaseOrders, id);
+    }
     // ---------------------------------------------------------------- Invoice actions
     async sendInvoice(id, to) {
         // Email dispatch — simulated, no email is actually sent.
@@ -370,6 +395,17 @@ export class DemoFrihetClient {
     }
     // ---------------------------------------------------------------- Intelligence
     async getBusinessContext() {
+        const month = DEMO_NOW.slice(0, 7);
+        const today = DEMO_NOW.slice(0, 10);
+        const monthInvoices = demoInvoices.filter((invoice) => String(invoice.issueDate).startsWith(month));
+        const monthExpenses = demoExpenses.filter((expense) => String(expense.date).startsWith(month));
+        // Fixture invoices have no partial payments: paid means settled; drafts are not receivables.
+        const unpaid = demoInvoices.filter((invoice) => invoice.status === "sent" || invoice.status === "overdue");
+        const overdue = unpaid.filter((invoice) => String(invoice.dueDate) < today);
+        const lastInvoice = [...demoInvoices].sort((a, b) => String(b.issueDate).localeCompare(String(a.issueDate)))[0];
+        const lastExpense = [...demoExpenses].sort((a, b) => String(b.date).localeCompare(String(a.date)))[0];
+        const revenue = demoSum(monthInvoices.filter((invoice) => invoice.status !== "draft" && invoice.status !== "cancelled"), "total");
+        const expenses = demoSum(monthExpenses, "amount");
         return {
             business: {
                 name: "Demo Studio SL",
@@ -381,39 +417,70 @@ export class DemoFrihetClient {
             defaults: { taxRate: 21, irpfRate: 15, dueDays: 30, currency: "EUR" },
             plan: {
                 name: "free",
-                invoices: { used: 5, limit: 999 },
-                expenses: { used: demoExpenses.length, limit: 5 },
+                invoices: { used: monthInvoices.length, limit: 999 },
+                expenses: { used: monthExpenses.length, limit: 5 },
                 aiMessages: { used: 2, limit: 30 },
             },
-            series: [{ id: "default", prefix: "F", current: 5, year: 2026 }],
+            series: [{ id: "default", prefix: "F", current: demoInvoices.length, year: Number(DEMO_NOW.slice(0, 4)) }],
             recentActivity: {
-                lastInvoice: { number: "F-2026-005", date: "2026-07-18", client: "Acme Studio" },
-                lastExpense: { date: "2026-07-17", vendor: "Demo Supplies", amount: 405.6 },
-                overdueCount: 1,
-                overdueAmount: 640,
-                unpaidCount: 2,
+                lastInvoice: lastInvoice
+                    ? { number: lastInvoice.documentNumber, date: lastInvoice.issueDate, client: lastInvoice.clientName }
+                    : null,
+                lastExpense: lastExpense
+                    ? { date: lastExpense.date, vendor: lastExpense.vendor, amount: lastExpense.amount }
+                    : null,
+                overdueCount: overdue.length,
+                overdueAmount: demoSum(overdue, "total"),
+                unpaidCount: unpaid.length,
+                coverage: { totalAnalyzed: demoInvoices.length, sampleLimit: 500, isTruncated: false, asOf: today, currency: "EUR", excludedForeignInvoices: 0 },
             },
-            topClients: [{ name: "Acme Studio", totalRevenue: 2200, invoiceCount: 2 }],
+            topClients: demoTopClients(demoInvoices.filter((invoice) => invoice.status === "paid")),
             currentMonth: {
-                revenue: 3960.4,
-                expenses: 405.6,
-                profit: 3554.8,
-                invoiceCount: 5,
-                expenseCount: demoExpenses.length,
+                revenue,
+                expenses,
+                profit: demoMoney(revenue - expenses),
+                invoiceCount: monthInvoices.length,
+                expenseCount: monthExpenses.length,
             },
             ...READ_STAMP,
         };
     }
     async getMonthlySummary(month) {
+        const period = month ?? DEMO_NOW.slice(0, 7);
+        const invoices = demoInvoices.filter((invoice) => String(invoice.issueDate).startsWith(`${period}-`));
+        const expenses = demoExpenses.filter((expense) => String(expense.date).startsWith(`${period}-`));
+        // Match /v1/monthly: drafts count as created, but do not contribute revenue or tax.
+        const issued = invoices.filter((invoice) => invoice.status !== "draft" && invoice.status !== "cancelled");
+        const deductible = expenses.filter((expense) => expense.taxDeductible !== false);
+        const revenue = {
+            total: demoSum(issued, "total"), taxBase: demoSum(issued, "subtotal"),
+            tax: demoSum(issued, "taxAmount"), irpf: demoSum(issued, "irpfAmount"),
+        };
+        const expenseTotal = demoSum(expenses, "amount");
+        const inputTax = demoSum(deductible, "tax");
+        const byCategory = {};
+        for (const expense of expenses) {
+            const category = String(expense.category ?? "other");
+            byCategory[category] = demoMoney((byCategory[category] ?? 0) + Number(expense.amount));
+        }
+        const vatPayable = demoMoney(revenue.tax - inputTax);
         return {
-            period: month ?? "2026-07",
-            revenue: { total: 3960.4, taxBase: 3273.06, tax: 687.34, irpf: 0 },
-            expenses: { total: 405.6, deductible: 405.6, tax: 70.4 },
-            profit: { gross: 3554.8, net: 2937.86 },
-            invoices: { created: 5, sent: 1, paid: 3, overdue: 1 },
-            topClients: [{ name: "Acme Studio", totalRevenue: 2200, invoiceCount: 2 }],
-            byCategory: { supplies: 405.6 },
-            taxLiability: { vatPayable: 616.94, irpfRetained: 0, estimatedModel303: 616.94 },
+            period,
+            revenue,
+            expenses: { total: expenseTotal, deductible: demoSum(deductible, "amount"), tax: inputTax },
+            profit: {
+                gross: demoMoney(revenue.total - expenseTotal),
+                net: demoMoney(revenue.total - expenseTotal - revenue.tax + inputTax + revenue.irpf),
+            },
+            invoices: {
+                created: invoices.length,
+                sent: invoices.filter((invoice) => invoice.status === "sent" || invoice.status === "partial").length,
+                paid: invoices.filter((invoice) => invoice.status === "paid").length,
+                overdue: invoices.filter((invoice) => invoice.status === "overdue").length,
+            },
+            topClients: demoTopClients(issued),
+            byCategory,
+            taxLiability: { vatPayable, irpfRetained: revenue.irpf, estimatedModel303: vatPayable },
             ...READ_STAMP,
         };
     }
@@ -516,7 +583,12 @@ export class DemoFrihetClient {
         return findOrStub(demoBankAccounts, id);
     }
     async listTransactions(params) {
-        return demoPage(demoTransactions, params);
+        const filtered = demoTransactions.filter((row) => (!params?.from || (typeof row.postedAt === "string" && row.postedAt >= params.from))
+            && (!params?.to || (typeof row.postedAt === "string" && row.postedAt <= params.to))
+            && (!params?.accountId || row.accountId === params.accountId)
+            && (!params?.status || row.status === params.status)
+            && (!params?.category || row.category === params.category));
+        return demoPage(filtered, params, ["postedAt", "id"]);
     }
     async categorizeTransaction(id, data) {
         return simulateAction(id, { category: data.category, ...(data.notes ? { notes: data.notes } : {}) });

package/dist/demo-fixtures.d.ts

@@ -31,11 +31,11 @@ export declare const DEMO_NOW = "2026-07-15T10:00:00.000Z";
 /** Test IBAN (ECBS/AEAT example — never a real account). */
 export declare const DEMO_TEST_IBAN = "ES9121000418450200051332";
 export type DemoPaginated = PaginatedResponse<Record<string, unknown>>;
-/** Wrap a fixture array in a PaginatedResponse. */
-export declare function demoPage(data: Record<string, unknown>[], params?: {
+/** Page fixtures after filtering; opt-in string keys sort descending on a copy. */
+export declare function demoPage(data: readonly Record<string, unknown>[], params?: {
     limit?: number;
     offset?: number;
-}): DemoPaginated;
+}, descendingKeys?: readonly string[]): DemoPaginated;
 /** Empty PaginatedResponse for surfaces without dedicated fixtures. */
 export declare function demoEmptyPage(params?: {
     limit?: number;
@@ -43,15 +43,25 @@ export declare function demoEmptyPage(params?: {
 }): DemoPaginated;
 export declare const demoClients: Record<string, unknown>[];
 export declare const demoProducts: Record<string, unknown>[];
+export declare function demoMoney(n: number): number;
 export declare const demoInvoices: Record<string, unknown>[];
+/** Aggregate stored fixture amounts; never recalculate invoice taxes here. */
+export declare function demoSum(records: Record<string, unknown>[], field: string): number;
+/** Rank only the invoices selected by the caller (paid or issued in a month). */
+export declare function demoTopClients(invoices: Record<string, unknown>[]): {
+    name: string;
+    totalRevenue: number;
+    invoiceCount: number;
+}[];
 export declare const demoExpenses: Record<string, unknown>[];
 export declare const demoQuotes: Record<string, unknown>[];
 export declare const demoVendors: Record<string, unknown>[];
+export declare const demoPurchaseOrders: Record<string, unknown>[];
 export declare const demoBankAccounts: Record<string, unknown>[];
 export declare const demoTransactions: Record<string, unknown>[];
 /** Find a fixture by id, or synthesize a minimal stamped object with that id. */
 export declare function findOrStub(collection: Record<string, unknown>[], id: string): Record<string, unknown> & DemoStamp;
-/** Deterministic-ish demo id (no network, no clock dependency). */
+/** Simulated ids cannot alias read-only fixtures (no network or clock dependency). */
 export declare function demoId(prefix: string): string;
 /**
  * Simulate a create/update: echo the input, stamp a fabricated demo id +

package/dist/demo-fixtures.js

@@ -36,12 +36,21 @@ export const EMPTY_STAMP = {
 export const DEMO_NOW = "2026-07-15T10:00:00.000Z";
 /** Test IBAN (ECBS/AEAT example — never a real account). */
 export const DEMO_TEST_IBAN = "ES9121000418450200051332";
-/** Wrap a fixture array in a PaginatedResponse. */
-export function demoPage(data, params) {
+/** Page fixtures after filtering; opt-in string keys sort descending on a copy. */
+export function demoPage(data, params, descendingKeys) {
     const limit = params?.limit ?? 50;
     const offset = params?.offset ?? 0;
+    const ordered = descendingKeys?.length ? [...data].sort((a, b) => {
+        for (const key of descendingKeys) {
+            const left = String(a[key] ?? "");
+            const right = String(b[key] ?? "");
+            if (left !== right)
+                return left < right ? 1 : -1;
+        }
+        return 0;
+    }) : data;
     return {
-        data: data.slice(offset, offset + limit),
+        data: ordered.slice(offset, offset + limit),
         total: data.length,
         limit,
         offset,
@@ -124,16 +133,17 @@ export const demoProducts = [
     { id: "demo_prd_007", name: "Menú catering (por persona)", unitPrice: 18, taxRate: 10, description: "Servicio de catering, IVA reducido hostelería", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
     { id: "demo_prd_008", name: "Libro técnico impreso", unitPrice: 24, taxRate: 4, description: "Publicación impresa, IVA superreducido", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
 ];
-function money(n) {
+export function demoMoney(n) {
     return Math.round(n * 100) / 100;
 }
 function invoice(opts) {
-    const subtotal = money(opts.items.reduce((s, i) => s + i.quantity * i.unitPrice, 0));
-    const taxAmount = money(subtotal * (opts.taxRate / 100));
-    const irpfAmount = opts.irpfRate ? money(subtotal * (opts.irpfRate / 100)) : 0;
-    const total = money(subtotal + taxAmount - irpfAmount);
+    const subtotal = demoMoney(opts.items.reduce((s, i) => s + i.quantity * i.unitPrice, 0));
+    const taxAmount = demoMoney(subtotal * (opts.taxRate / 100));
+    const irpfAmount = opts.irpfRate ? demoMoney(subtotal * (opts.irpfRate / 100)) : 0;
+    const total = demoMoney(subtotal + taxAmount - irpfAmount);
     return {
         id: opts.id,
+        documentNumber: `F-${opts.issueDate.slice(0, 4)}-${opts.id.split("_").at(-1)}`,
         clientId: opts.clientId,
         clientName: opts.clientName,
         items: opts.items,
@@ -163,16 +173,29 @@ export const demoInvoices = [
     invoice({ id: "demo_inv_008", clientId: "demo_cli_003", clientName: "Servicios Insulares Canarias SL", items: [{ description: "Mantenimiento mensual", quantity: 3, unitPrice: 150 }], taxRate: 7, status: "overdue", issueDate: "2026-04-05", dueDate: "2026-05-05", notes: "IGIC 7% — factura vencida", clientLocation: "canarias" }),
     invoice({ id: "demo_inv_009", clientId: "demo_cli_004", clientName: "Marina Delgado (autónoma)", items: [{ description: "Diseño de marca", quantity: 1, unitPrice: 1200 }, { description: "Auditoría SEO", quantity: 1, unitPrice: 600 }], taxRate: 21, status: "draft", issueDate: "2026-07-08", dueDate: "2026-08-08", irpfRate: 15, notes: "Autónoma con retención IRPF 15%", clientLocation: "peninsula" }),
 ];
+/** Aggregate stored fixture amounts; never recalculate invoice taxes here. */
+export function demoSum(records, field) {
+    return demoMoney(records.reduce((sum, record) => sum + Number(record[field] ?? 0), 0));
+}
+/** Rank only the invoices selected by the caller (paid or issued in a month). */
+export function demoTopClients(invoices) {
+    return demoClients.map((client) => {
+        const matched = invoices.filter((invoice) => invoice.clientId === client.id);
+        return { name: String(client.name), totalRevenue: demoSum(matched, "total"), invoiceCount: matched.length };
+    }).filter((client) => client.invoiceCount > 0)
+        .sort((a, b) => b.totalRevenue - a.totalRevenue)
+        .slice(0, 5);
+}
 /* ------------------------------------------------------------------ */
 /*  Expenses (6) — categorized                                         */
 /* ------------------------------------------------------------------ */
 export const demoExpenses = [
-    { id: "demo_exp_001", description: "Suscripción software de diseño", amount: 15.4, category: "software", date: "2026-07-01", vendor: "Herramientas Digitales SL", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_002", description: "Material de oficina", amount: 48.2, category: "office_supplies", date: "2026-06-18", vendor: "Papelería Central", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_003", description: "Comida de trabajo con cliente", amount: 62.0, category: "meals", date: "2026-06-22", vendor: "Restaurante El Puerto", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_004", description: "Combustible desplazamiento", amount: 70.0, category: "travel", date: "2026-06-25", vendor: "Estación de Servicio Norte", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_005", description: "Cuota gestoría mensual", amount: 90.0, category: "professional_services", date: "2026-07-01", vendor: "Gestoría Ramírez", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_006", description: "Hosting anual", amount: 120.0, category: "software", date: "2026-05-30", vendor: "Proveedor Cloud SL", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_001", description: "Suscripción software de diseño", amount: 15.4, category: "software", date: "2026-07-01", vendor: "Herramientas Digitales SL", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_002", description: "Material de oficina", amount: 48.2, category: "office_supplies", date: "2026-06-18", vendor: "Papelería Central", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_003", description: "Comida de trabajo con cliente", amount: 62.0, category: "meals", date: "2026-06-22", vendor: "Restaurante El Puerto", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_004", description: "Combustible desplazamiento", amount: 70.0, category: "travel", date: "2026-06-25", vendor: "Estación de Servicio Norte", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_005", description: "Cuota gestoría mensual", amount: 90.0, category: "professional_services", date: "2026-07-01", vendor: "Gestoría Ramírez", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_006", description: "Hosting anual", amount: 120.0, category: "software", date: "2026-05-30", vendor: "Proveedor Cloud SL", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
 ];
 /* ------------------------------------------------------------------ */
 /*  Quotes (2)                                                         */
@@ -218,6 +241,51 @@ export const demoVendors = [
     { id: "demo_ven_002", name: "Proveedor Cloud SL", email: "facturacion@example.com", phone: "+34 600 000 011", taxId: "B22222222", address: { city: "Barcelona", postalCode: "08007", country: "ES" }, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
 ];
 /* ------------------------------------------------------------------ */
+/*  Purchase orders (2) — ADR 0027 S2 read-only surface.              */
+/*  Same vendor ids as demoVendors so list+get read coherently.       */
+/* ------------------------------------------------------------------ */
+export const demoPurchaseOrders = [
+    {
+        id: "demo_po_001",
+        poNumber: "PO-2026-0001",
+        vendorId: "demo_ven_001",
+        vendorName: "Gestoría Ramírez",
+        status: "sent",
+        items: [
+            { description: "Asesoria contable mensual", quantity: 1, unitPrice: 350, productId: "demo_prod_001" },
+        ],
+        issueDate: "2026-09-01",
+        expectedDate: "2026-10-01",
+        taxRate: 21,
+        subtotal: 350,
+        tax: 73.5,
+        total: 423.5,
+        currency: "EUR",
+        notes: "Renovacion contrato asesoria",
+        createdAt: DEMO_NOW,
+        updatedAt: DEMO_NOW,
+    },
+    {
+        id: "demo_po_002",
+        poNumber: "PO-2026-0002",
+        vendorId: "demo_ven_002",
+        vendorName: "Proveedor Cloud SL",
+        status: "draft",
+        items: [
+            { description: "Hosting VPS 4 vCPU", quantity: 12, unitPrice: 45, productId: "demo_prod_002" },
+            { description: "Backup storage 500 GB", quantity: 1, unitPrice: 80 },
+        ],
+        issueDate: "2026-09-15",
+        taxRate: 21,
+        subtotal: 620,
+        tax: 130.2,
+        total: 750.2,
+        currency: "EUR",
+        createdAt: DEMO_NOW,
+        updatedAt: DEMO_NOW,
+    },
+];
+/* ------------------------------------------------------------------ */
 /*  Banking — 1 account + 4 transactions                              */
 /* ------------------------------------------------------------------ */
 export const demoBankAccounts = [
@@ -250,10 +318,10 @@ export function findOrStub(collection, id) {
     return { id, ...READ_STAMP };
 }
 let demoIdCounter = 0;
-/** Deterministic-ish demo id (no network, no clock dependency). */
+/** Simulated ids cannot alias read-only fixtures (no network or clock dependency). */
 export function demoId(prefix) {
     demoIdCounter += 1;
-    return `${prefix}_${String(demoIdCounter).padStart(3, "0")}`;
+    return `${prefix}_simulated_${String(demoIdCounter).padStart(3, "0")}`;
 }
 /**
  * Simulate a create/update: echo the input, stamp a fabricated demo id +