selftune 0.2.22 → 0.2.23

package/cli/selftune/sync.ts

@@ -7,6 +7,7 @@
  * - Codex rollout logs
  * - OpenCode session history
  * - OpenClaw session history
+ * - Pi session history
  *
  * After syncing raw session/query/telemetry records, it rebuilds the repaired
  * skill-usage overlay from Claude transcripts and Codex rollouts so monitoring,
@@ -25,6 +26,8 @@ import {
   OPENCLAW_AGENTS_DIR,
   OPENCLAW_INGEST_MARKER,
   OPENCODE_INGEST_MARKER,
+  PI_INGEST_MARKER,
+  PI_SESSIONS_DIR,
   QUERY_LOG,
   REPAIRED_SKILL_LOG,
   REPAIRED_SKILL_SESSIONS_MARKER,
@@ -56,7 +59,14 @@ import {
   readSessionsFromSqlite,
   writeSession as writeOpenCodeSession,
 } from "./ingestors/opencode-ingest.js";
+import {
+  findPiSessions,
+  findPiSkillNames,
+  parsePiSession,
+  writeSession as writePiSession,
+} from "./ingestors/pi-ingest.js";
 import { getDb } from "./localdb/db.js";
+import { writeCronRunToDb } from "./localdb/direct-write.js";
 import { querySkillUsageRecords } from "./localdb/queries.js";
 import {
   persistRepairedSkillUsageToDb,
@@ -91,6 +101,7 @@ export interface SyncResult {
     codex: SyncStepResult;
     opencode: SyncStepResult;
     openclaw: SyncStepResult;
+    pi: SyncStepResult;
   };
   repair: {
     ran: boolean;
@@ -113,6 +124,7 @@ export interface SyncOptions {
   codexHome: string;
   opencodeDataDir: string;
   openclawAgentsDir: string;
+  piSessionsDir: string;
   skillLogPath: string;
   repairedSkillLogPath: string;
   repairedSessionsPath: string;
@@ -123,6 +135,7 @@ export interface SyncOptions {
   syncCodex: boolean;
   syncOpenCode: boolean;
   syncOpenClaw: boolean;
+  syncPi: boolean;
   rebuildSkillUsage: boolean;
 }
 
@@ -133,6 +146,7 @@ export interface SyncDeps {
   syncCodex?: (options: SyncOptions) => SyncStepResult;
   syncOpenCode?: (options: SyncOptions) => SyncStepResult;
   syncOpenClaw?: (options: SyncOptions) => SyncStepResult;
+  syncPi?: (options: SyncOptions) => SyncStepResult;
   rebuildSkillUsage?: (options: SyncOptions) => {
     repairedSessions: number;
     repairedRecords: number;
@@ -154,6 +168,7 @@ export function createDefaultSyncOptions(overrides: Partial<SyncOptions> = {}):
     codexHome: DEFAULT_CODEX_HOME,
     opencodeDataDir: DEFAULT_OPENCODE_DATA_DIR,
     openclawAgentsDir: OPENCLAW_AGENTS_DIR,
+    piSessionsDir: PI_SESSIONS_DIR,
     skillLogPath: SKILL_LOG,
     repairedSkillLogPath: REPAIRED_SKILL_LOG,
     repairedSessionsPath: REPAIRED_SKILL_SESSIONS_MARKER,
@@ -163,6 +178,7 @@ export function createDefaultSyncOptions(overrides: Partial<SyncOptions> = {}):
     syncCodex: true,
     syncOpenCode: true,
     syncOpenClaw: true,
+    syncPi: true,
     rebuildSkillUsage: true,
     ...overrides,
   };
@@ -356,6 +372,45 @@ function syncOpenClawSource(
   };
 }
 
+function syncPiSource(options: SyncOptions, onProgress?: SyncProgressCallback): SyncStepResult {
+  if (!existsSync(options.piSessionsDir)) {
+    return { available: false, scanned: 0, synced: 0, skipped: 0 };
+  }
+
+  onProgress?.("scanning Pi sessions...");
+  const sinceTs = options.since ? options.since.getTime() : null;
+  const allSessions = findPiSessions(options.piSessionsDir, sinceTs);
+  const skillNames = findPiSkillNames();
+  const alreadyIngested = options.force ? new Set<string>() : loadMarker(PI_INGEST_MARKER);
+  const pending = allSessions.filter((session) => !alreadyIngested.has(session.sessionId));
+  onProgress?.(`found ${allSessions.length} sessions, ${pending.length} pending`);
+  const newIngested = new Set<string>();
+  let synced = 0;
+  let skipped = 0;
+
+  for (const sessionFile of pending) {
+    const session = parsePiSession(sessionFile.filePath, skillNames);
+    if (!session.session_id || !session.timestamp) {
+      skipped += 1;
+      continue;
+    }
+    writePiSession(session, options.dryRun);
+    newIngested.add(sessionFile.sessionId);
+    synced += 1;
+  }
+
+  if (!options.dryRun && newIngested.size > 0) {
+    saveMarker(PI_INGEST_MARKER, new Set([...alreadyIngested, ...newIngested]));
+  }
+
+  return {
+    available: true,
+    scanned: allSessions.length,
+    synced,
+    skipped,
+  };
+}
+
 function rebuildSkillUsageOverlay(
   options: SyncOptions,
   onProgress?: SyncProgressCallback,
@@ -445,6 +500,7 @@ export function syncSources(
   const runCodex = deps.syncCodex;
   const runOpenCode = deps.syncOpenCode;
   const runOpenClaw = deps.syncOpenClaw;
+  const runPi = deps.syncPi;
   const runRepair = deps.rebuildSkillUsage;
   const runCreatorContributions = deps.stageCreatorContributions;
   const db = getDb();
@@ -485,6 +541,10 @@ export function syncSources(
       )
     : disabledStep;
 
+  const pi = options.syncPi
+    ? timePhase("pi", () => (runPi ? runPi(options) : syncPiSource(options, onProgress)), timings)
+    : disabledStep;
+
   const repair = options.rebuildSkillUsage
     ? timePhase(
         "repair",
@@ -512,10 +572,10 @@ export function syncSources(
 
   const totalElapsed = Math.round(performance.now() - totalStart);
 
-  return {
+  const syncResult: SyncResult = {
     since: options.since ? options.since.toISOString() : null,
     dry_run: options.dryRun,
-    sources: { claude, codex, opencode, openclaw },
+    sources: { claude, codex, opencode, openclaw, pi },
     repair: {
       ran: options.rebuildSkillUsage,
       repaired_sessions: repair.repairedSessions,
@@ -526,6 +586,8 @@ export function syncSources(
     timings,
     total_elapsed_ms: totalElapsed,
   };
+
+  return syncResult;
 }
 
 function formatMs(ms: number): string {
@@ -549,6 +611,7 @@ export async function cliMain(): Promise<void> {
       "codex-home": { type: "string", default: DEFAULT_CODEX_HOME },
       "opencode-data-dir": { type: "string", default: DEFAULT_OPENCODE_DATA_DIR },
       "openclaw-agents-dir": { type: "string", default: OPENCLAW_AGENTS_DIR },
+      "pi-sessions-dir": { type: "string", default: PI_SESSIONS_DIR },
       "skill-log": { type: "string", default: SKILL_LOG },
       "repaired-skill-log": { type: "string", default: REPAIRED_SKILL_LOG },
       "repaired-sessions-marker": { type: "string", default: REPAIRED_SKILL_SESSIONS_MARKER },
@@ -559,6 +622,7 @@ export async function cliMain(): Promise<void> {
       "no-codex": { type: "boolean", default: false },
       "no-opencode": { type: "boolean", default: false },
       "no-openclaw": { type: "boolean", default: false },
+      "no-pi": { type: "boolean", default: false },
       "no-repair": { type: "boolean", default: false },
       json: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
@@ -577,6 +641,7 @@ Options:
   --codex-home <dir>               Codex home directory (default: ~/.codex)
   --opencode-data-dir <dir>        OpenCode data directory
   --openclaw-agents-dir <dir>      OpenClaw agents directory
+  --pi-sessions-dir <dir>          Pi sessions directory
   --skill-log <path>               Raw skill usage log path
   --repaired-skill-log <path>      Repaired overlay log path
   --repaired-sessions-marker <p>   Repaired session marker path
@@ -587,6 +652,7 @@ Options:
   --no-codex                       Skip Codex rollout ingest
   --no-opencode                    Skip OpenCode ingest
   --no-openclaw                    Skip OpenClaw ingest
+  --no-pi                          Skip Pi ingest
   --no-repair                      Skip rebuilt skill-usage overlay
   --json                           Output raw JSON instead of human-readable summary
   -h, --help                       Show this help`);
@@ -622,27 +688,64 @@ Options:
     process.stderr.write(`selftune sync${flags.length ? ` ${flags.join(" ")}` : ""}\n`);
   }
 
-  const result = syncSources(
-    createDefaultSyncOptions({
-      projectsDir: values["projects-dir"] ?? CLAUDE_CODE_PROJECTS_DIR,
-      codexHome: values["codex-home"] ?? DEFAULT_CODEX_HOME,
-      opencodeDataDir: values["opencode-data-dir"] ?? DEFAULT_OPENCODE_DATA_DIR,
-      openclawAgentsDir: values["openclaw-agents-dir"] ?? OPENCLAW_AGENTS_DIR,
-      skillLogPath: values["skill-log"] ?? SKILL_LOG,
-      repairedSkillLogPath: values["repaired-skill-log"] ?? REPAIRED_SKILL_LOG,
-      repairedSessionsPath: values["repaired-sessions-marker"] ?? REPAIRED_SKILL_SESSIONS_MARKER,
-      since,
-      dryRun: values["dry-run"] ?? false,
-      force: values.force ?? false,
-      syncClaude: !(values["no-claude"] ?? false),
-      syncCodex: !(values["no-codex"] ?? false),
-      syncOpenCode: !(values["no-opencode"] ?? false),
-      syncOpenClaw: !(values["no-openclaw"] ?? false),
-      rebuildSkillUsage: !(values["no-repair"] ?? false),
-    }),
-    {},
-    onProgress,
-  );
+  const syncStartedAt = new Date();
+  const syncStart = performance.now();
+  let result: SyncResult;
+  try {
+    result = syncSources(
+      createDefaultSyncOptions({
+        projectsDir: values["projects-dir"] ?? CLAUDE_CODE_PROJECTS_DIR,
+        codexHome: values["codex-home"] ?? DEFAULT_CODEX_HOME,
+        opencodeDataDir: values["opencode-data-dir"] ?? DEFAULT_OPENCODE_DATA_DIR,
+        openclawAgentsDir: values["openclaw-agents-dir"] ?? OPENCLAW_AGENTS_DIR,
+        piSessionsDir: values["pi-sessions-dir"] ?? PI_SESSIONS_DIR,
+        skillLogPath: values["skill-log"] ?? SKILL_LOG,
+        repairedSkillLogPath: values["repaired-skill-log"] ?? REPAIRED_SKILL_LOG,
+        repairedSessionsPath: values["repaired-sessions-marker"] ?? REPAIRED_SKILL_SESSIONS_MARKER,
+        since,
+        dryRun: values["dry-run"] ?? false,
+        force: values.force ?? false,
+        syncClaude: !(values["no-claude"] ?? false),
+        syncCodex: !(values["no-codex"] ?? false),
+        syncOpenCode: !(values["no-opencode"] ?? false),
+        syncOpenClaw: !(values["no-openclaw"] ?? false),
+        syncPi: !(values["no-pi"] ?? false),
+        rebuildSkillUsage: !(values["no-repair"] ?? false),
+      }),
+      {},
+      onProgress,
+    );
+  } catch (err) {
+    const syncElapsed = Math.round(performance.now() - syncStart);
+    const message = err instanceof Error ? err.message : String(err);
+    writeCronRunToDb(getDb(), {
+      jobName: "sync",
+      startedAt: syncStartedAt.toISOString(),
+      elapsedMs: syncElapsed,
+      status: "error",
+      error: message,
+    });
+    throw err;
+  }
+
+  // Log successful sync run to unified cron_runs timeline
+  const syncElapsed = Math.round(performance.now() - syncStart);
+  const s = result.sources;
+  writeCronRunToDb(getDb(), {
+    jobName: "sync",
+    startedAt: syncStartedAt.toISOString(),
+    elapsedMs: syncElapsed,
+    status: "success",
+    metrics: {
+      total_synced:
+        s.claude.synced + s.codex.synced + s.opencode.synced + s.openclaw.synced + s.pi.synced,
+      claude_synced: s.claude.synced,
+      codex_synced: s.codex.synced,
+      opencode_synced: s.opencode.synced,
+      openclaw_synced: s.openclaw.synced,
+      pi_synced: s.pi.synced,
+    },
+  });
 
   if (jsonOutput) {
     console.log(JSON.stringify(result, null, 2));
@@ -662,6 +765,7 @@ Options:
     process.stderr.write(
       `${formatStepLine("OpenClaw", result.sources.openclaw, timingMap.get("openclaw"))}\n`,
     );
+    process.stderr.write(`${formatStepLine("Pi", result.sources.pi, timingMap.get("pi"))}\n`);
 
     if (result.repair.ran) {
       const repairTiming = timingMap.get("repair");

package/cli/selftune/types.ts

@@ -34,7 +34,7 @@ export type AlphaLinkState =
   | "ready";
 
 export interface SelftuneConfig {
-  agent_type: "claude_code" | "codex" | "opencode" | "openclaw" | "unknown";
+  agent_type: "claude_code" | "codex" | "opencode" | "openclaw" | "pi" | "unknown";
   cli_path: string;
   llm_mode: "agent";
   agent_cli: string | null;
@@ -738,6 +738,7 @@ export interface BodyValidationResult {
   before_pass_rate?: number;
   after_pass_rate?: number;
   per_entry_results?: RoutingReplayEntryResult[];
+  before_entry_results?: RoutingReplayEntryResult[];
 }
 
 /** Configuration for which LLM model a role should use. */

package/cli/selftune/utils/jsonl.ts

@@ -1,9 +1,8 @@
 /**
- * JSONL read/write/append utilities.
+ * JSONL read utilities and marker file helpers.
  */
 
 import {
-  appendFileSync,
   closeSync,
   existsSync,
   fstatSync,
@@ -15,10 +14,6 @@ import {
 } from "node:fs";
 import { dirname } from "node:path";
 
-import { createLogger } from "./logging.js";
-import type { LogType } from "./schema-validator.js";
-import { validateRecord } from "./schema-validator.js";
-
 /**
  * Read a JSONL file and return parsed records.
  * Skips blank lines and lines that fail to parse.
@@ -86,30 +81,6 @@ export function readJsonlFrom<T = Record<string, unknown>>(
   }
 }
 
-/**
- * Append a single record to a JSONL file. Creates parent directories if needed.
- * When logType is provided, validates the record and logs warnings on failure
- * but still writes the record (fail-open: hooks must never block).
- *
- * @deprecated Phase 3: JSONL writes removed. Retained for materializer/test utilities only.
- */
-export function appendJsonl(path: string, record: unknown, logType?: LogType): void {
-  if (logType) {
-    const result = validateRecord(record, logType);
-    if (!result.valid) {
-      const logger = createLogger("jsonl");
-      for (const error of result.errors) {
-        logger.warn(`Validation warning for ${logType}: ${error}`);
-      }
-    }
-  }
-  const dir = dirname(path);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
-  }
-  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf-8");
-}
-
 /**
  * Load a marker file (JSON array of strings) for idempotent ingestion.
  */

package/cli/selftune/utils/skill-discovery.ts

@@ -263,6 +263,28 @@ export function classifySkillPath(
   return { skill_scope: "unknown" };
 }
 
+const TEST_PATH_SEGMENTS = [
+  "/tests/",
+  "/__tests__/",
+  "/test/",
+  "/fixtures/",
+  "/sandbox/",
+  "/test-data/",
+  "/testdata/",
+  "/mock/",
+  "/mocks/",
+];
+
+/**
+ * Check if a skill path is inside a test/fixture directory.
+ * Used to prevent test fixture skills from leaking into production data.
+ */
+export function isTestFixturePath(skillPath: string): boolean {
+  if (!skillPath) return false;
+  const normalized = skillPath.toLowerCase();
+  return TEST_PATH_SEGMENTS.some((seg) => normalized.includes(seg));
+}
+
 export function extractSkillNamesFromInstructions(
   text: string,
   knownSkillNames?: Iterable<string>,

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

@@ -7,7 +7,7 @@ import type { PushPayloadV2 } from "../src/schemas.js";
 export const evidenceOnlyPush: PushPayloadV2 = {
   schema_version: "2.0",
   client_version: "0.9.0",
-  push_id: "d4e5f6a7-b8c9-0123-defa-234567890123",
+  push_id: "d4e5f6a7-b8c9-8123-9efa-234567890123",
   normalizer_version: "0.2.1",
   canonical: {
     sessions: [],

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

@@ -1,7 +1,6 @@
 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";
 

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

@@ -10,7 +10,7 @@ import type { PushPayloadV2 } from "../src/schemas.js";
 export const partialPushUnresolvedParents: PushPayloadV2 = {
   schema_version: "2.0",
   client_version: "0.9.0",
-  push_id: "c3d4e5f6-a7b8-9012-cdef-123456789012",
+  push_id: "c3d4e5f6-a7b8-8012-8def-123456789012",
   normalizer_version: "0.2.1",
   canonical: {
     sessions: [],

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

@@ -13,9 +13,9 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./schemas": "./src/schemas.ts",
     "./types": "./src/types.ts",
     "./validators": "./src/validators.ts",
+    "./schemas": "./src/schemas.ts",
     "./fixtures": "./fixtures/index.ts"
   },
   "dependencies": {

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

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

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

@@ -1,5 +1,13 @@
-import { z } from "zod";
+/**
+ * Zod validation schemas for all canonical telemetry record types
+ * and the PushPayloadV2 envelope.
+ *
+ * This is the single source of truth -- cloud consumers should import
+ * from @selftune/telemetry-contract/schemas instead of maintaining
+ * their own copies.
+ */
 
+import { z } from "zod";
 import {
   CANONICAL_CAPTURE_MODES,
   CANONICAL_COMPLETION_STATUSES,
@@ -11,6 +19,8 @@ import {
   CANONICAL_SOURCE_SESSION_KINDS,
 } from "./types.js";
 
+// ---------- Shared enum schemas ----------
+
 export const canonicalPlatformSchema = z.enum(CANONICAL_PLATFORMS);
 export const captureModeSchema = z.enum(CANONICAL_CAPTURE_MODES);
 export const sourceSessionKindSchema = z.enum(CANONICAL_SOURCE_SESSION_KINDS);
@@ -19,6 +29,8 @@ export const invocationModeSchema = z.enum(CANONICAL_INVOCATION_MODES);
 export const completionStatusSchema = z.enum(CANONICAL_COMPLETION_STATUSES);
 export const recordKindSchema = z.enum(CANONICAL_RECORD_KINDS);
 
+// ---------- Shared structural schemas ----------
+
 export const rawSourceRefSchema = z.object({
   path: z.string().optional(),
   line: z.number().int().nonnegative().optional(),
@@ -42,6 +54,8 @@ export const canonicalSessionRecordBaseSchema = canonicalRecordBaseSchema.extend
   session_id: z.string().min(1),
 });
 
+// ---------- Canonical record schemas ----------
+
 export const CanonicalSessionRecordSchema = canonicalSessionRecordBaseSchema.extend({
   record_kind: z.literal("session"),
   external_session_id: z.string().optional(),
@@ -137,6 +151,8 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   raw_source_ref: rawSourceRefSchema.optional(),
 });
 
+// ---------- Orchestrate run schemas ----------
+
 export const OrchestrateRunSkillActionSchema = z.object({
   skill: z.string().min(1),
   action: z.enum(["evolve", "watch", "skip"]),
@@ -163,12 +179,12 @@ export const PushOrchestrateRunRecordSchema = z.object({
   skill_actions: z.array(OrchestrateRunSkillActionSchema),
 });
 
+// ---------- Push V2 envelope ----------
+
 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),
+  push_id: z.string().uuid(),
   normalizer_version: z.string().min(1),
   canonical: z.object({
     sessions: z.array(CanonicalSessionRecordSchema).min(0),
@@ -181,6 +197,8 @@ export const PushPayloadV2Schema = z.object({
   }),
 });
 
+// ---------- Inferred types from Zod schemas ----------
+
 export type PushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
 export type ZodCanonicalSessionRecord = z.infer<typeof CanonicalSessionRecordSchema>;
 export type ZodCanonicalPromptRecord = z.infer<typeof CanonicalPromptRecordSchema>;

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

@@ -1,7 +1,7 @@
 export const CANONICAL_SCHEMA_VERSION = "2.0" as const;
 export type CanonicalSchemaVersion = typeof CANONICAL_SCHEMA_VERSION;
 
-export const CANONICAL_PLATFORMS = ["claude_code", "codex", "opencode", "openclaw"] as const;
+export const CANONICAL_PLATFORMS = ["claude_code", "codex", "opencode", "openclaw", "pi"] as const;
 export type CanonicalPlatform = (typeof CANONICAL_PLATFORMS)[number];
 
 export const CANONICAL_CAPTURE_MODES = [
@@ -143,18 +143,7 @@ export interface CanonicalExecutionFactRecord extends CanonicalSessionRecordBase
   errors_encountered: number;
   input_tokens?: number;
   output_tokens?: number;
-  cached_input_tokens?: number;
-  reasoning_output_tokens?: number;
-  cost_usd?: number;
   duration_ms?: number;
-  files_changed?: number;
-  lines_added?: number;
-  lines_removed?: number;
-  lines_modified?: number;
-  /** Count of output-producing tool calls (Write, Edit, WebFetch, WebSearch, Skill, Agent). */
-  artifact_count?: number;
-  /** Inferred session type based on tool distribution. */
-  session_type?: "dev" | "research" | "content" | "mixed";
   completion_status?: CanonicalCompletionStatus;
   end_reason?: string;
 }

package/node_modules/@selftune/telemetry-contract/tests/compatibility.test.ts

@@ -1,5 +1,4 @@
 import { describe, expect, test } from "bun:test";
-
 import { completePush } from "../fixtures/complete-push.js";
 import { evidenceOnlyPush } from "../fixtures/evidence-only-push.js";
 import { partialPushNoSessions } from "../fixtures/partial-push-no-sessions.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.22",
+  "version": "0.2.23",
   "description": "Self-improving skills CLI for AI agents",
   "keywords": [
     "agent",

package/packages/telemetry-contract/fixtures/evidence-only-push.ts

@@ -7,7 +7,7 @@ import type { PushPayloadV2 } from "../src/schemas.js";
 export const evidenceOnlyPush: PushPayloadV2 = {
   schema_version: "2.0",
   client_version: "0.9.0",
-  push_id: "d4e5f6a7-b8c9-0123-defa-234567890123",
+  push_id: "d4e5f6a7-b8c9-8123-9efa-234567890123",
   normalizer_version: "0.2.1",
   canonical: {
     sessions: [],

package/packages/telemetry-contract/fixtures/golden.test.ts

@@ -1,7 +1,6 @@
 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";
 

package/packages/telemetry-contract/fixtures/partial-push-unresolved-parents.ts

@@ -10,7 +10,7 @@ import type { PushPayloadV2 } from "../src/schemas.js";
 export const partialPushUnresolvedParents: PushPayloadV2 = {
   schema_version: "2.0",
   client_version: "0.9.0",
-  push_id: "c3d4e5f6-a7b8-9012-cdef-123456789012",
+  push_id: "c3d4e5f6-a7b8-8012-8def-123456789012",
   normalizer_version: "0.2.1",
   canonical: {
     sessions: [],

package/packages/telemetry-contract/package.json

@@ -13,9 +13,9 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
-    "./schemas": "./src/schemas.ts",
     "./types": "./src/types.ts",
     "./validators": "./src/validators.ts",
+    "./schemas": "./src/schemas.ts",
     "./fixtures": "./fixtures/index.ts"
   },
   "dependencies": {

package/packages/telemetry-contract/src/index.ts

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

package/packages/telemetry-contract/src/schemas.ts

@@ -1,5 +1,13 @@
-import { z } from "zod";
+/**
+ * Zod validation schemas for all canonical telemetry record types
+ * and the PushPayloadV2 envelope.
+ *
+ * This is the single source of truth -- cloud consumers should import
+ * from @selftune/telemetry-contract/schemas instead of maintaining
+ * their own copies.
+ */
 
+import { z } from "zod";
 import {
   CANONICAL_CAPTURE_MODES,
   CANONICAL_COMPLETION_STATUSES,
@@ -11,6 +19,8 @@ import {
   CANONICAL_SOURCE_SESSION_KINDS,
 } from "./types.js";
 
+// ---------- Shared enum schemas ----------
+
 export const canonicalPlatformSchema = z.enum(CANONICAL_PLATFORMS);
 export const captureModeSchema = z.enum(CANONICAL_CAPTURE_MODES);
 export const sourceSessionKindSchema = z.enum(CANONICAL_SOURCE_SESSION_KINDS);
@@ -19,6 +29,8 @@ export const invocationModeSchema = z.enum(CANONICAL_INVOCATION_MODES);
 export const completionStatusSchema = z.enum(CANONICAL_COMPLETION_STATUSES);
 export const recordKindSchema = z.enum(CANONICAL_RECORD_KINDS);
 
+// ---------- Shared structural schemas ----------
+
 export const rawSourceRefSchema = z.object({
   path: z.string().optional(),
   line: z.number().int().nonnegative().optional(),
@@ -42,6 +54,8 @@ export const canonicalSessionRecordBaseSchema = canonicalRecordBaseSchema.extend
   session_id: z.string().min(1),
 });
 
+// ---------- Canonical record schemas ----------
+
 export const CanonicalSessionRecordSchema = canonicalSessionRecordBaseSchema.extend({
   record_kind: z.literal("session"),
   external_session_id: z.string().optional(),
@@ -137,6 +151,8 @@ export const CanonicalEvolutionEvidenceRecordSchema = z.object({
   raw_source_ref: rawSourceRefSchema.optional(),
 });
 
+// ---------- Orchestrate run schemas ----------
+
 export const OrchestrateRunSkillActionSchema = z.object({
   skill: z.string().min(1),
   action: z.enum(["evolve", "watch", "skip"]),
@@ -163,12 +179,12 @@ export const PushOrchestrateRunRecordSchema = z.object({
   skill_actions: z.array(OrchestrateRunSkillActionSchema),
 });
 
+// ---------- Push V2 envelope ----------
+
 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),
+  push_id: z.string().uuid(),
   normalizer_version: z.string().min(1),
   canonical: z.object({
     sessions: z.array(CanonicalSessionRecordSchema).min(0),
@@ -181,6 +197,8 @@ export const PushPayloadV2Schema = z.object({
   }),
 });
 
+// ---------- Inferred types from Zod schemas ----------
+
 export type PushPayloadV2 = z.infer<typeof PushPayloadV2Schema>;
 export type ZodCanonicalSessionRecord = z.infer<typeof CanonicalSessionRecordSchema>;
 export type ZodCanonicalPromptRecord = z.infer<typeof CanonicalPromptRecordSchema>;