@hailer/mcp 1.1.17-beta.2 → 1.2.0

package/.claude/skills/sdk-function-fields/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sdk-function-fields
 description: Complete guide to creating calculated function fields in Hailer - workflow, variable types, patterns
-version: 1.2.0
+version: 2.0.0
 triggers:
   - function field
   - calculated field
@@ -20,7 +20,7 @@ Complete guide for creating calculated fields that auto-update when dependencies
 ## Overview
 
 Function fields compute values from other fields. Examples:
-- Total = Quantity × Unit Price
+- Total = Quantity x Unit Price
 - Days Until Due = Due Date - Today
 - Invoice Total = Sum of line item prices (filtered by phase)
 
@@ -35,15 +35,14 @@ npm run pull
 
 ### 2. Add Field Definition (fields.ts)
 
+Add to the `fields` array in `workspace/[Workflow]_[id]/fields.ts`:
+
 ```typescript
-// workspace/[Workflow]_[id]/fields.ts
+// NEW field — omit _id, server assigns it after push
 {
-  label: "Total Cost",
-  type: "numeric",
-  key: "total_cost",
-  function: "@function:totalCost",
+  data: [],
+  function: "@function:total_cost_XXX",      // Must match exported function name
   functionEnabled: true,
-  editable: false,
   functionVariables: {
     quantity: {
       type: "=",
@@ -53,46 +52,89 @@ npm run pull
       type: "=",
       data: [FieldIds.unit_price]
     }
-  }
+  },
+  inviteToDiscussionOnChange: false,
+  key: "totalCost",
+  label: "Total Cost",
+  required: false,
+  type: "numeric"
 }
 ```
 
+**Required properties for function fields:**
+- `function`: `"@function:{functionName}"` — must match the exported function name exactly
+- `functionEnabled`: `true`
+- `functionVariables`: dependency wiring (see Variable Types below)
+- `data`: `[]` — always empty array for function fields
+- `type`: the output type (`"numeric"`, `"text"`, `"date"`, etc.)
+
+**For new fields:** Omit `_id`. The server assigns it after push. Run `npm run pull` after push to get the server-assigned ID.
+
+**For existing fields:** Keep the `_id` from enums.
+
 ### 3. Create Function File
 
-Create `workspace/[Workflow]_[id]/functions/totalCost.ts`:
+**Naming convention:** `{functionName}_{last3HexOfFieldId}.ts`
+
+- For new fields (no ID yet): use a temporary 3-char suffix, e.g., `total_cost_tmp.ts`
+- After push + pull, the SDK renames to match the server-assigned ID
+
+Create `workspace/[Workflow]_[id]/functions/total_cost_XXX.ts`:
 
 ```typescript
-export function totalCost(dep: {
-  quantity: number | null;
-  unitPrice: number | null;
-}): number {
+/**
+ * Field function for: Total Cost
+ * Field name: Total Cost
+ * Field ID: [assigned after push]
+ */
+
+interface Dependencies {
+  quantity: number;
+  unitPrice: number;
+}
+
+export function total_cost_XXX(dep: Dependencies): number {
   const qty = Number(dep.quantity) || 0;
   const price = Number(dep.unitPrice) || 0;
   return qty * price;
 }
 ```
 
-### 4. Export Function
+**File structure rules:**
+1. **JSDoc header** — field function name, label, and ID
+2. **`Dependencies` interface** — typed to match source field types (see Field Data Formats table)
+3. **Named export** — function name must match the `@function:` reference in fields.ts
+4. **Return type** — always explicit (`number`, `string`, etc.), never `any`
+
+### 4. Export from Index
 
 Edit `workspace/[Workflow]_[id]/functions/index.ts`:
 
 ```typescript
-export { totalCost } from './totalCost';
+// Auto-generated index of field functions
+// Import and re-export all field functions
+
+export { total_cost_XXX } from "./total_cost_XXX";
 ```
 
-### 5. Test
+### 5. Test with Vitest
 
 ```typescript
-// workspace/[Workflow]_[id]/main.test.ts
-import { totalCost } from './functions';
+// workspace/[Workflow]_[id]/functions/total_cost_XXX.test.ts
+import { total_cost_XXX } from "./total_cost_XXX";
 
-describe('totalCost', () => {
+describe('total_cost_XXX', () => {
   it('multiplies quantity by unit price', () => {
-    expect(totalCost({ quantity: 5, unitPrice: 10 })).toBe(50);
+    expect(total_cost_XXX({ quantity: 5, unitPrice: 10 })).toBe(50);
   });
 
-  it('handles null values', () => {
-    expect(totalCost({ quantity: null, unitPrice: 10 })).toBe(0);
+  it('handles null/undefined values', () => {
+    expect(total_cost_XXX({ quantity: null, unitPrice: 10 } as any)).toBe(0);
+    expect(total_cost_XXX({ quantity: 5, unitPrice: null } as any)).toBe(0);
+  });
+
+  it('handles non-numeric values', () => {
+    expect(total_cost_XXX({ quantity: "abc", unitPrice: 10 } as any)).toBe(0);
   });
 });
 ```
@@ -105,278 +147,325 @@ Run: `npm test`
 npm run fields-push:force
 ```
 
-Use `fields-push:force` (not `fields-push`). The non-force variant uses `fast-deep-equal` comparison which may skip `functionVariables` changes — your dependency wiring won't update.
+**Always use `:force`** — the non-force variant uses `fast-deep-equal` comparison which may skip `functionVariables` changes, so your dependency wiring won't update.
+
+### 7. Pull to Get Server IDs
+
+```bash
+npm run pull
+```
 
-### 7. Verify Enum Imports After Pull
+After pull:
+- Field gets a server-assigned `_id`
+- Function file may be renamed to match the new ID suffix
+- **Check enum imports** — identical hex suffixes across workflows can resolve to the wrong enum
 
-After pull, check enum imports manually. Identical hex suffixes across workflows can resolve to the wrong enum (e.g., `Tasks_FieldIds` vs `Orders_FieldIds` both having a field ending in `_abc123`). Fix any wrong imports before proceeding.
+**Important: Pull overwrites TypeScript declarations.** The server stores only the function body as plain JavaScript. On pull, the SDK regenerates the TypeScript wrapper (interface, return type, comments) from server metadata. Your type fixes get overwritten every time.
+
+| Part of File | Persists After Pull? | Why |
+|--------------|---------------------|-----|
+| Function body code | Yes | Stored on server as-is |
+| `Number()` wrapping | Yes | Part of function body |
+| Named constants | Yes | Part of function body |
+| Removed dependencies | Yes | Stored in server metadata |
+| `interface Dependencies` types | No | SDK regenerates from schema |
+| Return type annotation | No | SDK always uses `: any` |
+| Comments/JSDoc | No | Not stored on server |
+
+The SDK's type inference is imperfect — it may map `numeric` fields to `string` in the interface. This is cosmetic, not a runtime bug. **Always use defensive coding in the function body** (`Number()` wrapping, `|| 0` defaults) — never rely on TypeScript types for runtime safety. The function body is what runs on the server.
 
 ---
 
-## Field Data Formats in Functions
+## Quality Rules
 
-What format does each field type return when used as a dependency variable?
+These rules prevent the bugs found in real function fields. Follow them exactly.
 
-| Field Type | Returns | Example |
-|------------|---------|---------|
-| `text`, `textarea` | `string` | `"Hello world"` |
-| `numeric`, `numericunit` | `number` | `42.5` |
-| `date`, `datetime` | `number` (ms timestamp) | `1730937600000` |
-| `daterange`, `datetimerange` | `{ start: number, end: number }` | `{ start: 1730937600000, end: 1731024000000 }` |
-| `time` | `number` (ms timestamp, includes date!) | `1765863000000` |
-| `timerange` | `{ start: number, end: number }` | `{ start: 1765863000000, end: 1765915200000 }` (ms timestamps, includes date!) |
-| `textpredefinedoptions` | `string` | `"High"` |
-| `users`, `teams` | `string` (ID) | `"5f8a1b2c3d4e5f6a7b8c9d0e"` |
-| `activitylink` | `string` (activity ID) | `"692abc123def456"` |
-| `country` | `string` (ISO code) | `"FI"` |
-| `numeric` + `modifier.checkbox` | `number` | `1` (true) or `0` (false) |
+### Dependencies Interface Must Match Source Types
+
+Map each `functionVariables` entry to its correct TypeScript type based on how it's wired:
+
+| Variable type | Source | Dependencies type |
+|---------------|--------|-------------------|
+| `=` (same activity field) | numeric field | `number` |
+| `=` (same activity field) | text field | `string` |
+| `=` (same activity field) | date field | `number` (ms timestamp) |
+| `<` (backlink to field) | any field | `Array<SourceType>` |
+| `<` (backlink to `"meta"`) | metadata | `Array<ActivityMeta>` |
+| `?` (static phase ID) | phase enum | `string` |
+| `>` (forward link to field) | any field | `SourceType` |
+| `>` (forward link to `"meta"`) | metadata | `ActivityMeta` |
+| `=` with `data: ["meta"]` | own metadata | `ActivityMeta` |
+
+**Wrong:** Typing a numeric source field as `string` (causes silent JS coercion)
+**Right:** Always use the actual source field's type
+
+### No Unused Dependencies
 
-**Examples:**
-
-```javascript
-// Date field (milliseconds timestamp)
-const dueDate = dep.dueDate;  // 1730937600000
-const isOverdue = dueDate < Date.now();
-
-// Daterange field (object with start/end)
-const period = dep.eventPeriod;  // { start: 1730937600000, end: 1731024000000 }
-const startDate = period ? period.start : null;
-const endDate = period ? period.end : null;
-const durationMs = (endDate && startDate) ? (endDate - startDate) : 0;
-const durationDays = Math.ceil(durationMs / 86400000);
-
-// Time field (ms timestamp - includes date!)
-const startTime = dep.startTime;  // 1765863000000
-// To extract just the time, use Date methods:
-const date = new Date(startTime);
-const hours = date.getUTCHours();
-const minutes = date.getUTCMinutes();
-
-// Timerange field (object with start/end as ms timestamps - includes date!)
-const workHours = dep.workingHours;  // { start: 1765863000000, end: 1765915200000 }
-const durationMs = workHours ? (workHours.end - workHours.start) : 0;
-const durationMinutes = durationMs / 60000;
-
-// IMPORTANT: When to convert vs keep raw:
-// - Display only (text output) → use Date methods to extract time
-// - Write to another date/time field → keep as Unix milliseconds (no conversion!)
-
-// Checkbox field (1 or 0)
-const isActive = dep.isActive;  // 1 or 0
-if (isActive === 1) { /* checked */ }
+Every entry in `functionVariables` must be used in the function body. If you declare a dependency you don't use, it causes unnecessary cross-workflow lookups on every recalculation.
+
+**Wrong:**
+```typescript
+interface Dependencies {
+  goals: Array<number>;
+  assists: Array<number>;
+  salary: Array<number>;  // UNUSED — wasted cross-workflow lookup
+}
+export function rating(dep: Dependencies): number {
+  // salary is never referenced
+  return sumArray(dep.goals) * 2 + sumArray(dep.assists);
+}
 ```
 
+**Right:** Remove `salary` from both `functionVariables` in fields.ts AND the Dependencies interface.
+
+### Return Type — Always Explicit, Never `any`
+
+```typescript
+// Wrong
+export function myFunc(dep: Dependencies): any { ... }
+
+// Right
+export function myFunc(dep: Dependencies): number { ... }
+```
+
+### Defensive Value Handling
+
+```typescript
+// Scalars — default to zero/empty
+const value = Number(dep.quantity) || 0;
+const text = dep.name || "";
+
+// Arrays (backlinks) — ALWAYS default to empty array
+const items = dep.items || [];
+
+// Metadata — null-check before property access
+const phase = meta ? meta.phase : null;
+
+// Array iteration — use for loop with index, null-check each element
+for (let i = 0; i < items.length; i++) {
+  const val = Number(items[i]) || 0;
+}
+```
+
+### Runtime Is Plain JavaScript
+
+Files are `.ts` for local dev and testing, but **the runtime strips TypeScript and executes plain ES6 JavaScript** in isolated-vm. This means:
+- `interface` declarations are stripped — they're for dev-time safety only
+- No TypeScript-only syntax in the function body (no `as`, no generics, no `!` assertions)
+- Optional chaining (`?.`) and nullish coalescing (`??`) work (ES2020)
+- `const`/`let`/`for...of`/arrow functions/template literals all work
+
 ---
 
-## Backlink Arrays (`<`)
+## Variable Types Reference
 
-Backlinks return **arrays** because multiple activities can link to this one.
+### `=` — Same Activity Field
 
-```javascript
-// functionVariables config
-{
+Read a field value from the same activity.
+
+```typescript
+// fields.ts
+functionVariables: {
+  quantity: {
+    type: "=",
+    data: [FieldIds.quantity]
+  }
+}
+
+// function — returns scalar value
+const qty = Number(dep.quantity) || 0;
+```
+
+### `<` — Backlink (Other Activities Linking TO This One)
+
+Returns **arrays** — multiple activities can link to this one.
+
+```typescript
+// fields.ts
+functionVariables: {
   prices: {
     type: "<",
     data: [WorkflowIds.invoice_rows, InvoiceRows_FieldIds.total_price]
   }
 }
 
-// In function - ALWAYS default to empty array
+// function — ALWAYS default to empty array
 const prices = dep.prices || [];
 let total = 0;
 for (let i = 0; i < prices.length; i++) {
   total += Number(prices[i]) || 0;
 }
-return total;
 ```
 
----
-
-## Activity Metadata (`"meta"`)
-
-The special `"meta"` value returns activity metadata. It works with **all variable types**:
+### `>` — Forward Link (This Activity Links TO Another)
 
-### Current Activity Metadata (`=`)
+Read a field value from a linked activity.
 
-```javascript
-// Get metadata of THIS activity
-{
-  myMeta: {
-    type: "=",
-    data: ["meta"]
+```typescript
+// fields.ts
+functionVariables: {
+  customerName: {
+    type: ">",
+    data: [FieldIds.customer_link, Customers_FieldIds.name]
   }
 }
 
-// In function
-const myPhase = dep.myMeta ? dep.myMeta.phase : null;
-const myCreated = dep.myMeta ? dep.myMeta.created : 0;
+// function — returns scalar value (single linked activity)
+const name = dep.customerName || "";
 ```
 
-### Forward Link Metadata (`>`)
+### `?` — Static Value (Phase ID for Comparison)
 
-```javascript
-// Get metadata of LINKED activity (this → other)
-{
-  customerMeta: {
-    type: ">",
-    data: [FieldIds.customer_link, "meta"]
+Provides a known phase ID to compare against in logic.
+
+```typescript
+// fields.ts
+functionVariables: {
+  activePhase: {
+    type: "?",
+    data: [WorkflowIds.injuries, Injuries_PhaseIds.active]
   }
 }
 
-// In function
-const customerPhase = dep.customerMeta ? dep.customerMeta.phaseName : 'Unknown';
+// function — returns phase ID string
+const activePhase = dep.activePhase;  // "627d14339381d6077ab90ce9"
+if (meta.phase === activePhase) { ... }
+```
+
+---
+
+## Activity Metadata (`"meta"`)
+
+The special `"meta"` value returns activity metadata. Works with all variable types.
+
+### Own Metadata (`=`)
+
+```typescript
+functionVariables: {
+  myMeta: { type: "=", data: ["meta"] }
+}
+// dep.myMeta → { _id, name, phase, phaseName, created, updated, ... }
 ```
 
 ### Backlink Metadata (`<`)
 
-```javascript
-// Get metadata of activities linking TO this (others → this)
-{
-  rowsMeta: {
-    type: "<",
-    data: [WorkflowIds.invoice_rows, "meta"]
-  }
+```typescript
+functionVariables: {
+  injuryMeta: { type: "<", data: [WorkflowIds.injuries, "meta"] }
 }
+// dep.injuryMeta → Array<ActivityMeta>
+```
 
-// In function - returns ARRAY
-const rows = dep.rowsMeta || [];
-for (let i = 0; i < rows.length; i++) {
-  const phaseName = rows[i] ? rows[i].phaseName : 'Unknown';
+### Forward Link Metadata (`>`)
+
+```typescript
+functionVariables: {
+  customerMeta: { type: ">", data: [FieldIds.customer_link, "meta"] }
 }
+// dep.customerMeta → ActivityMeta
 ```
 
 ### Metadata Structure
 
-```javascript
-{
-  "_id": "694c9536acfa30f6df13201b",      // Activity ID
-  "name": "Invoice row name",              // Activity name
-  "process": "67dc1b7d3d2c9f6cf9a5468d",  // Workflow ID
-  "phase": "67dc1b7d3d2c9f6cf9a546c4",    // Phase ID
-  "processName": "Invoice Rows",           // Workflow name
-  "phaseName": "Active",                   // Phase name
-  "created": 1766626614031,               // Created timestamp (ms)
-  "updated": 1766626614031,               // Updated timestamp (ms)
-  "completed": null,                       // Completed timestamp or null
-  "sequence": 1649,                        // Activity sequence number
-  "active": true                           // Is activity active
+```typescript
+interface ActivityMeta {
+  _id: string;           // Activity ID
+  name: string;          // Activity name
+  process: string;       // Workflow ID
+  phase: string;         // Phase ID
+  processName: string;   // Workflow name
+  phaseName: string;     // Phase name
+  created: number;       // Created timestamp (ms)
+  updated: number;       // Updated timestamp (ms)
+  completed: number | null;  // Completed timestamp or null
+  sequence: number;      // Activity sequence number
+  active: boolean;       // Is activity active
 }
 ```
 
+**Note:** `"data"` and `"meta"` are interchangeable aliases. Prefer `"meta"` for clarity.
+
 ---
 
 ## Parallel Array Guarantee
 
-**CRITICAL INSIGHT:** When you have multiple `<` (backlink) variables from the **SAME source workflow**, they are guaranteed to be:
+**CRITICAL:** When you have multiple `<` (backlink) variables from the **SAME source workflow**, they are guaranteed to be:
 - Same length
 - Same order (index 0 in all arrays = same activity)
 
-**This is a core Hailer feature that enables safe parallel iteration.**
+This enables safe parallel iteration:
 
-```javascript
-const prices = dep['Total price'] || [];   // [41.76, 26.1, 153.47]
-const data = dep['Data'] || [];            // [{...}, {...}, {...}]
+```typescript
+const prices = dep.prices || [];     // [41.76, 26.1, 153.47]
+const rowMeta = dep.rowMeta || [];   // [{...}, {...}, {...}]
 
-// Index 0 in both = same Invoice Row activity
+// Index 0 in both = same source activity
 for (let i = 0; i < prices.length; i++) {
   const price = Number(prices[i]) || 0;
-  const phaseName = data[i] ? data[i].phaseName : 'Unknown';
-  // price and phaseName are from the SAME activity
+  const phaseName = rowMeta[i] ? rowMeta[i].phaseName : 'Unknown';
 }
 ```
 
-**Arrays from DIFFERENT workflows** are independent.
+**Arrays from DIFFERENT source workflows are independent — never assume index alignment across workflows.**
 
 ---
 
-## Static Variables (`?`)
-
-Static variables provide phase IDs for comparison in your function logic.
-
-```javascript
-// Get specific phase IDs to compare against
-{
-  donePhase: {
-    type: "?",
-    data: [WorkflowIds.sales_activities, PhaseIds.done]
-  },
-  archivePhase: {
-    type: "?",
-    data: [WorkflowIds.sales_activities, PhaseIds.archive]
-  }
-}
-
-// In function - compare against metadata phase
-const donePhase = dep.donePhase;       // "627d14339381d6077ab90ce9"
-const archivePhase = dep.archivePhase; // "639b49617a4413c20f15ac12"
+## Field Data Formats in Functions
 
-if (item.phase === donePhase || item.phase === archivePhase) {
-  // Activity is in done or archive phase
-}
-```
+What format does each field type return when used as a dependency?
 
-**Note:** To get `process` and `phase` IDs from activities, use `"meta"` (not `?`). Static `?` is only for providing known phase IDs for comparison.
+| Field Type | Returns | Example |
+|------------|---------|---------|
+| `text`, `textarea` | `string` | `"Hello world"` |
+| `numeric`, `numericunit` | `number` | `42.5` |
+| `date`, `datetime` | `number` (ms timestamp) | `1730937600000` |
+| `daterange`, `datetimerange` | `{ start: number, end: number }` | `{ start: 1730937600000, end: 1731024000000 }` |
+| `time` | `number` (ms timestamp, includes date!) | `1765863000000` |
+| `timerange` | `{ start: number, end: number }` | `{ start: 1765863000000, end: 1765915200000 }` |
+| `textpredefinedoptions` | `string` | `"High"` |
+| `users`, `teams` | `string` (ID) | `"5f8a1b2c3d4e5f6a7b8c9d0e"` |
+| `activitylink` | `string` (activity ID) | `"692abc123def456"` |
+| `country` | `string` (ISO code) | `"FI"` |
+| `numeric` + `modifier.checkbox` | `number` | `1` (true) or `0` (false) |
 
 ---
 
 ## Common Patterns
 
-### Sum from Backlinks + Filter by Phase (Complete Example)
+### Sum Backlink Values
 
-**functionVariables config:**
-```javascript
-{
-  Data: {
-    type: "<",
-    data: [WorkflowIds.sales_activities, "meta"]
-  },
-  dl: {
-    type: "<",
-    data: [WorkflowIds.sales_activities, FieldIds.deadline]
-  },
-  done: {
-    type: "?",
-    data: [WorkflowIds.sales_activities, PhaseIds.done]
-  },
-  archive: {
-    type: "?",
-    data: [WorkflowIds.sales_activities, PhaseIds.archive]
-  }
+```typescript
+interface Dependencies {
+  goals: Array<number>;
 }
-```
 
-**Function (find latest deadline from done/archived activities):**
-```javascript
-function latestCompletedDeadline(dep) {
-  const data = dep.Data || [];
-  const deadlines = dep.dl || [];
-  const donePhase = dep.done;
-  const archivePhase = dep.archive;
-
-  const arr = [];
-  for (let i = 0; i < data.length; i++) {
-    const item = data[i];
-    if ((item.phase === donePhase || item.phase === archivePhase) && deadlines[i]) {
-      arr.push(deadlines[i]);
-    }
+export function total_goals_XXX(dep: Dependencies): number {
+  const goals = dep.goals || [];
+  let sum = 0;
+  for (let i = 0; i < goals.length; i++) {
+    sum += Number(goals[i]) || 0;
   }
-
-  if (arr.length === 0) return null;
-  return Math.max(...arr);
+  return sum;
 }
 ```
 
-### Sum Active Only
+### Sum Backlinks Filtered by Phase
+
+```typescript
+interface Dependencies {
+  prices: Array<number>;
+  rowMeta: Array<ActivityMeta>;
+  activePhase: string;
+}
 
-```javascript
-function sumActiveOnly(dep) {
-  const prices = dep['Total price'] || [];
-  const data = dep['Data'] || [];
-  const activePhase = dep['Active'];
+export function sum_active_XXX(dep: Dependencies): number {
+  const prices = dep.prices || [];
+  const rowMeta = dep.rowMeta || [];
+  const activePhase = dep.activePhase;
 
   let total = 0;
   for (let i = 0; i < prices.length; i++) {
-    if (data[i] && data[i].phase === activePhase) {
+    if (rowMeta[i] && rowMeta[i].phase === activePhase) {
       total += Number(prices[i]) || 0;
     }
   }
@@ -384,127 +473,182 @@ function sumActiveOnly(dep) {
 }
 ```
 
-### Group by Phase
+### Composite Rating from Multiple Workflows
 
-```javascript
-function groupByPhase(dep) {
-  const prices = dep['Total price'] || [];
-  const data = dep['Data'] || [];
+```typescript
+interface Dependencies {
+  activePhase: string;
+  goals: Array<number>;
+  assists: Array<number>;
+  injuryMeta: Array<ActivityMeta>;
+}
 
-  const result = {};
-  for (let i = 0; i < prices.length; i++) {
-    const phaseName = data[i] ? data[i].phaseName : 'Unknown';
-    const price = Number(prices[i]) || 0;
-    result[phaseName] = (result[phaseName] || 0) + price;
+export function player_rating_XXX(dep: Dependencies): number {
+  const GOAL_WEIGHT = 2;
+  const INJURY_PENALTY = 5;
+
+  const goals = dep.goals || [];
+  const assists = dep.assists || [];
+  const injuryMeta = dep.injuryMeta || [];
+  const activePhase = dep.activePhase || null;
+
+  let totalGoals = 0;
+  for (let i = 0; i < goals.length; i++) {
+    totalGoals += Number(goals[i]) || 0;
+  }
+
+  let totalAssists = 0;
+  for (let i = 0; i < assists.length; i++) {
+    totalAssists += Number(assists[i]) || 0;
   }
-  return JSON.stringify(result);
+
+  let activeInjuryCount = 0;
+  for (let i = 0; i < injuryMeta.length; i++) {
+    const meta = injuryMeta[i];
+    if (meta && activePhase && meta.phase === activePhase) {
+      activeInjuryCount++;
+    }
+  }
+
+  return (totalGoals * GOAL_WEIGHT + totalAssists) - (activeInjuryCount * INJURY_PENALTY);
 }
 ```
 
-### Exclude Multiple Phases
+### Per-90-Minutes Normalization
+
+```typescript
+interface Dependencies {
+  goals: number;
+  minutesPlayed: number;
+}
 
-```javascript
-function sumExcludingCancelled(dep) {
-  const prices = dep['Total price'] || [];
-  const data = dep['Data'] || [];
-  const cancelledPhase = dep['Cancelled'];
-  const deletedPhase = dep['Deleted'];
+export function goals_per_90_XXX(dep: Dependencies): number {
+  const goals = Number(dep.goals) || 0;
+  const minutes = Number(dep.minutesPlayed) || 0;
 
-  let total = 0;
-  for (let i = 0; i < prices.length; i++) {
-    const phase = data[i] ? data[i].phase : null;
-    if (phase === cancelledPhase || phase === deletedPhase) continue;
-    total += Number(prices[i]) || 0;
-  }
-  return total;
+  if (minutes === 0) return 0;
+  return Math.round((goals / minutes) * 90 * 100) / 100;
+}
+```
+
+### Same-Activity Field Sum
+
+```typescript
+interface Dependencies {
+  yellowCards: number;
+  redCards: number;
+}
+
+export function total_cards_XXX(dep: Dependencies): number {
+  return (Number(dep.yellowCards) || 0) + (Number(dep.redCards) || 0);
 }
 ```
 
 ### Conditional Text
 
-```javascript
-function status(dep) {
+```typescript
+interface Dependencies {
+  dueDate: number;
+}
+
+export function status_XXX(dep: Dependencies): string {
   if (!dep.dueDate) return "No due date";
   if (dep.dueDate < Date.now()) return "Overdue";
   return "On track";
 }
 ```
 
-### Forward Link Value
+### Exclude Multiple Phases
 
-```javascript
-// Get value from linked activity
-functionVariables: {
-  customerName: {
-    type: ">",
-    data: [FieldIds.customer_link, Customers_FieldIds.name]
+```typescript
+interface Dependencies {
+  prices: Array<number>;
+  rowMeta: Array<ActivityMeta>;
+  cancelledPhase: string;
+  deletedPhase: string;
+}
+
+export function sum_excluding_cancelled_XXX(dep: Dependencies): number {
+  const prices = dep.prices || [];
+  const rowMeta = dep.rowMeta || [];
+
+  let total = 0;
+  for (let i = 0; i < prices.length; i++) {
+    const phase = rowMeta[i] ? rowMeta[i].phase : null;
+    if (phase === dep.cancelledPhase || phase === dep.deletedPhase) continue;
+    total += Number(prices[i]) || 0;
   }
+  return total;
 }
 ```
 
-### Emoji Based on Own Phase
+### Emoji Name Function Based on Own Phase
 
-```javascript
-// In name function: use activity's own phase, not parent workflow phase
-functionVariables: {
-  myMeta: {
-    type: "=",
-    data: ["meta"]  // Returns this activity's metadata
-  },
-  donePhase: {
-    type: "?",
-    data: [WorkflowIds.this_workflow, PhaseIds.done]
-  }
+```typescript
+interface Dependencies {
+  myMeta: ActivityMeta;
+  donePhase: string;
+  activityName: string;
 }
 
-// In name function
-function nameWithEmoji(dep) {
+export function name_with_status_XXX(dep: Dependencies): string {
   const myPhase = dep.myMeta ? dep.myMeta.phase : null;
-  const donePhase = dep.donePhase;
-
-  const prefix = (myPhase === donePhase) ? "✅ " : "🔄 ";
-  return prefix + dep.activityName;
+  const prefix = (myPhase === dep.donePhase) ? "done " : "";
+  return prefix + (dep.activityName || "Unnamed");
 }
 ```
 
-**Key:** Compare against the activity's OWN phase (from `"meta"` metadata), not the parent workflow's phase.
-
 ---
 
 ## Critical Rules
 
-1. **ES6 JavaScript only** - No TypeScript syntax in function body
-2. **Never return null/undefined** - Always return valid typed value
-3. **Handle null inputs** - Use `|| 0` or `|| ""` defaults
-4. **Same inputs = same outputs** - No randomness, deterministic
-5. **Helpers inside function** - Define helper functions in function body
-6. **Use enums** - Never hardcode field/workflow IDs
-7. **updateMany single-workflow rule** - `v3.activity.updateMany` targets one workflow per call. For cascading updates across multiple workflows, create separate function fields per target workflow. Don't mix activities from different workflows in one payload
-8. **Double-wrapped array for generic CRUD** - When outputting a payload for the monolith `POST /api/update-activities` handler, use `[[{_id, phaseId}, ...]]` (double-wrapped). The handler spreads parsed JSON as `updateMany(...args)`, so the first arg must be the array. Single-wrapped `[{_id, phaseId}]` causes "must be an array" validation error
-9. **Empty string validation** - Hailer rejects empty string `''` with "value is not allowed to be empty". Always return `'[]'` or a valid non-empty string as default from function fields
-10. **Metadata aliases** - `"data"` and `"meta"` are interchangeable aliases. `type: "="` with `data: ["meta"]` (or `data: ["data"]`) returns this activity's metadata object. `type: "<"` with `data: [workflowId, "meta"]` (or `data: [workflowId, "data"]`) returns array of metadata objects for linked activities. Prefer `"meta"` for clarity.
+1. **TypeScript files, JavaScript runtime** — Write `.ts` with interfaces for dev safety. Runtime strips TS and runs ES6 JS in isolated-vm. No TS-only syntax in function bodies.
+2. **Never return `null`/`undefined` from numeric fields** — Always return `0` as default. Hailer rejects empty string `''` with "value is not allowed to be empty" — return `'[]'` or valid non-empty string for text fields.
+3. **Handle null inputs defensively** — Use `Number(x) || 0` for numbers, `|| ""` for strings, `|| []` for arrays.
+4. **Deterministic** — Same inputs must produce same outputs. No `Math.random()`, no non-deterministic behavior.
+5. **No unused dependencies** — Every `functionVariables` entry must be used in the function. Unused deps cause wasted cross-workflow lookups.
+6. **Correct types in Dependencies** — Match the source field type exactly. A numeric source field is `number`, not `string`.
+7. **Return type is never `any`** — Always declare the actual return type (`number`, `string`).
+8. **Use enums for IDs** — Never hardcode workflow/field/phase IDs. Import from `workspace/enums.ts`.
+9. **`fields-push:force` only** — Non-force push skips `functionVariables` changes.
+10. **Pull after push** — Always `npm run pull` to get server-assigned IDs.
+11. **Magic numbers as constants** — Weights, multipliers, penalties should be named `const` at the top of the function.
+12. **`linkedfrom` fields don't work in isolated-vm** — Use `<` backlink dependencies instead.
 
 ---
 
 ## Common Mistakes
 
-| Wrong | Right |
-|-------|-------|
-| `var arr = dep.arr` | `const arr = dep.arr \|\| []` |
-| `arr[i] * 2` | `(Number(arr[i]) \|\| 0) * 2` |
-| `data[i].phase` | `data[i] ? data[i].phase : null` |
-| Assuming arrays match across workflows | Only same-workflow arrays are parallel |
-| Hardcoding phase IDs | Use `?` static variables with enums |
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `dep.arr` without default | `dep.arr \|\| []` | Backlinks can be undefined |
+| `arr[i] * 2` | `(Number(arr[i]) \|\| 0) * 2` | Array values can be null |
+| `meta.phase` | `meta ? meta.phase : null` | Metadata entries can be null |
+| `minutesPlayed: string` | `minutesPlayed: number` | Source is numeric field |
+| `): any` | `): number` | Explicit return type |
+| Unused dep in interface | Remove from both interface AND functionVariables | Wasted lookups |
+| `dep.salary` declared, never used | Don't declare it | Dead dependency |
+| Hardcoded `"627d14..."` | Use `PhaseIds.active` enum | Brittle, non-portable |
+| `npm run fields-push` | `npm run fields-push:force` | Non-force skips functionVariables |
+| Assuming cross-workflow array alignment | Only same-workflow `<` arrays are parallel | Different workflows = independent arrays |
 
 ---
 
 ## Checklist
 
-Before creating a function with backlinks:
-
-- [ ] All `<` arrays have `|| []` default
-- [ ] Individual array values use `Number(x) || 0`
-- [ ] Data metadata access has null check
-- [ ] Phase comparisons use `?` static variables
-- [ ] Using enums from workspace for all IDs
-- [ ] Tested with Vitest before push
+Before pushing a function field:
+
+- [ ] `Dependencies` interface types match source field types exactly
+- [ ] No unused dependencies (every functionVariables entry is used)
+- [ ] Return type is explicit (`number`, `string`), never `any`
+- [ ] All `<` arrays default with `|| []`
+- [ ] All numeric values wrapped with `Number(x) || 0`
+- [ ] All metadata access null-checked (`meta ? meta.phase : null`)
+- [ ] Phase comparisons use `?` static variables with enums
+- [ ] All IDs come from enums, never hardcoded
+- [ ] Magic numbers extracted to named constants
+- [ ] Function name matches `@function:` reference in fields.ts
+- [ ] Exported from `functions/index.ts`
+- [ ] Tested with Vitest (happy path + null/undefined inputs)
+- [ ] Using `fields-push:force` (not `fields-push`)
+- [ ] Will run `npm run pull` after push