@subcortex-ai/sdk 0.2.0 → 0.3.1

package/dist/index.cjs

@@ -46,6 +46,8 @@ __export(index_exports, {
   RecallNamespace: () => RecallNamespace,
   RelationshipTypes: () => RelationshipTypes,
   RelationshipsNamespace: () => RelationshipsNamespace,
+  RulePredicates: () => RulePredicates,
+  RulesNamespace: () => RulesNamespace,
   SIGNAL_DECAY_CONFIG: () => SIGNAL_DECAY_CONFIG,
   SYSTEM_SIGNAL_TYPES: () => SYSTEM_SIGNAL_TYPES,
   SearchNamespace: () => SearchNamespace,
@@ -1137,6 +1139,242 @@ function enc2(s) {
   return encodeURIComponent(s);
 }
 
+// src/types/rules.ts
+var RulePredicates = {
+  BANNED_PATTERN: "rule:banned_pattern",
+  REQUIRED_PATTERN: "rule:required_pattern",
+  FILE_CONSTRAINT: "rule:file_constraint",
+  REQUIRES_PROPAGATION: "rule:requires_propagation"
+};
+
+// src/rules.ts
+var RULE_PREDICATE_PREFIX = "rule:";
+var TYPE_TO_PREDICATE = {
+  banned_pattern: RulePredicates.BANNED_PATTERN,
+  required_pattern: RulePredicates.REQUIRED_PATTERN,
+  file_constraint: RulePredicates.FILE_CONSTRAINT,
+  requires_propagation: RulePredicates.REQUIRES_PROPAGATION
+};
+function defaultSeverity(confidence) {
+  if (confidence >= 1) return "block";
+  if (confidence >= 0.7) return "warn";
+  return "info";
+}
+var RulesNamespace = class {
+  http;
+  tenantId;
+  constructor(http, tenantId) {
+    this.http = http;
+    this.tenantId = tenantId;
+  }
+  /**
+   * Create a new rule.
+   *
+   * Stores an assertion with a `rule:*` predicate and a typed value.
+   * Defaults to confidence 1.0 (enforcement) if not specified.
+   *
+   * @example
+   * ```typescript
+   * await subcortex.rules.create({
+   *   subject: 'project:my-project',
+   *   type: 'banned_pattern',
+   *   pattern: 'as any',
+   *   description: 'No any casts — use proper types',
+   * })
+   * ```
+   */
+  async create(input) {
+    const confidence = input.confidence ?? 1;
+    const severity = input.severity ?? defaultSeverity(confidence);
+    const ruleValue = {
+      description: input.description,
+      pattern: input.pattern,
+      fileScope: input.fileScope,
+      propagatesTo: input.propagatesTo
+    };
+    const assertion = await this.http.post(
+      `/api/v1/assertions`,
+      {
+        subject: input.subject,
+        predicate: TYPE_TO_PREDICATE[input.type],
+        value: { ...ruleValue, severity },
+        confidence,
+        tenant_id: input.tenantId ?? this.tenantId
+      },
+      input.tenantId ?? this.tenantId
+    );
+    return parseRule(assertion);
+  }
+  /**
+   * Get a rule by its assertion ID.
+   */
+  async get(ruleId, options) {
+    const tenant = options?.tenantId ?? this.tenantId;
+    const assertion = await this.http.get(
+      `/api/v1/assertions/${enc3(tenant)}/${enc3(ruleId)}`
+    );
+    return parseRule(assertion);
+  }
+  /**
+   * List all rules for this project, optionally filtered by type or severity.
+   */
+  async list(options) {
+    const tenant = options?.tenantId ?? this.tenantId;
+    const assertions = await this.http.get(
+      `/api/v1/assertions/list/${enc3(tenant)}`
+    );
+    return assertions.filter((a) => isRuleAssertion(a)).filter((a) => options?.includeSuperseded || !a.isSuperseded).map(parseRule).filter((r) => !options?.type || r.type === options.type).filter((r) => !options?.severity || r.severity === options.severity);
+  }
+  /**
+   * Get all rules whose fileScope matches the given file path.
+   *
+   * This is the primary query for the PreToolUse hook — "what rules apply
+   * to the file I'm about to modify?"
+   *
+   * @example
+   * ```typescript
+   * const rules = await subcortex.rules.forFile('app/api/users/route.ts')
+   * // Returns banned_pattern and required_pattern rules whose fileScope
+   * // matches the path, plus any project-wide rules without a fileScope.
+   * ```
+   */
+  async forFile(filePath, options) {
+    const allRules = await this.list(options);
+    return allRules.filter((rule) => {
+      if (!rule.value.fileScope) return true;
+      try {
+        const regex = new RegExp(rule.value.fileScope);
+        return regex.test(filePath);
+      } catch {
+        return false;
+      }
+    });
+  }
+  /**
+   * Get all rules scoped to a specific intent subject.
+   *
+   * @example
+   * ```typescript
+   * const apiRules = await subcortex.rules.forIntent('api')
+   * // Queries subject "intent:api" for all rule assertions
+   * ```
+   */
+  async forIntent(intent, options) {
+    const tenant = options?.tenantId ?? this.tenantId;
+    const subject2 = intent.startsWith("intent:") ? intent : `intent:${intent}`;
+    const assertions = await this.http.get(
+      `/api/v1/assertions/query/${enc3(tenant)}/${enc3(subject2)}`
+    );
+    return assertions.filter((a) => isRuleAssertion(a)).filter((a) => options?.includeSuperseded || !a.isSuperseded).map(parseRule).filter((r) => !options?.type || r.type === options.type).filter((r) => !options?.severity || r.severity === options.severity);
+  }
+  /**
+   * Get all rules scoped to a specific subject (project, file, intent, etc.).
+   */
+  async forSubject(subject2, options) {
+    const tenant = options?.tenantId ?? this.tenantId;
+    const assertions = await this.http.get(
+      `/api/v1/assertions/query/${enc3(tenant)}/${enc3(subject2)}`
+    );
+    return assertions.filter((a) => isRuleAssertion(a)).filter((a) => options?.includeSuperseded || !a.isSuperseded).map(parseRule).filter((r) => !options?.type || r.type === options.type).filter((r) => !options?.severity || r.severity === options.severity);
+  }
+  /**
+   * Update a rule by superseding it.
+   *
+   * The old rule is marked as superseded, a new one is created.
+   * Full assertion history is preserved.
+   */
+  async update(input) {
+    const tenant = input.tenantId ?? this.tenantId;
+    const existing = await this.get(input.ruleId, { tenantId: tenant });
+    const confidence = input.confidence ?? existing.confidence;
+    const severity = input.severity ?? existing.severity;
+    const ruleValue = {
+      description: input.description ?? existing.value.description,
+      pattern: input.pattern ?? existing.value.pattern,
+      fileScope: input.fileScope ?? existing.value.fileScope,
+      propagatesTo: input.propagatesTo ?? existing.value.propagatesTo
+    };
+    const assertion = await this.http.post(
+      `/api/v1/assertions/supersede`,
+      {
+        original_assertion_id: input.ruleId,
+        subject: existing.subject,
+        predicate: existing.predicate,
+        value: { ...ruleValue, severity },
+        confidence,
+        tenant_id: tenant
+      },
+      tenant
+    );
+    return parseRule(assertion);
+  }
+  /**
+   * Retract (deactivate) a rule.
+   *
+   * The assertion's temporal bounds are closed. The rule stops matching
+   * in future queries but its history is preserved.
+   */
+  async retract(ruleId, options) {
+    const tenant = options?.tenantId ?? this.tenantId;
+    await this.http.post(
+      `/api/v1/assertions/retract/${enc3(tenant)}/${enc3(ruleId)}`,
+      {},
+      tenant
+    );
+  }
+};
+function isRuleAssertion(assertion) {
+  return assertion.predicate?.startsWith(RULE_PREDICATE_PREFIX) ?? false;
+}
+function parseRule(assertion) {
+  const predicate = assertion.predicate;
+  const type = predicate.replace(RULE_PREDICATE_PREFIX, "");
+  let ruleValue;
+  let severity;
+  if (typeof assertion.value === "object" && assertion.value !== null) {
+    const val = assertion.value;
+    ruleValue = {
+      description: String(val.description ?? ""),
+      pattern: val.pattern != null ? String(val.pattern) : void 0,
+      fileScope: val.fileScope != null ? String(val.fileScope) : void 0,
+      propagatesTo: Array.isArray(val.propagatesTo) ? val.propagatesTo.map(String) : void 0
+    };
+    severity = val.severity ?? defaultSeverity(assertion.confidence);
+  } else if (typeof assertion.value === "string") {
+    try {
+      const parsed = JSON.parse(assertion.value);
+      ruleValue = {
+        description: String(parsed.description ?? ""),
+        pattern: parsed.pattern != null ? String(parsed.pattern) : void 0,
+        fileScope: parsed.filePattern != null ? String(parsed.filePattern) : void 0,
+        propagatesTo: Array.isArray(parsed.propagatesTo) ? parsed.propagatesTo.map(String) : void 0
+      };
+      severity = parsed.severity ?? defaultSeverity(assertion.confidence);
+    } catch {
+      ruleValue = { description: String(assertion.value) };
+      severity = defaultSeverity(assertion.confidence);
+    }
+  } else {
+    ruleValue = { description: "" };
+    severity = defaultSeverity(assertion.confidence);
+  }
+  return {
+    id: assertion.id,
+    tenantId: assertion.tenantId,
+    subject: assertion.subject,
+    type,
+    predicate,
+    value: ruleValue,
+    severity,
+    confidence: assertion.confidence,
+    validFrom: assertion.validFrom,
+    isSuperseded: assertion.isSuperseded
+  };
+}
+function enc3(s) {
+  return encodeURIComponent(s);
+}
+
 // src/client.ts
 var AssertionsNamespace = class {
   constructor(http, tenantId) {
@@ -1158,21 +1396,21 @@ var AssertionsNamespace = class {
   async get(assertionId, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/assertions/${enc3(tenantId)}/${enc3(assertionId)}`
+      `/api/v1/assertions/${enc4(tenantId)}/${enc4(assertionId)}`
     );
   }
   /** Query assertions by subject. */
   async query(subject2, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/assertions/query/${enc3(tenantId)}/${enc3(subject2)}`
+      `/api/v1/assertions/query/${enc4(tenantId)}/${enc4(subject2)}`
     );
   }
   /** List all active assertions for the tenant. */
   async list(options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/assertions/list/${enc3(tenantId)}`
+      `/api/v1/assertions/list/${enc4(tenantId)}`
     );
   }
   /** Supersede an existing assertion with updated values. */
@@ -1191,7 +1429,7 @@ var AssertionsNamespace = class {
   async retract(assertionId, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.post(
-      `/api/v1/assertions/retract/${enc3(tenantId)}/${enc3(assertionId)}`,
+      `/api/v1/assertions/retract/${enc4(tenantId)}/${enc4(assertionId)}`,
       {}
     );
   }
@@ -1218,14 +1456,14 @@ var RelationshipsNamespace = class {
   async query(subject2, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/relationships/${enc3(tenantId)}/${enc3(subject2)}`
+      `/api/v1/relationships/${enc4(tenantId)}/${enc4(subject2)}`
     );
   }
   /** List all relationships for the tenant. */
   async list(options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/relationships/list/${enc3(tenantId)}`
+      `/api/v1/relationships/list/${enc4(tenantId)}`
     );
   }
 };
@@ -1252,14 +1490,14 @@ var AgentsNamespace = class {
   async get(agentId, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/agents/${enc3(tenantId)}/${enc3(agentId)}`
+      `/api/v1/agents/${enc4(tenantId)}/${enc4(agentId)}`
     );
   }
   /** Update an agent. */
   async update(agentId, input, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.put(
-      `/api/v1/agents/${enc3(tenantId)}/${enc3(agentId)}`,
+      `/api/v1/agents/${enc4(tenantId)}/${enc4(agentId)}`,
       {
         tenant_id: tenantId,
         name: input.name,
@@ -1276,20 +1514,20 @@ var AgentsNamespace = class {
   /** Delete an agent. */
   async delete(agentId, options) {
     const tenantId = options?.tenantId || this.tenantId;
-    await this.http.delete(`/api/v1/agents/${enc3(tenantId)}/${enc3(agentId)}`);
+    await this.http.delete(`/api/v1/agents/${enc4(tenantId)}/${enc4(agentId)}`);
   }
   /** List all agents for the tenant. */
   async list(options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/agents/list/${enc3(tenantId)}`
+      `/api/v1/agents/list/${enc4(tenantId)}`
     );
   }
   /** Get composed system instructions for an agent. */
   async getInstructions(agentId, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/agents/${enc3(tenantId)}/${enc3(agentId)}/instructions`
+      `/api/v1/agents/${enc4(tenantId)}/${enc4(agentId)}/instructions`
     );
   }
 };
@@ -1339,14 +1577,14 @@ var MemoryNamespace = class {
   async recall(subject2, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/assertions/query/${enc3(tenantId)}/${enc3(subject2)}`
+      `/api/v1/assertions/query/${enc4(tenantId)}/${enc4(subject2)}`
     );
   }
   /** Forget a specific memory (retract the assertion). */
   async forget(assertionId, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.post(
-      `/api/v1/assertions/retract/${enc3(tenantId)}/${enc3(assertionId)}`,
+      `/api/v1/assertions/retract/${enc4(tenantId)}/${enc4(assertionId)}`,
       {}
     );
   }
@@ -1378,7 +1616,7 @@ var IntakeNamespace = class {
   }
   /** Get pending intake results for an agent. */
   async pending(agentId, options) {
-    let path = `/api/v1/intake/pending/${enc3(agentId)}`;
+    let path = `/api/v1/intake/pending/${enc4(agentId)}`;
     const params = [];
     if (options?.status) params.push(`status=${options.status.join(",")}`);
     if (options?.limit) params.push(`limit=${options.limit}`);
@@ -1387,18 +1625,18 @@ var IntakeNamespace = class {
   }
   /** Acknowledge an intake result (mark as consumed). */
   async acknowledge(itemId) {
-    await this.http.post(`/api/v1/intake/acknowledge/${enc3(itemId)}`, {});
+    await this.http.post(`/api/v1/intake/acknowledge/${enc4(itemId)}`, {});
   }
   /** Acknowledge all pending items for an agent. */
   async acknowledgeAll(agentId) {
     return this.http.post(
-      `/api/v1/intake/acknowledge-all/${enc3(agentId)}`,
+      `/api/v1/intake/acknowledge-all/${enc4(agentId)}`,
       {}
     );
   }
   /** Get intake processing stats for an agent. */
   async stats(agentId) {
-    return this.http.get(`/api/v1/intake/stats/${enc3(agentId)}`);
+    return this.http.get(`/api/v1/intake/stats/${enc4(agentId)}`);
   }
 };
 var ExperiencesNamespace = class {
@@ -1414,14 +1652,14 @@ var ExperiencesNamespace = class {
     if (input?.limit) params.set("limit", String(input.limit));
     const qs = params.toString();
     return this.http.get(
-      `/api/v1/experiences/${enc3(tenantId)}${qs ? `?${qs}` : ""}`
+      `/api/v1/experiences/${enc4(tenantId)}${qs ? `?${qs}` : ""}`
     );
   }
   /** Get a single experience by ID. */
   async get(experienceId, options) {
     const tenantId = options?.tenantId || this.tenantId;
     return this.http.get(
-      `/api/v1/experiences/${enc3(tenantId)}/${enc3(experienceId)}`
+      `/api/v1/experiences/${enc4(tenantId)}/${enc4(experienceId)}`
     );
   }
 };
@@ -1436,7 +1674,7 @@ var RecallNamespace = class {
     const params = new URLSearchParams({ q: input.query });
     if (input.limit) params.set("limit", String(input.limit));
     return this.http.get(
-      `/api/v1/recall/${enc3(tenantId)}?${params.toString()}`
+      `/api/v1/recall/${enc4(tenantId)}?${params.toString()}`
     );
   }
 };
@@ -1449,7 +1687,7 @@ var GraphNamespace = class {
   async findPaths(input) {
     const tenantId = input.tenantId || this.tenantId;
     return this.http.post(
-      `/api/v1/graph/${enc3(tenantId)}/paths`,
+      `/api/v1/graph/${enc4(tenantId)}/paths`,
       {
         from: input.from,
         to: input.to,
@@ -1463,7 +1701,7 @@ var GraphNamespace = class {
   async traverse(input) {
     const tenantId = input.tenantId || this.tenantId;
     return this.http.post(
-      `/api/v1/graph/${enc3(tenantId)}/traverse`,
+      `/api/v1/graph/${enc4(tenantId)}/traverse`,
       {
         start_subject: input.startSubject,
         max_depth: input.maxDepth,
@@ -1484,7 +1722,7 @@ var TemporalNamespace = class {
     const tenantId = options?.tenantId || this.tenantId;
     const pointStr = point instanceof Date ? point.toISOString() : point;
     return this.http.get(
-      `/api/v1/temporal/${enc3(tenantId)}/${enc3(subject2)}/at?point=${enc3(pointStr)}`
+      `/api/v1/temporal/${enc4(tenantId)}/${enc4(subject2)}/at?point=${enc4(pointStr)}`
     );
   }
   /** Get assertions within a date range. */
@@ -1493,7 +1731,7 @@ var TemporalNamespace = class {
     const startStr = start instanceof Date ? start.toISOString() : start;
     const endStr = end instanceof Date ? end.toISOString() : end;
     return this.http.get(
-      `/api/v1/temporal/${enc3(tenantId)}/${enc3(subject2)}/range?start=${enc3(startStr)}&end=${enc3(endStr)}`
+      `/api/v1/temporal/${enc4(tenantId)}/${enc4(subject2)}/range?start=${enc4(startStr)}&end=${enc4(endStr)}`
     );
   }
 };
@@ -1506,7 +1744,7 @@ var SearchNamespace = class {
   async semantic(input) {
     const tenantId = input.tenantId || this.tenantId;
     return this.http.post(
-      `/api/v1/search/${enc3(tenantId)}/semantic`,
+      `/api/v1/search/${enc4(tenantId)}/semantic`,
       {
         embedding: input.embedding,
         top_k: input.topK
@@ -1596,10 +1834,10 @@ var EntitiesNamespace = class {
     const tenantId = options?.tenantId || this.tenantId;
     const subject2 = `entity:${entityName.toLowerCase().replace(/\s+/g, "-")}`;
     const assertions = await this.http.get(
-      `/api/v1/assertions/query/${enc3(tenantId)}/${enc3(subject2)}`
+      `/api/v1/assertions/query/${enc4(tenantId)}/${enc4(subject2)}`
     );
     const relationships = await this.http.get(
-      `/api/v1/relationships/query/${enc3(tenantId)}/${enc3(subject2)}`
+      `/api/v1/relationships/query/${enc4(tenantId)}/${enc4(subject2)}`
     );
     const typeAssertion = assertions.find((a) => a.predicate === "type" && !a.isSuperseded);
     const descAssertion = assertions.find((a) => a.predicate === "description" && !a.isSuperseded);
@@ -1607,7 +1845,7 @@ var EntitiesNamespace = class {
     const properties = await Promise.all(
       propertyRels.map(async (rel) => {
         const propAssertions = await this.http.get(
-          `/api/v1/assertions/query/${enc3(tenantId)}/${enc3(rel.toSubject)}`
+          `/api/v1/assertions/query/${enc4(tenantId)}/${enc4(rel.toSubject)}`
         );
         const fieldType = propAssertions.find((a) => a.predicate === "field_type" && !a.isSuperseded);
         const required = propAssertions.find((a) => a.predicate === "required" && !a.isSuperseded);
@@ -1637,7 +1875,7 @@ var EntitiesNamespace = class {
   async list(options) {
     const tenantId = options?.tenantId || this.tenantId;
     const all = await this.http.get(
-      `/api/v1/assertions/list/${enc3(tenantId)}`
+      `/api/v1/assertions/list/${enc4(tenantId)}`
     );
     return all.filter((a) => a.subject.startsWith("entity:") && a.predicate === "type" && !a.isSuperseded);
   }
@@ -1669,6 +1907,8 @@ var SubCortexClient = class {
   experiences;
   /** Entity schema management — create, describe, and manage data models */
   entities;
+  /** Code guardrails — typed rules stored as assertions with file-scope matching */
+  rules;
   http;
   constructor(options) {
     if (!options.apiKey && !options.token) {
@@ -1698,13 +1938,14 @@ var SubCortexClient = class {
     this.recall = new RecallNamespace(this.http, options.tenantId);
     this.experiences = new ExperiencesNamespace(this.http, options.tenantId);
     this.entities = new EntitiesNamespace(this.http, options.tenantId);
+    this.rules = new RulesNamespace(this.http, options.tenantId);
   }
   /** Check SubCortex server health. */
   async health() {
     return this.http.get("/health");
   }
 };
-function enc3(s) {
+function enc4(s) {
   return encodeURIComponent(s);
 }
 
@@ -1894,6 +2135,8 @@ function esc(s) {
   RecallNamespace,
   RelationshipTypes,
   RelationshipsNamespace,
+  RulePredicates,
+  RulesNamespace,
   SIGNAL_DECAY_CONFIG,
   SYSTEM_SIGNAL_TYPES,
   SearchNamespace,