@isparling/engram-coach 0.1.0 → 0.2.0

package/engram-coach-config.ts

@@ -0,0 +1,268 @@
+/**
+ * engram-coach runtime configuration resolution and validation.
+ *
+ * This is the single canonical config resolver for engram-coach. It replaces
+ * the prose resolution order documented in `shared/setup.md` and SETUP.md:
+ *
+ *   1. `ENGRAM_COACH_CONFIG` (explicit override, nonblank)
+ *   2. `<projectRoot>/.engram-coach/config.json`
+ *   3. `~/.claude/engram-coach/config.json`
+ *
+ * The first candidate that exists wins; a config that exists but is
+ * malformed or invalid is a configuration error, never a silent fallback.
+ * Parsed JSON is validated field by field into real types — no untyped JSON
+ * escapes this module.
+ *
+ * Capture configuration: `model` comes from `ENGRAM_COACH_CAPTURE_MODEL`
+ * when nonblank, otherwise `capture.model`; absence of both is an error.
+ * Omitted timeout/candidate limits default to 60/3; explicit values must be
+ * positive integers with `timeout_seconds <= 60` and
+ * `max_candidates_per_turn <= 3`.
+ *
+ * @module engram-coach-config
+ */
+
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Runtime config types (camelCase — internal runtime surface)
+// ---------------------------------------------------------------------------
+
+export type CaptureConfig = {
+  model: string;
+  timeoutSeconds: number;
+  maxCandidatesPerTurn: number;
+};
+
+export type EngramCoachRuntimeConfig = {
+  activeProfile: string;
+  coachingDocsDir: string;
+  prescriptionsDir: string;
+  capture: CaptureConfig;
+};
+
+/** Raised when no config resolves or a resolved config fails validation. */
+export class EngramCoachConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "EngramCoachConfigError";
+  }
+}
+
+export type LoadEngramCoachConfigOptions = {
+  /** Environment variables; defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Absolute project working directory; defaults to `process.cwd()`. */
+  projectRoot?: string;
+  /** Absolute user home directory; defaults to `os.homedir()`. */
+  homeDir?: string;
+};
+
+export const DEFAULT_CAPTURE_TIMEOUT_SECONDS = 60;
+export const DEFAULT_CAPTURE_MAX_CANDIDATES_PER_TURN = 3;
+const MAX_CAPTURE_TIMEOUT_SECONDS = 60;
+const MAX_CAPTURE_CANDIDATES_PER_TURN = 3;
+
+const MISSING_MODEL_MESSAGE =
+  'capture model missing: set ENGRAM_COACH_CAPTURE_MODEL or add a nonblank "capture.model" to config.json';
+
+// ---------------------------------------------------------------------------
+// Field-level validation of parsed file JSON
+// ---------------------------------------------------------------------------
+
+/** Reads a required nonblank string field off a validated object. */
+function requiredString(
+  parent: { [key: string]: unknown },
+  key: string,
+  where: string,
+): string {
+  const value = parent[key];
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new EngramCoachConfigError(`${where}: "${key}" must be a nonblank string`);
+  }
+  return value;
+}
+
+/**
+ * Reads an optional positive-integer limit with a default ceiling: omitted
+ * falls back to `fallback`; explicit values must be integers in (0, max].
+ */
+function optionalLimit(
+  parent: { [key: string]: unknown },
+  key: string,
+  fallback: number,
+  max: number,
+  where: string,
+): number {
+  const value = parent[key];
+  if (value === undefined) {
+    return fallback;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0 || value > max) {
+    throw new EngramCoachConfigError(
+      `${where}: "${key}" must be a positive integer <= ${max} (got ${JSON.stringify(value)})`,
+    );
+  }
+  return value;
+}
+
+type RawCoachConfigFile = {
+  active_profile: string;
+  profiles: { [key: string]: unknown };
+};
+
+/**
+ * Validates parsed file JSON into the raw shape needed to build the runtime
+ * config. Throws {@link EngramCoachConfigError} on any structural problem.
+ */
+function parseConfigFile(parsed: unknown): RawCoachConfigFile {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new EngramCoachConfigError('config.json: top-level value must be an object');
+  }
+  const topLevel = parsed as { [key: string]: unknown };
+  const profiles = topLevel.profiles;
+  if (typeof profiles !== "object" || profiles === null || Array.isArray(profiles)) {
+    throw new EngramCoachConfigError('config.json: "profiles" must be an object');
+  }
+  return {
+    active_profile: requiredString(topLevel, "active_profile", "config.json"),
+    profiles: profiles as { [key: string]: unknown },
+  };
+}
+
+function profileEntry(
+  profiles: { [key: string]: unknown },
+  activeProfile: string,
+): { coaching_docs_dir: string; prescriptions_dir: string } {
+  const entry = profiles[activeProfile];
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    throw new EngramCoachConfigError(
+      `config.json: no profile named "${activeProfile}" under "profiles"`,
+    );
+  }
+  const fields = entry as { [key: string]: unknown };
+  const where = `profiles.${activeProfile}`;
+  return {
+    coaching_docs_dir: requiredString(fields, "coaching_docs_dir", where),
+    prescriptions_dir: requiredString(fields, "prescriptions_dir", where),
+  };
+}
+
+/**
+ * Validates the capture block and environment override into the runtime
+ * capture config. The env override wins when nonblank; absence of both
+ * model sources is a configuration error.
+ */
+function parseCaptureConfig(capture: unknown, envModel: string | undefined): CaptureConfig {
+  const trimmedEnvModel = envModel?.trim();
+  if (trimmedEnvModel === undefined || trimmedEnvModel.length === 0) {
+    if (
+      typeof capture !== "object" ||
+      capture === null ||
+      Array.isArray(capture) ||
+      typeof (capture as { [key: string]: unknown }).model !== "string" ||
+      ((capture as { [key: string]: unknown }).model as string).trim().length === 0
+    ) {
+      throw new EngramCoachConfigError(MISSING_MODEL_MESSAGE);
+    }
+  }
+  const model =
+    trimmedEnvModel !== undefined && trimmedEnvModel.length > 0
+      ? trimmedEnvModel
+      : ((capture as { [key: string]: unknown }).model as string).trim();
+
+  const limits: { [key: string]: unknown } =
+    typeof capture === "object" && capture !== null && !Array.isArray(capture)
+      ? (capture as { [key: string]: unknown })
+      : {};
+
+  return {
+    model,
+    timeoutSeconds: optionalLimit(
+      limits,
+      "timeout_seconds",
+      DEFAULT_CAPTURE_TIMEOUT_SECONDS,
+      MAX_CAPTURE_TIMEOUT_SECONDS,
+      "capture",
+    ),
+    maxCandidatesPerTurn: optionalLimit(
+      limits,
+      "max_candidates_per_turn",
+      DEFAULT_CAPTURE_MAX_CANDIDATES_PER_TURN,
+      MAX_CAPTURE_CANDIDATES_PER_TURN,
+      "capture",
+    ),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+function resolveCandidatePaths(options: LoadEngramCoachConfigOptions): string[] {
+  const candidates: string[] = [];
+  const explicit = options.env?.ENGRAM_COACH_CONFIG;
+  if (explicit !== undefined && explicit.trim().length > 0) {
+    candidates.push(explicit);
+  }
+  candidates.push(join(options.projectRoot ?? process.cwd(), ".engram-coach", "config.json"));
+  candidates.push(join(options.homeDir ?? homedir(), ".claude", "engram-coach", "config.json"));
+  return candidates;
+}
+
+async function readFirstExisting(
+  paths: string[],
+): Promise<{ path: string; contents: string }> {
+  for (const path of paths) {
+    let contents: string;
+    try {
+      contents = await readFile(path, "utf8");
+    } catch {
+      continue;
+    }
+    return { path, contents };
+  }
+  throw new EngramCoachConfigError(
+    "config not found; tried:\n" +
+      paths.map((path) => `  - ${path}`).join("\n") +
+      "\nRun the intake skill or copy config.json.example to .engram-coach/config.json",
+  );
+}
+
+/**
+ * Loads and validates the engram-coach runtime config using the standard
+ * path precedence. Throws {@link EngramCoachConfigError} when no candidate
+ * exists or the first existing candidate fails validation.
+ */
+export async function loadEngramCoachConfig(
+  options: LoadEngramCoachConfigOptions = {},
+): Promise<EngramCoachRuntimeConfig> {
+  const found = await readFirstExisting(resolveCandidatePaths(options));
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(found.contents);
+  } catch (error) {
+    throw new EngramCoachConfigError(
+      `${found.path}: invalid JSON (${error instanceof Error ? error.message : String(error)})`,
+    );
+  }
+
+  const file = parseConfigFile(parsed);
+  const profile = profileEntry(file.profiles, file.active_profile);
+  const capture = parseCaptureConfig(
+    typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+      ? (parsed as { [key: string]: unknown }).capture
+      : undefined,
+    options.env?.ENGRAM_COACH_CAPTURE_MODEL ?? process.env.ENGRAM_COACH_CAPTURE_MODEL,
+  );
+
+  return {
+    activeProfile: file.active_profile,
+    coachingDocsDir: profile.coaching_docs_dir,
+    prescriptionsDir: profile.prescriptions_dir,
+    capture,
+  };
+}

package/engram-coach-domain.ts

@@ -184,12 +184,17 @@ export type EngramCoachDetails = {
   /** Turn index within the session for provenance. */
   turnIndex: number;
 
-  /** Confidence: "high" when LLM was used, "low" for deterministic fallback. */
+  /**
+   * Confidence in the extraction. Ambient LLM candidates are "low" until a
+   * human reviews them; explicitly captured, athlete-approved records are
+   * "high".
+   */
   extractionConfidence: "high" | "low";
 };
 
 // ---------------------------------------------------------------------------
-// Coaching topic hints — expanded set for deterministic fallback extraction.
+// Coaching topic hints — the vocabulary skills and ambient prompts use to tag
+// scope topics.
 // ---------------------------------------------------------------------------
 
 export const COACHING_TOPIC_HINTS = [

package/engram-coach-keys.ts

@@ -0,0 +1,189 @@
+/**
+ * engram-coach canonical entity key derivation.
+ *
+ * Identity is derived by the pack, never accepted from an LLM or skill. A
+ * candidate may provide key components; this module validates and
+ * canonicalizes them into one of the pack's exact key formats:
+ *
+ *   workout:<session-id>
+ *   prescription:<arc-id>:<session-id>
+ *   threshold:<sport>:lt1
+ *   threshold:<sport>:lt2
+ *   persona:<active-profile>
+ *   monitoring:<concern-id>:<signal>
+ *
+ * Human components (sports, signals, profile names) are lower-case slug
+ * normalized. Durable IDs (session_id, arc_id, concern_id) are validated for
+ * safety and preserved verbatim — rescheduling or retitling never changes a
+ * key. Dates, titles, week numbers, and workout bodies never participate in
+ * identity: they live in `effective_at`, `statement`, and `details` and are
+ * ignored here.
+ *
+ * When a unique key cannot be derived the result is `unbound`; unbound
+ * candidates cannot supersede anything automatically and are surfaced as
+ * explicit preview blocks.
+ *
+ * @module engram-coach-keys
+ */
+
+import type { JsonObject, JsonValue } from "@isparling/engram-harness/knowledge-types";
+import type { StructuredStateChange } from "./engram-coach-capture-types.ts";
+
+/** The state entity types that participate in keyed identity. */
+export type KeyedEntityType = StructuredStateChange["entity_type"];
+
+/**
+ * Input to key derivation: any structured state capture, or the minimal
+ * subset of one ({ entity_type, key_components }). Extra structured fields
+ * (`effective_at`, `statement`, `details`) are accepted and deliberately
+ * excluded from identity.
+ */
+export type CanonicalEntityKeyInput =
+  & Pick<StructuredStateChange, "entity_type" | "key_components">
+  & Partial<Omit<StructuredStateChange, "entity_type" | "key_components">>;
+
+export type DerivedCanonicalEntityKey =
+  | { kind: "bound"; key: string }
+  | { kind: "unbound"; reason: string };
+
+/**
+ * Durable-ID grammar: nonempty, starts alphanumeric, then alphanumerics,
+ * `.`, `_`, `-`, or `~`. Colons and whitespace are excluded because `:` is
+ * the key separator and IDs must survive embedding in single-segment keys.
+ */
+const DURABLE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/;
+
+function isRecord(value: JsonValue): value is { [key: string]: JsonValue } {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Reads a string component from the key components object. */
+function component(
+  components: CanonicalEntityKeyInput["key_components"],
+  name: string,
+): string | null {
+  const value = components[name];
+  return typeof value === "string" ? value : null;
+}
+
+/**
+ * Validates a durable identifier and returns it verbatim. Empty, missing,
+ * or unsafe values yield null with a diagnostic naming the component.
+ */
+function durableId(components: JsonObject, name: string): string | null {
+  const raw = component(components, name);
+  if (raw === null || !DURABLE_ID_PATTERN.test(raw)) {
+    return null;
+  }
+  return raw;
+}
+
+/**
+ * Lower-case slug normalization for human-readable components: trim,
+ * lowercase, collapse every run of characters outside [a-z0-9] into `-`,
+ * and strip leading/trailing separators. Returns null when nothing usable
+ * remains.
+ */
+function slug(raw: string): string | null {
+  const normalized = raw
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized.length > 0 ? normalized : null;
+}
+
+function humanComponent(
+  components: JsonObject,
+  name: string,
+): string | null {
+  const raw = component(components, name);
+  return raw === null ? null : slug(raw);
+}
+
+function unbound(reason: string): DerivedCanonicalEntityKey {
+  return { kind: "unbound", reason };
+}
+
+function bound(key: string): DerivedCanonicalEntityKey {
+  return { kind: "bound", key };
+}
+
+/**
+ * Derives the canonical entity key for a structured state capture.
+ *
+ * Returns `{ kind: "bound", key }` with the exact format above, or
+ * `{ kind: "unbound", reason }` when required components are missing or
+ * invalid — including unknown state entity types, which have no defined
+ * identity format.
+ */
+export function deriveCanonicalEntityKey(
+  input: CanonicalEntityKeyInput,
+): DerivedCanonicalEntityKey {
+  const { entity_type } = input;
+  const components: JsonObject = isRecord(input.key_components)
+    ? input.key_components
+    : {};
+
+  switch (entity_type) {
+    case "workout": {
+      const sessionId = durableId(components, "session_id");
+      return sessionId === null
+        ? unbound("workout requires a valid session_id component")
+        : bound(`workout:${sessionId}`);
+    }
+
+    case "prescription": {
+      // Prescription keys require BOTH arc and session components; the
+      // invoking skill already has arc context from the loaded prescription.
+      const arcId = durableId(components, "arc_id");
+      if (arcId === null) {
+        return unbound("prescription requires a valid arc_id component");
+      }
+      const sessionId = durableId(components, "session_id");
+      if (sessionId === null) {
+        return unbound("prescription requires a valid session_id component");
+      }
+      return bound(`prescription:${arcId}:${sessionId}`);
+    }
+
+    case "threshold": {
+      const sport = humanComponent(components, "sport");
+      if (sport === null) {
+        return unbound("threshold requires a valid sport component");
+      }
+      const level = component(components, "level");
+      if (level === null || (level !== "lt1" && level !== "lt2" && level !== "LT1" && level !== "LT2")) {
+        return unbound("threshold level must be lt1 or lt2");
+      }
+      return bound(`threshold:${sport}:${level.toLowerCase()}`);
+    }
+
+    case "persona": {
+      const activeProfile = humanComponent(components, "active_profile");
+      return activeProfile === null
+        ? unbound("persona requires a valid active_profile component")
+        : bound(`persona:${activeProfile}`);
+    }
+
+    case "monitoring": {
+      const concernId = durableId(components, "concern_id");
+      if (concernId === null) {
+        return unbound("monitoring requires a valid concern_id component");
+      }
+      const signal = humanComponent(components, "signal");
+      if (signal === null) {
+        return unbound("monitoring requires a valid signal component");
+      }
+      return bound(`monitoring:${concernId}:${signal}`);
+    }
+
+    default: {
+      // Exhaustiveness guard: a new state entity type without a key format
+      // here fails derivation instead of inventing identity.
+      const exhaustive: never = entity_type;
+      void exhaustive;
+      return unbound("unknown state entity type has no canonical key format");
+    }
+  }
+}