@jamesaphoenix/tx-types 0.4.2 → 0.4.4

package/dist/learning.js

@@ -3,8 +3,13 @@
  *
  * Type definitions for the contextual learnings system.
  * See PRD-010 and DD-010 for specification.
- * Zero runtime dependencies - pure TypeScript types only.
+ * Core type definitions using Effect Schema (Doctrine Rule 10).
+ * Schema definitions provide both compile-time types and runtime validation.
  */
+import { Schema } from "effect";
+// =============================================================================
+// CONSTANTS
+// =============================================================================
 /**
  * Valid learning source types.
  */
@@ -14,4 +19,107 @@ export const LEARNING_SOURCE_TYPES = [
     "manual",
     "claude_md",
 ];
+// =============================================================================
+// SCHEMAS & TYPES
+// =============================================================================
+/** Learning source type - where the learning came from. */
+export const LearningSourceTypeSchema = Schema.Literal(...LEARNING_SOURCE_TYPES);
+/** Learning ID - branded integer. */
+export const LearningIdSchema = Schema.Number.pipe(Schema.int(), Schema.brand("LearningId"));
+/** Core learning entity. */
+export const LearningSchema = Schema.Struct({
+    id: LearningIdSchema,
+    content: Schema.String,
+    sourceType: LearningSourceTypeSchema,
+    sourceRef: Schema.NullOr(Schema.String),
+    createdAt: Schema.DateFromSelf,
+    keywords: Schema.Array(Schema.String),
+    category: Schema.NullOr(Schema.String),
+    usageCount: Schema.Number.pipe(Schema.int()),
+    lastUsedAt: Schema.NullOr(Schema.DateFromSelf),
+    outcomeScore: Schema.NullOr(Schema.Number),
+    embedding: Schema.NullOr(Schema.instanceOf(Float32Array)),
+});
+/** Learning with relevance scoring from search results. */
+export const LearningWithScoreSchema = Schema.Struct({
+    ...LearningSchema.fields,
+    relevanceScore: Schema.Number,
+    bm25Score: Schema.Number,
+    vectorScore: Schema.Number,
+    recencyScore: Schema.Number,
+    /** RRF (Reciprocal Rank Fusion) score from combining BM25 and vector rankings */
+    rrfScore: Schema.Number,
+    /** Rank in BM25 results (1-indexed, 0 if not in BM25 results) */
+    bm25Rank: Schema.Number.pipe(Schema.int()),
+    /** Rank in vector similarity results (1-indexed, 0 if not in vector results) */
+    vectorRank: Schema.Number.pipe(Schema.int()),
+    /** LLM reranker score (0-1, optional - only present when reranking is applied) */
+    rerankerScore: Schema.optional(Schema.Number),
+    /** Feedback score from historical usage (0-1, 0.5 = neutral, optional) */
+    feedbackScore: Schema.optional(Schema.Number),
+});
+/** Input for creating a new learning. */
+export const CreateLearningInputSchema = Schema.Struct({
+    content: Schema.String,
+    sourceType: Schema.optional(LearningSourceTypeSchema),
+    sourceRef: Schema.optional(Schema.NullOr(Schema.String)),
+    keywords: Schema.optional(Schema.Array(Schema.String)),
+    category: Schema.optional(Schema.NullOr(Schema.String)),
+});
+/** Input for updating an existing learning. */
+export const UpdateLearningInputSchema = Schema.Struct({
+    usageCount: Schema.optional(Schema.Number.pipe(Schema.int())),
+    lastUsedAt: Schema.optional(Schema.DateFromSelf),
+    outcomeScore: Schema.optional(Schema.Number),
+    embedding: Schema.optional(Schema.instanceOf(Float32Array)),
+});
+/** Query options for learning searches. */
+export const LearningQuerySchema = Schema.Struct({
+    query: Schema.String,
+    limit: Schema.optional(Schema.Number.pipe(Schema.int())),
+    minScore: Schema.optional(Schema.Number),
+    category: Schema.optional(Schema.String),
+    sourceType: Schema.optional(LearningSourceTypeSchema),
+});
+/** Options for context retrieval. */
+export const ContextOptionsSchema = Schema.Struct({
+    /** Maximum number of learnings to return (default: 10, capped at 50). Misnamed — this is a result count, not a token budget. */
+    maxTokens: Schema.optional(Schema.Number.pipe(Schema.int())),
+});
+/** Result of context retrieval for a task. */
+export const ContextResultSchema = Schema.Struct({
+    taskId: Schema.String,
+    taskTitle: Schema.String,
+    learnings: Schema.Array(LearningWithScoreSchema),
+    searchQuery: Schema.String,
+    searchDuration: Schema.Number,
+});
+/** Result of a learning search operation. */
+export const LearningSearchResultSchema = Schema.Struct({
+    learnings: Schema.Array(LearningSchema),
+    query: Schema.String,
+    searchDuration: Schema.Number,
+});
+/** Options for MMR (Maximal Marginal Relevance) diversification. See PRD-017. */
+export const DiversificationOptionsSchema = Schema.Struct({
+    /** Enable MMR diversification (default: false) */
+    enabled: Schema.optional(Schema.Boolean),
+    /** Trade-off between relevance (1.0) and diversity (0.0) (default: 0.7) */
+    lambda: Schema.optional(Schema.Number),
+    /** Maximum results per category for top 5 results (default: 2) */
+    maxPerCategory: Schema.optional(Schema.Number.pipe(Schema.int())),
+});
+/** Options for retrieval operations. Used by RetrieverService.search(). */
+export const RetrievalOptionsSchema = Schema.Struct({
+    /** Maximum number of results to return (default: 10) */
+    limit: Schema.optional(Schema.Number.pipe(Schema.int())),
+    /** Minimum relevance score threshold (default: 0.1) */
+    minScore: Schema.optional(Schema.Number),
+    /** Optional category filter */
+    category: Schema.optional(Schema.String),
+    /** Optional source type filter */
+    sourceType: Schema.optional(LearningSourceTypeSchema),
+    /** MMR diversification options for result variety */
+    diversification: Schema.optional(DiversificationOptionsSchema),
+});
 //# sourceMappingURL=learning.js.map

package/dist/learning.js.map

@@ -1 +1 @@
-{"version":3,"file":"learning.js","sourceRoot":"","sources":["../src/learning.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,YAAY;IACZ,KAAK;IACL,QAAQ;IACR,WAAW;CACH,CAAC"}
+{"version":3,"file":"learning.js","sourceRoot":"","sources":["../src/learning.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAE/B,gFAAgF;AAChF,YAAY;AACZ,gFAAgF;AAEhF;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,YAAY;IACZ,KAAK;IACL,QAAQ;IACR,WAAW;CACH,CAAC;AAEX,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,qBAAqB,CAAC,CAAA;AAGhF,qCAAqC;AACrC,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAChD,MAAM,CAAC,GAAG,EAAE,EACZ,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAC3B,CAAA;AAGD,4BAA4B;AAC5B,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1C,EAAE,EAAE,gBAAgB;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,UAAU,EAAE,wBAAwB;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACvC,SAAS,EAAE,MAAM,CAAC,YAAY;IAC9B,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;IACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;IAC5C,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC;IAC9C,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;CAC1D,CAAC,CAAA;AAGF,2DAA2D;AAC3D,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC;IACnD,GAAG,cAAc,CAAC,MAAM;IACxB,cAAc,EAAE,MAAM,CAAC,MAAM;IAC7B,SAAS,EAAE,MAAM,CAAC,MAAM;IACxB,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,YAAY,EAAE,MAAM,CAAC,MAAM;IAC3B,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC,MAAM;IACvB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;IAC1C,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;IAC5C,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IAC7C,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;CAC9C,CAAC,CAAA;AAGF,yCAAyC;AACzC,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrD,OAAO,EAAE,MAAM,CAAC,MAAM;IACtB,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IACrD,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACxD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACtD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;CACxD,CAAC,CAAA;AAGF,+CAA+C;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7D,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,YAAY,CAAC;IAChD,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;CAC5D,CAAC,CAAA;AAGF,2CAA2C;AAC3C,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAC;CACtD,CAAC,CAAA;AAGF,qCAAqC;AACrC,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC;IAChD,gIAAgI;IAChI,SAAS,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;CAC7D,CAAC,CAAA;AAGF,8CAA8C;AAC9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/C,MAAM,EAAE,MAAM,CAAC,MAAM;IACrB,SAAS,EAAE,MAAM,CAAC,MAAM;IACxB,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC,MAAM;IAC1B,cAAc,EAAE,MAAM,CAAC,MAAM;CAC9B,CAAC,CAAA;AAGF,6CAA6C;AAC7C,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,CAAC;IACtD,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC,MAAM;IACpB,cAAc,EAAE,MAAM,CAAC,MAAM;CAC9B,CAAC,CAAA;AAGF,iFAAiF;AACjF,MAAM,CAAC,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,CAAC;IACxD,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC;IACxC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACtC,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;CAClE,CAAC,CAAA;AAGF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,wBAAwB,CAAC;IACrD,qDAAqD;IACrD,eAAe,EAAE,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAAC;CAC/D,CAAC,CAAA"}