@advicenxt/sbp-server 0.1.0

package/src/types.ts

@@ -0,0 +1,314 @@
+/**
+ * SBP Core Types
+ * Stigmergic Blackboard Protocol v0.1
+ */
+
+// ============================================================================
+// DECAY MODELS
+// ============================================================================
+
+export interface ExponentialDecay {
+  type: "exponential";
+  half_life_ms: number;
+}
+
+export interface LinearDecay {
+  type: "linear";
+  rate_per_ms: number;
+}
+
+export interface StepDecay {
+  type: "step";
+  steps: Array<{ at_ms: number; intensity: number }>;
+}
+
+export interface ImmortalDecay {
+  type: "immortal";
+}
+
+export type DecayModel = ExponentialDecay | LinearDecay | StepDecay | ImmortalDecay;
+
+// ============================================================================
+// PHEROMONE
+// ============================================================================
+
+export interface Pheromone {
+  id: string;
+  trail: string;
+  type: string;
+  emitted_at: number;
+  last_reinforced_at: number;
+  initial_intensity: number;
+  decay_model: DecayModel;
+  payload: Record<string, unknown>;
+  source_agent?: string;
+  tags: string[];
+  ttl_floor: number;
+}
+
+export interface PheromoneSnapshot {
+  id: string;
+  trail: string;
+  type: string;
+  current_intensity: number;
+  payload: Record<string, unknown>;
+  age_ms: number;
+  tags: string[];
+}
+
+// ============================================================================
+// TAG FILTERING
+// ============================================================================
+
+export interface TagFilter {
+  any?: string[];
+  all?: string[];
+  none?: string[];
+}
+
+// ============================================================================
+// SCENT CONDITIONS
+// ============================================================================
+
+export interface ThresholdCondition {
+  type: "threshold";
+  trail: string;
+  signal_type: string;
+  tags?: TagFilter;
+  aggregation: "sum" | "max" | "avg" | "count" | "any";
+  operator: ">=" | ">" | "<=" | "<" | "==" | "!=";
+  value: number;
+}
+
+export interface CompositeCondition {
+  type: "composite";
+  operator: "and" | "or" | "not";
+  conditions: ScentCondition[];
+}
+
+export interface RateCondition {
+  type: "rate";
+  trail: string;
+  signal_type: string;
+  metric: "emissions_per_second" | "intensity_delta";
+  window_ms: number;
+  operator: ">=" | ">" | "<=" | "<";
+  value: number;
+}
+
+export interface PatternCondition {
+  type: "pattern";
+  /** Sequence of pheromone types to match */
+  sequence: Array<{
+    trail: string;
+    signal_type: string;
+    min_intensity?: number;
+  }>;
+  /** Time window in which the full sequence must appear */
+  window_ms: number;
+  /** Whether the sequence must appear in order (default: true) */
+  ordered?: boolean;
+}
+
+export type ScentCondition = ThresholdCondition | CompositeCondition | RateCondition | PatternCondition;
+
+// ============================================================================
+// SCENT REGISTRATION
+// ============================================================================
+
+export type MergeStrategy = "reinforce" | "replace" | "max" | "add" | "new";
+export type TriggerMode = "level" | "edge_rising" | "edge_falling";
+
+export interface Scent {
+  scent_id: string;
+  agent_endpoint: string;
+  condition: ScentCondition;
+  cooldown_ms: number;
+  activation_payload: Record<string, unknown>;
+  trigger_mode: TriggerMode;
+  hysteresis: number;
+  max_execution_ms: number;
+  last_triggered_at: number | null;
+  last_condition_met: boolean;
+  context_trails?: string[];
+}
+
+// ============================================================================
+// OPERATION PARAMS & RESULTS
+// ============================================================================
+
+export interface EmitParams {
+  trail: string;
+  type: string;
+  intensity: number;
+  decay?: DecayModel;
+  payload?: Record<string, unknown>;
+  tags?: string[];
+  merge_strategy?: MergeStrategy;
+  source_agent?: string;
+}
+
+export interface EmitResult {
+  pheromone_id: string;
+  action: "created" | "reinforced" | "replaced" | "merged";
+  previous_intensity?: number;
+  new_intensity: number;
+}
+
+export interface SniffParams {
+  trails?: string[];
+  types?: string[];
+  min_intensity?: number;
+  max_age_ms?: number;
+  tags?: TagFilter;
+  limit?: number;
+  include_evaporated?: boolean;
+}
+
+export interface AggregateStats {
+  count: number;
+  sum_intensity: number;
+  max_intensity: number;
+  avg_intensity: number;
+}
+
+export interface SniffResult {
+  timestamp: number;
+  pheromones: PheromoneSnapshot[];
+  aggregates: Record<string, AggregateStats>;
+}
+
+export interface RegisterScentParams {
+  scent_id: string;
+  agent_endpoint: string;
+  condition: ScentCondition;
+  cooldown_ms?: number;
+  activation_payload?: Record<string, unknown>;
+  trigger_mode?: TriggerMode;
+  hysteresis?: number;
+  max_execution_ms?: number;
+  context_trails?: string[];
+}
+
+export interface RegisterScentResult {
+  scent_id: string;
+  status: "registered" | "updated";
+  current_condition_state: {
+    met: boolean;
+    partial?: Record<string, boolean>;
+  };
+}
+
+export interface DeregisterScentParams {
+  scent_id: string;
+}
+
+export interface DeregisterScentResult {
+  scent_id: string;
+  status: "deregistered" | "not_found";
+}
+
+export interface TriggerPayload {
+  scent_id: string;
+  triggered_at: number;
+  condition_snapshot: Record<string, { value: number; pheromone_ids: string[] }>;
+  context_pheromones: PheromoneSnapshot[];
+  activation_payload: Record<string, unknown>;
+}
+
+export interface EvaporateParams {
+  trail?: string;
+  types?: string[];
+  older_than_ms?: number;
+  below_intensity?: number;
+  tags?: TagFilter;
+}
+
+export interface EvaporateResult {
+  evaporated_count: number;
+  trails_affected: string[];
+}
+
+export interface InspectParams {
+  include?: Array<"trails" | "scents" | "stats">;
+}
+
+export interface TrailInfo {
+  name: string;
+  pheromone_count: number;
+  total_intensity: number;
+  avg_intensity: number;
+}
+
+export interface ScentInfo {
+  scent_id: string;
+  agent_endpoint: string;
+  condition_met: boolean;
+  in_cooldown: boolean;
+  last_triggered_at: number | null;
+}
+
+export interface InspectResult {
+  timestamp: number;
+  trails?: TrailInfo[];
+  scents?: ScentInfo[];
+  stats?: {
+    total_pheromones: number;
+    active_pheromones: number;
+    total_scents: number;
+    uptime_ms: number;
+  };
+}
+
+// ============================================================================
+// JSON-RPC
+// ============================================================================
+
+export interface JsonRpcRequest<T = unknown> {
+  jsonrpc: "2.0";
+  id: string | number;
+  method: string;
+  params: T;
+}
+
+export interface JsonRpcSuccessResponse<T = unknown> {
+  jsonrpc: "2.0";
+  id: string | number;
+  result: T;
+}
+
+export interface JsonRpcErrorResponse {
+  jsonrpc: "2.0";
+  id: string | number | null;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+}
+
+export type JsonRpcResponse<T = unknown> = JsonRpcSuccessResponse<T> | JsonRpcErrorResponse;
+
+// ============================================================================
+// ERROR CODES
+// ============================================================================
+
+export const SBP_ERROR_CODES = {
+  TRAIL_NOT_FOUND: -32001,
+  SCENT_NOT_FOUND: -32002,
+  PAYLOAD_VALIDATION_FAILED: -32003,
+  RATE_LIMITED: -32004,
+  UNAUTHORIZED: -32005,
+  INVALID_CONDITION: -32006,
+} as const;
+
+export class SbpError extends Error {
+  constructor(
+    public code: number,
+    message: string,
+    public data?: unknown
+  ) {
+    super(message);
+    this.name = "SbpError";
+  }
+}

package/src/validation.ts

@@ -0,0 +1,251 @@
+/**
+ * SBP Input Validation
+ * Zod schemas for all JSON-RPC params and protocol messages
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// DECAY MODEL SCHEMAS
+// ============================================================================
+
+const ExponentialDecaySchema = z.object({
+  type: z.literal("exponential"),
+  half_life_ms: z.number().positive(),
+});
+
+const LinearDecaySchema = z.object({
+  type: z.literal("linear"),
+  rate_per_ms: z.number().positive(),
+});
+
+const StepDecaySchema = z.object({
+  type: z.literal("step"),
+  steps: z
+    .array(
+      z.object({
+        at_ms: z.number().nonnegative(),
+        intensity: z.number().min(0).max(1),
+      })
+    )
+    .min(1),
+});
+
+const ImmortalDecaySchema = z.object({
+  type: z.literal("immortal"),
+});
+
+const DecayModelSchema = z.discriminatedUnion("type", [
+  ExponentialDecaySchema,
+  LinearDecaySchema,
+  StepDecaySchema,
+  ImmortalDecaySchema,
+]);
+
+// ============================================================================
+// TAG FILTER SCHEMAS
+// ============================================================================
+
+const TagFilterSchema = z
+  .object({
+    any: z.array(z.string()).optional(),
+    all: z.array(z.string()).optional(),
+    none: z.array(z.string()).optional(),
+  })
+  .strict();
+
+// ============================================================================
+// CONDITION SCHEMAS
+// ============================================================================
+
+const ThresholdConditionSchema = z.object({
+  type: z.literal("threshold"),
+  trail: z.string().min(1),
+  signal_type: z.string().min(1),
+  tags: TagFilterSchema.optional(),
+  aggregation: z.enum(["sum", "max", "avg", "count", "any"]),
+  operator: z.enum([">=", ">", "<=", "<", "==", "!="]),
+  value: z.number(),
+});
+
+const RateConditionSchema = z.object({
+  type: z.literal("rate"),
+  trail: z.string().min(1),
+  signal_type: z.string().min(1),
+  metric: z.enum(["emissions_per_second", "intensity_delta"]),
+  window_ms: z.number().positive(),
+  operator: z.enum([">=", ">", "<=", "<"]),
+  value: z.number(),
+});
+
+const PatternConditionSchema = z.object({
+  type: z.literal("pattern"),
+  sequence: z
+    .array(
+      z.object({
+        trail: z.string().min(1),
+        signal_type: z.string().min(1),
+        min_intensity: z.number().min(0).max(1).optional(),
+      })
+    )
+    .min(1),
+  window_ms: z.number().positive(),
+  ordered: z.boolean().optional(),
+});
+
+// Recursive condition schema using z.lazy for composite self-reference
+const ScentConditionSchema: z.ZodType = z.lazy(() =>
+  z.union([
+    ThresholdConditionSchema,
+    z.object({
+      type: z.literal("composite"),
+      operator: z.enum(["and", "or", "not"]),
+      conditions: z.array(ScentConditionSchema).min(1),
+    }),
+    RateConditionSchema,
+    PatternConditionSchema,
+  ])
+);
+
+// ============================================================================
+// OPERATION PARAM SCHEMAS
+// ============================================================================
+
+export const EmitParamsSchema = z.object({
+  trail: z.string().min(1, "Trail must be a non-empty string"),
+  type: z.string().min(1, "Type must be a non-empty string"),
+  intensity: z.number().min(0).max(1, "Intensity must be between 0 and 1"),
+  decay: DecayModelSchema.optional(),
+  payload: z.record(z.unknown()).optional(),
+  tags: z.array(z.string()).optional(),
+  merge_strategy: z.enum(["reinforce", "replace", "max", "add", "new"]).optional(),
+  source_agent: z.string().optional(),
+});
+
+export const SniffParamsSchema = z.object({
+  trails: z.array(z.string()).optional(),
+  types: z.array(z.string()).optional(),
+  min_intensity: z.number().min(0).max(1).optional(),
+  max_age_ms: z.number().positive().optional(),
+  tags: TagFilterSchema.optional(),
+  limit: z.number().int().positive().max(10000).optional(),
+  include_evaporated: z.boolean().optional(),
+});
+
+export const RegisterScentParamsSchema = z.object({
+  scent_id: z.string().min(1, "Scent ID must be a non-empty string"),
+  agent_endpoint: z.string().optional().default(""),
+  condition: ScentConditionSchema,
+  cooldown_ms: z.number().int().nonnegative().optional(),
+  activation_payload: z.record(z.unknown()).optional(),
+  trigger_mode: z.enum(["level", "edge_rising", "edge_falling"]).optional(),
+  hysteresis: z.number().nonnegative().optional(),
+  max_execution_ms: z.number().positive().optional(),
+  context_trails: z.array(z.string()).optional(),
+});
+
+export const DeregisterScentParamsSchema = z.object({
+  scent_id: z.string().min(1),
+});
+
+export const EvaporateParamsSchema = z.object({
+  trail: z.string().optional(),
+  types: z.array(z.string()).optional(),
+  older_than_ms: z.number().positive().optional(),
+  below_intensity: z.number().min(0).max(1).optional(),
+  tags: TagFilterSchema.optional(),
+});
+
+export const InspectParamsSchema = z.object({
+  include: z.array(z.enum(["trails", "scents", "stats"])).optional(),
+});
+
+export const SubscribeParamsSchema = z.object({
+  scent_id: z.string().min(1),
+});
+
+export const UnsubscribeParamsSchema = z.object({
+  scent_id: z.string().min(1),
+});
+
+// ============================================================================
+// JSON-RPC ENVELOPE SCHEMA
+// ============================================================================
+
+export const JsonRpcRequestSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: z.union([z.string(), z.number()]),
+  method: z.string().min(1),
+  params: z.unknown().optional().default({}),
+});
+
+// ============================================================================
+// VALIDATION HELPER
+// ============================================================================
+
+/** Map of method names to their param schemas */
+const METHOD_SCHEMAS: Record<string, z.ZodType> = {
+  "sbp/emit": EmitParamsSchema,
+  "sbp/sniff": SniffParamsSchema,
+  "sbp/register_scent": RegisterScentParamsSchema,
+  "sbp/deregister_scent": DeregisterScentParamsSchema,
+  "sbp/evaporate": EvaporateParamsSchema,
+  "sbp/inspect": InspectParamsSchema,
+  "sbp/subscribe": SubscribeParamsSchema,
+  "sbp/unsubscribe": UnsubscribeParamsSchema,
+};
+
+export interface ValidationError {
+  code: -32600 | -32602;
+  message: string;
+  data?: unknown;
+}
+
+/**
+ * Validate a JSON-RPC request envelope.
+ * Returns the parsed request or a JSON-RPC error.
+ */
+export function validateEnvelope(
+  body: unknown
+): { ok: true; request: z.infer<typeof JsonRpcRequestSchema> } | { ok: false; error: ValidationError } {
+  const result = JsonRpcRequestSchema.safeParse(body);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: -32600,
+        message: "Invalid JSON-RPC request",
+        data: result.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+      },
+    };
+  }
+  return { ok: true, request: result.data };
+}
+
+/**
+ * Validate method-specific params.
+ * Returns the parsed params or a JSON-RPC error.
+ */
+export function validateParams(
+  method: string,
+  params: unknown
+): { ok: true; params: unknown } | { ok: false; error: ValidationError } {
+  const schema = METHOD_SCHEMAS[method];
+  if (!schema) {
+    // Unknown methods are handled by the RPC router, not here
+    return { ok: true, params };
+  }
+
+  const result = schema.safeParse(params);
+  if (!result.success) {
+    return {
+      ok: false,
+      error: {
+        code: -32602,
+        message: `Invalid params for ${method}`,
+        data: result.error.issues.map((i) => ({ path: i.path.join("."), message: i.message })),
+      },
+    };
+  }
+  return { ok: true, params: result.data };
+}

package/tsconfig.eslint.json

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "include": ["src/**/*", "src/**/*.test.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}