npm - selftune - Versions diffs - 0.2.6 → 0.2.9 - Mend

selftune 0.2.6 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (119) hide show

package/README.md +1 -0
package/apps/local-dashboard/dist/assets/index-Bs3Y4ixf.css +1 -0
package/apps/local-dashboard/dist/assets/index-C4UYGWKr.js +15 -0
package/apps/local-dashboard/dist/assets/vendor-react-BQH_6WrG.js +60 -0
package/apps/local-dashboard/dist/assets/{vendor-table-B7VF2Ipl.js → vendor-table-dK1QMLq9.js} +1 -1
package/apps/local-dashboard/dist/assets/{vendor-ui-r2k_Ku_V.js → vendor-ui-CO2mrx6e.js} +60 -65
package/apps/local-dashboard/dist/index.html +5 -5
package/cli/selftune/activation-rules.ts +57 -18
package/cli/selftune/agent-guidance.ts +96 -0
package/cli/selftune/alpha-identity.ts +156 -0
package/cli/selftune/alpha-upload/build-payloads.ts +151 -0
package/cli/selftune/alpha-upload/client.ts +113 -0
package/cli/selftune/alpha-upload/flush.ts +191 -0
package/cli/selftune/alpha-upload/index.ts +194 -0
package/cli/selftune/alpha-upload/queue.ts +252 -0
package/cli/selftune/alpha-upload/stage-canonical.ts +251 -0
package/cli/selftune/alpha-upload-contract.ts +52 -0
package/cli/selftune/auth/device-code.ts +110 -0
package/cli/selftune/auto-update.ts +130 -0
package/cli/selftune/badge/badge.ts +19 -9
package/cli/selftune/canonical-export.ts +16 -3
package/cli/selftune/constants.ts +28 -8
package/cli/selftune/contribute/bundle.ts +33 -5
package/cli/selftune/dashboard-contract.ts +32 -1
package/cli/selftune/dashboard-server.ts +215 -693
package/cli/selftune/dashboard.ts +1 -1
package/cli/selftune/eval/baseline.ts +11 -7
package/cli/selftune/eval/hooks-to-evals.ts +39 -15
package/cli/selftune/eval/synthetic-evals.ts +54 -1
package/cli/selftune/evolution/audit.ts +24 -19
package/cli/selftune/evolution/constitutional.ts +176 -0
package/cli/selftune/evolution/evidence.ts +18 -13
package/cli/selftune/evolution/evolve-body.ts +104 -7
package/cli/selftune/evolution/evolve.ts +195 -22
package/cli/selftune/evolution/propose-body.ts +18 -1
package/cli/selftune/evolution/propose-description.ts +27 -2
package/cli/selftune/evolution/rollback.ts +11 -15
package/cli/selftune/export.ts +84 -0
package/cli/selftune/grading/auto-grade.ts +14 -4
package/cli/selftune/grading/grade-session.ts +17 -6
package/cli/selftune/hooks/auto-activate.ts +5 -0
package/cli/selftune/hooks/evolution-guard.ts +25 -11
package/cli/selftune/hooks/prompt-log.ts +23 -9
package/cli/selftune/hooks/session-stop.ts +78 -15
package/cli/selftune/hooks/skill-eval.ts +189 -10
package/cli/selftune/index.ts +274 -2
package/cli/selftune/ingestors/claude-replay.ts +48 -21
package/cli/selftune/init.ts +260 -49
package/cli/selftune/last.ts +7 -7
package/cli/selftune/localdb/db.ts +90 -10
package/cli/selftune/localdb/direct-write.ts +573 -0
package/cli/selftune/localdb/materialize.ts +296 -42
package/cli/selftune/localdb/queries.ts +482 -32
package/cli/selftune/localdb/schema.ts +153 -1
package/cli/selftune/monitoring/watch.ts +27 -8
package/cli/selftune/normalization.ts +88 -15
package/cli/selftune/observability.ts +257 -5
package/cli/selftune/orchestrate.ts +176 -53
package/cli/selftune/quickstart.ts +34 -10
package/cli/selftune/repair/skill-usage.ts +15 -2
package/cli/selftune/routes/actions.ts +77 -0
package/cli/selftune/routes/badge.ts +66 -0
package/cli/selftune/routes/doctor.ts +12 -0
package/cli/selftune/routes/index.ts +14 -0
package/cli/selftune/routes/orchestrate-runs.ts +13 -0
package/cli/selftune/routes/overview.ts +14 -0
package/cli/selftune/routes/report.ts +293 -0
package/cli/selftune/routes/skill-report.ts +230 -0
package/cli/selftune/status.ts +203 -7
package/cli/selftune/sync.ts +14 -1
package/cli/selftune/types.ts +52 -2
package/cli/selftune/utils/jsonl.ts +58 -1
package/cli/selftune/utils/selftune-meta.ts +38 -0
package/cli/selftune/utils/skill-log.ts +30 -4
package/cli/selftune/utils/transcript.ts +15 -0
package/cli/selftune/workflows/workflows.ts +7 -6
package/package.json +11 -6
package/packages/telemetry-contract/fixtures/complete-push.ts +184 -0
package/packages/telemetry-contract/fixtures/evidence-only-push.ts +58 -0
package/packages/telemetry-contract/fixtures/golden.json +1 -0
package/packages/telemetry-contract/fixtures/index.ts +4 -0
package/packages/telemetry-contract/fixtures/partial-push-no-sessions.ts +40 -0
package/packages/telemetry-contract/fixtures/partial-push-unresolved-parents.ts +79 -0
package/packages/telemetry-contract/package.json +6 -1
package/packages/telemetry-contract/src/schemas.ts +196 -0
package/packages/telemetry-contract/src/types.ts +3 -1
package/packages/telemetry-contract/src/validators.ts +3 -1
package/packages/telemetry-contract/tests/compatibility.test.ts +144 -0
package/packages/ui/package.json +4 -0
package/packages/ui/src/components/ActivityTimeline.tsx +61 -29
package/packages/ui/src/components/section-cards.tsx +31 -14
package/packages/ui/src/types.ts +1 -0
package/skill/SKILL.md +214 -174
package/skill/Workflows/AlphaUpload.md +45 -0
package/skill/Workflows/Baseline.md +18 -12
package/skill/Workflows/Composability.md +3 -3
package/skill/Workflows/Dashboard.md +39 -91
package/skill/Workflows/Doctor.md +93 -66
package/skill/Workflows/Evals.md +49 -40
package/skill/Workflows/Evolve.md +76 -28
package/skill/Workflows/EvolveBody.md +37 -38
package/skill/Workflows/Initialize.md +145 -26
package/skill/Workflows/Orchestrate.md +11 -2
package/skill/Workflows/Sync.md +23 -0
package/skill/Workflows/Watch.md +2 -5
package/skill/agents/diagnosis-analyst.md +163 -0
package/skill/agents/evolution-reviewer.md +149 -0
package/skill/agents/integration-guide.md +154 -0
package/skill/agents/pattern-analyst.md +149 -0
package/skill/assets/multi-skill-settings.json +1 -1
package/skill/assets/single-skill-settings.json +1 -1
package/skill/references/interactive-config.md +39 -0
package/skill/references/invocation-taxonomy.md +34 -0
package/skill/references/logs.md +15 -1
package/skill/references/setup-patterns.md +3 -3
package/skill/settings_snippet.json +1 -1
package/apps/local-dashboard/dist/assets/index-C75H1Q3n.css +0 -1
package/apps/local-dashboard/dist/assets/index-axE4kz3Q.js +0 -15
package/apps/local-dashboard/dist/assets/vendor-react-U7zYD9Rg.js +0 -60

package/apps/local-dashboard/dist/index.html CHANGED Viewed

@@ -5,11 +5,11 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
   <title>selftune — Dashboard</title>
   <link rel="icon" type="image/png" href="/favicon.png" />
-  <script type="module" crossorigin src="/assets/index-axE4kz3Q.js"></script>
-  <link rel="modulepreload" crossorigin href="/assets/vendor-react-U7zYD9Rg.js">
-  <link rel="modulepreload" crossorigin href="/assets/vendor-ui-r2k_Ku_V.js">
-  <link rel="modulepreload" crossorigin href="/assets/vendor-table-B7VF2Ipl.js">
-  <link rel="stylesheet" crossorigin href="/assets/index-C75H1Q3n.css">
+  <script type="module" crossorigin src="/assets/index-C4UYGWKr.js"></script>
+  <link rel="modulepreload" crossorigin href="/assets/vendor-react-BQH_6WrG.js">
+  <link rel="modulepreload" crossorigin href="/assets/vendor-ui-CO2mrx6e.js">
+  <link rel="modulepreload" crossorigin href="/assets/vendor-table-dK1QMLq9.js">
+  <link rel="stylesheet" crossorigin href="/assets/index-Bs3Y4ixf.css">
 </head>
 <body>
   <div id="root"></div>

package/cli/selftune/activation-rules.ts CHANGED Viewed

@@ -2,37 +2,67 @@
  * Default activation rules for the auto-activate hook.
  *
  * Each rule evaluates session context and returns a suggestion string
- * (or null if the rule doesn't fire). Rules must be pure functions
- * that read from the filesystem — no network calls, no imports from
- * evolution/monitoring/grading layers.
+ * (or null if the rule doesn't fire). Rules must be pure functions —
+ * no network calls, no imports from evolution/monitoring/grading layers.
+ *
+ * SQLite is the default read path for log data. JSONL fallback is used
+ * only when context paths differ from the well-known constants
+ * (test/custom-path override).
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { EVOLUTION_AUDIT_LOG, QUERY_LOG } from "./constants.js";
+import { getDb } from "./localdb/db.js";
+import { queryEvolutionAudit, queryQueryLog, querySkillUsageRecords } from "./localdb/queries.js";
 import type { ActivationContext, ActivationRule } from "./types.js";
 import { readJsonl } from "./utils/jsonl.js";
 // ---------------------------------------------------------------------------
-// Rule: post-session diagnostic
+// Rule: post-session diagnostic (SQLite-first; JSONL for test/custom paths)
 // ---------------------------------------------------------------------------
 const postSessionDiagnostic: ActivationRule = {
   id: "post-session-diagnostic",
   description: "Suggest `selftune last` when session has >2 unmatched queries",
   evaluate(ctx: ActivationContext): string | null {
-    // Count queries for this session
-    const queries = readJsonl<{ session_id: string; query: string }>(ctx.query_log_path);
+    // Count queries for this session — SQLite is the default path
+    let queries: Array<{ session_id: string; query: string }>;
+    if (ctx.query_log_path === QUERY_LOG) {
+      try {
+        const db = getDb();
+        queries = queryQueryLog(db) as Array<{ session_id: string; query: string }>;
+      } catch {
+        return null;
+      }
+    } else {
+      // test/custom-path fallback
+      queries = readJsonl<{ session_id: string; query: string }>(ctx.query_log_path);
+    }
     const sessionQueries = queries.filter((q) => q.session_id === ctx.session_id);
     if (sessionQueries.length === 0) return null;
-    // Count skill usages for this session (skill log is in the same dir as query log)
-    const skillLogPath = join(dirname(ctx.query_log_path), "skill_usage_log.jsonl");
-    const skillUsages = existsSync(skillLogPath)
-      ? readJsonl<{ session_id: string }>(skillLogPath).filter(
+    // Count skill usages for this session — SQLite is the default path
+    let skillUsages: Array<{ session_id: string }>;
+    if (ctx.query_log_path === QUERY_LOG) {
+      try {
+        const db = getDb();
+        skillUsages = (querySkillUsageRecords(db) as Array<{ session_id: string }>).filter(
           (s) => s.session_id === ctx.session_id,
-        )
-      : [];
+        );
+      } catch {
+        return null;
+      }
+    } else {
+      // test/custom-path fallback
+      const skillLogPath = join(dirname(ctx.query_log_path), "skill_usage_log.jsonl");
+      skillUsages = existsSync(skillLogPath)
+        ? readJsonl<{ session_id: string }>(skillLogPath).filter(
+            (s) => s.session_id === ctx.session_id,
+          )
+        : [];
+    }
     const unmatchedCount = sessionQueries.length - skillUsages.length;
@@ -83,7 +113,7 @@ const gradingThresholdBreach: ActivationRule = {
 };
 // ---------------------------------------------------------------------------
-// Rule: stale evolution
+// Rule: stale evolution (SQLite-first; JSONL for test/custom paths)
 // ---------------------------------------------------------------------------
 const staleEvolution: ActivationRule = {
@@ -93,10 +123,19 @@ const staleEvolution: ActivationRule = {
   evaluate(ctx: ActivationContext): string | null {
     const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
-    // Check last evolution timestamp
-    const auditEntries = readJsonl<{ timestamp: string; action: string }>(
-      ctx.evolution_audit_log_path,
-    );
+    // Check last evolution timestamp — SQLite is the default path
+    let auditEntries: Array<{ timestamp: string; action: string }>;
+    if (ctx.evolution_audit_log_path === EVOLUTION_AUDIT_LOG) {
+      try {
+        const db = getDb();
+        auditEntries = queryEvolutionAudit(db) as Array<{ timestamp: string; action: string }>;
+      } catch {
+        return null;
+      }
+    } else {
+      // test/custom-path fallback
+      auditEntries = readJsonl<{ timestamp: string; action: string }>(ctx.evolution_audit_log_path);
+    }
     if (auditEntries.length === 0) {
       // No evolution has ever run — check for false negatives
@@ -105,7 +144,7 @@ const staleEvolution: ActivationRule = {
         : null;
     }
-    const lastEntry = auditEntries[auditEntries.length - 1];
+    const lastEntry = auditEntries[0]; // queryEvolutionAudit returns DESC order
     const lastTimestamp = new Date(lastEntry.timestamp).getTime();
     const ageMs = Date.now() - lastTimestamp;

package/cli/selftune/agent-guidance.ts ADDED Viewed

@@ -0,0 +1,96 @@
+import { getAlphaLinkState } from "./alpha-identity.js";
+import type { AgentCommandGuidance, AlphaIdentity, AlphaLinkState } from "./types.js";
+function sanitizeAlphaEmail(email?: string): string | null {
+  const trimmed = email?.trim();
+  if (!trimmed) return null;
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(trimmed)) return null;
+  return trimmed;
+}
+function buildAlphaInitCommand(options?: { email?: string; force?: boolean }): string {
+  const parts = ["selftune", "init", "--alpha"];
+  const email = sanitizeAlphaEmail(options?.email);
+  if (email) {
+    parts.push("--alpha-email", email);
+  }
+  if (options?.force) {
+    parts.push("--force");
+  }
+  return parts.join(" ");
+}
+function buildGuidance(
+  code: string,
+  message: string,
+  nextCommand: string,
+  blocking: boolean,
+  suggestedCommands: string[],
+): AgentCommandGuidance {
+  return {
+    code,
+    message,
+    next_command: nextCommand,
+    suggested_commands: suggestedCommands,
+    blocking,
+  };
+}
+export function getAlphaGuidanceForState(
+  state: AlphaLinkState,
+  options?: { email?: string },
+): AgentCommandGuidance {
+  switch (state) {
+    case "not_linked":
+      return buildGuidance(
+        "alpha_cloud_link_required",
+        "Alpha upload is not linked. Run the init command with --alpha to authenticate via browser.",
+        buildAlphaInitCommand({ email: options?.email }),
+        true,
+        ["selftune status", "selftune doctor"],
+      );
+    case "linked_not_enrolled":
+      return buildGuidance(
+        "alpha_enrollment_incomplete",
+        "Cloud account is linked but alpha enrollment is incomplete. Re-run init with --alpha to complete enrollment via browser.",
+        buildAlphaInitCommand({ email: options?.email, force: true }),
+        true,
+        ["selftune status", "selftune doctor"],
+      );
+    case "enrolled_no_credential":
+      return buildGuidance(
+        "alpha_credential_required",
+        "Alpha enrollment exists, but the local upload credential is missing or invalid. Re-run init with --alpha to re-authenticate via browser.",
+        buildAlphaInitCommand({ email: options?.email, force: true }),
+        true,
+        ["selftune status", "selftune doctor"],
+      );
+    case "ready":
+      return buildGuidance(
+        "alpha_upload_ready",
+        "Alpha upload is configured and ready.",
+        "selftune alpha upload",
+        false,
+        ["selftune status", "selftune doctor"],
+      );
+  }
+}
+export function getAlphaGuidance(identity: AlphaIdentity | null): AgentCommandGuidance {
+  if (!identity) {
+    return getAlphaGuidanceForState("not_linked");
+  }
+  return getAlphaGuidanceForState(getAlphaLinkState(identity), { email: identity.email });
+}
+export function formatGuidanceLines(
+  guidance: AgentCommandGuidance,
+  options?: { indent?: string },
+): string[] {
+  const indent = options?.indent ?? "  ";
+  const lines = [`${indent}Next command:       ${guidance.next_command}`];
+  if (guidance.suggested_commands.length > 0) {
+    lines.push(`${indent}Suggested commands: ${guidance.suggested_commands.join(", ")}`);
+  }
+  return lines;
+}

package/cli/selftune/alpha-identity.ts ADDED Viewed

@@ -0,0 +1,156 @@
+/**
+ * Alpha program identity management — cached cloud identity model.
+ *
+ * Local config is a cache of cloud-linked identity, not the source of truth.
+ * The cloud_user_id field is the primary "linked" indicator. Legacy local-only
+ * identities (user_id without cloud_user_id) are detected by migrateLocalIdentity().
+ *
+ * Handles stable user identity generation, config persistence,
+ * and consent notice for the selftune alpha program.
+ */
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { AlphaIdentity, AlphaLinkState, SelftuneConfig } from "./types.js";
+// ---------------------------------------------------------------------------
+// User ID generation
+// ---------------------------------------------------------------------------
+/** Generate a stable UUID for alpha user identity. */
+export function generateUserId(): string {
+  return randomUUID();
+}
+// ---------------------------------------------------------------------------
+// Config read/write helpers
+// ---------------------------------------------------------------------------
+/**
+ * Read the alpha identity block from the selftune config file.
+ * Returns null if config does not exist or has no alpha block.
+ */
+export function readAlphaIdentity(configPath: string): AlphaIdentity | null {
+  if (!existsSync(configPath)) return null;
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(raw) as SelftuneConfig;
+    return config.alpha ?? null;
+  } catch {
+    return null;
+  }
+}
+/**
+ * Write the alpha identity block into the selftune config file.
+ * Reads existing config, merges the alpha block, and writes back.
+ * Creates parent directories if needed.
+ */
+export function writeAlphaIdentity(configPath: string, identity: AlphaIdentity): void {
+  let config: Record<string, unknown> = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf-8"));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Unable to update alpha identity: ${configPath} is not valid JSON (${message})`,
+      );
+    }
+  }
+  config.alpha = identity;
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Link state helper — cloud-first model
+// ---------------------------------------------------------------------------
+/** Check if an API key has the expected st_live_ or st_test_ prefix. */
+export function isValidApiKeyFormat(key: string): boolean {
+  return key.startsWith("st_live_") || key.startsWith("st_test_");
+}
+/**
+ * Derive the cloud link readiness state from an AlphaIdentity.
+ *
+ * State machine:
+ *   null                              -> "not_linked"
+ *   not enrolled, no cloud_user_id    -> "not_linked"
+ *   not enrolled, has cloud_user_id   -> "linked_not_enrolled"
+ *   enrolled, no valid api_key        -> "enrolled_no_credential"
+ *   enrolled, valid api_key           -> "ready"
+ *
+ * cloud_user_id enriches the identity (confirms cloud link) but is not a gate.
+ * The device-code flow sets both api_key and cloud_user_id simultaneously.
+ */
+export function getAlphaLinkState(identity: AlphaIdentity | null): AlphaLinkState {
+  if (!identity) return "not_linked";
+  if (!identity.enrolled) return identity.cloud_user_id ? "linked_not_enrolled" : "not_linked";
+  if (!identity.api_key || !isValidApiKeyFormat(identity.api_key)) return "enrolled_no_credential";
+  // Enrolled + valid key = ready (cloud_user_id is bonus, not gate)
+  return "ready";
+}
+// ---------------------------------------------------------------------------
+// Migration helper
+// ---------------------------------------------------------------------------
+/**
+ * Detect legacy local-only alpha blocks and mark them as needing cloud link.
+ * A legacy identity has email + user_id but no cloud_user_id.
+ */
+export function migrateLocalIdentity(identity: AlphaIdentity): {
+  needsCloudLink: boolean;
+  identity: AlphaIdentity;
+} {
+  if (identity.cloud_user_id) {
+    return { needsCloudLink: false, identity };
+  }
+  // Legacy: has local user_id but no cloud link
+  return { needsCloudLink: true, identity };
+}
+// ---------------------------------------------------------------------------
+// Consent notice
+// ---------------------------------------------------------------------------
+export const ALPHA_CONSENT_NOTICE = `
+========================================
+  selftune Alpha Program
+========================================
+You are enrolling in the selftune alpha program.
+WHAT IS COLLECTED:
+  - Skill invocations and trigger metadata
+  - Session metadata (timestamps, tool counts, error counts)
+  - Evolution outcomes (proposals, pass rates, deployments)
+  - Raw user prompt/query text submitted during captured sessions
+WHAT IS NOT COLLECTED:
+  - File contents or source code
+  - Full transcript bodies beyond the captured prompt/query text
+  - Structured repository names or file paths as separate fields
+IMPORTANT:
+  Raw prompt/query text is uploaded unchanged for the friendly alpha cohort.
+  If your prompt includes repository names, file paths, or secrets, that text
+  may be included in the alpha data you choose to share.
+Your alpha identity (email, display name, and any upload API key)
+is stored locally in ~/.selftune/config.json and used for alpha coordination
+and authenticated uploads.
+TO UNENROLL:
+  selftune init --no-alpha
+========================================
+`;

package/cli/selftune/alpha-upload/build-payloads.ts ADDED Viewed

@@ -0,0 +1,151 @@
+/**
+ * V2 canonical push payload builder (staging-based).
+ *
+ * Reads from the canonical_upload_staging table using a single monotonic
+ * cursor (local_seq). Each staged row contains the full canonical record
+ * JSON, so no fields are dropped or hardcoded during payload construction.
+ *
+ * Evolution evidence rows (record_kind = "evolution_evidence") are separated
+ * and placed in the canonical.evolution_evidence array.
+ */
+import type { Database } from "bun:sqlite";
+import type { CanonicalRecord } from "@selftune/telemetry-contract";
+import { buildPushPayloadV2 } from "../canonical-export.js";
+import type { EvolutionEvidenceEntry } from "../types.js";
+// -- Types --------------------------------------------------------------------
+export interface BuildV2Result {
+  payload: Record<string, unknown>;
+  lastSeq: number;
+}
+// -- Constants ----------------------------------------------------------------
+const DEFAULT_LIMIT = 500;
+// -- Helpers ------------------------------------------------------------------
+/** Parse a JSON string, returning null on failure. */
+function safeParseJson<T>(json: string | null): T | null {
+  if (!json) return null;
+  try {
+    return JSON.parse(json) as T;
+  } catch {
+    return null;
+  }
+}
+// -- Main builder -------------------------------------------------------------
+/**
+ * Build a V2 canonical push payload from the staging table.
+ *
+ * Reads records from canonical_upload_staging WHERE local_seq > afterSeq,
+ * groups them by record_kind, and assembles a V2 push payload.
+ *
+ * Returns null when no new records exist after afterSeq.
+ */
+export function buildV2PushPayload(
+  db: Database,
+  afterSeq?: number,
+  limit: number = DEFAULT_LIMIT,
+): BuildV2Result | null {
+  const whereClause = afterSeq !== undefined ? "WHERE local_seq > ?" : "";
+  const params = afterSeq !== undefined ? [afterSeq, limit] : [limit];
+  const sql = `
+    SELECT local_seq, record_kind, record_json
+    FROM canonical_upload_staging
+    ${whereClause}
+    ORDER BY local_seq ASC
+    LIMIT ?
+  `;
+  const rows = db.query(sql).all(...params) as Array<{
+    local_seq: number;
+    record_kind: string;
+    record_json: string;
+  }>;
+  if (rows.length === 0) return null;
+  const canonicalRecords: CanonicalRecord[] = [];
+  const evidenceEntries: EvolutionEvidenceEntry[] = [];
+  const orchestrateRuns: Record<string, unknown>[] = [];
+  let lastParsedSeq: number | null = null;
+  let hitMalformedRow = false;
+  for (const row of rows) {
+    const parsed = safeParseJson<Record<string, unknown>>(row.record_json);
+    if (!parsed) {
+      hitMalformedRow = true;
+      break;
+    }
+    if (row.record_kind === "evolution_evidence") {
+      const timestamp =
+        typeof parsed.timestamp === "string" && parsed.timestamp.trim().length > 0
+          ? parsed.timestamp
+          : null;
+      const proposalId =
+        typeof parsed.proposal_id === "string" && parsed.proposal_id.trim().length > 0
+          ? parsed.proposal_id
+          : null;
+      if (!timestamp || !proposalId) {
+        hitMalformedRow = true;
+        break;
+      }
+      // Evolution evidence has its own shape
+      evidenceEntries.push({
+        timestamp,
+        proposal_id: proposalId,
+        skill_name: parsed.skill_name as string,
+        skill_path: (parsed.skill_path as string) ?? "",
+        target: (parsed.target as EvolutionEvidenceEntry["target"]) ?? "description",
+        stage: (parsed.stage as EvolutionEvidenceEntry["stage"]) ?? "created",
+        rationale: parsed.rationale as string | undefined,
+        confidence: parsed.confidence as number | undefined,
+        details: parsed.details as string | undefined,
+        original_text: parsed.original_text as string | undefined,
+        proposed_text: parsed.proposed_text as string | undefined,
+        eval_set: parsed.eval_set_json as EvolutionEvidenceEntry["eval_set"],
+        validation: parsed.validation_json as EvolutionEvidenceEntry["validation"],
+        evidence_id: parsed.evidence_id as string | undefined,
+      });
+    } else if (row.record_kind === "orchestrate_run") {
+      // Orchestrate run records -- pass through as-is
+      orchestrateRuns.push(parsed);
+    } else {
+      // Canonical telemetry records -- pass through as-is
+      canonicalRecords.push(parsed as unknown as CanonicalRecord);
+    }
+    lastParsedSeq = row.local_seq;
+  }
+  // If nothing parsed successfully, return null
+  if (
+    canonicalRecords.length === 0 &&
+    evidenceEntries.length === 0 &&
+    orchestrateRuns.length === 0
+  ) {
+    return null;
+  }
+  const payload = buildPushPayloadV2(canonicalRecords, evidenceEntries, orchestrateRuns);
+  if (lastParsedSeq === null) {
+    return null;
+  }
+  const lastSeq = lastParsedSeq;
+  if (hitMalformedRow && (process.env.DEBUG || process.env.NODE_ENV === "development")) {
+    console.error(
+      "[alpha-upload/build-payloads] encountered malformed staged row; cursor held at last valid seq",
+    );
+  }
+  return { payload, lastSeq };
+}

package/cli/selftune/alpha-upload/client.ts ADDED Viewed

@@ -0,0 +1,113 @@
+/**
+ * Alpha upload HTTP client.
+ *
+ * POSTs V2 canonical push payloads to the cloud API's POST /api/v1/push.
+ * Uses native fetch (Bun built-in). Never throws -- returns a
+ * PushUploadResult indicating success or failure.
+ */
+import type { PushUploadResult } from "../alpha-upload-contract.js";
+import { getSelftuneVersion } from "../utils/selftune-meta.js";
+function isPushUploadResult(value: unknown): value is PushUploadResult {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.success === "boolean" &&
+    Array.isArray(record.errors) &&
+    record.errors.every((entry) => typeof entry === "string") &&
+    (record.push_id === undefined || typeof record.push_id === "string") &&
+    (record._status === undefined || typeof record._status === "number")
+  );
+}
+function isAcceptedPushResponse(value: unknown): value is { status: "accepted"; push_id: string } {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return record.status === "accepted" && typeof record.push_id === "string";
+}
+/**
+ * Upload a single V2 push payload to the given endpoint.
+ *
+ * Returns a typed result. Never throws -- network errors and HTTP
+ * failures are captured in the result.
+ */
+export async function uploadPushPayload(
+  payload: Record<string, unknown>,
+  endpoint: string,
+  apiKey?: string,
+): Promise<PushUploadResult> {
+  try {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      "User-Agent": `selftune/${getSelftuneVersion()}`,
+    };
+    if (apiKey) {
+      headers.Authorization = `Bearer ${apiKey}`;
+    }
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (response.ok) {
+      // Read body as text first — Bun consumes the stream on .json(),
+      // so a failed .json() followed by .text() would throw.
+      const body = await response.text();
+      if (body.length === 0) {
+        return {
+          success: true,
+          push_id: (payload as { push_id?: string }).push_id,
+          errors: [],
+          _status: response.status,
+        };
+      }
+      try {
+        const parsed: unknown = JSON.parse(body);
+        if (isPushUploadResult(parsed)) {
+          return { ...parsed, _status: parsed._status ?? response.status };
+        }
+        if (isAcceptedPushResponse(parsed)) {
+          return {
+            success: true,
+            push_id: parsed.push_id,
+            errors: [],
+            _status: response.status,
+          };
+        }
+        return {
+          success: false,
+          errors: ["Invalid JSON response shape for PushUploadResult"],
+          _status: response.status,
+        };
+      } catch {
+        return {
+          success: false,
+          errors: [`Unexpected non-JSON response body: ${body.slice(0, 200)}`],
+          _status: response.status,
+        };
+      }
+    }
+    // Non-2xx response -- read error text for diagnostics
+    const errorText = await response.text().catch(() => "unknown error");
+    return {
+      success: false,
+      errors: [`HTTP ${response.status}: ${errorText.slice(0, 200)}`],
+      _status: response.status,
+    };
+  } catch (err) {
+    // Network-level failure (DNS, timeout, connection refused, etc.)
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      success: false,
+      errors: [message],
+      _status: 0,
+    };
+  }
+}