@vue-skuilder/db 0.1.23 → 0.1.25

package/dist/{types-DQaXnuoc.d.ts → types-CJrLM1Ew.d.ts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-DDY4N-Uq.js';
+import { D as DocType } from './types-legacy-JXDxinpU.js';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-Bn0itutr.d.cts → types-W8n-B6HG.d.cts}

@@ -1,5 +1,5 @@
 import { CourseConfig } from '@vue-skuilder/common';
-import { D as DocType } from './types-legacy-DDY4N-Uq.cjs';
+import { D as DocType } from './types-legacy-JXDxinpU.cjs';
 
 interface StaticCourseManifest {
     version: string;

package/dist/{types-legacy-DDY4N-Uq.d.cts → types-legacy-JXDxinpU.d.cts}

@@ -14,7 +14,9 @@ declare enum DocType {
     SCHEDULED_CARD = "SCHEDULED_CARD",
     TAG = "TAG",
     NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY",
-    STRATEGY_STATE = "STRATEGY_STATE"
+    STRATEGY_STATE = "STRATEGY_STATE",
+    USER_OUTCOME = "USER_OUTCOME",
+    STRATEGY_LEARNING_STATE = "STRATEGY_LEARNING_STATE"
 }
 interface QualifiedCardID {
     courseID: string;
@@ -91,6 +93,8 @@ declare const DocTypePrefixes: {
     readonly PEDAGOGY: "PEDAGOGY";
     readonly NAVIGATION_STRATEGY: "NAVIGATION_STRATEGY";
     readonly STRATEGY_STATE: "STRATEGY_STATE";
+    readonly USER_OUTCOME: "USER_OUTCOME";
+    readonly STRATEGY_LEARNING_STATE: "STRATEGY_LEARNING_STATE";
 };
 interface CardHistory<T extends CardRecord> {
     _id: PouchDB.Core.DocumentId;

package/dist/{types-legacy-DDY4N-Uq.d.ts → types-legacy-JXDxinpU.d.ts}

@@ -14,7 +14,9 @@ declare enum DocType {
     SCHEDULED_CARD = "SCHEDULED_CARD",
     TAG = "TAG",
     NAVIGATION_STRATEGY = "NAVIGATION_STRATEGY",
-    STRATEGY_STATE = "STRATEGY_STATE"
+    STRATEGY_STATE = "STRATEGY_STATE",
+    USER_OUTCOME = "USER_OUTCOME",
+    STRATEGY_LEARNING_STATE = "STRATEGY_LEARNING_STATE"
 }
 interface QualifiedCardID {
     courseID: string;
@@ -91,6 +93,8 @@ declare const DocTypePrefixes: {
     readonly PEDAGOGY: "PEDAGOGY";
     readonly NAVIGATION_STRATEGY: "NAVIGATION_STRATEGY";
     readonly STRATEGY_STATE: "STRATEGY_STATE";
+    readonly USER_OUTCOME: "USER_OUTCOME";
+    readonly STRATEGY_LEARNING_STATE: "STRATEGY_LEARNING_STATE";
 };
 interface CardHistory<T extends CardRecord> {
     _id: PouchDB.Core.DocumentId;

package/dist/util/packer/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-Bn0itutr.cjs';
-export { C as CouchDBToStaticPacker } from '../../index-B_j6u5E4.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-W8n-B6HG.cjs';
+export { C as CouchDBToStaticPacker } from '../../index-Ba7hYbHj.cjs';
 import '@vue-skuilder/common';
-import '../../types-legacy-DDY4N-Uq.cjs';
+import '../../types-legacy-JXDxinpU.cjs';
 import 'moment';

package/dist/util/packer/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-DQaXnuoc.js';
-export { C as CouchDBToStaticPacker } from '../../index-Dj0SEgk3.js';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig, S as StaticCourseManifest } from '../../types-CJrLM1Ew.js';
+export { C as CouchDBToStaticPacker } from '../../index-BWvO-_rJ.js';
 import '@vue-skuilder/common';
-import '../../types-legacy-DDY4N-Uq.js';
+import '../../types-legacy-JXDxinpU.js';
 import 'moment';

package/docs/brainstorm-navigation-paradigm.md

@@ -1,6 +1,10 @@
 # Brainstorm: Navigation Paradigm Exploration
 
 > **Status:** Informal brainstorming. Not a design doc or TODO.
+>
+> **Note:** Many concepts explored here have since been implemented.
+> See `navigators-architecture.md` for current architecture and
+> `devlog/1032-orchestrator` for evolutionary orchestration implementation.
 
 This document explores the navigation strategy paradigm: what other strategy types
 might exist, where the current design shines or struggles, and what alternative
@@ -79,7 +83,8 @@ Trigger-response generators need:
 4. **Exit criteria** — When does intervention end?
 
 This argues for strategies having **lifecycle state**, not just stateless scoring.
-See `todo-strategy-state-storage.md` for related concerns.
+**Update:** Strategy state storage is now implemented via `StrategyStateDoc` — see
+`navigators-architecture.md` for details.
 
 ---
 
@@ -138,7 +143,7 @@ Strategies are instantiated per-request. No persistence of:
 - "Last time I surfaced tag X was..."
 - "This user responds well to strategy Y"
 
-**Mitigation:** `todo-strategy-state-storage.md` (not implemented)
+**Mitigation:** ✅ Implemented via `StrategyStateDoc` — see `navigators-architecture.md`
 
 ### 2. Pull-Only Model
 
@@ -255,25 +260,30 @@ rules:
 **Pros:** Declarative, inspectable, author-configurable
 **Cons:** Limited expressiveness, new DSL to maintain
 
-### 4. Bandit Selection (Planned)
+### 4. Bandit-Style Selection (IMPLEMENTED ✅)
 
-Instead of a fixed pipeline, select among N candidate pipelines:
+Strategies carry **learnable weights** that automatically tune based on outcomes:
 
 ```
-PipelineA: ELO
-PipelineB: Hierarchy(ELO)
-PipelineC: Interference(Hierarchy(ELO))
-
-Orchestrator selects pipeline per-session based on:
-- User cohort
-- Historical effectiveness
-- Exploration/exploitation balance
+Strategy weights = { weight: 1.2, confidence: 0.8, sampleSize: 500 }
+
+Users are distributed across weight space via deviation:
+  effectiveWeight = peakWeight + deviation * spread
+  
+Gradient learning correlates deviation with outcomes:
+  +deviation → +outcome → increase peak
+  +deviation → -outcome → decrease peak
 ```
 
-**Pros:** Learns what works, self-improving
-**Cons:** Requires outcome measurement, cold-start problem
+**Implemented features:**
+- LearnableWeight on strategies
+- Deviation-based cohort distribution
+- Outcome recording per user/period
+- Gradient computation via linear regression
+- Automatic weight updates
+- Observability API endpoints
 
-See `todo-evolutionary-orchestration.md`.
+See `navigators-architecture.md` for details.
 
 ### 5. LLM-Guided Selection
 
@@ -316,23 +326,20 @@ Solver finds valid card sequence.
 
 Rather than wholesale paradigm shift, extend current model:
 
-### Near-term (compatible with naive orchestration)
+### Completed ✅
 
-1. **Richer context** — Pass session state to strategies
-2. **Trigger-response generator** — New generator type with activation state
-3. **Session-scoped state** — Allow strategies to persist within-session
+1. **Pipeline architecture** — Generators + Filters with provenance tracking
+2. **Strategy state storage** — User-scoped persistence via `StrategyStateDoc`
+3. **Evolutionary orchestration** — Learnable weights with gradient learning
+4. **Outcome measurement** — `UserOutcomeRecord` for tracking effectiveness
+5. **Observability** — API endpoints and admin dashboard
 
-### Medium-term (with strategy state storage)
+### Still Applicable
 
-4. **Cross-session state** — Strategies remember past sessions
-5. **Event hooks** — Strategies can subscribe to card results
-6. **Intervention protocol** — Active intervention preempts normal generation
-
-### Long-term (with evolutionary orchestration)
-
-7. **Bandit selection** among pipelines
-8. **Outcome measurement** for strategy effectiveness
-9. **Hybrid architectures** where blackboard/reactive patterns augment pipeline
+1. **Trigger-response generators** — Event-driven strategies with activation state
+2. **Richer context** — Session state, temporal context
+3. **Event hooks** — Strategies subscribing to card results
+4. **Intervention protocol** — Active intervention preempts normal generation
 
 ---
 
@@ -362,8 +369,7 @@ Rather than wholesale paradigm shift, extend current model:
 
 ## Related Documents
 
-- `navigators-architecture.md` — Current architecture
-- `todo-naive-orchestration.md` — Pipeline assembly (prerequisite)
-- `todo-strategy-state-storage.md` — State persistence
-- `todo-evolutionary-orchestration.md` — Bandit selection vision
-- `todo-provenance.md` — Audit trail (transparency)
+- `navigators-architecture.md` — Current architecture (includes evolutionary orchestration)
+- `future-orchestration-vision.md` — Remaining vision items (programmable strategies, self-healing)
+- `todo-strategy-authoring.md` — Strategy creation tools (UI complete)
+- `devlog/1032-orchestrator` — Evolutionary orchestration implementation

package/docs/future-orchestration-vision.md

@@ -0,0 +1,216 @@
+# Future Orchestration Vision
+
+This document tracks aspirational features for the evolutionary orchestration system
+that extend beyond the current implementation.
+
+## Status: VISION / NOT STARTED
+
+> **Prerequisite:** The core orchestration system (learnable weights, deviation-based
+> distribution, gradient learning) is implemented. See `navigators-architecture.md`
+> for the current architecture.
+
+---
+
+## Implemented (Reference)
+
+The following are **complete** and documented in `navigators-architecture.md`:
+
+- ✅ LearnableWeight interface with weight, confidence, sampleSize
+- ✅ Deviation-based weight distribution (bell curve sampling)
+- ✅ UserOutcomeRecord for tracking learning outcomes
+- ✅ Gradient computation via linear regression
+- ✅ Automatic weight updates based on gradient
+- ✅ Observability API endpoints (6 endpoints)
+- ✅ Admin dashboard in platform-ui
+
+---
+
+## Remaining Vision
+
+### 1. Parameterizable / Programmable Strategies
+
+**Goal:** Enable template-based prerequisite rules that generalize across courses.
+
+```typescript
+interface ParameterizedPrerequisite {
+  pattern: "grade-{n} & {subject}";
+  implies: "grade-{n+1} & {subject}";
+  constraints: {
+    n: { type: "number", min: 1, max: 12 },
+    subject: { type: "tag-category", category: "academic-subject" }
+  };
+}
+```
+
+**Example use cases:**
+- `grade-3 & geometry` → requires `grade-2 & geometry`
+- `unit-{n} & {topic}` → requires `unit-{n-1} & {topic}`
+- Cross-course strategy reuse without copy-paste
+
+**What's needed:**
+1. Template syntax design
+2. Variable binding and substitution
+3. Rule engine to evaluate parameterized rules
+4. Cross-course strategy registry
+
+---
+
+### 2. Self-Healing Content
+
+**Goal:** Automatically identify learning barriers and surface them to authors.
+
+**Barrier signals:**
+- High failure rate on specific cards/tags
+- ELO stagnation on specific topics
+- Long dwell time before mastery
+- Drop-off (users abandon at specific points)
+- Cohort-wide plateau detection
+
+**Components needed:**
+1. **Barrier Detection Pipeline** — Analyze outcomes to identify stuck points
+2. **Alert System** — Notify authors of identified barriers
+3. **Intervention Hooks** — Enable targeted content insertion
+4. **Feedback Loop** — Measure whether interventions resolve barriers
+
+**Example flow:**
+```
+Detection: 40% of users fail on "long-division-with-remainders" after
+           mastering "long-division-no-remainder"
+
+Alert: "Learning barrier detected between division topics.
+        Consider intermediate content for remainder concept."
+
+Author action: Adds 5 cards on "remainder as leftover" concept
+
+Feedback: Barrier detection re-runs, measures improvement
+```
+
+---
+
+### 3. Cross-Course Strategy Sharing
+
+**Goal:** Strategies that prove effective in one course can be shared and
+adapted to other courses.
+
+**Components:**
+- Strategy export/import format
+- Cross-course strategy registry
+- Adaptation hints for tag mapping
+- Reputation/effectiveness scores from source course
+
+---
+
+### 4. Author Incentive Mechanisms
+
+**Goal:** Create feedback loops that reward authors for effective content.
+
+**Potential signals:**
+- User outcomes correlated with specific content
+- Content utility weights (cards that consistently help)
+- Barrier resolution credit
+
+**Considerations:**
+- How to attribute outcomes to specific content when many cards contribute?
+- How to handle content that is effective but not "fun"?
+- Privacy implications of tracking detailed content effectiveness
+
+---
+
+### 5. Trigger-Response Generators
+
+**Goal:** Event-driven generators that activate under specific conditions.
+
+```typescript
+interface TriggerResponseGenerator {
+  trigger: {
+    condition: 'failureSpike' | 'plateau' | 'returnAfterGap' | 'frustration';
+    parameters: Record<string, number>;
+  };
+  response: {
+    mode: 'remedial' | 'confidence-building' | 'capstone';
+    targetTags?: string[];
+    duration?: { cards?: number; minutes?: number };
+  };
+}
+```
+
+**Example triggers:**
+- Frustration signal (N failures in M minutes) → easier content
+- Plateau detection (no ELO movement for K sessions) → challenging content
+- Inactivity return (first session after gap) → review-heavy session
+
+**What's needed:**
+- Event bus / signal mechanism for strategies to observe events
+- Activation state tracking ("I am currently intervening on tag T")
+- Priority over base generator (preempt vs blend)
+- Exit criteria (when does intervention end)
+
+See `brainstorm-navigation-paradigm.md` for detailed exploration.
+
+---
+
+### 6. Cohort-Aware Calibration
+
+**Goal:** Use population data to improve cold-start behavior.
+
+**Applications:**
+- Initial card difficulty estimates from population performance
+- Initial interval estimates based on similar users
+- Strategy weight priors from population effectiveness
+
+---
+
+### 7. LLM-Guided Selection (Experimental)
+
+**Goal:** Use language models to interpret learner state and select content.
+
+```
+Given:
+- User profile: { elo: 950, strugglingWith: ['vowel-sounds'], ... }
+- Session context: { duration: 12min, cardsSeen: 8, recentFailures: 2 }
+- Available cards: [...]
+
+Select the next 5 cards and explain reasoning.
+```
+
+**Considerations:**
+- Latency and cost
+- Unpredictability and debugging difficulty
+- When is LLM guidance worth the overhead?
+
+---
+
+## Design Decisions Ahead
+
+### Centralized vs Decentralized Orchestration
+
+**Option A: Central Orchestrator Service**
+- Single service decides strategy application
+- Cleaner cohort tracking
+- Requires backend infrastructure
+
+**Option B: Client-Side Orchestration**
+- Each client computes its own strategy set
+- Works offline
+- Harder to track cohorts
+
+**Current:** Hybrid — client computes from synced registry, outcomes reported to backend.
+
+### Outcome Attribution
+
+When multiple strategies are active, how do we attribute outcomes?
+
+- All strategies get credit/blame equally?
+- Weight by score contribution?
+- Require isolated A/B cells?
+
+**Current:** Equal attribution. Future work may instrument isolated testing.
+
+---
+
+## Related Documents
+
+- `navigators-architecture.md` — Current implementation (complete)
+- `brainstorm-navigation-paradigm.md` — Exploration of alternative mechanisms
+- `todo-strategy-authoring.md` — Strategy creation tools
+- `devlog/1032-orchestrator` — Implementation details