bulltrackers-module 1.0.995 → 1.0.996

package/functions/api-v3/routes/workspace.js

@@ -4,11 +4,32 @@
  */
 
 const express = require('express');
+const fs = require('fs');
+const path = require('path');
 const config = require('../config');
 const { requireVerifiedUser } = require('../middleware/identity');
 const { requireFirebaseAuth } = require('../middleware/auth');
 const { generateDynamicPaths } = require('./workspace-generator');
 
+const FRAMEWORK_ROOT = path.join(__dirname, '../../computation-system-v3/framework');
+
+// Read-only sample computation templates that we copy into each user's
+// editable `computations/` directory on first bootstrap.
+const SAMPLE_COMPUTATION_TEMPLATES = [
+    {
+        source: 'docs/authoring/sample-computations/grade1-portfolio-summary.js',
+        target: 'computations/Sample_PortfolioDailySummary_Grade1.js'
+    },
+    {
+        source: 'docs/authoring/sample-computations/grade2-entity-risk-change.js',
+        target: 'computations/Sample_EntityRiskChange_Grade2.js'
+    },
+    {
+        source: 'docs/authoring/sample-computations/grade3-alert-on-risk-spike.js',
+        target: 'computations/Sample_RiskSpikeAlerts_Grade3.js'
+    }
+];
+
 const MAX_PATHS_PER_USER = 500;
 const MAX_FILE_BYTES = 512 * 1024;
 const MAX_TOTAL_BYTES = 5 * 1024 * 1024;
@@ -147,21 +168,48 @@ function createWorkspaceRouter() {
         }
     });
 
-    // POST /workspace/bootstrap — Only initializes user directories now!
+    // POST /workspace/bootstrap — Initializes user directories and sample computations.
     router.post('/bootstrap', requireVerifiedUser, async (req, res, next) => {
         try {
             const userId = (req.identity && req.identity.cid) || req.targetUserId;
             const ref = req.services.db.collection('users').doc(userId).collection('workspace_files');
             const snap = await ref.get();
 
-            // We only need to bootstrap user-editable files now. 
+            // We only need to bootstrap user-editable files now.
             // The read-only registry is automatically served in /tree and /file.
-            const userPaths = [
-                { path: 'computations', kind: 'directory', content: null }
-            ];
+            const userPaths = [{ path: 'computations', kind: 'directory', content: null }];
+
+            // Pre-populate the computations/ directory with three fully documented,
+            // valid sample computations. The source of truth lives under
+            // computation-system-v3/framework/docs/authoring/sample-computations/*.
+            const sampleFiles = [];
+            for (const template of SAMPLE_COMPUTATION_TEMPLATES) {
+                const absolute = path.join(FRAMEWORK_ROOT, template.source);
+                try {
+                    if (fs.existsSync(absolute)) {
+                        const content = fs.readFileSync(absolute, 'utf8');
+                        sampleFiles.push({
+                            path: template.target,
+                            kind: 'file',
+                            content
+                        });
+                    }
+                } catch (e) {
+                    // If a template cannot be read, skip it; bootstrap should still succeed.
+                    // The admin can fix the underlying file and re-bootstrap later.
+                    // eslint-disable-next-line no-console
+                    console.error(
+                        '[workspace.bootstrap] Failed to read sample computation template',
+                        template.source,
+                        e && e.message
+                    );
+                }
+            }
 
             const now = new Date().toISOString();
-            for (const item of userPaths) {
+            const bootstrapItems = [...userPaths, ...sampleFiles];
+
+            for (const item of bootstrapItems) {
                 const existing = snap.docs.find((d) => (d.data().path || d.id.replace(/__/g, '/')) === item.path);
                 if (existing) continue;
 

package/functions/computation-system-v3/framework/doc-registry.js

@@ -49,6 +49,13 @@ const REGISTERED_FILES = [
     'docs/modules/trades.md',
     'docs/modules/userMetrics.md',
 
+    // ── Authoring Samples ──────────────────────────────────────────────────────────
+    // These are read-only, fully documented example computations that are also used
+    // as templates for pre-populating the user's `computations/` directory.
+    'docs/authoring/sample-computations/grade1-portfolio-summary.js',
+    'docs/authoring/sample-computations/grade2-entity-risk-change.js',
+    'docs/authoring/sample-computations/grade3-alert-on-risk-spike.js',
+
     // ── SQL Reference ─────────────────────────────────────────────────────────────
     'docs/sql/annotated-sql.md',
 

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade1-portfolio-summary.js

@@ -0,0 +1,93 @@
+/**
+ * Grade 1 sample computation — Daily portfolio value summary.
+ *
+ * This is a deliberately small, linear example that shows:
+ *   - How to declare a minimal `config` for a user computation.
+ *   - How to read from `ctx.data` using the keys defined in `config.requires`.
+ *   - How to log a short, human-readable trace line via `ctx.log`.
+ *   - How to return a safe, envelope-compatible result object (no reserved keys).
+ *
+ * The goal is to be a "perfect role model" for new authors, not to be clever.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `name` is globally unique per tenant and used in scheduling / storage paths.
+ * - `skills: ['lib']` enables read-only helper libraries on `ctx.lib` (not used here,
+ *   but included so users see the recommended default).
+ * - `requires.portfolio_snapshots` declares the data this computation expects:
+ *   a recent window of portfolio snapshots with `date` + `total_value` fields.
+ * - `storage.bigquery: true` means the framework will persist results to BigQuery
+ *   under the standard `computations` dataset for this tenant.
+ */
+exports.config = {
+    name: 'Sample_PortfolioDailySummary_Grade1',
+    skills: ['lib'],
+    lib: [],
+    requires: {
+        portfolio_snapshots: {
+            // The runtime will fetch up to 7 days of snapshots ending at ctx.date.
+            lookback: 7,
+            mandatory: true,
+            fields: ['date', 'total_value']
+        }
+    },
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — called by the runtime for a single execution target.
+ *
+ * Signature:
+ *   - ctx.computation: string  → the value of config.name.
+ *   - ctx.date: string         → ISO date (YYYY-MM-DD) the run is targeting.
+ *   - ctx.data: object         → data fetched according to `config.requires`.
+ *   - ctx.log: (message) => void → structured log helper scoped to this computation.
+ *
+ * Behaviour:
+ *   1. Read the `portfolio_snapshots` array from ctx.data.
+ *   2. Filter out rows that do not have a finite numeric `total_value`.
+ *   3. Compute a simple count and average total value over the window.
+ *   4. Log a short summary line with the number of snapshots analysed.
+ *   5. Return a result object with:
+ *        - outcome: high-level status code for domain logic ("OK" or "NO_DATA").
+ *        - asOfDate: the target date for the run.
+ *        - snapshotCount: how many rows were actually used.
+ *        - averagePortfolioValue: null if there was no valid data.
+ */
+exports.process = function process(ctx) {
+    const snapshots = Array.isArray(ctx.data && ctx.data.portfolio_snapshots)
+        ? ctx.data.portfolio_snapshots
+        : [];
+
+    const numericValues = [];
+    for (const row of snapshots) {
+        const raw = row && row.total_value;
+        const value = typeof raw === 'number' ? raw : Number(raw);
+        if (Number.isFinite(value)) {
+            numericValues.push(value);
+        }
+    }
+
+    const snapshotCount = numericValues.length;
+    const averagePortfolioValue =
+        snapshotCount === 0
+            ? null
+            : numericValues.reduce((sum, value) => sum + value, 0) / snapshotCount;
+
+    ctx.log(
+        `[Sample_PortfolioDailySummary_Grade1] analysed ${snapshotCount} snapshot(s) for ${ctx.date}`
+    );
+
+    return {
+        // Use a domain-level outcome key; never use reserved keys like `status` or `error`.
+        outcome: snapshotCount === 0 ? 'NO_DATA' : 'OK',
+        asOfDate: ctx.date,
+        snapshotCount,
+        averagePortfolioValue
+    };
+};
+

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade2-entity-risk-change.js

@@ -0,0 +1,145 @@
+/**
+ * Grade 2 sample computation — Per-entity risk change over a rolling window.
+ *
+ * This example builds on the Grade 1 sample by:
+ *   - Operating in a clearly per-entity way (each entity is evaluated independently).
+ *   - Working with two logical inputs (`risk_snapshots` and `portfolio_snapshots`).
+ *   - Computing a small derived metric (risk delta) per entity.
+ *   - Demonstrating safe handling of missing / partial data.
+ *
+ * It is still intentionally linear and readable; the comments explain each step so that
+ * new authors can copy this pattern when adding their own logic.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `name` uniquely identifies this computation.
+ * - `type: 'per-entity'` tells the runtime to run once per entity (e.g. per portfolio).
+ * - `requires.risk_snapshots` and `requires.portfolio_snapshots` declare the inputs.
+ * - `storage.bigquery: true` persists the result into tenant-scoped BigQuery tables.
+ */
+exports.config = {
+    name: 'Sample_EntityRiskChange_Grade2',
+    type: 'per-entity',
+    skills: ['lib'],
+    lib: [],
+    requires: {
+        risk_snapshots: {
+            // 30-day lookback window of per-entity risk scores.
+            lookback: 30,
+            mandatory: true,
+            fields: ['date', 'entity_id', 'risk_score']
+        },
+        portfolio_snapshots: {
+            // Optional: we only need a name/label for display purposes.
+            lookback: 1,
+            mandatory: false,
+            fields: ['entity_id', 'display_name']
+        }
+    },
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — computes the change in risk score for a single entity.
+ *
+ * For each entity on a given date:
+ *   1. Filter the `risk_snapshots` array down to the current entityId (if provided).
+ *   2. Sort snapshots by date to find the "previous" and "current" entries.
+ *   3. Compute a simple delta: current_risk - previous_risk.
+ *   4. Look up a human-readable portfolio name from `portfolio_snapshots` if present.
+ *   5. Return a single object that describes today's risk position for this entity.
+ */
+exports.process = function process(ctx) {
+    const entityId = ctx.entityId;
+
+    const allRiskSnapshots = Array.isArray(ctx.data && ctx.data.risk_snapshots)
+        ? ctx.data.risk_snapshots
+        : [];
+
+    // Step 1: isolate this entity's rows (or all rows if entityId is not provided).
+    const entityRiskRows = allRiskSnapshots.filter((row) => {
+        if (!row) return false;
+        if (entityId == null) return true;
+        return String(row.entity_id) === String(entityId);
+    });
+
+    // Step 2: sort by date ascending so the last element is the most recent snapshot.
+    entityRiskRows.sort((a, b) => {
+        const ad = a && a.date ? String(a.date) : '';
+        const bd = b && b.date ? String(b.date) : '';
+        return ad.localeCompare(bd);
+    });
+
+    const rowCount = entityRiskRows.length;
+    if (rowCount === 0) {
+        ctx.log(
+            `[Sample_EntityRiskChange_Grade2] no risk_snapshots found for entity ${String(
+                entityId || 'GLOBAL'
+            )} on ${ctx.date}`
+        );
+
+        return {
+            outcome: 'NO_DATA',
+            asOfDate: ctx.date,
+            entityId: entityId || null,
+            currentRisk: null,
+            previousRisk: null,
+            riskDelta: null
+        };
+    }
+
+    const latest = entityRiskRows[rowCount - 1];
+    const previous = rowCount > 1 ? entityRiskRows[rowCount - 2] : null;
+
+    const currentRisk =
+        latest && typeof latest.risk_score === 'number'
+            ? latest.risk_score
+            : Number(latest && latest.risk_score);
+    const previousRisk =
+        previous && typeof previous.risk_score === 'number'
+            ? previous.risk_score
+            : Number(previous && previous.risk_score);
+
+    const safeCurrent = Number.isFinite(currentRisk) ? currentRisk : null;
+    const safePrevious = Number.isFinite(previousRisk) ? previousRisk : null;
+
+    let riskDelta = null;
+    if (safeCurrent != null && safePrevious != null) {
+        riskDelta = safeCurrent - safePrevious;
+    }
+
+    // Optional: look up a display name from portfolio_snapshots for nicer reporting.
+    let portfolioName = null;
+    const portfolioRows = Array.isArray(ctx.data && ctx.data.portfolio_snapshots)
+        ? ctx.data.portfolio_snapshots
+        : [];
+    const matchingPortfolio = portfolioRows.find((row) => {
+        if (!row) return false;
+        if (entityId == null) return false;
+        return String(row.entity_id) === String(entityId);
+    });
+    if (matchingPortfolio && typeof matchingPortfolio.display_name === 'string') {
+        portfolioName = matchingPortfolio.display_name;
+    }
+
+    ctx.log(
+        `[Sample_EntityRiskChange_Grade2] entity ${String(
+            entityId || 'GLOBAL'
+        )} risk=${safeCurrent} (delta=${riskDelta}) on ${ctx.date}`
+    );
+
+    return {
+        outcome: 'OK',
+        asOfDate: ctx.date,
+        entityId: entityId || null,
+        portfolioName,
+        currentRisk: safeCurrent,
+        previousRisk: safePrevious,
+        riskDelta
+    };
+};
+

package/functions/computation-system-v3/framework/docs/authoring/sample-computations/grade3-alert-on-risk-spike.js

@@ -0,0 +1,102 @@
+/**
+ * Grade 3 sample computation — Simple alert surface for risk spikes.
+ *
+ * This example is intentionally still single-file and easy to read, but it
+ * shows a slightly more "production-like" pattern:
+ *   - It depends on the Grade 2 computation's result by name via `dependencies`.
+ *   - It treats the upstream result as an input table in `requires`.
+ *   - It emits a compact list of "alerts" that could be consumed by downstream
+ *     dashboards or notification systems.
+ *
+ * This is not wired into any real alerting system; it is a didactic example
+ * that demonstrates how to compose computations safely.
+ */
+
+/**
+ * Configuration object for the computation.
+ *
+ * - `dependencies` lists another computation by name. The planner ensures that
+ *   the dependency runs first for the target date / entity set before this one.
+ * - `requires.entity_risk_change` models the dependency's output as a table-like
+ *   input; in a real deployment this would be backed by storage (e.g. BigQuery).
+ */
+exports.config = {
+    name: 'Sample_RiskSpikeAlerts_Grade3',
+    skills: ['lib'],
+    lib: [],
+    dependencies: ['Sample_EntityRiskChange_Grade2'],
+    requires: {
+        entity_risk_change: {
+            // The runtime will typically resolve this from the dependency's output.
+            lookback: 1,
+            mandatory: true,
+            fields: [
+                'asOfDate',
+                'entityId',
+                'portfolioName',
+                'currentRisk',
+                'previousRisk',
+                'riskDelta'
+            ]
+        }
+    },
+    storage: {
+        bigquery: true
+    }
+};
+
+/**
+ * Process function — builds a list of simple alert objects when risk jumps.
+ *
+ * Behaviour:
+ *   1. Read the `entity_risk_change` rows for the current date.
+ *   2. Filter to entities whose absolute riskDelta is above a fixed threshold.
+ *   3. Map each row to a small, explicit alert object.
+ *   4. Return a payload containing:
+ *        - outcome: "OK" or "NO_ALERTS".
+ *        - asOfDate: the date we evaluated.
+ *        - alerts: array of alert objects (possibly empty).
+ *
+ * NOTE: This computation does not send notifications itself; it produces clean,
+ * queryable data that other systems can use as a source of truth.
+ */
+exports.process = function process(ctx) {
+    const rows = Array.isArray(ctx.data && ctx.data.entity_risk_change)
+        ? ctx.data.entity_risk_change
+        : [];
+
+    const THRESHOLD = 5; // Example threshold for a "meaningful" risk move.
+
+    const alerts = [];
+    for (const row of rows) {
+        if (!row) continue;
+
+        const delta = row.riskDelta;
+        if (!Number.isFinite(delta)) continue;
+
+        if (Math.abs(delta) < THRESHOLD) {
+            continue;
+        }
+
+        alerts.push({
+            entityId: row.entityId || null,
+            portfolioName: typeof row.portfolioName === 'string' ? row.portfolioName : null,
+            asOfDate: row.asOfDate || ctx.date,
+            currentRisk: Number.isFinite(row.currentRisk) ? row.currentRisk : null,
+            previousRisk: Number.isFinite(row.previousRisk) ? row.previousRisk : null,
+            riskDelta: delta,
+            direction: delta > 0 ? 'INCREASE' : 'DECREASE'
+        });
+    }
+
+    ctx.log(
+        `[Sample_RiskSpikeAlerts_Grade3] generated ${alerts.length} alert(s) for ${ctx.date} with threshold ${THRESHOLD}`
+    );
+
+    return {
+        outcome: alerts.length === 0 ? 'NO_ALERTS' : 'OK',
+        asOfDate: ctx.date,
+        alerts
+    };
+};
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulltrackers-module",
-  "version": "1.0.995",
+  "version": "1.0.996",
   "description": "Helper Functions for Bulltrackers.",
   "main": "index.js",
   "files": [