v1.3.0

.gitea/workflows/default_nottags.yaml

@@ -6,19 +6,19 @@ on:
       - '**'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  NPMCI_COMPUTED_REPOURL: https://${-{gitea.repository_owner}-}:${-{secrets.GITEA_TOKEN}-}@{{module.githost}}/${-{gitea.repository}-}.git
-  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM: ${-{secrets.NPMCI_TOKEN_NPM}-}
-  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_TOKEN_NPM2: ${-{secrets.NPMCI_TOKEN_NPM2}-}
-  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_GIT_GITHUBTOKEN: ${-{secrets.NPMCI_GIT_GITHUBTOKEN}-}
-  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+  NPMCI_URL_CLOUDLY: ${-{secrets.NPMCI_URL_CLOUDLY}-}
 
 jobs:
   security:
     runs-on: ubuntu-latest
     continue-on-error: true
     container:
-      image: ${{ env.IMAGE }}
+      image: ${-{ env.IMAGE }-}
 
     steps:
       - uses: actions/checkout@v3
@@ -26,7 +26,7 @@ jobs:
       - name: Install pnpm and npmci
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
 
       - name: Run npm prepare
         run: npmci npm prepare
@@ -44,11 +44,11 @@ jobs:
         continue-on-error: true
 
   test:
-    if: ${{ always() }}
+    if: ${-{ always() }-}
     needs: security
     runs-on: ubuntu-latest
     container:
-      image: ${{ env.IMAGE }}
+      image: ${-{ env.IMAGE }-}
 
     steps:
       - uses: actions/checkout@v3

.gitea/workflows/default_tags.yaml

@@ -6,19 +6,19 @@ on:
       - '*'
 
 env:
-  IMAGE: registry.gitlab.com/hosttoday/ht-docker-node:npmci
+  IMAGE: code.foss.global/host.today/ht-docker-node:npmci
-  NPMCI_COMPUTED_REPOURL: https://${{gitea.repository_owner}}:${{secrets.GITEA_TOKEN}}@gitea.lossless.digital/${{gitea.repository}}.git
+  NPMCI_COMPUTED_REPOURL: https://${-{gitea.repository_owner}-}:${-{secrets.GITEA_TOKEN}-}@{{module.githost}}/${-{gitea.repository}-}.git
-  NPMCI_TOKEN_NPM: ${{secrets.NPMCI_TOKEN_NPM}}
+  NPMCI_TOKEN_NPM: ${-{secrets.NPMCI_TOKEN_NPM}-}
-  NPMCI_TOKEN_NPM2: ${{secrets.NPMCI_TOKEN_NPM2}}
+  NPMCI_TOKEN_NPM2: ${-{secrets.NPMCI_TOKEN_NPM2}-}
-  NPMCI_GIT_GITHUBTOKEN: ${{secrets.NPMCI_GIT_GITHUBTOKEN}}
+  NPMCI_GIT_GITHUBTOKEN: ${-{secrets.NPMCI_GIT_GITHUBTOKEN}-}
-  NPMCI_URL_CLOUDLY: ${{secrets.NPMCI_URL_CLOUDLY}}
+  NPMCI_URL_CLOUDLY: ${-{secrets.NPMCI_URL_CLOUDLY}-}
 
 jobs:
   security:
     runs-on: ubuntu-latest
     continue-on-error: true
     container:
-      image: ${{ env.IMAGE }}
+      image: ${-{ env.IMAGE }-}
 
     steps:
       - uses: actions/checkout@v3
@@ -26,7 +26,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Audit production dependencies
@@ -42,11 +42,11 @@ jobs:
         continue-on-error: true
 
   test:
-    if: ${{ always() }}
+    if: ${-{ always() }-}
     needs: security
     runs-on: ubuntu-latest
     container:
-      image: ${{ env.IMAGE }}
+      image: ${-{ env.IMAGE }-}
 
     steps:
       - uses: actions/checkout@v3
@@ -54,7 +54,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Test stable
@@ -74,7 +74,7 @@ jobs:
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     container:
-      image: ${{ env.IMAGE }}
+      image: ${-{ env.IMAGE }-}
 
     steps:
       - uses: actions/checkout@v3
@@ -82,7 +82,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Release
@@ -95,7 +95,7 @@ jobs:
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
     runs-on: ubuntu-latest
     container:
-      image: ${{ env.IMAGE }}
+      image: ${-{ env.IMAGE }-}
     continue-on-error: true
 
     steps:
@@ -104,7 +104,7 @@ jobs:
       - name: Prepare
         run: |
           pnpm install -g pnpm
-          pnpm install -g @shipzone/npmci
+          pnpm install -g @ship.zone/npmci
           npmci npm prepare
 
       - name: Code quality

.gitignore

@@ -3,7 +3,6 @@
 # artifacts
 coverage/
 public/
-pages/
 
 # installs
 node_modules/
@@ -17,4 +16,8 @@ node_modules/
 dist/
 dist_*/
 
-# custom
+# AI
+.claude/
+.serena/
+
+#------# custom

changelog.md

@@ -1,26 +1,61 @@
 # Changelog
 
+## 2025-12-18 - 1.3.0 - feat(interfaces)
+add comprehensive TypeScript interface modules, demo data, docs, and publish metadata
+
+- Introduce many new interface modules under ts_interfaces (contract, attachments, identity, versioning, legal, lifecycle, pdf, signature, terms, collaboration) with types and factory functions
+- Add demo data package (ts_demodata) including a detailed demo contract and updated demodata readme
+- Add/expand package readmes and ts/readme for @signature.digital/tools, @signature.digital/interfaces and @signature.digital/demodata
+- Update tspublish.json files to declare package dependencies for monorepo publishing
+- Enable experimentalDecorators in tsconfig.json
+- Add MIT license file
+
+## 2025-12-18 - 1.2.0 - feat(tools)
+add demodata feature, update package metadata, tsconfig paths, CI/workflows, and bump deps
+
+- Add demodata subpackage (@signature.digital/demodata) and export entry
+- Introduce tsconfig path aliases for @signature.digital/tools, @signature.digital/demodata, and @signature.digital/interfaces
+- Update package.json metadata (repository, bugs, homepage), add pnpm overrides, and bump dev/deps (@git.zone/tsbuild, @git.zone/tstest, @tsclass/tsclass)
+- Rename and configure tspublish.json files to include package names and registries for publishing
+- Fix interfaces: change IInvolvedParty.contact type to plugins.tsclass.business.TContact
+- Update tests to use @git.zone/tstest/tapbundle and export tap.start()
+- Revise CI workflow files to use code.foss.global image, new secret placeholder formatting, and @ship.zone/npmci package name
+- Rework npmextra.json structure and add release registries and szci config
+- Update README and changelog content and add minor .gitignore entries for AI tools
+
+## 2024-12-19 - 1.1.0 - feat(demodata)
+
+Add demo data feature for contracts
+
+- Introduced demo contract data for Minijob Employment Contract outlining details for employer and employee roles.
+- Enhanced package.json with new export entry for demodata.
+- Implemented new ts_demodata directory with sample contract representation.
+
 ## 2024-12-19 - 1.0.11 - fix(interfaces)
+
 Fixed import path in ts_interfaces/index.ts
 
 - Corrected import path for plugins in ts_interfaces/index.ts to prevent module resolution issues.
 
 ## 2024-12-18 - 1.0.10 - fix(test)
+
 Add initial test for portablecontract
 
-
 ## 2024-12-18 - 1.0.9 - fix(ts_interfaces)
+
 Resolved missing exports in plugins.ts
 
 - Added export statements in ts_interfaces/plugins.ts to resolve module issues.
 
 ## 2024-12-18 - 1.0.8 - fix(core)
+
 Fixed export paths in package configuration
 
 - Updated exports paths in package.json for proper module resolution.
 - Fixed export statement in ts/index.ts to reference the correct path for interface exports.
 
 ## 2024-12-18 - 1.0.7 - fix(project)
+
 Corrected misalignment in file structure and package metadata.
 
 - Updated the file export path in ts/index.ts to correct interface export location.
@@ -29,10 +64,11 @@ Corrected misalignment in file structure and package metadata.
 - Ensured proper build script path in package.json.
 
 ## 2024-12-18 - 1.0.6 - fix(core)
+
 No code changes detected.
 
-
 ## 2024-12-18 - 1.0.5 - fix(core)
+
 Corrected package and npm extra configuration to ensure consistent naming.
 
 - Updated 'name' field in package.json from '@signature.digital/portablecontract' to '@signature.digital/tools'.
@@ -40,6 +76,7 @@ Corrected package and npm extra configuration to ensure consistent naming.
 - Updated 'npmPackagename' in npmextra.json from '@signature.digital/portablecontract' to '@signature.digital/tools'.
 
 ## 2023-11-22 to 2023-11-28 - 1.0.1 to 1.0.4 - core updates
+
 Fixes and updates in the core component.
 
 - Updated core module to enhance performance and fix minor bugs in version 1.0.1

license

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Task Venture Capital GmbH (hello@task.vc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

npmextra.json

@@ -1,5 +1,5 @@
 {
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "gitlab.com",
@@ -27,13 +27,16 @@
         "contract validation",
         "unit testing"
       ]
+    },
+    "release": {
+      "registries": ["https://verdaccio.lossless.digital"],
+      "accessLevel": "public"
     }
   },
-  "npmci": {
+  "@git.zone/tsdoc": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  },
-  "tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

package.json

@@ -1,11 +1,12 @@
 {
   "name": "@signature.digital/tools",
-  "version": "1.0.11",
+  "version": "1.3.0",
   "private": false,
   "description": "A TypeScript package providing utilities for managing digital contracts with modular interfaces and business context integration.",
   "exports": {
     ".": "./ts/index.js",
-    "./interfaces": "./dist_ts_interfaces/index.js"
+    "./interfaces": "./dist_ts_interfaces/index.js",
+    "./demodata": "./dist_ts_demodata/index.js"
   },
   "type": "module",
   "author": "Task Venture Capital GmbH",
@@ -16,24 +17,23 @@
     "buildDocs": "(tsdoc)"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.2.0",
+    "@git.zone/tsbuild": "^2.6.1",
     "@git.zone/tsbundle": "^2.1.0",
     "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tstest": "^1.0.90",
+    "@git.zone/tstest": "^1.0.96",
-    "@push.rocks/tapbundle": "^5.5.3",
     "@types/node": "^22.10.2"
   },
   "dependencies": {
-    "@tsclass/tsclass": "^4.2.0"
+    "@tsclass/tsclass": "^9.3.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/signature.digital/portablecontract.git"
+    "url": "https://gitlab.com/signature.digital/tools.git"
   },
   "bugs": {
-    "url": "https://gitlab.com/signature.digital/portablecontract/issues"
+    "url": "https://gitlab.com/signature.digital/tools/issues"
   },
-  "homepage": "https://gitlab.com/signature.digital/portablecontract#readme",
+  "homepage": "https://gitlab.com/signature.digital/tools#readme",
   "browserslist": [
     "last 1 chrome versions"
   ],
@@ -66,5 +66,8 @@
     "dynamic role assignment",
     "contract validation",
     "unit testing"
-  ]
+  ],
+  "pnpm": {
+    "overrides": {}
+  }
 }

readme.md

@@ -1,315 +1,442 @@
 # @signature.digital/tools
-A TypeScript package offering utility interfaces and classes for efficient digital contract management and business context integration with a modular design.
+
+A comprehensive TypeScript library for **digital contract management** – covering every stage from drafting and collaboration to e-signatures, legal compliance, and archival. 📜✨
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Features at a Glance
+
+🔹 **99.9% Contract Coverage** – Supports employment, service, sales, lease, license, NDA, financial, and dozens more contract types
+🔹 **eIDAS Compliant Signatures** – Simple, advanced, and qualified electronic signatures with full audit trails
+🔹 **Identity Verification** – Passport/NFC, document+selfie, video ident, and third-party IdP support
+🔹 **Legal Compliance** – RFC 3161 TSA timestamps, blockchain anchoring, LTV (Long-Term Validation)
+🔹 **Version Control** – Semantic versioning, branches, diffs, and amendment tracking
+🔹 **Real-time Collaboration** – Comments, suggestions, presence tracking, conflict resolution
+🔹 **Complete Audit Logs** – Hash-chained, tamper-evident action history
+🔹 **PDF Generation** – Configurable templates, branding, security, and digital signing
+🔹 **TypeScript-First** – Full type safety with comprehensive interfaces and factory functions
 
 ## Install
-To install the `@signature.digital/tools` package, use your preferred package manager. For npm, run the following command:
 
 ```bash
+# Using pnpm (recommended)
+pnpm add @signature.digital/tools
+
+# Using npm
 npm install @signature.digital/tools
 ```
 
-Alternatively, if you are using Yarn, you can add the package with:
+## Quick Start
-
-```bash
-yarn add @signature.digital/tools
-```
-
-Ensure your development environment supports ECMAScript Modules. In your `tsconfig.json`, you should set the `"module"` option to `"ESNext"` or a compatible module type that supports ES Modules.
-
-## Usage
-
-This guide details the comprehensive features of the `@signature.digital/tools` package, designed to streamline digital contract management in TypeScript applications. By using this package, you can leverage the structured capabilities of TypeScript to define, manage, and operate on digital contracts effectively.
-
-### Introduction to the Module
-
-The `@signature.digital/tools` package capitalizes on TypeScript's robust typing system to mold digital contract management paradigms. It encourages an interface-driven approach to designing contracts, promotes modularity, and integrates business context inherently within its structures. 
-
-### Key Features
-
-1. **Interface-Driven Design:**
-   Utilize TypeScript interfaces to clearly delineate data structures for contracts. This results in easily maintainable, testable, and scalable digital contract solutions.
-
-2. **Modular Architecture:**
-   Divide and conquer complex contract datasets by representing them as reusable modules.
-
-3. **Business Contextualization:**
-   Seamlessly integrate business metadata into your contracts to reflect real-world applications and business scenarios.
-
-### Usage Scenarios
-
-Below are practical examples to help you understand and leverage the full capabilities of the `@signature.digital/tools` package.
-
-#### 1. Designing Contract Components
-
-Begin by defining the core components of a contract using the provided interfaces. Start with `IRole`, `IInvolvedParty`, `IParagraph`, and `IPortableContract`:
 
 ```typescript
-import { IPortableContract, IRole, IInvolvedParty, IParagraph } from '@signature.digital/tools';
+import {
-import { tsclass } from '@signature.digital/tools';
+  createEmptyContract,
+  createRole,
+  createInvolvedParty,
+  createParagraph,
+  type IPortableContract,
+} from '@signature.digital/tools';
 
-const createRoles = (): IRole[] => [
+// Create a new employment contract
-  {
+const contract = createEmptyContract(
-    id: 'role-001',
+  'Software Developer Employment Agreement',
-    name: 'Legal Advisor',
+  'employment',
-    description: 'Advises on legal obligations and ensures compliance.'
+  'employment_full_time',
-  },
+  'user-123',
-  {
+  'en'
-    id: 'role-002',
-    name: 'Stakeholder',
-    description: 'Interest in the outcome of the contract.'
-  }
-];
-
-const createContacts = (): tsclass.business.IContact[] => [
-  {
-    email: 'advisor@legalfirm.com',
-    address: '123 Legal Firm St, Legal City'
-  },
-  {
-    email: 'stakeholder@business.com',
-    address: '456 Business Way, Industry City'
-  }
-];
-
-const createParagraphs = (): IParagraph[] => [
-  {
-    uniqueId: 'para-001',
-    parent: null,
-    title: 'Introduction',
-    content: 'Introduction to the contract, setting expectations and scope of the agreement.'
-  },
-  {
-    uniqueId: 'para-002',
-    parent: null,
-    title: 'Obligations',
-    content: 'Details the specific obligations and responsibilities of each involved party.'
-  }
-];
-
-const createPortableContract = (): IPortableContract => {
-  const roles = createRoles();
-  const contacts = createContacts();
-  const paragraphs = createParagraphs();
-
-  return {
-    title: 'Digital Service Agreement',
-    context: 'A digital service provision framework between organizations.',
-    availableRoles: roles,
-    involvedParties: [
-      { role: roles[0].name, contact: contacts[0] },
-      { role: roles[1].name, contact: contacts[1] }
-    ],
-    priorContracts: [],
-    paragraphs
-  };
-};
-
-const contract = createPortableContract();
-console.log(contract);
-```
-
-This example highlights how you can define the roles, contacts, and paragraphs that collectively represent a comprehensive digital contract model.
-
-#### 2. Expanding Contract Details
-
-Extend core contracts to encapsulate more details specific to your organizational needs. You can add dates, custom attributes, or any other relevant information:
-
-```typescript
-interface IExtendedPortableContract extends IPortableContract {
-  startDate: Date;
-  endDate: Date;
-  customAttributes?: Record<string, any>;
-}
-
-const createExtendedContract = (): IExtendedPortableContract => {
-  const baseContract = createPortableContract();
-  return {
-    ...baseContract,
-    startDate: new Date('2023-01-01'),
-    endDate: new Date('2024-01-01'),
-    customAttributes: {
-      department: 'Legal',
-      projectCode: 'DSA2023'
-    }
-  };
-};
-
-const extendedContract = createExtendedContract();
-console.log(extendedContract);
-```
-
-#### 3. Maintaining Contract History
-
-Managing contractual history provides a strategic advantage in legal and administrative processes. Employ the `priorContracts` attribute to keep track of iterations:
-
-```typescript
-const initialContractVersion: IPortableContract = {
-  title: 'Initial Service Agreement',
-  context: 'Foundation agreement before the current digital service contract.',
-  availableRoles: createRoles(),
-  involvedParties: [
-    { role: 'Legal Advisor', contact: createContacts()[0] }
-  ],
-  priorContracts: [],
-  paragraphs: []
-};
-
-const updatedContractVersion = {
-  ...initialContractVersion,
-  title: 'Revised Digital Service Agreement',
-  priorContracts: [initialContractVersion]
-};
-
-console.log(updatedContractVersion);
-```
-
-This functionality is crucial for firms that require detailed records of contractual changes over time.
-
-#### 4. Integrating Business Entities
-
-Leverage the power of `@tsclass/tsclass` to seamlessly embed business information within contracts, enhancing clarity and context:
-
-```typescript
-const businessParty = {
-  role: 'Business Analyst',
-  contact: {
-    email: 'analyst@corporation.com',
-    address: '123 Business Lane, Tech City'
-  }
-};
-
-extendedContract.involvedParties.push(businessParty);
-console.log(extendedContract.involvedParties);
-```
-
-This level of integration is perfect for incorporating stakeholders' information.
-
-#### 5. Implementing Validation Logic
-
-While the package promotes interface-based design, users must implement validation patterns to ensure contract data integrity. Below is an example of how to perform basic validations:
-
-```typescript
-function isValidContractStructure(contract: IPortableContract): boolean {
-  return (
-    contract.context !== '' &&
-    contract.availableRoles.length > 0 &&
-    contract.involvedParties.length > 0 &&
-    contract.paragraphs.every(paragraph => paragraph.content !== '')
 );
-}
 
-if (!isValidContractStructure(extendedContract)) {
+// Define roles
-  throw new Error('Invalid contract structure detected!');
+const employerRole = createRole('employer', 'Employer', 'The hiring company');
+const employeeRole = createRole('employee', 'Employee', 'The hired individual');
+
+contract.availableRoles.push(employerRole, employeeRole);
+
+// Add contract content
+contract.paragraphs.push(
+  createParagraph('Scope of Work', 'The Employee shall perform software development duties...', 'clause', 1),
+  createParagraph('Compensation', 'The Employee shall receive a monthly salary of...', 'clause', 2)
+);
+
+console.log(contract.id); // UUID
+console.log(contract.lifecycle.currentStatus); // 'draft'
+```
+
+## Package Structure
+
+This package provides **three entry points**:
+
+| Entry Point | Package Name | Description |
+|-------------|--------------|-------------|
+| `@signature.digital/tools` | `@signature.digital/tools` | Main export – re-exports all interfaces |
+| `@signature.digital/tools/interfaces` | `@signature.digital/interfaces` | Core TypeScript interfaces |
+| `@signature.digital/tools/demodata` | `@signature.digital/demodata` | Demo contracts for testing |
+
+## Core Concepts
+
+### 📄 Contract Types
+
+The library supports a comprehensive taxonomy of contract types:
+
+```typescript
+type TContractCategory =
+  | 'employment'    // Full-time, part-time, minijob, freelance, executive...
+  | 'service'       // SLA, MSA, maintenance, support agreements
+  | 'sales'         // Purchase orders, distribution, supply agreements
+  | 'lease'         // Residential, commercial, equipment, vehicle
+  | 'license'       // Software, patent, trademark, franchise
+  | 'partnership'   // Joint ventures, strategic alliances
+  | 'confidentiality' // NDA (unilateral/bilateral/multilateral)
+  | 'financial'     // Loans, guarantees, investments
+  | 'other';        // Settlement, POA, LOI, MOU
+```
+
+### 🔐 Signature System
+
+Full support for eIDAS-compliant signatures:
+
+```typescript
+import type { ISignature, TSignatureType, TSignatureLegalLevel } from '@signature.digital/tools';
+
+// Supported signature types
+type TSignatureType = 'drawn' | 'typed' | 'click' | 'digital' | 'qualified' | 'biometric';
+
+// eIDAS legal levels
+type TSignatureLegalLevel = 'simple' | 'advanced' | 'qualified';
+```
+
+**Signature data structures** include:
+- **Drawn signatures** – Stroke data from signature pads (compatible with signature_pad library)
+- **Typed signatures** – Text with font styling
+- **Click-to-sign** – Acknowledgment-based acceptance
+- **Digital signatures** – X.509/PKI certificate-based (PKCS#7)
+- **Qualified signatures** – eIDAS QES via QTSP
+- **Biometric** – Fingerprint, facial, voice (extensible)
+
+### 🪪 Identity Verification
+
+```typescript
+import type { IIdentityVerificationResult, TIdentityVerificationMethod } from '@signature.digital/tools';
+
+// Supported verification methods
+type TIdentityVerificationMethod =
+  | 'email' | 'sms' | 'knowledge'
+  | 'document_upload' | 'document_nfc' | 'document_ocr'
+  | 'biometric_facial' | 'video_ident'
+  | 'bankid' | 'eid' | 'third_party_idp';
+```
+
+### ⚖️ Legal Compliance
+
+**RFC 3161 TSA Timestamps:**
+```typescript
+import type { ITsaTimestamp, IBlockchainTimestamp } from '@signature.digital/tools';
+
+// TSA timestamp with qualified status
+interface ITsaTimestamp {
+  authority: ITsaAuthority;
+  token: ITsaToken;
+  verification: ITsaVerification;
+  qualifiedInfo?: IQualifiedTsaInfo;
 }
 ```
 
-This sample function demonstrates a straightforward mechanism to verify that the contract structure adheres to defined rules and prevents incorrect data entries.
+**Blockchain Anchoring:**
-
-### Advanced Usage
-
-Let's delve into more intricate capabilities and scenarios that `@signature.digital/tools` can facilitate:
-
-#### Asynchronous Loading and Initialization
-
-For scenarios where parts of contracts or their dependencies are fetched from databases or APIs, the `@signature.digital/tools` suite can interact seamlessly with asynchronous sources:
-
 ```typescript
-async function fetchContractData(): Promise<IPortableContract> {
+// Supported networks
-  // Simulate API call
+type TBlockchainNetwork = 'bitcoin' | 'ethereum' | 'polygon' | 'arbitrum' | 'optimism' | 'hyperledger' | 'private';
-  return new Promise((resolve) => {
-    setTimeout(() => resolve(createPortableContract()), 1000);
-  });
-}
-
-async function initializeAsyncContract() {
-  try {
-    const contractData = await fetchContractData();
-    console.log('Loaded contract:', contractData);
-  } catch (error) {
-    console.error('Error fetching contract data:', error);
-  }
-}
-
-initializeAsyncContract();
 ```
 
-This approach is vital when integrating with remote contract stores or dynamically fetching contract components.
+### 📝 Contract Content
 
-#### Dynamic Role Assignment
+Paragraphs support rich features:
-
-Business environments often require flexibility in role assignments, which can be handled dynamically within the contract configurations:
 
 ```typescript
-function addDynamicRoleToContract(contract: IPortableContract, roleName: string, contactInfo: tsclass.business.IContact) {
+import type { IParagraph, IVariable, ICondition } from '@signature.digital/tools';
-  const role: IRole = {
+
-    id: `role-${Math.random().toString(36).substr(2, 9)}`, // Random ID generator
+// Section types
-    name: roleName,
+type TSectionType = 'preamble' | 'definitions' | 'clause' | 'subclause' | 'schedule' | 'exhibit' | 'annex' | 'amendment' | 'signature_block' | 'witness_block' | 'acknowledgment' | 'recital';
-    description: `Dynamic role added for ${roleName}`
+
+// Variables with validation and formatting
+interface IVariable {
+  variableId: string;
+  name: string;
+  type: TVariableType; // 'text' | 'number' | 'currency' | 'date' | 'party_name' | 'calculated'...
+  value?: unknown;
+  required: boolean;
+  validation?: IVariableValidation;
+  format?: IVariableFormat;
+}
+```
+
+### 💰 Financial Terms
+
+Machine-readable financial data:
+
+```typescript
+import type { IFinancialTerms, IPaymentScheduleEntry } from '@signature.digital/tools';
+
+const financialTerms: IFinancialTerms = {
+  totalValue: { amount: 50000, currency: 'EUR', includesTax: false },
+  paymentSchedule: [...],
+  paymentMethods: ['bank_transfer', 'sepa_direct_debit'],
+  billingRates: [...],
+  penalties: [...],
+};
+```
+
+### 📅 Time Terms
+
+Duration, milestones, renewal, and termination:
+
+```typescript
+import type { ITimeTerms, IRenewalTerms, ITerminationTerms } from '@signature.digital/tools';
+
+const timeTerms: ITimeTerms = {
+  effectiveDate: Date.now(),
+  duration: { value: 12, unit: 'months' },
+  isIndefinite: false,
+  renewal: {
+    type: 'auto_renew',
+    renewalPeriod: { value: 12, unit: 'months' },
+    maxRenewals: 3,
+  },
+  termination: {
+    noticePeriod: { duration: { value: 30, unit: 'days' }, form: 'written' },
+  },
+};
+```
+
+### 🔄 Version Control
+
+Git-like versioning for contracts:
+
+```typescript
+import { createInitialVersion, incrementVersion, versionToString } from '@signature.digital/tools';
+
+const v1 = createInitialVersion('user-123');
+const v2version = incrementVersion(v1.version, 'minor');
+console.log(versionToString(v2version)); // '0.2.0'
+```
+
+### 👥 Collaboration
+
+Real-time collaboration support:
+
+```typescript
+import type { ICommentThread, ISuggestion, IUserPresence } from '@signature.digital/tools';
+import { createCommentThread, createSuggestion, createUserPresence } from '@signature.digital/tools';
+
+// Track user presence
+const presence = createUserPresence('user-123', 'Alice', '#1a73e8');
+
+// Comments with threads
+const thread = createCommentThread(contractId, versionId, {
+  type: 'text_range',
+  paragraphId: 'para-1',
+  textRange: { start: 0, end: 50, quotedText: 'Sample text' },
+}, 'user-123');
+
+// Track-changes style suggestions
+const suggestion = createSuggestion(
+  contractId, versionId, 'para-1',
+  'replace', 'old text', 'new text',
+  'user-456', 'Bob'
+);
+```
+
+### 📊 Audit Logging
+
+Tamper-evident, hash-chained audit logs:
+
+```typescript
+import type { IAuditLog, IContractAction, TActionCategory } from '@signature.digital/tools';
+
+// Action categories
+type TActionCategory =
+  | 'create' | 'view' | 'edit' | 'status_change'
+  | 'share' | 'permission_change' | 'comment'
+  | 'signature_request' | 'signature_given' | 'signature_declined'
+  | 'export' | 'print' | 'download'
+  | 'archive' | 'restore' | 'delete';
+```
+
+### 📑 PDF Generation
+
+Comprehensive PDF configuration:
+
+```typescript
+import { createDefaultPdfConfig, type IPdfGenerationConfig } from '@signature.digital/tools';
+
+const pdfConfig = createDefaultPdfConfig('Employment Contract');
+
+// Customize branding
+pdfConfig.branding.primaryColor = '#1a73e8';
+pdfConfig.branding.logo = {
+  url: 'https://example.com/logo.png',
+  position: 'left',
+  maxWidth: 150,
+  maxHeight: 50,
 };
 
-  contract.availableRoles.push(role);
+// Security settings
-  contract.involvedParties.push({ role: role.name, contact: contactInfo });
+pdfConfig.security = {
-  console.log(`Added role: ${roleName}`);
+  encryption: { enabled: true, algorithm: 'AES-256' },
-}
+  permissions: {
-
+    printing: 'high_resolution',
-addDynamicRoleToContract(contract, 'Compliance Officer', {
+    copying: false,
-  email: 'compliance@business.com',
+    modifying: false,
-  address: 'Office 42, Compliance Street'
+  },
-});
+};
-console.log(contract);
 ```
 
-Dynamic role assignments are essential when handling expansive contracts with changing stakeholder roles.
+## Demo Data
 
-#### Comprehensive Testing
+Test your implementation with realistic demo contracts:
-
-You should construct extensive tests for contract components by leveraging TypeScript's compatibility with common testing frameworks. Although the test cases here are isolated, they serve as foundational templates:
 
 ```typescript
-import { expect } from '@push.rocks/tapbundle';
+import { demoContract } from '@signature.digital/tools/demodata';
 
-tap.test('Contract Initial Structure', async () => {
+console.log(demoContract.title); // 'Minijob Employment Contract'
-  const contractBase = createPortableContract();
+console.log(demoContract.metadata.governingLaw.country); // 'DE'
-  expect(contractBase.title).toBe('Digital Service Agreement');
+console.log(demoContract.paragraphs.length); // 8 fully structured paragraphs
-  expect(contractBase.paragraphs.length).toBeGreaterThan(0);
-});
-
-tap.test('Role Addition', async () => {
-  const testContract = createPortableContract();
-  const initialRoleCount = testContract.availableRoles.length;
-
-  const newRole: IRole = {
-    id: 'role-003',
-    name: 'Tester',
-    description: 'Ensures quality and compliance of the contract.'
-  };
-
-  testContract.availableRoles.push(newRole);
-  expect(testContract.availableRoles.length).toBe(initialRoleCount + 1);
-});
-
-tap.start();
 ```
 
-These examples demonstrate basic test cases to verify the functionality and resiliency of your contract management system.
+The demo contract showcases:
+- Multi-language support (DE/EN)
+- Variable placeholders with validation
+- Legal references (BGB, SGB IV, MiLoG)
+- Financial terms with payment schedules
+- Company and person contacts with full details
+- Proper role and party structure
 
-By utilizing the `@signature.digital/tools` package, developers can construct robust, dynamic, and efficient digital contract management systems tailored to a wide array of business scenarios. The examples provided above only scratch the surface of the package's versatility and extendability, empowering developers to innovate and automate contract handling processes in TypeScript.
+## Factory Functions
+
+The library provides factory functions for creating properly initialized objects:
+
+```typescript
+// Contract creation
+createEmptyContract(title, category, contractType, createdBy, language?)
+createDefaultMetadata(category, contractType, language?)
+createDefaultGoverningLaw()
+
+// Roles and parties
+createRole(id, name, description, options?)
+createInvolvedParty(roleId, contact, signingOrder?)
+
+// Content
+createParagraph(title, content, sectionType?, order?)
+createVariable(variableId, name, type, required?)
+
+// Terms
+createEmptyFinancialTerms()
+createEmptyTimeTerms()
+createEmptyObligationTerms()
+
+// Versioning
+createInitialVersion(userId, userDisplayName?)
+createEmptyVersionHistory(contractId, initialVersion)
+incrementVersion(current, incrementType)
+versionToString(version)
+parseVersionString(versionString)
+
+// Collaboration
+createCommentThread(contractId, versionId, anchor, userId)
+createComment(threadId, authorId, authorDisplayName, content)
+createSuggestion(...)
+createCollaborator(userId, contact, permission, invitedBy)
+createUserPresence(userId, displayName, color)
+
+// Lifecycle
+createInitialLifecycle(contractId)
+createEmptyAuditLog(contractId)
+createStatusTransition(fromStatus, toStatus, triggeredBy, reason?)
+createLegalHold(name, description, contractIds, createdBy, reason)
+
+// Attachments
+createContractAttachment(contractId, versionId, type, category, title, addedBy)
+createPriorContractReference(relationshipType, contractId?, externalReference?)
+createDocumentBundle(name, mainContractId, purpose, createdBy)
+createAttachmentFile(filename, mimeType, size, storageProvider, storageKey, checksum)
+
+// Identity verification
+createIdentityVerificationRequest(methods, requiredConfidence, expiresInSeconds?)
+createPendingVerificationResult(requestId)
+
+// Legal compliance
+createEmptyLegalComplianceProof()
+createPendingTsaTimestamp(authorityUrl)
+createPendingBlockchainTimestamp(network, dataHash)
+
+// PDF
+createDefaultPdfConfig(title)
+createDefaultBranding()
+createDefaultLayout()
+createDefaultContentOptions()
+createDefaultPageNumbering()
+
+// Signatures
+createEmptySignatureMetadata()
+createDefaultSignatureFieldRequirements()
+```
+
+## TypeScript Integration
+
+All interfaces follow strict naming conventions:
+- **Interfaces**: `I` prefix (e.g., `IPortableContract`)
+- **Types**: `T` prefix (e.g., `TContractStatus`)
+
+```typescript
+import type {
+  // Core interfaces
+  IPortableContract,
+  IRole,
+  IInvolvedParty,
+  IParagraph,
+
+  // Signature system
+  ISignature,
+  ISignatureField,
+  TSignatureType,
+  TSignatureLegalLevel,
+
+  // Identity
+  IIdentityVerificationResult,
+  TIdentityVerificationMethod,
+
+  // Legal
+  ILegalComplianceProof,
+  ITsaTimestamp,
+  IBlockchainTimestamp,
+
+  // Terms
+  IFinancialTerms,
+  ITimeTerms,
+  IObligationTerms,
+
+  // And 200+ more types...
+} from '@signature.digital/tools';
+```
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

test/test.ts

@@ -1,8 +1,8 @@
-import { expect, expectAsync, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
 import * as portablecontract from '../ts/index.js'
 
 tap.test('first test', async () => {
   console.log(portablecontract)
 })
 
-tap.start()
+export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@signature.digital/tools',
-  version: '1.0.11',
+  version: '1.3.0',
   description: 'A TypeScript package providing utilities for managing digital contracts with modular interfaces and business context integration.'
 }

ts/portablecontract.plugins.ts

@@ -1,3 +1,7 @@
+// project scope
+import * as interfaces from '@signature.digital/interfaces';
+
+// @tsclass scope
 import * as tsclass from '@tsclass/tsclass';
 
 export {

ts/readme.md

@@ -0,0 +1,105 @@
+# @signature.digital/tools
+
+The main package for the signature.digital contract management system. 🚀
+
+This is the **recommended entry point** – it re-exports all interfaces from `@signature.digital/interfaces` for convenient access.
+
+## Install
+
+```bash
+pnpm add @signature.digital/tools
+```
+
+## Usage
+
+```typescript
+import {
+  // Contract creation
+  createEmptyContract,
+  createRole,
+  createInvolvedParty,
+  createParagraph,
+
+  // Types
+  type IPortableContract,
+  type IRole,
+  type IInvolvedParty,
+  type IParagraph,
+  type TContractStatus,
+
+  // All other interfaces and types
+} from '@signature.digital/tools';
+```
+
+## Why This Package?
+
+This is the **umbrella package** that provides a single import for:
+
+- All **interfaces** from `@signature.digital/interfaces`
+- All **factory functions** for creating contract objects
+- All **type aliases** for contract classification
+
+If you only need the types/interfaces without runtime code, you can use `@signature.digital/interfaces` directly.
+
+## Quick Start
+
+```typescript
+import {
+  createEmptyContract,
+  createRole,
+  createParagraph,
+} from '@signature.digital/tools';
+
+// Create a new contract
+const contract = createEmptyContract(
+  'Service Agreement',
+  'service',
+  'service_professional',
+  'user-123'
+);
+
+// Add roles
+contract.availableRoles.push(
+  createRole('provider', 'Service Provider', 'The party providing services'),
+  createRole('client', 'Client', 'The party receiving services')
+);
+
+// Add content
+contract.paragraphs.push(
+  createParagraph('Scope of Services', 'Provider shall deliver...', 'clause', 1),
+  createParagraph('Payment Terms', 'Client shall pay...', 'clause', 2)
+);
+```
+
+## Package Ecosystem
+
+| Package | Purpose |
+|---------|---------|
+| `@signature.digital/tools` | Main entry point (this package) |
+| `@signature.digital/interfaces` | Core TypeScript interfaces |
+| `@signature.digital/demodata` | Demo contracts for testing |
+
+## Dependencies
+
+- `@signature.digital/interfaces` – Core interface definitions
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../LICENSE) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts/tspublish.json

@@ -0,0 +1,8 @@
+{
+  "name": "@signature.digital/tools",
+  "order": 2,
+  "registries": ["useBase"],
+  "dependencies": [
+    "@signature.digital/interfaces"
+  ]
+}

ts_demodata/democontract.ts

@@ -0,0 +1,612 @@
+/**
+ * @file democontract.ts
+ * @description Demo contract showcasing the comprehensive contract interface
+ * A Minijob Employment Contract under German law
+ */
+
+import * as plugins from './plugins.js';
+
+/**
+ * Demo Minijob Employment Contract
+ * Demonstrates all major features of the IPortableContract interface
+ */
+export const demoContract: plugins.interfaces.IPortableContract = {
+  // ============================================================================
+  // CORE IDENTITY
+  // ============================================================================
+  id: '550e8400-e29b-41d4-a716-446655440000',
+  title: 'Minijob Employment Contract',
+  context: 'Employment agreement for a Minijob (geringfügige Beschäftigung) position under German law, subject to § 8 SGB IV regulations.',
+
+  // ============================================================================
+  // METADATA
+  // ============================================================================
+  metadata: {
+    contractNumber: 'EMP-2024-001',
+    category: 'employment',
+    contractType: 'employment_minijob',
+    language: 'de',
+    additionalLanguages: ['en'],
+    bindingLanguage: 'de',
+    governingLaw: {
+      country: 'DE',
+      applicableLaws: ['BGB', 'TzBfG', 'MiLoG', 'ArbZG', 'SGB IV § 8'],
+      disputeJurisdiction: 'Arbeitsgericht Bremen',
+      disputeResolution: 'litigation',
+    },
+    tags: ['minijob', 'part-time', 'german-law'],
+    relatedContractIds: [],
+    confidentialityLevel: 'confidential',
+    customFields: {
+      department: 'Operations',
+      costCenter: 'CC-100',
+    },
+  },
+
+  // ============================================================================
+  // ROLES
+  // ============================================================================
+  availableRoles: [
+    {
+      id: 'employer',
+      name: 'Arbeitgeber',
+      description: 'The party offering the Minijob position.',
+      category: 'party',
+      signatureRequired: true,
+      defaultSigningOrder: 1,
+      legalCapacity: 'representative',
+      notifyOnChanges: true,
+      notifyOnComments: true,
+      displayColor: '#1a73e8',
+      minParties: 1,
+      maxParties: 1,
+    },
+    {
+      id: 'employee',
+      name: 'Arbeitnehmer',
+      description: 'The party accepting the Minijob position.',
+      category: 'party',
+      signatureRequired: true,
+      defaultSigningOrder: 2,
+      legalCapacity: 'individual',
+      notifyOnChanges: true,
+      notifyOnComments: true,
+      displayColor: '#34a853',
+      minParties: 1,
+      maxParties: 1,
+    },
+  ],
+
+  // ============================================================================
+  // INVOLVED PARTIES
+  // ============================================================================
+  involvedParties: [
+    {
+      partyId: 'party-employer-001',
+      roleId: 'employer',
+      contact: {
+        type: 'company',
+        name: 'Demo GmbH',
+        description: 'A demonstration company for contract examples',
+        address: {
+          streetName: 'Musterstraße',
+          houseNumber: '123',
+          postalCode: '28195',
+          city: 'Bremen',
+          country: 'Germany',
+        },
+        status: 'active',
+        registrationDetails: {
+          vatId: 'DE123456789',
+          registrationId: 'HRB 12345',
+          registrationName: 'Handelsregister Bremen',
+        },
+      },
+      partyRole: 'signer',
+      signingOrder: 1,
+      signingDependency: 'none',
+      dependsOnParties: [],
+      signature: {
+        status: 'pending',
+      },
+      actingAsProxy: true,
+      legalProxy: {
+        type: 'company_representative',
+        representedEntity: {
+          type: 'company',
+          name: 'Demo GmbH',
+          description: 'A demonstration company',
+          address: {
+            streetName: 'Musterstraße',
+            houseNumber: '123',
+            postalCode: '28195',
+            city: 'Bremen',
+            country: 'Germany',
+          },
+          status: 'active',
+          registrationDetails: {
+            vatId: 'DE123456789',
+            registrationId: 'HRB 12345',
+            registrationName: 'Handelsregister Bremen',
+          },
+        },
+        position: 'Geschäftsführer',
+        authorityScope: 'Full authority to enter into employment contracts',
+      },
+      deliveryEmail: 'hr@demo-gmbh.example',
+      preferredLanguage: 'de',
+      remindersSent: 0,
+      totalViews: 0,
+      metadata: {},
+    },
+    {
+      partyId: 'party-employee-001',
+      roleId: 'employee',
+      contact: {
+        type: 'person',
+        name: 'Max',
+        surname: 'Mustermann',
+        salutation: 'Mr',
+        sex: 'male',
+        description: 'Employee',
+        address: {
+          streetName: 'Beispielweg',
+          houseNumber: '42',
+          postalCode: '28199',
+          city: 'Bremen',
+          country: 'Germany',
+        },
+        email: 'max.mustermann@example.com',
+        phone: '+49 421 1234567',
+      },
+      partyRole: 'signer',
+      signingOrder: 2,
+      signingDependency: 'sequential',
+      dependsOnParties: ['party-employer-001'],
+      signature: {
+        status: 'pending',
+      },
+      actingAsProxy: false,
+      deliveryEmail: 'max.mustermann@example.com',
+      preferredLanguage: 'de',
+      remindersSent: 0,
+      totalViews: 0,
+      metadata: {},
+    },
+  ],
+
+  // ============================================================================
+  // PARAGRAPHS
+  // ============================================================================
+  paragraphs: [
+    {
+      uniqueId: 'para-preamble',
+      parentId: null,
+      title: 'Vertragsparteien',
+      content: 'Zwischen\n\n**{{employer_name}}**\n{{employer_address}}\nvertreten durch {{employer_representative}}\n\n– nachfolgend „Arbeitgeber" genannt –\n\nund\n\n**{{employee_name}}**\n{{employee_address}}\n\n– nachfolgend „Arbeitnehmer" genannt –\n\nwird folgender Arbeitsvertrag für eine geringfügig entlohnte Beschäftigung (Minijob) geschlossen:',
+      sectionType: 'preamble',
+      numbering: undefined,
+      order: 0,
+      depth: 0,
+      required: true,
+      isEditable: false,
+      variables: [
+        { variableId: 'employer_name', name: 'Employer Name', type: 'party_name', required: true, source: { type: 'party_field', path: 'involvedParties[0].contact.name' } },
+        { variableId: 'employer_address', name: 'Employer Address', type: 'party_address', required: true, source: { type: 'party_field', path: 'involvedParties[0].contact.address' } },
+        { variableId: 'employer_representative', name: 'Employer Representative', type: 'text', required: true },
+        { variableId: 'employee_name', name: 'Employee Name', type: 'party_name', required: true, source: { type: 'party_field', path: 'involvedParties[1].contact.name' } },
+        { variableId: 'employee_address', name: 'Employee Address', type: 'party_address', required: true, source: { type: 'party_field', path: 'involvedParties[1].contact.address' } },
+      ],
+      conditions: [],
+      legalReferences: [],
+      translations: {
+        en: {
+          title: 'Contracting Parties',
+          content: 'Between\n\n**{{employer_name}}**\n{{employer_address}}\nrepresented by {{employer_representative}}\n\n– hereinafter referred to as "Employer" –\n\nand\n\n**{{employee_name}}**\n{{employee_address}}\n\n– hereinafter referred to as "Employee" –\n\nthe following employment contract for marginal employment (Minijob) is concluded:',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: [],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-1',
+      parentId: null,
+      title: '§ 1 Beginn und Dauer des Arbeitsverhältnisses',
+      content: '(1) Das Arbeitsverhältnis beginnt am {{start_date}}.\n\n(2) Das Arbeitsverhältnis wird auf unbestimmte Zeit geschlossen.\n\n(3) Die ersten {{probation_months}} Monate gelten als Probezeit, während der das Arbeitsverhältnis von beiden Seiten mit einer Frist von zwei Wochen gekündigt werden kann.',
+      sectionType: 'clause',
+      numbering: '1',
+      order: 1,
+      depth: 0,
+      required: true,
+      isEditable: true,
+      variables: [
+        { variableId: 'start_date', name: 'Start Date', type: 'date', required: true, format: { dateFormat: 'DD.MM.YYYY' } },
+        { variableId: 'probation_months', name: 'Probation Period (Months)', type: 'number', required: true, defaultValue: 6, validation: { min: 0, max: 6 } },
+      ],
+      conditions: [],
+      legalReferences: [
+        { type: 'statute', citation: '§ 622 BGB', jurisdiction: 'DE' },
+      ],
+      translations: {
+        en: {
+          title: '§ 1 Commencement and Duration of Employment',
+          content: '(1) The employment relationship begins on {{start_date}}.\n\n(2) The employment relationship is concluded for an indefinite period.\n\n(3) The first {{probation_months}} months are considered a probationary period, during which either party may terminate the employment with two weeks\' notice.',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['duration', 'probation'],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-2',
+      parentId: null,
+      title: '§ 2 Tätigkeit und Arbeitsort',
+      content: '(1) Der Arbeitnehmer wird als {{job_title}} eingestellt.\n\n(2) Der Arbeitsort ist {{work_location}}.\n\n(3) Der Arbeitgeber ist berechtigt, dem Arbeitnehmer im Rahmen des Direktionsrechts auch andere zumutbare Tätigkeiten zuzuweisen.',
+      sectionType: 'clause',
+      numbering: '2',
+      order: 2,
+      depth: 0,
+      required: true,
+      isEditable: true,
+      variables: [
+        { variableId: 'job_title', name: 'Job Title', type: 'text', required: true },
+        { variableId: 'work_location', name: 'Work Location', type: 'text', required: true },
+      ],
+      conditions: [],
+      legalReferences: [],
+      translations: {
+        en: {
+          title: '§ 2 Duties and Place of Work',
+          content: '(1) The employee is employed as {{job_title}}.\n\n(2) The place of work is {{work_location}}.\n\n(3) The employer is entitled to assign other reasonable duties to the employee within the scope of the right of direction.',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['duties', 'location'],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-3',
+      parentId: null,
+      title: '§ 3 Arbeitszeit',
+      content: '(1) Die regelmäßige wöchentliche Arbeitszeit beträgt {{weekly_hours}} Stunden.\n\n(2) Die Verteilung der Arbeitszeit wird vom Arbeitgeber nach billigem Ermessen festgelegt.\n\n(3) Der Arbeitnehmer verpflichtet sich, auf Anordnung des Arbeitgebers Mehrarbeit zu leisten, soweit dies gesetzlich zulässig ist.',
+      sectionType: 'clause',
+      numbering: '3',
+      order: 3,
+      depth: 0,
+      required: true,
+      isEditable: true,
+      variables: [
+        { variableId: 'weekly_hours', name: 'Weekly Hours', type: 'number', required: true, defaultValue: 10, validation: { min: 1, max: 20 } },
+      ],
+      conditions: [],
+      legalReferences: [
+        { type: 'statute', citation: 'ArbZG', jurisdiction: 'DE' },
+      ],
+      translations: {
+        en: {
+          title: '§ 3 Working Hours',
+          content: '(1) The regular weekly working time is {{weekly_hours}} hours.\n\n(2) The distribution of working time is determined by the employer at their reasonable discretion.\n\n(3) The employee undertakes to work overtime upon instruction by the employer, insofar as this is legally permissible.',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['working-hours'],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-4',
+      parentId: null,
+      title: '§ 4 Vergütung',
+      content: '(1) Der Arbeitnehmer erhält eine monatliche Bruttovergütung von {{monthly_salary}} EUR.\n\n(2) Die Vergütung wird jeweils zum Monatsende auf das vom Arbeitnehmer angegebene Konto überwiesen.\n\n(3) Die Vergütung bleibt im Rahmen der Minijob-Verdienstgrenze (§ 8 SGB IV).',
+      sectionType: 'clause',
+      numbering: '4',
+      order: 4,
+      depth: 0,
+      required: true,
+      isEditable: true,
+      variables: [
+        { variableId: 'monthly_salary', name: 'Monthly Salary (EUR)', type: 'currency', required: true, defaultValue: 520, validation: { max: 538 } },
+      ],
+      conditions: [],
+      legalReferences: [
+        { type: 'statute', citation: '§ 8 SGB IV', jurisdiction: 'DE' },
+        { type: 'statute', citation: 'MiLoG', jurisdiction: 'DE' },
+      ],
+      translations: {
+        en: {
+          title: '§ 4 Compensation',
+          content: '(1) The employee receives a gross monthly compensation of {{monthly_salary}} EUR.\n\n(2) The compensation is transferred to the account specified by the employee at the end of each month.\n\n(3) The compensation remains within the Minijob earnings limit (§ 8 SGB IV).',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['compensation', 'salary'],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-5',
+      parentId: null,
+      title: '§ 5 Urlaub',
+      content: '(1) Der Arbeitnehmer hat Anspruch auf bezahlten Erholungsurlaub entsprechend der gesetzlichen Bestimmungen.\n\n(2) Bei einer {{work_days_per_week}}-Tage-Woche beträgt der Jahresurlaubsanspruch {{vacation_days}} Arbeitstage.',
+      sectionType: 'clause',
+      numbering: '5',
+      order: 5,
+      depth: 0,
+      required: true,
+      isEditable: true,
+      variables: [
+        { variableId: 'work_days_per_week', name: 'Work Days per Week', type: 'number', required: true, defaultValue: 2 },
+        { variableId: 'vacation_days', name: 'Vacation Days per Year', type: 'number', required: true, source: { type: 'calculated', formula: 'Math.ceil(work_days_per_week * 4)' } },
+      ],
+      conditions: [],
+      legalReferences: [
+        { type: 'statute', citation: 'BUrlG', jurisdiction: 'DE' },
+      ],
+      translations: {
+        en: {
+          title: '§ 5 Vacation',
+          content: '(1) The employee is entitled to paid vacation in accordance with statutory provisions.\n\n(2) For a {{work_days_per_week}}-day work week, the annual vacation entitlement is {{vacation_days}} working days.',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['vacation', 'leave'],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-6',
+      parentId: null,
+      title: '§ 6 Kündigung',
+      content: '(1) Nach Ablauf der Probezeit kann das Arbeitsverhältnis mit einer Frist von vier Wochen zum Fünfzehnten oder zum Ende eines Kalendermonats gekündigt werden.\n\n(2) Die Kündigung bedarf der Schriftform.',
+      sectionType: 'clause',
+      numbering: '6',
+      order: 6,
+      depth: 0,
+      required: true,
+      isEditable: true,
+      variables: [],
+      conditions: [],
+      legalReferences: [
+        { type: 'statute', citation: '§ 622 BGB', jurisdiction: 'DE' },
+      ],
+      translations: {
+        en: {
+          title: '§ 6 Termination',
+          content: '(1) After the probationary period, the employment relationship may be terminated with four weeks\' notice to the 15th or the end of a calendar month.\n\n(2) Termination must be in writing.',
+        },
+      },
+      crossReferences: ['para-1'],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['termination', 'notice'],
+      aiGenerated: false,
+    },
+    {
+      uniqueId: 'para-signature',
+      parentId: null,
+      title: 'Unterschriften',
+      content: 'Mit ihrer Unterschrift bestätigen die Parteien, dass sie diesen Vertrag gelesen und verstanden haben und sich an dessen Bedingungen gebunden fühlen.\n\n{{signature_location}}, den {{signature_date}}',
+      sectionType: 'signature_block',
+      order: 7,
+      depth: 0,
+      required: true,
+      isEditable: false,
+      variables: [
+        { variableId: 'signature_location', name: 'Signature Location', type: 'text', required: true, defaultValue: 'Bremen' },
+        { variableId: 'signature_date', name: 'Signature Date', type: 'date', required: true, source: { type: 'manual' } },
+      ],
+      conditions: [],
+      legalReferences: [],
+      translations: {
+        en: {
+          title: 'Signatures',
+          content: 'By signing, the parties confirm that they have read and understood this contract and agree to be bound by its terms.\n\n{{signature_location}}, {{signature_date}}',
+        },
+      },
+      crossReferences: [],
+      attachmentReferences: [],
+      jurisdictions: ['DE'],
+      tags: ['signatures'],
+      aiGenerated: false,
+    },
+  ],
+
+  // ============================================================================
+  // VARIABLES (Global)
+  // ============================================================================
+  variables: [],
+
+  // ============================================================================
+  // SIGNATURE FIELDS
+  // ============================================================================
+  signatureFields: [],
+
+  // ============================================================================
+  // FINANCIAL TERMS
+  // ============================================================================
+  financialTerms: {
+    totalValue: {
+      amount: 520,
+      currency: 'EUR',
+      includesTax: false,
+    },
+    paymentSchedule: [
+      {
+        paymentId: 'salary-monthly',
+        description: 'Monthly Salary',
+        amount: { amount: 520, currency: 'EUR', includesTax: false },
+        dueDate: 0,
+        frequency: 'monthly',
+        isFinalPayment: false,
+        status: 'pending',
+      },
+    ],
+    paymentMethods: ['bank_transfer'],
+    paymentDueDays: 0,
+    depositRefundable: false,
+    billingRates: [],
+    interestRates: {},
+    penalties: [],
+  },
+
+  // ============================================================================
+  // TIME TERMS
+  // ============================================================================
+  timeTerms: {
+    isIndefinite: true,
+    commencementConditions: ['Signed by both parties'],
+    milestones: [],
+    deadlines: [],
+    noticePeriods: {
+      termination: {
+        duration: { value: 4, unit: 'weeks' },
+        effectivePoint: 'end_of_month',
+        form: 'written',
+      },
+    },
+    keyDates: [],
+  },
+
+  // ============================================================================
+  // OBLIGATION TERMS
+  // ============================================================================
+  obligationTerms: {
+    deliverables: [],
+    serviceLevels: [],
+    quantities: [],
+    obligations: [
+      {
+        obligationId: 'work-performance',
+        type: 'performance',
+        description: 'Employee shall perform duties as assigned by employer',
+        obligorPartyId: 'party-employee-001',
+        beneficiaryPartyId: 'party-employer-001',
+        recurring: true,
+        priority: 'high',
+        status: 'pending',
+      },
+      {
+        obligationId: 'salary-payment',
+        type: 'payment',
+        description: 'Employer shall pay monthly salary',
+        obligorPartyId: 'party-employer-001',
+        beneficiaryPartyId: 'party-employee-001',
+        recurring: true,
+        frequency: 'monthly',
+        priority: 'high',
+        status: 'pending',
+      },
+    ],
+    warranties: [],
+    representations: [],
+    insuranceRequirements: [],
+    complianceRequirements: ['Minijob regulations (§ 8 SGB IV)', 'Minimum wage (MiLoG)'],
+  },
+
+  // ============================================================================
+  // DOCUMENTS
+  // ============================================================================
+  priorContracts: [],
+  attachments: [],
+
+  // ============================================================================
+  // VERSIONING
+  // ============================================================================
+  versionHistory: {
+    contractId: '550e8400-e29b-41d4-a716-446655440000',
+    currentVersionId: 'version-001',
+    currentVersion: { major: 1, minor: 0, patch: 0 },
+    versions: [
+      {
+        id: 'version-001',
+        version: { major: 1, minor: 0, patch: 0 },
+        versionString: '1.0.0',
+        type: 'draft',
+        createdAt: Date.now(),
+        createdBy: 'system',
+        createdByDisplayName: 'System',
+        changes: [],
+        contentHash: '',
+        tags: ['initial'],
+        isAmendment: false,
+      },
+    ],
+    branches: [
+      {
+        id: 'branch-main',
+        name: 'main',
+        createdAt: Date.now(),
+        createdBy: 'system',
+        baseVersionId: 'version-001',
+        headVersionId: 'version-001',
+        status: 'active',
+      },
+    ],
+    mainBranchId: 'branch-main',
+    publishedVersions: [],
+    amendmentVersions: [],
+  },
+
+  // ============================================================================
+  // COLLABORATION
+  // ============================================================================
+  collaborators: [],
+  commentThreads: [],
+  suggestions: [],
+
+  // ============================================================================
+  // LIFECYCLE
+  // ============================================================================
+  lifecycle: {
+    contractId: '550e8400-e29b-41d4-a716-446655440000',
+    currentStatus: 'draft',
+    statusHistory: [],
+    createdAt: Date.now(),
+  },
+
+  // ============================================================================
+  // AUDIT LOG
+  // ============================================================================
+  auditLog: {
+    contractId: '550e8400-e29b-41d4-a716-446655440000',
+    actions: [],
+    genesisHash: 'genesis-hash-placeholder',
+    currentHash: 'genesis-hash-placeholder',
+    chainLength: 0,
+    statistics: {
+      totalActions: 0,
+      actionsByCategory: {} as Record<string, number>,
+      uniqueUsers: [],
+      dateRange: { earliest: 0, latest: 0 },
+    },
+  },
+
+  // ============================================================================
+  // TIMESTAMPS
+  // ============================================================================
+  createdAt: Date.now(),
+  createdBy: 'system',
+  updatedAt: Date.now(),
+
+  // ============================================================================
+  // ORGANIZATION
+  // ============================================================================
+  visibility: 'private',
+
+  // ============================================================================
+  // INTEGRATIONS
+  // ============================================================================
+  integrations: {
+    customIntegrations: {},
+  },
+};

ts_demodata/index.ts

@@ -0,0 +1 @@
+export * from './democontract.js';

ts_demodata/plugins.ts

@@ -0,0 +1,5 @@
+import * as interfaces from '@signature.digital/interfaces';
+
+export {
+  interfaces,
+}

ts_demodata/readme.md

@@ -0,0 +1,179 @@
+# @signature.digital/demodata
+
+Demo contracts and test data for the signature.digital contract management system. 🧪
+
+Use these realistic sample contracts for testing, development, and demonstrating the full capabilities of the `@signature.digital/interfaces` types.
+
+## Install
+
+```bash
+pnpm add @signature.digital/demodata
+```
+
+## Usage
+
+```typescript
+import { demoContract } from '@signature.digital/demodata';
+
+console.log(demoContract.title); // 'Minijob Employment Contract'
+console.log(demoContract.metadata.language); // 'de'
+console.log(demoContract.paragraphs.length); // 8
+```
+
+## Available Demo Data
+
+### demoContract
+
+A **German Minijob Employment Contract** (geringfügige Beschäftigung) that demonstrates the full power of the `IPortableContract` interface:
+
+```typescript
+import { demoContract } from '@signature.digital/demodata';
+```
+
+**Contract Details:**
+- **Type**: Employment → Minijob
+- **Language**: German (with English translations)
+- **Governing Law**: Germany (BGB, TzBfG, MiLoG, ArbZG, SGB IV)
+- **Jurisdiction**: Arbeitsgericht Bremen
+
+**Features Demonstrated:**
+
+| Feature | Details |
+|---------|---------|
+| 🏢 **Parties** | Company employer + Individual employee |
+| 📜 **Roles** | Arbeitgeber, Arbeitnehmer with full configuration |
+| 📝 **Paragraphs** | 8 sections with proper German legal structure |
+| 🌍 **Multi-language** | DE/EN translations for all content |
+| 🔤 **Variables** | Placeholders with validation rules |
+| ⚖️ **Legal refs** | BGB, SGB IV, MiLoG, ArbZG citations |
+| 💰 **Financial** | Monthly salary payment schedule |
+| ⏱️ **Time terms** | Indefinite duration with notice periods |
+| 📋 **Obligations** | Work performance, salary payment |
+| 🔖 **Metadata** | Contract number, tags, custom fields |
+
+## Contract Structure
+
+The demo contract includes these sections:
+
+1. **Vertragsparteien** (Contracting Parties) – Preamble with party details
+2. **§ 1 Beginn und Dauer** – Commencement, duration, probation
+3. **§ 2 Tätigkeit und Arbeitsort** – Duties and place of work
+4. **§ 3 Arbeitszeit** – Working hours configuration
+5. **§ 4 Vergütung** – Compensation within Minijob limits
+6. **§ 5 Urlaub** – Vacation entitlement (pro-rata)
+7. **§ 6 Kündigung** – Termination notice periods
+8. **Unterschriften** – Signature block
+
+## Variables Example
+
+The demo contract showcases various variable types:
+
+```typescript
+// Party-linked variables (auto-populated)
+{ variableId: 'employer_name', type: 'party_name', source: { type: 'party_field', path: 'involvedParties[0].contact.name' } }
+
+// Date variables with formatting
+{ variableId: 'start_date', type: 'date', format: { dateFormat: 'DD.MM.YYYY' } }
+
+// Validated number variables
+{ variableId: 'probation_months', type: 'number', defaultValue: 6, validation: { min: 0, max: 6 } }
+
+// Calculated variables
+{ variableId: 'vacation_days', type: 'number', source: { type: 'calculated', formula: 'Math.ceil(work_days_per_week * 4)' } }
+
+// Currency with limits
+{ variableId: 'monthly_salary', type: 'currency', defaultValue: 520, validation: { max: 538 } }
+```
+
+## Party Examples
+
+The demo includes both company and individual contacts:
+
+```typescript
+// Employer (Company)
+{
+  type: 'company',
+  name: 'Demo GmbH',
+  address: { streetName: 'Musterstraße', houseNumber: '123', city: 'Bremen', country: 'Germany' },
+  registrationDetails: { vatId: 'DE123456789', registrationId: 'HRB 12345' }
+}
+
+// Employee (Person)
+{
+  type: 'person',
+  name: 'Max',
+  surname: 'Mustermann',
+  email: 'max.mustermann@example.com',
+  phone: '+49 421 1234567'
+}
+```
+
+## Use Cases
+
+### Testing Contract Rendering
+
+```typescript
+import { demoContract } from '@signature.digital/demodata';
+
+// Test paragraph rendering
+demoContract.paragraphs.forEach(para => {
+  console.log(`${para.numbering} ${para.title}`);
+  console.log(para.content);
+});
+```
+
+### Testing Variable Substitution
+
+```typescript
+import { demoContract } from '@signature.digital/demodata';
+
+function substituteVariables(content: string, variables: Record<string, unknown>): string {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key) => String(variables[key] || `{{${key}}}`));
+}
+
+const values = { employer_name: 'Acme Corp', start_date: '01.01.2025' };
+const rendered = substituteVariables(demoContract.paragraphs[0].content, values);
+```
+
+### Testing Translation Display
+
+```typescript
+import { demoContract } from '@signature.digital/demodata';
+
+function getParagraphInLanguage(para: IParagraph, lang: string): { title: string; content: string } {
+  if (lang === para.language || lang === 'de') {
+    return { title: para.title, content: para.content };
+  }
+  return para.translations[lang] || { title: para.title, content: para.content };
+}
+
+// Get English version
+const englishPara = getParagraphInLanguage(demoContract.paragraphs[1], 'en');
+console.log(englishPara.title); // '§ 1 Commencement and Duration of Employment'
+```
+
+## Dependencies
+
+- `@signature.digital/interfaces` – Contract interface definitions
+- `@tsclass/tsclass` – Business entity types
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../LICENSE) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts_demodata/tspublish.json

@@ -0,0 +1,9 @@
+{
+  "name": "@signature.digital/demodata",
+  "order": 3,
+  "registries": ["useBase"],
+  "dependencies": [
+    "@signature.digital/interfaces",
+    "@tsclass/tsclass"
+  ]
+}

ts_interfaces/attachments.ts

@@ -0,0 +1,231 @@
+/**
+ * @file attachments.ts
+ * @description Document attachment interfaces
+ * Exhibits, schedules, prior contracts, and document bundles
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TAttachmentType,
+  TAttachmentCategory,
+  TPriorContractRelationship,
+  TConfidentialityLevel,
+} from './types.js';
+
+// ============================================================================
+// ATTACHMENT FILE
+// ============================================================================
+
+/**
+ * Storage provider types
+ */
+export type TStorageProvider = 'local' | 's3' | 'azure' | 'gcs';
+
+/**
+ * File metadata for attachment
+ */
+export interface IAttachmentFile {
+  id: string;
+  filename: string;
+  mimeType: string;
+  size: number;
+  storageProvider: TStorageProvider;
+  storageKey: string;
+  checksum: string;
+  checksumAlgorithm: 'SHA-256';
+  thumbnailUrl?: string;
+  previewUrl?: string;
+  pageCount?: number;
+  textExtraction?: string;
+}
+
+// ============================================================================
+// CONTRACT ATTACHMENT
+// ============================================================================
+
+/**
+ * Extended attachment for contracts
+ */
+export interface IContractAttachment {
+  id: string;
+  contractId: string;
+  type: TAttachmentType;
+  category: TAttachmentCategory;
+  title: string;
+  description?: string;
+  file?: IAttachmentFile;
+  inlineContent?: string;
+  referencedInParagraphs: string[];
+  displayOrder: number;
+  versionId: string;
+  attachmentVersion: number;
+  addedAt: number;
+  addedBy: string;
+  lastModifiedAt?: number;
+  lastModifiedBy?: string;
+  isConfidential: boolean;
+  confidentialityLevel: TConfidentialityLevel;
+}
+
+// ============================================================================
+// PRIOR CONTRACT REFERENCE
+// ============================================================================
+
+/**
+ * External contract reference
+ */
+export interface IExternalContractReference {
+  title: string;
+  date: number;
+  parties: string[];
+  summary?: string;
+  documentUrl?: string;
+}
+
+/**
+ * Referenced clause from prior contract
+ */
+export interface IReferencedClause {
+  clauseReference: string;
+  relevance: string;
+}
+
+/**
+ * Prior contract reference
+ */
+export interface IPriorContractReference {
+  id: string;
+  contractId?: string;
+  externalReference?: IExternalContractReference;
+  relationshipType: TPriorContractRelationship;
+  referencedClauses: IReferencedClause[];
+  notes?: string;
+}
+
+// ============================================================================
+// DOCUMENT BUNDLE
+// ============================================================================
+
+/**
+ * Export settings for document bundle
+ */
+export interface IBundleExportSettings {
+  includeAuditLog: boolean;
+  includeComments: boolean;
+  redactConfidential: boolean;
+  watermark?: string;
+}
+
+/**
+ * Document bundle purpose
+ */
+export type TBundlePurpose = 'signing_package' | 'due_diligence' | 'archive' | 'discovery' | 'custom';
+
+/**
+ * Document bundle (collection of related documents)
+ */
+export interface IDocumentBundle {
+  id: string;
+  name: string;
+  description?: string;
+  mainContractId: string;
+  attachmentIds: string[];
+  priorContractIds: string[];
+  createdAt: number;
+  createdBy: string;
+  purpose: TBundlePurpose;
+  exportSettings?: IBundleExportSettings;
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create a new contract attachment
+ */
+export function createContractAttachment(
+  contractId: string,
+  versionId: string,
+  type: TAttachmentType,
+  category: TAttachmentCategory,
+  title: string,
+  addedBy: string
+): IContractAttachment {
+  return {
+    id: crypto.randomUUID(),
+    contractId,
+    type,
+    category,
+    title,
+    referencedInParagraphs: [],
+    displayOrder: 0,
+    versionId,
+    attachmentVersion: 1,
+    addedAt: Date.now(),
+    addedBy,
+    isConfidential: false,
+    confidentialityLevel: 'internal',
+  };
+}
+
+/**
+ * Create a prior contract reference
+ */
+export function createPriorContractReference(
+  relationshipType: TPriorContractRelationship,
+  contractId?: string,
+  externalReference?: IExternalContractReference
+): IPriorContractReference {
+  return {
+    id: crypto.randomUUID(),
+    contractId,
+    externalReference,
+    relationshipType,
+    referencedClauses: [],
+  };
+}
+
+/**
+ * Create a document bundle
+ */
+export function createDocumentBundle(
+  name: string,
+  mainContractId: string,
+  purpose: TBundlePurpose,
+  createdBy: string
+): IDocumentBundle {
+  return {
+    id: crypto.randomUUID(),
+    name,
+    mainContractId,
+    attachmentIds: [],
+    priorContractIds: [],
+    createdAt: Date.now(),
+    createdBy,
+    purpose,
+  };
+}
+
+/**
+ * Create an attachment file metadata
+ */
+export function createAttachmentFile(
+  filename: string,
+  mimeType: string,
+  size: number,
+  storageProvider: TStorageProvider,
+  storageKey: string,
+  checksum: string
+): IAttachmentFile {
+  return {
+    id: crypto.randomUUID(),
+    filename,
+    mimeType,
+    size,
+    storageProvider,
+    storageKey,
+    checksum,
+    checksumAlgorithm: 'SHA-256',
+  };
+}

ts_interfaces/collaboration.ts

@@ -0,0 +1,365 @@
+/**
+ * @file collaboration.ts
+ * @description Collaboration interfaces
+ * Comments, suggestions, user presence, and collaborative editing support
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TPresenceStatus,
+  TCommentThreadStatus,
+  TSuggestionStatus,
+  TSuggestionChangeType,
+  TConflictResolutionStrategy,
+  TEditingMode,
+  TCollaborationPermission,
+} from './types.js';
+import type { IVersionChange } from './versioning.js';
+
+// ============================================================================
+// USER PRESENCE
+// ============================================================================
+
+/**
+ * User's current location in document
+ */
+export interface IUserLocation {
+  paragraphId?: string;
+  characterPosition?: number;
+  selectionRange?: {
+    start: number;
+    end: number;
+  };
+}
+
+/**
+ * Device information for presence
+ */
+export interface IDeviceInfo {
+  type: 'desktop' | 'tablet' | 'mobile';
+  browser?: string;
+}
+
+/**
+ * User presence information
+ */
+export interface IUserPresence {
+  userId: string;
+  displayName: string;
+  avatarUrl?: string;
+  color: string;
+  status: TPresenceStatus;
+  currentLocation?: IUserLocation;
+  lastActivity: number;
+  sessionStarted: number;
+  deviceInfo?: IDeviceInfo;
+}
+
+/**
+ * Real-time cursor position for collaborative editing
+ */
+export interface ICursorPosition {
+  userId: string;
+  paragraphId: string;
+  offset: number;
+  timestamp: number;
+}
+
+// ============================================================================
+// COMMENTS
+// ============================================================================
+
+/**
+ * Anchor point for a comment
+ */
+export interface ICommentAnchor {
+  type: 'paragraph' | 'text_range' | 'document' | 'party' | 'attachment';
+  paragraphId?: string;
+  textRange?: {
+    start: number;
+    end: number;
+    quotedText: string;
+  };
+  elementPath?: string;
+}
+
+/**
+ * User mention in comment
+ */
+export interface IMention {
+  userId: string;
+  displayName: string;
+  notified: boolean;
+  notifiedAt?: number;
+}
+
+/**
+ * Reaction on a comment
+ */
+export interface IReaction {
+  emoji: string;
+  userId: string;
+  timestamp: number;
+}
+
+/**
+ * Individual comment within a thread
+ */
+export interface IComment {
+  id: string;
+  threadId: string;
+  authorId: string;
+  authorDisplayName: string;
+  authorAvatarUrl?: string;
+  content: string;
+  createdAt: number;
+  editedAt?: number;
+  mentions: IMention[];
+  reactions: IReaction[];
+  parentCommentId?: string;
+  isDeleted: boolean;
+}
+
+/**
+ * Comment thread on a specific location
+ */
+export interface ICommentThread {
+  id: string;
+  contractId: string;
+  versionId: string;
+  anchor: ICommentAnchor;
+  status: TCommentThreadStatus;
+  resolvedBy?: string;
+  resolvedAt?: number;
+  comments: IComment[];
+  createdAt: number;
+  createdBy: string;
+  lastActivityAt: number;
+}
+
+// ============================================================================
+// SUGGESTIONS
+// ============================================================================
+
+/**
+ * Suggestion for proposed changes (track changes mode)
+ */
+export interface ISuggestion {
+  id: string;
+  contractId: string;
+  versionId: string;
+  targetParagraphId: string;
+  targetTextRange?: {
+    start: number;
+    end: number;
+  };
+  changeType: TSuggestionChangeType;
+  originalContent: string;
+  suggestedContent: string;
+  status: TSuggestionStatus;
+  suggestedBy: string;
+  suggestedByDisplayName: string;
+  suggestedAt: number;
+  reviewedBy?: string;
+  reviewedAt?: number;
+  rejectionReason?: string;
+  discussionThreadId?: string;
+}
+
+// ============================================================================
+// CONFLICTS
+// ============================================================================
+
+/**
+ * Conflicting change from a user
+ */
+export interface IConflictingChange {
+  userId: string;
+  userDisplayName: string;
+  content: string;
+  timestamp: number;
+}
+
+/**
+ * Conflict marker for simultaneous edits
+ */
+export interface IEditConflict {
+  id: string;
+  contractId: string;
+  paragraphId: string;
+  baseContent: string;
+  changes: IConflictingChange[];
+  status: 'unresolved' | 'resolved' | 'auto_merged';
+  resolvedContent?: string;
+  resolvedBy?: string;
+  resolvedAt?: number;
+  resolutionStrategy?: TConflictResolutionStrategy;
+}
+
+// ============================================================================
+// COLLABORATION SESSION
+// ============================================================================
+
+/**
+ * Collaborative editing session
+ */
+export interface ICollaborationSession {
+  id: string;
+  contractId: string;
+  versionId: string;
+  participants: IUserPresence[];
+  editingMode: TEditingMode;
+  activeCursors: ICursorPosition[];
+  pendingChanges: IVersionChange[];
+  startedAt: number;
+  lastActivityAt: number;
+  autoSaveInterval: number;
+}
+
+// ============================================================================
+// COLLABORATOR
+// ============================================================================
+
+/**
+ * Notification preferences for a collaborator
+ */
+export interface INotificationPreferences {
+  onComment: boolean;
+  onSuggestion: boolean;
+  onVersionPublish: boolean;
+  onSignatureRequest: boolean;
+}
+
+/**
+ * Collaborator with permission
+ */
+export interface ICollaborator {
+  userId: string;
+  contact: plugins.tsclass.business.TContact;
+  permission: TCollaborationPermission;
+  invitedBy: string;
+  invitedAt: number;
+  acceptedAt?: number;
+  expiresAt?: number;
+  notificationPreferences: INotificationPreferences;
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create a new comment thread
+ */
+export function createCommentThread(
+  contractId: string,
+  versionId: string,
+  anchor: ICommentAnchor,
+  userId: string
+): ICommentThread {
+  const now = Date.now();
+  return {
+    id: crypto.randomUUID(),
+    contractId,
+    versionId,
+    anchor,
+    status: 'open',
+    comments: [],
+    createdAt: now,
+    createdBy: userId,
+    lastActivityAt: now,
+  };
+}
+
+/**
+ * Create a new comment
+ */
+export function createComment(
+  threadId: string,
+  authorId: string,
+  authorDisplayName: string,
+  content: string
+): IComment {
+  return {
+    id: crypto.randomUUID(),
+    threadId,
+    authorId,
+    authorDisplayName,
+    content,
+    createdAt: Date.now(),
+    mentions: [],
+    reactions: [],
+    isDeleted: false,
+  };
+}
+
+/**
+ * Create a new suggestion
+ */
+export function createSuggestion(
+  contractId: string,
+  versionId: string,
+  targetParagraphId: string,
+  changeType: TSuggestionChangeType,
+  originalContent: string,
+  suggestedContent: string,
+  suggestedBy: string,
+  suggestedByDisplayName: string
+): ISuggestion {
+  return {
+    id: crypto.randomUUID(),
+    contractId,
+    versionId,
+    targetParagraphId,
+    changeType,
+    originalContent,
+    suggestedContent,
+    status: 'pending',
+    suggestedBy,
+    suggestedByDisplayName,
+    suggestedAt: Date.now(),
+  };
+}
+
+/**
+ * Create a new collaborator
+ */
+export function createCollaborator(
+  userId: string,
+  contact: plugins.tsclass.business.TContact,
+  permission: TCollaborationPermission,
+  invitedBy: string
+): ICollaborator {
+  return {
+    userId,
+    contact,
+    permission,
+    invitedBy,
+    invitedAt: Date.now(),
+    notificationPreferences: {
+      onComment: true,
+      onSuggestion: true,
+      onVersionPublish: true,
+      onSignatureRequest: true,
+    },
+  };
+}
+
+/**
+ * Create default user presence
+ */
+export function createUserPresence(
+  userId: string,
+  displayName: string,
+  color: string
+): IUserPresence {
+  const now = Date.now();
+  return {
+    userId,
+    displayName,
+    color,
+    status: 'viewing',
+    lastActivity: now,
+    sessionStarted: now,
+  };
+}

ts_interfaces/contract.ts

@@ -0,0 +1,561 @@
+/**
+ * @file contract.ts
+ * @description Enhanced portable contract interface
+ * The main contract data structure that ties all modules together
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TContractCategory,
+  TContractType,
+  TContractStatus,
+  TPartyRole,
+  TSigningDependency,
+  TLegalCapacity,
+  TSectionType,
+  TVariableType,
+  TConditionOperator,
+  TConditionCombine,
+  TLegalReferenceType,
+  TDisputeResolution,
+  TSignatureType,
+  TSignatureLegalLevel,
+  TConfidentialityLevel,
+} from './types.js';
+import type {
+  IFinancialTerms,
+  ITimeTerms,
+  IObligationTerms,
+  createEmptyFinancialTerms,
+  createEmptyTimeTerms,
+  createEmptyObligationTerms,
+} from './terms.js';
+import type { ISignature, ISignatureFieldPlacement, ISignatureFieldRequirements, ISignatureDependency } from './signature.js';
+import type { IIdentityVerificationResult } from './identity.js';
+import type { ILegalComplianceProof } from './legal.js';
+import type { IVersionHistory, IVersion } from './versioning.js';
+import type { ICollaborator, ICommentThread, ISuggestion } from './collaboration.js';
+import type { IDocumentLifecycle, IAuditLog } from './lifecycle.js';
+import type { IContractAttachment, IPriorContractReference } from './attachments.js';
+import type { IPdfGenerationConfig } from './pdf.js';
+
+// ============================================================================
+// METADATA
+// ============================================================================
+
+/**
+ * Governing law and jurisdiction
+ */
+export interface IGoverningLaw {
+  country: string;
+  state?: string;
+  applicableLaws: string[];
+  disputeJurisdiction?: string;
+  disputeResolution: TDisputeResolution;
+  arbitrationInstitution?: string;
+  arbitrationRules?: string;
+  arbitrationSeat?: string;
+  numberOfArbitrators?: number;
+  proceedingsLanguage?: string;
+}
+
+/**
+ * Contract metadata
+ */
+export interface IContractMetadata {
+  contractNumber?: string;
+  category: TContractCategory;
+  contractType: TContractType;
+  language: string;
+  additionalLanguages: string[];
+  bindingLanguage?: string;
+  governingLaw: IGoverningLaw;
+  tags: string[];
+  internalReference?: string;
+  externalReference?: string;
+  templateId?: string;
+  parentContractId?: string;
+  relatedContractIds: string[];
+  confidentialityLevel: TConfidentialityLevel;
+  customFields: Record<string, unknown>;
+}
+
+// ============================================================================
+// ROLES AND PARTIES
+// ============================================================================
+
+/**
+ * Role definition
+ */
+export interface IRole {
+  id: string;
+  name: string;
+  description: string;
+  category: 'party' | 'witness' | 'notary' | 'guarantor' | 'beneficiary';
+  signatureRequired: boolean;
+  defaultSigningOrder: number;
+  legalCapacity?: TLegalCapacity;
+  notifyOnChanges: boolean;
+  notifyOnComments: boolean;
+  displayColor?: string;
+  icon?: string;
+  minParties?: number;
+  maxParties?: number;
+}
+
+/**
+ * Legal proxy information
+ */
+export interface ILegalProxy {
+  type: 'self' | 'company_representative' | 'power_of_attorney' | 'guardian' | 'other';
+  representedEntity: plugins.tsclass.business.TContact;
+  position?: string;
+  poaDocumentId?: string;
+  authorityScope?: string;
+}
+
+/**
+ * Party signature status
+ */
+export interface IPartySignature {
+  status: 'pending' | 'viewed' | 'signed' | 'declined' | 'voided';
+  signedAt?: number;
+  signature?: ISignature;
+  declinedAt?: number;
+  declineReason?: string;
+}
+
+/**
+ * Involved party in contract
+ */
+export interface IInvolvedParty {
+  partyId: string;
+  roleId: string;
+  contact: plugins.tsclass.business.TContact;
+  partyRole: TPartyRole;
+  signingOrder: number;
+  signingDependency: TSigningDependency;
+  dependsOnParties: string[];
+  signature: IPartySignature;
+  identityVerification?: IIdentityVerificationResult;
+  legalComplianceProof?: ILegalComplianceProof;
+  actingAsProxy: boolean;
+  legalProxy?: ILegalProxy;
+  deliveryEmail?: string;
+  deliveryPhone?: string;
+  preferredLanguage?: string;
+  internalNotes?: string;
+  invitationSentAt?: number;
+  remindersSent: number;
+  lastReminderAt?: number;
+  firstViewedAt?: number;
+  lastViewedAt?: number;
+  totalViews: number;
+  metadata: Record<string, unknown>;
+}
+
+// ============================================================================
+// CONTENT STRUCTURE
+// ============================================================================
+
+/**
+ * Variable validation rules
+ */
+export interface IVariableValidation {
+  pattern?: string;
+  minLength?: number;
+  maxLength?: number;
+  min?: number;
+  max?: number;
+  options?: string[];
+}
+
+/**
+ * Variable format specification
+ */
+export interface IVariableFormat {
+  dateFormat?: string;
+  numberFormat?: string;
+  currencyFormat?: string;
+}
+
+/**
+ * Variable source configuration
+ */
+export interface IVariableSource {
+  type: 'party_field' | 'contract_field' | 'calculated' | 'external' | 'manual';
+  path?: string;
+  formula?: string;
+  externalSource?: string;
+}
+
+/**
+ * Variable/placeholder definition
+ */
+export interface IVariable {
+  variableId: string;
+  name: string;
+  type: TVariableType;
+  value?: unknown;
+  defaultValue?: unknown;
+  required: boolean;
+  source?: IVariableSource;
+  validation?: IVariableValidation;
+  format?: IVariableFormat;
+}
+
+/**
+ * Condition for conditional content
+ */
+export interface ICondition {
+  conditionId: string;
+  field: string;
+  operator: TConditionOperator;
+  value: unknown;
+  combine?: TConditionCombine;
+  nestedConditions: ICondition[];
+}
+
+/**
+ * Legal reference annotation
+ */
+export interface ILegalReference {
+  type: TLegalReferenceType;
+  citation: string;
+  url?: string;
+  jurisdiction?: string;
+  effectiveDate?: number;
+}
+
+/**
+ * Paragraph translation
+ */
+export interface IParagraphTranslation {
+  title: string;
+  content: string;
+}
+
+/**
+ * Paragraph/section in contract
+ */
+export interface IParagraph {
+  uniqueId: string;
+  parentId: string | null;
+  title: string;
+  content: string;
+  sectionType: TSectionType;
+  numbering?: string;
+  order: number;
+  depth: number;
+  required: boolean;
+  isEditable: boolean;
+  variables: IVariable[];
+  conditions: ICondition[];
+  legalReferences: ILegalReference[];
+  language?: string;
+  translations: Record<string, IParagraphTranslation>;
+  crossReferences: string[];
+  attachmentReferences: string[];
+  jurisdictions: string[];
+  tags: string[];
+  aiGenerated: boolean;
+  templateSourceId?: string;
+  lastEditedBy?: string;
+  lastEditedAt?: number;
+  lockedBy?: string;
+  lockedAt?: number;
+}
+
+// ============================================================================
+// SIGNATURE FIELDS
+// ============================================================================
+
+/**
+ * Signer assignment to signature field
+ */
+export interface ISignerAssignment {
+  id: string;
+  partyId?: string;
+  email: string;
+  phone?: string;
+  signingOrder: number;
+  invitationStatus: 'not_sent' | 'sent' | 'delivered' | 'opened' | 'bounced';
+  invitationSentAt?: number;
+  deliveredAt?: number;
+  openedAt?: number;
+  remindersSent: number;
+  lastReminderAt?: number;
+  accessTokenHash?: string;
+  tokenExpiresAt?: number;
+}
+
+/**
+ * Signature field in contract
+ */
+export interface ISignatureField {
+  id: string;
+  name: string;
+  description?: string;
+  placement: ISignatureFieldPlacement;
+  requirements: ISignatureFieldRequirements;
+  dependencies: ISignatureDependency[];
+  assignedSigner?: ISignerAssignment;
+  status: 'pending' | 'ready' | 'in_progress' | 'completed' | 'declined' | 'expired' | 'voided';
+  signature?: ISignature;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ============================================================================
+// MAIN CONTRACT INTERFACE
+// ============================================================================
+
+/**
+ * Complete portable contract interface
+ * All fields are required - use empty arrays/objects where no data
+ */
+export interface IPortableContract {
+  // Core Identity
+  id: string;
+  title: string;
+  context: string;
+  metadata: IContractMetadata;
+
+  // Parties and Roles
+  availableRoles: IRole[];
+  involvedParties: IInvolvedParty[];
+
+  // Content Structure
+  paragraphs: IParagraph[];
+  variables: IVariable[];
+  signatureFields: ISignatureField[];
+
+  // Structured Terms
+  financialTerms: IFinancialTerms;
+  timeTerms: ITimeTerms;
+  obligationTerms: IObligationTerms;
+
+  // Documents
+  priorContracts: IPriorContractReference[];
+  attachments: IContractAttachment[];
+
+  // Versioning
+  versionHistory: IVersionHistory;
+
+  // Collaboration
+  collaborators: ICollaborator[];
+  commentThreads: ICommentThread[];
+  suggestions: ISuggestion[];
+
+  // Lifecycle and Audit
+  lifecycle: IDocumentLifecycle;
+  auditLog: IAuditLog;
+
+  // PDF Generation (optional)
+  pdfConfig?: IPdfGenerationConfig;
+  finalDocument?: plugins.tsclass.business.IPdf;
+  renderTemplateId?: string;
+  renderOptions?: Record<string, unknown>;
+
+  // Timestamps
+  createdAt: number;
+  createdBy: string;
+  updatedAt: number;
+  updatedBy?: string;
+
+  // Organization
+  organizationId?: string;
+  visibility: 'private' | 'organization' | 'public';
+
+  // Integrations
+  integrations: {
+    crmId?: string;
+    erpId?: string;
+    customIntegrations: Record<string, string>;
+  };
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+import {
+  createEmptyFinancialTerms as _createEmptyFinancialTerms,
+  createEmptyTimeTerms as _createEmptyTimeTerms,
+  createEmptyObligationTerms as _createEmptyObligationTerms,
+} from './terms.js';
+import { createInitialVersion, createEmptyVersionHistory } from './versioning.js';
+import { createInitialLifecycle, createEmptyAuditLog } from './lifecycle.js';
+
+/**
+ * Create default governing law
+ */
+export function createDefaultGoverningLaw(): IGoverningLaw {
+  return {
+    country: '',
+    applicableLaws: [],
+    disputeResolution: 'litigation',
+  };
+}
+
+/**
+ * Create default contract metadata
+ */
+export function createDefaultMetadata(
+  category: TContractCategory,
+  contractType: TContractType,
+  language: string = 'en'
+): IContractMetadata {
+  return {
+    category,
+    contractType,
+    language,
+    additionalLanguages: [],
+    governingLaw: createDefaultGoverningLaw(),
+    tags: [],
+    relatedContractIds: [],
+    confidentialityLevel: 'internal',
+    customFields: {},
+  };
+}
+
+/**
+ * Create a new empty contract
+ */
+export function createEmptyContract(
+  title: string,
+  category: TContractCategory,
+  contractType: TContractType,
+  createdBy: string,
+  language: string = 'en'
+): IPortableContract {
+  const id = crypto.randomUUID();
+  const now = Date.now();
+  const initialVersion = createInitialVersion(createdBy);
+
+  return {
+    id,
+    title,
+    context: '',
+    metadata: createDefaultMetadata(category, contractType, language),
+    availableRoles: [],
+    involvedParties: [],
+    paragraphs: [],
+    variables: [],
+    signatureFields: [],
+    financialTerms: _createEmptyFinancialTerms(),
+    timeTerms: _createEmptyTimeTerms(),
+    obligationTerms: _createEmptyObligationTerms(),
+    priorContracts: [],
+    attachments: [],
+    versionHistory: createEmptyVersionHistory(id, initialVersion),
+    collaborators: [],
+    commentThreads: [],
+    suggestions: [],
+    lifecycle: createInitialLifecycle(id),
+    auditLog: createEmptyAuditLog(id),
+    createdAt: now,
+    createdBy,
+    updatedAt: now,
+    visibility: 'private',
+    integrations: {
+      customIntegrations: {},
+    },
+  };
+}
+
+/**
+ * Create a new role
+ */
+export function createRole(
+  id: string,
+  name: string,
+  description: string,
+  options: Partial<IRole> = {}
+): IRole {
+  return {
+    id,
+    name,
+    description,
+    category: 'party',
+    signatureRequired: true,
+    defaultSigningOrder: 1,
+    notifyOnChanges: true,
+    notifyOnComments: true,
+    ...options,
+  };
+}
+
+/**
+ * Create an involved party
+ */
+export function createInvolvedParty(
+  roleId: string,
+  contact: plugins.tsclass.business.TContact,
+  signingOrder: number = 1
+): IInvolvedParty {
+  return {
+    partyId: crypto.randomUUID(),
+    roleId,
+    contact,
+    partyRole: 'signer',
+    signingOrder,
+    signingDependency: 'none',
+    dependsOnParties: [],
+    signature: {
+      status: 'pending',
+    },
+    actingAsProxy: false,
+    remindersSent: 0,
+    totalViews: 0,
+    metadata: {},
+  };
+}
+
+/**
+ * Create a paragraph
+ */
+export function createParagraph(
+  title: string,
+  content: string,
+  sectionType: TSectionType = 'clause',
+  order: number = 0
+): IParagraph {
+  return {
+    uniqueId: crypto.randomUUID(),
+    parentId: null,
+    title,
+    content,
+    sectionType,
+    order,
+    depth: 0,
+    required: true,
+    isEditable: true,
+    variables: [],
+    conditions: [],
+    legalReferences: [],
+    translations: {},
+    crossReferences: [],
+    attachmentReferences: [],
+    jurisdictions: [],
+    tags: [],
+    aiGenerated: false,
+  };
+}
+
+/**
+ * Create a variable
+ */
+export function createVariable(
+  variableId: string,
+  name: string,
+  type: TVariableType,
+  required: boolean = true
+): IVariable {
+  return {
+    variableId,
+    name,
+    type,
+    required,
+  };
+}

ts_interfaces/identity.ts

@@ -0,0 +1,295 @@
+/**
+ * @file identity.ts
+ * @description Identity verification interfaces
+ * Extensible design for passport/NFC, document+selfie, video ident, and third-party providers
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TIdentityVerificationMethod,
+  TVerificationConfidence,
+  TIdentityVerificationStatus,
+  TIdentityDocumentType,
+} from './types.js';
+
+// ============================================================================
+// IDENTITY VERIFICATION REQUEST
+// ============================================================================
+
+/**
+ * Expected identity to verify against
+ */
+export interface IExpectedIdentity {
+  fullName?: string;
+  dateOfBirth?: string;
+  nationality?: string;
+  documentNumber?: string;
+}
+
+/**
+ * Request for identity verification
+ */
+export interface IIdentityVerificationRequest {
+  id: string;
+  methods: TIdentityVerificationMethod[];
+  requiredConfidence: TVerificationConfidence;
+  expectedIdentity?: IExpectedIdentity;
+  createdAt: number;
+  expiresAt: number;
+  callbackUrl?: string;
+}
+
+// ============================================================================
+// DOCUMENT VERIFICATION
+// ============================================================================
+
+/**
+ * Personal information from identity document
+ */
+export interface IDocumentPersonalInfo {
+  fullName: string;
+  givenNames: string;
+  surname: string;
+  dateOfBirth: string;
+  sex: 'M' | 'F' | 'X';
+  nationality: string;
+  placeOfBirth?: string;
+}
+
+/**
+ * Document validity information
+ */
+export interface IDocumentValidity {
+  issueDate?: string;
+  expiryDate: string;
+  issuingAuthority?: string;
+}
+
+/**
+ * Machine Readable Zone data
+ */
+export interface IMrzData {
+  raw: string[];
+  valid: boolean;
+  checkDigitsValid: boolean;
+}
+
+/**
+ * NFC chip data (for ePassports)
+ */
+export interface INfcChipData {
+  readSuccess: boolean;
+  chipAuthenticated: boolean;
+  activeAuthentication?: {
+    performed: boolean;
+    success: boolean;
+  };
+  passiveAuthentication?: {
+    performed: boolean;
+    success: boolean;
+    certificateChainValid: boolean;
+  };
+  dataGroupsRead: string[];
+  photoBase64?: string;
+}
+
+/**
+ * Document images
+ */
+export interface IDocumentImages {
+  frontBase64?: string;
+  backBase64?: string;
+  portraitBase64?: string;
+}
+
+/**
+ * Identity document data extracted from document
+ */
+export interface IIdentityDocument {
+  documentType: TIdentityDocumentType;
+  issuingCountry: string;
+  documentNumber: string;
+  personalInfo: IDocumentPersonalInfo;
+  validity: IDocumentValidity;
+  mrz?: IMrzData;
+  nfcData?: INfcChipData;
+  images?: IDocumentImages;
+}
+
+// ============================================================================
+// FACIAL/BIOMETRIC VERIFICATION
+// ============================================================================
+
+/**
+ * Liveness check result
+ */
+export interface ILivenessResult {
+  isLive: boolean;
+  confidence: number;
+  checks: {
+    blinkDetected?: boolean;
+    headMovementDetected?: boolean;
+    depthAnalysis?: boolean;
+    textureAnalysis?: boolean;
+  };
+}
+
+/**
+ * Face matching result
+ */
+export interface IFaceMatchResult {
+  matched: boolean;
+  confidence: number;
+  referenceSource: 'document_photo' | 'nfc_photo' | 'existing_profile';
+}
+
+/**
+ * Facial verification result
+ */
+export interface IFacialVerification {
+  livenessCheckPerformed: boolean;
+  livenessResult?: ILivenessResult;
+  faceMatchResult?: IFaceMatchResult;
+  selfieReference?: string;
+  capturedAt: number;
+}
+
+// ============================================================================
+// THIRD-PARTY IDENTITY PROVIDER
+// ============================================================================
+
+/**
+ * Third-party identity provider configuration
+ */
+export interface IIdentityProvider {
+  id: string;
+  name: string;
+  type: 'oidc' | 'saml' | 'proprietary' | 'bankid' | 'eid';
+  countries: string[];
+  methods: TIdentityVerificationMethod[];
+  maxConfidence: TVerificationConfidence;
+  config?: Record<string, unknown>;
+}
+
+/**
+ * Third-party verification result
+ */
+export interface IThirdPartyVerification {
+  provider: IIdentityProvider;
+  providerReference: string;
+  verifiedAt: number;
+  claims: Record<string, unknown>;
+  levelOfAssurance?: 'low' | 'substantial' | 'high';
+  rawAssertionReference?: string;
+}
+
+// ============================================================================
+// VERIFICATION FAILURES
+// ============================================================================
+
+/**
+ * Verification failure details
+ */
+export interface IVerificationFailure {
+  code: string;
+  method: TIdentityVerificationMethod;
+  message: string;
+  timestamp: number;
+  recoverable: boolean;
+}
+
+/**
+ * Verification audit entry
+ */
+export interface IVerificationAuditEntry {
+  timestamp: number;
+  action: string;
+  details: Record<string, unknown>;
+  actor?: {
+    type: 'user' | 'system' | 'agent';
+    id: string;
+  };
+}
+
+// ============================================================================
+// IDENTITY VERIFICATION RESULT
+// ============================================================================
+
+/**
+ * Verified identity information
+ */
+export interface IVerifiedIdentity {
+  fullName: string;
+  givenNames?: string;
+  surname?: string;
+  dateOfBirth?: string;
+  nationality?: string;
+  address?: plugins.tsclass.business.IAddress;
+}
+
+/**
+ * Complete identity verification result
+ */
+export interface IIdentityVerificationResult {
+  id: string;
+  requestId: string;
+  status: TIdentityVerificationStatus;
+  confidence: TVerificationConfidence;
+  confidenceScore: number;
+  methodsAttempted: TIdentityVerificationMethod[];
+  successfulMethod?: TIdentityVerificationMethod;
+  verifiedIdentity?: IVerifiedIdentity;
+  documentVerification?: IIdentityDocument;
+  facialVerification?: IFacialVerification;
+  thirdPartyVerification?: IThirdPartyVerification;
+  timestamps: {
+    started: number;
+    completed: number;
+    expiresAt?: number;
+  };
+  failureReasons: IVerificationFailure[];
+  auditTrail: IVerificationAuditEntry[];
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create an identity verification request
+ */
+export function createIdentityVerificationRequest(
+  methods: TIdentityVerificationMethod[],
+  requiredConfidence: TVerificationConfidence,
+  expiresInSeconds: number = 3600
+): IIdentityVerificationRequest {
+  const now = Date.now();
+  return {
+    id: crypto.randomUUID(),
+    methods,
+    requiredConfidence,
+    createdAt: now,
+    expiresAt: now + expiresInSeconds * 1000,
+  };
+}
+
+/**
+ * Create a pending identity verification result
+ */
+export function createPendingVerificationResult(requestId: string): IIdentityVerificationResult {
+  const now = Date.now();
+  return {
+    id: crypto.randomUUID(),
+    requestId,
+    status: 'pending',
+    confidence: 'none',
+    confidenceScore: 0,
+    methodsAttempted: [],
+    timestamps: {
+      started: now,
+      completed: 0,
+    },
+    failureReasons: [],
+    auditTrail: [],
+  };
+}

ts_interfaces/index.ts

@@ -1,27 +1,65 @@
+/**
+ * @file index.ts
+ * @description Main export file for signature.digital contract interfaces
+ * Comprehensive contract management system supporting 99.9% of contract use cases
+ */
+
 import * as plugins from './plugins.js';
-export interface IParagraph {
-  uniqueId: string;
-  parent: IParagraph | null;
-  title: string;
-  content: string;
-}
 
-export interface IRole {
+// Export plugins for access to tsclass types
-  id: string;
+export { plugins };
-  name: string;
-  description: string;
-}
 
-export interface IInvolvedParty {
+// ============================================================================
-  role: string;
+// TYPE ALIASES
-  contact: plugins.tsclass.business.IContact;
+// ============================================================================
-}
+export * from './types.js';
 
-export interface IPortableContract {
+// ============================================================================
-  title: string;
+// STRUCTURED TERMS
-  context: string;
+// ============================================================================
-  availableRoles: IRole[];
+export * from './terms.js';
-  involvedParties: IInvolvedParty[];
+
-  priorContracts: IPortableContract[];
+// ============================================================================
-  paragraphs: IParagraph[];
+// SIGNATURE SYSTEM
-}
+// ============================================================================
+export * from './signature.js';
+
+// ============================================================================
+// IDENTITY VERIFICATION
+// ============================================================================
+export * from './identity.js';
+
+// ============================================================================
+// LEGAL COMPLIANCE
+// ============================================================================
+export * from './legal.js';
+
+// ============================================================================
+// VERSIONING
+// ============================================================================
+export * from './versioning.js';
+
+// ============================================================================
+// COLLABORATION
+// ============================================================================
+export * from './collaboration.js';
+
+// ============================================================================
+// LIFECYCLE AND AUDIT
+// ============================================================================
+export * from './lifecycle.js';
+
+// ============================================================================
+// ATTACHMENTS
+// ============================================================================
+export * from './attachments.js';
+
+// ============================================================================
+// PDF GENERATION
+// ============================================================================
+export * from './pdf.js';
+
+// ============================================================================
+// MAIN CONTRACT INTERFACE
+// ============================================================================
+export * from './contract.js';

ts_interfaces/legal.ts

@@ -0,0 +1,369 @@
+/**
+ * @file legal.ts
+ * @description Legal compliance interfaces
+ * TSA (RFC 3161) timestamps, blockchain anchoring, eIDAS qualified signatures
+ */
+
+import type {
+  TTimestampMethod,
+  TBlockchainNetwork,
+  THashAlgorithm,
+  TSignatureLegalLevel,
+  TComplianceAction,
+  TQualificationStatus,
+  TValidationStatus,
+  TIdentityVerificationMethod,
+} from './types.js';
+
+// ============================================================================
+// TSA TIMESTAMP (RFC 3161)
+// ============================================================================
+
+/**
+ * Time Stamp Authority information
+ */
+export interface ITsaAuthority {
+  name: string;
+  url: string;
+  certificateFingerprint: string;
+  isQualified: boolean;
+  country?: string;
+}
+
+/**
+ * Timestamp token data
+ */
+export interface ITsaToken {
+  tokenBase64: string;
+  serialNumber: string;
+  time: number;
+  hashAlgorithm: string;
+  hashedMessage: string;
+  nonce?: string;
+}
+
+/**
+ * TSA verification status
+ */
+export interface ITsaVerification {
+  verified: boolean;
+  verifiedAt: number;
+  certificateChainValid: boolean;
+  signatureValid: boolean;
+}
+
+/**
+ * Qualified TSA information (eIDAS)
+ */
+export interface IQualifiedTsaInfo {
+  trustedListReference: string;
+  serviceId: string;
+  qualificationStatus: TQualificationStatus;
+}
+
+/**
+ * RFC 3161 Time Stamp Token
+ */
+export interface ITsaTimestamp {
+  id: string;
+  authority: ITsaAuthority;
+  token: ITsaToken;
+  verification: ITsaVerification;
+  qualifiedInfo?: IQualifiedTsaInfo;
+}
+
+// ============================================================================
+// BLOCKCHAIN TIMESTAMP
+// ============================================================================
+
+/**
+ * Blockchain transaction information
+ */
+export interface IBlockchainTransaction {
+  txHash: string;
+  blockNumber: number;
+  blockHash: string;
+  blockTimestamp: number;
+  txIndex: number;
+}
+
+/**
+ * Merkle proof for aggregated timestamps
+ */
+export interface IMerkleProof {
+  root: string;
+  proof: string[];
+  leaf: string;
+  positions: ('left' | 'right')[];
+}
+
+/**
+ * Timestamped data information
+ */
+export interface ITimestampedData {
+  dataHash: string;
+  hashAlgorithm: THashAlgorithm;
+  dataReference?: string;
+}
+
+/**
+ * Blockchain verification status
+ */
+export interface IBlockchainVerification {
+  verified: boolean;
+  verifiedAt: number;
+  blockConfirmations: number;
+  explorerUrl?: string;
+}
+
+/**
+ * Blockchain timestamping provider
+ */
+export interface IBlockchainProvider {
+  name: string;
+  serviceId?: string;
+  proofUrl?: string;
+}
+
+/**
+ * Blockchain timestamp anchor
+ */
+export interface IBlockchainTimestamp {
+  id: string;
+  network: TBlockchainNetwork;
+  chainId?: number;
+  transaction: IBlockchainTransaction;
+  merkleProof?: IMerkleProof;
+  timestampedData: ITimestampedData;
+  verification: IBlockchainVerification;
+  provider?: IBlockchainProvider;
+}
+
+// ============================================================================
+// LONG-TERM VALIDATION (LTV)
+// ============================================================================
+
+/**
+ * Long-term validation data (for PAdES-LTV equivalent)
+ */
+export interface ILongTermValidation {
+  certificateChains: string[];
+  ocspResponses: string[];
+  crlData: string[];
+  archiveTimestamp?: ITsaTimestamp;
+}
+
+/**
+ * Document hash information
+ */
+export interface IDocumentHashInfo {
+  algorithm: THashAlgorithm;
+  value: string;
+  scope: 'content_only' | 'content_and_signatures' | 'full_envelope';
+}
+
+/**
+ * Signature validation details
+ */
+export interface ISignatureValidationDetails {
+  cryptographicCheck: boolean;
+  certificateChainValid: boolean;
+  timestampValid: boolean;
+  signerIdentityVerified: boolean;
+}
+
+/**
+ * Signature validation result
+ */
+export interface ISignatureValidation {
+  validatedAt: number;
+  status: TValidationStatus;
+  details: ISignatureValidationDetails;
+}
+
+// ============================================================================
+// COMPLIANCE AUDIT
+// ============================================================================
+
+/**
+ * Compliance audit entry
+ */
+export interface IComplianceAuditEntry {
+  timestamp: number;
+  action: TComplianceAction;
+  details: Record<string, unknown>;
+  actor: {
+    type: 'system' | 'service' | 'user';
+    id: string;
+  };
+}
+
+// ============================================================================
+// LEGAL COMPLIANCE PROOF
+// ============================================================================
+
+/**
+ * Complete legal compliance proof for a signature
+ */
+export interface ILegalComplianceProof {
+  id: string;
+  schemaVersion: '1.0.0';
+  eidasLevel?: TSignatureLegalLevel;
+  jurisdictions: string[];
+  tsaTimestamps: ITsaTimestamp[];
+  blockchainTimestamps: IBlockchainTimestamp[];
+  longTermValidation?: ILongTermValidation;
+  documentHash: IDocumentHashInfo;
+  signatureValidation?: ISignatureValidation;
+  auditTrail: IComplianceAuditEntry[];
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ============================================================================
+// SIGNATURE VALIDATION REQUEST/RESULT
+// ============================================================================
+
+/**
+ * Request to validate a signature
+ */
+export interface ISignatureValidationRequest {
+  signatureId: string;
+  documentHash: string;
+  validationLevel: 'basic' | 'timestamp' | 'long_term';
+  checkRevocation: boolean;
+  validationTime?: number;
+}
+
+/**
+ * Detailed validation result for signature integrity
+ */
+export interface ISignatureIntegrityResult {
+  status: 'valid' | 'invalid';
+  message?: string;
+}
+
+/**
+ * Certificate chain validation result
+ */
+export interface ICertificateChainResult {
+  status: 'valid' | 'invalid' | 'unknown';
+  chainLength: number;
+  rootTrusted: boolean;
+  message?: string;
+}
+
+/**
+ * Timestamp validation result
+ */
+export interface ITimestampValidationResult {
+  status: 'valid' | 'invalid' | 'not_present';
+  timestampTime?: number;
+  tsaName?: string;
+}
+
+/**
+ * Revocation check result
+ */
+export interface IRevocationResult {
+  status: 'good' | 'revoked' | 'unknown';
+  checkedAt: number;
+  method: 'ocsp' | 'crl' | 'none';
+  revocationTime?: number;
+}
+
+/**
+ * Identity verification validation result
+ */
+export interface IIdentityValidationResult {
+  status: 'verified' | 'not_verified' | 'expired';
+  method?: TIdentityVerificationMethod;
+  verifiedAt?: number;
+}
+
+/**
+ * Signature validation result
+ */
+export interface ISignatureValidationResult {
+  requestId: string;
+  status: TValidationStatus;
+  details: {
+    signatureIntegrity: ISignatureIntegrityResult;
+    certificateChain?: ICertificateChainResult;
+    timestamp?: ITimestampValidationResult;
+    revocation?: IRevocationResult;
+    identityVerification?: IIdentityValidationResult;
+  };
+  warnings: string[];
+  validatedAt: number;
+  reportReference?: string;
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create empty legal compliance proof
+ */
+export function createEmptyLegalComplianceProof(): ILegalComplianceProof {
+  const now = Date.now();
+  return {
+    id: crypto.randomUUID(),
+    schemaVersion: '1.0.0',
+    jurisdictions: [],
+    tsaTimestamps: [],
+    blockchainTimestamps: [],
+    documentHash: {
+      algorithm: 'SHA-256',
+      value: '',
+      scope: 'full_envelope',
+    },
+    auditTrail: [],
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+/**
+ * Create a TSA timestamp request result placeholder
+ */
+export function createPendingTsaTimestamp(authorityUrl: string): Partial<ITsaTimestamp> {
+  return {
+    id: crypto.randomUUID(),
+    authority: {
+      name: '',
+      url: authorityUrl,
+      certificateFingerprint: '',
+      isQualified: false,
+    },
+    verification: {
+      verified: false,
+      verifiedAt: 0,
+      certificateChainValid: false,
+      signatureValid: false,
+    },
+  };
+}
+
+/**
+ * Create a blockchain timestamp placeholder
+ */
+export function createPendingBlockchainTimestamp(
+  network: TBlockchainNetwork,
+  dataHash: string
+): Partial<IBlockchainTimestamp> {
+  return {
+    id: crypto.randomUUID(),
+    network,
+    timestampedData: {
+      dataHash,
+      hashAlgorithm: 'SHA-256',
+    },
+    verification: {
+      verified: false,
+      verifiedAt: 0,
+      blockConfirmations: 0,
+    },
+  };
+}

ts_interfaces/lifecycle.ts

@@ -0,0 +1,457 @@
+/**
+ * @file lifecycle.ts
+ * @description Document lifecycle and audit interfaces
+ * Status workflow, transitions, retention policies, and legal holds
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TContractStatus,
+  TTerminationReason,
+  TActionCategory,
+  TActionSeverity,
+  TPaymentFrequency,
+} from './types.js';
+import type { IDuration, IMonetaryAmount, IPriceAdjustment } from './terms.js';
+
+// ============================================================================
+// STATUS TRANSITIONS
+// ============================================================================
+
+/**
+ * Validation check for status transition
+ */
+export interface IStatusValidation {
+  rule: string;
+  description: string;
+  passed: boolean;
+  failureReason?: string;
+  checkedAt: number;
+}
+
+/**
+ * Status transition with validation
+ */
+export interface IStatusTransition {
+  fromStatus: TContractStatus;
+  toStatus: TContractStatus;
+  triggeredBy: string;
+  triggeredAt: number;
+  reason?: string;
+  metadata?: Record<string, unknown>;
+  validationsPerformed: IStatusValidation[];
+}
+
+/**
+ * Validation rule for transitions
+ */
+export interface ITransitionValidationRule {
+  id: string;
+  name: string;
+  description: string;
+  validatorType: 'signature_count' | 'approval_chain' | 'date_check' | 'custom';
+  parameters?: Record<string, unknown>;
+}
+
+/**
+ * Status transition rules configuration
+ */
+export interface IStatusTransitionRule {
+  allowedTransitions: TContractStatus[];
+  requiredValidations: ITransitionValidationRule[];
+  requiresApproval: boolean;
+  approverRoles?: string[];
+}
+
+/**
+ * Map of status transition rules
+ */
+export type TStatusTransitionRules = Record<TContractStatus, IStatusTransitionRule>;
+
+// ============================================================================
+// TERMINATION
+// ============================================================================
+
+/**
+ * Early termination penalty
+ */
+export interface IEarlyTerminationPenalty {
+  amount: number;
+  currency: string;
+  paid: boolean;
+  paidAt?: number;
+}
+
+/**
+ * Termination record
+ */
+export interface ITermination {
+  terminatedAt: number;
+  terminatedBy: string;
+  effectiveDate: number;
+  reason: TTerminationReason;
+  customReasonDescription?: string;
+  noticeGiven: boolean;
+  noticeDate?: number;
+  noticePeriodDays?: number;
+  earlyTerminationPenalty?: IEarlyTerminationPenalty;
+  mutuallyAgreed: boolean;
+  agreementDocumentId?: string;
+}
+
+// ============================================================================
+// EXPIRATION AND RENEWAL
+// ============================================================================
+
+/**
+ * Auto-renewal terms
+ */
+export interface IAutoRenewTerms {
+  renewalPeriodMonths: number;
+  maxRenewals: number;
+  currentRenewalCount: number;
+  priceAdjustment?: IPriceAdjustment;
+}
+
+/**
+ * Renewal notice information
+ */
+export interface IRenewalNotice {
+  requiredNoticeDays: number;
+  noticeReceivedAt?: number;
+  renewalDeclined: boolean;
+  declinedAt?: number;
+  declinedBy?: string;
+}
+
+/**
+ * Expiration and renewal handling
+ */
+export interface IExpirationConfig {
+  expirationDate: number;
+  reminderDays: number[];
+  autoRenew: boolean;
+  autoRenewTerms?: IAutoRenewTerms;
+  renewalNotice?: IRenewalNotice;
+}
+
+// ============================================================================
+// STATUS HISTORY
+// ============================================================================
+
+/**
+ * Complete status history entry
+ */
+export interface IStatusHistoryEntry {
+  id: string;
+  previousStatus: TContractStatus | null;
+  newStatus: TContractStatus;
+  transition: IStatusTransition;
+  versionIdAtTransition: string;
+  hashChainLink: string;
+}
+
+// ============================================================================
+// DOCUMENT LIFECYCLE
+// ============================================================================
+
+/**
+ * Document lifecycle state
+ */
+export interface IDocumentLifecycle {
+  contractId: string;
+  currentStatus: TContractStatus;
+  statusHistory: IStatusHistoryEntry[];
+  createdAt: number;
+  firstPublishedAt?: number;
+  executedAt?: number;
+  effectiveDate?: number;
+  expiration?: IExpirationConfig;
+  termination?: ITermination;
+  supersededBy?: string;
+  supersedes?: string;
+}
+
+// ============================================================================
+// AUDIT LOG
+// ============================================================================
+
+/**
+ * Geolocation for audit entry
+ */
+export interface IAuditGeolocation {
+  country: string;
+  region?: string;
+  city?: string;
+  coordinates?: {
+    lat: number;
+    lng: number;
+  };
+}
+
+/**
+ * Digital signature for audit entry non-repudiation
+ */
+export interface IAuditDigitalSignature {
+  signedBy: string;
+  algorithm: 'RSA-SHA256' | 'ECDSA-P256';
+  signature: string;
+  certificate?: string;
+}
+
+/**
+ * Extended action interface building on IObjectAction from tsclass
+ */
+export interface IContractAction extends plugins.tsclass.database.IObjectAction {
+  id: string;
+  contractId: string;
+  versionId?: string;
+  category: TActionCategory;
+  severity: TActionSeverity;
+  ipAddress?: string;
+  userAgent?: string;
+  sessionId?: string;
+  location?: IAuditGeolocation;
+  previousActionHash: string;
+  actionHash: string;
+  digitalSignature?: IAuditDigitalSignature;
+}
+
+/**
+ * Audit log statistics
+ */
+export interface IAuditStatistics {
+  totalActions: number;
+  actionsByCategory: Record<TActionCategory, number>;
+  uniqueUsers: string[];
+  dateRange: {
+    earliest: number;
+    latest: number;
+  };
+}
+
+/**
+ * Complete audit log for a contract
+ */
+export interface IAuditLog {
+  contractId: string;
+  actions: IContractAction[];
+  genesisHash: string;
+  currentHash: string;
+  chainLength: number;
+  lastVerifiedAt?: number;
+  statistics: IAuditStatistics;
+}
+
+// ============================================================================
+// RETENTION AND LEGAL HOLDS
+// ============================================================================
+
+/**
+ * Retention policy scope
+ */
+export interface IRetentionScope {
+  contractTypes?: string[];
+  jurisdictions?: string[];
+  tags?: string[];
+  allContracts?: boolean;
+}
+
+/**
+ * Retention period configuration
+ */
+export interface IRetentionPeriod {
+  duration: number;
+  startFrom: 'execution' | 'expiration' | 'termination' | 'creation';
+}
+
+/**
+ * Retention policy configuration
+ */
+export interface IRetentionPolicy {
+  id: string;
+  name: string;
+  description: string;
+  appliesTo: IRetentionScope;
+  retentionPeriod: IRetentionPeriod;
+  endOfRetentionAction: 'archive' | 'delete' | 'review' | 'anonymize';
+  legalBasis?: string;
+  legalHoldOverrides: boolean;
+}
+
+/**
+ * Legal hold for litigation/investigation
+ */
+export interface ILegalHold {
+  id: string;
+  name: string;
+  description: string;
+  contractIds: string[];
+  userIds?: string[];
+  dateRange?: {
+    start: number;
+    end: number;
+  };
+  createdBy: string;
+  createdAt: number;
+  reason: string;
+  caseReference?: string;
+  indefinite: boolean;
+  expiresAt?: number;
+  status: 'active' | 'released' | 'expired';
+  releasedBy?: string;
+  releasedAt?: number;
+  releaseReason?: string;
+}
+
+// ============================================================================
+// DISCOVERY EXPORT
+// ============================================================================
+
+/**
+ * Discovery export access log entry
+ */
+export interface IDiscoveryAccessLog {
+  userId: string;
+  accessedAt: number;
+  action: 'download' | 'view';
+  ipAddress: string;
+}
+
+/**
+ * Export package for legal discovery
+ */
+export interface IDiscoveryExport {
+  id: string;
+  requestedBy: string;
+  requestedAt: number;
+  contractIds: string[];
+  dateRange?: {
+    start: number;
+    end: number;
+  };
+  includeAuditLog: boolean;
+  includeVersionHistory: boolean;
+  includeComments: boolean;
+  includeAttachments: boolean;
+  format: 'pdf' | 'json' | 'xml' | 'native';
+  packageUrl?: string;
+  packageHash?: string;
+  generatedAt?: number;
+  expiresAt?: number;
+  accessLog: IDiscoveryAccessLog[];
+}
+
+// ============================================================================
+// COMPLIANCE CHECK
+// ============================================================================
+
+/**
+ * Individual compliance finding
+ */
+export interface IComplianceFinding {
+  id: string;
+  severity: 'critical' | 'major' | 'minor' | 'informational';
+  title: string;
+  description: string;
+  affectedElements?: string[];
+  recommendation?: string;
+}
+
+/**
+ * Compliance check result
+ */
+export interface IComplianceCheck {
+  checkId: string;
+  contractId: string;
+  performedAt: number;
+  performedBy: string;
+  checkType: 'retention' | 'signature_validity' | 'chain_integrity' | 'access_audit';
+  passed: boolean;
+  findings: IComplianceFinding[];
+  remediationRequired: boolean;
+  remediationActions?: string[];
+  remediationDeadline?: number;
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create initial document lifecycle
+ */
+export function createInitialLifecycle(contractId: string): IDocumentLifecycle {
+  const now = Date.now();
+  return {
+    contractId,
+    currentStatus: 'draft',
+    statusHistory: [],
+    createdAt: now,
+  };
+}
+
+/**
+ * Create empty audit log
+ */
+export function createEmptyAuditLog(contractId: string): IAuditLog {
+  const genesisHash = crypto.randomUUID();
+  return {
+    contractId,
+    actions: [],
+    genesisHash,
+    currentHash: genesisHash,
+    chainLength: 0,
+    statistics: {
+      totalActions: 0,
+      actionsByCategory: {} as Record<TActionCategory, number>,
+      uniqueUsers: [],
+      dateRange: {
+        earliest: 0,
+        latest: 0,
+      },
+    },
+  };
+}
+
+/**
+ * Create a status transition
+ */
+export function createStatusTransition(
+  fromStatus: TContractStatus,
+  toStatus: TContractStatus,
+  triggeredBy: string,
+  reason?: string
+): IStatusTransition {
+  return {
+    fromStatus,
+    toStatus,
+    triggeredBy,
+    triggeredAt: Date.now(),
+    reason,
+    validationsPerformed: [],
+  };
+}
+
+/**
+ * Create a legal hold
+ */
+export function createLegalHold(
+  name: string,
+  description: string,
+  contractIds: string[],
+  createdBy: string,
+  reason: string
+): ILegalHold {
+  return {
+    id: crypto.randomUUID(),
+    name,
+    description,
+    contractIds,
+    createdBy,
+    createdAt: Date.now(),
+    reason,
+    indefinite: true,
+    status: 'active',
+  };
+}

ts_interfaces/pdf.ts

@@ -0,0 +1,502 @@
+/**
+ * @file pdf.ts
+ * @description PDF generation configuration interfaces
+ * Templates, branding, layout, headers/footers, and security
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TPageSize,
+  TPageOrientation,
+  THeaderFooterContentType,
+  TPageNumberFormat,
+  TPdfEncryptionAlgorithm,
+  TPdfPrintingPermission,
+  TPdfJobStatus,
+} from './types.js';
+
+// ============================================================================
+// FONT CONFIGURATION
+// ============================================================================
+
+/**
+ * Font configuration
+ */
+export interface IFontConfig {
+  family: string;
+  fallback: string[];
+  size: number;
+  lineHeight: number;
+  weight?: 'normal' | 'bold' | number;
+}
+
+// ============================================================================
+// BRANDING
+// ============================================================================
+
+/**
+ * Logo configuration
+ */
+export interface ILogoConfig {
+  url: string;
+  position: 'left' | 'center' | 'right';
+  maxWidth: number;
+  maxHeight: number;
+}
+
+/**
+ * Watermark configuration
+ */
+export interface IWatermarkConfig {
+  text?: string;
+  imageUrl?: string;
+  opacity: number;
+  position: 'center' | 'diagonal';
+  showOnlyOnDraft: boolean;
+}
+
+/**
+ * Branding configuration for PDF
+ */
+export interface IPdfBranding {
+  logo?: ILogoConfig;
+  primaryColor: string;
+  secondaryColor: string;
+  textColor: string;
+  fonts: {
+    heading: IFontConfig;
+    body: IFontConfig;
+    monospace?: IFontConfig;
+  };
+  watermark?: IWatermarkConfig;
+}
+
+// ============================================================================
+// LAYOUT
+// ============================================================================
+
+/**
+ * Custom page size
+ */
+export interface ICustomPageSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Page margins
+ */
+export interface IPageMargins {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * PDF layout configuration
+ */
+export interface IPdfLayout {
+  pageSize: TPageSize;
+  customSize?: ICustomPageSize;
+  orientation: TPageOrientation;
+  margins: IPageMargins;
+  columns: 1 | 2;
+  columnGap?: number;
+  paragraphSpacing: number;
+  sectionSpacing: number;
+  firstPageDifferent: boolean;
+  firstPageMargins?: IPageMargins;
+}
+
+// ============================================================================
+// HEADER/FOOTER
+// ============================================================================
+
+/**
+ * Header/Footer content definition
+ */
+export interface IPdfHeaderFooterContent {
+  type: THeaderFooterContentType;
+  text?: string;
+  imageUrl?: string;
+  pageNumberFormat?: TPageNumberFormat;
+  pageNumberPrefix?: string;
+  includeTotal?: boolean;
+  dateFormat?: string;
+  customTemplate?: string;
+  fontSize?: number;
+  fontWeight?: 'normal' | 'bold';
+  color?: string;
+}
+
+/**
+ * Header/Footer configuration
+ */
+export interface IPdfHeaderFooter {
+  enabled: boolean;
+  height: number;
+  left?: IPdfHeaderFooterContent;
+  center?: IPdfHeaderFooterContent;
+  right?: IPdfHeaderFooterContent;
+  borderBottom?: boolean;
+  borderTop?: boolean;
+  borderColor?: string;
+  skipFirstPage: boolean;
+  skipLastPage: boolean;
+}
+
+// ============================================================================
+// PAGE NUMBERING
+// ============================================================================
+
+/**
+ * Page numbering configuration
+ */
+export interface IPdfPageNumbering {
+  enabled: boolean;
+  startFrom: number;
+  format: TPageNumberFormat;
+  position: 'header' | 'footer';
+  alignment: 'left' | 'center' | 'right';
+  prefix?: string;
+  suffix?: string;
+}
+
+// ============================================================================
+// CONTENT OPTIONS
+// ============================================================================
+
+/**
+ * Table of contents configuration
+ */
+export interface ITocConfig {
+  enabled: boolean;
+  depth: number;
+  title: string;
+  pageBreakAfter: boolean;
+}
+
+/**
+ * Cover page configuration
+ */
+export interface ICoverPageConfig {
+  enabled: boolean;
+  template: 'standard' | 'minimal' | 'custom';
+  customTemplateId?: string;
+  showLogo: boolean;
+  showDate: boolean;
+  showParties: boolean;
+  showConfidentialityNotice: boolean;
+  confidentialityText?: string;
+}
+
+/**
+ * Signature page configuration
+ */
+export interface ISignaturePageConfig {
+  enabled: boolean;
+  signatureBlockStyle: 'inline' | 'separate_page' | 'both';
+  includeWitnessLines: boolean;
+  includeInitialsOnEachPage: boolean;
+}
+
+/**
+ * Attachment handling configuration
+ */
+export interface IAttachmentConfig {
+  includeInline: boolean;
+  includeSeparately: boolean;
+  attachmentToc: boolean;
+}
+
+/**
+ * Content formatting configuration
+ */
+export interface IFormattingConfig {
+  headingNumbering: boolean;
+  paragraphNumbering: boolean;
+  preserveMarkdownFormatting: boolean;
+  convertLinksToFootnotes: boolean;
+}
+
+/**
+ * Content rendering options
+ */
+export interface IPdfContentOptions {
+  tableOfContents: ITocConfig;
+  coverPage?: ICoverPageConfig;
+  signaturePages: ISignaturePageConfig;
+  attachments: IAttachmentConfig;
+  formatting: IFormattingConfig;
+}
+
+// ============================================================================
+// SECURITY
+// ============================================================================
+
+/**
+ * Encryption configuration
+ */
+export interface IPdfEncryption {
+  enabled: boolean;
+  algorithm: TPdfEncryptionAlgorithm;
+}
+
+/**
+ * Password protection
+ */
+export interface IPdfPasswords {
+  userPassword?: string;
+  ownerPassword?: string;
+}
+
+/**
+ * PDF permissions
+ */
+export interface IPdfPermissions {
+  printing: TPdfPrintingPermission;
+  copying: boolean;
+  modifying: boolean;
+  annotating: boolean;
+  formFilling: boolean;
+  accessibility: boolean;
+  assembly: boolean;
+}
+
+/**
+ * PDF digital signature configuration
+ */
+export interface IPdfDigitalSignature {
+  enabled: boolean;
+  certificateId: string;
+  signatureReason: string;
+  signatureLocation?: string;
+  timestampAuthority?: string;
+}
+
+/**
+ * PDF security options
+ */
+export interface IPdfSecurity {
+  encryption: IPdfEncryption;
+  passwords?: IPdfPasswords;
+  permissions: IPdfPermissions;
+  digitalSignature?: IPdfDigitalSignature;
+}
+
+// ============================================================================
+// METADATA
+// ============================================================================
+
+/**
+ * PDF metadata
+ */
+export interface IPdfMetadata {
+  title: string;
+  subject?: string;
+  author?: string;
+  creator: string;
+  producer: string;
+  keywords: string[];
+  creationDate: number;
+  modificationDate?: number;
+  customProperties?: Record<string, string>;
+}
+
+// ============================================================================
+// COMPLETE CONFIGURATION
+// ============================================================================
+
+/**
+ * Complete PDF generation configuration
+ */
+export interface IPdfGenerationConfig {
+  templateId?: string;
+  useDefaultTemplate: boolean;
+  branding: IPdfBranding;
+  layout: IPdfLayout;
+  header?: IPdfHeaderFooter;
+  footer?: IPdfHeaderFooter;
+  pageNumbering: IPdfPageNumbering;
+  contentOptions: IPdfContentOptions;
+  security?: IPdfSecurity;
+  metadata: IPdfMetadata;
+}
+
+// ============================================================================
+// PDF TEMPLATE
+// ============================================================================
+
+/**
+ * PDF template definition
+ */
+export interface IPdfTemplate {
+  id: string;
+  name: string;
+  description?: string;
+  version: string;
+  config: IPdfGenerationConfig;
+  allowedContractTypes?: string[];
+  organizationId?: string;
+  isSystem: boolean;
+  createdAt: number;
+  createdBy: string;
+  lastModifiedAt?: number;
+  lastModifiedBy?: string;
+}
+
+// ============================================================================
+// PDF GENERATION JOB
+// ============================================================================
+
+/**
+ * PDF generation result
+ */
+export interface IPdfGenerationResult {
+  pdf: plugins.tsclass.business.IPdf;
+  pageCount: number;
+  fileSize: number;
+}
+
+/**
+ * PDF generation error
+ */
+export interface IPdfGenerationError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+/**
+ * PDF generation job
+ */
+export interface IPdfGenerationJob {
+  id: string;
+  contractId: string;
+  versionId: string;
+  config: IPdfGenerationConfig;
+  status: TPdfJobStatus;
+  progress?: number;
+  queuedAt: number;
+  startedAt?: number;
+  completedAt?: number;
+  result?: IPdfGenerationResult;
+  error?: IPdfGenerationError;
+  retryCount: number;
+  maxRetries: number;
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create default branding
+ */
+export function createDefaultBranding(): IPdfBranding {
+  return {
+    primaryColor: '#1a1a1a',
+    secondaryColor: '#666666',
+    textColor: '#333333',
+    fonts: {
+      heading: {
+        family: 'Helvetica',
+        fallback: ['Arial', 'sans-serif'],
+        size: 14,
+        lineHeight: 1.4,
+        weight: 'bold',
+      },
+      body: {
+        family: 'Helvetica',
+        fallback: ['Arial', 'sans-serif'],
+        size: 11,
+        lineHeight: 1.5,
+      },
+    },
+  };
+}
+
+/**
+ * Create default layout
+ */
+export function createDefaultLayout(): IPdfLayout {
+  return {
+    pageSize: 'A4',
+    orientation: 'portrait',
+    margins: {
+      top: 25,
+      right: 20,
+      bottom: 25,
+      left: 20,
+    },
+    columns: 1,
+    paragraphSpacing: 10,
+    sectionSpacing: 20,
+    firstPageDifferent: false,
+  };
+}
+
+/**
+ * Create default content options
+ */
+export function createDefaultContentOptions(): IPdfContentOptions {
+  return {
+    tableOfContents: {
+      enabled: true,
+      depth: 2,
+      title: 'Table of Contents',
+      pageBreakAfter: true,
+    },
+    signaturePages: {
+      enabled: true,
+      signatureBlockStyle: 'inline',
+      includeWitnessLines: false,
+      includeInitialsOnEachPage: false,
+    },
+    attachments: {
+      includeInline: false,
+      includeSeparately: true,
+      attachmentToc: true,
+    },
+    formatting: {
+      headingNumbering: true,
+      paragraphNumbering: false,
+      preserveMarkdownFormatting: true,
+      convertLinksToFootnotes: false,
+    },
+  };
+}
+
+/**
+ * Create default page numbering
+ */
+export function createDefaultPageNumbering(): IPdfPageNumbering {
+  return {
+    enabled: true,
+    startFrom: 1,
+    format: 'numeric',
+    position: 'footer',
+    alignment: 'center',
+  };
+}
+
+/**
+ * Create default PDF generation config
+ */
+export function createDefaultPdfConfig(title: string): IPdfGenerationConfig {
+  return {
+    useDefaultTemplate: true,
+    branding: createDefaultBranding(),
+    layout: createDefaultLayout(),
+    pageNumbering: createDefaultPageNumbering(),
+    contentOptions: createDefaultContentOptions(),
+    metadata: {
+      title,
+      creator: 'signature.digital',
+      producer: 'signature.digital PDF Generator',
+      keywords: [],
+      creationDate: Date.now(),
+    },
+  };
+}

ts_interfaces/readme.md

@@ -0,0 +1,204 @@
+# @signature.digital/interfaces
+
+Core TypeScript interfaces for the signature.digital contract management system. 📋
+
+This package provides **200+ interfaces and types** covering every aspect of digital contract management – from basic contract structure to eIDAS-compliant signatures, identity verification, and legal compliance.
+
+## Install
+
+```bash
+pnpm add @signature.digital/interfaces
+```
+
+## Usage
+
+```typescript
+import type {
+  IPortableContract,
+  IRole,
+  IInvolvedParty,
+  IParagraph,
+  TContractStatus,
+} from '@signature.digital/interfaces';
+```
+
+## Module Structure
+
+The package is organized into focused modules:
+
+| Module | Description |
+|--------|-------------|
+| `types.ts` | Foundation type aliases (90+ types) |
+| `terms.ts` | Financial, time, and obligation terms |
+| `signature.ts` | Signature data structures and fields |
+| `identity.ts` | Identity verification system |
+| `legal.ts` | TSA timestamps, blockchain anchoring, compliance |
+| `versioning.ts` | Semantic versioning and change tracking |
+| `collaboration.ts` | Comments, suggestions, presence |
+| `lifecycle.ts` | Status workflow, audit logs, retention |
+| `attachments.ts` | Exhibits, schedules, document bundles |
+| `pdf.ts` | PDF generation configuration |
+| `contract.ts` | Main `IPortableContract` interface |
+
+## Type Categories
+
+### 📋 Contract Classification
+
+```typescript
+type TContractCategory = 'employment' | 'service' | 'sales' | 'lease' | 'license' | 'partnership' | 'confidentiality' | 'financial' | 'real_estate' | 'intellectual_property' | 'government' | 'construction' | 'healthcare' | 'insurance' | 'other';
+
+type TContractType = 'employment_full_time' | 'employment_part_time' | 'employment_minijob' | ... | string;
+
+type TContractStatus = 'draft' | 'internal_review' | 'legal_review' | 'negotiation' | 'pending_approval' | 'pending_signature' | 'partially_signed' | 'signed' | 'executed' | 'active' | 'suspended' | 'renewal_pending' | 'expired' | 'terminated' | 'superseded' | 'cancelled' | 'voided';
+```
+
+### ✍️ Signature Types
+
+```typescript
+type TSignatureType = 'drawn' | 'typed' | 'click' | 'digital' | 'qualified' | 'biometric';
+type TSignatureLegalLevel = 'simple' | 'advanced' | 'qualified';
+type TSignatureStatus = 'pending' | 'captured' | 'verified' | 'timestamped' | 'complete' | 'revoked' | 'expired';
+```
+
+### 🪪 Identity Verification
+
+```typescript
+type TIdentityVerificationMethod = 'none' | 'email' | 'sms' | 'knowledge' | 'document_upload' | 'document_nfc' | 'document_ocr' | 'biometric_facial' | 'video_ident' | 'bankid' | 'eid' | 'third_party_idp';
+type TVerificationConfidence = 'none' | 'low' | 'medium' | 'high' | 'verified';
+type TIdentityDocumentType = 'passport' | 'national_id' | 'drivers_license' | 'residence_permit' | 'travel_document' | 'other';
+```
+
+### 💰 Financial Types
+
+```typescript
+type TPaymentFrequency = 'one_time' | 'daily' | 'weekly' | 'bi_weekly' | 'semi_monthly' | 'monthly' | 'bi_monthly' | 'quarterly' | 'semi_annually' | 'annually' | 'on_demand' | 'upon_completion' | 'milestone_based' | 'custom';
+type TPaymentMethod = 'bank_transfer' | 'sepa_direct_debit' | 'credit_card' | 'check' | 'cash' | 'paypal' | 'crypto' | 'escrow' | 'letter_of_credit' | 'other';
+```
+
+### ⏱️ Time & Duration
+
+```typescript
+type TDurationUnit = 'hours' | 'days' | 'weeks' | 'months' | 'years' | 'indefinite';
+type TRenewalType = 'none' | 'manual' | 'auto_renew' | 'evergreen' | 'option_to_renew';
+type TTerminationReason = 'breach_of_contract' | 'mutual_agreement' | 'convenience' | 'non_performance' | 'insolvency' | 'force_majeure' | 'regulatory_change' | 'merger_acquisition' | 'other';
+```
+
+### ⚖️ Legal Compliance
+
+```typescript
+type TTimestampMethod = 'tsa' | 'blockchain' | 'qualified_tsa';
+type TBlockchainNetwork = 'bitcoin' | 'ethereum' | 'polygon' | 'arbitrum' | 'optimism' | 'hyperledger' | 'private';
+type THashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512' | 'Keccak-256';
+type TSignatureAlgorithm = 'RSA-SHA256' | 'RSA-SHA384' | 'RSA-SHA512' | 'ECDSA-P256' | 'ECDSA-P384' | 'Ed25519';
+```
+
+## Key Interfaces
+
+### IPortableContract
+
+The main contract interface that ties everything together:
+
+```typescript
+interface IPortableContract {
+  id: string;
+  title: string;
+  context: string;
+  metadata: IContractMetadata;
+  availableRoles: IRole[];
+  involvedParties: IInvolvedParty[];
+  paragraphs: IParagraph[];
+  variables: IVariable[];
+  signatureFields: ISignatureField[];
+  financialTerms: IFinancialTerms;
+  timeTerms: ITimeTerms;
+  obligationTerms: IObligationTerms;
+  priorContracts: IPriorContractReference[];
+  attachments: IContractAttachment[];
+  versionHistory: IVersionHistory;
+  collaborators: ICollaborator[];
+  commentThreads: ICommentThread[];
+  suggestions: ISuggestion[];
+  lifecycle: IDocumentLifecycle;
+  auditLog: IAuditLog;
+  pdfConfig?: IPdfGenerationConfig;
+  // ... timestamps, organization, integrations
+}
+```
+
+### ISignature
+
+Complete signature with data, metadata, and verification:
+
+```typescript
+interface ISignature {
+  id: string;
+  signatureType: TSignatureType;
+  legalLevel: TSignatureLegalLevel;
+  data: TSignatureData; // Discriminated union
+  metadata: ISignatureMetadata;
+  consents: IConsent[];
+  auditTrail: ISignatureAuditEntry[];
+  status: TSignatureStatus;
+}
+```
+
+### IIdentityVerificationResult
+
+Full identity verification outcome:
+
+```typescript
+interface IIdentityVerificationResult {
+  id: string;
+  status: TIdentityVerificationStatus;
+  confidence: TVerificationConfidence;
+  confidenceScore: number;
+  methodsAttempted: TIdentityVerificationMethod[];
+  verifiedIdentity?: IVerifiedIdentity;
+  documentVerification?: IIdentityDocument;
+  facialVerification?: IFacialVerification;
+  thirdPartyVerification?: IThirdPartyVerification;
+  // ... timestamps, failures, audit trail
+}
+```
+
+## Factory Functions
+
+Each module provides factory functions for creating properly initialized objects:
+
+```typescript
+import {
+  createEmptyContract,
+  createRole,
+  createParagraph,
+  createEmptyFinancialTerms,
+  createInitialVersion,
+  createCommentThread,
+  createDefaultPdfConfig,
+  // ... 30+ factory functions
+} from '@signature.digital/interfaces';
+```
+
+## Dependencies
+
+- `@tsclass/tsclass` – Business entity types (`TContact`, `IAddress`, `IPdf`, etc.)
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](../LICENSE) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

ts_interfaces/signature.ts

@@ -0,0 +1,436 @@
+/**
+ * @file signature.ts
+ * @description Signature data structures and types
+ * Supports drawn, typed, click, digital, qualified, and biometric signatures
+ */
+
+import type {
+  TSignatureType,
+  TSignatureLegalLevel,
+  TSignatureStatus,
+  TSignatureAuditAction,
+  THashAlgorithm,
+  TSignatureAlgorithm,
+} from './types.js';
+
+// ============================================================================
+// SIGNATURE DATA STRUCTURES (Discriminated Union)
+// ============================================================================
+
+/**
+ * Base signature data common to all types
+ */
+export interface ISignatureDataBase {
+  id: string;
+  schemaVersion: '1.0.0';
+  capturedAt: number;
+}
+
+/**
+ * Individual stroke point from signature_pad
+ */
+export interface ISignatureStrokePoint {
+  x: number;
+  y: number;
+  pressure: number;
+  time: number;
+}
+
+/**
+ * Drawn signature data (canvas-based)
+ * Compatible with signature_pad library output
+ */
+export interface ISignatureDataDrawn extends ISignatureDataBase {
+  type: 'drawn';
+  strokeData: ISignatureStrokePoint[][];
+  svg: string;
+  pngBase64?: string;
+  canvasDimensions: {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+  };
+  drawingMetrics?: {
+    totalStrokes: number;
+    totalPoints: number;
+    averageVelocity: number;
+    drawingDurationMs: number;
+  };
+}
+
+/**
+ * Typed signature data
+ */
+export interface ISignatureDataTyped extends ISignatureDataBase {
+  type: 'typed';
+  text: string;
+  fontFamily: string;
+  fontSize: number;
+  svg: string;
+  pngBase64?: string;
+}
+
+/**
+ * Click-to-sign acknowledgment
+ */
+export interface ISignatureDataClick extends ISignatureDataBase {
+  type: 'click';
+  acknowledgmentText: string;
+  acknowledged: boolean;
+  fullNameEntered?: string;
+  jobTitle?: string;
+}
+
+/**
+ * Certificate information for digital signatures
+ */
+export interface ICertificateInfo {
+  certificatePem: string;
+  serialNumber: string;
+  issuer: string;
+  subject: string;
+  validity: {
+    notBefore: number;
+    notAfter: number;
+  };
+  fingerprint: string;
+}
+
+/**
+ * Digital certificate-based signature (X.509/PKI)
+ */
+export interface ISignatureDataDigital extends ISignatureDataBase {
+  type: 'digital';
+  certificate: ICertificateInfo;
+  signatureValue: string;
+  signatureAlgorithm: TSignatureAlgorithm;
+  contentHash: string;
+  hashAlgorithm: THashAlgorithm;
+}
+
+/**
+ * Qualified Trust Service Provider information
+ */
+export interface IQtspInfo {
+  name: string;
+  providerId: string;
+  serviceId: string;
+  country: string;
+}
+
+/**
+ * Signature creation device information
+ */
+export interface ISignatureCreationDevice {
+  type: 'local' | 'remote';
+  deviceId?: string;
+  certification?: string;
+}
+
+/**
+ * Qualified Electronic Signature (eIDAS QES)
+ */
+export interface ISignatureDataQualified extends ISignatureDataBase {
+  type: 'qualified';
+  digitalSignature: Omit<ISignatureDataDigital, 'type' | 'id' | 'schemaVersion' | 'capturedAt'>;
+  qtsp: IQtspInfo;
+  trustedListReference?: string;
+  signatureCreationDevice?: ISignatureCreationDevice;
+}
+
+/**
+ * Biometric signature data (extensible for future)
+ */
+export interface ISignatureDataBiometric extends ISignatureDataBase {
+  type: 'biometric';
+  biometricType: 'fingerprint' | 'facial' | 'voice' | 'iris';
+  templateReference: string;
+  confidenceScore: number;
+  provider: string;
+}
+
+/**
+ * Union type of all signature data types
+ */
+export type TSignatureData =
+  | ISignatureDataDrawn
+  | ISignatureDataTyped
+  | ISignatureDataClick
+  | ISignatureDataDigital
+  | ISignatureDataQualified
+  | ISignatureDataBiometric;
+
+// ============================================================================
+// SIGNATURE METADATA
+// ============================================================================
+
+/**
+ * IP geolocation information
+ */
+export interface IIpGeolocation {
+  country: string;
+  countryCode: string;
+  region?: string;
+  city?: string;
+}
+
+/**
+ * Device fingerprint for fraud detection
+ */
+export interface IDeviceFingerprint {
+  hash: string;
+  components: {
+    screenResolution?: string;
+    timezone?: string;
+    language?: string;
+    platform?: string;
+    colorDepth?: number;
+    touchSupport?: boolean;
+    canvasFingerprint?: string;
+    webglFingerprint?: string;
+  };
+  confidence: number;
+}
+
+/**
+ * Session information
+ */
+export interface ISigningSession {
+  sessionId: string;
+  sessionStarted: number;
+  pageViews: number;
+  documentsViewed: string[];
+}
+
+/**
+ * Comprehensive signature metadata capturing context
+ */
+export interface ISignatureMetadata {
+  timestamps: {
+    clientCaptured: number;
+    serverReceived?: number;
+    blockchainTimestamped?: number;
+    tsaTimestamped?: number;
+  };
+  geolocation?: {
+    latitude: number;
+    longitude: number;
+    accuracy: number;
+    altitude?: number;
+    timestamp: number;
+    source: 'gps' | 'network' | 'ip-based';
+  };
+  network: {
+    ipAddress: string;
+    ipGeolocation?: IIpGeolocation;
+    userAgent: string;
+  };
+  deviceFingerprint?: IDeviceFingerprint;
+  session?: ISigningSession;
+}
+
+// ============================================================================
+// CONSENT AND VERIFICATION
+// ============================================================================
+
+/**
+ * Legal consent record
+ */
+export interface IConsent {
+  type: 'terms_accepted' | 'electronic_signature' | 'data_processing' | 'custom';
+  text: string;
+  accepted: boolean;
+  timestamp?: number;
+}
+
+/**
+ * Signature audit trail entry
+ */
+export interface ISignatureAuditEntry {
+  timestamp: number;
+  action: TSignatureAuditAction;
+  actor: {
+    type: 'user' | 'system' | 'service';
+    id: string;
+    name?: string;
+  };
+  details: Record<string, unknown>;
+  ipAddress?: string;
+}
+
+// ============================================================================
+// COMPLETE SIGNATURE OBJECT
+// ============================================================================
+
+/**
+ * Forward declaration for identity verification (defined in identity.ts)
+ */
+export interface IIdentityVerificationResultRef {
+  id: string;
+  status: string;
+  confidence: string;
+}
+
+/**
+ * Forward declaration for legal compliance proof (defined in legal.ts)
+ */
+export interface ILegalComplianceProofRef {
+  id: string;
+  eidasLevel?: TSignatureLegalLevel;
+}
+
+/**
+ * Complete signature with data, metadata, and verification status
+ */
+export interface ISignature {
+  id: string;
+  schemaVersion: '1.0.0';
+  signatureType: TSignatureType;
+  legalLevel: TSignatureLegalLevel;
+  data: TSignatureData;
+  metadata: ISignatureMetadata;
+  identityVerificationId?: string;
+  legalComplianceProofId?: string;
+  consents: IConsent[];
+  auditTrail: ISignatureAuditEntry[];
+  status: TSignatureStatus;
+}
+
+// ============================================================================
+// SIGNATURE FIELD PLACEMENT
+// ============================================================================
+
+/**
+ * Paragraph-based placement
+ */
+export interface IPlacementParagraph {
+  paragraphId: string;
+  position: 'before' | 'after' | 'inline';
+  inlineOffset?: number;
+}
+
+/**
+ * Page-based placement (PDF coordinates)
+ */
+export interface IPlacementPage {
+  pageNumber: number;
+  coordinates: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
+}
+
+/**
+ * Anchor-based placement
+ */
+export interface IPlacementAnchor {
+  anchorText: string;
+  occurrence: number;
+  offset: {
+    x: number;
+    y: number;
+  };
+  size: {
+    width: number;
+    height: number;
+  };
+}
+
+/**
+ * Signature field placement configuration
+ */
+export interface ISignatureFieldPlacement {
+  type: 'paragraph' | 'page' | 'anchor' | 'append';
+  paragraph?: IPlacementParagraph;
+  page?: IPlacementPage;
+  anchor?: IPlacementAnchor;
+  displayOrder: number;
+}
+
+// ============================================================================
+// SIGNATURE FIELD REQUIREMENTS
+// ============================================================================
+
+import type { TIdentityVerificationMethod, TVerificationConfidence } from './types.js';
+
+/**
+ * Requirements for a signature field
+ */
+export interface ISignatureFieldRequirements {
+  required: boolean;
+  allowedSignatureTypes: TSignatureType[];
+  minimumLegalLevel: TSignatureLegalLevel;
+  identityVerification: {
+    required: boolean;
+    allowedMethods?: TIdentityVerificationMethod[];
+    minimumConfidence?: TVerificationConfidence;
+  };
+  timestamping: {
+    required: boolean;
+    types?: ('tsa' | 'qualified_tsa' | 'blockchain')[];
+  };
+  deadline?: {
+    timestamp?: number;
+    relativeSeconds?: number;
+  };
+  customValidation?: {
+    ruleId: string;
+    params: Record<string, unknown>;
+  }[];
+}
+
+// ============================================================================
+// SIGNATURE DEPENDENCIES
+// ============================================================================
+
+import type { TFieldDependencyType } from './types.js';
+
+/**
+ * Defines dependencies between signature fields
+ */
+export interface ISignatureDependency {
+  type: TFieldDependencyType;
+  dependsOn: string[];
+  timeConstraint?: {
+    minSecondsAfter?: number;
+    maxSecondsAfter?: number;
+  };
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create empty signature metadata
+ */
+export function createEmptySignatureMetadata(): ISignatureMetadata {
+  return {
+    timestamps: {
+      clientCaptured: Date.now(),
+    },
+    network: {
+      ipAddress: '',
+      userAgent: '',
+    },
+  };
+}
+
+/**
+ * Create default signature field requirements
+ */
+export function createDefaultSignatureFieldRequirements(): ISignatureFieldRequirements {
+  return {
+    required: true,
+    allowedSignatureTypes: ['drawn', 'typed', 'click'],
+    minimumLegalLevel: 'simple',
+    identityVerification: {
+      required: false,
+    },
+    timestamping: {
+      required: false,
+    },
+  };
+}

ts_interfaces/terms.ts

@@ -0,0 +1,405 @@
+/**
+ * @file terms.ts
+ * @description Financial, time-based, and obligation terms interfaces
+ * Machine-readable structured terms for contracts
+ */
+
+import * as plugins from './plugins.js';
+import type {
+  TPaymentFrequency,
+  TPaymentMethod,
+  TPaymentStatus,
+  TInterestType,
+  TPenaltyType,
+  TDurationUnit,
+  TRenewalType,
+  TNoticeEffectivePoint,
+  TNoticeForm,
+  TMilestoneStatus,
+  TObligationType,
+  TObligationStatus,
+  TObligationPriority,
+  TDeliverableStatus,
+  TInsuranceType,
+} from './types.js';
+
+// ============================================================================
+// FINANCIAL TERMS INTERFACES
+// ============================================================================
+
+/**
+ * Monetary amount with currency
+ */
+export interface IMonetaryAmount {
+  amount: number;
+  currency: string;
+  includesTax: boolean;
+  taxRate?: number;
+}
+
+/**
+ * Payment schedule entry
+ */
+export interface IPaymentScheduleEntry {
+  paymentId: string;
+  description: string;
+  amount: IMonetaryAmount;
+  dueDate: number;
+  frequency: TPaymentFrequency;
+  numberOfPayments?: number;
+  isFinalPayment: boolean;
+  milestoneId?: string;
+  status: TPaymentStatus;
+  paidDate?: number;
+}
+
+/**
+ * Interest rate configuration
+ */
+export interface IInterestRate {
+  type: TInterestType;
+  baseRate: number;
+  spread?: number;
+  referenceRate?: string;
+  compoundingFrequency?: TPaymentFrequency;
+  maxRate?: number;
+  minRate?: number;
+}
+
+/**
+ * Penalty configuration
+ */
+export interface IPenalty {
+  id: string;
+  type: TPenaltyType;
+  description: string;
+  fixedAmount?: IMonetaryAmount;
+  percentage?: number;
+  percentageOf?: 'contract_value' | 'outstanding_amount' | 'monthly_value' | 'custom';
+  interestRate?: IInterestRate;
+  gracePeriod?: IDuration;
+  maximumPenalty?: IMonetaryAmount;
+}
+
+/**
+ * Billing rate for time-based contracts
+ */
+export interface IBillingRate {
+  id: string;
+  description: string;
+  type: 'hourly' | 'daily' | 'weekly' | 'monthly' | 'per_unit' | 'flat';
+  rate: IMonetaryAmount;
+  roleId?: string;
+  minimumUnit?: number;
+}
+
+/**
+ * Price adjustment provisions
+ */
+export interface IPriceAdjustment {
+  type: 'fixed_increase' | 'cpi_linked' | 'negotiated' | 'formula_based';
+  frequency: TPaymentFrequency;
+  fixedIncreasePercentage?: number;
+  linkedIndex?: string;
+  formula?: string;
+  maxIncrease?: number;
+  noticePeriod?: IDuration;
+}
+
+/**
+ * Comprehensive financial terms
+ */
+export interface IFinancialTerms {
+  totalValue?: IMonetaryAmount;
+  paymentSchedule: IPaymentScheduleEntry[];
+  paymentMethods: TPaymentMethod[];
+  paymentTerms?: string;
+  paymentDueDays?: number;
+  deposit?: IMonetaryAmount;
+  depositRefundable: boolean;
+  retainer?: IMonetaryAmount;
+  billingRates: IBillingRate[];
+  interestRates: {
+    latePayment?: IInterestRate;
+    financing?: IInterestRate;
+  };
+  penalties: IPenalty[];
+  priceAdjustment?: IPriceAdjustment;
+  paymentAccount?: plugins.tsclass.finance.ISepaConnection;
+  notes?: string;
+}
+
+// ============================================================================
+// TIME-BASED TERMS INTERFACES
+// ============================================================================
+
+/**
+ * Duration specification
+ */
+export interface IDuration {
+  value: number;
+  unit: TDurationUnit;
+}
+
+/**
+ * Milestone definition
+ */
+export interface IMilestone {
+  milestoneId: string;
+  name: string;
+  description: string;
+  targetDate?: number;
+  completedDate?: number;
+  status: TMilestoneStatus;
+  dependsOn: string[];
+  paymentId?: string;
+  deliverables: string[];
+  acceptanceCriteria: string[];
+}
+
+/**
+ * Deadline definition
+ */
+export interface IDeadline {
+  id: string;
+  name: string;
+  description?: string;
+  date: number;
+  type: 'hard' | 'soft';
+  penalty?: IPenalty;
+  reminderDays: number[];
+}
+
+/**
+ * Key date for tracking
+ */
+export interface IKeyDate {
+  id: string;
+  name: string;
+  date: number;
+  type: 'anniversary' | 'review' | 'renewal_deadline' | 'price_adjustment' | 'custom';
+  notes?: string;
+}
+
+/**
+ * Notice period configuration
+ */
+export interface INoticePeriod {
+  duration: IDuration;
+  effectivePoint: TNoticeEffectivePoint;
+  form: TNoticeForm;
+}
+
+/**
+ * Renewal terms
+ */
+export interface IRenewalTerms {
+  type: TRenewalType;
+  renewalPeriod?: IDuration;
+  maxRenewals?: number;
+  currentRenewalCount: number;
+  nonRenewalNotice?: INoticePeriod;
+  renewalPriceAdjustment?: IPriceAdjustment;
+  conditions: string[];
+}
+
+/**
+ * Termination terms
+ */
+export interface ITerminationTerms {
+  noticePeriod: INoticePeriod;
+  immediateTerminationGrounds: string[];
+  terminationFee?: IMonetaryAmount;
+  postTerminationObligations: string[];
+  survivalClauses: string[];
+}
+
+/**
+ * Comprehensive time-based terms
+ */
+export interface ITimeTerms {
+  effectiveDate?: number;
+  executionDate?: number;
+  expirationDate?: number;
+  duration?: IDuration;
+  isIndefinite: boolean;
+  commencementConditions: string[];
+  milestones: IMilestone[];
+  deadlines: IDeadline[];
+  noticePeriods: {
+    termination?: INoticePeriod;
+    renewal?: INoticePeriod;
+    amendment?: INoticePeriod;
+    priceChange?: INoticePeriod;
+  };
+  renewal?: IRenewalTerms;
+  termination?: ITerminationTerms;
+  keyDates: IKeyDate[];
+}
+
+// ============================================================================
+// OBLIGATION TERMS INTERFACES
+// ============================================================================
+
+/**
+ * Deliverable definition
+ */
+export interface IDeliverable {
+  deliverableId: string;
+  name: string;
+  description: string;
+  responsiblePartyId: string;
+  receivingPartyId?: string;
+  dueDate?: number;
+  milestoneId?: string;
+  acceptanceCriteria: string[];
+  quantity?: number;
+  unit?: string;
+  qualityStandards: string[];
+  deliveryMethod?: string;
+  status: TDeliverableStatus;
+}
+
+/**
+ * Service level definition
+ */
+export interface IServiceLevel {
+  slId: string;
+  metric: string;
+  description?: string;
+  target: number;
+  unit: string;
+  measurementPeriod: TPaymentFrequency;
+  minimumLevel?: number;
+  penalty?: IPenalty;
+  remedyCredit?: IMonetaryAmount;
+  exclusions: string[];
+  reporting?: {
+    frequency: TPaymentFrequency;
+    format?: string;
+  };
+}
+
+/**
+ * Quantity specification
+ */
+export interface IQuantitySpec {
+  minimum?: number;
+  maximum?: number;
+  target?: number;
+  unit: string;
+  period?: TPaymentFrequency;
+}
+
+/**
+ * General obligation
+ */
+export interface IObligation {
+  obligationId: string;
+  type: TObligationType;
+  description: string;
+  obligorPartyId: string;
+  beneficiaryPartyId?: string;
+  dueDate?: number;
+  recurring: boolean;
+  frequency?: TPaymentFrequency;
+  duration?: IDuration;
+  priority: TObligationPriority;
+  clauseId?: string;
+  status: TObligationStatus;
+}
+
+/**
+ * Warranty definition
+ */
+export interface IWarranty {
+  id: string;
+  description: string;
+  duration?: IDuration;
+  scope?: string;
+  limitations: string[];
+  remedies: string[];
+}
+
+/**
+ * Representation definition
+ */
+export interface IRepresentation {
+  id: string;
+  partyId: string;
+  statement: string;
+  asOfDate: 'signing' | 'effective_date' | 'ongoing';
+}
+
+/**
+ * Insurance requirement
+ */
+export interface IInsuranceRequirement {
+  id: string;
+  type: TInsuranceType;
+  minimumCoverage: IMonetaryAmount;
+  description?: string;
+  requireCertificate: boolean;
+}
+
+/**
+ * Comprehensive obligation terms
+ */
+export interface IObligationTerms {
+  deliverables: IDeliverable[];
+  serviceLevels: IServiceLevel[];
+  quantities: IQuantitySpec[];
+  obligations: IObligation[];
+  warranties: IWarranty[];
+  representations: IRepresentation[];
+  insuranceRequirements: IInsuranceRequirement[];
+  complianceRequirements: string[];
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS FOR EMPTY STRUCTURES
+// ============================================================================
+
+/**
+ * Create empty financial terms
+ */
+export function createEmptyFinancialTerms(): IFinancialTerms {
+  return {
+    paymentSchedule: [],
+    paymentMethods: [],
+    depositRefundable: false,
+    billingRates: [],
+    interestRates: {},
+    penalties: [],
+  };
+}
+
+/**
+ * Create empty time terms
+ */
+export function createEmptyTimeTerms(): ITimeTerms {
+  return {
+    isIndefinite: false,
+    commencementConditions: [],
+    milestones: [],
+    deadlines: [],
+    noticePeriods: {},
+    keyDates: [],
+  };
+}
+
+/**
+ * Create empty obligation terms
+ */
+export function createEmptyObligationTerms(): IObligationTerms {
+  return {
+    deliverables: [],
+    serviceLevels: [],
+    quantities: [],
+    obligations: [],
+    warranties: [],
+    representations: [],
+    insuranceRequirements: [],
+    complianceRequirements: [],
+  };
+}

ts_interfaces/tspublish.json

@@ -0,0 +1,8 @@
+{
+  "name": "@signature.digital/interfaces",
+  "order": 1,
+  "registries": ["useBase"],
+  "dependencies": [
+    "@tsclass/tsclass"
+  ]
+}

ts_interfaces/types.ts

@@ -0,0 +1,912 @@
+/**
+ * @file types.ts
+ * @description Foundation type aliases for signature.digital contract system
+ * All type aliases use T prefix as per project conventions
+ */
+
+// ============================================================================
+// CONTRACT CLASSIFICATION
+// ============================================================================
+
+/**
+ * Broad categories of contracts for classification and routing
+ */
+export type TContractCategory =
+  | 'employment'
+  | 'service'
+  | 'sales'
+  | 'lease'
+  | 'license'
+  | 'partnership'
+  | 'confidentiality'
+  | 'financial'
+  | 'real_estate'
+  | 'intellectual_property'
+  | 'government'
+  | 'construction'
+  | 'healthcare'
+  | 'insurance'
+  | 'other';
+
+/**
+ * Specific contract types within categories - extensible via string literal union
+ */
+export type TContractType =
+  // Employment
+  | 'employment_full_time'
+  | 'employment_part_time'
+  | 'employment_minijob'
+  | 'employment_internship'
+  | 'employment_freelance'
+  | 'employment_consulting'
+  | 'employment_executive'
+  | 'employment_temporary'
+  | 'employment_apprenticeship'
+  // Service
+  | 'service_agreement'
+  | 'service_level_agreement'
+  | 'master_service_agreement'
+  | 'maintenance_agreement'
+  | 'support_agreement'
+  | 'managed_services'
+  // Sales
+  | 'sales_agreement'
+  | 'purchase_order'
+  | 'distribution_agreement'
+  | 'supply_agreement'
+  | 'consignment_agreement'
+  // Lease/Rental
+  | 'lease_residential'
+  | 'lease_commercial'
+  | 'lease_equipment'
+  | 'lease_vehicle'
+  | 'sublease'
+  // License
+  | 'software_license'
+  | 'patent_license'
+  | 'trademark_license'
+  | 'franchise_agreement'
+  | 'content_license'
+  // Partnership
+  | 'partnership_general'
+  | 'partnership_limited'
+  | 'joint_venture'
+  | 'strategic_alliance'
+  | 'consortium_agreement'
+  // Confidentiality
+  | 'nda_unilateral'
+  | 'nda_bilateral'
+  | 'nda_multilateral'
+  | 'non_compete'
+  | 'non_solicitation'
+  // Financial
+  | 'loan_agreement'
+  | 'credit_facility'
+  | 'guarantee'
+  | 'security_agreement'
+  | 'investment_agreement'
+  | 'shareholder_agreement'
+  // Other
+  | 'settlement_agreement'
+  | 'release_waiver'
+  | 'power_of_attorney'
+  | 'memorandum_of_understanding'
+  | 'letter_of_intent'
+  | string; // Allow custom types
+
+// ============================================================================
+// CONTRACT LIFECYCLE STATUS
+// ============================================================================
+
+/**
+ * Contract lifecycle status - complete workflow states
+ */
+export type TContractStatus =
+  // Draft phase
+  | 'draft'
+  | 'internal_review'
+  | 'legal_review'
+  // Negotiation phase
+  | 'negotiation'
+  | 'pending_approval'
+  // Signature phase
+  | 'pending_signature'
+  | 'partially_signed'
+  | 'signed'
+  // Active phase
+  | 'executed'
+  | 'active'
+  | 'suspended'
+  | 'renewal_pending'
+  // End phase
+  | 'expired'
+  | 'terminated'
+  | 'superseded'
+  | 'cancelled'
+  | 'voided';
+
+// ============================================================================
+// PARTY AND ROLE TYPES
+// ============================================================================
+
+/**
+ * Role types in contract signing workflow
+ */
+export type TPartyRole =
+  | 'signer'
+  | 'witness'
+  | 'notary'
+  | 'cc'
+  | 'approver'
+  | 'guarantor'
+  | 'beneficiary';
+
+/**
+ * Signing dependency types
+ */
+export type TSigningDependency =
+  | 'none'
+  | 'sequential'
+  | 'parallel'
+  | 'after_specific';
+
+/**
+ * Legal capacity when signing
+ */
+export type TLegalCapacity =
+  | 'individual'
+  | 'representative'
+  | 'attorney'
+  | 'guardian';
+
+// ============================================================================
+// SIGNATURE TYPES
+// ============================================================================
+
+/**
+ * All supported signature input methods
+ */
+export type TSignatureType =
+  | 'drawn'
+  | 'typed'
+  | 'click'
+  | 'digital'
+  | 'qualified'
+  | 'biometric';
+
+/**
+ * Signature legal level based on eIDAS regulation
+ */
+export type TSignatureLegalLevel =
+  | 'simple'
+  | 'advanced'
+  | 'qualified';
+
+/**
+ * Signature lifecycle status
+ */
+export type TSignatureStatus =
+  | 'pending'
+  | 'captured'
+  | 'verified'
+  | 'timestamped'
+  | 'complete'
+  | 'revoked'
+  | 'expired';
+
+// ============================================================================
+// IDENTITY VERIFICATION TYPES
+// ============================================================================
+
+/**
+ * Supported identity verification methods
+ */
+export type TIdentityVerificationMethod =
+  | 'none'
+  | 'email'
+  | 'sms'
+  | 'knowledge'
+  | 'document_upload'
+  | 'document_nfc'
+  | 'document_ocr'
+  | 'biometric_facial'
+  | 'video_ident'
+  | 'bankid'
+  | 'eid'
+  | 'third_party_idp';
+
+/**
+ * Verification confidence levels
+ */
+export type TVerificationConfidence =
+  | 'none'
+  | 'low'
+  | 'medium'
+  | 'high'
+  | 'verified';
+
+/**
+ * Identity verification status
+ */
+export type TIdentityVerificationStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'manual_review'
+  | 'verified'
+  | 'failed'
+  | 'expired'
+  | 'cancelled';
+
+/**
+ * Identity document types
+ */
+export type TIdentityDocumentType =
+  | 'passport'
+  | 'national_id'
+  | 'drivers_license'
+  | 'residence_permit'
+  | 'travel_document'
+  | 'other';
+
+// ============================================================================
+// FINANCIAL TYPES
+// ============================================================================
+
+/**
+ * Payment frequency for recurring payments
+ */
+export type TPaymentFrequency =
+  | 'one_time'
+  | 'daily'
+  | 'weekly'
+  | 'bi_weekly'
+  | 'semi_monthly'
+  | 'monthly'
+  | 'bi_monthly'
+  | 'quarterly'
+  | 'semi_annually'
+  | 'annually'
+  | 'on_demand'
+  | 'upon_completion'
+  | 'milestone_based'
+  | 'custom';
+
+/**
+ * Payment method types
+ */
+export type TPaymentMethod =
+  | 'bank_transfer'
+  | 'sepa_direct_debit'
+  | 'credit_card'
+  | 'check'
+  | 'cash'
+  | 'paypal'
+  | 'crypto'
+  | 'escrow'
+  | 'letter_of_credit'
+  | 'other';
+
+/**
+ * Interest calculation methods
+ */
+export type TInterestType =
+  | 'simple'
+  | 'compound'
+  | 'fixed'
+  | 'variable'
+  | 'prime_plus'
+  | 'reference_plus'
+  | 'none';
+
+/**
+ * Payment status
+ */
+export type TPaymentStatus =
+  | 'pending'
+  | 'invoiced'
+  | 'paid'
+  | 'overdue'
+  | 'waived'
+  | 'refunded';
+
+/**
+ * Penalty types
+ */
+export type TPenaltyType =
+  | 'late_payment'
+  | 'early_termination'
+  | 'breach'
+  | 'non_performance'
+  | 'custom';
+
+// ============================================================================
+// TIME AND DURATION TYPES
+// ============================================================================
+
+/**
+ * Duration unit for time periods
+ */
+export type TDurationUnit =
+  | 'hours'
+  | 'days'
+  | 'weeks'
+  | 'months'
+  | 'years'
+  | 'indefinite';
+
+/**
+ * Renewal types
+ */
+export type TRenewalType =
+  | 'none'
+  | 'manual'
+  | 'auto_renew'
+  | 'evergreen'
+  | 'option_to_renew';
+
+/**
+ * Notice effective point
+ */
+export type TNoticeEffectivePoint =
+  | 'immediate'
+  | 'end_of_week'
+  | 'end_of_month'
+  | 'end_of_quarter'
+  | 'end_of_year'
+  | 'anytime';
+
+/**
+ * Notice form requirements
+ */
+export type TNoticeForm =
+  | 'written'
+  | 'email'
+  | 'registered_mail'
+  | 'any';
+
+/**
+ * Milestone status
+ */
+export type TMilestoneStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'completed'
+  | 'delayed'
+  | 'cancelled';
+
+/**
+ * Termination reason taxonomy
+ */
+export type TTerminationReason =
+  | 'breach_of_contract'
+  | 'mutual_agreement'
+  | 'convenience'
+  | 'non_performance'
+  | 'insolvency'
+  | 'force_majeure'
+  | 'regulatory_change'
+  | 'merger_acquisition'
+  | 'other';
+
+// ============================================================================
+// CONTENT AND SECTION TYPES
+// ============================================================================
+
+/**
+ * Section types for contract structure
+ */
+export type TSectionType =
+  | 'preamble'
+  | 'definitions'
+  | 'clause'
+  | 'subclause'
+  | 'schedule'
+  | 'exhibit'
+  | 'annex'
+  | 'amendment'
+  | 'signature_block'
+  | 'witness_block'
+  | 'acknowledgment'
+  | 'recital'
+  | 'custom';
+
+/**
+ * Variable/placeholder types for dynamic content
+ */
+export type TVariableType =
+  | 'text'
+  | 'number'
+  | 'currency'
+  | 'date'
+  | 'duration'
+  | 'percentage'
+  | 'party_name'
+  | 'party_address'
+  | 'party_contact'
+  | 'calculated'
+  | 'selection'
+  | 'custom';
+
+/**
+ * Condition operators for conditional sections
+ */
+export type TConditionOperator =
+  | 'equals'
+  | 'not_equals'
+  | 'contains'
+  | 'not_contains'
+  | 'greater_than'
+  | 'less_than'
+  | 'in_list'
+  | 'not_in_list'
+  | 'is_empty'
+  | 'is_not_empty'
+  | 'party_has_role'
+  | 'contract_type_is';
+
+/**
+ * Logical combination for conditions
+ */
+export type TConditionCombine = 'and' | 'or';
+
+// ============================================================================
+// VERSIONING TYPES
+// ============================================================================
+
+/**
+ * Version type
+ */
+export type TVersionType = 'draft' | 'final' | 'amendment';
+
+/**
+ * Change operation types for diff tracking
+ */
+export type TChangeOperation =
+  | 'insert'
+  | 'delete'
+  | 'modify'
+  | 'move'
+  | 'format'
+  | 'merge';
+
+/**
+ * Branch status
+ */
+export type TBranchStatus = 'active' | 'merged' | 'abandoned';
+
+// ============================================================================
+// COLLABORATION TYPES
+// ============================================================================
+
+/**
+ * User presence status
+ */
+export type TPresenceStatus =
+  | 'viewing'
+  | 'editing'
+  | 'commenting'
+  | 'idle'
+  | 'offline';
+
+/**
+ * Comment thread status
+ */
+export type TCommentThreadStatus = 'open' | 'resolved' | 'archived';
+
+/**
+ * Suggestion status
+ */
+export type TSuggestionStatus = 'pending' | 'accepted' | 'rejected' | 'superseded';
+
+/**
+ * Suggestion change type
+ */
+export type TSuggestionChangeType = 'insert' | 'delete' | 'replace' | 'format';
+
+/**
+ * Conflict resolution strategy
+ */
+export type TConflictResolutionStrategy = 'accept_first' | 'accept_last' | 'manual_merge';
+
+/**
+ * Editing mode
+ */
+export type TEditingMode = 'collaborative' | 'suggestion_only' | 'view_only';
+
+/**
+ * Permission level for collaboration
+ */
+export type TCollaborationPermission =
+  | 'owner'
+  | 'admin'
+  | 'editor'
+  | 'suggester'
+  | 'commenter'
+  | 'viewer';
+
+// ============================================================================
+// AUDIT TYPES
+// ============================================================================
+
+/**
+ * Action categories for filtering and reporting
+ */
+export type TActionCategory =
+  // Document lifecycle
+  | 'create'
+  | 'view'
+  | 'edit'
+  | 'status_change'
+  | 'version_create'
+  | 'version_rollback'
+  // Collaboration
+  | 'share'
+  | 'permission_change'
+  | 'comment'
+  | 'suggestion'
+  // Signature
+  | 'signature_request'
+  | 'signature_given'
+  | 'signature_declined'
+  | 'signature_revoked'
+  // Export/Import
+  | 'export'
+  | 'print'
+  | 'download'
+  // Administrative
+  | 'archive'
+  | 'restore'
+  | 'delete'
+  | 'retention_policy_applied';
+
+/**
+ * Action severity levels
+ */
+export type TActionSeverity = 'info' | 'warning' | 'critical';
+
+/**
+ * Signature audit action types
+ */
+export type TSignatureAuditAction =
+  | 'signature_requested'
+  | 'document_viewed'
+  | 'signature_captured'
+  | 'identity_verification_started'
+  | 'identity_verification_completed'
+  | 'identity_verification_failed'
+  | 'timestamp_requested'
+  | 'timestamp_received'
+  | 'signature_validated'
+  | 'signature_revoked'
+  | 'certificate_expired';
+
+/**
+ * Compliance action types
+ */
+export type TComplianceAction =
+  | 'proof_created'
+  | 'tsa_timestamp_requested'
+  | 'tsa_timestamp_received'
+  | 'blockchain_anchor_requested'
+  | 'blockchain_anchor_confirmed'
+  | 'validation_performed'
+  | 'ltv_data_collected'
+  | 'archive_timestamp_added';
+
+// ============================================================================
+// ATTACHMENT TYPES
+// ============================================================================
+
+/**
+ * Attachment type classification
+ */
+export type TAttachmentType =
+  | 'exhibit'
+  | 'schedule'
+  | 'appendix'
+  | 'amendment'
+  | 'side_letter'
+  | 'certificate'
+  | 'evidence';
+
+/**
+ * Attachment category for organization
+ */
+export type TAttachmentCategory =
+  // Legal documents
+  | 'legal_entity_docs'
+  | 'authorization'
+  | 'insurance'
+  | 'compliance'
+  // Identity documents
+  | 'identity'
+  | 'address_proof'
+  // Technical documents
+  | 'specifications'
+  | 'diagrams'
+  | 'data_schemas'
+  // Financial documents
+  | 'financial_statements'
+  | 'pricing'
+  | 'payment_terms'
+  // Other
+  | 'correspondence'
+  | 'other';
+
+/**
+ * Prior contract relationship types
+ */
+export type TPriorContractRelationship =
+  | 'supersedes'
+  | 'amends'
+  | 'extends'
+  | 'references'
+  | 'depends_on'
+  | 'conflicts_with';
+
+/**
+ * Confidentiality levels
+ */
+export type TConfidentialityLevel =
+  | 'public'
+  | 'internal'
+  | 'confidential'
+  | 'restricted';
+
+// ============================================================================
+// LEGAL COMPLIANCE TYPES
+// ============================================================================
+
+/**
+ * Timestamping methods
+ */
+export type TTimestampMethod =
+  | 'tsa'
+  | 'blockchain'
+  | 'qualified_tsa';
+
+/**
+ * Supported blockchain networks for timestamping
+ */
+export type TBlockchainNetwork =
+  | 'bitcoin'
+  | 'ethereum'
+  | 'polygon'
+  | 'arbitrum'
+  | 'optimism'
+  | 'hyperledger'
+  | 'private';
+
+/**
+ * Hash algorithms
+ */
+export type THashAlgorithm =
+  | 'SHA-256'
+  | 'SHA-384'
+  | 'SHA-512'
+  | 'Keccak-256';
+
+/**
+ * Signature algorithm types
+ */
+export type TSignatureAlgorithm =
+  | 'RSA-SHA256'
+  | 'RSA-SHA384'
+  | 'RSA-SHA512'
+  | 'ECDSA-P256'
+  | 'ECDSA-P384'
+  | 'Ed25519';
+
+/**
+ * Qualification status for eIDAS
+ */
+export type TQualificationStatus = 'qualified' | 'withdrawn' | 'unknown';
+
+/**
+ * Validation status
+ */
+export type TValidationStatus = 'valid' | 'invalid' | 'indeterminate' | 'expired';
+
+// ============================================================================
+// PDF GENERATION TYPES
+// ============================================================================
+
+/**
+ * Page size presets
+ */
+export type TPageSize = 'A4' | 'Letter' | 'Legal' | 'custom';
+
+/**
+ * Page orientation
+ */
+export type TPageOrientation = 'portrait' | 'landscape';
+
+/**
+ * Header/footer content types
+ */
+export type THeaderFooterContentType =
+  | 'text'
+  | 'image'
+  | 'page_number'
+  | 'date'
+  | 'custom';
+
+/**
+ * Page number format
+ */
+export type TPageNumberFormat = 'numeric' | 'roman' | 'alpha';
+
+/**
+ * PDF encryption algorithm
+ */
+export type TPdfEncryptionAlgorithm = 'AES-128' | 'AES-256';
+
+/**
+ * PDF printing permission level
+ */
+export type TPdfPrintingPermission = 'none' | 'low_resolution' | 'high_resolution';
+
+/**
+ * PDF generation job status
+ */
+export type TPdfJobStatus = 'queued' | 'processing' | 'completed' | 'failed';
+
+// ============================================================================
+// OBLIGATION TYPES
+// ============================================================================
+
+/**
+ * Obligation types
+ */
+export type TObligationType =
+  | 'performance'
+  | 'payment'
+  | 'delivery'
+  | 'confidentiality'
+  | 'compliance'
+  | 'reporting'
+  | 'insurance'
+  | 'indemnification'
+  | 'custom';
+
+/**
+ * Obligation status
+ */
+export type TObligationStatus =
+  | 'pending'
+  | 'active'
+  | 'completed'
+  | 'breached'
+  | 'waived';
+
+/**
+ * Obligation priority
+ */
+export type TObligationPriority = 'critical' | 'high' | 'medium' | 'low';
+
+/**
+ * Deliverable status
+ */
+export type TDeliverableStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'delivered'
+  | 'accepted'
+  | 'rejected'
+  | 'revised';
+
+/**
+ * Insurance requirement types
+ */
+export type TInsuranceType =
+  | 'general_liability'
+  | 'professional_liability'
+  | 'workers_comp'
+  | 'property'
+  | 'auto'
+  | 'cyber'
+  | 'other';
+
+// ============================================================================
+// WORKFLOW TYPES
+// ============================================================================
+
+/**
+ * Workflow types for signing
+ */
+export type TWorkflowType =
+  | 'sequential'
+  | 'parallel'
+  | 'hybrid'
+  | 'custom';
+
+/**
+ * Workflow status
+ */
+export type TWorkflowStatus =
+  | 'draft'
+  | 'active'
+  | 'completed'
+  | 'expired'
+  | 'cancelled'
+  | 'voided';
+
+/**
+ * Workflow events
+ */
+export type TWorkflowEvent =
+  | 'workflow_started'
+  | 'signature_completed'
+  | 'signature_declined'
+  | 'workflow_completed'
+  | 'deadline_approaching'
+  | 'deadline_expired'
+  | 'all_signatures_complete';
+
+// ============================================================================
+// SIGNATURE FIELD TYPES
+// ============================================================================
+
+/**
+ * Signature field status
+ */
+export type TSignatureFieldStatus =
+  | 'pending'
+  | 'ready'
+  | 'in_progress'
+  | 'completed'
+  | 'declined'
+  | 'expired'
+  | 'voided';
+
+/**
+ * Signature field placement types
+ */
+export type TPlacementType =
+  | 'paragraph'
+  | 'page'
+  | 'anchor'
+  | 'append';
+
+/**
+ * Signing dependency types for fields
+ */
+export type TFieldDependencyType =
+  | 'sequential'
+  | 'parallel'
+  | 'any'
+  | 'witness';
+
+/**
+ * Invitation status
+ */
+export type TInvitationStatus =
+  | 'not_sent'
+  | 'sent'
+  | 'delivered'
+  | 'opened'
+  | 'bounced';
+
+// ============================================================================
+// LEGAL REFERENCE TYPES
+// ============================================================================
+
+/**
+ * Legal reference types
+ */
+export type TLegalReferenceType =
+  | 'statute'
+  | 'regulation'
+  | 'case_law'
+  | 'internal_clause'
+  | 'standard'
+  | 'definition';
+
+/**
+ * Dispute resolution methods
+ */
+export type TDisputeResolution =
+  | 'litigation'
+  | 'arbitration'
+  | 'mediation'
+  | 'negotiation';

ts_interfaces/versioning.ts

@@ -0,0 +1,268 @@
+/**
+ * @file versioning.ts
+ * @description Version management interfaces
+ * Semantic versioning, change tracking, branches, and diff comparison
+ */
+
+import type {
+  TVersionType,
+  TChangeOperation,
+  TBranchStatus,
+} from './types.js';
+
+// ============================================================================
+// SEMANTIC VERSION
+// ============================================================================
+
+/**
+ * Semantic version following major.minor.patch pattern
+ * For contracts: major = substantial changes, minor = clause additions, patch = wording fixes
+ */
+export interface ISemanticVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  label?: 'alpha' | 'beta' | 'rc' | 'final';
+}
+
+/**
+ * Version string type
+ */
+export type TVersionString = `${number}.${number}.${number}` | `${number}.${number}.${number}-${string}`;
+
+// ============================================================================
+// VERSION CHANGES
+// ============================================================================
+
+/**
+ * Represents a single atomic change within a version
+ */
+export interface IVersionChange {
+  id: string;
+  operation: TChangeOperation;
+  targetPath: string;
+  targetParagraphId?: string;
+  previousValue?: string | object;
+  newValue?: string | object;
+  characterRange?: {
+    start: number;
+    end: number;
+  };
+  timestamp: number;
+  userId: string;
+  userDisplayName?: string;
+  changeReason?: string;
+}
+
+// ============================================================================
+// AMENDMENT
+// ============================================================================
+
+/**
+ * Amendment-specific information
+ */
+export interface IAmendmentDetails {
+  amendmentNumber: number;
+  amendmentType: 'modification' | 'addendum' | 'rider' | 'waiver' | 'extension';
+  effectiveDate: number;
+  supersedes: string[];
+  requiresResigning: boolean;
+  affectedSections: string[];
+}
+
+// ============================================================================
+// VERSION
+// ============================================================================
+
+/**
+ * A complete version snapshot
+ */
+export interface IVersion {
+  id: string;
+  version: ISemanticVersion;
+  versionString: TVersionString;
+  type: TVersionType;
+  createdAt: number;
+  createdBy: string;
+  createdByDisplayName?: string;
+  previousVersionId?: string;
+  changes: IVersionChange[];
+  contentHash: string;
+  parentHash?: string;
+  title?: string;
+  description?: string;
+  tags: string[];
+  isAmendment: boolean;
+  amendmentDetails?: IAmendmentDetails;
+}
+
+// ============================================================================
+// VERSION BRANCH
+// ============================================================================
+
+/**
+ * Branch for parallel version development
+ */
+export interface IVersionBranch {
+  id: string;
+  name: string;
+  description?: string;
+  createdAt: number;
+  createdBy: string;
+  baseVersionId: string;
+  headVersionId: string;
+  status: TBranchStatus;
+  mergedIntoVersionId?: string;
+}
+
+// ============================================================================
+// VERSION HISTORY
+// ============================================================================
+
+/**
+ * Complete version history for a contract
+ */
+export interface IVersionHistory {
+  contractId: string;
+  currentVersionId: string;
+  currentVersion: ISemanticVersion;
+  versions: IVersion[];
+  branches: IVersionBranch[];
+  mainBranchId: string;
+  publishedVersions: string[];
+  amendmentVersions: string[];
+}
+
+// ============================================================================
+// VERSION DIFF
+// ============================================================================
+
+/**
+ * Diff summary statistics
+ */
+export interface IDiffSummary {
+  insertions: number;
+  deletions: number;
+  modifications: number;
+  paragraphsAffected: string[];
+}
+
+/**
+ * Version comparison result
+ */
+export interface IVersionDiff {
+  fromVersionId: string;
+  toVersionId: string;
+  fromVersion: ISemanticVersion;
+  toVersion: ISemanticVersion;
+  changes: IVersionChange[];
+  summary: IDiffSummary;
+}
+
+// ============================================================================
+// ROLLBACK
+// ============================================================================
+
+/**
+ * Rollback request
+ */
+export interface IRollbackRequest {
+  targetVersionId: string;
+  reason: string;
+  requestedBy: string;
+  requestedAt: number;
+  createNewVersion: boolean;
+}
+
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+
+/**
+ * Create initial version
+ */
+export function createInitialVersion(userId: string, userDisplayName?: string): IVersion {
+  const now = Date.now();
+  return {
+    id: crypto.randomUUID(),
+    version: { major: 0, minor: 1, patch: 0 },
+    versionString: '0.1.0',
+    type: 'draft',
+    createdAt: now,
+    createdBy: userId,
+    createdByDisplayName: userDisplayName,
+    changes: [],
+    contentHash: '',
+    tags: [],
+    isAmendment: false,
+  };
+}
+
+/**
+ * Create empty version history
+ */
+export function createEmptyVersionHistory(contractId: string, initialVersion: IVersion): IVersionHistory {
+  const mainBranchId = crypto.randomUUID();
+  return {
+    contractId,
+    currentVersionId: initialVersion.id,
+    currentVersion: initialVersion.version,
+    versions: [initialVersion],
+    branches: [
+      {
+        id: mainBranchId,
+        name: 'main',
+        createdAt: initialVersion.createdAt,
+        createdBy: initialVersion.createdBy,
+        baseVersionId: initialVersion.id,
+        headVersionId: initialVersion.id,
+        status: 'active',
+      },
+    ],
+    mainBranchId,
+    publishedVersions: [],
+    amendmentVersions: [],
+  };
+}
+
+/**
+ * Increment semantic version
+ */
+export function incrementVersion(
+  current: ISemanticVersion,
+  incrementType: 'major' | 'minor' | 'patch'
+): ISemanticVersion {
+  switch (incrementType) {
+    case 'major':
+      return { major: current.major + 1, minor: 0, patch: 0 };
+    case 'minor':
+      return { major: current.major, minor: current.minor + 1, patch: 0 };
+    case 'patch':
+      return { major: current.major, minor: current.minor, patch: current.patch + 1 };
+  }
+}
+
+/**
+ * Convert semantic version to string
+ */
+export function versionToString(version: ISemanticVersion): TVersionString {
+  const base = `${version.major}.${version.minor}.${version.patch}` as TVersionString;
+  if (version.label && version.label !== 'final') {
+    return `${base}-${version.label}` as TVersionString;
+  }
+  return base;
+}
+
+/**
+ * Parse version string to semantic version
+ */
+export function parseVersionString(versionString: string): ISemanticVersion {
+  const [base, label] = versionString.split('-');
+  const [major, minor, patch] = base.split('.').map(Number);
+  return {
+    major: major || 0,
+    minor: minor || 0,
+    patch: patch || 0,
+    label: label as ISemanticVersion['label'],
+  };
+}

tsconfig.json

@@ -1,14 +1,17 @@
 {
   "compilerOptions": {
     "experimentalDecorators": true,
-    "useDefineForClassFields": false,
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
     "esModuleInterop": true,
-    "verbatimModuleSyntax": true
+    "verbatimModuleSyntax": true,
-  },
+    "baseUrl": ".",
-  "exclude": [
+    "paths": {
-    "dist_*/**/*.d.ts"
+      "@signature.digital/tools": ["./ts/index.js"],
-  ]
+      "@signature.digital/demodata": ["./ts_demodata/index.js"],
+      "@signature.digital/interfaces": ["./ts_interfaces/index.js"]
+    }
+  },
+  "exclude": ["dist_*/**/*.d.ts"]
 }