selftune 0.2.10 → 0.2.13

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

@@ -0,0 +1,165 @@
+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 type CanonicalPlatform = (typeof CANONICAL_PLATFORMS)[number];
+
+export const CANONICAL_CAPTURE_MODES = [
+  "hook",
+  "replay",
+  "wrapper",
+  "batch_ingest",
+  "repair",
+] as const;
+export type CanonicalCaptureMode = (typeof CANONICAL_CAPTURE_MODES)[number];
+
+export const CANONICAL_SOURCE_SESSION_KINDS = [
+  "interactive",
+  "replayed",
+  "synthetic",
+  "repaired",
+] as const;
+export type CanonicalSourceSessionKind = (typeof CANONICAL_SOURCE_SESSION_KINDS)[number];
+
+export const CANONICAL_PROMPT_KINDS = [
+  "user",
+  "continuation",
+  "task_notification",
+  "teammate_message",
+  "system_instruction",
+  "tool_output",
+  "meta",
+  "unknown",
+] as const;
+export type CanonicalPromptKind = (typeof CANONICAL_PROMPT_KINDS)[number];
+
+export const CANONICAL_INVOCATION_MODES = ["explicit", "implicit", "inferred", "repaired"] as const;
+export type CanonicalInvocationMode = (typeof CANONICAL_INVOCATION_MODES)[number];
+
+export const CANONICAL_COMPLETION_STATUSES = [
+  "completed",
+  "failed",
+  "interrupted",
+  "cancelled",
+  "unknown",
+] as const;
+export type CanonicalCompletionStatus = (typeof CANONICAL_COMPLETION_STATUSES)[number];
+
+export const CANONICAL_RECORD_KINDS = [
+  "session",
+  "prompt",
+  "skill_invocation",
+  "execution_fact",
+  "normalization_run",
+] as const;
+export type CanonicalRecordKind = (typeof CANONICAL_RECORD_KINDS)[number];
+
+export interface CanonicalRawSourceRef {
+  path?: string;
+  line?: number;
+  event_type?: string;
+  raw_id?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CanonicalRecordBase {
+  record_kind: CanonicalRecordKind;
+  schema_version: CanonicalSchemaVersion;
+  normalizer_version: string;
+  normalized_at: string;
+  platform: CanonicalPlatform;
+  capture_mode: CanonicalCaptureMode;
+  raw_source_ref: CanonicalRawSourceRef;
+}
+
+export interface CanonicalSessionRecordBase extends CanonicalRecordBase {
+  source_session_kind: CanonicalSourceSessionKind;
+  session_id: string;
+}
+
+export interface CanonicalSessionRecord extends CanonicalSessionRecordBase {
+  record_kind: "session";
+  started_at?: string;
+  ended_at?: string;
+  external_session_id?: string;
+  parent_session_id?: string;
+  agent_id?: string;
+  agent_type?: string;
+  agent_cli?: string;
+  session_key?: string;
+  channel?: string;
+  workspace_path?: string;
+  repo_root?: string;
+  repo_remote?: string;
+  branch?: string;
+  commit_sha?: string;
+  permission_mode?: string;
+  approval_policy?: string;
+  sandbox_policy?: string;
+  provider?: string;
+  model?: string;
+  completion_status?: CanonicalCompletionStatus;
+  end_reason?: string;
+}
+
+export interface CanonicalPromptRecord extends CanonicalSessionRecordBase {
+  record_kind: "prompt";
+  prompt_id: string;
+  occurred_at: string;
+  prompt_text: string;
+  prompt_hash?: string;
+  prompt_kind: CanonicalPromptKind;
+  is_actionable: boolean;
+  prompt_index?: number;
+  parent_prompt_id?: string;
+  source_message_id?: string;
+}
+
+export interface CanonicalSkillInvocationRecord extends CanonicalSessionRecordBase {
+  record_kind: "skill_invocation";
+  skill_invocation_id: string;
+  occurred_at: string;
+  matched_prompt_id?: string;
+  skill_name: string;
+  skill_path?: string;
+  skill_version_hash?: string;
+  invocation_mode: CanonicalInvocationMode;
+  triggered: boolean;
+  confidence: number;
+  tool_name?: string;
+  tool_call_id?: string;
+  agent_type?: string;
+}
+
+export interface CanonicalExecutionFactRecord extends CanonicalSessionRecordBase {
+  record_kind: "execution_fact";
+  execution_fact_id: string;
+  occurred_at: string;
+  prompt_id?: string;
+  tool_calls_json: Record<string, number>;
+  total_tool_calls: number;
+  bash_commands_redacted?: string[];
+  assistant_turns: number;
+  errors_encountered: number;
+  input_tokens?: number;
+  output_tokens?: number;
+  duration_ms?: number;
+  completion_status?: CanonicalCompletionStatus;
+  end_reason?: string;
+}
+
+export interface CanonicalNormalizationRunRecord extends CanonicalRecordBase {
+  record_kind: "normalization_run";
+  run_id: string;
+  run_at: string;
+  raw_records_seen: number;
+  canonical_records_written: number;
+  repair_applied: boolean;
+}
+
+export type CanonicalRecord =
+  | CanonicalSessionRecord
+  | CanonicalPromptRecord
+  | CanonicalSkillInvocationRecord
+  | CanonicalExecutionFactRecord
+  | CanonicalNormalizationRunRecord;

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

@@ -0,0 +1,111 @@
+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,
+  type CanonicalRawSourceRef,
+  type CanonicalRecord,
+} from "./types.js";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function hasString(value: Record<string, unknown>, key: string): boolean {
+  return typeof value[key] === "string" && value[key].length > 0;
+}
+
+function includesValue<T extends readonly string[]>(values: T, value: unknown): value is T[number] {
+  return typeof value === "string" && values.includes(value);
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isNumberRecord(value: unknown): value is Record<string, number> {
+  return isObject(value) && Object.values(value).every(isFiniteNumber);
+}
+
+function hasSessionScope(value: Record<string, unknown>): boolean {
+  return (
+    includesValue(CANONICAL_SOURCE_SESSION_KINDS, value.source_session_kind) &&
+    hasString(value, "session_id")
+  );
+}
+
+export function isCanonicalRawSourceRef(value: unknown): value is CanonicalRawSourceRef {
+  return isObject(value);
+}
+
+export function isCanonicalRecord(value: unknown): value is CanonicalRecord {
+  if (!isObject(value)) return false;
+  if (value.schema_version !== CANONICAL_SCHEMA_VERSION) return false;
+  if (!includesValue(CANONICAL_RECORD_KINDS, value.record_kind)) return false;
+  if (!includesValue(CANONICAL_PLATFORMS, value.platform)) return false;
+  if (!includesValue(CANONICAL_CAPTURE_MODES, value.capture_mode)) return false;
+  if (!hasString(value, "normalizer_version")) return false;
+  if (!hasString(value, "normalized_at")) return false;
+  if (!isCanonicalRawSourceRef(value.raw_source_ref)) return false;
+
+  switch (value.record_kind) {
+    case "session":
+      return (
+        hasSessionScope(value) &&
+        (value.completion_status === undefined ||
+          includesValue(CANONICAL_COMPLETION_STATUSES, value.completion_status))
+      );
+    case "prompt":
+      return (
+        hasSessionScope(value) &&
+        hasString(value, "prompt_id") &&
+        hasString(value, "occurred_at") &&
+        hasString(value, "prompt_text") &&
+        includesValue(CANONICAL_PROMPT_KINDS, value.prompt_kind) &&
+        typeof value.is_actionable === "boolean"
+      );
+    case "skill_invocation":
+      return (
+        hasSessionScope(value) &&
+        hasString(value, "skill_invocation_id") &&
+        hasString(value, "occurred_at") &&
+        (value.matched_prompt_id === undefined || hasString(value, "matched_prompt_id")) &&
+        hasString(value, "skill_name") &&
+        includesValue(CANONICAL_INVOCATION_MODES, value.invocation_mode) &&
+        typeof value.triggered === "boolean" &&
+        isFiniteNumber(value.confidence)
+      );
+    case "execution_fact":
+      return (
+        hasSessionScope(value) &&
+        hasString(value, "execution_fact_id") &&
+        hasString(value, "occurred_at") &&
+        isNumberRecord(value.tool_calls_json) &&
+        isFiniteNumber(value.total_tool_calls) &&
+        (value.bash_commands_redacted === undefined ||
+          isStringArray(value.bash_commands_redacted)) &&
+        isFiniteNumber(value.assistant_turns) &&
+        isFiniteNumber(value.errors_encountered) &&
+        (value.completion_status === undefined ||
+          includesValue(CANONICAL_COMPLETION_STATUSES, value.completion_status))
+      );
+    case "normalization_run":
+      return (
+        hasString(value, "run_id") &&
+        hasString(value, "run_at") &&
+        isFiniteNumber(value.raw_records_seen) &&
+        isFiniteNumber(value.canonical_records_written) &&
+        typeof value.repair_applied === "boolean"
+      );
+    default:
+      return false;
+  }
+}

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

@@ -0,0 +1,145 @@
+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";
+import { partialPushUnresolvedParents } from "../fixtures/partial-push-unresolved-parents.js";
+import { PushPayloadV2Schema } from "../src/schemas.js";
+
+describe("PushPayloadV2Schema compatibility", () => {
+  // ---- Fixture validation ----
+
+  test("complete-push fixture passes validation", () => {
+    const result = PushPayloadV2Schema.safeParse(completePush);
+    if (!result.success) {
+      throw new Error(`Validation failed: ${JSON.stringify(result.error.issues, null, 2)}`);
+    }
+    expect(result.success).toBe(true);
+  });
+
+  test("partial-push-no-sessions fixture passes validation", () => {
+    const result = PushPayloadV2Schema.safeParse(partialPushNoSessions);
+    if (!result.success) {
+      throw new Error(`Validation failed: ${JSON.stringify(result.error.issues, null, 2)}`);
+    }
+    expect(result.success).toBe(true);
+  });
+
+  test("partial-push-unresolved-parents fixture passes validation", () => {
+    const result = PushPayloadV2Schema.safeParse(partialPushUnresolvedParents);
+    if (!result.success) {
+      throw new Error(`Validation failed: ${JSON.stringify(result.error.issues, null, 2)}`);
+    }
+    expect(result.success).toBe(true);
+  });
+
+  test("evidence-only-push fixture passes validation", () => {
+    const result = PushPayloadV2Schema.safeParse(evidenceOnlyPush);
+    if (!result.success) {
+      throw new Error(`Validation failed: ${JSON.stringify(result.error.issues, null, 2)}`);
+    }
+    expect(result.success).toBe(true);
+  });
+
+  // ---- execution_fact_id is required ----
+
+  test("execution_fact_id is required on execution facts", () => {
+    const badPayload = structuredClone(completePush);
+    delete (badPayload.canonical.execution_facts[0] as Record<string, unknown>).execution_fact_id;
+    const result = PushPayloadV2Schema.safeParse(badPayload);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const paths = result.error.issues.map((i) => i.path.join("."));
+      expect(paths).toContain("canonical.execution_facts.0.execution_fact_id");
+    }
+  });
+
+  test("execution_fact_id rejects empty string", () => {
+    const badPayload = structuredClone(completePush);
+    (badPayload.canonical.execution_facts[0] as Record<string, unknown>).execution_fact_id = "";
+    const result = PushPayloadV2Schema.safeParse(badPayload);
+    expect(result.success).toBe(false);
+    if (!result.success) {
+      const paths = result.error.issues.map((i) => i.path.join("."));
+      expect(paths).toContain("canonical.execution_facts.0.execution_fact_id");
+    }
+  });
+
+  // ---- bash_commands_redacted is optional ----
+
+  test("bash_commands_redacted is optional (omitting it passes)", () => {
+    // The unresolved-parents fixture already omits bash_commands_redacted
+    const ef = partialPushUnresolvedParents.canonical.execution_facts[0];
+    expect(ef.bash_commands_redacted).toBeUndefined();
+
+    const result = PushPayloadV2Schema.safeParse(partialPushUnresolvedParents);
+    expect(result.success).toBe(true);
+  });
+
+  test("bash_commands_redacted accepts an array when present", () => {
+    const ef = completePush.canonical.execution_facts[0];
+    expect(Array.isArray(ef.bash_commands_redacted)).toBe(true);
+
+    const result = PushPayloadV2Schema.safeParse(completePush);
+    expect(result.success).toBe(true);
+  });
+
+  // ---- Zero-session pushes ----
+
+  test("zero-session pushes pass validation", () => {
+    expect(partialPushNoSessions.canonical.sessions).toHaveLength(0);
+    const result = PushPayloadV2Schema.safeParse(partialPushNoSessions);
+    expect(result.success).toBe(true);
+  });
+
+  test("evidence-only push with all empty arrays passes", () => {
+    expect(evidenceOnlyPush.canonical.sessions).toHaveLength(0);
+    expect(evidenceOnlyPush.canonical.prompts).toHaveLength(0);
+    expect(evidenceOnlyPush.canonical.skill_invocations).toHaveLength(0);
+    expect(evidenceOnlyPush.canonical.execution_facts).toHaveLength(0);
+    expect(evidenceOnlyPush.canonical.normalization_runs).toHaveLength(0);
+    const result = PushPayloadV2Schema.safeParse(evidenceOnlyPush);
+    expect(result.success).toBe(true);
+  });
+
+  // ---- Unresolved parent references ----
+
+  test("unresolved parent references pass (invocation references session_id not in sessions)", () => {
+    const sessionIds = new Set(
+      partialPushUnresolvedParents.canonical.sessions.map((s) => s.session_id),
+    );
+    const invSessionIds = partialPushUnresolvedParents.canonical.skill_invocations.map(
+      (i) => i.session_id,
+    );
+
+    // Precondition: arrays must be non-empty for the test to be meaningful
+    expect(invSessionIds.length).toBeGreaterThan(0);
+
+    // Confirm the invocation references a session not in the sessions array
+    for (const sid of invSessionIds) {
+      expect(sessionIds.has(sid)).toBe(false);
+    }
+
+    const result = PushPayloadV2Schema.safeParse(partialPushUnresolvedParents);
+    expect(result.success).toBe(true);
+  });
+
+  test("prompts with unresolved session_id pass validation", () => {
+    const sessionIds = new Set(
+      partialPushUnresolvedParents.canonical.sessions.map((s) => s.session_id),
+    );
+    const promptSessionIds = partialPushUnresolvedParents.canonical.prompts.map(
+      (p) => p.session_id,
+    );
+
+    // Precondition: arrays must be non-empty for the test to be meaningful
+    expect(promptSessionIds.length).toBeGreaterThan(0);
+
+    for (const sid of promptSessionIds) {
+      expect(sessionIds.has(sid)).toBe(false);
+    }
+
+    const result = PushPayloadV2Schema.safeParse(partialPushUnresolvedParents);
+    expect(result.success).toBe(true);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.10",
+  "version": "0.2.13",
   "description": "Self-improving skills CLI for AI agents",
   "keywords": [
     "agent",
@@ -65,9 +65,9 @@
     "test:fast": "bun test $(find tests -name '*.test.ts' ! -name 'evolve.test.ts' ! -name 'integration.test.ts' ! -name 'dashboard-server.test.ts' ! -path '*/blog-proof/*')",
     "test:slow": "bun test tests/evolution/evolve.test.ts tests/evolution/integration.test.ts tests/monitoring/integration.test.ts tests/dashboard/dashboard-server.test.ts",
     "build:dashboard": "cd apps/local-dashboard && bunx vite build",
-    "link:claude-workspace": "bash scripts/link-claude-workspace.sh",
     "prepack": "node scripts/publish-package-json.cjs prepare",
     "postpack": "node scripts/publish-package-json.cjs restore",
+    "link:claude-workspace": "bash scripts/link-claude-workspace.sh",
     "sync-version": "bun run scripts/sync-skill-version.ts",
     "validate:subagents": "bun run scripts/validate-subagent-docs.ts",
     "prepublishOnly": "bun run sync-version && bun run build:dashboard",
@@ -82,5 +82,8 @@
     "@types/bun": "^1.1.0",
     "oxfmt": "^0.41.0",
     "oxlint": "^1.56.0"
-  }
+  },
+  "bundledDependencies": [
+    "@selftune/telemetry-contract"
+  ]
 }

package/packages/telemetry-contract/node_modules/zod/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/packages/telemetry-contract/node_modules/zod/README.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="logo.svg" width="200px" align="center" alt="Zod logo" />
+  <h1 align="center">Zod</h1>
+  <p align="center">
+    TypeScript-first schema validation with static type inference
+    <br/>
+    by <a href="https://x.com/colinhacks">@colinhacks</a>
+  </p>
+</p>
+<br/>
+
+<p align="center">
+<a href="https://github.com/colinhacks/zod/actions?query=branch%3Amain"><img src="https://github.com/colinhacks/zod/actions/workflows/test.yml/badge.svg?event=push&branch=main" alt="Zod CI status" /></a>
+<a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/colinhacks/zod" alt="License"></a>
+<a href="https://www.npmjs.com/package/zod" rel="nofollow"><img src="https://img.shields.io/npm/dw/zod.svg" alt="npm"></a>
+<a href="https://discord.gg/KaSRdyX2vc" rel="nofollow"><img src="https://img.shields.io/discord/893487829802418277?label=Discord&logo=discord&logoColor=white" alt="discord server"></a>
+<a href="https://github.com/colinhacks/zod" rel="nofollow"><img src="https://img.shields.io/github/stars/colinhacks/zod" alt="stars"></a>
+</p>
+
+<div align="center">
+  <a href="https://zod.dev/api">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://discord.gg/RcG33DQJdf">Discord</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://twitter.com/colinhacks">𝕏</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://bsky.app/profile/zod.dev">Bluesky</a>
+  <br />
+</div>
+
+<br/>
+<br/>
+
+<h2 align="center">Featured sponsor: Jazz</h2>
+
+<div align="center">
+  <a href="https://jazz.tools/?utm_source=zod">
+    <picture width="85%" >
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png">
+      <img alt="jazz logo" src="https://raw.githubusercontent.com/garden-co/jazz/938f6767e46cdfded60e50d99bf3b533f4809c68/homepage/homepage/public/Zod%20sponsor%20message.png" width="85%">
+    </picture>
+  </a>
+  <br/>
+  <p><sub>Learn more about <a target="_blank" rel="noopener noreferrer" href="mailto:sponsorship@colinhacks.com">featured sponsorships</a></sub></p>
+</div>
+
+<br/>
+<br/>
+<br/>
+
+### [Read the docs →](https://zod.dev/api)
+
+<br/>
+<br/>
+
+## What is Zod?
+
+Zod is a TypeScript-first validation library. Define a schema and parse some data with it. You'll get back a strongly typed, validated result.
+
+```ts
+import * as z from "zod";
+
+const User = z.object({
+  name: z.string(),
+});
+
+// some untrusted data...
+const input = {
+  /* stuff */
+};
+
+// the parsed result is validated and type safe!
+const data = User.parse(input);
+
+// so you can use it with confidence :)
+console.log(data.name);
+```
+
+<br/>
+
+## Features
+
+- Zero external dependencies
+- Works in Node.js and all modern browsers
+- Tiny: `2kb` core bundle (gzipped)
+- Immutable API: methods return a new instance
+- Concise interface
+- Works with TypeScript and plain JS
+- Built-in JSON Schema conversion
+- Extensive ecosystem
+
+<br/>
+
+## Installation
+
+```sh
+npm install zod
+```
+
+<br/>
+
+## Basic usage
+
+Before you can do anything else, you need to define a schema. For the purposes of this guide, we'll use a simple object schema.
+
+```ts
+import * as z from "zod";
+
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+```
+
+### Parsing data
+
+Given any Zod schema, use `.parse` to validate an input. If it's valid, Zod returns a strongly-typed _deep clone_ of the input.
+
+```ts
+Player.parse({ username: "billie", xp: 100 });
+// => returns { username: "billie", xp: 100 }
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](https://zod.dev/api#refinements) or [transforms](https://zod.dev/api#transforms), you'll need to use the `.parseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.parseAsync("hello");
+// => "hello"
+```
+
+### Handling errors
+
+When validation fails, the `.parse()` method will throw a `ZodError` instance with granular information about the validation issues.
+
+```ts
+try {
+  Player.parse({ username: 42, xp: "100" });
+} catch (err) {
+  if (err instanceof z.ZodError) {
+    err.issues;
+    /* [
+      {
+        expected: 'string',
+        code: 'invalid_type',
+        path: [ 'username' ],
+        message: 'Invalid input: expected string'
+      },
+      {
+        expected: 'number',
+        code: 'invalid_type',
+        path: [ 'xp' ],
+        message: 'Invalid input: expected number'
+      }
+    ] */
+  }
+}
+```
+
+To avoid a `try/catch` block, you can use the `.safeParse()` method to get back a plain result object containing either the successfully parsed data or a `ZodError`. The result type is a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions), so you can handle both cases conveniently.
+
+```ts
+const result = Player.safeParse({ username: 42, xp: "100" });
+if (!result.success) {
+  result.error; // ZodError instance
+} else {
+  result.data; // { username: string; xp: number }
+}
+```
+
+**Note** — If your schema uses certain asynchronous APIs like `async` [refinements](#refine) or [transforms](#transform), you'll need to use the `.safeParseAsync()` method instead.
+
+```ts
+const schema = z.string().refine(async (val) => val.length <= 8);
+
+await schema.safeParseAsync("hello");
+// => { success: true; data: "hello" }
+```
+
+### Inferring types
+
+Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility and use it however you like.
+
+```ts
+const Player = z.object({
+  username: z.string(),
+  xp: z.number(),
+});
+
+// extract the inferred type
+type Player = z.infer<typeof Player>;
+
+// use it in your code
+const player: Player = { username: "billie", xp: 100 };
+```
+
+In some cases, the input & output types of a schema can diverge. For instance, the `.transform()` API can convert the input from one type to another. In these cases, you can extract the input and output types independently:
+
+```ts
+const mySchema = z.string().transform((val) => val.length);
+
+type MySchemaIn = z.input<typeof mySchema>;
+// => string
+
+type MySchemaOut = z.output<typeof mySchema>; // equivalent to z.infer<typeof mySchema>
+// number
+```