@subcortex-ai/sdk 0.1.3 → 0.3.0

package/dist/index.d.ts

@@ -517,6 +517,8 @@ interface RegisterPersonInput {
     details?: string;
     /** Confidence level */
     confidence?: ConfidenceLevel | number;
+    /** Session ID for experience binding */
+    sessionId?: string;
 }
 /** Result of person registration */
 interface RegisterPersonResult {
@@ -685,6 +687,214 @@ declare class SignalsNamespace {
     }>;
 }
 
+/**
+ * Rule types — typed code guardrails stored as assertions.
+ *
+ * Rules are assertions with structured predicates (`rule:banned_pattern`,
+ * `rule:required_pattern`, etc.) and typed values. The engine stores them
+ * identically to any other assertion — same WAL, same content-addressable IDs,
+ * same temporal model, same supersession chain.
+ *
+ * The RulesNamespace provides typed CRUD and file-scope matching on top of
+ * the raw assertion layer, so consumers don't parse JSON blobs in hooks.
+ */
+/** The kind of enforcement a rule performs. */
+type RuleType = 'banned_pattern' | 'required_pattern' | 'file_constraint' | 'requires_propagation';
+/** How the system responds to a violation. */
+type RuleSeverity = 'block' | 'warn' | 'info';
+/** Well-known rule predicates. Scoped under `rule:` to avoid collision with general assertions. */
+declare const RulePredicates: {
+    readonly BANNED_PATTERN: "rule:banned_pattern";
+    readonly REQUIRED_PATTERN: "rule:required_pattern";
+    readonly FILE_CONSTRAINT: "rule:file_constraint";
+    readonly REQUIRES_PROPAGATION: "rule:requires_propagation";
+};
+type RulePredicate = typeof RulePredicates[keyof typeof RulePredicates];
+/** The typed structure stored in the assertion value field. */
+interface RuleValue {
+    /** Regex pattern to match against file content (banned/required pattern rules). */
+    pattern?: string;
+    /** Glob or regex for which files this rule applies to. If omitted, applies to all files. */
+    fileScope?: string;
+    /** Human-readable description of what this rule enforces and why. */
+    description: string;
+    /** What surfaces must be updated when this rule's scope is changed (propagation rules). */
+    propagatesTo?: string[];
+}
+/** A rule — a typed, parsed view of an enforcement assertion. */
+interface Rule {
+    /** Assertion ID (content-addressable BLAKE3 hash) */
+    id: string;
+    /** Tenant this rule belongs to */
+    tenantId: string;
+    /** Subject scope — e.g. `project:{id}`, `intent:api`, `file:prisma/schema.prisma` */
+    subject: string;
+    /** Rule type — which enforcement behavior this rule triggers */
+    type: RuleType;
+    /** The full typed predicate, e.g. `rule:banned_pattern` */
+    predicate: RulePredicate;
+    /** Structured rule configuration */
+    value: RuleValue;
+    /** Severity — block (enforcement), warn (guidance), info (context) */
+    severity: RuleSeverity;
+    /** Confidence score from the underlying assertion */
+    confidence: number;
+    /** When this rule became active */
+    validFrom: string;
+    /** Whether this rule has been superseded by a newer version */
+    isSuperseded: boolean;
+}
+/** Input for creating a rule. */
+interface CreateRuleInput {
+    /** Subject scope — e.g. `project:{id}`, `intent:api`, `file:src/db/schema.ts` */
+    subject: string;
+    /** Rule type */
+    type: RuleType;
+    /** Regex pattern (for banned_pattern and required_pattern) */
+    pattern?: string;
+    /** File scope glob/regex — which files this rule applies to */
+    fileScope?: string;
+    /** Human-readable description of the rule and its rationale */
+    description: string;
+    /** Surfaces that must be updated (for requires_propagation rules) */
+    propagatesTo?: string[];
+    /** Severity — defaults to 'block' for confidence 1.0, 'warn' for >= 0.7, 'info' otherwise */
+    severity?: RuleSeverity;
+    /** Confidence — defaults to 1.0 (enforcement). Set lower for guidance/context. */
+    confidence?: number;
+    /** Override tenant ID */
+    tenantId?: string;
+}
+/** Input for updating (superseding) a rule. */
+interface UpdateRuleInput {
+    /** ID of the rule to supersede */
+    ruleId: string;
+    /** Updated fields (only provided fields change; others carry forward) */
+    pattern?: string;
+    fileScope?: string;
+    description?: string;
+    propagatesTo?: string[];
+    severity?: RuleSeverity;
+    confidence?: number;
+    /** Override tenant ID */
+    tenantId?: string;
+}
+/** Options for querying rules. */
+interface RuleQueryOptions {
+    /** Filter by rule type */
+    type?: RuleType;
+    /** Filter by severity */
+    severity?: RuleSeverity;
+    /** Include superseded rules in results (default: false) */
+    includeSuperseded?: boolean;
+    /** Override tenant ID */
+    tenantId?: string;
+}
+
+/**
+ * RulesNamespace — typed code guardrails stored as assertions.
+ *
+ * Rules are assertions with `rule:*` predicates and structured values.
+ * This namespace provides typed CRUD, file-scope matching, and intent-based
+ * queries so consumers work with `Rule` objects instead of raw assertions
+ * with JSON blobs stuffed into the value field.
+ *
+ * @example
+ * ```typescript
+ * // Create a rule
+ * const rule = await subcortex.rules.create({
+ *   subject: 'intent:api',
+ *   type: 'banned_pattern',
+ *   pattern: 'NextResponse\\.json\\(',
+ *   fileScope: 'app/api/.*\\.ts$',
+ *   description: 'Use apiSuccess() instead of NextResponse.json()',
+ * })
+ *
+ * // Get all rules that apply to a file
+ * const rules = await subcortex.rules.forFile('app/api/users/route.ts')
+ *
+ * // Get enforcement rules only
+ * const enforcement = await subcortex.rules.list({ severity: 'block' })
+ * ```
+ */
+
+declare class RulesNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /**
+     * 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',
+     * })
+     * ```
+     */
+    create(input: CreateRuleInput): Promise<Rule>;
+    /**
+     * Get a rule by its assertion ID.
+     */
+    get(ruleId: string, options?: {
+        tenantId?: string;
+    }): Promise<Rule>;
+    /**
+     * List all rules for this project, optionally filtered by type or severity.
+     */
+    list(options?: RuleQueryOptions): Promise<Rule[]>;
+    /**
+     * 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.
+     * ```
+     */
+    forFile(filePath: string, options?: RuleQueryOptions): Promise<Rule[]>;
+    /**
+     * 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
+     * ```
+     */
+    forIntent(intent: string, options?: RuleQueryOptions): Promise<Rule[]>;
+    /**
+     * Get all rules scoped to a specific subject (project, file, intent, etc.).
+     */
+    forSubject(subject: string, options?: RuleQueryOptions): Promise<Rule[]>;
+    /**
+     * Update a rule by superseding it.
+     *
+     * The old rule is marked as superseded, a new one is created.
+     * Full assertion history is preserved.
+     */
+    update(input: UpdateRuleInput): Promise<Rule>;
+    /**
+     * Retract (deactivate) a rule.
+     *
+     * The assertion's temporal bounds are closed. The rule stops matching
+     * in future queries but its history is preserved.
+     */
+    retract(ruleId: string, options?: {
+        tenantId?: string;
+    }): Promise<void>;
+}
+
 /**
  * SubCortexClient — the main entry point for the SubCortex SDK.
  *
@@ -1053,6 +1263,7 @@ interface ComposedInstructions {
     modelProvider: string;
     modelId: string;
     temperature: number;
+    maxTokens: number;
     voiceId: string;
 }
 /**
@@ -1287,6 +1498,197 @@ declare class IntakeNamespace {
     /** Get intake processing stats for an agent. */
     stats(agentId: string): Promise<IntakeStats>;
 }
+interface Experience {
+    id: string;
+    tenant_id: string;
+    agent_id: string | null;
+    session_id: string;
+    start_time: string;
+    end_time: string | null;
+    assertion_ids: string[];
+    relationship_ids: string[];
+    summary: string | null;
+    topic: string | null;
+    emotional_arc: string | null;
+}
+declare class ExperiencesNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /** List experiences, optionally filtered by subject. */
+    list(input?: {
+        subject?: string;
+        limit?: number;
+        tenantId?: string;
+    }): Promise<Experience[]>;
+    /** Get a single experience by ID. */
+    get(experienceId: string, options?: {
+        tenantId?: string;
+    }): Promise<Experience>;
+}
+interface RecallResult {
+    assertion_id: string;
+    score: number;
+    subject: string;
+    predicate: string;
+    snippet: string;
+}
+interface RecallSearchInput {
+    query: string;
+    limit?: number;
+    tenantId?: string;
+}
+interface RecallSearchResponse {
+    results: RecallResult[];
+    total_hits: number;
+}
+declare class RecallNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /** BM25 full-text search across assertions. */
+    search(input: RecallSearchInput): Promise<RecallSearchResponse>;
+}
+interface GraphPath {
+    subjects: string[];
+    total_confidence: number;
+    length: number;
+}
+interface FindPathsInput {
+    from: string;
+    to: string;
+    maxDepth?: number;
+    minConfidence?: number;
+    /** "shortest" | "highest_confidence" | "all" */
+    strategy?: string;
+    tenantId?: string;
+}
+interface TraversalNode {
+    subject: string;
+    depth: number;
+    path_confidence: number;
+}
+interface TraversalResult {
+    nodes: TraversalNode[];
+    edge_count: number;
+    depth_reached: number;
+    truncated: boolean;
+}
+interface TraverseInput {
+    startSubject: string;
+    maxDepth?: number;
+    relationshipTypes?: string[];
+    minConfidence?: number;
+    maxNodes?: number;
+    tenantId?: string;
+}
+declare class GraphNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /** Find paths between two subjects. */
+    findPaths(input: FindPathsInput): Promise<GraphPath[]>;
+    /** BFS traversal from a starting subject. */
+    traverse(input: TraverseInput): Promise<TraversalResult>;
+}
+interface TemporalSnapshot {
+    subject: string;
+    point: string;
+    assertions: Assertion[];
+}
+interface TemporalRange {
+    subject: string;
+    start: string;
+    end: string;
+    assertions: Assertion[];
+}
+declare class TemporalNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /** Get assertions valid at a specific point in time. */
+    at(subject: string, point: Date | string, options?: {
+        tenantId?: string;
+    }): Promise<TemporalSnapshot>;
+    /** Get assertions within a date range. */
+    range(subject: string, start: Date | string, end: Date | string, options?: {
+        tenantId?: string;
+    }): Promise<TemporalRange>;
+}
+interface SearchResult {
+    assertion_id: string;
+    similarity: number;
+}
+interface SemanticSearchInput {
+    embedding: number[];
+    topK?: number;
+    tenantId?: string;
+}
+declare class SearchNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /** Semantic nearest-neighbor search over assertion embeddings. */
+    semantic(input: SemanticSearchInput): Promise<SearchResult[]>;
+}
+interface CreateEntityInput {
+    /** Entity name (used as the subject identifier, e.g. "Project") */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Entity type classification (e.g. "model", "workflow", "reference") */
+    type?: string;
+    /** Override default tenant */
+    tenantId?: string;
+}
+interface AddPropertyInput {
+    /** Entity name this property belongs to */
+    entityName: string;
+    /** Property name */
+    name: string;
+    /** Property field type (e.g. "string", "number", "date", "boolean", "reference") */
+    fieldType: string;
+    /** Whether this property is required */
+    required?: boolean;
+    /** Override default tenant */
+    tenantId?: string;
+}
+interface EntityDescription {
+    subject: string;
+    name: string;
+    type: string | null;
+    description: string | null;
+    properties: Array<{
+        name: string;
+        fieldType: string | null;
+        required: boolean;
+    }>;
+    relationships: Array<{
+        type: string;
+        target: string;
+        confidence: number;
+    }>;
+}
+declare class EntitiesNamespace {
+    private http;
+    private tenantId;
+    constructor(http: HttpTransport, tenantId: string);
+    /** Create an entity with optional description and type. */
+    create(input: CreateEntityInput): Promise<Assertion>;
+    /** Add a property to an entity. */
+    addProperty(input: AddPropertyInput): Promise<{
+        assertion: Assertion;
+        relationship: Relationship;
+    }>;
+    /** Describe an entity by reconstructing its properties and relationships from assertions. */
+    describe(entityName: string, options?: {
+        tenantId?: string;
+    }): Promise<EntityDescription>;
+    /** List all entities for a tenant (subjects with entity: prefix that have a type predicate). */
+    list(options?: {
+        tenantId?: string;
+    }): Promise<Assertion[]>;
+}
 declare class SubCortexClient {
     /** Assertion operations (low-level knowledge primitives) */
     readonly assertions: AssertionsNamespace;
@@ -1302,6 +1704,20 @@ declare class SubCortexClient {
     readonly users: UsersNamespace;
     /** Emotional signals — record, query, and resolve */
     readonly signals: SignalsNamespace;
+    /** Graph queries — pathfinding and traversal */
+    readonly graph: GraphNamespace;
+    /** Temporal queries — point-in-time snapshots and range queries */
+    readonly temporal: TemporalNamespace;
+    /** Semantic search over assertion embeddings */
+    readonly search: SearchNamespace;
+    /** BM25 full-text recall search */
+    readonly recall: RecallNamespace;
+    /** Episodic memory — experiences grouped by session */
+    readonly experiences: ExperiencesNamespace;
+    /** Entity schema management — create, describe, and manage data models */
+    readonly entities: EntitiesNamespace;
+    /** Code guardrails — typed rules stored as assertions with file-scope matching */
+    readonly rules: RulesNamespace;
     private readonly http;
     constructor(options: SubCortexClientOptions);
     /** Check SubCortex server health. */
@@ -1450,4 +1866,4 @@ declare class SubCortexTimeoutError extends SubCortexNetworkError {
     constructor(timeoutMs: number);
 }
 
-export { type AgentCapability, type AgentConfig, type AgentInstructions, type AgentMemoryPolicy, type AgentModelConfig, type AgentPersonality, AgentsNamespace, type Assertion, AssertionsNamespace, type BatchResult, CONTEXT_SCHEMA_VERSION, type CandidateAssertion, type ComposedInstructions, ConfidenceLevel, type ConfidenceScore, ConfidenceScores, type ConflictItem, type ConnectedPerson, type ContextFormat, type ContextFormatOptions, type CreateAgentInput, type CreateAssertionInput, type CreateRelationshipInput, EntityPredicate, EntityRelationship, EventPredicate, type HealthResponse, type IdentifyUserInput, IdentityPredicate, IntakeNamespace, type IntakeResponseItem, type IntakeResult, type IntakeStats, type IntakeSubmission, MULTI_VALUE_PREDICATES, MemoryNamespace, MemoryPredicate, NEGATIVE_SIGNALS, OrgRelationship, POSITIVE_SIGNALS, type PaginatedResponse, Predicates, type Provenance, RELATIONSHIP_LABELS, REVERSE_RELATIONSHIPS, RapportPredicate, type RecordRapportInput, type RecordSignalInput, type RegisterPersonInput, type RegisterPersonResult, type Relationship, RelationshipTypes, RelationshipsNamespace, type ResolveSignalInput, type RetryConfig, SIGNAL_DECAY_CONFIG, SYSTEM_SIGNAL_TYPES, type SignalEntry, type SignalQueryOptions, type SignalSnapshot, type SignalType, SignalsNamespace, type StoreMemoryInput, SubCortexAuthenticationError, SubCortexAuthorizationError, SubCortexClient, type SubCortexClientOptions, SubCortexConflictError, SubCortexError, SubCortexNetworkError, SubCortexNotFoundError, SubCortexRateLimitError, SubCortexServerError, SubCortexTimeoutError, SubCortexValidationError, SubjectPrefix, type SupersedeAssertionInput, type SystemSignalType, type TemporalBounds, type Trajectory, type UpdateAgentInput, type UserIdentification, type UserMemory, UsersNamespace, WorkPredicate, confidenceToScore, formatContext, getDecayHalfLife, isValidSignalType, scoreToConfidence, subject, toContextXml };
+export { type AddPropertyInput, type AgentCapability, type AgentConfig, type AgentInstructions, type AgentMemoryPolicy, type AgentModelConfig, type AgentPersonality, AgentsNamespace, type Assertion, AssertionsNamespace, type BatchResult, CONTEXT_SCHEMA_VERSION, type CandidateAssertion, type ComposedInstructions, ConfidenceLevel, type ConfidenceScore, ConfidenceScores, type ConflictItem, type ConnectedPerson, type ContextFormat, type ContextFormatOptions, type CreateAgentInput, type CreateAssertionInput, type CreateEntityInput, type CreateRelationshipInput, type CreateRuleInput, EntitiesNamespace, type EntityDescription, EntityPredicate, EntityRelationship, EventPredicate, type Experience, ExperiencesNamespace, type FindPathsInput, GraphNamespace, type GraphPath, type HealthResponse, type IdentifyUserInput, IdentityPredicate, IntakeNamespace, type IntakeResponseItem, type IntakeResult, type IntakeStats, type IntakeSubmission, MULTI_VALUE_PREDICATES, MemoryNamespace, MemoryPredicate, NEGATIVE_SIGNALS, OrgRelationship, POSITIVE_SIGNALS, type PaginatedResponse, Predicates, type Provenance, RELATIONSHIP_LABELS, REVERSE_RELATIONSHIPS, RapportPredicate, RecallNamespace, type RecallResult, type RecallSearchInput, type RecallSearchResponse, type RecordRapportInput, type RecordSignalInput, type RegisterPersonInput, type RegisterPersonResult, type Relationship, RelationshipTypes, RelationshipsNamespace, type ResolveSignalInput, type RetryConfig, type Rule, type RulePredicate, RulePredicates, type RuleQueryOptions, type RuleSeverity, type RuleType, type RuleValue, RulesNamespace, SIGNAL_DECAY_CONFIG, SYSTEM_SIGNAL_TYPES, SearchNamespace, type SearchResult, type SemanticSearchInput, type SignalEntry, type SignalQueryOptions, type SignalSnapshot, type SignalType, SignalsNamespace, type StoreMemoryInput, SubCortexAuthenticationError, SubCortexAuthorizationError, SubCortexClient, type SubCortexClientOptions, SubCortexConflictError, SubCortexError, SubCortexNetworkError, SubCortexNotFoundError, SubCortexRateLimitError, SubCortexServerError, SubCortexTimeoutError, SubCortexValidationError, SubjectPrefix, type SupersedeAssertionInput, type SystemSignalType, type TemporalBounds, TemporalNamespace, type TemporalRange, type TemporalSnapshot, type Trajectory, type TraversalNode, type TraversalResult, type TraverseInput, type UpdateAgentInput, type UpdateRuleInput, type UserIdentification, type UserMemory, UsersNamespace, WorkPredicate, confidenceToScore, formatContext, getDecayHalfLife, isValidSignalType, scoreToConfidence, subject, toContextXml };