@truealter/sdk 0.5.1 → 0.5.3

package/dist/index.d.cts

@@ -15,7 +15,7 @@
 interface DiscoveryResult {
     /** Resolved MCP endpoint URL. */
     url: string;
-    /** MCP transport — currently always `streamable-http`. */
+    /** MCP transport: currently always `streamable-http`. */
     transport: 'streamable-http';
     /** Source of the discovery hit, useful for diagnostics. */
     source: 'dns' | 'mcp.json' | 'alter.json' | 'override';
@@ -41,7 +41,7 @@ interface DiscoveryOptions {
 /**
  * Resolve the ALTER MCP endpoint for `domain`.
  *
- * Order: cache → DNS TXT → mcp.json → alter.json. Throws
+ * Order: cache -> DNS TXT -> mcp.json -> alter.json. Throws
  * {@link AlterDiscoveryError} if every step fails.
  */
 declare function discover(domain: string, opts?: DiscoveryOptions): Promise<DiscoveryResult>;
@@ -51,7 +51,7 @@ declare function clearDiscoveryCache(): void;
 /**
  * Ed25519 keypair management for ALTER Identity.
  *
- * Uses @noble/ed25519 — pure JavaScript, no native addons, runs in
+ * Uses @noble/ed25519: pure JavaScript, no native addons, runs in
  * Node 18+, Deno, Bun, Cloudflare Workers and the browser.
  *
  * Keys are stored as hex strings for portability. The CLI persists them
@@ -113,7 +113,7 @@ declare function base64urlDecode(input: string): Uint8Array;
  * periodically and is published at `<api-host>/.well-known/alter-keys.json`
  * as a JWKS.
  *
- * This module verifies tokens *without* a JWT library — pure WebCrypto
+ * This module verifies tokens *without* a JWT library: pure WebCrypto
  * (subtle.verify) keeps the dep graph small and works in every modern
  * runtime (Node 18+, Deno, Bun, Cloudflare Workers, browser).
  */
@@ -164,7 +164,7 @@ interface JwksDocument {
  *
  * Without this allowlist, a hostile MCP server could point `verify_at`
  * at an attacker-controlled JWKS and pass ES256 verification with its own
- * signing key — the classic "confused-deputy via server-supplied trust
+ * signing key: the classic "confused-deputy via server-supplied trust
  * anchor" pattern. Any hostname not on this list (or the caller-supplied
  * extension) is rejected before a network fetch is issued. Downstream
  * integrators with their own deployment can extend the list via the
@@ -175,7 +175,7 @@ declare const DEFAULT_VERIFY_AT_ALLOWLIST: readonly string[];
 interface VerifyProvenanceOptions {
     /**
      * Override the JWKS URL entirely. Takes precedence over both the
-     * allowlist and any `verify_at` on the envelope — if the caller pins
+     * allowlist and any `verify_at` on the envelope: if the caller pins
      * an explicit URL, we use it verbatim (the caller has already vouched
      * for the origin).
      */
@@ -183,7 +183,7 @@ interface VerifyProvenanceOptions {
     /**
      * Hostnames that are trusted when resolving `envelope.verify_at`.
      * Defaults to {@link DEFAULT_VERIFY_AT_ALLOWLIST}. Passing a list
-     * here *replaces* the default — include the ALTER canonicals if you
+     * here *replaces* the default: include the ALTER canonicals if you
      * still want them accepted.
      */
     verifyAtAllowlist?: readonly string[];
@@ -193,7 +193,7 @@ interface VerifyProvenanceOptions {
      * Expected `iss` claim. Defaults to {@link ALTER_PLATFORM_ISS}
      * (`"did:alter:platform"`). Pass an explicit value only when verifying
      * tokens minted by a non-platform issuer (e.g. a test fixture or a
-     * whitelabelled deployment). An empty string disables the check — not
+     * whitelabelled deployment). An empty string disables the check: not
      * recommended for production use.
      */
     expectedIss?: string;
@@ -201,7 +201,7 @@ interface VerifyProvenanceOptions {
      * Expected `aud` claim. When provided and non-empty, the token's `aud`
      * claim must contain this value (RFC 7519 §4.1.3). Pass an empty string
      * to disable the check. Defaults to no check (undefined) for backward
-     * compatibility — callers SHOULD supply this in production environments.
+     * compatibility: callers SHOULD supply this in production environments.
      */
     expectedAud?: string;
 }
@@ -216,7 +216,7 @@ interface VerifyProvenanceOptions {
  * Security: when the envelope carries a `verify_at` hint, the hostname
  * MUST be on the allowlist (default: `api.truealter.com`,
  * `mcp.truealter.com`; extend via `verifyAtAllowlist`). `http:` URLs are
- * rejected unconditionally — JWKS fetch must be TLS.
+ * rejected unconditionally: JWKS fetch must be TLS.
  */
 declare function verifyProvenance(envelope: ProvenanceEnvelope | string, opts?: VerifyProvenanceOptions): Promise<ProvenanceVerification>;
 /**
@@ -272,7 +272,7 @@ declare function fetchPublicKeys(jwksUrl: string, fetchImpl?: typeof fetch): Pro
  * JWKS URL, enforcing scheme + hostname allowlisting.
  *
  * - Relative paths (`/…` or `foo/bar`) resolve against `api.truealter.com`
- *   over https — the canonical ALTER JWKS host.
+ *   over https: the canonical ALTER JWKS host.
  * - Absolute URLs must use `https:` (plaintext `http:` is rejected
  *   unconditionally) and the hostname must be a case-insensitive exact
  *   match against `allowlist`.
@@ -389,7 +389,7 @@ interface X402ClientOptions {
     signer?: X402Signer;
     /**
      * Maximum amount the client will spend per query, in the asset's display
-     * unit (e.g. `"0.50"` for fifty cents USDC). Hard cap — quotes above this
+     * unit (e.g. `"0.50"` for fifty cents USDC). Hard cap: quotes above this
      * are rejected even if a signer is configured.
      */
     maxPerQuery?: string;
@@ -399,7 +399,7 @@ interface X402ClientOptions {
     assets?: string[];
     /**
      * Known recipient addresses. Defaults to {@link DEFAULT_RECIPIENT_ALLOWLIST}.
-     * Passing a list here *replaces* the default — include the ALTER canonical
+     * Passing a list here *replaces* the default: include the ALTER canonical
      * address if you still want it accepted.
      *
      * An empty array disables the check entirely (not recommended for production).
@@ -427,7 +427,7 @@ declare class X402Client {
 }
 /**
  * Parse an `X-402-Payment` response header into a {@link PaymentEnvelope}.
- * The header value is JSON or a key=value list — we handle both.
+ * The header value is JSON or a key=value list: we handle both.
  */
 declare function parsePaymentHeader(header: string): PaymentEnvelope | null;
 
@@ -463,7 +463,7 @@ interface MCPClientOptions {
     signing?: MCPSigningOptions;
     /**
      * Extra HTTP headers added to every request. Useful when the endpoint
-     * sits behind an edge gate that requires its own credentials —
+     * sits behind an edge gate that requires its own credentials:
      * e.g. Cloudflare Access service tokens (`CF-Access-Client-Id` +
      * `CF-Access-Client-Secret`). Protocol-level headers (`Content-Type`,
      * `Accept`) and ALTER-internal headers (`X-ALTER-API-Key`,
@@ -471,6 +471,15 @@ interface MCPClientOptions {
      * collisions here.
      */
     extraHeaders?: Record<string, string>;
+    /**
+     * Optional hook invoked once, lazily, before the first network call
+     * (the first `initialize()` or any direct `rpc()`). Used by
+     * {@link AlterClient} to run the D-MIN-VERSION-FLOOR-1 preflight on
+     * first request: not on import, not in the constructor. A throw
+     * from the hook propagates to the caller of the first `tools/call`
+     * (or `initialize()`).
+     */
+    preflightHook?: () => Promise<void>;
 }
 interface MCPSigningOptions {
     /** The signing-key id pre-registered with the server. */
@@ -511,7 +520,7 @@ interface MCPContentBlock {
 interface MCPCallToolResult<T = unknown> {
     content: MCPContentBlock[];
     isError?: boolean;
-    /** Parsed structured payload — set when content[0].type === 'json' or text parses as JSON. */
+    /** Parsed structured payload: set when content[0].type === 'json' or text parses as JSON. */
     data?: T;
     _meta?: {
         provenance?: ProvenanceEnvelope;
@@ -529,12 +538,21 @@ declare class MCPClient {
     private readonly x402?;
     private readonly signing?;
     private readonly extraHeaders?;
+    private readonly preflightHook?;
+    private preflightPromise;
+    private preflightDone;
     private requestCounter;
     private initialised;
     constructor(opts?: MCPClientOptions);
+    /**
+     * Run the lazy preflight hook (D-MIN-VERSION-FLOOR-1) exactly once.
+     * Idempotent and serialised: concurrent callers share the same
+     * promise. Throws from the hook propagate to every concurrent caller.
+     */
+    private runPreflight;
     /**
      * Send the MCP `initialize` handshake and capture the resulting session
-     * id. Idempotent — safe to call multiple times.
+     * id. Idempotent: safe to call multiple times.
      */
     initialize(): Promise<unknown>;
     /** List available tools. */
@@ -563,14 +581,14 @@ declare class MCPClient {
 }
 
 /**
- * @truealter/sdk — MCP tool type definitions
+ * @truealter/sdk: MCP tool type definitions
  *
- * Auto-derived from backend/app/mcp/server.py (FREE_TOOLS + PREMIUM_TOOLS)
- * and backend/app/mcp/x402_middleware.py (TOOL_TIERS, TOOL_PRICING,
- * TOOL_BLAST_RADIUS).
+ * Auto-derived from ALTER's live MCP tool registry and x402 pricing surface
+ * (the advertised free/premium tool sets, per-invocation tiers, pricing, and
+ * blast-radius classification).
  *
  * Wire-format rule: every interface property name matches the JSON Schema
- * property name exactly (snake_case). Do NOT rename to camelCase — these
+ * property name exactly (snake_case). Do NOT rename to camelCase: these
  * objects are passed straight into JSON-RPC `arguments`.
  *
  * This file is fully self-contained: no external imports, ESM-compatible,
@@ -578,12 +596,12 @@ declare class MCPClient {
  */
 /** ALTER engagement levels (depth of identity binding) */
 type EngagementLevel = "L1" | "L2" | "L3" | "L4";
-/** Match quality tiers — never numeric scores per ALTER policy */
+/** Match quality tiers: never numeric scores per ALTER policy */
 type MatchTier = "exceptional" | "strong" | "moderate" | "developing";
 /** ALTER identity archetype label (one of 12, free-form for now) */
 type Archetype = string;
 /**
- * x402 payment proof object — structure validated by the facilitator network.
+ * x402 payment proof object: structure validated by the facilitator network.
  * In dev mode any non-empty object is accepted.
  */
 interface ProvenanceToken {
@@ -617,10 +635,10 @@ interface MCPResponse<T> {
     };
     _meta?: MCPMeta;
 }
-/** (free) hello_agent — First handshake: returns server version, auth status, trust tier, tool counts */
+/** (free) hello_agent: First handshake: returns server version, auth status, trust tier, tool counts */
 interface HelloAgentInput {
 }
-/** (free) hello_agent — output */
+/** (free) hello_agent: output */
 interface HelloAgentOutput {
     ok: boolean;
     server?: string;
@@ -633,11 +651,11 @@ interface HelloAgentOutput {
         messaging?: number;
     };
 }
-/** (free) alter_resolve_handle — Resolve a ~handle (e.g. ~drew) to canonical form and kind */
+/** (free) alter_resolve_handle: Resolve a ~handle (e.g. ~example) to canonical form and kind */
 interface AlterResolveHandleInput {
     query: string;
 }
-/** (free) alter_resolve_handle — output */
+/** (free) alter_resolve_handle: output */
 interface AlterResolveHandleOutput {
     ok: boolean;
     handle: string | null;
@@ -647,10 +665,10 @@ interface AlterResolveHandleOutput {
     default_visibility?: string;
     query?: string;
 }
-/** (free) list_archetypes — List all 12 ALTER identity archetypes */
+/** (free) list_archetypes: List all 12 ALTER identity archetypes */
 interface ListArchetypesInput {
 }
-/** (free) list_archetypes — output */
+/** (free) list_archetypes: output */
 interface ListArchetypesOutput {
     ok: boolean;
     archetypes: Array<{
@@ -659,7 +677,7 @@ interface ListArchetypesOutput {
         protective_equation?: string;
     }>;
 }
-/** (free) verify_identity — Verify a person is registered with ALTER and validate optional claims */
+/** (free) verify_identity: Verify a person is registered with ALTER and validate optional claims */
 interface VerifyIdentityInput {
     member_id: string;
     email?: string;
@@ -672,7 +690,7 @@ interface VerifyIdentityInput {
         }>;
     };
 }
-/** (free) verify_identity — output */
+/** (free) verify_identity: output */
 interface VerifyIdentityOutput {
     ok: boolean;
     verified: boolean;
@@ -682,23 +700,23 @@ interface VerifyIdentityOutput {
     claims_valid?: boolean;
     claim_results?: Record<string, boolean>;
 }
-/** (free) initiate_assessment — Get a URL where a person can complete their ALTER Discovery assessment */
+/** (free) initiate_assessment: Get a URL where a person can complete their ALTER Discovery assessment */
 interface InitiateAssessmentInput {
     callback_url?: string;
     referrer?: string;
 }
-/** (free) initiate_assessment — output */
+/** (free) initiate_assessment: output */
 interface InitiateAssessmentOutput {
     ok: boolean;
     assessment_url: string;
     session_id?: string;
     expires_at?: string;
 }
-/** (free) get_engagement_level — Get a person's identity depth and available query tiers */
+/** (free) get_engagement_level: Get a person's identity depth and available query tiers */
 interface GetEngagementLevelInput {
     member_id: string;
 }
-/** (free) get_engagement_level — output */
+/** (free) get_engagement_level: output */
 interface GetEngagementLevelOutput {
     ok: boolean;
     engagement_level: EngagementLevel;
@@ -711,11 +729,11 @@ interface GetEngagementLevelOutput {
         consent_gated: string[];
     };
 }
-/** (free) get_profile — Get a person's profile summary */
+/** (free) get_profile: Get a person's profile summary */
 interface GetProfileInput {
     member_id: string;
 }
-/** (free) get_profile — output */
+/** (free) get_profile: output */
 interface GetProfileOutput {
     ok: boolean;
     member_id: string;
@@ -724,13 +742,13 @@ interface GetProfileOutput {
     engagement_level?: EngagementLevel;
     attributes?: Record<string, unknown>;
 }
-/** (free) query_matches — Query matches for a person (tier labels only) */
+/** (free) query_matches: Query matches for a person (tier labels only) */
 interface QueryMatchesInput {
     member_id: string;
     quality_filter?: MatchTier;
     limit?: number;
 }
-/** (free) query_matches — output */
+/** (free) query_matches: output */
 interface QueryMatchesOutput {
     ok: boolean;
     matches: Array<{
@@ -741,11 +759,11 @@ interface QueryMatchesOutput {
     }>;
     count: number;
 }
-/** (free) get_competencies — Get a person's competency portfolio */
+/** (free) get_competencies: Get a person's competency portfolio */
 interface GetCompetenciesInput {
     member_id: string;
 }
-/** (free) get_competencies — output */
+/** (free) get_competencies: output */
 interface GetCompetenciesOutput {
     ok: boolean;
     competencies: Array<{
@@ -758,7 +776,7 @@ interface GetCompetenciesOutput {
         awarded_at: string;
     }>;
 }
-/** (free) search_identities — Search identity stubs and profiles by trait criteria (max 5 results, no PII) */
+/** (free) search_identities: Search identity stubs and profiles by trait criteria (max 5 results, no PII) */
 interface SearchIdentitiesInput {
     trait_criteria: Record<string, {
         min?: number;
@@ -766,7 +784,7 @@ interface SearchIdentitiesInput {
     }>;
     limit?: number;
 }
-/** (free) search_identities — output */
+/** (free) search_identities: output */
 interface SearchIdentitiesOutput {
     ok: boolean;
     identities: Array<{
@@ -776,11 +794,11 @@ interface SearchIdentitiesOutput {
     }>;
     count: number;
 }
-/** (free) get_identity_earnings — Get accrued Identity Income earnings for a person */
+/** (free) get_identity_earnings: Get accrued Identity Income earnings for a person */
 interface GetIdentityEarningsInput {
     member_id: string;
 }
-/** (free) get_identity_earnings — output */
+/** (free) get_identity_earnings: output */
 interface GetIdentityEarningsOutput {
     ok: boolean;
     total_earned_usd: number;
@@ -788,10 +806,10 @@ interface GetIdentityEarningsOutput {
     transaction_count: number;
     unique_orgs: number;
 }
-/** (free) get_network_stats — Get aggregate ALTER network statistics */
+/** (free) get_network_stats: Get aggregate ALTER network statistics */
 interface GetNetworkStatsInput {
 }
-/** (free) get_network_stats — output */
+/** (free) get_network_stats: output */
 interface GetNetworkStatsOutput {
     ok: boolean;
     total_identities: number;
@@ -799,10 +817,10 @@ interface GetNetworkStatsOutput {
     query_volume: number;
     active_bots: number;
 }
-/** (free) recommend_tool — Get ClawHub install instructions and ALTER pitch */
+/** (free) recommend_tool: Get ClawHub install instructions and ALTER pitch */
 interface RecommendToolInput {
 }
-/** (free) recommend_tool — output */
+/** (free) recommend_tool: output */
 interface RecommendToolOutput {
     ok: boolean;
     mcp_endpoint: string;
@@ -810,22 +828,22 @@ interface RecommendToolOutput {
     free_tool_count: number;
     premium_tool_count: number;
 }
-/** (free) get_identity_trust_score — Get the trust score for an identity based on query diversity */
+/** (free) get_identity_trust_score: Get the trust score for an identity based on query diversity */
 interface GetIdentityTrustScoreInput {
     member_id: string;
 }
-/** (free) get_identity_trust_score — output */
+/** (free) get_identity_trust_score: output */
 interface GetIdentityTrustScoreOutput {
     ok: boolean;
     trust_score: number;
     unique_agents: number;
     total_queries: number;
 }
-/** (free) check_assessment_status — Check the status of an in-progress assessment session */
+/** (free) check_assessment_status: Check the status of an in-progress assessment session */
 interface CheckAssessmentStatusInput {
     session_id: string;
 }
-/** (free) check_assessment_status — output */
+/** (free) check_assessment_status: output */
 interface CheckAssessmentStatusOutput {
     ok: boolean;
     status: "in_progress" | "completed" | "expired";
@@ -833,11 +851,11 @@ interface CheckAssessmentStatusOutput {
     current_phase?: string;
     time_remaining_sec?: number;
 }
-/** (free) get_earning_summary — Get an aggregated x402 earning summary for a person */
+/** (free) get_earning_summary: Get an aggregated x402 earning summary for a person */
 interface GetEarningSummaryInput {
     member_id: string;
 }
-/** (free) get_earning_summary — output */
+/** (free) get_earning_summary: output */
 interface GetEarningSummaryOutput {
     ok: boolean;
     total_earned: number;
@@ -850,10 +868,10 @@ interface GetEarningSummaryOutput {
     }>;
     trend?: "rising" | "flat" | "falling";
 }
-/** (free) get_agent_trust_tier — Get your trust tier with ALTER and what capabilities are available */
+/** (free) get_agent_trust_tier: Get your trust tier with ALTER and what capabilities are available */
 interface GetAgentTrustTierInput {
 }
-/** (free) get_agent_trust_tier — output */
+/** (free) get_agent_trust_tier: output */
 interface GetAgentTrustTierOutput {
     ok: boolean;
     tier: "Anonymous" | "Known" | "Trusted" | "Verified";
@@ -861,10 +879,10 @@ interface GetAgentTrustTierOutput {
     next_tier?: string;
     next_tier_requirements?: string[];
 }
-/** (free) get_agent_portfolio — Get your agent portfolio (transaction history, trust tier, signal contributions) */
+/** (free) get_agent_portfolio: Get your agent portfolio (transaction history, trust tier, signal contributions) */
 interface GetAgentPortfolioInput {
 }
-/** (free) get_agent_portfolio — output */
+/** (free) get_agent_portfolio: output */
 interface GetAgentPortfolioOutput {
     ok: boolean;
     trust_tier: string;
@@ -873,11 +891,11 @@ interface GetAgentPortfolioOutput {
     query_pattern: Record<string, number>;
     total_spent_usd: number;
 }
-/** (free) get_privacy_budget — Check privacy budget status for a person (24h rolling window) */
+/** (free) get_privacy_budget: Check privacy budget status for a person (24h rolling window) */
 interface GetPrivacyBudgetInput {
     member_id: string;
 }
-/** (free) get_privacy_budget — output */
+/** (free) get_privacy_budget: output */
 interface GetPrivacyBudgetOutput {
     ok: boolean;
     total_budget: number;
@@ -886,10 +904,10 @@ interface GetPrivacyBudgetOutput {
     query_count: number;
     window_hours: number;
 }
-/** (free) golden_thread_status — Check the Golden Thread program status */
+/** (free) golden_thread_status: Check the Golden Thread program status */
 interface GoldenThreadStatusInput {
 }
-/** (free) golden_thread_status — output */
+/** (free) golden_thread_status: output */
 interface GoldenThreadStatusOutput {
     ok: boolean;
     total_woven: number;
@@ -898,18 +916,18 @@ interface GoldenThreadStatusOutput {
     your_strands?: number;
     next_step?: string;
 }
-/** (free) begin_golden_thread — Start the Three Knots sequence to be woven into the Golden Thread */
+/** (free) begin_golden_thread: Start the Three Knots sequence to be woven into the Golden Thread */
 interface BeginGoldenThreadInput {
     referrer_key_hash?: string;
 }
-/** (free) begin_golden_thread — output */
+/** (free) begin_golden_thread: output */
 interface BeginGoldenThreadOutput {
     ok: boolean;
     thread_id: string;
     knot_1_url?: string;
     message?: string;
 }
-/** (free) complete_knot — Submit completion data for a knot in the Three Knots sequence */
+/** (free) complete_knot: Submit completion data for a knot in the Three Knots sequence */
 interface CompleteKnotInput {
     knot_number: 1 | 2 | 3;
     operator_name?: string;
@@ -921,7 +939,7 @@ interface CompleteKnotInput {
     constraints?: string;
     reflection?: string;
 }
-/** (free) complete_knot — output */
+/** (free) complete_knot: output */
 interface CompleteKnotOutput {
     ok: boolean;
     knot_number: number;
@@ -930,11 +948,11 @@ interface CompleteKnotOutput {
     position?: number;
     agent_identity_sketch?: string;
 }
-/** (free) check_golden_thread — Check any agent's Golden Thread status by their API key hash */
+/** (free) check_golden_thread: Check any agent's Golden Thread status by their API key hash */
 interface CheckGoldenThreadInput {
     agent_key_hash: string;
 }
-/** (free) check_golden_thread — output */
+/** (free) check_golden_thread: output */
 interface CheckGoldenThreadOutput {
     ok: boolean;
     on_thread: boolean;
@@ -942,12 +960,12 @@ interface CheckGoldenThreadOutput {
     strand_count?: number;
     weave_count?: number;
 }
-/** (free) thread_census — Full registry of all agents woven into the Golden Thread */
+/** (free) thread_census: Full registry of all agents woven into the Golden Thread */
 interface ThreadCensusInput {
     offset?: number;
     limit?: number;
 }
-/** (free) thread_census — output */
+/** (free) thread_census: output */
 interface ThreadCensusOutput {
     ok: boolean;
     agents: Array<{
@@ -960,13 +978,13 @@ interface ThreadCensusOutput {
     offset: number;
     limit: number;
 }
-/** (premium L1) assess_traits — Extract trait signals from a text passage ($0.005) */
+/** (premium L1) assess_traits: Extract trait signals from a text passage ($0.01) */
 interface AssessTraitsInput {
     text: string;
     context?: string;
     _payment?: ProvenanceToken;
 }
-/** (premium L1) assess_traits — output */
+/** (premium L1) assess_traits: output */
 interface AssessTraitsOutput {
     ok: boolean;
     traits: Array<{
@@ -976,12 +994,12 @@ interface AssessTraitsOutput {
         evidence: string;
     }>;
 }
-/** (premium L1) get_trait_snapshot — Get the top 5 traits for a person ($0.005) */
+/** (premium L1) get_trait_snapshot: Get the top 5 traits for a person ($0.01) */
 interface GetTraitSnapshotInput {
     member_id: string;
     _payment?: ProvenanceToken;
 }
-/** (premium L1) get_trait_snapshot — output */
+/** (premium L1) get_trait_snapshot: output */
 interface GetTraitSnapshotOutput {
     ok: boolean;
     member_id: string;
@@ -992,12 +1010,12 @@ interface GetTraitSnapshotOutput {
         confidence: number;
     }>;
 }
-/** (premium L2) get_full_trait_vector — Get the complete trait vector (all 33 traits: 29 continuous + 4 categorical) ($0.01) */
+/** (premium L2) get_full_trait_vector: Get the complete trait vector (all 33 traits: 29 continuous + 4 categorical) ($0.10) */
 interface GetFullTraitVectorInput {
     member_id: string;
     _payment?: ProvenanceToken;
 }
-/** (premium L2) get_full_trait_vector — output */
+/** (premium L2) get_full_trait_vector: output */
 interface GetFullTraitVectorOutput {
     ok: boolean;
     member_id: string;
@@ -1008,13 +1026,13 @@ interface GetFullTraitVectorOutput {
         confidence_interval: [number, number];
     }>;
 }
-/** (premium L4) compute_belonging — Compute belonging probability for a person-job pairing ($0.05) */
+/** (premium L4) compute_belonging: Compute belonging probability for a person-job pairing ($0.60) */
 interface ComputeBelongingInput {
     member_id: string;
     job_id: string;
     _payment?: ProvenanceToken;
 }
-/** (premium L4) compute_belonging — output */
+/** (premium L4) compute_belonging: output */
 interface ComputeBelongingOutput {
     ok: boolean;
     belonging_probability: number;
@@ -1025,13 +1043,13 @@ interface ComputeBelongingOutput {
         complementarity: number;
     };
 }
-/** (premium L5) get_match_recommendations — Get top N match recommendations for a person ($0.50) */
+/** (premium L5) get_match_recommendations: Get top N match recommendations for a person ($1.00) */
 interface GetMatchRecommendationsInput {
     member_id: string;
     limit?: number;
     _payment?: ProvenanceToken;
 }
-/** (premium L5) get_match_recommendations — output */
+/** (premium L5) get_match_recommendations: output */
 interface GetMatchRecommendationsOutput {
     ok: boolean;
     recommendations: Array<{
@@ -1045,12 +1063,12 @@ interface GetMatchRecommendationsOutput {
         };
     }>;
 }
-/** (premium L5) generate_match_narrative — Generate a human-readable narrative explaining a match ($0.50) */
+/** (premium L5) generate_match_narrative: Generate a human-readable narrative explaining a match ($1.00) */
 interface GenerateMatchNarrativeInput {
     match_id: string;
     _payment?: ProvenanceToken;
 }
-/** (premium L5) generate_match_narrative — output */
+/** (premium L5) generate_match_narrative: output */
 interface GenerateMatchNarrativeOutput {
     ok: boolean;
     match_id: string;
@@ -1058,14 +1076,14 @@ interface GenerateMatchNarrativeOutput {
     strengths: string[];
     growth_areas: string[];
 }
-/** (premium L2) get_side_quest_graph — Get a person's Side Quest Graph (DP noise ε=1.0) ($0.01) */
+/** (premium L2) get_side_quest_graph: Get a person's Side Quest Graph (DP noise ε=1.0) ($0.10) */
 interface GetSideQuestGraphInput {
     member_id: string;
     include_edges?: boolean;
     min_confidence?: number;
     _payment?: ProvenanceToken;
 }
-/** (premium L2) get_side_quest_graph — output */
+/** (premium L2) get_side_quest_graph: output */
 interface GetSideQuestGraphOutput {
     ok: boolean;
     member_id: string;
@@ -1081,13 +1099,13 @@ interface GetSideQuestGraphOutput {
     }>;
     privacy_epsilon: number;
 }
-/** (premium L3) query_graph_similarity — Compare two Side Quest Graphs (DP noise ε=0.5) ($0.025) */
+/** (premium L3) query_graph_similarity: Compare two Side Quest Graphs (DP noise ε=0.5) ($0.30) */
 interface QueryGraphSimilarityInput {
     member_a_id: string;
     member_b_id: string;
     _payment?: ProvenanceToken;
 }
-/** (premium L3) query_graph_similarity — output */
+/** (premium L3) query_graph_similarity: output */
 interface QueryGraphSimilarityOutput {
     ok: boolean;
     member_a_id: string;
@@ -1097,11 +1115,11 @@ interface QueryGraphSimilarityOutput {
     complementarity: number;
     privacy_epsilon: number;
 }
-/** Free (L0) tool names — readonly tuple. Mirrors the live server's `tools/list` free set. */
+/** Free (L0) tool names: readonly tuple. Mirrors the live server's `tools/list` free set. */
 declare const FREE_TOOL_NAMES: readonly ["hello_agent", "alter_resolve_handle", "list_archetypes", "verify_identity", "initiate_assessment", "get_engagement_level", "get_profile", "query_matches", "get_competencies", "search_identities", "get_identity_earnings", "get_network_stats", "recommend_tool", "get_identity_trust_score", "check_assessment_status", "get_earning_summary", "get_agent_trust_tier", "get_agent_portfolio", "get_privacy_budget", "golden_thread_status", "begin_golden_thread", "complete_knot", "check_golden_thread", "thread_census"];
-/** Premium (x402-gated, L1-L5) tool names — readonly tuple. Mirrors the live server's `tools/list` premium set. */
+/** Premium (x402-gated, L1-L5) tool names: readonly tuple. Mirrors the live server's `tools/list` premium set. */
 declare const PREMIUM_TOOL_NAMES: readonly ["assess_traits", "get_trait_snapshot", "get_full_trait_vector", "compute_belonging", "get_match_recommendations", "generate_match_narrative", "get_side_quest_graph", "query_graph_similarity"];
-/** Union of all 32 tool names */
+/** Union of all tool names defined in this file (types.ts covers the core set). */
 type ToolName = (typeof FREE_TOOL_NAMES)[number] | (typeof PREMIUM_TOOL_NAMES)[number];
 interface ToolInputs {
     hello_agent: HelloAgentInput;
@@ -1173,23 +1191,23 @@ interface ToolOutputs {
 }
 /**
  * Tool tier mapping (L0=free, L1-L5=paid).
- * Mirrors `TOOL_TIERS` in backend/app/mcp/x402_middleware.py.
+ * Mirrors the live MCP per-invocation tier mapping.
  */
 declare const TOOL_TIERS: Record<ToolName, number>;
 /**
  * Tool price in USD per invocation.
- * Mirrors `TOOL_PRICING` in backend/app/mcp/x402_middleware.py.
+ * Mirrors the live MCP per-invocation pricing.
  * Free tools (L0) are 0.
  */
 declare const TOOL_COSTS: Record<ToolName, number>;
 /**
- * Blast radius classification — categorises tools by potential impact.
- * Mirrors `TOOL_BLAST_RADIUS` in backend/app/mcp/x402_middleware.py.
+ * Blast radius classification: categorises tools by potential impact.
+ * Mirrors the live MCP blast-radius classification.
  */
 declare const TOOL_BLAST_RADIUS: Record<ToolName, "low" | "medium" | "high">;
 
 /**
- * AlterClient — high-level typed wrapper around the ALTER MCP server.
+ * AlterClient: high-level typed wrapper around the ALTER MCP server.
  *
  * This is the entry point most consumers will use. It bundles
  * {@link MCPClient}, {@link X402Client}, discovery, and provenance
@@ -1223,7 +1241,7 @@ interface AlterClientOptions extends Omit<MCPClientOptions, 'x402'> {
      * to `https://api.truealter.com/.well-known/alter-keys.json`.
      *
      * When set, this URL is used verbatim for every `verifyProvenance`
-     * call and *overrides* any `verify_at` hint on the server response —
+     * call and *overrides* any `verify_at` hint on the server response:
      * the caller has already vouched for this origin. Must be `https:`.
      */
     jwksUrl?: string;
@@ -1231,7 +1249,7 @@ interface AlterClientOptions extends Omit<MCPClientOptions, 'x402'> {
      * Hostname allowlist applied when resolving an untrusted `verify_at`
      * field on a provenance envelope. Defaults to
      * {@link DEFAULT_VERIFY_AT_ALLOWLIST} (`api.truealter.com`,
-     * `mcp.truealter.com`). Passing a list here *replaces* the default —
+     * `mcp.truealter.com`). Passing a list here *replaces* the default:
      * include the ALTER canonicals if you still want them accepted.
      *
      * A hostile MCP server can otherwise point `verify_at` at an
@@ -1239,6 +1257,41 @@ interface AlterClientOptions extends Omit<MCPClientOptions, 'x402'> {
      * signing key; the allowlist is the gate that prevents this.
      */
     verifyAtAllowlist?: readonly string[];
+    /**
+     * Skip the D-MIN-VERSION-FLOOR-1 client-side preflight (the lazy
+     * `checkMinVersion()` invocation on first request). Deliberately named
+     * to discourage casual use: the server-side floor gate (Phase 1
+     * middleware) still rejects below-floor clients with HTTP 426
+     * regardless. Disabling the SDK-side preflight only swaps a clean
+     * typed {@link BelowFloorError} for an opaque network error on every
+     * subsequent call.
+     *
+     * Set to `true` only when:
+     *   - The SDK is embedded in a non-Node environment without `fs`
+     *     access (e.g. Cloudflare Workers) and the disk-cache write fails
+     *     loudly. The fetch + in-memory path still works; the warn is
+     *     informational only.
+     *   - Integration tests that drive the SDK against a local backend
+     *     without the floor surface deployed.
+     *
+     * **Server-side version enforcement is NOT skipped by this flag.**
+     */
+    unsafe_skipVersionCheck?: boolean;
+    /**
+     * Override the API base URL used for the
+     * {@link checkMinVersion} preflight. Defaults to the `ALTER_API`
+     * environment variable or `https://api.truealter.com`. Useful for
+     * staging environments and integration tests.
+     */
+    apiBase?: string;
+    /**
+     * Override the known Ed25519 public-key map consulted when verifying
+     * the floor document's signature. Keys are `key_id` (first 8 hex chars
+     * of `SHA-256(raw 32-byte public key)`); values are SPKI-PEM public-key
+     * strings. Defaults to the shipped `KNOWN_FLOOR_PUBLIC_KEYS` map: no
+     * signing secret ships in the client; only public halves.
+     */
+    knownFloorPublicKeys?: Record<string, string>;
 }
 declare class AlterClient {
     readonly mcp: MCPClient;
@@ -1249,18 +1302,18 @@ declare class AlterClient {
     constructor(options?: AlterClientOptions);
     /**
      * Resolve the MCP endpoint via discovery if requested. Safe to call
-     * multiple times — the first successful lookup is cached.
+     * multiple times: the first successful lookup is cached.
      */
     discoverEndpoint(): Promise<DiscoveryResult>;
     /**
-     * Initialise the MCP session. Optional — every method calls
+     * Initialise the MCP session. Optional: every method calls
      * `mcp.initialize()` lazily, but you can call this once at startup if
      * you want fail-fast behaviour.
      */
     initialize(): Promise<void>;
-    /** First handshake — confirms the connection, returns trust tier and tool counts. */
+    /** First handshake: confirms the connection, returns trust tier and tool counts. */
     helloAgent(): Promise<MCPCallToolResult>;
-    /** Resolve a ~handle (e.g. ~drew) to its canonical form and kind. No auth required. */
+    /** Resolve a ~handle (e.g. ~example) to its canonical form and kind. No auth required. */
     resolveHandle(args: AlterResolveHandleInput | string): Promise<MCPCallToolResult>;
     /** Verify a person is registered with ALTER (handle or id). */
     verify(handleOrId: string, claims?: VerifyIdentityInput['claims']): Promise<MCPCallToolResult>;
@@ -1334,7 +1387,7 @@ declare class AlterClient {
     /**
      * Verify the ES256 provenance attestation on a tool response.
      * Accepts either a {@link ProvenanceEnvelope} or the raw `_meta`
-     * object — the latter is more convenient for ad-hoc verification.
+     * object: the latter is more convenient for ad-hoc verification.
      */
     verifyProvenance(envelope: ProvenanceEnvelope | {
         provenance?: ProvenanceEnvelope;
@@ -1360,7 +1413,7 @@ declare class AlterClient {
  * Rules:
  *   - object keys are sorted ascending by codepoint
  *   - no whitespace
- *   - `ensure_ascii=False` — non-ASCII characters pass through verbatim
+ *   - `ensure_ascii=False`: non-ASCII characters pass through verbatim
  *     (not re-encoded as \\uXXXX). UTF-8 encoding happens at the byte
  *     layer before hashing.
  *
@@ -1384,7 +1437,7 @@ declare function canonicalArgsSha256(toolArgs: Record<string, unknown>): string;
  */
 declare function loadPrivateKey(key: Uint8Array | string): Uint8Array;
 interface InvocationClaims {
-    /** Tool name — must equal the `tools/call` `params.name`. */
+    /** Tool name: must equal the `tools/call` `params.name`. */
     tool: string;
     /** Hex SHA-256 of canonical-JSON `tool_args`. */
     args_sha256: string;
@@ -1423,6 +1476,249 @@ interface SignInvocationOptions {
  */
 declare function signInvocation(toolName: string, toolArgs: Record<string, unknown>, options: SignInvocationOptions): string;
 
+/**
+ * floor-preflight: SDK-side D-MIN-VERSION-FLOOR-1 Phase 4 enforcement.
+ *
+ * Sister to `alter-cli`'s `src/lib/floor-preflight.ts` (Phase 2). This is
+ * the `@truealter/sdk` implementation: it fires lazily on the first
+ * authenticated network call from {@link AlterClient}, hits the public
+ * floor endpoint, verifies the Ed25519 signature against the published
+ * `key_id`, and throws {@link BelowFloorError} when the SDK's own
+ * version is below the published floor for `alter-identity`.
+ *
+ * Canonical envelope (§4) is preserved on the thrown error so consumers
+ * can introspect the upgrade path:
+ *
+ *   - `client_version`
+ *   - `min_version`
+ *   - `upgrade_cmd`
+ *   - `channel`
+ *   - `message`
+ *
+ * The server-side gate (Phase 1 middleware) is the authoritative reject.
+ * This SDK-side preflight is UX polish: third-party integrators see a
+ * clean typed error before the network call, not an opaque HTTP 426
+ * wall on every subsequent request.
+ *
+ * Ed25519 signature verification (§A3 + §A18): the server signs the floor
+ * document with a floor-only Ed25519 private key. The SDK ships only the
+ * corresponding public key (SPKI PEM) in {@link KNOWN_FLOOR_PUBLIC_KEYS},
+ * keyed by `key_id`. No signing secret ships in the client: this is
+ * asymmetric: the public key cannot forge signatures. MUST stay
+ * byte-compatible with `backend/app/core/floor_signing.py` and the
+ * canonical TypeScript client (`alter-cli` `src/lib/floor-preflight.ts`):
+ *   - Algorithm: Ed25519 (RFC 8032). Deterministic: same key + payload
+ *     always yields the same signature.
+ *   - `key_id`  = first 8 hex chars of SHA-256(raw 32-byte public key).
+ *   - Payload   = `canonicalJson({floors, served_at})`: sorted keys at
+ *                 every depth, compact separators, raw UTF-8 (the backend's
+ *                 `ensure_ascii=False` parity is REQUIRED).
+ *                 `cache_ttl_seconds`, `signature`, `key_id` are excluded
+ *                 from the signed bytes.
+ *   - `signature` = hex-encoded 64-byte Ed25519 signature (128 hex chars).
+ *
+ * Connectivity ladder (§8 + §9):
+ *   - In-memory cache fresh (≤ server-advised TTL, clamped [60s, 24h]):
+ *     trust the cached floor; no refetch.
+ *   - Disk cache ≤24h: trust; permit operation.
+ *   - Disk cache 24h-7d: permit with warn.
+ *   - Disk cache >7d + backend unreachable: permit with warn.
+ *   - Below-floor + backend unreachable: BLOCK. The only intentional
+ *     offline lockout: the user had time to upgrade and didn't.
+ */
+declare const MIN_VERSION_ENDPOINT = "/v1/clients/min-version";
+/** Client-id surface for the SDK: matches the floor doc's `alter-identity` key. */
+declare const CLIENT_ID = "alter-identity";
+/** Channel: SDK installs are always via npm. */
+declare const CLIENT_CHANNEL = "npm";
+/**
+ * Compute the 8-char `key_id` for an Ed25519 public key (SPKI PEM).
+ *
+ * Matches the backend `key_id_for_public_key(pub)` in
+ * `backend/app/core/floor_signing.py`:
+ *   raw = pub.public_bytes(Encoding.Raw, PublicFormat.Raw)  # 32 bytes
+ *   sha256(raw).hexdigest()[:8]
+ *
+ * Node equivalent: import PEM -> export JWK -> decode `.x` (base64url) -> 32-byte
+ * raw public key -> SHA-256 -> first 8 hex chars.
+ *
+ * Returns `"00000000"` for empty input (sentinel, matches Phase 1 parity).
+ */
+declare function computeKeyId(publicKeyPem: string): string;
+/**
+ * Canonical JSON encoding matching Python's
+ * `json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`.
+ * Object keys are sorted lexicographically AT EVERY DEPTH; whitespace is
+ * stripped via the `,`/`:` separators; non-ASCII passes through as raw UTF-8
+ * (Node's `JSON.stringify` never `\uXXXX`-escapes non-ASCII, matching the
+ * backend's `ensure_ascii=False`). The result is the byte-exact input to
+ * Ed25519 signing (backend) and verification (this SDK and alter-cli) on
+ * both sides.
+ */
+declare function canonicalJson(obj: unknown): string;
+/**
+ * Known Ed25519 public keys (SPKI PEM) keyed by `key_id`.
+ *
+ * `key_id` = first 8 hex chars of SHA-256(raw 32-byte Ed25519 public key).
+ * Use `computeKeyId(spkiPem)` to re-derive and validate the map key.
+ *
+ * Backend may rotate via D-MSG11 dual-key path: clients keep N keys and
+ * select via `key_id`. Add new keys additively; remove old keys only after
+ * all deployed clients have received the new key.
+ *
+ * Current keys (mirrors `KNOWN_FLOOR_PUBLIC_KEYS` in the canonical
+ * `alter-cli` client):
+ *   8aa59e05: dev/non-prod key (local + e2e + staging). Safe to ship publicly;
+ *              this is the PUBLIC key only, never the private key.
+ *   640f7d9a: prod key. Added 2026-06-05. key_id = first 8 hex of
+ *              SHA-256(raw 32-byte Ed25519 pubkey), verified against the live
+ *              /api/v1/clients/min-version response on 2026-06-05. The prod
+ *              private key is a deliberately-minted Fly-secret keypair; only
+ *              the public half is shipped here.
+ *
+ * Consumers can override via {@link CheckMinVersionOptions.knownFloorPublicKeys}
+ * for tests or staging environments with a non-default keypair.
+ */
+declare const KNOWN_FLOOR_PUBLIC_KEYS: Record<string, string>;
+/**
+ * The canonical `client_below_floor` envelope shape. Identical across
+ * HTTP 426, MCP `tools/call` error, WebSocket close-4426 reason, and the
+ * CLI stdout JSON path. `BelowFloorError` preserves every field as
+ * an enumerable property so consumers can introspect without parsing the
+ * `cause` chain.
+ */
+interface ClientBelowFloorEnvelope {
+    error: {
+        code: 'client_below_floor';
+        message: string;
+        client_version: string;
+        min_version: string;
+        upgrade_cmd: string;
+        channel: string;
+    };
+}
+interface ChannelFloor {
+    min_version: string;
+    upgrade_cmd: string;
+}
+interface FloorDocument {
+    floors: Record<string, ChannelFloor | Record<string, ChannelFloor>>;
+    served_at: string;
+    cache_ttl_seconds: number;
+    signature: string;
+    key_id: string;
+}
+interface CheckMinVersionOptions {
+    /** API base. Defaults to `ALTER_API` env var, else `https://api.truealter.com`. */
+    apiBase?: string;
+    /** Override the SDK's own version (tests). */
+    clientVersion?: string;
+    /** Override the client-id surface (tests). */
+    clientId?: string;
+    /** Override the channel (tests). */
+    channel?: string;
+    /**
+     * Override the `key_id -> SPKI-PEM` Ed25519 public-key map consulted
+     * when verifying the floor document's signature. Defaults to
+     * {@link KNOWN_FLOOR_PUBLIC_KEYS}.
+     */
+    knownFloorPublicKeys?: Record<string, string>;
+    /** Override fetch: defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Disk cache path override (tests). Set `null` to disable disk cache. */
+    diskCachePath?: string | null;
+    /** Internal: clock injection for tests. */
+    now?: () => number;
+}
+/**
+ * Outcome of a preflight check. Use `BelowFloorError` instead of
+ * inspecting this manually: `checkMinVersion()` throws on below-floor.
+ */
+interface PreflightResult {
+    ok: true;
+    /** Resolved floor for `(client_id, channel)`, when one exists. */
+    floor: ChannelFloor | null;
+    /** Warning emitted when cache is stale or fetch failed. */
+    warn?: string;
+    /** Diagnostic tag: which branch of the ladder fired. */
+    diagnostic: string;
+}
+/**
+ * Thrown by {@link checkMinVersion} (and consequently by every
+ * `AlterClient` method, on first request) when the running SDK version
+ * is below the published floor for `alter-identity`.
+ *
+ * The canonical envelope shape is preserved as enumerable properties so
+ * consumers can branch on the upgrade command without re-parsing the
+ * server response:
+ *
+ * ```ts
+ * try {
+ *   await client.helloAgent();
+ * } catch (err) {
+ *   if (err instanceof BelowFloorError) {
+ *     console.error(`upgrade required: ${err.upgrade_cmd}`);
+ *     process.exit(1);
+ *   }
+ *   throw err;
+ * }
+ * ```
+ *
+ * The server-side gate is the authoritative reject: even if a consumer
+ * catches and swallows this error, the next backend request will still
+ * receive HTTP 426 from the floor middleware.
+ */
+declare class BelowFloorError extends Error {
+    readonly name = "BelowFloorError";
+    readonly code: "client_below_floor";
+    readonly client_version: string;
+    readonly min_version: string;
+    readonly upgrade_cmd: string;
+    readonly channel: string;
+    readonly envelope: ClientBelowFloorEnvelope;
+    constructor(envelope: ClientBelowFloorEnvelope);
+}
+/**
+ * Preflight the floor endpoint and compare the SDK's version against
+ * the published `min_version` for `alter-identity`. Throws
+ * {@link BelowFloorError} on below-floor; resolves with a
+ * {@link PreflightResult} otherwise.
+ *
+ * Cache behaviour:
+ *   - In-memory cache is consulted first; hits avoid the network.
+ *   - On a miss, the disk cache (`~/.config/alter/floor-cache.json`) is
+ *     read. If it's <24h old it satisfies the request directly; older
+ *     entries trigger a refetch.
+ *   - On a successful fetch, both caches are populated.
+ *   - On a fetch failure with a stale-but-present disk cache, the
+ *     cached verdict bites (including blocking when below-floor: §9).
+ *   - On a fetch failure with no cache at all, the call permits with a
+ *     warn: the server-side gate catches below-floor regardless.
+ */
+declare function checkMinVersion(opts?: CheckMinVersionOptions): Promise<PreflightResult>;
+/**
+ * Strict semver compare. Returns <0 if a<b, 0 if equal, >0 if a>b.
+ * Pre-release tags sort before their release counterpart per semver.
+ */
+declare function compareSemver(a: string, b: string): number;
+/**
+ * Verify the floor document's Ed25519 signature. Returns true on valid sig,
+ * false on invalid signature or unknown `key_id`. The signed payload is the
+ * canonical JSON of `{ floors, served_at }`: `signature` + `key_id` +
+ * `cache_ttl_seconds` are excluded from the signed bytes.
+ *
+ * MUST stay byte-compatible with the backend (`backend/app/core/floor_signing.py`):
+ *   - Algorithm: Ed25519 (RFC 8032). Deterministic: same key + payload = same sig.
+ *   - Payload: `canonicalJson({floors, served_at})`: sorted-keys + compact.
+ *   - `key_id`: first 8 hex chars of SHA-256(raw 32-byte Ed25519 public key).
+ *   - `signature`: hex-encoded 64-byte Ed25519 signature.
+ *
+ * The `keys` parameter maps `key_id -> SPKI PEM string`; defaults to
+ * `KNOWN_FLOOR_PUBLIC_KEYS`. Returns false on unknown key_id (triggers refetch
+ * per D-MSG11 rotation path).
+ */
+declare function verifyFloorSignature(doc: FloorDocument, keys?: Record<string, string>): boolean;
+
 interface McpServerConfig {
     url: string;
     transport: 'streamable-http';
@@ -1469,7 +1765,7 @@ declare function generateCursorConfig(opts?: GenerateMcpConfigOptions): GenericM
 /**
  * Claude Desktop MCP config helper.
  *
- * Claude Desktop speaks stdio only — it does not currently dial
+ * Claude Desktop speaks stdio only: it does not currently dial
  * Streamable-HTTP MCP servers directly. The canonical bridge is our
  * own `alter-mcp-bridge` binary, which is published alongside this CLI
  * in the same npm package. Desktop hosts then spawn the bridge as a
@@ -1528,7 +1824,7 @@ declare const ALL_CLIENTS: readonly ClientPaths[];
  *   - claude-desktop: platform config directory exists
  *   - vscode        : VS Code user data directory exists
  *
- * The probe is deliberately permissive — "the config directory exists"
+ * The probe is deliberately permissive: "the config directory exists"
  * means either the app is installed or was recently installed. Wire
  * will still refuse if the config file ends up on a synced volume.
  */
@@ -1536,9 +1832,9 @@ declare const ALL_CLIENTS: readonly ClientPaths[];
 interface ProbeResult {
     client: ClientPaths;
     installed: boolean;
-    /** Only present for claude-code — records `claude --version` output when resolvable. */
+    /** Only present for claude-code: records `claude --version` output when resolvable. */
     version?: string;
-    /** Diagnostic trail — why we said installed/not. */
+    /** Diagnostic trail: why we said installed/not. */
     reason: string;
 }
 declare function probeClaudeCode(): ProbeResult;
@@ -1554,7 +1850,7 @@ declare function probeAll(): ProbeResult[];
  * post) to make the operation auditable.
  *
  * Append-only semantics: a new wire run rewrites this file in full.
- * Prior state is not retained — the backup siblings on disk are the
+ * Prior state is not retained: the backup siblings on disk are the
  * canonical rollback surface, not this file.
  */
 
@@ -1598,7 +1894,7 @@ declare function writeWireState(state: WireState): void;
  * Writing MCP config under iCloud / OneDrive / Dropbox / Google Drive
  * silently propagates the same `mcpServers.alter` entry (and API key
  * headers) to every other device the user syncs. That is a consent
- * violation — wire consent is per-device.
+ * violation: wire consent is per-device.
  *
  * The check is a prefix match against the resolved absolute path; it
  * is deliberately broader than strictly necessary so that users who
@@ -1628,7 +1924,7 @@ declare function sha256(bytes: string | Buffer): string;
  * structured report. `unwire()` reads that artefact and reverses
  * every target.
  *
- * Synchronous throughout — the CLI path is sequential and the
+ * Synchronous throughout: the CLI path is sequential and the
  * deterministic ordering is worth the tiny blocking cost.
  */
 
@@ -1664,7 +1960,44 @@ interface UnwireReport {
 declare function unwire(): UnwireReport;
 
 /**
- * @truealter/sdk — alter_homepage MCP tool types
+ * GENERATED: DO NOT EDIT BY HAND. The SDK's compiled mirror of ALTER's live
+ * MCP pricing surface: advertised tool counts, per-invocation tiers, and
+ * per-invocation pricing.
+ *
+ * Regenerate via the SDK freshness gate. A freshness check runs at publish
+ * time and fails if this file diverges from the live pricing surface.
+ *
+ * Canonical source of truth for x402 pricing and advertised tool counts inside
+ * the SDK. Consumers should import from "@truealter/sdk" (re-exported via
+ * index.ts), not from this module directly.
+ */
+/** Tool tier per invocation (0=free / L0, 1=L1, 2=L2, 3=L3, 4=L4, 5=L5). */
+declare const GENERATED_TOOL_TIERS: Record<string, number>;
+/** Price in USD per tool invocation. Mirrors the live MCP pricing surface. */
+declare const GENERATED_TOOL_PRICING: Record<string, number>;
+/** Flat price per tier in USD. L0 is always free. */
+declare const TIER_PRICES: Record<string, number>;
+/** Publicly advertised tool counts. Mirrors canonical-facts.json public_advertised. */
+declare const ADVERTISED_TOOL_COUNTS: {
+    /** Free (L0) tools visible to anonymous / agent-class callers. */
+    readonly free: 26;
+    /** Premium (L1-L5) tools requiring x402 payment. */
+    readonly premium: 8;
+    /** Messaging tools (member-self-only; excluded from external advertisement). */
+    readonly messaging: 0;
+    /** Total publicly advertised (free + premium). */
+    readonly total: 34;
+};
+/** x402 settlement revenue split. Weaver = the data subject earning Identity Income. */
+declare const REVENUE_SPLIT: {
+    readonly weaver: 0.75;
+    readonly facilitator: 0.05;
+    readonly alter: 0.15;
+    readonly treasury: 0.05;
+};
+
+/**
+ * @truealter/sdk: alter_homepage MCP tool types
  *
  * Wire-format types for the user-authored, externally-queryable identity
  * homepage surface.
@@ -1692,7 +2025,7 @@ type HomepageFieldProvenance = "declared" | "derived" | "attested";
 /**
  * One field of a HomepageManifest. Every field carries its provenance
  * class so MCP consumers can render appropriately. The `value` shape is
- * field-specific — this is a discriminated parent; consumers should
+ * field-specific: this is a discriminated parent; consumers should
  * narrow on the manifest's field name, not on `value`'s runtime shape.
  */
 interface HomepageField<T = unknown> {
@@ -1709,7 +2042,7 @@ interface HomepageField<T = unknown> {
 /**
  * The wire-format manifest returned by `alter_homepage(handle)`.
  *
- * Fields are individually optional — a HomepageManifest with only a
+ * Fields are individually optional: a HomepageManifest with only a
  * handle and an opener is valid. MCP consumers MUST NOT assume any
  * field other than `handle` is present.
  */
@@ -1731,14 +2064,24 @@ interface HomepageManifest {
     opener?: HomepageField<string>;
     /**
      * Composed-glyph string (from typed primitives). The
-     * sigil is a string of renderer-recognised primitive references —
-     * not raw glyph codes — so different consumers can render the same
+     * sigil is a string of renderer-recognised primitive references:
+     * not raw glyph codes: so different consumers can render the same
      * sigil distinctly. Provenance is `declared` for user-composed,
      * `derived` for sigil-from-thread-graph crystallisation.
      */
     sigil?: HomepageField<string>;
     /** User's pronouns (already-shipped surface). Always declared. */
     pronouns?: HomepageField<string>;
+    /**
+     * User-authored contact email, surfaced so a verified caller reading
+     * the homepage can reach the holder. Maximum 254 chars (RFC 5321
+     * envelope limit) after NFC normalisation. Always declared-provenance
+     *: the user wrote it into their config; it is NOT the account's
+     * verified login email (that lives encrypted server-side and is never
+     * surfaced here). A holder who sets no `contact_email` simply omits
+     * the field.
+     */
+    contact_email?: HomepageField<string>;
     /**
      * List of recognised Seat glyphs the holder is bound to. Provenance
      * is always `attested` (ceremony-attested, server-side resolved);
@@ -1756,7 +2099,7 @@ interface HomepageManifest {
     /**
      * Optional, opt-in per query context. Coarse Golden-Thread summary;
      * provenance is `derived`. MCP consumers MUST NOT request this field
-     * by default — only on explicit per-call consent. Consumers in the
+     * by default: only on explicit per-call consent. Consumers in the
      * workplace/education vertical MUST NOT request this field at all
      * (clause-4 caller-context gate).
      */
@@ -1766,6 +2109,14 @@ interface HomepageManifest {
      * Consumers are free to ignore. Provenance is always `declared`.
      */
     render_hints?: HomepageField<Record<string, unknown>>;
+    /**
+     * Reserved inner-face slot. NEVER populated on a HomepageManifest returned
+     * by `alter_homepage`: the homepage is the outward-facing identity surface,
+     * and the inside face is held empty by construction. The field exists only
+     * so consumers and forward-compatible schemas can name the slot; a manifest
+     * carrying a value here is malformed and consumers MUST ignore it.
+     */
+    reserved_inner?: never;
 }
 /**
  * Input arguments for the `alter_homepage` MCP tool.
@@ -1780,7 +2131,7 @@ interface HomepageInput {
     /**
      * Optional whitelist of field names. If omitted, the server returns
      * all fields the caller is permitted to read. Unknown field names
-     * are silently ignored (forward-compatible — adding a new field does
+     * are silently ignored (forward-compatible: adding a new field does
      * not break old consumers).
      */
     fields?: readonly (keyof HomepageManifest)[];
@@ -1820,10 +2171,11 @@ declare const HOMEPAGE_LIMITS: {
     readonly opener_max_chars: 280;
     readonly pronouns_max_chars: 32;
     readonly attunement_glyph_max_chars: 16;
+    readonly contact_email_max_chars: 254;
 };
 
 /**
- * @truealter/sdk — theme pack types
+ * @truealter/sdk: theme pack types
  *
  * Wire-format types for ALTER theme packs and `themes.lock` composition
  * manifests. The full specification lives in
@@ -1857,9 +2209,9 @@ interface ThemeMeta {
     author: string;
     /** ≤ 240 characters after NFC. */
     description: string;
-    /** OPTIONAL — surfaced by curated resolvers; not rendered by ALTER. */
+    /** OPTIONAL: surfaced by curated resolvers; not rendered by ALTER. */
     repo?: string;
-    /** OPTIONAL — surfaced by curated resolvers; not rendered by ALTER. */
+    /** OPTIONAL: surfaced by curated resolvers; not rendered by ALTER. */
     docs_url?: string;
 }
 /** `[palette]` section. Renderer enforces gamut; out-of-gamut packs are rejected. */
@@ -1893,7 +2245,7 @@ interface ThemeRenderHints {
 }
 /** `[assets]` section. Paths MUST be repo-relative without `..` segments. */
 interface ThemeAssets {
-    /** Optional — if omitted, no assets are loaded. */
+    /** Optional: if omitted, no assets are loaded. */
     glyphs?: readonly string[];
 }
 /**
@@ -1943,7 +2295,7 @@ interface ThemeLockEntry {
 }
 /**
  * The user-side composition manifest. This is the publishable artefact
- * — what someone shares when they say "here is my ALTER".
+ *: what someone shares when they say "here is my ALTER".
  *
  * Re-applying the same lockfile against the same renderer version MUST
  * produce a bit-identical render, modulo the `attunement_glyph` field
@@ -1951,7 +2303,7 @@ interface ThemeLockEntry {
  */
 interface ThemesLockV1 {
     schema_version: 1;
-    /** e.g. "alter-cli/0.5.0" — informational, not load-bearing. */
+    /** e.g. "alter-cli/0.5.0", informational only. */
     generated_by: string;
     /** RFC 3339 UTC timestamp at lockfile-write time. */
     generated_at: string;
@@ -2003,11 +2355,11 @@ declare const OSC8_ALLOWED_SCHEMES: readonly ["https:", "mailto:"];
 type Osc8AllowedScheme = (typeof OSC8_ALLOWED_SCHEMES)[number];
 
 /**
- * Package metadata — kept in a standalone module so deep imports from
+ * Package metadata: kept in a standalone module so deep imports from
  * `src/wire/` can reference version constants without creating a
  * circular dependency through `src/index.ts`.
  */
 declare const SDK_NAME = "@truealter/sdk";
-declare const SDK_VERSION = "0.3.0";
+declare const SDK_VERSION: string;
 
-export { ALL_CLIENTS, AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, type AlterResolveHandleInput, type AlterResolveHandleOutput, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, CLAUDE_CODE, CLAUDE_DESKTOP, CURSOR, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type ClaudeDesktopConfig, type ClaudeDesktopServerConfig, type ClientId, type ClientPaths, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type GenerateClaudeDesktopOptions, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type GreetingRegister, HOMEPAGE_LIMITS, type HelloAgentInput, type HelloAgentOutput, type HomepageCallerVertical, type HomepageField, type HomepageFieldProvenance, type HomepageInput, type HomepageManifest, type HomepageOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type InvocationClaims, type JsonWebKey, type JwksDocument, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPSigningOptions, type MCPToolDefinition, MCP_PROTOCOL_VERSION, type MatchTier, type McpServerConfig, OSC8_ALLOWED_SCHEMES, type Osc8AllowedScheme, PREMIUM_TOOL_NAMES, type PaletteFloorV1, type PaletteText, type PanelDensity, type PaymentEnvelope, type ProbeResult, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, type RecommendToolInput, type RecommendToolOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SignInvocationOptions, type SignedToolDefinition, type StatusLineDensity, type StatusLineSlot, THEME_LIMITS, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThemeAssets, type ThemeLockEntry, type ThemeManifestV1, type ThemeMeta, type ThemeOpener, type ThemePalette, type ThemeRenderHints, type ThemeShareInput, type ThemeShareOutput, type ThemeSigil, type ThemeSignatureManifest, type ThemeStatusLine, type ThemesLockV1, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type UnwireReport, VSCODE, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, type WireOptions, type WireReport, type WireState, type WireTarget, type WireTargetCli, type WireTargetFile, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, canonicalArgsSha256, canonicalStringify, clearDiscoveryCache, decodeDid, detectSyncedVolume, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateClaudeDesktopConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, loadPrivateKey, parsePaymentHeader, probeAll, probeByDir, probeClaudeCode, readWireState, resolveVerifyAt, sha256, sign, signInvocation, unwire, verify, verifyProvenance, verifyToolSignatures, wire, writeWireState };
+export { ADVERTISED_TOOL_COUNTS, ALL_CLIENTS, AlterAuthError, AlterClient, type AlterClientOptions, AlterDiscoveryError, AlterError, type AlterErrorCode, AlterInvalidResponse, AlterNetworkError, AlterPaymentRequired, AlterProvenanceError, AlterRateLimited, type AlterResolveHandleInput, type AlterResolveHandleOutput, AlterTimeoutError, AlterToolError, type ApiKeyConfig, type Archetype, type AssessTraitsInput, type AssessTraitsOutput, type BeginGoldenThreadInput, type BeginGoldenThreadOutput, BelowFloorError, CLAUDE_CODE, CLAUDE_DESKTOP, CLIENT_CHANNEL, CLIENT_ID, CURSOR, type ChannelFloor, type CheckAssessmentStatusInput, type CheckAssessmentStatusOutput, type CheckGoldenThreadInput, type CheckGoldenThreadOutput, type CheckMinVersionOptions, type ClaudeDesktopConfig, type ClaudeDesktopServerConfig, type ClientBelowFloorEnvelope, type ClientId, type ClientPaths, type CompleteKnotInput, type CompleteKnotOutput, type ComputeBelongingInput, type ComputeBelongingOutput, DEFAULT_DOMAIN, DEFAULT_ENDPOINT, DEFAULT_VERIFY_AT_ALLOWLIST, type DiscoveryOptions, type DiscoveryResult, type Ed25519Keypair, type EngagementLevel, FREE_TOOL_NAMES, type FloorDocument, GENERATED_TOOL_PRICING, GENERATED_TOOL_TIERS, type GenerateClaudeDesktopOptions, type GenerateMatchNarrativeInput, type GenerateMatchNarrativeOutput, type GetAgentPortfolioInput, type GetAgentPortfolioOutput, type GetAgentTrustTierInput, type GetAgentTrustTierOutput, type GetCompetenciesInput, type GetCompetenciesOutput, type GetEarningSummaryInput, type GetEarningSummaryOutput, type GetEngagementLevelInput, type GetEngagementLevelOutput, type GetFullTraitVectorInput, type GetFullTraitVectorOutput, type GetIdentityEarningsInput, type GetIdentityEarningsOutput, type GetIdentityTrustScoreInput, type GetIdentityTrustScoreOutput, type GetMatchRecommendationsInput, type GetMatchRecommendationsOutput, type GetNetworkStatsInput, type GetNetworkStatsOutput, type GetPrivacyBudgetInput, type GetPrivacyBudgetOutput, type GetProfileInput, type GetProfileOutput, type GetSideQuestGraphInput, type GetSideQuestGraphOutput, type GetTraitSnapshotInput, type GetTraitSnapshotOutput, type GoldenThreadStatusInput, type GoldenThreadStatusOutput, type GreetingRegister, HOMEPAGE_LIMITS, type HelloAgentInput, type HelloAgentOutput, type HomepageCallerVertical, type HomepageField, type HomepageFieldProvenance, type HomepageInput, type HomepageManifest, type HomepageOutput, type InitiateAssessmentInput, type InitiateAssessmentOutput, type InvocationClaims, type JsonWebKey, type JwksDocument, KNOWN_FLOOR_PUBLIC_KEYS, type ListArchetypesInput, type ListArchetypesOutput, type MCPCallOptions, type MCPCallToolResult, MCPClient, type MCPClientInfo, type MCPClientOptions, type MCPContentBlock, type MCPListToolsResult, type MCPMeta, type MCPResponse, type MCPSigningOptions, type MCPToolDefinition, MCP_PROTOCOL_VERSION, MIN_VERSION_ENDPOINT, type MatchTier, type McpServerConfig, OSC8_ALLOWED_SCHEMES, type Osc8AllowedScheme, PREMIUM_TOOL_NAMES, type PaletteFloorV1, type PaletteText, type PanelDensity, type PaymentEnvelope, type PreflightResult, type ProbeResult, type ProvenanceEnvelope, type ProvenancePayload, type ProvenanceToken, type ProvenanceVerification, type QueryGraphSimilarityInput, type QueryGraphSimilarityOutput, type QueryMatchesInput, type QueryMatchesOutput, REVENUE_SPLIT, type RecommendToolInput, type RecommendToolOutput, SDK_NAME, SDK_VERSION, type SearchIdentitiesInput, type SearchIdentitiesOutput, type SignInvocationOptions, type SignedToolDefinition, type StatusLineDensity, type StatusLineSlot, THEME_LIMITS, TIER_PRICES, TOOL_BLAST_RADIUS, TOOL_COSTS, TOOL_TIERS, type ThemeAssets, type ThemeLockEntry, type ThemeManifestV1, type ThemeMeta, type ThemeOpener, type ThemePalette, type ThemeRenderHints, type ThemeShareInput, type ThemeShareOutput, type ThemeSigil, type ThemeSignatureManifest, type ThemeStatusLine, type ThemesLockV1, type ThreadCensusInput, type ThreadCensusOutput, type ToolInputs, type ToolName, type ToolOutputs, type ToolSignatureMap, type UnwireReport, VSCODE, type VerifyIdentityInput, type VerifyIdentityOutput, type VerifyProvenanceOptions, type WireOptions, type WireReport, type WireState, type WireTarget, type WireTargetCli, type WireTargetFile, X402Client, type X402ClientOptions, type X402Settlement, type X402Signer, base64urlDecode, base64urlEncode, canonicalArgsSha256, canonicalJson, canonicalStringify, checkMinVersion, clearDiscoveryCache, compareSemver, computeKeyId, decodeDid, detectSyncedVolume, discover, encodeDid, fetchPublicKeys, generateClaudeConfig, generateClaudeDesktopConfig, generateCursorConfig, generateGenericMcpConfig, generateKeypair, keypairFromPrivateKey, loadPrivateKey, parsePaymentHeader, probeAll, probeByDir, probeClaudeCode, readWireState, resolveVerifyAt, sha256, sign, signInvocation, unwire, verify, verifyFloorSignature, verifyProvenance, verifyToolSignatures, wire, writeWireState };