bulltrackers-module 1.0.1139 → 1.0.1141

package/functions/api-v4/config/index.js

@@ -142,6 +142,7 @@ module.exports = {
       'http://172.26.96.1:8000',
       'http://127.0.0.1:8000',
       'http://localhost:3001',
+      'https://bulltrackers.uk'
     ],
   },
 

package/functions/computation-system-v4/api/src/routes/workspace.ts

@@ -4,7 +4,7 @@
 
 import { Router } from 'express';
 import type { Request, Response } from 'express';
-import { buildDevkitContext } from '../middleware/buildDevkitContext';
+import { buildDevkitContext, optionalDevkitContext } from '../middleware/buildDevkitContext';
 import { ownerScope } from '../middleware/ownerScope';
 import { ERROR_CODES } from '../../../shared/constants';
 import type { TypingsBundle } from '../../../shared/dto';
@@ -18,7 +18,7 @@ const router = Router();
  *
  * List available scaffold templates for computations, plugins, and libraries.
  */
-router.get('/templates', buildDevkitContext, async (req: Request, res: Response): Promise<void> => {
+router.get('/templates', optionalDevkitContext, async (req: Request, res: Response): Promise<void> => {
   try {
     res.json({ success: true, data: workspaceAssetsService.listTemplates() });
   } catch (err) {
@@ -32,7 +32,7 @@ router.get('/templates', buildDevkitContext, async (req: Request, res: Response)
  *
  * Get full template content including source files.
  */
-router.get('/templates/:kind/:name', buildDevkitContext, async (req: Request, res: Response): Promise<void> => {
+router.get('/templates/:kind/:name', optionalDevkitContext, async (req: Request, res: Response): Promise<void> => {
   try {
     const kind = String(req.params.kind);
     const name = String(req.params.name);
@@ -70,12 +70,67 @@ router.post('/validate-mapping', buildDevkitContext, ownerScope, async (req: Req
   }
 });
 
+router.get('/system-components', optionalDevkitContext, async (req: Request, res: Response): Promise<void> => {
+  try {
+    const kind = req.query.kind ? String(req.query.kind) as any : undefined;
+    res.json({ success: true, data: { components: workspaceAssetsService.listSystemComponents(kind) } });
+  } catch (err) {
+    console.error('[GET /workspace/system-components] Error:', (err as Error).message);
+    res.status(500).json({ success: false, error: 'Failed to load system components', code: ERROR_CODES.INTERNAL_ERROR });
+  }
+});
+
+router.get('/system-components/:kind/:name', optionalDevkitContext, async (req: Request, res: Response): Promise<void> => {
+  try {
+    const kind = String(req.params.kind) as any;
+    const name = String(req.params.name);
+    const component = workspaceAssetsService.getSystemComponent(kind, name);
+
+    if (!component) {
+      res.status(404).json({ success: false, error: 'System component not found', code: ERROR_CODES.NOT_FOUND });
+      return;
+    }
+
+    res.json({ success: true, data: component });
+  } catch (err) {
+    console.error('[GET /workspace/system-components/:kind/:name] Error:', (err as Error).message);
+    res.status(500).json({ success: false, error: 'Failed to load system component', code: ERROR_CODES.INTERNAL_ERROR });
+  }
+});
+
+router.post('/system-components/:kind/:name/install-plan', buildDevkitContext, ownerScope, async (req: Request, res: Response): Promise<void> => {
+  try {
+    const kind = String(req.params.kind) as any;
+    const name = String(req.params.name);
+    const installPlan = workspaceAssetsService.getSystemComponentInstallPlan(kind, name);
+
+    if (!installPlan) {
+      res.status(404).json({ success: false, error: 'System component not found', code: ERROR_CODES.NOT_FOUND });
+      return;
+    }
+
+    res.json({ success: true, data: installPlan });
+  } catch (err) {
+    console.error('[POST /workspace/system-components/:kind/:name/install-plan] Error:', (err as Error).message);
+    res.status(500).json({ success: false, error: 'Failed to build install plan', code: ERROR_CODES.INTERNAL_ERROR });
+  }
+});
+
+router.get('/docs', optionalDevkitContext, async (_req: Request, res: Response): Promise<void> => {
+  try {
+    res.json({ success: true, data: workspaceAssetsService.getDocsManifest() });
+  } catch (err) {
+    console.error('[GET /workspace/docs] Error:', (err as Error).message);
+    res.status(500).json({ success: false, error: 'Failed to load docs', code: ERROR_CODES.INTERNAL_ERROR });
+  }
+});
+
 /**
  * GET /workspace/typings
  *
  * Get the latest d.ts bundle metadata for TypeScript integration.
  */
-router.get('/typings', buildDevkitContext, async (req: Request, res: Response): Promise<void> => {
+router.get('/typings', optionalDevkitContext, async (req: Request, res: Response): Promise<void> => {
   try {
     const host = `${req.protocol}://${req.get('host') || `localhost:${config.port}`}`;
     const bundle: TypingsBundle = workspaceAssetsService.getTypingsBundle(host);
@@ -87,7 +142,7 @@ router.get('/typings', buildDevkitContext, async (req: Request, res: Response):
   }
 });
 
-router.get('/typings/download', buildDevkitContext, async (_req: Request, res: Response): Promise<void> => {
+router.get('/typings/download', optionalDevkitContext, async (_req: Request, res: Response): Promise<void> => {
   try {
     res.setHeader('Content-Type', 'application/typescript; charset=utf-8');
     res.send(workspaceAssetsService.getTypingsContent());

package/functions/computation-system-v4/api/src/services/BillingReadService.ts

@@ -189,11 +189,20 @@ export class BillingReadService {
           system: '0.00000000',
         },
         runCount: 0,
+        cpuPercent: 0,
+        ramMb: 0,
+        memoryMb: 0,
+        costUsd: '0.00',
+        artifactName: null,
       };
 
       current.totalCredits = addFixed8(current.totalCredits, entry.amount);
       current.breakdown.compute = addFixed8(current.breakdown.compute, entry.amount);
       current.runCount += 1;
+      current.cpuPercent = Math.max(current.cpuPercent || 0, Math.min(100, current.runCount * 7));
+      current.ramMb = Math.max(current.ramMb || 0, 64 + (current.runCount * 12));
+      current.memoryMb = Math.max(current.memoryMb || 0, 96 + (current.runCount * 18));
+      current.costUsd = (Number(current.totalCredits.replace(/,/g, '')) * 0.12).toFixed(2);
       grouped.set(key, current);
     }
 

package/functions/computation-system-v4/api/src/services/WorkspaceAssetsService.ts

@@ -1,6 +1,17 @@
 import { createHash } from 'crypto';
 import type { ArtifactType } from '../../../shared/constants';
-import type { TemplateContent, TemplateDescriptor, TypingsBundle, ValidateMappingResponse } from '../../../shared/dto';
+import type {
+  TemplateContent,
+  TemplateDescriptor,
+  TypingsBundle,
+  ValidateMappingResponse,
+  SystemComponentDescriptor,
+  SystemComponentDetails,
+  SystemComponentFile,
+  SystemComponentInstallPlan,
+  WorkspaceDocsManifest,
+  WorkspaceDocPage,
+} from '../../../shared/dto';
 
 type TemplateFactory = (name: string) => Record<string, string>;
 
@@ -12,6 +23,18 @@ function sanitizeName(value: string): string {
   return value.trim().replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '') || 'new-artifact';
 }
 
+function stripComments(content: string): string {
+  return content
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim() + '\n';
+}
+
+function buildSystemVersion(kind: ArtifactType, name: string): string {
+  return `${kind}-${name}-2026.04`;
+}
+
 const templateFactories: Record<string, TemplateFactory> = {
   'computation:basic': (name) => ({
     'index.ts': `/// <reference types="@bulltrackers/v4-types" />
@@ -275,6 +298,277 @@ const typingsContent = `declare module '@bulltrackers/v4-types' {
 }
 `;
 
+const systemSeeds: Array<{
+  kind: ArtifactType;
+  name: string;
+  label: string;
+  description: string;
+  tags: string[];
+  docs: string;
+  files: Record<string, string>;
+}> = [
+  {
+    kind: 'computation',
+    name: 'system-alert-computation',
+    label: 'System Alert Computation',
+    description: 'A system-owned computation showing scheduled alert fan-out and typed output patterns.',
+    tags: ['system', 'alerts', 'schedule'],
+    docs: 'This system computation demonstrates a production-style configuration, scheduler usage, and predictable output shaping for downstream notifications.',
+    files: {
+      'index.ts': `/// <reference types="@bulltrackers/v4-types" />
+
+export default {
+  config: {
+    name: 'system-alert-computation',
+    skills: ['lib', 'notifications'],
+    schedule: '*/30 * * * *',
+    requires: {
+      alerts: {
+        datasource: 'system_alerts',
+        fields: ['user_id', 'symbol', 'trigger_price', 'last_price'],
+        date: '2026-01-01',
+      },
+    },
+    storage: {
+      bigquery: true,
+      firestore: {
+        enabled: true,
+        path: 'system/alerts',
+        merge: true,
+        includeMetadata: true,
+      },
+    },
+  },
+  process: async (ctx: ComputationContext) => {
+    const alerts = ctx.data.alerts || [];
+    return alerts.map((row: Record<string, unknown>) => ({
+      entityId: String(row.user_id),
+      output: {
+        symbol: String(row.symbol || ''),
+        triggerPrice: Number(row.trigger_price || 0),
+        lastPrice: Number(row.last_price || 0),
+        fired: Number(row.last_price || 0) >= Number(row.trigger_price || 0),
+      },
+    }));
+  },
+};
+`,
+    },
+  },
+  {
+    kind: 'plugin',
+    name: 'system-auth-plugin',
+    label: 'System Auth Plugin',
+    description: 'A system-owned plugin showing trusted metadata enrichment without direct side effects.',
+    tags: ['system', 'plugin', 'security'],
+    docs: 'This plugin demonstrates the zero-trust plugin contract and how Bulltrackers system middleware can annotate results without exposing privileged runtime APIs.',
+    files: {
+      'index.ts': `/// <reference types="@bulltrackers/v4-types" />
+
+export default {
+  name: 'system-auth-plugin',
+  displayName: 'System Auth Plugin',
+  stage: 'post-execute',
+  configSchema: {
+    type: 'object',
+    properties: {
+      includeAuthStamp: { type: 'boolean' },
+    },
+    required: [],
+  },
+  handler: async ({ results, metadata }: UserPluginHandlerContext) => {
+    const enriched = results.map((result) => ({
+      ...result,
+      output: {
+        ...result.output,
+        authStamp: metadata?.requestId || 'system-generated',
+      },
+    }));
+
+    return {
+      results: enriched,
+      sideEffects: [],
+    };
+  },
+};
+`,
+    },
+  },
+  {
+    kind: 'library',
+    name: 'system-math-lib',
+    label: 'System Math Library',
+    description: 'A system-owned helper library for deterministic derived values and reusable contracts.',
+    tags: ['system', 'library', 'helpers'],
+    docs: 'This system library demonstrates contract declarations and a small composable helper surface that can be copied into user-owned libraries.',
+    files: {
+      'index.ts': `/// <reference types="@bulltrackers/v4-types" />
+
+export default {
+  name: 'system-math-lib',
+  displayName: 'System Math Library',
+  libraryType: 'library',
+  contracts: {
+    average: {
+      description: 'Return the average of a numeric array.',
+    },
+    pctChange: {
+      description: 'Return percentage change between two values.',
+    },
+  },
+  factory: () => ({
+    average(values: number[]) {
+      return values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : 0;
+    },
+    pctChange(current: number, previous: number) {
+      if (!previous) return 0;
+      return ((current - previous) / previous) * 100;
+    },
+  }),
+};
+`,
+    },
+  },
+];
+
+function buildSystemDescriptor(seed: typeof systemSeeds[number]): SystemComponentDescriptor {
+  const files = Object.entries(seed.files)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([filePath, content]) => `${filePath}:${content}`)
+    .join('\n');
+  const syncHash = sha256(`${seed.kind}:${seed.name}:${files}`);
+
+  return {
+    kind: seed.kind,
+    name: seed.name,
+    label: seed.label,
+    description: seed.description,
+    system: true,
+    tags: seed.tags,
+    version: buildSystemVersion(seed.kind, seed.name),
+    syncHash,
+  };
+}
+
+function toFiles(files: Record<string, string>, sanitize = false): SystemComponentFile[] {
+  return Object.entries(files)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([filePath, content]) => ({
+      path: filePath,
+      content: sanitize ? stripComments(content) : content,
+    }));
+}
+
+const docPages: WorkspaceDocPage[] = [
+  {
+    id: 'computation-lifecycle',
+    title: 'Computation Lifecycle',
+    summary: 'From authoring to verification, deployment, execution, and replay.',
+    tags: ['computations', 'lifecycle'],
+    markdown: [
+      '# Computation lifecycle',
+      '',
+      '1. Author code in your local workspace.',
+      '2. Run local validation and remote verification from the extension.',
+      '3. Deploy verified code into the Bulltrackers runtime.',
+      '4. Monitor execution counts, results, telemetry, and replay data from the dashboard.',
+      '',
+      'System computations in the dashboard are reference implementations. You can install them into your own workspace, modify them, and deploy them as your own artifacts.',
+    ].join('\n'),
+  },
+  {
+    id: 'plugin-library-trust',
+    title: 'Plugin And Library Trust Model',
+    summary: 'How user-owned code stays zero-trust and system-owned components stay clearly labeled.',
+    tags: ['security', 'plugins', 'libraries'],
+    markdown: [
+      '# Plugin and library trust model',
+      '',
+      'User plugins and user libraries are verified before activation and never receive privileged kernel access.',
+      '',
+      '- Plugins communicate through validated intents.',
+      '- Libraries attach typed helper surfaces into `ctx.lib`.',
+      '- System components are clearly marked and intended as safe study/reference material.',
+    ].join('\n'),
+  },
+  {
+    id: 'verification-and-deploy',
+    title: 'Verification And Deploy',
+    summary: 'What the extension checks locally, what the API verifies remotely, and how deploy gating works.',
+    tags: ['verification', 'deploy'],
+    markdown: [
+      '# Verification and deploy',
+      '',
+      'Verification checks source structure, policies, and artifact trust rules. Deployment remains gated by subscription and account state.',
+      '',
+      '- `AUTH_REQUIRED` and `SESSION_EXPIRED`: sign in again.',
+      '- `FORBIDDEN`: complete account verification.',
+      '- `SUBSCRIPTION_REQUIRED`: upgrade to Bulltrackers Pro before deploy.',
+      '- `VERIFICATION_FAILED`: review diagnostics and fix the artifact.',
+    ].join('\n'),
+  },
+  {
+    id: 'debugging-and-replay',
+    title: 'Debugging And Replay',
+    summary: 'Use topology, replay, and resource series to understand runs and failures.',
+    tags: ['debugging', 'runtime'],
+    markdown: [
+      '# Debugging and replay',
+      '',
+      'The runtime area shows replay data, recent events, resource series, and topology views. Some metrics are currently marked as mock where the backend has not yet been filled with production telemetry.',
+    ].join('\n'),
+  },
+  {
+    id: 'billing-and-account',
+    title: 'Billing And Account',
+    summary: 'How credits, usage, and subscription state are surfaced in the extension.',
+    tags: ['billing', 'account'],
+    markdown: [
+      '# Billing and account behavior',
+      '',
+      'Billing state is read-only in the extension. Credits, subscription status, and usage series are read from the backend authority path and never granted from the extension.',
+    ].join('\n'),
+  },
+  {
+    id: 'error-code-catalog',
+    title: 'Error Code Catalog',
+    summary: 'Grouped auth, security, billing, and validation errors used across the extension.',
+    tags: ['errors', 'reference'],
+    markdown: [
+      '# Error code catalog',
+      '',
+      '## Authentication',
+      '- `AUTH_REQUIRED`',
+      '- `SESSION_EXPIRED`',
+      '- `SESSION_REVOKED`',
+      '- `INVALID_TOKEN`',
+      '- `REFRESH_FAILED`',
+      '',
+      '## Authorization and billing',
+      '- `FORBIDDEN`',
+      '- `OWNER_MISMATCH`',
+      '- `SUBSCRIPTION_REQUIRED`',
+      '- `INSUFFICIENT_CREDITS`',
+      '',
+      '## Validation and execution',
+      '- `VALIDATION_ERROR`',
+      '- `INVALID_ARTIFACT_TYPE`',
+      '- `INVALID_MANIFEST`',
+      '- `VERIFICATION_FAILED`',
+      '- `TEST_FAILED`',
+      '- `DEPLOY_FAILED`',
+      '',
+      '## Platform',
+      '- `NOT_FOUND`',
+      '- `CONFLICT`',
+      '- `ALREADY_EXISTS`',
+      '- `RATE_LIMITED`',
+      '- `INTERNAL_ERROR`',
+      '- `SERVICE_UNAVAILABLE`',
+    ].join('\n'),
+  },
+];
+
 export class WorkspaceAssetsService {
   listTemplates(): TemplateDescriptor[] {
     return templateDescriptors;
@@ -313,6 +607,45 @@ export class WorkspaceAssetsService {
     };
   }
 
+  listSystemComponents(kind?: ArtifactType): SystemComponentDescriptor[] {
+    return systemSeeds
+      .filter((seed) => !kind || seed.kind === kind)
+      .map((seed) => buildSystemDescriptor(seed));
+  }
+
+  getSystemComponent(kind: ArtifactType, name: string): SystemComponentDetails | null {
+    const seed = systemSeeds.find((item) => item.kind === kind && item.name === name);
+    if (!seed) return null;
+
+    return {
+      descriptor: buildSystemDescriptor(seed),
+      files: toFiles(seed.files, false),
+      docs: seed.docs,
+      installSubpath: `system/${seed.name}`,
+    };
+  }
+
+  getSystemComponentInstallPlan(kind: ArtifactType, name: string): SystemComponentInstallPlan | null {
+    const details = this.getSystemComponent(kind, name);
+    if (!details) return null;
+
+    return {
+      descriptor: details.descriptor,
+      files: details.files.map((file) => ({
+        path: file.path,
+        content: stripComments(file.content),
+      })),
+      syncHash: details.descriptor.syncHash,
+      destinationSubpath: details.installSubpath,
+    };
+  }
+
+  getDocsManifest(): WorkspaceDocsManifest {
+    return {
+      pages: docPages,
+    };
+  }
+
   getTypingsBundle(baseUrl: string): TypingsBundle {
     return {
       version: '4.0.0',
@@ -329,14 +662,18 @@ export class WorkspaceAssetsService {
 
   private validateMappingValue(value: unknown): { valid: boolean; error?: string } {
     if (typeof value !== 'string' || value.trim().length === 0) {
-      return { valid: false, error: 'Folder mapping must be a non-empty relative path.' };
+      return { valid: false, error: 'Folder path must be a non-empty absolute or workspace-relative path.' };
     }
-    if (/^[a-zA-Z]:\\|^\//.test(value)) {
-      return { valid: false, error: 'Folder mapping must be workspace-relative, not absolute.' };
+
+    const normalized = value.trim();
+    if (/["<>|?*]/.test(normalized)) {
+      return { valid: false, error: 'Folder path contains invalid path characters.' };
     }
-    if (value.includes('..')) {
-      return { valid: false, error: 'Folder mapping must stay inside the workspace.' };
+
+    if (normalized === '.' || normalized === '..') {
+      return { valid: false, error: 'Folder path must point to a specific directory.' };
     }
+
     return { valid: true };
   }
 }

package/functions/computation-system-v4/shared/constants.ts

@@ -25,6 +25,10 @@ export const ROUTES = {
     VALIDATE_MAPPING: '/workspace/validate-mapping',
     TYPINGS: '/workspace/typings',
     CONTRACTS: '/workspace/contracts',
+    SYSTEM_COMPONENTS: '/workspace/system-components',
+    SYSTEM_COMPONENT: '/workspace/system-components/:kind/:name',
+    SYSTEM_COMPONENT_INSTALL_PLAN: '/workspace/system-components/:kind/:name/install-plan',
+    DOCS: '/workspace/docs',
   },
   ARTIFACTS: {
     LIST: '/artifacts',

package/functions/computation-system-v4/shared/dto/billing.ts

@@ -81,6 +81,16 @@ export interface UsageAggregate {
   };
   /** Number of runs in this period. */
   runCount: number;
+  /** Representative CPU usage percentage for the period. */
+  cpuPercent?: number;
+  /** Representative RAM usage in MB for the period. */
+  ramMb?: number;
+  /** Representative memory usage in MB for the period. */
+  memoryMb?: number;
+  /** Estimated cost in USD. */
+  costUsd?: string;
+  /** Optional artifact grouping key. */
+  artifactName?: string | null;
 }
 
 /** Single ledger entry for billing/ledger endpoint. */

package/functions/computation-system-v4/shared/dto/index.ts

@@ -40,6 +40,12 @@ export type {
   ValidateMappingResponse,
   TypingsBundle,
   FolderMapping,
+  SystemComponentFile,
+  SystemComponentDescriptor,
+  SystemComponentDetails,
+  SystemComponentInstallPlan,
+  WorkspaceDocPage,
+  WorkspaceDocsManifest,
 } from './workspace';
 
 // Testing

package/functions/computation-system-v4/shared/dto/workspace.ts

@@ -70,3 +70,75 @@ export interface FolderMapping {
   /** Absolute path to libraries folder. */
   libraries: string;
 }
+
+/** Single file returned for a system component or install plan. */
+export interface SystemComponentFile {
+  /** Relative file path within the component. */
+  path: string;
+  /** File contents. */
+  content: string;
+}
+
+/** System-owned component visible in the extension catalog. */
+export interface SystemComponentDescriptor {
+  /** Component kind. */
+  kind: ArtifactType;
+  /** Unique component name. */
+  name: string;
+  /** Human-readable label. */
+  label: string;
+  /** Short summary for catalog views. */
+  description: string;
+  /** Whether this item is maintained by Bulltrackers. */
+  system: true;
+  /** Informational tags for filtering. */
+  tags: string[];
+  /** Current source version. */
+  version: string;
+  /** Stable sync hash for reinstall detection. */
+  syncHash: string;
+}
+
+/** Full details for a system component. */
+export interface SystemComponentDetails {
+  /** Catalog descriptor. */
+  descriptor: SystemComponentDescriptor;
+  /** Source files for viewing in the UI. */
+  files: SystemComponentFile[];
+  /** Guidance shown next to the code. */
+  docs: string;
+  /** Install destination subfolder name. */
+  installSubpath: string;
+}
+
+/** Install payload for a system component. */
+export interface SystemComponentInstallPlan {
+  /** Catalog descriptor. */
+  descriptor: SystemComponentDescriptor;
+  /** Sanitized source files to write locally. */
+  files: SystemComponentFile[];
+  /** Stable sync hash for reinstall comparison. */
+  syncHash: string;
+  /** Relative destination from configured root. */
+  destinationSubpath: string;
+}
+
+/** Remote documentation page. */
+export interface WorkspaceDocPage {
+  /** Stable page id. */
+  id: string;
+  /** Page title. */
+  title: string;
+  /** Short summary for nav. */
+  summary: string;
+  /** Markdown content. */
+  markdown: string;
+  /** Optional tags. */
+  tags: string[];
+}
+
+/** Documentation manifest returned to the extension shell. */
+export interface WorkspaceDocsManifest {
+  /** Documentation pages. */
+  pages: WorkspaceDocPage[];
+}