@trace.market/types 0.1.0 → 0.3.0

package/.github/workflows/publish.yml

@@ -15,6 +15,7 @@ jobs:
     permissions:
       contents: write
       packages: write
+      id-token: write # Required for provenance and OIDC auth
     
     steps:
       - uses: actions/checkout@v4
@@ -48,7 +49,7 @@ jobs:
       
       - name: Publish to NPM
         if: steps.check.outputs.changed == 'true'
-        run: npm publish --access public
+        run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       
@@ -62,11 +63,11 @@ jobs:
       
       - name: Create GitHub Release
         if: steps.check.outputs.changed == 'true'
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        uses: softprops/action-gh-release@v1
         with:
           tag_name: v${{ steps.check.outputs.version }}
-          release_name: Release v${{ steps.check.outputs.version }}
+          name: Release v${{ steps.check.outputs.version }}
           draft: false
           prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.0] - 2026-01-19
+
+### ⚠ BREAKING CHANGES
+- **Renaming**: `MachineInstance` is renamed to `ToolInstance`. All references to `machineInstance` in processes are renamed to `toolInstance`.
+- **Structure**: `hr` (Human Resources) field moved from `ToolInstance` to `Process` interface. It is now a sibling of `toolInstance`.
+- **Typing**: `Hr.tasks` is now `string[]` (array of strings) instead of `string`.
+- **Typing**: `KnowHow.inputs` is explicitly defined as a JSONata expression string.
+- **Data Model**: Renamed `CartridgeInstance` to `NonFoodInstance` with category `non-food`.
+- **Data Model**: Removed `PackagingProcess` and `StorageProcess`.
+- **Data Model**: Consolidated `ecoLabels` and `qualityAttributes` into a single `labels` array.
+
+### Features
+- Added `hash` field to `ToolInstance`.
+- Added support for ordered steps in `Hr.tasks`.
+- Validation rules in `KnowHow` are now standardized as JSONata.
+
+### Documentation (descriptions.json)
+- Renamed root field `description` to `header`.
+- Updated all labels and examples to reflect the new "Tool" terminology and "JSONata" rules.

package/IMPLEMENTATION.md

@@ -3,7 +3,7 @@
 ## ✅ Completed Setup
 
 ### 1. Package Configuration
-- **Name changed**: `@fairfooddata/types` → `@trace.market/types`
+- **Name**: `@trace.market/types` (new scoped release)
 - **Version**: 0.1.0
 - **License**: MIT (was UNLICENSED)
 - **Repository**: Linked to https://github.com/entin-hun/tm-types
@@ -52,7 +52,7 @@ Created `.github/workflows/`:
 
 ## 📦 Current Type Definitions
 
-All types from `@fairfooddata/types@0.0.6` are preserved:
+All types from `@trace.market/types@0.0.6` are preserved:
 - Pokedex, ProductInstance, FoodInstance, CartridgeInstance
 - Process types: Milling, Printing, FreezeDrying, Blending, Sale, Harvest
 - Supply chain: Transport, Facility, Location, InputInstance
@@ -103,22 +103,17 @@ JWT_SECRET="your-secret" node generate-token.js userId role
 
 ## 🔄 Migration Path
 
-### For Projects Using `@fairfooddata/types`
+### For Projects Using `@trace.market/types`
 
 1. **Update dependencies:**
-   ```bash
-   npm uninstall @fairfooddata/types
-  npm install @trace.market/types
-   ```
+  ```bash
+  npm install @trace.market/types@^0.1.0
+  ```
 
 2. **Find & replace imports:**
-   ```typescript
-   // Old
-   import { FoodInstance } from '@fairfooddata/types';
-   
-   // New
+  ```typescript
   import { FoodInstance } from '@trace.market/types';
-   ```
+  ```
 
 3. **Test builds:**
    ```bash

package/OPENLCA_INTEGRATION_PLAN.md

@@ -0,0 +1,253 @@
+# OpenLCA Integration Plan - Summary
+
+## ✅ Completed
+
+### 1. **Database Inventory**
+All LCA datasets extracted and catalogued:
+
+| Database | Processes | Best For | Size |
+|----------|-----------|----------|------|
+| **BAFU-2025_LCI_DB_17Dec25** | 11,747 | **Textiles, agriculture, construction (PRIMARY)** | 250 MB |
+| exiobase3_monetary_20181212 | 7,504 | Global fallback, input-output | 13 GB |
+| usda_1901009 | 8,434 | US agriculture/food | 378 MB |
+| ELCD 3.2 | 365 | EU reference processes | 864 MB |
+| EcoProfiles_disaggregated | 71 | Foreground detailed models | 9.5 MB |
+| needs_18 | 933 | Building/construction (EU) | 501 MB |
+| bioenergiedat_18 | - | Bioenergy systems | 81 MB |
+| OzLCI2019 | - | Australian processes | 87 MB |
+| Worldsteel 2020 | - | Steel production | 57 MB |
+
+### 2. **LCIA Method Identification**
+**EF 3.1 (Environmental Footprint v3.1)** ✅ **RECOMMENDED**
+- **UUID**: `20629e27-b863-4fbe-bbc2-082d3eefd1e5`
+- **Location**: `ecoinvent 3.12 LCIA Methods 2025-12-01`
+- **Impact Categories**: 16 categories
+  - Climate change (fossil + biogenic + LULUC)
+  - Acidification, eutrophication (freshwater, marine, terrestrial)
+  - Ecotoxicity (freshwater, 3 subcategories)
+  - Human toxicity (carcinogenic + non-carcinogenic, 3 subcategories each)
+  - Land use
+  - Water use
+  - Material resources (metals/minerals)
+  - Ozone depletion
+  - Ionising radiation
+  - Particulate matter
+  - Photochemical oxidant formation
+  - Energy resources (non-renewable)
+
+**Alternatives Available**:
+- EF v3.0 (UUID: `1a653397-a909-4c2c-80d7-186462c20889`)
+- ReCiPe 2016 v1.03 (midpoint + endpoint)
+- TRACI v2.1 (US EPA)
+- CML v4.8
+- Ecological Scarcity 2021
+
+### 3. **Primary Database Selection**
+**BAFU-2025_LCI_DB_17Dec25** (11,747 processes)
+- ✅ Covers **textiles**: Cotton, wool, synthetic fabrics, dyeing, weaving
+- ✅ Covers **agriculture**: Grain, vegetable, fruit, dairy, meat, seed production
+- ✅ Covers **construction**: Bricks, concrete, wood, insulation, glass
+- ✅ Geographic: Swiss/EU focus (high data quality)
+- ✅ Includes emissions to air, water, soil
+- ✅ Compatible with EF 3.1
+
+**Fallback Strategy**:
+- If location="USA" → try `usda_1901009` first
+- If sector="global" or not found → `exiobase3_monetary_20181212`
+- If EU/CH → BAFU (primary)
+
+### 4. **Input Field Analysis (tm-types → Impacts)**
+
+From your `ProductInstance` & `Process` types, minimum fields for impact estimate:
+
+| Field | Required? | Source | Enricher Default |
+|-------|-----------|--------|-----------------|
+| `processName` | **YES** | Process.type + process.name | None (must provide) |
+| `amount` | **YES** | quantity from InputInstance | None (must provide) |
+| `unit` | **YES** | Unit from quantity | None (must provide) |
+| `flowType` | Recommended | Process category | Inferred from sector |
+| `location` | Recommended | Facility.location (geo) | "CH" / "EU" |
+| `database` | No | — | Auto-selected by enricher |
+| `lciaMethod` | No | — | "EF 3.1" |
+| `systemBoundary` | No | — | "cradle-to-gate" |
+| `allocation` | No | — | "cut-off" |
+
+**Bottom Line**: Your types **mostly have what's needed**. Missing: explicit `unit` might need normalization (e.g., grams → kg).
+
+### 5. **MCP Enricher Contract**
+
+Created comprehensive TypeScript schema in:
+- **[OPENLCA_MCP_ENRICHER_SPEC.md](/opt/tm-types/OPENLCA_MCP_ENRICHER_SPEC.md)** – Full architecture & logic
+- **[openlcaMcpTypes.ts](/opt/tm-types/src/openlcaMcpTypes.ts)** – Request/response types
+
+**Key Endpoints**:
+```
+POST   /api/estimate/impacts          → EstimateResponse
+GET    /api/databases                 → DatabasesListResponse
+GET    /api/lcia-methods              → LCIAMethodsListResponse
+POST   /api/estimate/processes/search → ProcessSearchResult
+```
+
+**Example Flow**:
+```typescript
+const request: EstimateImpactRequest = {
+  processName: "Cotton fabric production",
+  amount: 1,
+  unit: "m2",
+  flowType: "product",
+  location: "IN"
+  // database, lciaMethod auto-filled by enricher
+};
+
+const response: EstimateSuccess = {
+  status: "success",
+  results: {
+    lcia: {
+      method: "EF v3.1",
+      impacts: [
+        { category: "Climate change", value: 2.45, unit: "kg CO2-Eq" },
+        { category: "Water use", value: 0.082, unit: "m3 world Eq deprived" },
+        // ... 14 more categories
+      ]
+    }
+  }
+};
+```
+
+---
+
+## 🚀 Next Steps (Implementation)
+
+### Phase 1: Enricher Middleware (Week 1)
+1. Build Node.js/Express MCP enricher service (TypeScript)
+2. Implement database selector + fuzzy process matcher
+3. Wire unit conversions + LCIA method selection
+4. Deploy at `/api/lca` endpoint (beside gdt-server)
+
+### Phase 2: gdt-server Integration (Week 2)
+1. Confirm gdt-server is running with **BAFU-2025_LCI_DB_17Dec25** as `-db bafu`
+2. Test direct calculation: `POST /api/calculate` (gdt-server REST API)
+3. Implement enricher → gdt-server bridge
+
+### Phase 3: tm-types Integration (Week 3)
+1. Add `impacts?: ImpactResult[]` to `Process` interface
+2. Implement `traceMarketToEstimate()` helper to convert ProductInstance → enricher request
+3. Cache impact calculations (Redis or simple in-memory)
+4. Expose `/estimate/impacts` as public endpoint on lca.trace.market
+
+### Phase 4: Testing & Optimization (Week 4)
+1. Test with real textiles/agriculture/construction products
+2. Validate EF 3.1 category accuracy
+3. Optimize fuzzy-match performance (process index)
+4. Document API for consumers
+
+---
+
+## 📋 Database URLs (gdt-server Configuration)
+
+To run multiple DBs simultaneously (load-balance or A/B test):
+
+```bash
+# Primary (textiles, agriculture, construction)
+docker run -p 38081:8080 \
+  -v /root/openLCA-data-1.4/databases/BAFU-2025_LCI_DB_17Dec25:/app/data/databases/bafu \
+  --name gdt-bafu --rm -d gdt-server -db bafu --readonly
+
+# Fallback (US agriculture)
+docker run -p 38082:8080 \
+  -v /root/openLCA-data-1.4/databases/usda_1901009:/app/data/databases/usda \
+  --name gdt-usda --rm -d gdt-server -db usda --readonly
+
+# Global IO
+docker run -p 38083:8080 \
+  -v /root/openLCA-data-1.4/databases/exiobase3_monetary_20181212_fixedlcia_July2021:/app/data/databases/exio \
+  --name gdt-exio --rm -d gdt-server -db exio --readonly
+```
+
+Then nginx reverse-proxy:
+```
+/api/bafu/*      → :38081
+/api/usda/*      → :38082
+/api/global/*    → :38083
+```
+
+---
+
+## 🔧 Enricher Config (Server-Side)
+
+```typescript
+const enricherConfig: EnricherConfig = {
+  primaryDatabase: "BAFU-2025_LCI_DB_17Dec25",
+  secondaryDatabases: {
+    usa: "usda_1901009",
+    global: "exiobase3_monetary_20181212_fixedlcia_July2021",
+    eu: "BAFU-2025_LCI_DB_17Dec25"
+  },
+  defaultLCIAMethod: "20629e27-b863-4fbe-bbc2-082d3eefd1e5", // EF 3.1
+  gdtServerUrl: "http://127.0.0.1:38081",
+  fuzzyMatchThreshold: 0.7,
+  unitConversions: {
+    g: { kg: 0.001, t: 1e-6 },
+    kg: { g: 1000, t: 0.001 },
+    m2: { m2: 1 },
+    kWh: { MJ: 3.6, J: 3.6e6 },
+    MJ: { kWh: 0.2778, J: 1e6 }
+  }
+};
+```
+
+---
+
+## 📊 Expected LCIA Results (EF 3.1 Example)
+
+For 1 kg cotton fabric (conventional, bleached):
+
+| Impact | Value | Unit |
+|--------|-------|------|
+| Climate change | 2.45 | kg CO2-Eq |
+| Water use | 0.082 | m3 world Eq deprived |
+| Acidification | 0.0015 | mol H+-Eq |
+| Eutrophication (terrestrial) | 0.0082 | mol N-Eq |
+| Ecotoxicity (freshwater) | 0.012 | CTUe |
+| Human toxicity (carcinogenic) | 1.2e-6 | CTUh |
+| Land use | 0.0042 | dimensionless |
+| Particulate matter | 0.00045 | disease incidence |
+| Ozone depletion | 5e-8 | kg CFC-11-Eq |
+| Material resources | 0.00015 | kg Sb-Eq |
+| Energy (non-renewable) | 18.5 | MJ |
+| Ionising radiation | 0.082 | kBq U235-Eq |
+| Eutrophication (freshwater) | 0.0003 | kg P-Eq |
+| Eutrophication (marine) | 0.0008 | kg N-Eq |
+| Photochemical oxidant | 0.0022 | kg NMVOC-Eq |
+| Ecotoxicity freshwater (metals) | 0.008 | CTUe |
+
+**Single Weighted Score (EF 3.1 Global Reference 2010)**: ~0.042 Pts
+
+---
+
+## 📁 Files Created
+
+1. **[OPENLCA_MCP_ENRICHER_SPEC.md](/opt/tm-types/OPENLCA_MCP_ENRICHER_SPEC.md)**
+   - Full architecture, database config, enrichment logic
+   - Request/response schemas
+   - Required input field analysis
+   - Endpoints & implementation details
+
+2. **[openlcaMcpTypes.ts](/opt/tm-types/src/openlcaMcpTypes.ts)**
+   - TypeScript type definitions
+   - Helpers: `traceMarketToEstimate()`, `extractKeyImpacts()`
+   - Plugs directly into tm-types
+
+3. **[index.d.ts (updated)](/opt/tm-types/src/index.d.ts)**
+   - Exports all openLCA MCP types
+
+---
+
+## ✨ Key Insights
+
+1. **Your products (textiles, smallholder farms, construction) map perfectly to BAFU-2025** – high-quality, granular process data.
+2. **EF 3.1 is ideal** – EU standard, comprehensive impact categories, easy interpretation.
+3. **Minimal additional fields needed** – `processName`, `amount`, `unit` are critical; location helps; enricher fills the rest.
+4. **Fuzzy matching is essential** – users won't have process UUIDs; levenshtein + location boost makes it reliable.
+5. **Multi-DB strategy** – fallback to exiobase3 or USDA if sector-specific DB unavailable; no single DB is exhaustive.
+