@voyant-travel/finance 0.159.0 → 0.162.0

package/README.md

@@ -2,6 +2,29 @@
 
 Finance module for Voyant. Invoices, payments, credit notes, supplier payments, and finance notes.
 
+## Composed agent commands
+
+`create_booking` is owned by the Finance booking-create extension because that package
+already owns the atomic composer spanning product conversion, travelers, room/item
+lines, payment schedules, optional credits and group membership, invoices, ledger
+records, and post-commit events. The Tool is a structural adapter over that service.
+
+`issue_invoice_from_booking` creates and issues either an invoice or proforma through
+the same package-owned composer used by the HTTP route. Agent execution requires an
+idempotency key and exact approval. Approved execution records approval and causation
+in the action ledger; replaying an already executed approval returns the original
+invoice rather than issuing a duplicate.
+
+## Agent Tools
+
+`issue_invoice_refund` defines a refund as issuing an `issued` credit note
+against an invoice through the existing credit-note domain service. Agent
+callers cannot issue it directly: the first call creates a pending action-ledger
+approval, and execution requires the approved id plus an exact match on the
+principal, command, current invoice snapshot, and fingerprint. Successful
+execution is recorded as `finance.credit_note.issue_refund`, linked to the
+requested action and approval, and requires `finance:refund`.
+
 ## Install
 
 ```bash
@@ -94,11 +117,11 @@ Booking creation UIs can show the same tax line that booking finalization will
 persist by mounting the booking-tax extension:
 
 ```typescript
-import { createBookingTaxHonoExtension } from "@voyant-travel/finance/booking-tax"
+import { createBookingTaxApiExtension } from "@voyant-travel/finance/booking-tax"
 
 createApp({
   extensions: [
-    createBookingTaxHonoExtension({
+    createBookingTaxApiExtension({
       resolveBookingTaxSettings: async (db) => {
         const settings = await getTaxSettings(db)
         return {
@@ -117,7 +140,7 @@ store, while `@voyant-travel/finance` owns the tax policy rule walker, tax-regim
 lookup, product tax-class fallback, and inclusive/exclusive math.
 
 Templates that already mount custom routes can call `mountBookingTaxRoutes(...)`
-from the same entrypoint instead of using the Hono extension.
+from the same entrypoint instead of using the API extension.
 
 Mounting this route registers:
 
@@ -149,11 +172,11 @@ exchange-rate resolver:
 
 ```typescript
 import {
-  createFinanceHonoModule,
+  createFinanceApiModule,
   createVoyantDataFxExchangeRateResolver,
 } from "@voyant-travel/finance"
 
-createFinanceHonoModule({
+createFinanceApiModule({
   invoiceFxSettings: {
     baseCurrency: "RON",
     fxCommissionBps: 200,

package/dist/booking-tax.d.ts

@@ -1,5 +1,5 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import type { HonoExtension } from "@voyant-travel/hono/module";
+import type { ApiExtension } from "@voyant-travel/hono/module";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { Hono } from "hono";
 export type ProductTaxFacts = {
@@ -129,5 +129,5 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
     };
 }, "/">;
 export declare function mountBookingTaxRoutes(hono: Hono, options?: BookingTaxRouteOptions): void;
-export declare function createBookingTaxHonoExtension(options?: BookingTaxRouteOptions): HonoExtension;
-export declare const createBookingTaxVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<HonoExtension>;
+export declare function createBookingTaxApiExtension(options?: BookingTaxRouteOptions): ApiExtension;
+export declare const createBookingTaxVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<ApiExtension>;

package/dist/booking-tax.js

@@ -320,7 +320,7 @@ export function createBookingTaxRoutes(options = {}) {
 export function mountBookingTaxRoutes(hono, options = {}) {
     hono.route("/v1/admin/bookings", createBookingTaxRoutes(options));
 }
-export function createBookingTaxHonoExtension(options = {}) {
+export function createBookingTaxApiExtension(options = {}) {
     const extension = {
         name: "booking-tax",
         module: "bookings",
@@ -331,5 +331,5 @@ export function createBookingTaxHonoExtension(options = {}) {
     };
 }
 export const createBookingTaxVoyantRuntime = defineGraphRuntimeFactory(async ({ getPort }) => {
-    return createBookingTaxHonoExtension(createFinanceBookingTaxRuntime(await getPort(financeOperatorSettingsRuntimePort)));
+    return createBookingTaxApiExtension(createFinanceBookingTaxRuntime(await getPort(financeOperatorSettingsRuntimePort)));
 });

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { Module } from "@voyant-travel/core";
-import type { HonoModule } from "@voyant-travel/hono/module";
+import type { ApiModule } from "@voyant-travel/hono/module";
 import { type BookingTaxRouteOptions } from "./booking-tax.js";
 import { type CheckoutRoutesOptions } from "./checkout-routes.js";
 import { type FinanceRuntimeOptions } from "./route-runtime.js";
@@ -18,21 +18,21 @@ export { createPublicFinanceRoutes, type PublicFinanceRouteOptions, publicFinanc
 export { type SupplierInvoiceRoutes, supplierInvoiceRoutes, } from "./routes-supplier-invoices.js";
 export { type PublicFinanceRuntimeOptions, publicFinanceService } from "./service-public.js";
 export declare const financeModule: Module;
-export interface FinanceHonoModuleOptions extends FinanceRuntimeOptions, PublicFinanceRouteOptions, CheckoutRoutesOptions, BookingTaxRouteOptions {
+export interface FinanceApiModuleOptions extends FinanceRuntimeOptions, PublicFinanceRouteOptions, CheckoutRoutesOptions, BookingTaxRouteOptions {
 }
-export declare function createFinanceHonoModule(options?: FinanceHonoModuleOptions): HonoModule;
-export declare const financeHonoModule: HonoModule;
-export declare const createFinanceVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<HonoModule>;
+export declare function createFinanceApiModule(options?: FinanceApiModuleOptions): ApiModule;
+export declare const financeApiModule: ApiModule;
+export declare const createFinanceVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<ApiModule>;
 export { type BookingCancellationSettlementInput, buildPaidBookingCancellationSettlementNote, closeTerminalBookingPaymentSchedules, financeBookingLifecycle, recordPaidBookingCancellationSettlement, } from "./booking-lifecycle.js";
-export { type BookingTaxRouteOptions, type BookingTaxSettings, computeBookingItemTaxLine, createBookingTaxHonoExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, type ProductTaxFacts, type ResolveBookingSellTaxRateOptions, type ResolveBookingTaxSettings, type ResolvedBookingSellTaxRate, resolveBookingSellTaxRate, type TaxPolicyCondition, type UpdateBookingTaxSettings, } from "./booking-tax.js";
+export { type BookingTaxRouteOptions, type BookingTaxSettings, computeBookingItemTaxLine, createBookingTaxApiExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, type ProductTaxFacts, type ResolveBookingSellTaxRateOptions, type ResolveBookingTaxSettings, type ResolvedBookingSellTaxRate, resolveBookingSellTaxRate, type TaxPolicyCondition, type UpdateBookingTaxSettings, } from "./booking-tax.js";
 export type { CardPaymentBilling, CardPaymentStartArgs, CardPaymentStarter, CardPaymentStartResult, } from "./card-payment.js";
 export { type DocumentDownloadEnvelope, type DocumentDownloadResolution, type DocumentDownloadResolver, resolveStoredDocumentDownload, type StoredDocumentReference, } from "./document-download.js";
-export { createInvoiceFxHonoExtension, createInvoiceFxRoutes, createVoyantDataFxExchangeRateResolver, type InvoiceExchangeRateResolution, type InvoiceFxContext, type InvoiceFxOptions, type InvoiceFxRouteOptions, type InvoiceFxSettings, mountInvoiceFxRoutes, type ResolvedInvoiceFxSettings, type ResolveInvoiceExchangeRate, type ResolveInvoiceExchangeRateInput, type ResolveInvoiceFxSettings, resolveInvoiceFxContext, resolveInvoiceFxSettingsOrDefault, type UpdateInvoiceFxSettings, type VoyantDataFxResolverOptions, } from "./invoice-fx.js";
+export { createInvoiceFxApiExtension, createInvoiceFxRoutes, createVoyantDataFxExchangeRateResolver, type InvoiceExchangeRateResolution, type InvoiceFxContext, type InvoiceFxOptions, type InvoiceFxRouteOptions, type InvoiceFxSettings, mountInvoiceFxRoutes, type ResolvedInvoiceFxSettings, type ResolveInvoiceExchangeRate, type ResolveInvoiceExchangeRateInput, type ResolveInvoiceFxSettings, resolveInvoiceFxContext, resolveInvoiceFxSettingsOrDefault, type UpdateInvoiceFxSettings, type VoyantDataFxResolverOptions, } from "./invoice-fx.js";
 export { type CreateOrderPaymentSessionsOptions, createOrderPaymentSessions, type EnsureOrderSessionParams, type OrderPaymentSessionSummary, type OrderPaymentSessions, type OrderPaymentSessionTargetType, type StartOrderPaymentProvider, } from "./order-payment-sessions.js";
 export type { ComputedScheduleEntry, ComputeScheduleInput, DepositKind, DepositRule, PaymentPolicy, PaymentPolicyCascadeLayers, PaymentPolicySource, PaymentScheduleEntryType, ResolvedPaymentPolicy, } from "./payment-policy.js";
 export { computePaymentSchedule, isPaymentPolicyEmpty, noDepositPolicy, normalizePaymentPolicy, policyShouldRequireFullPayment, resolveEffectivePaymentPolicy, } from "./payment-policy.js";
 export { createPaymentPolicyCascade, type PaymentPolicyCascade, type PaymentPolicyCascadeOptions, type PaymentPolicyCascadeReaders, readPolicySourceFromInternalNotes, stampPolicySourceOnBooking, } from "./payment-policy-cascade.js";
-export { type BookingScheduleRoutesOptions, createBookingScheduleAdminRoutes, createBookingScheduleHonoExtension, createBookingScheduleVoyantRuntime, createPaymentPolicyPublicRoutes, generatePaymentScheduleForBooking, type PaymentPolicyEntityContext, } from "./payment-schedule/routes.js";
+export { type BookingScheduleRoutesOptions, createBookingScheduleAdminRoutes, createBookingScheduleApiExtension, createBookingScheduleVoyantRuntime, createPaymentPolicyPublicRoutes, generatePaymentScheduleForBooking, type PaymentPolicyEntityContext, } from "./payment-schedule/routes.js";
 export { buildFinanceRouteRuntime, FINANCE_ROUTE_RUNTIME_CONTAINER_KEY, type FinanceRouteRuntime, type FinanceRuntimeOptions, } from "./route-runtime.js";
 export { bookingsCreateExtension } from "./routes-booking-create.js";
 export { createFinanceAdminDocumentRoutes, type FinanceDocumentRouteOptions, } from "./routes-documents.js";

package/dist/index.js

@@ -30,7 +30,7 @@ export const financeModule = {
     linkable: financeLinkable,
     requiresTransactionalDb: true,
 };
-export function createFinanceHonoModule(options = {}) {
+export function createFinanceApiModule(options = {}) {
     const adminRoutes = stampOpenApiRegistryApiId(new OpenAPIHono()
         .route("/", financeRoutes)
         .route("/", createFinanceCheckoutAdminRoutes(options))
@@ -63,9 +63,9 @@ export function createFinanceHonoModule(options = {}) {
         publicRoutes,
     };
 }
-export const financeHonoModule = createFinanceHonoModule();
+export const financeApiModule = createFinanceApiModule();
 export const createFinanceVoyantRuntime = defineGraphRuntimeFactory(async ({ api, getPort, getPorts, hasPort }) => {
-    const configured = createFinanceHonoModule(createFinanceRuntime(await getPort(financeHostRuntimePort), await getPort(financeNotificationsRuntimePort), hasPort(financeCheckoutPaymentStartersRuntimePort)
+    const configured = createFinanceApiModule(createFinanceRuntime(await getPort(financeHostRuntimePort), await getPort(financeNotificationsRuntimePort), hasPort(financeCheckoutPaymentStartersRuntimePort)
         ? await getPort(financeCheckoutPaymentStartersRuntimePort)
         : undefined, await getPorts(financeInvoiceSettlementPollerRuntimePort)));
     const bootstrap = configured.module.bootstrap;
@@ -87,13 +87,13 @@ export const createFinanceVoyantRuntime = defineGraphRuntimeFactory(async ({ api
     return selected;
 });
 export { buildPaidBookingCancellationSettlementNote, closeTerminalBookingPaymentSchedules, financeBookingLifecycle, recordPaidBookingCancellationSettlement, } from "./booking-lifecycle.js";
-export { computeBookingItemTaxLine, createBookingTaxHonoExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, resolveBookingSellTaxRate, } from "./booking-tax.js";
+export { computeBookingItemTaxLine, createBookingTaxApiExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, resolveBookingSellTaxRate, } from "./booking-tax.js";
 export { resolveStoredDocumentDownload, } from "./document-download.js";
-export { createInvoiceFxHonoExtension, createInvoiceFxRoutes, createVoyantDataFxExchangeRateResolver, mountInvoiceFxRoutes, resolveInvoiceFxContext, resolveInvoiceFxSettingsOrDefault, } from "./invoice-fx.js";
+export { createInvoiceFxApiExtension, createInvoiceFxRoutes, createVoyantDataFxExchangeRateResolver, mountInvoiceFxRoutes, resolveInvoiceFxContext, resolveInvoiceFxSettingsOrDefault, } from "./invoice-fx.js";
 export { createOrderPaymentSessions, } from "./order-payment-sessions.js";
 export { computePaymentSchedule, isPaymentPolicyEmpty, noDepositPolicy, normalizePaymentPolicy, policyShouldRequireFullPayment, resolveEffectivePaymentPolicy, } from "./payment-policy.js";
 export { createPaymentPolicyCascade, readPolicySourceFromInternalNotes, stampPolicySourceOnBooking, } from "./payment-policy-cascade.js";
-export { createBookingScheduleAdminRoutes, createBookingScheduleHonoExtension, createBookingScheduleVoyantRuntime, createPaymentPolicyPublicRoutes, generatePaymentScheduleForBooking, } from "./payment-schedule/routes.js";
+export { createBookingScheduleAdminRoutes, createBookingScheduleApiExtension, createBookingScheduleVoyantRuntime, createPaymentPolicyPublicRoutes, generatePaymentScheduleForBooking, } from "./payment-schedule/routes.js";
 export { buildFinanceRouteRuntime, FINANCE_ROUTE_RUNTIME_CONTAINER_KEY, } from "./route-runtime.js";
 export { bookingsCreateExtension } from "./routes-booking-create.js";
 export { createFinanceAdminDocumentRoutes, } from "./routes-documents.js";

package/dist/invoice-fx.d.ts

@@ -1,5 +1,5 @@
 import type { ModuleContainer } from "@voyant-travel/core";
-import type { HonoExtension } from "@voyant-travel/hono/module";
+import type { ApiExtension } from "@voyant-travel/hono/module";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { Hono } from "hono";
 import type { Env } from "./routes-shared.js";
@@ -129,5 +129,5 @@ export declare function createInvoiceFxRoutes(options?: InvoiceFxRouteOptions):
     };
 }, "/", "/invoice-fx-rate">;
 export declare function mountInvoiceFxRoutes(hono: Hono, options?: InvoiceFxRouteOptions): Hono;
-export declare function createInvoiceFxHonoExtension(options?: InvoiceFxRouteOptions): HonoExtension;
+export declare function createInvoiceFxApiExtension(options?: InvoiceFxRouteOptions): ApiExtension;
 export {};

package/dist/invoice-fx.js

@@ -174,7 +174,7 @@ export function mountInvoiceFxRoutes(hono, options = {}) {
     hono.route("/v1/admin/finance", createInvoiceFxRoutes(options));
     return hono;
 }
-export function createInvoiceFxHonoExtension(options = {}) {
+export function createInvoiceFxApiExtension(options = {}) {
     const extension = {
         name: "finance.invoice-fx",
         module: "finance",

package/dist/invoice-issue-authorization.d.ts

@@ -0,0 +1,69 @@
+/** Exact approval and idempotency orchestration for invoice issue Tools. */
+import { type ActionLedgerCapabilityAccessResult, type ActionLedgerRequestContextValues, actionLedgerService, type BuildActionLedgerApprovedExecutionFieldsInput, requestActionLedgerApproval } from "@voyant-travel/action-ledger";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { CreateInvoiceFromBookingInput } from "./service.js";
+export declare const FINANCE_INVOICE_ISSUE_CAPABILITY: {
+    readonly id: "finance:invoice-issue-from-booking";
+    readonly version: "v1";
+    readonly resource: "finance";
+    readonly action: "write";
+    readonly risk: "high";
+    readonly ledgerPolicy: "required";
+    readonly approvalPolicy: "required";
+    readonly reversible: false;
+    readonly allowedActorTypes: readonly ["staff", "system"];
+    readonly requiredGrants: readonly [{
+        readonly resource: "finance";
+        readonly action: "write";
+    }, {
+        readonly resource: "bookings";
+        readonly action: "read";
+    }];
+};
+export declare const FINANCE_INVOICE_ISSUE_APPROVAL_POLICY = "finance-invoice-issue-approval-v1";
+export declare const FINANCE_INVOICE_ISSUE_ACTION_NAME = "finance.invoice.issue_from_booking";
+export declare const FINANCE_INVOICE_ISSUE_TOOL_NAME = "finance.issue_invoice_from_booking";
+export interface FinanceInvoiceIssueAuthorizationInput {
+    db: PostgresJsDatabase;
+    commandInput: CreateInvoiceFromBookingInput;
+    actor?: string | null;
+    callerType?: string | null;
+    scopes?: readonly string[] | null;
+    isInternalRequest?: boolean | null;
+    requestContext: ActionLedgerRequestContextValues;
+    approvalId?: string | null;
+    idempotencyKey?: string | null;
+}
+export type FinanceInvoiceIssueAuthorizationResult = {
+    status: "authorized";
+    access: ActionLedgerCapabilityAccessResult;
+    approvedAction: BuildActionLedgerApprovedExecutionFieldsInput;
+} | {
+    status: "approval_required";
+    access: ActionLedgerCapabilityAccessResult;
+    requestedAction: Awaited<ReturnType<typeof requestActionLedgerApproval>>["requestedAction"];
+    approval: Awaited<ReturnType<typeof requestActionLedgerApproval>>["approval"];
+    replayed: boolean;
+} | {
+    status: "already_executed";
+    access: ActionLedgerCapabilityAccessResult;
+    invoiceId: string;
+} | {
+    status: "denied";
+    access: ActionLedgerCapabilityAccessResult;
+} | {
+    status: "missing_idempotency_key";
+    access: ActionLedgerCapabilityAccessResult;
+} | {
+    status: "idempotency_conflict";
+    access: ActionLedgerCapabilityAccessResult;
+    message: string;
+    existingActionId: string;
+} | {
+    status: "invalid_approval";
+    access: ActionLedgerCapabilityAccessResult;
+    validation: Exclude<Awaited<ReturnType<typeof actionLedgerService.validateApprovedAction>>, {
+        ok: true;
+    }>;
+};
+export declare function authorizeFinanceInvoiceIssue(input: FinanceInvoiceIssueAuthorizationInput): Promise<FinanceInvoiceIssueAuthorizationResult>;

package/dist/invoice-issue-authorization.js

@@ -0,0 +1,156 @@
+/** Exact approval and idempotency orchestration for invoice issue Tools. */
+import { ActionLedgerIdempotencyConflictError, actionLedgerService, appendActionLedgerMutation, buildActionApprovalCommandFingerprint, evaluateActionLedgerApprovalRequirement, evaluateActionLedgerCapabilityAccess, mapActionLedgerRequestContext, requestActionLedgerApproval, } from "@voyant-travel/action-ledger";
+export const FINANCE_INVOICE_ISSUE_CAPABILITY = {
+    id: "finance:invoice-issue-from-booking",
+    version: "v1",
+    resource: "finance",
+    action: "write",
+    risk: "high",
+    ledgerPolicy: "required",
+    approvalPolicy: "required",
+    reversible: false,
+    allowedActorTypes: ["staff", "system"],
+    requiredGrants: [
+        { resource: "finance", action: "write" },
+        { resource: "bookings", action: "read" },
+    ],
+};
+export const FINANCE_INVOICE_ISSUE_APPROVAL_POLICY = "finance-invoice-issue-approval-v1";
+export const FINANCE_INVOICE_ISSUE_ACTION_NAME = "finance.invoice.issue_from_booking";
+export const FINANCE_INVOICE_ISSUE_TOOL_NAME = "finance.issue_invoice_from_booking";
+export async function authorizeFinanceInvoiceIssue(input) {
+    const access = evaluateActionLedgerCapabilityAccess({
+        definition: FINANCE_INVOICE_ISSUE_CAPABILITY,
+        actor: input.actor,
+        callerType: input.callerType,
+        scopes: input.scopes,
+        isInternalRequest: input.isInternalRequest,
+    });
+    if (!access.allowed) {
+        await appendActionLedgerMutation(input.db, {
+            context: input.requestContext,
+            actionName: FINANCE_INVOICE_ISSUE_ACTION_NAME,
+            actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+            actionKind: "create",
+            status: "denied",
+            evaluatedRisk: access.evaluatedRisk,
+            targetType: "booking",
+            targetId: input.commandInput.bookingId,
+            routeOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+            capabilityId: access.capabilityId,
+            capabilityVersion: access.capabilityVersion,
+            authorizationSource: access.authorizationSource,
+            mutationDetail: {
+                summary: `Invoice issue denied: ${access.reason}`,
+                reversalKind: "none",
+            },
+        });
+        return { status: "denied", access };
+    }
+    const approvalRequirement = evaluateActionLedgerApprovalRequirement({
+        access,
+        conditionalApprovalRequired: true,
+        reasonCode: "invoice_issue_from_booking_requested_by_agent",
+    });
+    const fingerprint = await buildActionApprovalCommandFingerprint({
+        actionName: FINANCE_INVOICE_ISSUE_ACTION_NAME,
+        actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+        targetType: "booking",
+        targetId: input.commandInput.bookingId,
+        commandInput: input.commandInput,
+        approvalPolicy: approvalRequirement.approvalPolicy,
+        capabilityId: access.capabilityId,
+        capabilityVersion: access.capabilityVersion,
+        evaluatedRisk: approvalRequirement.evaluatedRisk,
+        reasonCode: approvalRequirement.reasonCode,
+    });
+    if (input.approvalId) {
+        const principal = mapActionLedgerRequestContext(input.requestContext);
+        const validation = await actionLedgerService.validateApprovedAction(input.db, {
+            approvalId: input.approvalId,
+            actionName: FINANCE_INVOICE_ISSUE_ACTION_NAME,
+            actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+            requestedActionKind: "create",
+            requestedActionStatus: "awaiting_approval",
+            targetType: "booking",
+            targetId: input.commandInput.bookingId,
+            routeOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+            principalType: principal.principalType,
+            principalId: principal.principalId,
+            idempotencyFingerprint: fingerprint,
+            executionActionKind: "create",
+            executionStatus: "succeeded",
+        });
+        if (!validation.ok) {
+            if (validation.reason === "already_executed" && validation.existingActionId) {
+                const existing = await actionLedgerService.getEntry(input.db, validation.existingActionId);
+                const resultRef = existing?.mutationDetail?.commandResultRef;
+                if (resultRef?.startsWith("invoice:")) {
+                    return {
+                        status: "already_executed",
+                        access,
+                        invoiceId: resultRef.slice("invoice:".length),
+                    };
+                }
+            }
+            return { status: "invalid_approval", access, validation };
+        }
+        return {
+            status: "authorized",
+            access,
+            approvedAction: {
+                requestedActionId: validation.requestedAction.id,
+                approvalId: validation.approval.id,
+                idempotencyFingerprint: validation.idempotencyFingerprint,
+            },
+        };
+    }
+    if (!input.idempotencyKey)
+        return { status: "missing_idempotency_key", access };
+    try {
+        const result = await requestActionLedgerApproval(input.db, {
+            context: input.requestContext,
+            actionName: FINANCE_INVOICE_ISSUE_ACTION_NAME,
+            actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+            actionKind: "create",
+            evaluatedRisk: approvalRequirement.evaluatedRisk,
+            targetType: "booking",
+            targetId: input.commandInput.bookingId,
+            routeOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+            capabilityId: access.capabilityId,
+            capabilityVersion: access.capabilityVersion,
+            authorizationSource: access.authorizationSource,
+            idempotencyScope: `${FINANCE_INVOICE_ISSUE_TOOL_NAME}:${input.commandInput.bookingId}`,
+            idempotencyKey: input.idempotencyKey,
+            idempotencyFingerprint: fingerprint,
+            mutationDetail: {
+                summary: "Invoice issue from booking awaiting approval",
+                reversalKind: "none",
+            },
+            approval: {
+                policyName: FINANCE_INVOICE_ISSUE_APPROVAL_POLICY,
+                policyVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+                riskSnapshot: approvalRequirement.evaluatedRisk,
+                reasonCode: approvalRequirement.reasonCode,
+            },
+        });
+        return {
+            status: "approval_required",
+            access,
+            requestedAction: result.requestedAction,
+            approval: result.approval,
+            replayed: result.replayed,
+        };
+    }
+    catch (error) {
+        if (error instanceof ActionLedgerIdempotencyConflictError) {
+            return {
+                status: "idempotency_conflict",
+                access,
+                message: error.message,
+                existingActionId: error.existingActionId,
+            };
+        }
+        throw error;
+    }
+}