selftune 0.2.10 → 0.2.13

package/node_modules/@selftune/telemetry-contract/fixtures/evidence-only-push.ts

@@ -0,0 +1,58 @@
+import type { PushPayloadV2 } from "../src/schemas.js";
+
+/**
+ * A valid PushPayloadV2 with only evolution_evidence entries and
+ * empty arrays for all other record types.
+ */
+export const evidenceOnlyPush: PushPayloadV2 = {
+  schema_version: "2.0",
+  client_version: "0.9.0",
+  push_id: "d4e5f6a7-b8c9-0123-defa-234567890123",
+  normalizer_version: "0.2.1",
+  canonical: {
+    sessions: [],
+    prompts: [],
+    skill_invocations: [],
+    execution_facts: [],
+    normalization_runs: [],
+    evolution_evidence: [
+      {
+        evidence_id: "ev_fixture_commit_001",
+        skill_name: "commit",
+        proposal_id: "evo-only-001",
+        target: "description",
+        stage: "deployed",
+        rationale: "Broadened trigger to catch 'save my work' patterns",
+        confidence: 0.91,
+        original_text: "Create git commits with good messages",
+        proposed_text:
+          "Create git commits with descriptive messages when asked to commit, save work, or checkpoint progress",
+        eval_set_json: {
+          positives: ["commit this", "save my work", "checkpoint"],
+          negatives: ["show git log", "what changed"],
+        },
+        validation_json: {
+          pass_rate_before: 0.76,
+          pass_rate_after: 0.92,
+          improvement: 0.16,
+        },
+      },
+      {
+        evidence_id: "ev_fixture_testrunner_002",
+        skill_name: "test-runner",
+        target: "routing",
+        stage: "proposed",
+        rationale: "Missing trigger for 'run my specs'",
+      },
+      {
+        evidence_id: "ev_fixture_deploy_003",
+        skill_name: "deploy-helper",
+        proposal_id: "evo-only-003",
+        target: "body",
+        stage: "validated",
+        confidence: 0.85,
+        raw_source_ref: { event_type: "evolution_evidence", raw_id: "evo-only-003" },
+      },
+    ],
+  },
+};

package/node_modules/@selftune/telemetry-contract/fixtures/golden.json

@@ -0,0 +1,88 @@
+[
+  {
+    "_description": "Minimal valid session record",
+    "record_kind": "session",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl" },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "started_at": "2026-01-15T11:50:00Z",
+    "ended_at": "2026-01-15T12:05:00Z",
+    "completion_status": "completed"
+  },
+  {
+    "_description": "Minimal valid prompt record",
+    "record_kind": "prompt",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl", "line": 3 },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "prompt_id": "golden-prompt-001",
+    "occurred_at": "2026-01-15T11:51:00Z",
+    "prompt_text": "Fix the login bug",
+    "prompt_kind": "user",
+    "is_actionable": true
+  },
+  {
+    "_description": "Minimal valid skill_invocation record",
+    "record_kind": "skill_invocation",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl", "line": 7 },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "skill_invocation_id": "golden-invocation-001",
+    "occurred_at": "2026-01-15T11:52:00Z",
+    "matched_prompt_id": "golden-prompt-001",
+    "skill_name": "commit",
+    "invocation_mode": "explicit",
+    "triggered": true,
+    "confidence": 1.0
+  },
+  {
+    "_description": "Minimal valid execution_fact record",
+    "record_kind": "execution_fact",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": { "path": "/tmp/raw/session-001.jsonl", "line": 15 },
+    "source_session_kind": "interactive",
+    "session_id": "golden-session-001",
+    "execution_fact_id": "golden-exec-fact-001",
+    "occurred_at": "2026-01-15T12:04:00Z",
+    "tool_calls_json": { "Read": 5, "Edit": 3, "Bash": 2 },
+    "total_tool_calls": 10,
+    "bash_commands_redacted": ["git status", "bun test"],
+    "assistant_turns": 4,
+    "errors_encountered": 0,
+    "completion_status": "completed"
+  },
+  {
+    "_description": "Minimal valid normalization_run record",
+    "record_kind": "normalization_run",
+    "schema_version": "2.0",
+    "normalizer_version": "0.2.1",
+    "normalized_at": "2026-01-15T12:00:00Z",
+    "platform": "claude_code",
+    "capture_mode": "hook",
+    "raw_source_ref": {},
+    "run_id": "golden-run-001",
+    "run_at": "2026-01-15T12:00:00Z",
+    "raw_records_seen": 42,
+    "canonical_records_written": 38,
+    "repair_applied": false
+  }
+]

package/node_modules/@selftune/telemetry-contract/fixtures/golden.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { CANONICAL_SCHEMA_VERSION } from "../src/types.js";
+import { isCanonicalRecord } from "../src/validators.js";
+
+const fixtures = JSON.parse(
+  readFileSync(join(import.meta.dirname, "golden.json"), "utf-8"),
+) as Record<string, unknown>[];
+
+describe("golden fixtures", () => {
+  test("all fixtures pass isCanonicalRecord", () => {
+    for (const fixture of fixtures) {
+      const desc = fixture._description ?? fixture.record_kind;
+      const result = isCanonicalRecord(fixture);
+      if (!result) throw new Error(`Failed: ${desc}`);
+      expect(result).toBe(true);
+    }
+  });
+
+  test("all fixtures use current schema version", () => {
+    for (const fixture of fixtures) {
+      expect(fixture.schema_version).toBe(CANONICAL_SCHEMA_VERSION);
+    }
+  });
+
+  test("covers every record_kind", () => {
+    const kinds = new Set(fixtures.map((f) => f.record_kind));
+    expect(kinds).toContain("session");
+    expect(kinds).toContain("prompt");
+    expect(kinds).toContain("skill_invocation");
+    expect(kinds).toContain("execution_fact");
+    expect(kinds).toContain("normalization_run");
+  });
+
+  test("mutated fixtures fail validation", () => {
+    for (const fixture of fixtures) {
+      const bad = { ...fixture, schema_version: "0.0" };
+      expect(isCanonicalRecord(bad)).toBe(false);
+    }
+  });
+});

package/node_modules/@selftune/telemetry-contract/fixtures/index.ts

@@ -0,0 +1,4 @@
+export { completePush } from "./complete-push.js";
+export { evidenceOnlyPush } from "./evidence-only-push.js";
+export { partialPushNoSessions } from "./partial-push-no-sessions.js";
+export { partialPushUnresolvedParents } from "./partial-push-unresolved-parents.js";

package/node_modules/@selftune/telemetry-contract/fixtures/partial-push-no-sessions.ts

@@ -0,0 +1,40 @@
+import type { PushPayloadV2 } from "../src/schemas.js";
+
+/**
+ * A valid PushPayloadV2 with zero sessions but non-empty evolution_evidence.
+ * Tests that partial pushes (no sessions) pass validation.
+ */
+export const partialPushNoSessions: PushPayloadV2 = {
+  schema_version: "2.0",
+  client_version: "0.9.0",
+  push_id: "b2c3d4e5-f6a7-8901-bcde-f12345678901",
+  normalizer_version: "0.2.1",
+  canonical: {
+    sessions: [],
+    prompts: [],
+    skill_invocations: [],
+    execution_facts: [],
+    normalization_runs: [],
+    evolution_evidence: [
+      {
+        evidence_id: "ev_nosess_deploy_001",
+        skill_name: "deploy-helper",
+        proposal_id: "prop-nosess-001",
+        target: "description",
+        stage: "validated",
+        rationale: "Expanded trigger coverage for deploy-related queries",
+        confidence: 0.88,
+        original_text: "Help with deployments",
+        proposed_text:
+          "Assist with deployment pipelines, rollbacks, and infrastructure provisioning",
+      },
+      {
+        evidence_id: "ev_nosess_codereview_002",
+        skill_name: "code-review",
+        target: "body",
+        stage: "proposed",
+        rationale: "Body rewrite for clearer instructions",
+      },
+    ],
+  },
+};

package/node_modules/@selftune/telemetry-contract/fixtures/partial-push-unresolved-parents.ts

@@ -0,0 +1,79 @@
+import type { PushPayloadV2 } from "../src/schemas.js";
+
+/**
+ * A valid PushPayloadV2 with invocations and prompts that reference a
+ * session_id NOT present in the sessions array.
+ *
+ * Tests that the contract allows unresolved parent references -- the
+ * session may have been pushed in a prior payload or may arrive later.
+ */
+export const partialPushUnresolvedParents: PushPayloadV2 = {
+  schema_version: "2.0",
+  client_version: "0.9.0",
+  push_id: "c3d4e5f6-a7b8-9012-cdef-123456789012",
+  normalizer_version: "0.2.1",
+  canonical: {
+    sessions: [],
+    prompts: [
+      {
+        record_kind: "prompt",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T11:00:00Z",
+        platform: "claude_code",
+        capture_mode: "replay",
+        raw_source_ref: { path: "/tmp/raw/orphan-session.jsonl", line: 2 },
+        source_session_kind: "replayed",
+        session_id: "orphan-session-999",
+        prompt_id: "orphan-prompt-001",
+        occurred_at: "2026-03-19T10:30:00Z",
+        prompt_text: "Refactor the database layer",
+        prompt_kind: "user",
+        is_actionable: true,
+        prompt_index: 0,
+      },
+    ],
+    skill_invocations: [
+      {
+        record_kind: "skill_invocation",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T11:00:00Z",
+        platform: "claude_code",
+        capture_mode: "replay",
+        raw_source_ref: { path: "/tmp/raw/orphan-session.jsonl", line: 5 },
+        source_session_kind: "replayed",
+        session_id: "orphan-session-999",
+        skill_invocation_id: "orphan-inv-001",
+        occurred_at: "2026-03-19T10:31:00Z",
+        matched_prompt_id: "orphan-prompt-001",
+        skill_name: "db-refactor",
+        invocation_mode: "inferred",
+        triggered: true,
+        confidence: 0.72,
+      },
+    ],
+    execution_facts: [
+      {
+        record_kind: "execution_fact",
+        schema_version: "2.0",
+        normalizer_version: "0.2.1",
+        normalized_at: "2026-03-19T11:00:00Z",
+        platform: "claude_code",
+        capture_mode: "replay",
+        raw_source_ref: { path: "/tmp/raw/orphan-session.jsonl", line: 12 },
+        source_session_kind: "replayed",
+        session_id: "orphan-session-999",
+        execution_fact_id: "orphan-ef-001",
+        occurred_at: "2026-03-19T10:45:00Z",
+        tool_calls_json: { Read: 8, Edit: 6, Bash: 4 },
+        total_tool_calls: 18,
+        assistant_turns: 7,
+        errors_encountered: 1,
+        duration_ms: 90000,
+        completion_status: "completed",
+      },
+    ],
+    normalization_runs: [],
+  },
+};

package/node_modules/@selftune/telemetry-contract/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.js";

package/node_modules/@selftune/telemetry-contract/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@selftune/telemetry-contract",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Canonical telemetry schema, types, and validators for selftune",
+  "license": "MIT",
+  "author": "Daniel Petro",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/selftune-dev/selftune.git",
+    "directory": "packages/telemetry-contract"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./schemas": "./src/schemas.ts",
+    "./types": "./src/types.ts",
+    "./validators": "./src/validators.ts",
+    "./fixtures": "./fixtures/index.ts"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/node_modules/@selftune/telemetry-contract/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./validators.js";

package/node_modules/@selftune/telemetry-contract/src/schemas.ts

@@ -0,0 +1,197 @@
+import { z } from "zod";
+
+import {
+  CANONICAL_CAPTURE_MODES,
+  CANONICAL_COMPLETION_STATUSES,
+  CANONICAL_INVOCATION_MODES,
+  CANONICAL_PLATFORMS,
+  CANONICAL_PROMPT_KINDS,
+  CANONICAL_RECORD_KINDS,
+  CANONICAL_SCHEMA_VERSION,
+  CANONICAL_SOURCE_SESSION_KINDS,
+} from "./types.js";
+
+export const canonicalPlatformSchema = z.enum(CANONICAL_PLATFORMS);
+export const captureModeSchema = z.enum(CANONICAL_CAPTURE_MODES);
+export const sourceSessionKindSchema = z.enum(CANONICAL_SOURCE_SESSION_KINDS);
+export const promptKindSchema = z.enum(CANONICAL_PROMPT_KINDS);
+export const invocationModeSchema = z.enum(CANONICAL_INVOCATION_MODES);
+export const completionStatusSchema = z.enum(CANONICAL_COMPLETION_STATUSES);
+export const recordKindSchema = z.enum(CANONICAL_RECORD_KINDS);
+
+export const rawSourceRefSchema = z.object({
+  path: z.string().optional(),
+  line: z.number().int().nonnegative().optional(),
+  event_type: z.string().optional(),
+  raw_id: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const canonicalRecordBaseSchema = z.object({
+  record_kind: recordKindSchema,
+  schema_version: z.literal(CANONICAL_SCHEMA_VERSION),
+  normalizer_version: z.string().min(1),
+  normalized_at: z.string().datetime(),
+  platform: canonicalPlatformSchema,
+  capture_mode: captureModeSchema,
+  raw_source_ref: rawSourceRefSchema,
+});
+
+export const canonicalSessionRecordBaseSchema = canonicalRecordBaseSchema.extend({
+  source_session_kind: sourceSessionKindSchema,
+  session_id: z.string().min(1),
+});
+
+export const CanonicalSessionRecordSchema = canonicalSessionRecordBaseSchema.extend({
+  record_kind: z.literal("session"),
+  external_session_id: z.string().optional(),
+  parent_session_id: z.string().optional(),
+  agent_id: z.string().optional(),
+  agent_type: z.string().optional(),
+  agent_cli: z.string().optional(),
+  session_key: z.string().optional(),
+  channel: z.string().optional(),
+  workspace_path: z.string().optional(),
+  repo_root: z.string().optional(),
+  repo_remote: z.string().optional(),
+  branch: z.string().optional(),
+  commit_sha: z.string().optional(),
+  permission_mode: z.string().optional(),
+  approval_policy: z.string().optional(),
+  sandbox_policy: z.string().optional(),
+  provider: z.string().optional(),
+  model: z.string().optional(),
+  started_at: z.string().datetime().optional(),
+  ended_at: z.string().datetime().optional(),
+  completion_status: completionStatusSchema.optional(),
+  end_reason: z.string().optional(),
+});
+
+export const CanonicalPromptRecordSchema = canonicalSessionRecordBaseSchema.extend({
+  record_kind: z.literal("prompt"),
+  prompt_id: z.string().min(1),
+  occurred_at: z.string().datetime(),
+  prompt_text: z.string().min(1),
+  prompt_hash: z.string().optional(),
+  prompt_kind: promptKindSchema,
+  is_actionable: z.boolean(),
+  prompt_index: z.number().int().nonnegative().optional(),
+  parent_prompt_id: z.string().optional(),
+  source_message_id: z.string().optional(),
+});
+
+export const CanonicalSkillInvocationRecordSchema = canonicalSessionRecordBaseSchema.extend({
+  record_kind: z.literal("skill_invocation"),
+  skill_invocation_id: z.string().min(1),
+  occurred_at: z.string().datetime(),
+  matched_prompt_id: z.string().min(1).optional(),
+  skill_name: z.string().min(1),
+  skill_path: z.string().optional(),
+  skill_version_hash: z.string().optional(),
+  invocation_mode: invocationModeSchema,
+  triggered: z.boolean(),
+  confidence: z.number().min(0).max(1),
+  tool_name: z.string().optional(),
+  tool_call_id: z.string().optional(),
+  agent_type: z.string().optional(),
+});
+
+export const CanonicalExecutionFactRecordSchema = canonicalSessionRecordBaseSchema.extend({
+  record_kind: z.literal("execution_fact"),
+  execution_fact_id: z.string().min(1),
+  occurred_at: z.string().datetime(),
+  prompt_id: z.string().optional(),
+  tool_calls_json: z.record(z.string(), z.number().finite()),
+  total_tool_calls: z.number().int().nonnegative(),
+  bash_commands_redacted: z.array(z.string()).optional(),
+  assistant_turns: z.number().int().nonnegative(),
+  errors_encountered: z.number().int().nonnegative(),
+  input_tokens: z.number().int().nonnegative().optional(),
+  output_tokens: z.number().int().nonnegative().optional(),
+  duration_ms: z.number().nonnegative().optional(),
+  completion_status: completionStatusSchema.optional(),
+  end_reason: z.string().optional(),
+});
+
+export const CanonicalNormalizationRunRecordSchema = canonicalRecordBaseSchema.extend({
+  record_kind: z.literal("normalization_run"),
+  run_id: z.string().min(1),
+  run_at: z.string().datetime(),
+  raw_records_seen: z.number().int().nonnegative(),
+  canonical_records_written: z.number().int().nonnegative(),
+  repair_applied: z.boolean(),
+});
+
+export const CanonicalEvolutionEvidenceRecordSchema = z.object({
+  evidence_id: z.string().min(1),
+  skill_name: z.string().min(1),
+  proposal_id: z.string().optional(),
+  target: z.string().min(1),
+  stage: z.string().min(1),
+  rationale: z.string().optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  original_text: z.string().optional(),
+  proposed_text: z.string().optional(),
+  eval_set_json: z.unknown().optional(),
+  validation_json: z.unknown().optional(),
+  raw_source_ref: rawSourceRefSchema.optional(),
+});
+
+export const OrchestrateRunSkillActionSchema = z.object({
+  skill: z.string().min(1),
+  action: z.enum(["evolve", "watch", "skip"]),
+  reason: z.string(),
+  deployed: z.boolean().optional(),
+  rolledBack: z.boolean().optional(),
+  alert: z.string().nullable().optional(),
+  elapsed_ms: z.number().nonnegative().optional(),
+  llm_calls: z.number().int().nonnegative().optional(),
+});
+
+export const PushOrchestrateRunRecordSchema = z.object({
+  run_id: z.string().min(1),
+  timestamp: z.string().datetime(),
+  elapsed_ms: z.number().int().nonnegative(),
+  dry_run: z.boolean(),
+  approval_mode: z.enum(["auto", "review"]),
+  total_skills: z.number().int().nonnegative(),
+  evaluated: z.number().int().nonnegative(),
+  evolved: z.number().int().nonnegative(),
+  deployed: z.number().int().nonnegative(),
+  watched: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  skill_actions: z.array(OrchestrateRunSkillActionSchema),
+});
+
+export const PushPayloadV2Schema = z.object({
+  schema_version: z.literal("2.0"),
+  client_version: z.string().min(1),
+  // Queue-generated push IDs are typically UUIDs, but the wire contract only
+  // requires a stable non-empty idempotency key.
+  push_id: z.string().min(1),
+  normalizer_version: z.string().min(1),
+  canonical: z.object({
+    sessions: z.array(CanonicalSessionRecordSchema).min(0),
+    prompts: z.array(CanonicalPromptRecordSchema).min(0),
+    skill_invocations: z.array(CanonicalSkillInvocationRecordSchema).min(0),
+    execution_facts: z.array(CanonicalExecutionFactRecordSchema).min(0),
+    normalization_runs: z.array(CanonicalNormalizationRunRecordSchema).min(0),
+    evolution_evidence: z.array(CanonicalEvolutionEvidenceRecordSchema).optional(),
+    orchestrate_runs: z.array(PushOrchestrateRunRecordSchema).optional(),
+  }),
+});
+
+export type PushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
+export type ZodCanonicalSessionRecord = z.infer<typeof CanonicalSessionRecordSchema>;
+export type ZodCanonicalPromptRecord = z.infer<typeof CanonicalPromptRecordSchema>;
+export type ZodCanonicalSkillInvocationRecord = z.infer<
+  typeof CanonicalSkillInvocationRecordSchema
+>;
+export type ZodCanonicalExecutionFactRecord = z.infer<typeof CanonicalExecutionFactRecordSchema>;
+export type ZodCanonicalNormalizationRunRecord = z.infer<
+  typeof CanonicalNormalizationRunRecordSchema
+>;
+export type ZodCanonicalEvolutionEvidenceRecord = z.infer<
+  typeof CanonicalEvolutionEvidenceRecordSchema
+>;
+export type ZodPushOrchestrateRunRecord = z.infer<typeof PushOrchestrateRunRecordSchema>;