@voyantjs/legal 0.49.0 → 0.50.1

package/README.md

@@ -68,6 +68,21 @@ configured `documentStorage`, and persists a contract attachment. `regenerate-pd
 uses the configured contract document generator and replaces the canonical
 generated document artifact.
 
+## Contract Lifecycle
+
+Contract lifecycle transitions are enforced by the contract service:
+
+```text
+draft -> issued -> sent -> signed -> executed
+```
+
+Contracts may be voided from any non-void stage. Each service transition appends
+to `stageHistory` and emits a domain event when an event bus is configured:
+`contract.issued`, `contract.sent`, `contract.signed`, `contract.executed`, or
+`contract.voided`. Event payloads are intentionally minimal: contract IDs,
+relationship IDs, stage names, and timestamps only; rendered bodies, variables,
+metadata, and signature details stay out of the event payload.
+
 ### Policies
 
 - **Policies** (`pol`) — policy definitions by kind (cancellation, payment, T&C, etc.)

package/dist/contracts/index.d.ts

@@ -7,8 +7,10 @@ export declare const contractsLinkable: {
     contract: LinkableDefinition;
     contractTemplate: LinkableDefinition;
 };
-export type { Contract, ContractAttachment, ContractNumberSeries, ContractSignature, ContractTemplate, ContractTemplateVersion, NewContract, NewContractAttachment, NewContractNumberSeries, NewContractSignature, NewContractTemplate, NewContractTemplateVersion, } from "./schema.js";
-export { contractAttachments, contractNumberSeries, contractSignatures, contracts, contractTemplates, contractTemplateVersions, } from "./schema.js";
+export type { ContractLifecycleEvent, ContractLifecycleHook, ContractLifecycleRuntimeOptions, ContractLifecycleStage, ContractLifecycleTransition, } from "./lifecycle.js";
+export { appendContractStageHistory, buildContractLifecycleEvent, CONTRACT_LIFECYCLE_EVENT_NAMES, CONTRACT_LIFECYCLE_STAGES, checkContractLifecycleTransition, createContractStageHistoryEntry, emitContractLifecycleEvent, } from "./lifecycle.js";
+export type { Contract, ContractAttachment, ContractNumberSeries, ContractSignature, ContractStageHistoryEntry, ContractStatus, ContractTemplate, ContractTemplateVersion, NewContract, NewContractAttachment, NewContractNumberSeries, NewContractSignature, NewContractTemplate, NewContractTemplateVersion, } from "./schema.js";
+export { contractAttachments, contractNumberSeries, contractSignatures, contractStatusValues, contracts, contractTemplates, contractTemplateVersions, } from "./schema.js";
 export { allocateContractNumber, ContractTemplateSyntaxError, contractsService, isContractTemplateSyntaxError, renderTemplate, validateContractTemplateBody, validateTemplateVariables, } from "./service.js";
 export type { ContractDocumentGeneratedEvent, ContractDocumentGeneratorContext, ContractDocumentRuntimeOptions, GeneratedContractDocumentArtifact, GeneratedContractDocumentRecord, StorageBackedContractDocumentGeneratorOptions, StorageBackedContractDocumentSerializer, StorageBackedContractDocumentUpload, } from "./service-documents.js";
 export { createPdfContractDocumentGenerator, createStorageBackedContractDocumentGenerator, defaultPdfContractDocumentSerializer, defaultStorageBackedContractDocumentSerializer, } from "./service-documents.js";
@@ -16,5 +18,5 @@ export type { CloudBrowserGoToOptions, CloudBrowserPdfInput, CloudBrowserPdfOpti
 export { createBrowserRenderedPdfContractDocumentSerializer, defaultContractHtmlWrapper, } from "./service-documents-browser.js";
 export type { ContractTemplateLiquidSnippet, ContractTemplateVariableCategory, ContractTemplateVariableDefinition, ContractTemplateVariableType, } from "./template-authoring.js";
 export { contractTemplateLiquidSnippets, contractTemplateVariableCatalog, } from "./template-authoring.js";
-export { contractBodyFormatSchema, contractListQuerySchema, contractNumberResetStrategySchema, contractScopeSchema, contractSignatureMethodSchema, contractStatusSchema, contractTemplateDefaultQuerySchema, contractTemplateListQuerySchema, generateContractDocumentInputSchema, generatedContractDocumentAttachmentSchema, generatedContractDocumentResultSchema, insertContractAttachmentSchema, insertContractNumberSeriesSchema, insertContractSchema, insertContractSignatureSchema, insertContractTemplateSchema, insertContractTemplateVersionSchema, renderTemplateInputSchema, updateContractAttachmentSchema, updateContractNumberSeriesSchema, updateContractSchema, updateContractTemplateSchema, } from "./validation.js";
+export { contractBodyFormatSchema, contractListQuerySchema, contractNumberResetStrategySchema, contractScopeSchema, contractSignatureMethodSchema, contractStageHistoryEntrySchema, contractStatusSchema, contractTemplateDefaultQuerySchema, contractTemplateListQuerySchema, generateContractDocumentInputSchema, generatedContractDocumentAttachmentSchema, generatedContractDocumentResultSchema, insertContractAttachmentSchema, insertContractNumberSeriesSchema, insertContractSchema, insertContractSignatureSchema, insertContractTemplateSchema, insertContractTemplateVersionSchema, renderTemplateInputSchema, updateContractAttachmentSchema, updateContractNumberSeriesSchema, updateContractSchema, updateContractTemplateSchema, } from "./validation.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,YAAY,EACV,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAA;AAErF,eAAO,MAAM,gBAAgB,EAAE,kBAK9B,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,kBAKtC,CAAA;AAED,eAAO,MAAM,iBAAiB;;;CAG7B,CAAA;AAED,YAAY,EACV,QAAQ,EACR,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,SAAS,EACT,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,6BAA6B,EAC7B,cAAc,EACd,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,8BAA8B,EAC9B,gCAAgC,EAChC,8BAA8B,EAC9B,iCAAiC,EACjC,+BAA+B,EAC/B,6CAA6C,EAC7C,uCAAuC,EACvC,mCAAmC,GACpC,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,kCAAkC,EAClC,4CAA4C,EAC5C,oCAAoC,EACpC,8CAA8C,GAC/C,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,yDAAyD,GAC1D,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,kDAAkD,EAClD,0BAA0B,GAC3B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EACV,6BAA6B,EAC7B,gCAAgC,EAChC,kCAAkC,EAClC,4BAA4B,GAC7B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,iCAAiC,EACjC,mBAAmB,EACnB,6BAA6B,EAC7B,oBAAoB,EACpB,kCAAkC,EAClC,+BAA+B,EAC/B,mCAAmC,EACnC,yCAAyC,EACzC,qCAAqC,EACrC,8BAA8B,EAC9B,gCAAgC,EAChC,oBAAoB,EACpB,6BAA6B,EAC7B,4BAA4B,EAC5B,mCAAmC,EACnC,yBAAyB,EACzB,8BAA8B,EAC9B,gCAAgC,EAChC,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD,YAAY,EACV,yBAAyB,EACzB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAA;AAErF,eAAO,MAAM,gBAAgB,EAAE,kBAK9B,CAAA;AAED,eAAO,MAAM,wBAAwB,EAAE,kBAKtC,CAAA;AAED,eAAO,MAAM,iBAAiB;;;CAG7B,CAAA;AAED,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,+BAA+B,EAC/B,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,0BAA0B,EAC1B,2BAA2B,EAC3B,8BAA8B,EAC9B,yBAAyB,EACzB,gCAAgC,EAChC,+BAA+B,EAC/B,0BAA0B,GAC3B,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,QAAQ,EACR,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,uBAAuB,EACvB,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,EACpB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,gBAAgB,EAChB,6BAA6B,EAC7B,cAAc,EACd,4BAA4B,EAC5B,yBAAyB,GAC1B,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,8BAA8B,EAC9B,gCAAgC,EAChC,8BAA8B,EAC9B,iCAAiC,EACjC,+BAA+B,EAC/B,6CAA6C,EAC7C,uCAAuC,EACvC,mCAAmC,GACpC,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EACL,kCAAkC,EAClC,4CAA4C,EAC5C,oCAAoC,EACpC,8CAA8C,GAC/C,MAAM,wBAAwB,CAAA;AAC/B,YAAY,EACV,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,yDAAyD,GAC1D,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,kDAAkD,EAClD,0BAA0B,GAC3B,MAAM,gCAAgC,CAAA;AACvC,YAAY,EACV,6BAA6B,EAC7B,gCAAgC,EAChC,kCAAkC,EAClC,4BAA4B,GAC7B,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,GAChC,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,wBAAwB,EACxB,uBAAuB,EACvB,iCAAiC,EACjC,mBAAmB,EACnB,6BAA6B,EAC7B,+BAA+B,EAC/B,oBAAoB,EACpB,kCAAkC,EAClC,+BAA+B,EAC/B,mCAAmC,EACnC,yCAAyC,EACzC,qCAAqC,EACrC,8BAA8B,EAC9B,gCAAgC,EAChC,oBAAoB,EACpB,6BAA6B,EAC7B,4BAA4B,EAC5B,mCAAmC,EACnC,yBAAyB,EACzB,8BAA8B,EAC9B,gCAAgC,EAChC,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,iBAAiB,CAAA"}

package/dist/contracts/index.js

@@ -15,9 +15,10 @@ export const contractsLinkable = {
     contract: contractLinkable,
     contractTemplate: contractTemplateLinkable,
 };
-export { contractAttachments, contractNumberSeries, contractSignatures, contracts, contractTemplates, contractTemplateVersions, } from "./schema.js";
+export { appendContractStageHistory, buildContractLifecycleEvent, CONTRACT_LIFECYCLE_EVENT_NAMES, CONTRACT_LIFECYCLE_STAGES, checkContractLifecycleTransition, createContractStageHistoryEntry, emitContractLifecycleEvent, } from "./lifecycle.js";
+export { contractAttachments, contractNumberSeries, contractSignatures, contractStatusValues, contracts, contractTemplates, contractTemplateVersions, } from "./schema.js";
 export { allocateContractNumber, ContractTemplateSyntaxError, contractsService, isContractTemplateSyntaxError, renderTemplate, validateContractTemplateBody, validateTemplateVariables, } from "./service.js";
 export { createPdfContractDocumentGenerator, createStorageBackedContractDocumentGenerator, defaultPdfContractDocumentSerializer, defaultStorageBackedContractDocumentSerializer, } from "./service-documents.js";
 export { createBrowserRenderedPdfContractDocumentSerializer, defaultContractHtmlWrapper, } from "./service-documents-browser.js";
 export { contractTemplateLiquidSnippets, contractTemplateVariableCatalog, } from "./template-authoring.js";
-export { contractBodyFormatSchema, contractListQuerySchema, contractNumberResetStrategySchema, contractScopeSchema, contractSignatureMethodSchema, contractStatusSchema, contractTemplateDefaultQuerySchema, contractTemplateListQuerySchema, generateContractDocumentInputSchema, generatedContractDocumentAttachmentSchema, generatedContractDocumentResultSchema, insertContractAttachmentSchema, insertContractNumberSeriesSchema, insertContractSchema, insertContractSignatureSchema, insertContractTemplateSchema, insertContractTemplateVersionSchema, renderTemplateInputSchema, updateContractAttachmentSchema, updateContractNumberSeriesSchema, updateContractSchema, updateContractTemplateSchema, } from "./validation.js";
+export { contractBodyFormatSchema, contractListQuerySchema, contractNumberResetStrategySchema, contractScopeSchema, contractSignatureMethodSchema, contractStageHistoryEntrySchema, contractStatusSchema, contractTemplateDefaultQuerySchema, contractTemplateListQuerySchema, generateContractDocumentInputSchema, generatedContractDocumentAttachmentSchema, generatedContractDocumentResultSchema, insertContractAttachmentSchema, insertContractNumberSeriesSchema, insertContractSchema, insertContractSignatureSchema, insertContractTemplateSchema, insertContractTemplateVersionSchema, renderTemplateInputSchema, updateContractAttachmentSchema, updateContractNumberSeriesSchema, updateContractSchema, updateContractTemplateSchema, } from "./validation.js";

package/dist/contracts/lifecycle.d.ts

@@ -0,0 +1,49 @@
+import type { EventBus } from "@voyantjs/core";
+import type { Contract, ContractStageHistoryEntry } from "./schema.js";
+export declare const CONTRACT_LIFECYCLE_STAGES: readonly ["draft", "issued", "sent", "signed", "executed", "expired", "void"];
+export type ContractLifecycleStage = (typeof CONTRACT_LIFECYCLE_STAGES)[number];
+export type ContractLifecycleTransition = "created" | "issued" | "sent" | "signed" | "executed" | "voided";
+export declare const CONTRACT_LIFECYCLE_EVENT_NAMES: {
+    readonly issued: "contract.issued";
+    readonly sent: "contract.sent";
+    readonly signed: "contract.signed";
+    readonly executed: "contract.executed";
+    readonly voided: "contract.voided";
+};
+export interface ContractLifecycleEvent {
+    contractId: string;
+    contractNumber: string | null;
+    scope: Contract["scope"];
+    previousStage: ContractLifecycleStage;
+    stage: ContractLifecycleStage;
+    transition: Exclude<ContractLifecycleTransition, "created">;
+    occurredAt: string;
+    personId: string | null;
+    organizationId: string | null;
+    supplierId: string | null;
+    channelId: string | null;
+    bookingId: string | null;
+    orderId: string | null;
+}
+export type ContractLifecycleHook = (event: ContractLifecycleEvent) => Promise<void> | void;
+export interface ContractLifecycleRuntimeOptions {
+    eventBus?: EventBus;
+    lifecycleHooks?: readonly ContractLifecycleHook[];
+}
+export type ContractLifecycleTransitionCheck = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "not_draft" | "not_issued" | "not_sent" | "not_signed" | "already_void";
+};
+export declare function createContractStageHistoryEntry(stage: ContractLifecycleStage, options?: {
+    previousStage?: ContractLifecycleStage | null;
+    transition?: ContractLifecycleTransition;
+    enteredAt?: Date;
+    actorId?: string | null;
+}): ContractStageHistoryEntry;
+export declare function appendContractStageHistory(current: readonly ContractStageHistoryEntry[] | null | undefined, entry: ContractStageHistoryEntry): ContractStageHistoryEntry[];
+export declare function checkContractLifecycleTransition(from: ContractLifecycleStage, transition: Exclude<ContractLifecycleTransition, "created">): ContractLifecycleTransitionCheck;
+export declare function buildContractLifecycleEvent(contract: Contract, previousStage: ContractLifecycleStage, stage: ContractLifecycleStage, transition: Exclude<ContractLifecycleTransition, "created">, occurredAt: Date): ContractLifecycleEvent;
+export declare function emitContractLifecycleEvent(runtime: ContractLifecycleRuntimeOptions | undefined, event: ContractLifecycleEvent): Promise<void>;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/contracts/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/contracts/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,yBAAyB,EAAkB,MAAM,aAAa,CAAA;AAEtF,eAAO,MAAM,yBAAyB,+EAQQ,CAAA;AAE9C,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE/E,MAAM,MAAM,2BAA2B,GACnC,SAAS,GACT,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,UAAU,GACV,QAAQ,CAAA;AAEZ,eAAO,MAAM,8BAA8B;;;;;;CAMyC,CAAA;AAEpF,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,KAAK,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;IACxB,aAAa,EAAE,sBAAsB,CAAA;IACrC,KAAK,EAAE,sBAAsB,CAAA;IAC7B,UAAU,EAAE,OAAO,CAAC,2BAA2B,EAAE,SAAS,CAAC,CAAA;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,sBAAsB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;AAE3F,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,cAAc,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAClD;AAED,MAAM,MAAM,gCAAgC,GACxC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,cAAc,CAAA;CAAE,CAAA;AAQlG,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE;IACP,aAAa,CAAC,EAAE,sBAAsB,GAAG,IAAI,CAAA;IAC7C,UAAU,CAAC,EAAE,2BAA2B,CAAA;IACxC,SAAS,CAAC,EAAE,IAAI,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACnB,GACL,yBAAyB,CAQ3B;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,SAAS,yBAAyB,EAAE,GAAG,IAAI,GAAG,SAAS,EAChE,KAAK,EAAE,yBAAyB,GAC/B,yBAAyB,EAAE,CAa7B;AAED,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,sBAAsB,EAC5B,UAAU,EAAE,OAAO,CAAC,2BAA2B,EAAE,SAAS,CAAC,GAC1D,gCAAgC,CAelC;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,sBAAsB,EACrC,KAAK,EAAE,sBAAsB,EAC7B,UAAU,EAAE,OAAO,CAAC,2BAA2B,EAAE,SAAS,CAAC,EAC3D,UAAU,EAAE,IAAI,GACf,sBAAsB,CAgBxB;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,+BAA+B,GAAG,SAAS,EACpD,KAAK,EAAE,sBAAsB,iBAe9B"}

package/dist/contracts/lifecycle.js

@@ -0,0 +1,87 @@
+export const CONTRACT_LIFECYCLE_STAGES = [
+    "draft",
+    "issued",
+    "sent",
+    "signed",
+    "executed",
+    "expired",
+    "void",
+];
+export const CONTRACT_LIFECYCLE_EVENT_NAMES = {
+    issued: "contract.issued",
+    sent: "contract.sent",
+    signed: "contract.signed",
+    executed: "contract.executed",
+    voided: "contract.voided",
+};
+function isContractLifecycleStage(value) {
+    return (typeof value === "string" && CONTRACT_LIFECYCLE_STAGES.includes(value));
+}
+export function createContractStageHistoryEntry(stage, options = {}) {
+    return {
+        stage,
+        previousStage: options.previousStage ?? null,
+        transition: options.transition ?? "created",
+        enteredAt: (options.enteredAt ?? new Date()).toISOString(),
+        ...(options.actorId === undefined ? {} : { actorId: options.actorId }),
+    };
+}
+export function appendContractStageHistory(current, entry) {
+    const existing = Array.isArray(current)
+        ? current.filter((item) => isContractLifecycleStage(item.stage) &&
+            (item.previousStage === null ||
+                item.previousStage === undefined ||
+                isContractLifecycleStage(item.previousStage)) &&
+            typeof item.transition === "string" &&
+            typeof item.enteredAt === "string")
+        : [];
+    return [...existing, entry];
+}
+export function checkContractLifecycleTransition(from, transition) {
+    switch (transition) {
+        case "issued":
+            return from === "draft" ? { ok: true } : { ok: false, reason: "not_draft" };
+        case "sent":
+            return from === "issued" || from === "sent"
+                ? { ok: true }
+                : { ok: false, reason: "not_issued" };
+        case "signed":
+            return from === "sent" ? { ok: true } : { ok: false, reason: "not_sent" };
+        case "executed":
+            return from === "signed" ? { ok: true } : { ok: false, reason: "not_signed" };
+        case "voided":
+            return from === "void" ? { ok: false, reason: "already_void" } : { ok: true };
+    }
+}
+export function buildContractLifecycleEvent(contract, previousStage, stage, transition, occurredAt) {
+    return {
+        contractId: contract.id,
+        contractNumber: contract.contractNumber ?? null,
+        scope: contract.scope,
+        previousStage,
+        stage,
+        transition,
+        occurredAt: occurredAt.toISOString(),
+        personId: contract.personId ?? null,
+        organizationId: contract.organizationId ?? null,
+        supplierId: contract.supplierId ?? null,
+        channelId: contract.channelId ?? null,
+        bookingId: contract.bookingId ?? null,
+        orderId: contract.orderId ?? null,
+    };
+}
+export async function emitContractLifecycleEvent(runtime, event) {
+    const eventName = CONTRACT_LIFECYCLE_EVENT_NAMES[event.transition];
+    await runtime?.eventBus?.emit(eventName, event, {
+        category: "domain",
+        source: "service",
+    });
+    for (const hook of runtime?.lifecycleHooks ?? []) {
+        try {
+            await hook(event);
+        }
+        catch (error) {
+            console.error(`[legal] lifecycle hook failed for ${eventName}:`, error);
+        }
+    }
+}

package/dist/contracts/route-runtime.d.ts

@@ -1,10 +1,12 @@
 import type { EventBus } from "@voyantjs/core";
 import type { StorageProvider } from "@voyantjs/storage";
+import type { ContractLifecycleHook } from "./lifecycle.js";
 import type { ContractDocumentGenerator, ContractsRouteOptions } from "./routes.js";
 export type ContractsRouteRuntime = {
     documentGenerator?: ContractDocumentGenerator;
     documentStorage?: StorageProvider | null;
     eventBus?: EventBus;
+    lifecycleHooks?: readonly ContractLifecycleHook[];
 };
 export declare const CONTRACTS_ROUTE_RUNTIME_CONTAINER_KEY = "providers.legal.contracts.runtime";
 export declare function buildContractsRouteRuntime(bindings: Record<string, unknown>, options?: ContractsRouteOptions): ContractsRouteRuntime;

package/dist/contracts/route-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-runtime.d.ts","sourceRoot":"","sources":["../../src/contracts/route-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD,OAAO,KAAK,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnF,MAAM,MAAM,qBAAqB,GAAG;IAClC,iBAAiB,CAAC,EAAE,yBAAyB,CAAA;IAC7C,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACpB,CAAA;AAED,eAAO,MAAM,qCAAqC,sCAAsC,CAAA;AAExF,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,qBAAqB,CAMvB"}
+{"version":3,"file":"route-runtime.d.ts","sourceRoot":"","sources":["../../src/contracts/route-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAExD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAC3D,OAAO,KAAK,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnF,MAAM,MAAM,qBAAqB,GAAG;IAClC,iBAAiB,CAAC,EAAE,yBAAyB,CAAA;IAC7C,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,CAAA;IACxC,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,cAAc,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAA;CAClD,CAAA;AAED,eAAO,MAAM,qCAAqC,sCAAsC,CAAA;AAExF,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,OAAO,GAAE,qBAA0B,GAClC,qBAAqB,CAOvB"}

package/dist/contracts/route-runtime.js

@@ -4,5 +4,6 @@ export function buildContractsRouteRuntime(bindings, options = {}) {
         documentGenerator: options.resolveDocumentGenerator?.(bindings) ?? options.documentGenerator,
         documentStorage: options.resolveDocumentStorage?.(bindings) ?? options.documentStorage,
         eventBus: options.resolveEventBus?.(bindings) ?? options.eventBus,
+        lifecycleHooks: options.resolveLifecycleHooks?.(bindings) ?? options.lifecycleHooks,
     };
 }