@iworkforces/tracelattice 2.0.3

package/dist/contracts/PersistenceBackend.d.ts

@@ -0,0 +1,134 @@
+import type { ThoughtData } from '../core/thought.js';
+import type { Edge } from '../core/graph/Edge.js';
+import type { Summary } from '../core/compression/Summary.js';
+import type { BranchId, SessionId } from './ids.js';
+/**
+ * Persistence backend interface for storing thought history and branches.
+ *
+ * Implementations can store data in various formats (JSON files, SQLite, etc.)
+ * while providing a unified API for HistoryManager.
+ */
+export interface PersistenceBackend {
+    /**
+     * Save a single thought to persistent storage.
+     *
+     * @param thought - The thought data to persist
+     */
+    saveThought(thought: ThoughtData): Promise<void>;
+    /**
+     * Load all thoughts from persistent storage.
+     * Returns thoughts in chronological order (oldest first).
+     *
+     * @returns Array of all persisted thoughts
+     */
+    loadHistory(): Promise<ThoughtData[]>;
+    /**
+     * Save all thoughts in a branch to persistent storage.
+     *
+     * @param branchId - The unique identifier for the branch
+     * @param thoughts - Array of thoughts in branch
+     */
+    saveBranch(branchId: BranchId, thoughts: ThoughtData[]): Promise<void>;
+    /**
+     * Delete one global branch without treating an empty branch as deletion.
+     *
+     * Optional on legacy backends; the complete scoped capability requires it.
+     *
+     * @param branchId - The branch identifier to delete
+     */
+    deleteBranch?(branchId: BranchId): Promise<void>;
+    /**
+     * Load all thoughts for a specific branch.
+     *
+     * @param branchId - The unique identifier for the branch
+     * @returns Array of thoughts in branch, or undefined if branch doesn't exist
+     */
+    loadBranch(branchId: BranchId): Promise<ThoughtData[] | undefined>;
+    /**
+     * List all branch IDs that are persisted.
+     *
+     * @returns Array of branch identifiers
+     */
+    listBranches(): Promise<BranchId[]>;
+    /**
+     * Check if backend is healthy.
+     * @returns Promise that resolves to true if healthy, false otherwise
+     */
+    healthy(): Promise<boolean>;
+    /**
+     * Clear all persisted data (history and branches).
+     * Use with caution - this cannot be undone.
+     */
+    clear(): Promise<void>;
+    /**
+     * Close the backend and release resources.
+     * Should be called during graceful shutdown to ensure data is flushed.
+     */
+    close(): Promise<void>;
+    /**
+     * Save edges for a session, replacing any previously saved edges.
+     *
+     * @param sessionId - The session whose edges to persist
+     * @param edges - Array of edges to save
+     */
+    saveEdges(sessionId: SessionId, edges: readonly Edge[]): Promise<void>;
+    /**
+     * Load edges for a session from persistent storage.
+     * Returns edges in chronological order (by createdAt ascending).
+     * Returns empty array if no edges exist for the session.
+     *
+     * @param sessionId - The session whose edges to load
+     * @returns Array of persisted edges, sorted by createdAt
+     */
+    loadEdges(sessionId: SessionId): Promise<Edge[]>;
+    /**
+     * List all session IDs that have persisted edge data.
+     *
+     * @returns Array of session identifiers with persisted edges
+     */
+    listEdgeSessions(): Promise<SessionId[]>;
+    /**
+     * Save summaries for a session, replacing any previously saved summaries.
+     *
+     * @param sessionId - The session whose summaries to persist
+     * @param summaries - Array of summaries to save
+     */
+    saveSummaries(sessionId: SessionId, summaries: readonly Summary[]): Promise<void>;
+    /**
+     * Load summaries for a session from persistent storage.
+     * Returns summaries in chronological order (by createdAt ascending).
+     * Returns empty array if no summaries exist for the session.
+     *
+     * @param sessionId - The session whose summaries to load
+     * @returns Array of persisted summaries, sorted by createdAt
+     */
+    loadSummaries(sessionId: SessionId): Promise<Summary[]>;
+}
+/** Session-scoped persistence operations implemented as one indivisible capability. */
+export type SessionScopedPersistenceOperation = 'saveThoughtForSession' | 'loadHistoryForSession' | 'saveBranchForSession' | 'deleteBranch' | 'deleteBranchForSession' | 'loadBranchForSession' | 'listBranchesForSession' | 'listSessions' | 'clearSession';
+/** Persistence contract for durable named-session isolation. */
+export interface SessionScopedPersistenceBackend extends PersistenceBackend {
+    deleteBranch(branchId: BranchId): Promise<void>;
+    saveThoughtForSession(sessionId: SessionId, thought: ThoughtData): Promise<void>;
+    loadHistoryForSession(sessionId: SessionId): Promise<ThoughtData[]>;
+    saveBranchForSession(sessionId: SessionId, branchId: BranchId, thoughts: readonly ThoughtData[]): Promise<void>;
+    deleteBranchForSession(sessionId: SessionId, branchId: BranchId): Promise<void>;
+    loadBranchForSession(sessionId: SessionId, branchId: BranchId): Promise<ThoughtData[] | undefined>;
+    listBranchesForSession(sessionId: SessionId): Promise<BranchId[]>;
+    listSessions(): Promise<SessionId[]>;
+    clearSession(sessionId: SessionId): Promise<void>;
+}
+/** Return whether a backend implements every session-scoped operation. */
+export declare function supportsSessionScopedPersistence(backend: PersistenceBackend): backend is SessionScopedPersistenceBackend;
+export interface PersistenceConfig {
+    enabled?: boolean;
+    backend?: 'file' | 'sqlite' | 'memory';
+    options?: {
+        dataDir?: string;
+        dbPath?: string;
+        enableWAL?: boolean;
+        maxHistorySize?: number;
+        persistBranches?: boolean;
+    };
+}
+//# sourceMappingURL=PersistenceBackend.d.ts.map

package/dist/contracts/PersistenceBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PersistenceBackend.d.ts","sourceRoot":"","sources":["../../src/contracts/PersistenceBackend.ts"],"names":[],"mappings":"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"}

package/dist/contracts/PersistenceBackend.js

@@ -0,0 +1,6 @@
+function supportsSessionScopedPersistence(backend) {
+    return 'saveThoughtForSession' in backend && 'function' == typeof backend.saveThoughtForSession && 'loadHistoryForSession' in backend && 'function' == typeof backend.loadHistoryForSession && 'saveBranchForSession' in backend && 'function' == typeof backend.saveBranchForSession && 'deleteBranch' in backend && 'function' == typeof backend.deleteBranch && 'deleteBranchForSession' in backend && 'function' == typeof backend.deleteBranchForSession && 'loadBranchForSession' in backend && 'function' == typeof backend.loadBranchForSession && 'listBranchesForSession' in backend && 'function' == typeof backend.listBranchesForSession && 'listSessions' in backend && 'function' == typeof backend.listSessions && 'clearSession' in backend && 'function' == typeof backend.clearSession;
+}
+export { supportsSessionScopedPersistence };
+
+//# sourceMappingURL=PersistenceBackend.js.map

package/dist/contracts/PersistenceBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts/PersistenceBackend.js","sources":["../../src/contracts/PersistenceBackend.ts"],"sourcesContent":["import type { ThoughtData } from '../core/thought.js';\nimport type { Edge } from '../core/graph/Edge.js';\nimport type { Summary } from '../core/compression/Summary.js';\nimport type { BranchId, SessionId } from './ids.js';\n\n/**\n * Persistence backend interface for storing thought history and branches.\n *\n * Implementations can store data in various formats (JSON files, SQLite, etc.)\n * while providing a unified API for HistoryManager.\n */\nexport interface PersistenceBackend {\n\t/**\n\t * Save a single thought to persistent storage.\n\t *\n\t * @param thought - The thought data to persist\n\t */\n\tsaveThought(thought: ThoughtData): Promise<void>;\n\n\t/**\n\t * Load all thoughts from persistent storage.\n\t * Returns thoughts in chronological order (oldest first).\n\t *\n\t * @returns Array of all persisted thoughts\n\t */\n\tloadHistory(): Promise<ThoughtData[]>;\n\n\t/**\n\t * Save all thoughts in a branch to persistent storage.\n\t *\n\t * @param branchId - The unique identifier for the branch\n\t * @param thoughts - Array of thoughts in branch\n\t */\n\tsaveBranch(branchId: BranchId, thoughts: ThoughtData[]): Promise<void>;\n\n\t/**\n\t * Delete one global branch without treating an empty branch as deletion.\n\t *\n\t * Optional on legacy backends; the complete scoped capability requires it.\n\t *\n\t * @param branchId - The branch identifier to delete\n\t */\n\tdeleteBranch?(branchId: BranchId): Promise<void>;\n\n\t/**\n\t * Load all thoughts for a specific branch.\n\t *\n\t * @param branchId - The unique identifier for the branch\n\t * @returns Array of thoughts in branch, or undefined if branch doesn't exist\n\t */\n\tloadBranch(branchId: BranchId): Promise<ThoughtData[] | undefined>;\n\n\t/**\n\t * List all branch IDs that are persisted.\n\t *\n\t * @returns Array of branch identifiers\n\t */\n\tlistBranches(): Promise<BranchId[]>;\n\n\t/**\n\t * Check if backend is healthy.\n\t * @returns Promise that resolves to true if healthy, false otherwise\n\t */\n\thealthy(): Promise<boolean>;\n\n\t/**\n\t * Clear all persisted data (history and branches).\n\t * Use with caution - this cannot be undone.\n\t */\n\tclear(): Promise<void>;\n\n\t/**\n\t * Close the backend and release resources.\n\t * Should be called during graceful shutdown to ensure data is flushed.\n\t */\n\tclose(): Promise<void>;\n\n\t/**\n\t * Save edges for a session, replacing any previously saved edges.\n\t *\n\t * @param sessionId - The session whose edges to persist\n\t * @param edges - Array of edges to save\n\t */\n\tsaveEdges(sessionId: SessionId, edges: readonly Edge[]): Promise<void>;\n\n\t/**\n\t * Load edges for a session from persistent storage.\n\t * Returns edges in chronological order (by createdAt ascending).\n\t * Returns empty array if no edges exist for the session.\n\t *\n\t * @param sessionId - The session whose edges to load\n\t * @returns Array of persisted edges, sorted by createdAt\n\t */\n\tloadEdges(sessionId: SessionId): Promise<Edge[]>;\n\n\t/**\n\t * List all session IDs that have persisted edge data.\n\t *\n\t * @returns Array of session identifiers with persisted edges\n\t */\n\tlistEdgeSessions(): Promise<SessionId[]>;\n\n\t/**\n\t * Save summaries for a session, replacing any previously saved summaries.\n\t *\n\t * @param sessionId - The session whose summaries to persist\n\t * @param summaries - Array of summaries to save\n\t */\n\tsaveSummaries(sessionId: SessionId, summaries: readonly Summary[]): Promise<void>;\n\n\t/**\n\t * Load summaries for a session from persistent storage.\n\t * Returns summaries in chronological order (by createdAt ascending).\n\t * Returns empty array if no summaries exist for the session.\n\t *\n\t * @param sessionId - The session whose summaries to load\n\t * @returns Array of persisted summaries, sorted by createdAt\n\t */\n\tloadSummaries(sessionId: SessionId): Promise<Summary[]>;\n}\n\n/** Session-scoped persistence operations implemented as one indivisible capability. */\nexport type SessionScopedPersistenceOperation =\n\t| 'saveThoughtForSession'\n\t| 'loadHistoryForSession'\n\t| 'saveBranchForSession'\n\t| 'deleteBranch'\n\t| 'deleteBranchForSession'\n\t| 'loadBranchForSession'\n\t| 'listBranchesForSession'\n\t| 'listSessions'\n\t| 'clearSession';\n\n/** Persistence contract for durable named-session isolation. */\nexport interface SessionScopedPersistenceBackend extends PersistenceBackend {\n\tdeleteBranch(branchId: BranchId): Promise<void>;\n\tsaveThoughtForSession(sessionId: SessionId, thought: ThoughtData): Promise<void>;\n\tloadHistoryForSession(sessionId: SessionId): Promise<ThoughtData[]>;\n\tsaveBranchForSession(\n\t\tsessionId: SessionId,\n\t\tbranchId: BranchId,\n\t\tthoughts: readonly ThoughtData[]\n\t): Promise<void>;\n\tdeleteBranchForSession(sessionId: SessionId, branchId: BranchId): Promise<void>;\n\tloadBranchForSession(\n\t\tsessionId: SessionId,\n\t\tbranchId: BranchId\n\t): Promise<ThoughtData[] | undefined>;\n\tlistBranchesForSession(sessionId: SessionId): Promise<BranchId[]>;\n\tlistSessions(): Promise<SessionId[]>;\n\tclearSession(sessionId: SessionId): Promise<void>;\n}\n\n/** Return whether a backend implements every session-scoped operation. */\nexport function supportsSessionScopedPersistence(\n\tbackend: PersistenceBackend\n): backend is SessionScopedPersistenceBackend {\n\treturn (\n\t\t'saveThoughtForSession' in backend &&\n\t\ttypeof backend.saveThoughtForSession === 'function' &&\n\t\t'loadHistoryForSession' in backend &&\n\t\ttypeof backend.loadHistoryForSession === 'function' &&\n\t\t'saveBranchForSession' in backend &&\n\t\ttypeof backend.saveBranchForSession === 'function' &&\n\t\t'deleteBranch' in backend &&\n\t\ttypeof backend.deleteBranch === 'function' &&\n\t\t'deleteBranchForSession' in backend &&\n\t\ttypeof backend.deleteBranchForSession === 'function' &&\n\t\t'loadBranchForSession' in backend &&\n\t\ttypeof backend.loadBranchForSession === 'function' &&\n\t\t'listBranchesForSession' in backend &&\n\t\ttypeof backend.listBranchesForSession === 'function' &&\n\t\t'listSessions' in backend &&\n\t\ttypeof backend.listSessions === 'function' &&\n\t\t'clearSession' in backend &&\n\t\ttypeof backend.clearSession === 'function'\n\t);\n}\n\nexport interface PersistenceConfig {\n\tenabled?: boolean;\n\tbackend?: 'file' | 'sqlite' | 'memory';\n\toptions?: {\n\t\tdataDir?: string;\n\t\tdbPath?: string;\n\t\tenableWAL?: boolean;\n\t\tmaxHistorySize?: number;\n\t\tpersistBranches?: boolean;\n\t};\n}\n"],"names":["supportsSessionScopedPersistence","backend"],"mappings":"AA0JO,SAASA,iCACfC,OAA2B;IAE3B,OACC,2BAA2BA,WAC3B,AAAyC,cAAzC,OAAOA,QAAQ,qBAAqB,IACpC,2BAA2BA,WAC3B,AAAyC,cAAzC,OAAOA,QAAQ,qBAAqB,IACpC,0BAA0BA,WAC1B,AAAwC,cAAxC,OAAOA,QAAQ,oBAAoB,IACnC,kBAAkBA,WAClB,AAAgC,cAAhC,OAAOA,QAAQ,YAAY,IAC3B,4BAA4BA,WAC5B,AAA0C,cAA1C,OAAOA,QAAQ,sBAAsB,IACrC,0BAA0BA,WAC1B,AAAwC,cAAxC,OAAOA,QAAQ,oBAAoB,IACnC,4BAA4BA,WAC5B,AAA0C,cAA1C,OAAOA,QAAQ,sBAAsB,IACrC,kBAAkBA,WAClB,AAAgC,cAAhC,OAAOA,QAAQ,YAAY,IAC3B,kBAAkBA,WAClB,AAAgC,cAAhC,OAAOA,QAAQ,YAAY;AAE7B"}

package/dist/contracts/calibrator.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Calibrator contracts — interfaces for confidence calibration.
+ *
+ * Defines the shape of calibration metrics, results, and the calibrator
+ * service that maps raw model confidence to calibrated probabilities.
+ *
+ * @module contracts/calibrator
+ */
+import type { SessionId } from './ids.js';
+import type { ThoughtType } from './reasoning-types.js';
+/**
+ * Aggregate calibration quality metrics for a session (or globally).
+ *
+ * @example
+ * ```typescript
+ * const m: CalibrationMetrics = calibrator.metrics('session-1');
+ * console.log(m.brierScore, m.ece, m.sampleCount);
+ * ```
+ */
+export interface CalibrationMetrics {
+    /** Brier score across all samples (lower is better). `null` if no samples. */
+    readonly brierScore: number | null;
+    /** Expected Calibration Error (lower is better). `null` if no samples. */
+    readonly ece: number | null;
+    /** Number of (prediction, outcome) samples backing the metrics. */
+    readonly sampleCount: number;
+    /** Per-thought-type Brier score breakdown. `null` per bucket if empty. */
+    readonly perTypeBrier: Record<ThoughtType, number | null>;
+}
+/**
+ * Result of calibrating a single raw confidence value.
+ *
+ * @example
+ * ```typescript
+ * const r: CalibrationResult = calibrator.calibrate(0.9, 'hypothesis', 'session-1');
+ * // r.calibrated may be lower than r.raw if the model is over-confident.
+ * ```
+ */
+export interface CalibrationResult {
+    /** Original raw confidence in `[0, 1]`. */
+    readonly raw: number;
+    /** Calibrated confidence in `[0, 1]`. */
+    readonly calibrated: number;
+    /** Temperature used in the calibration mapping (1.0 = identity). */
+    readonly temperature: number;
+    /** Weight applied to the prior when blending with the raw signal. */
+    readonly priorWeight: number;
+}
+/**
+ * Calibrator service contract — converts raw confidence into calibrated
+ * probabilities and reports calibration quality.
+ *
+ * Implementations should be deterministic for the same `(raw, type, sessionId)`
+ * triple given a fixed internal state.
+ *
+ * @example
+ * ```typescript
+ * const result = calibrator.calibrate(0.85, 'verification', 'session-1');
+ * const stats  = calibrator.metrics('session-1');
+ * calibrator.refit('session-1');
+ * ```
+ */
+export interface ICalibrator {
+    /** Whether calibration is enabled. When `false`, `calibrate()` returns `raw` unchanged. */
+    readonly enabled: boolean;
+    /**
+     * Map a raw confidence value to a calibrated value.
+     *
+     * @param rawConfidence - Raw confidence in `[0, 1]`.
+     * @param type - Thought type the confidence is associated with.
+     * @param sessionId - Session identifier for per-session calibration state.
+     * @returns The calibration result.
+     */
+    calibrate(rawConfidence: number, type: ThoughtType, sessionId: SessionId): CalibrationResult;
+    /**
+     * Get calibration metrics for a session, or globally if `sessionId` is omitted.
+     *
+     * @param sessionId - Optional session id; omit for global metrics.
+     * @returns Aggregate calibration metrics.
+     */
+    metrics(sessionId?: SessionId): CalibrationMetrics;
+    /**
+     * Refit the calibration model from accumulated samples.
+     *
+     * @param sessionId - Optional session id; omit to refit global state.
+     */
+    refit(sessionId?: SessionId): void;
+    /**
+     * Remove the fitted temperature for one session while preserving global state.
+     *
+     * @param sessionId - Session identifier whose fitted temperature is removed.
+     */
+    clearSession(sessionId: SessionId): void;
+    /** Remove all fitted session and global temperatures. */
+    clearAll(): void;
+}
+//# sourceMappingURL=calibrator.d.ts.map

package/dist/contracts/calibrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calibrator.d.ts","sourceRoot":"","sources":["../../src/contracts/calibrator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IACjC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;OAOG;IACH,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,iBAAiB,CAAC;IAC7F;;;;;OAKG;IACH,OAAO,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,kBAAkB,CAAC;IACnD;;;;OAIG;IACH,KAAK,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACzC,yDAAyD;IACzD,QAAQ,IAAI,IAAI,CAAC;CACjB"}

package/dist/contracts/calibrator.js

@@ -0,0 +1 @@
+export { };

package/dist/contracts/features.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Feature flag definitions with const-asserted shape.
+ *
+ * @module contracts/features
+ */
+/**
+ * Feature flags for opt-in/out TraceLattice capabilities.
+ *
+ * All flags default to true (enabled). Opt-out via configuration.
+ */
+export interface FeatureFlags {
+    /** Enable DAG edges between thoughts. @default true */
+    readonly dagEdges: boolean;
+    /** Reasoning strategy selector. @default 'sequential' */
+    readonly reasoningStrategy: 'sequential' | 'tot';
+    /** Enable confidence calibration. @default true */
+    readonly calibration: boolean;
+    /** Enable thought compression. @default true */
+    readonly compression: boolean;
+    /** Enable tool interleaving. @default true */
+    readonly toolInterleave: boolean;
+    /** Enable new thought types. @default true */
+    readonly newThoughtTypes: boolean;
+    /** Enable outcome recording. @default true */
+    readonly outcomeRecording: boolean;
+}
+/**
+ * All feature flag keys as a union type.
+ */
+export type FeatureFlagKey = keyof FeatureFlags;
+/**
+ * Default feature flag values. All features enabled by default.
+ */
+export declare const DEFAULT_FLAGS: FeatureFlags;
+//# sourceMappingURL=features.d.ts.map

package/dist/contracts/features.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"features.d.ts","sourceRoot":"","sources":["../../src/contracts/features.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,iBAAiB,EAAE,YAAY,GAAG,KAAK,CAAC;IACjD,mDAAmD;IACnD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,YAAY,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,YAQlB,CAAC"}

package/dist/contracts/features.js

@@ -0,0 +1,12 @@
+const DEFAULT_FLAGS = {
+    dagEdges: true,
+    reasoningStrategy: 'sequential',
+    calibration: true,
+    compression: true,
+    toolInterleave: true,
+    newThoughtTypes: true,
+    outcomeRecording: true
+};
+export { DEFAULT_FLAGS };
+
+//# sourceMappingURL=features.js.map

package/dist/contracts/features.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts/features.js","sources":["../../src/contracts/features.ts"],"sourcesContent":["/**\n * Feature flag definitions with const-asserted shape.\n *\n * @module contracts/features\n */\n\n/**\n * Feature flags for opt-in/out TraceLattice capabilities.\n *\n * All flags default to true (enabled). Opt-out via configuration.\n */\nexport interface FeatureFlags {\n\t/** Enable DAG edges between thoughts. @default true */\n\treadonly dagEdges: boolean;\n\t/** Reasoning strategy selector. @default 'sequential' */\n\treadonly reasoningStrategy: 'sequential' | 'tot';\n\t/** Enable confidence calibration. @default true */\n\treadonly calibration: boolean;\n\t/** Enable thought compression. @default true */\n\treadonly compression: boolean;\n\t/** Enable tool interleaving. @default true */\n\treadonly toolInterleave: boolean;\n\t/** Enable new thought types. @default true */\n\treadonly newThoughtTypes: boolean;\n\t/** Enable outcome recording. @default true */\n\treadonly outcomeRecording: boolean;\n}\n\n/**\n * All feature flag keys as a union type.\n */\nexport type FeatureFlagKey = keyof FeatureFlags;\n\n/**\n * Default feature flag values. All features enabled by default.\n */\nexport const DEFAULT_FLAGS: FeatureFlags = {\n\tdagEdges: true,\n\treasoningStrategy: 'sequential',\n\tcalibration: true,\n\tcompression: true,\n\ttoolInterleave: true,\n\tnewThoughtTypes: true,\n\toutcomeRecording: true,\n} as const;\n\n"],"names":["DEFAULT_FLAGS"],"mappings":"AAoCO,MAAMA,gBAA8B;IAC1C,UAAU;IACV,mBAAmB;IACnB,aAAa;IACb,aAAa;IACb,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;AACnB"}

package/dist/contracts/ids.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Branded identifier types for compile-time slot safety.
+ *
+ * These nominal types prevent accidental mixing of different ID kinds
+ * (e.g. passing a `ThoughtId` where a `SessionId` is expected). At
+ * runtime they are plain strings — the brand exists only in the type
+ * system.
+ *
+ * @module contracts/ids
+ */
+declare const __brand: unique symbol;
+/**
+ * Nominal brand helper.
+ *
+ * The brand is a phantom property — it exists at the type level only
+ * and carries zero runtime cost.
+ */
+export type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/** Branded session identifier. */
+export type SessionId = Brand<string, 'SessionId'>;
+/** Branded thought identifier. */
+export type ThoughtId = Brand<string, 'ThoughtId'>;
+/** Branded edge identifier. */
+export type EdgeId = Brand<string, 'EdgeId'>;
+/** Branded suspension token. */
+export type SuspensionToken = Brand<string, 'SuspensionToken'>;
+/** Branded branch identifier. */
+export type BranchId = Brand<string, 'BranchId'>;
+/** Branded summary identifier. */
+export type SummaryId = Brand<string, 'SummaryId'>;
+/**
+ * Validate and brand a string as a {@link SessionId}.
+ *
+ * Enforces {@link SESSION_ID_PATTERN} and {@link MAX_SESSION_ID_LENGTH}.
+ * The reserved global session sentinel `__global__` is always accepted.
+ *
+ * @throws {ValidationError} when the input is not a valid session id.
+ */
+export declare function asSessionId(value: string): SessionId;
+/** Brand a string as a {@link ThoughtId} without validation. */
+export declare function asThoughtId(value: string): ThoughtId;
+/** Brand a string as an {@link EdgeId} without validation. */
+export declare function asEdgeId(value: string): EdgeId;
+/** Brand a string as a {@link SuspensionToken} without validation. */
+export declare function asSuspensionToken(value: string): SuspensionToken;
+/** Brand a string as a {@link BranchId} without validation. */
+export declare function asBranchId(value: string): BranchId;
+/** Brand a string as a {@link SummaryId} without validation. */
+export declare function asSummaryId(value: string): SummaryId;
+/** Generate a fresh {@link ThoughtId}. */
+export declare function generateThoughtId(): ThoughtId;
+/** Generate a fresh {@link EdgeId}. */
+export declare function generateEdgeId(): EdgeId;
+/** Generate a fresh {@link SuspensionToken}. */
+export declare function generateSuspensionToken(): SuspensionToken;
+/** Generate a fresh {@link SummaryId}. */
+export declare function generateSummaryId(): SummaryId;
+/**
+ * Reserved sentinel session id used when callers omit `session_id`.
+ *
+ * Branded once here so production and test code share one constant
+ * instead of casting `'__global__'` ad-hoc.
+ */
+export declare const GLOBAL_SESSION_ID: SessionId;
+export {};
+//# sourceMappingURL=ids.d.ts.map

package/dist/contracts/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/contracts/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,CAAC,MAAM,OAAO,EAAE,OAAO,MAAM,CAAC;AAErC;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAEvE,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEnD,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEnD,+BAA+B;AAC/B,MAAM,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE7C,gCAAgC;AAChC,MAAM,MAAM,eAAe,GAAG,KAAK,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAE/D,iCAAiC;AACjC,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AAEjD,kCAAkC;AAClC,MAAM,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAsBpD;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAEpD;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,CAEhE;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAElD;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAEpD;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,uCAAuC;AACvC,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,gDAAgD;AAChD,wBAAgB,uBAAuB,IAAI,eAAe,CAEzD;AAED,0CAA0C;AAC1C,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAqC,CAAC"}

package/dist/contracts/ids.js

@@ -0,0 +1,40 @@
+import { MAX_SESSION_ID_LENGTH, SESSION_ID_PATTERN, generateUlid } from "../core/ids.js";
+import { ValidationError } from "../errors.js";
+function asSessionId(value) {
+    if ('__global__' === value) return value;
+    if ('string' != typeof value || 0 === value.length) throw new ValidationError('session_id', 'must be a non-empty string');
+    if (value.length > MAX_SESSION_ID_LENGTH) throw new ValidationError('session_id', `exceeds max length of ${MAX_SESSION_ID_LENGTH}`);
+    if (!SESSION_ID_PATTERN.test(value)) throw new ValidationError('session_id', 'must match alphanumeric, hyphens, underscores');
+    return value;
+}
+function asThoughtId(value) {
+    return value;
+}
+function asEdgeId(value) {
+    return value;
+}
+function asSuspensionToken(value) {
+    return value;
+}
+function asBranchId(value) {
+    return value;
+}
+function asSummaryId(value) {
+    return value;
+}
+function generateThoughtId() {
+    return generateUlid();
+}
+function generateEdgeId() {
+    return generateUlid();
+}
+function generateSuspensionToken() {
+    return generateUlid();
+}
+function generateSummaryId() {
+    return generateUlid();
+}
+const GLOBAL_SESSION_ID = asSessionId('__global__');
+export { GLOBAL_SESSION_ID, asBranchId, asEdgeId, asSessionId, asSummaryId, asSuspensionToken, asThoughtId, generateEdgeId, generateSummaryId, generateSuspensionToken, generateThoughtId };
+
+//# sourceMappingURL=ids.js.map

package/dist/contracts/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts/ids.js","sources":["../../src/contracts/ids.ts"],"sourcesContent":["/**\n * Branded identifier types for compile-time slot safety.\n *\n * These nominal types prevent accidental mixing of different ID kinds\n * (e.g. passing a `ThoughtId` where a `SessionId` is expected). At\n * runtime they are plain strings — the brand exists only in the type\n * system.\n *\n * @module contracts/ids\n */\n\nimport {\n\tgenerateUlid,\n\tMAX_SESSION_ID_LENGTH,\n\tSESSION_ID_PATTERN,\n} from '../core/ids.js';\nimport { ValidationError } from '../errors.js';\n\ndeclare const __brand: unique symbol;\n\n/**\n * Nominal brand helper.\n *\n * The brand is a phantom property — it exists at the type level only\n * and carries zero runtime cost.\n */\nexport type Brand<T, B extends string> = T & { readonly [__brand]: B };\n\n/** Branded session identifier. */\nexport type SessionId = Brand<string, 'SessionId'>;\n\n/** Branded thought identifier. */\nexport type ThoughtId = Brand<string, 'ThoughtId'>;\n\n/** Branded edge identifier. */\nexport type EdgeId = Brand<string, 'EdgeId'>;\n\n/** Branded suspension token. */\nexport type SuspensionToken = Brand<string, 'SuspensionToken'>;\n\n/** Branded branch identifier. */\nexport type BranchId = Brand<string, 'BranchId'>;\n\n/** Branded summary identifier. */\nexport type SummaryId = Brand<string, 'SummaryId'>;\n\n/**\n * Validate and brand a string as a {@link SessionId}.\n *\n * Enforces {@link SESSION_ID_PATTERN} and {@link MAX_SESSION_ID_LENGTH}.\n * The reserved global session sentinel `__global__` is always accepted.\n *\n * @throws {ValidationError} when the input is not a valid session id.\n */\nexport function asSessionId(value: string): SessionId {\n\tif (value === '__global__') {\n\t\t// eslint-disable-next-line no-restricted-syntax -- branding constructor, cannot self-reference\n\t\treturn value as SessionId;\n\t}\n\tif (typeof value !== 'string' || value.length === 0) {\n\t\tthrow new ValidationError('session_id', 'must be a non-empty string');\n\t}\n\tif (value.length > MAX_SESSION_ID_LENGTH) {\n\t\tthrow new ValidationError(\n\t\t\t'session_id',\n\t\t\t`exceeds max length of ${MAX_SESSION_ID_LENGTH}`,\n\t\t);\n\t}\n\tif (!SESSION_ID_PATTERN.test(value)) {\n\t\tthrow new ValidationError(\n\t\t\t'session_id',\n\t\t\t'must match alphanumeric, hyphens, underscores',\n\t\t);\n\t}\n\t// eslint-disable-next-line no-restricted-syntax -- branding constructor, cannot self-reference\n\treturn value as SessionId;\n}\n\n/** Brand a string as a {@link ThoughtId} without validation. */\nexport function asThoughtId(value: string): ThoughtId {\n\treturn value as ThoughtId;\n}\n\n/** Brand a string as an {@link EdgeId} without validation. */\nexport function asEdgeId(value: string): EdgeId {\n\treturn value as EdgeId;\n}\n\n/** Brand a string as a {@link SuspensionToken} without validation. */\nexport function asSuspensionToken(value: string): SuspensionToken {\n\treturn value as SuspensionToken;\n}\n\n/** Brand a string as a {@link BranchId} without validation. */\nexport function asBranchId(value: string): BranchId {\n\treturn value as BranchId;\n}\n\n/** Brand a string as a {@link SummaryId} without validation. */\nexport function asSummaryId(value: string): SummaryId {\n\treturn value as SummaryId;\n}\n\n/** Generate a fresh {@link ThoughtId}. */\nexport function generateThoughtId(): ThoughtId {\n\treturn generateUlid() as ThoughtId;\n}\n\n/** Generate a fresh {@link EdgeId}. */\nexport function generateEdgeId(): EdgeId {\n\treturn generateUlid() as EdgeId;\n}\n\n/** Generate a fresh {@link SuspensionToken}. */\nexport function generateSuspensionToken(): SuspensionToken {\n\treturn generateUlid() as SuspensionToken;\n}\n\n/** Generate a fresh {@link SummaryId}. */\nexport function generateSummaryId(): SummaryId {\n\treturn generateUlid() as SummaryId;\n}\n\n/**\n * Reserved sentinel session id used when callers omit `session_id`.\n *\n * Branded once here so production and test code share one constant\n * instead of casting `'__global__'` ad-hoc.\n */\nexport const GLOBAL_SESSION_ID: SessionId = asSessionId('__global__');\n"],"names":["asSessionId","value","ValidationError","MAX_SESSION_ID_LENGTH","SESSION_ID_PATTERN","asThoughtId","asEdgeId","asSuspensionToken","asBranchId","asSummaryId","generateThoughtId","generateUlid","generateEdgeId","generateSuspensionToken","generateSummaryId","GLOBAL_SESSION_ID"],"mappings":";;AAsDO,SAASA,YAAYC,KAAa;IACxC,IAAIA,AAAU,iBAAVA,OAEH,OAAOA;IAER,IAAI,AAAiB,YAAjB,OAAOA,SAAsBA,AAAiB,MAAjBA,MAAM,MAAM,EAC5C,MAAM,IAAIC,gBAAgB,cAAc;IAEzC,IAAID,MAAM,MAAM,GAAGE,uBAClB,MAAM,IAAID,gBACT,cACA,CAAC,sBAAsB,EAAEC,uBAAuB;IAGlD,IAAI,CAACC,mBAAmB,IAAI,CAACH,QAC5B,MAAM,IAAIC,gBACT,cACA;IAIF,OAAOD;AACR;AAGO,SAASI,YAAYJ,KAAa;IACxC,OAAOA;AACR;AAGO,SAASK,SAASL,KAAa;IACrC,OAAOA;AACR;AAGO,SAASM,kBAAkBN,KAAa;IAC9C,OAAOA;AACR;AAGO,SAASO,WAAWP,KAAa;IACvC,OAAOA;AACR;AAGO,SAASQ,YAAYR,KAAa;IACxC,OAAOA;AACR;AAGO,SAASS;IACf,OAAOC;AACR;AAGO,SAASC;IACf,OAAOD;AACR;AAGO,SAASE;IACf,OAAOF;AACR;AAGO,SAASG;IACf,OAAOH;AACR;AAQO,MAAMI,oBAA+Bf,YAAY"}