@hailer/mcp 1.3.14 → 1.3.23

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

@@ -1,16 +1,10 @@
 ---
 name: sdk-function-fields
-description: Complete guide to creating calculated function fields in Hailer - workflow, variable types, patterns
-version: 2.0.0
-triggers:
-  - function field
-  - calculated field
-  - formula field
-  - backlinks
-  - phase filtering
-  - Data metadata
+description: Complete guide to creating calculated function fields in Hailer — variable types (=, >, <, ?), field data formats, backlink arrays, activity metadata, editable fields, TypeScript gotchas, and push workflow. Load when creating, debugging, or updating any function field. Also use when you see code 191 "does not compile", null return values, or questions about cross-workflow calculations.
 ---
 
+<!-- augmentation-guard: shrink-ok -->
+
 # Function Fields
 
 Complete guide for creating calculated fields that auto-update when dependencies change.
@@ -20,635 +14,402 @@ Complete guide for creating calculated fields that auto-update when dependencies
 ## Overview
 
 Function fields compute values from other fields. Examples:
-- Total = Quantity x Unit Price
+- Total = Quantity × Unit Price
 - Days Until Due = Due Date - Today
 - Invoice Total = Sum of line item prices (filtered by phase)
 
 ---
 
-## Step-by-Step Workflow
+## Canonical Fixture
 
-### 1. Pull Latest
-```bash
-npm run pull
+Pinned to testspace, workflow `Date format test` (`_id: 6a16d64ed9d2a360ab10420d`), activity `test-active-probe` (`_id: 6a16d6f1d9d2a360ab1047de`). Gold copy — paste from this block.
+
+```typescript
+// selfMeta_DATA — full metadata object via data: ["data"]
+functionVariables: { selfMeta_DATA: { type: "=", data: ["data"] } }
+// body: return JSON.stringify(dep.selfMeta_DATA)
+// returned: {"_id":"6a16d6f1d9d2a360ab1047de","name":"test","process":"6a16d64ed9d2a360ab10420d","phase":"6a16d64ed9d2a360ab10420c","created":1779881713567,"updated":1779906718754,"completed":null,"processName":"Date format test","phaseName":"New Phase","sequence":1}
+
+// selfMeta_META — wrong magic key silently returns null
+functionVariables: { selfMeta_META: { type: "=", data: ["meta"] } }
+// returned: "null"
+
+// selfPhaseId — property accessor via data: ["data", "<key>"]
+functionVariables: { selfPhaseId: { type: "=", data: ["data", "phase"] } }
+// returned: "6a16d64ed9d2a360ab10420c"
 ```
 
-### 2. Add Field Definition (fields.ts)
+**Empirical observations (2026-05-27):**
+- `data: ["data"]` returns the 10-key metadata object
+- `data: ["meta"]` returns `null` (silent — wrong magic key)
+- `data: ["data", "<key>"]` accesses a specific property of the metadata object
+- `data: ["data", "active"]` returns `null` despite REST showing `active` — dropped on the resolver path
+- `created`/`updated` timestamps are **13-digit milliseconds**
 
-Add to the `fields` array in `workspace/[Workflow]_[id]/fields.ts`:
+---
 
-```typescript
-// NEW field — omit _id, server assigns it after push
-{
-  data: [],
-  function: "@function:total_cost_XXX",      // Must match exported function name
-  functionEnabled: true,
-  functionVariables: {
-    quantity: {
-      type: "=",
-      data: [FieldIds.quantity]
-    },
-    unitPrice: {
-      type: "=",
-      data: [FieldIds.unit_price]
-    }
-  },
-  inviteToDiscussionOnChange: false,
-  key: "totalCost",
-  label: "Total Cost",
-  required: false,
-  type: "numeric"
-}
-```
+## Directory Structure
 
-**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.)
+```
+workspace/[Workflow]_[id]/
+├── fields.ts                    # Add function field definition here
+├── functions/
+│   ├── index.ts                 # Export all functions
+│   ├── total_cost_abc.ts        # Individual function file — filename encodes last 3 hex chars of field _id
+│   └── risk_level_def.ts
+└── main.test.ts                 # Test functions with Vitest
+```
 
-**For new fields:** Omit `_id`. The server assigns it after push. Run `npm run pull` after push to get the server-assigned ID.
+**Filename convention:** `<slug>_<xyz>.ts` — the last 3 hex chars come from the field's `_id`. Confirm by the field's `_id`, not the app column header.
 
-**For existing fields:** Keep the `_id` from enums.
+---
 
-### 3. Create Function File
+## Step-by-Step Workflow
 
-**Naming convention:** `{functionName}_{last3HexOfFieldId}.ts`
+### 1. Add Field Definition (fields.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
+```typescript
+{
+  label: "Total Cost",
+  type: "numeric",
+  key: "total_cost",
+  function: "@function:totalCost",
+  functionEnabled: true,
+  editable: false,
+  functionVariables: {
+    quantity: { type: "=", data: [FieldIds.quantity] },
+    unitPrice: { type: "=", data: [FieldIds.unit_price] }
+  }
+}
+```
 
-Create `workspace/[Workflow]_[id]/functions/total_cost_XXX.ts`:
+### 2. Create Function File
 
 ```typescript
 /**
- * Field function for: Total Cost
- * Field name: Total Cost
- * Field ID: [assigned after push]
+ * total_cost — Multiplies quantity by unit price to produce line-item total
  */
-
-interface Dependencies {
-  quantity: number;
-  unitPrice: number;
-}
-
-export function total_cost_XXX(dep: Dependencies): number {
+export function totalCost(dep): any {
   const qty = Number(dep.quantity) || 0;
   const price = Number(dep.unitPrice) || 0;
   return qty * price;
 }
 ```
 
-**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
-// Auto-generated index of field functions
-// Import and re-export all field functions
-
-export { total_cost_XXX } from "./total_cost_XXX";
-```
-
-### 5. Test with Vitest
+### 3. Export Function
 
 ```typescript
-// workspace/[Workflow]_[id]/functions/total_cost_XXX.test.ts
-import { total_cost_XXX } from "./total_cost_XXX";
-
-describe('total_cost_XXX', () => {
-  it('multiplies quantity by unit price', () => {
-    expect(total_cost_XXX({ quantity: 5, unitPrice: 10 })).toBe(50);
-  });
-
-  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);
-  });
-});
+// workspace/[Workflow]_[id]/functions/index.ts
+export { totalCost } from './totalCost';
 ```
 
-Run: `npm test`
-
-### 6. Push
+### 4. Push
 
 ```bash
 npm run fields-push:force
 ```
 
-**Always use `:force`** — the non-force variant uses `fast-deep-equal` comparison which may skip `functionVariables` changes, so your dependency wiring won't update.
+**Two-batch field creation:** new function fields sometimes need two push cycles:
+1. Create the plain field (no function logic) → `fields-push:force` → `pull` (gets server ID)
+2. Add `functionEnabled`, `functionVariables`, and function code → `fields-push:force`
 
-### 7. Pull to Get Server IDs
+**Pull deletes unpushed function files.** `npm run pull` regenerates the entire `functions/` directory from server state — locally written `.ts` files not yet pushed are silently deleted. Push all function changes first; if a mid-work pull is unavoidable, `git stash -u` first.
 
-```bash
-npm run 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
+## Variable Types Reference
 
-**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.
+| Type | Name | data Array | Returns |
+|------|------|------------|---------|
+| `=` | Current field | `[FieldId]` | Single value |
+| `>` | Forward link | `[linkedId, fieldId, suffix?, key?]` (1–4 elements) | Single value |
+| `<` | Backlink | `[WorkflowId, TargetFieldId]` | **Array** |
+| `?` | Static | `[WorkflowId, PhaseId]` | Phase ID string |
 
-| 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 |
+**CRITICAL:** Forward links use `LinkFieldId` (the activitylink field ID). Backlinks use `WorkflowId`.
 
-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.
+`suffix` (third element): `"data"` accesses the linked activity's metadata pseudo-key. Use `"data"`, not `"meta"` — `"meta"` silently returns null.
 
 ---
 
-## Quality Rules
-
-These rules prevent the bugs found in real function fields. Follow them exactly.
-
-### 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` |
+## Field Data Formats in Functions
 
-**Wrong:** Typing a numeric source field as `string` (causes silent JS coercion)
-**Right:** Always use the actual source field's type
+| 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 }` (ms, includes date!) | — |
+| `textpredefinedoptions` | `string` | `"High"` |
+| `users` | `object {_id, firstname, lastname}` | Resolution happens server-side before isolated-vm runs |
+| `teams` | `string` (ID) | Raw team ID string |
+| `activitylink` | `object {_id, name}` | Use `dep.myLink._id === otherId` for comparison |
+| `country` | `string` (ISO code) | `"FI"` |
+| `numeric` + `modifier.checkbox` | `number` | `1` (true) or `0` (false) |
 
-### No Unused Dependencies
+---
 
-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.
+## Editable Fields (Freeze After First Calculation)
 
-**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);
+{
+  _id: Fields.qty_per_parent,
+  editable: true,  // Calculates initially; protected once user has set a value
+  functionEnabled: true,
+  function: "@function:calculate_ratio"
 }
 ```
 
-**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;
+`editable: false` (default) — Recalculates every time dependencies change.
+`editable: true` — Stored values win; FF only runs when the field is empty.
 
-// 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;
-}
-```
+**Write acceptance confirmed (Timo, platform owner, 2026-06-14):** all interfaces — MCP `create_activity`/`update_activity`, REST `v3.activity.createMany`/`updateMany`, app-sdk, and CLI — accept writes to `editable: true` function fields.
 
-### Runtime Is Plain JavaScript
+**Writability test is `editable: true`, NOT `functionEnabled === false`.** A field with `functionEnabled: true` AND `editable: true` is both computed AND writable.
 
-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
+**Async backfill after fields-push:** when a new editable function field backfills from a same-activity source, the server-side recompute is asynchronous and can take several minutes. Don't conclude backfill failed from an immediate empty read.
 
 ---
 
-## Variable Types Reference
-
-### `=` — Same Activity Field
-
-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)
+## Backlink Arrays (`<`)
 
-Returns **arrays** — multiple activities can link to this one.
+Backlinks return **arrays** because multiple activities can link to this one.
 
-```typescript
-// fields.ts
-functionVariables: {
-  prices: {
-    type: "<",
-    data: [WorkflowIds.invoice_rows, InvoiceRows_FieldIds.total_price]
-  }
+```javascript
+// functionVariables config
+{
+  prices: { type: "<", data: [WorkflowIds.invoice_rows, InvoiceRows_FieldIds.total_price] }
 }
 
-// function — ALWAYS default to empty array
+// In 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;
 ```
 
-### `>` — Forward Link (This Activity Links TO Another)
+**Parallel Array Guarantee:** When you have multiple `<` variables from the **SAME source workflow**, they are guaranteed same length and same order. Index 0 in all arrays = same activity. This enables safe parallel iteration.
 
-Read a field value from a linked activity.
+**`<` backlink aggregates recompute IN REAL TIME when a child is added, edited, or deleted** (confirmed by Timo, Hailer platform owner, 2026-06-22).
 
-```typescript
-// fields.ts
-functionVariables: {
-  customerName: {
-    type: ">",
-    data: [FieldIds.customer_link, Customers_FieldIds.name]
-  }
-}
-
-// function — returns scalar value (single linked activity)
-const name = dep.customerName || "";
-```
-
-### `?` — Static Value (Phase ID for Comparison)
-
-Provides a known phase ID to compare against in logic.
-
-```typescript
-// fields.ts
-functionVariables: {
-  activePhase: {
-    type: "?",
-    data: [WorkflowIds.injuries, Injuries_PhaseIds.active]
-  }
-}
-
-// function — returns phase ID string
-const activePhase = dep.activePhase;  // "627d14339381d6077ab90ce9"
-if (meta.phase === activePhase) { ... }
-```
+**Don't chain one FF on another for `<` backlink VALUE aggregation.** Re-derive the backlink sum independently in each FF. Eval ordering is not guaranteed.
 
 ---
 
-## Activity Metadata (`"meta"`)
+## Activity Metadata (`"data"`)
 
-The special `"meta"` value returns activity metadata. Works with all variable types.
+**Critical:** use `"data"` as the magic key, NOT `"meta"` — `"meta"` silently returns null.
 
-### Own Metadata (`=`)
+### Current Activity Metadata (`=`)
 
-```typescript
-functionVariables: {
-  myMeta: { type: "=", data: ["meta"] }
+```javascript
+{
+  myMeta: { type: "=", data: ["data"] }
 }
-// dep.myMeta → { _id, name, phase, phaseName, created, updated, ... }
+// Available meta fields (10 keys): _id, name, process, phase, created, updated,
+// completed, processName, phaseName, sequence
 ```
 
-### Backlink Metadata (`<`)
+`sequence` is a server-maintained auto-incrementing activity counter — usable for serial names like `T-YYYY-NNNN`.
 
-```typescript
-functionVariables: {
-  injuryMeta: { type: "<", data: [WorkflowIds.injuries, "meta"] }
-}
-// dep.injuryMeta → Array<ActivityMeta>
-```
+**`active` is absent at runtime** despite appearing in REST show_activity_by_id — dropped on the resolver path. Compare `dep.selfMeta.phase` against known endpoint phase IDs instead.
 
 ### Forward Link Metadata (`>`)
 
-```typescript
-functionVariables: {
-  customerMeta: { type: ">", data: [FieldIds.customer_link, "meta"] }
+```javascript
+{
+  customerMeta: { type: ">", data: [FieldIds.customer_link, "data"] }
 }
-// dep.customerMeta → ActivityMeta
+// In function
+const customerPhase = dep.customerMeta ? dep.customerMeta.phaseName : 'Unknown';
 ```
 
-### Metadata Structure
+### Backlink Metadata (`<`)
 
-```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
+```javascript
+{
+  rowsMeta: { type: "<", data: [WorkflowIds.invoice_rows, "data"] }
+}
+// In function - returns ARRAY
+const rows = dep.rowsMeta || [];
+for (let i = 0; i < rows.length; i++) {
+  const phaseName = rows[i] ? rows[i].phaseName : 'Unknown';
 }
 ```
 
-**Note:** `"data"` and `"meta"` are interchangeable aliases. Prefer `"meta"` for clarity.
-
 ---
 
-## Parallel Array Guarantee
+## Static Variables (`?`)
 
-**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)
+Static variables provide phase IDs for comparison.
 
-This enables safe parallel iteration:
-
-```typescript
-const prices = dep.prices || [];     // [41.76, 26.1, 153.47]
-const rowMeta = dep.rowMeta || [];   // [{...}, {...}, {...}]
-
-// Index 0 in both = same source activity
-for (let i = 0; i < prices.length; i++) {
-  const price = Number(prices[i]) || 0;
-  const phaseName = rowMeta[i] ? rowMeta[i].phaseName : 'Unknown';
+```javascript
+{
+  donePhase: { type: "?", data: [WorkflowIds.sales_activities, PhaseIds.done] }
 }
+// In function
+if (item.phase === dep.donePhase) { /* Activity is done */ }
 ```
 
-**Arrays from DIFFERENT source workflows are independent — never assume index alignment across workflows.**
-
----
-
-## Field Data Formats in Functions
-
-What format does each field type return when used as a dependency?
-
-| 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 Backlink Values
+### Sum from Backlinks
 
-```typescript
-interface Dependencies {
-  goals: Array<number>;
-}
-
-export function total_goals_XXX(dep: Dependencies): number {
-  const goals = dep.goals || [];
+```javascript
+function total(dep) {
+  const prices = dep.prices || [];
   let sum = 0;
-  for (let i = 0; i < goals.length; i++) {
-    sum += Number(goals[i]) || 0;
+  for (let i = 0; i < prices.length; i++) {
+    sum += Number(prices[i]) || 0;
   }
   return sum;
 }
 ```
 
-### Sum Backlinks Filtered by Phase
-
-```typescript
-interface Dependencies {
-  prices: Array<number>;
-  rowMeta: Array<ActivityMeta>;
-  activePhase: string;
-}
+### Filter by Phase
 
-export function sum_active_XXX(dep: Dependencies): number {
-  const prices = dep.prices || [];
-  const rowMeta = dep.rowMeta || [];
-  const activePhase = dep.activePhase;
+```javascript
+function latestCompletedDeadline(dep) {
+  const data = dep.Data || [];
+  const deadlines = dep.dl || [];
+  const donePhase = dep.done;
+  const archivePhase = dep.archive;
 
-  let total = 0;
-  for (let i = 0; i < prices.length; i++) {
-    if (rowMeta[i] && rowMeta[i].phase === activePhase) {
-      total += Number(prices[i]) || 0;
+  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]);
     }
   }
-  return total;
+  if (arr.length === 0) return null;
+  return Math.max(...arr);
 }
 ```
 
-### Composite Rating from Multiple Workflows
-
-```typescript
-interface Dependencies {
-  activePhase: string;
-  goals: Array<number>;
-  assists: Array<number>;
-  injuryMeta: Array<ActivityMeta>;
-}
-
-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;
+### Auto-numbering with `sequence`
 
-  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;
-  }
+```javascript
+// nameFunctionVariables
+{ selfMeta: { type: "=", data: ["data"] } }
 
-  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);
+// nameFunction body
+function myNameFn(dep) {
+  if (!dep.selfMeta) return null;
+  var year = new Date(dep.selfMeta.created).getFullYear();
+  var seq = String(dep.selfMeta.sequence).padStart(4, '0');
+  return 'T-' + year + '-' + seq;
 }
 ```
 
-### Per-90-Minutes Normalization
+`sequence` is monotonic across the workflow's whole lifetime — does NOT reset each year. Deletions can leave gaps.
 
-```typescript
-interface Dependencies {
-  goals: number;
-  minutesPlayed: number;
-}
+---
 
-export function goals_per_90_XXX(dep: Dependencies): number {
-  const goals = Number(dep.goals) || 0;
-  const minutes = Number(dep.minutesPlayed) || 0;
+## Critical Rules
 
-  if (minutes === 0) return 0;
-  return Math.round((goals / minutes) * 90 * 100) / 100;
-}
-```
+1. **ES6 JavaScript only** — no TypeScript syntax in function body
+2. **Return null when no value** — Hailer rejects empty string `""` with ValidationError. Return `null` instead of `''`. Exception for date/number FFs feeding filters: return `null` not `0` (a `0` fallback makes every empty date a valid timestamp at 1970-01-01).
+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. **Empty string validation** — always return `null` for no-value cases
+8. **Data metadata shorthand** — `type: "="` with `data: ["data"]` returns metadata. Use `"data"` not `"meta"`.
+9. **`linkedFrom()` API does not work in isolated-vm** — use `type: "<"` backlink variables instead
+10. **Return type in .ts file** — always use `: any` as the return type annotation (SDK regex only matches single-word return types)
+11. **Server rejects ALL TypeScript-only constructs:**
+    - Parameter type annotations: `function foo(dep: Dependencies)` → code 191
+    - Union types in local vars: `let maxDate: number | null = null;` → code 191
+    - Typed array literals: `const dates: number[] = [];` → code 191
+    - `as Type` casts in body → code 191
+    - Safe: `// @ts-nocheck` at file top, untyped `let`/`const`, JSDoc comments
+
+    Safe pattern:
+    ```ts
+    // ✗ rejected — param type annotation
+    export function calcTotal(dep: Dependencies): any { ... }
+
+    // ✓ safe
+    export function calcTotal(dep): any { ... }
+
+    let maxDate = 0;  // sentinel — timestamps always > 0
+    return maxDate || null;
+    ```
+
+12. **Same-value dep write does NOT trigger recalc** — Hailer skips re-evaluation when dependency write contains the same value as stored. Toggle the dep through a different value (e.g., `null`) and back to force re-evaluation.
+13. **Don't use `type` or `data` as functionVariables key names** — they collide with the variable schema's own properties. Use descriptive names.
 
-### Same-Activity Field Sum
+---
 
-```typescript
-interface Dependencies {
-  yellowCards: number;
-  redCards: number;
-}
+## Naming Collisions in functionVariables Keys
 
-export function total_cards_XXX(dep: Dependencies): number {
-  return (Number(dep.yellowCards) || 0) + (Number(dep.redCards) || 0);
-}
-```
+Don't use `type` or `data` as a key name. They collide with the variable schema's properties — the function body receives `undefined` or malformed `dep.type`/`dep.data`.
 
-### Conditional Text
+---
 
-```typescript
-interface Dependencies {
-  dueDate: number;
-}
+## Recompute Triggers
 
-export function status_XXX(dep: Dependencies): string {
-  if (!dep.dueDate) return "No due date";
-  if (dep.dueDate < Date.now()) return "Overdue";
-  return "On track";
-}
-```
+**Field-definition change forces full recompute:** A change to `functionVariables` or function body triggers the backend to recompute across ALL existing activities. A plain push with no diff is deep-equal-skipped.
 
-### Exclude Multiple Phases
+**`>` (forward-link) FFs do NOT auto-compute on `v3.activity.createMany`** — they stay null on bulk-seeded data. Trigger a recompute via a field-definition edit.
 
-```typescript
-interface Dependencies {
-  prices: Array<number>;
-  rowMeta: Array<ActivityMeta>;
-  cancelledPhase: string;
-  deletedPhase: string;
-}
+**`<` backlinks recompute in real time** when a child is added, edited, or deleted.
 
-export function sum_excluding_cancelled_XXX(dep: Dependencies): number {
-  const prices = dep.prices || [];
-  const rowMeta = dep.rowMeta || [];
+**Multi-hop FFs** (FF that routes through another FF as intermediate) do NOT recompute on bulk `createMany` — this is a separate confirmed gap.
 
-  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 Name Function Based on Own Phase
+## Bulk Function-Field Push: Use a NOT_INHERITANCE Exclusion Set
 
-```typescript
-interface Dependencies {
-  myMeta: ActivityMeta;
-  donePhase: string;
-  activityName: string;
-}
+When writing a script that auto-discovers function fields and pushes them all with a shared shape, maintain an explicit exclusion set to avoid pushing fields with custom logic using the batch shape (would corrupt them silently).
 
-export function name_with_status_XXX(dep: Dependencies): string {
-  const myPhase = dep.myMeta ? dep.myMeta.phase : null;
-  const prefix = (myPhase === dep.donePhase) ? "done " : "";
-  return prefix + (dep.activityName || "Unnamed");
+```typescript
+const NOT_PUSH_TARGET = new Set([
+  "tilavaraus_phase_sync_fc8",
+  "yhteyshenkiln_yhteystiedot_96d",
+]);
+for (const [key, fn] of discovered) {
+  if (NOT_PUSH_TARGET.has(key)) continue;
+  await pushFunctionField(key, fn);
 }
 ```
 
 ---
 
-## Critical Rules
+## Null Safety Rule
 
-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.
+| Input type | Guard pattern |
+|------------|---------------|
+| Backlink arrays (`<`) | `dep.items \|\| []` |
+| Metadata object | `dep.meta ? dep.meta.phase : null` |
+| String/text field | `dep.name \|\| ''` |
+| Number field | `Number(dep.amount) \|\| 0` |
+| JSON string parse | `dep.json ? JSON.parse(dep.json) : []` — do NOT use `dep.json && JSON.parse(dep.json)`; when `dep.json` is null, `&&` short-circuits to `false`, then `for (const item of false)` throws |
+| Date range | `if (!range \|\| !range.start) return null;` |
+| Nested property | `item && item._id` before accessing |
 
 ---
 
 ## Common Mistakes
 
-| 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 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
+| Wrong | Right |
+|-------|-------|
+| `return ''` when no value | `return null` |
+| `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` |
+| Hardcoding phase IDs | Use `?` static variables with enums |
+| TypeScript syntax in function body | Plain ES6 JS only |
+| `let maxDate: number \| null = null;` | `let maxDate = 0;` (sentinel) |
+| `const dates: number[] = [];` | `const dates = [];` |
+| `export function calc(): string \| null` | `: any` — SDK regex matches single-word return types only |
+| `dep.myLink === 'someId'` | `dep.myLink._id === 'someId'` — activitylink `=` returns object |
+| Using `"meta"` magic key | Use `"data"` — `"meta"` silently returns null |
+| `type: "="` with `"linkedfrom"` | Use `type: "<"` with `[workflowId, "data"]` for reverse links |