@vibe-hero/server 0.1.0

package/dist/schemas/profile.js

@@ -0,0 +1,177 @@
+/**
+ * @file Learner Profile schemas (read-write, per-user, local at ~/.vibe-hero/).
+ *
+ * The profile is a single Zod-validated JSON document. Privacy-critical: only
+ * derived grades/scores are persisted, never raw answer text (FR-018/024).
+ *
+ * Source of truth: specs/001-vibe-hero-mvp/data-model.md (§ Learner Profile).
+ */
+import { z } from "zod";
+import { AbilityKeySchema, GradeSchema, TierSchema, ToolIdSchema, } from "./common.js";
+/** ISO-8601 datetime string. */
+const IsoDateTimeSchema = z.string().datetime();
+/**
+ * User configuration written by the setup skill (FR-031). Absence of `config`
+ * on the root profile is the first-run setup gate (FR-032).
+ */
+export const ConfigSchema = z.object({
+    toolsLearning: z.array(ToolIdSchema),
+    offerCadence: z.enum(["off", "per_session", "per_topic"]),
+    proactiveOffers: z.boolean(),
+    quizLength: z.number().int().min(3).max(5).default(4),
+    createdAt: IsoDateTimeSchema,
+    updatedAt: IsoDateTimeSchema,
+});
+/**
+ * Elo-style ability estimate for one {@link AbilityKey}. `itemsSeen` drives the
+ * provisional → settled K-factor; `lastItemIds` avoids back-to-back repeats.
+ *
+ * `dwell` is the consecutive count of recent graded items that satisfied the
+ * promotion-crossing condition (FR-008 / SC-014). It is the dwell counter the
+ * pure graduation engine threads across `submit_answer` calls so a single fluke
+ * item cannot promote — incremented while θ stays above the promotion bar and
+ * reset to 0 the moment an item fails it. Defaulted to `0` so profiles written
+ * before this field read forward without migration (additive, forward-compat).
+ */
+export const AbilityEstimateSchema = z.object({
+    value: z.number(),
+    itemsSeen: z.number().int().nonnegative(),
+    lastAssessedAt: IsoDateTimeSchema,
+    lastItemIds: z.array(z.string().min(1)),
+    dwell: z.number().int().nonnegative().default(0),
+});
+/**
+ * Per-key graduation state with hysteresis (FR-008/009). `currentTier` is 0
+ * until the learner first graduates.
+ */
+export const TierGraduationSchema = z.object({
+    currentTier: z.union([TierSchema, z.literal(0)]),
+    status: z.enum(["current", "due_for_review"]),
+    graduatedAt: IsoDateTimeSchema,
+    lastChangeReason: z.enum(["graduated", "demoted", "review_due"]),
+});
+/** An entry in the due-for-review queue. */
+export const ReviewEntrySchema = z.object({
+    key: AbilityKeySchema,
+    dueAt: IsoDateTimeSchema,
+    reason: z.enum(["spaced", "lapsed"]),
+});
+/**
+ * One graded item inside a {@link QuizRecord}. Persists only the derived grade
+ * and continuous score — NO raw answer text (privacy, FR-018/024).
+ */
+export const AnsweredItemSchema = z.object({
+    itemId: z.string().min(1),
+    tier: TierSchema,
+    difficulty: z.number(),
+    grade: GradeSchema,
+    score: z.number().min(0).max(1),
+    gradedBy: z.enum(["engine", "host_agent"]),
+    answeredAt: IsoDateTimeSchema,
+});
+/**
+ * One quiz session. Only records with `completedAt` present count toward
+ * graduation; partial sessions are discarded.
+ */
+export const QuizRecordSchema = z.object({
+    id: z.string().min(1),
+    key: AbilityKeySchema,
+    startedAt: IsoDateTimeSchema,
+    completedAt: IsoDateTimeSchema.optional(),
+    items: z.array(AnsweredItemSchema),
+    abilityBefore: z.number(),
+    abilityAfter: z.number(),
+});
+/**
+ * Per-session offer accounting (anti-fatigue, FR-020/020a). Reset per session
+ * id. Under `per_session`: max 1 offer; a decline sets `declinedThisSession`
+ * and suppresses further offers. Under `per_topic`: at most one offer per
+ * distinct {@link AbilityKey} per session.
+ *
+ * `candidateKeys` is the per-session pool of topics that observed activity has
+ * flagged as offer-worthy (accumulated by `record_observation` as signals
+ * arrive). `get_offer` — which receives no signals of its own — resolves the
+ * surfaced offer from this pool. It is distinct from `offeredTopicKeys`, which
+ * records topics that have ALREADY surfaced (driving the `per_topic` cadence cap
+ * and the cross-session backoff). Defaulted to `[]` so older persisted profiles
+ * read forward without migration.
+ */
+export const OfferLedgerSchema = z.object({
+    // Empty string denotes "no session bound yet" (fresh / reset profile); a real
+    // session id is written when the first session begins.
+    sessionId: z.string(),
+    offersThisSession: z.number().int().nonnegative(),
+    declinedThisSession: z.boolean(),
+    offeredTopicKeys: z.array(AbilityKeySchema),
+    candidateKeys: z.array(AbilityKeySchema).default([]),
+});
+/**
+ * Cross-session backoff (FR-020b). Each decline lengthens the next-eligible
+ * interval; after N consecutive declines offers are globally muted via
+ * `mutedUntil`. An accept resets `consecutiveDeclines`.
+ */
+export const OfferBackoffSchema = z.object({
+    consecutiveDeclines: z.number().int().nonnegative(),
+    mutedUntil: IsoDateTimeSchema.optional(),
+    perTopicNextEligibleAt: z.record(AbilityKeySchema, IsoDateTimeSchema),
+});
+/**
+ * Transient, privacy-safe observation event derived from a hook payload and/or
+ * transcript record (correlated by `tool_use_id`, FR-017). Used only to
+ * populate offer candidates; never stored as raw prompt/tool I/O (FR-018).
+ */
+export const ObservationEventSchema = z.object({
+    tool: ToolIdSchema,
+    topicKeys: z.array(AbilityKeySchema),
+    success: z.boolean(),
+    timestamp: IsoDateTimeSchema,
+    correlationId: z.string().min(1),
+});
+/** Current profile document schema version (migration guard). */
+export const PROFILE_SCHEMA_VERSION = 1;
+/**
+ * The root learner profile document, persisted as a single JSON file. `config`
+ * absent ⇒ first-run setup gate (FR-032). `abilities`/`graduations` are keyed
+ * by {@link AbilityKeySchema} (`class|topic`).
+ */
+export const ProfileSchema = z.object({
+    schemaVersion: z.number().int().positive(),
+    createdAt: IsoDateTimeSchema,
+    updatedAt: IsoDateTimeSchema,
+    config: ConfigSchema.optional(),
+    abilities: z.record(AbilityKeySchema, AbilityEstimateSchema),
+    graduations: z.record(AbilityKeySchema, TierGraduationSchema),
+    reviewSchedule: z.array(ReviewEntrySchema),
+    quizHistory: z.array(QuizRecordSchema),
+    offers: OfferLedgerSchema,
+    backoff: OfferBackoffSchema,
+});
+/**
+ * Build a valid, empty profile for first-run / corrupted-file recovery
+ * (FR-023). `config` is intentionally omitted so the setup gate (FR-032)
+ * engages until the user runs setup.
+ *
+ * @param now - ISO timestamp to stamp `createdAt`/`updatedAt` and the empty
+ *   per-session ledger; defaults to the current time.
+ */
+export const emptyProfile = (now = new Date().toISOString()) => ({
+    schemaVersion: PROFILE_SCHEMA_VERSION,
+    createdAt: now,
+    updatedAt: now,
+    abilities: {},
+    graduations: {},
+    reviewSchedule: [],
+    quizHistory: [],
+    offers: {
+        sessionId: "",
+        offersThisSession: 0,
+        declinedThisSession: false,
+        offeredTopicKeys: [],
+        candidateKeys: [],
+    },
+    backoff: {
+        consecutiveDeclines: 0,
+        perTopicNextEligibleAt: {},
+    },
+});
+//# sourceMappingURL=profile.js.map

package/dist/schemas/profile.js.map

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