@gajae-code/coding-agent 0.12.21 → 0.13.0

package/dist/types/sdk/elevation/grant-ledger.d.ts

@@ -0,0 +1,163 @@
+import { SDK_STATE_VERSION } from "../broker/state-version";
+import { type ElevationOperation } from "./digest";
+import { type ElevationAnswerAuthority, type ElevationClaimIdentity, type ElevationDispatchOutcome, type ElevationDispatchReceipt } from "./dispatch-receipt";
+import { type BrokerOwnerPrincipal, classifyProcessIncarnationLiveness } from "./owner";
+/**
+ * Broker-owned elevation grant ledger.
+ *
+ * Durable state machine (per elevation request):
+ * `requested -> granted -> claimed -> dispatched(outcome)`; terminal
+ * `denied`/`expired`/`misused`/`target_unavailable`; crash truth
+ * `consumed` (claimed but outcome unknown). Grants are single-use: the claim
+ * CAS consumes the grant before dispatch, and a crash between consume and
+ * dispatch is replayed truthfully as `consumed` with outcome `unknown`
+ * (retry requires a new grant — fail closed).
+ *
+ * All mutations and reads serialize on one elevation-local
+ * `withFileLock` transaction covering grants (`grants.jsonl`), dispatch
+ * receipts (`receipts.jsonl`), the issue index (`index.json`), and the
+ * audit trail (`audit.jsonl`), so a claim, its receipt, and the issue
+ * sequence commit together.
+ *
+ * The answer boundary is internal operator-only: there is no public
+ * `elevation.answer` operation; answers are admitted only from the internal
+ * operator attestation, so requester self-approval is impossible by
+ * construction.
+ */
+export type ElevationGrantState = "requested" | "granted" | "claimed" | "dispatched" | "consumed" | "denied" | "expired" | "misused" | "target_unavailable";
+export interface ElevationSessionIdentity {
+    sessionId: string;
+    /** Exact endpoint state root bound at issue time; never the repo root. */
+    endpointStateRoot: string;
+    endpointGeneration: number;
+    endpointIncarnation: string;
+}
+/** Audit-only requester binding; never an identity claim. */
+export interface ElevationRequester {
+    source: "broker_connection";
+    connectionId: string;
+}
+export interface ElevationGrantRecord {
+    version: typeof SDK_STATE_VERSION;
+    /** Durable correlation ID; UUID, path-safe. */
+    elevationRequestId: string;
+    /** Monotonic path-safe issue sequence, allocated under the ledger lock. */
+    issueIndex: number;
+    state: ElevationGrantState;
+    operation: ElevationOperation;
+    requestDigest: string;
+    sessionIdentity: ElevationSessionIdentity;
+    principal: BrokerOwnerPrincipal;
+    requester: ElevationRequester;
+    requestedAt: number;
+    expiresAt: number;
+    outcome?: ElevationDispatchOutcome;
+    ts: number;
+}
+export type ElevationErrorCode = "not_found" | "invalid_input" | "idempotency_conflict" | "grant_spent" | "elevation_claim_in_progress" | "elevation_required" | "elevation_unavailable" | "elevation_not_required" | "endpoint_stale" | "target_unavailable" | "expired" | "misused" | "duplicate_answer" | "terminal_uncertain" | (string & {});
+export type ElevationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: ElevationErrorCode;
+        message: string;
+    };
+};
+export interface ElevationIssueParams {
+    /** Optional caller-supplied correlation ID for idempotent retry; the broker generates a UUID otherwise. */
+    elevationRequestId?: string;
+    operation: ElevationOperation;
+    input: Record<string, unknown>;
+    sessionIdentity: ElevationSessionIdentity;
+    principal: BrokerOwnerPrincipal;
+    requester: ElevationRequester;
+    expiresInMs?: number;
+}
+export interface ElevationIssueValue {
+    replay: boolean;
+    elevationRequestId: string;
+    issueIndex: number;
+    requestDigest: string;
+    state: ElevationGrantState;
+    requestedAt: number;
+    expiresAt: number;
+    grant: ElevationGrantRecord;
+}
+export interface ElevationAnswerParams {
+    elevationRequestId: string;
+    answer: "approve" | "deny";
+    /** Digest the answering surface presented from the gate payload. */
+    presentedDigest: string;
+    /** Broker-owner principal attesting the answer authority. */
+    principal: BrokerOwnerPrincipal;
+    answerer: ElevationAnswerAuthority;
+    /** Current broker-resolved target identity; undefined means the session is unreachable. */
+    currentSessionIdentity?: ElevationSessionIdentity;
+}
+export type ElevationAnswerOutcome = "granted" | "denied" | "expired" | "misused" | "target_unavailable" | "duplicate_answer";
+export interface ElevationAnswerValue {
+    outcome: ElevationAnswerOutcome;
+    grant: ElevationGrantRecord;
+}
+export interface ElevationClaimParams {
+    elevationRequestId: string;
+    claimIdentity: ElevationClaimIdentity;
+    /** Current broker-resolved target identity; undefined means the session is unreachable. */
+    currentSessionIdentity?: ElevationSessionIdentity;
+}
+export interface ElevationClaimValue {
+    grant: ElevationGrantRecord;
+    receipt: ElevationDispatchReceipt;
+}
+export interface ElevationDispatchParams {
+    elevationRequestId: string;
+    dispatchIdentity: ElevationClaimIdentity;
+    outcome: ElevationDispatchOutcome;
+}
+export interface ElevationDispatchValue {
+    grant: ElevationGrantRecord;
+    receipt: ElevationDispatchReceipt;
+}
+export interface ElevationReadValue {
+    grant: ElevationGrantRecord;
+    receipt?: ElevationDispatchReceipt;
+}
+export interface ElevationListValue {
+    grants: ElevationReadValue[];
+}
+export interface ElevationLedgerOptions {
+    /** Defaults to the GJC_SDK_ELEVATION_ENABLED environment flag. */
+    enabled?: boolean;
+    /** Request lifetime before the grant expires. */
+    ttlMs?: number;
+    /** Injectable clock. */
+    now?: () => number;
+    /**
+     * Injectable tri-state process-incarnation liveness classifier (defaults to
+     * `classifyProcessIncarnationLiveness`). Test seam for crash-state replay:
+     * "unknown" must always fail closed as `elevation_claim_in_progress`.
+     */
+    classifyLiveness?: typeof classifyProcessIncarnationLiveness;
+}
+declare function isElevationOperation(value: unknown): value is ElevationOperation;
+declare function isElevationGrantRecord(value: unknown): value is ElevationGrantRecord;
+export declare class ElevationLedger {
+    #private;
+    constructor(agentDir: string, options?: ElevationLedgerOptions);
+    get warnings(): readonly string[];
+    open(): Promise<this>;
+    assertSupportedStateVersions(): Promise<void>;
+    issue(params: ElevationIssueParams): Promise<ElevationResult<ElevationIssueValue>>;
+    answer(params: ElevationAnswerParams): Promise<ElevationResult<ElevationAnswerValue>>;
+    claim(params: ElevationClaimParams): Promise<ElevationResult<ElevationClaimValue>>;
+    dispatch(params: ElevationDispatchParams): Promise<ElevationResult<ElevationDispatchValue>>;
+    /** Pure read without reconciliation writes; used before actions. */
+    get(elevationRequestId: string): Promise<ElevationResult<ElevationReadValue>>;
+    /** Truthful read: reconciles expiry and crash-state claims before returning. */
+    resolve(elevationRequestId: string, claimIdentity: ElevationClaimIdentity): Promise<ElevationResult<ElevationReadValue>>;
+    /** Truthful listing: reconciles every grant before returning. */
+    list(claimIdentity: ElevationClaimIdentity): Promise<ElevationResult<ElevationListValue>>;
+}
+export { isElevationGrantRecord, isElevationOperation };

package/dist/types/sdk/elevation/owner.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Broker-owner principal.
+ *
+ * The elevation authority is the broker itself under the existing loopback
+ * trust model: one local OS-user/broker authority derived entirely from
+ * broker-owned state, never from caller input. `agentDirUid` is the uid that
+ * owns the agent directory, `brokerPid`/`brokerIncarnation` identify the
+ * broker process tenure so a restarted broker cannot attest the same
+ * authority.
+ */
+export interface BrokerOwnerPrincipal {
+    kind: "broker_owner";
+    owner: {
+        agentDirUid: number;
+        brokerPid: number;
+        brokerIncarnation: string;
+    };
+}
+export declare function isBrokerOwnerPrincipal(value: unknown): value is BrokerOwnerPrincipal;
+export declare function sameBrokerOwnerPrincipal(left: BrokerOwnerPrincipal, right: BrokerOwnerPrincipal): boolean;
+/**
+ * Reads the broker-owner principal from broker-owned state. Throws when the
+ * broker cannot attest a canonical process incarnation (the broker refuses to
+ * start in that case anyway), so callers treat a throw as "authority
+ * unavailable".
+ */
+export declare function readBrokerOwnerPrincipal(agentDir: string, brokerPid: number, brokerIncarnation: string): Promise<BrokerOwnerPrincipal>;
+export type ProcessIncarnationLiveness = "alive" | "dead" | "unknown";
+/**
+ * Tri-state liveness of a process incarnation.
+ *
+ * - `alive`: the pid is running and its current incarnation matches the
+ *   stored one, so the original process tenure is still live.
+ * - `dead`: ESRCH (the pid is provably gone — independent of any persisted
+ *   incarnation text), or the pid is running under a *different* canonical
+ *   incarnation (PID reuse), which provably means the original process
+ *   ended.
+ * - `unknown`: the pid is malformed, the persisted or observed incarnation
+ *   is malformed/undefined, or the current incarnation cannot be read.
+ *   Unknown never implies death: elevation claims must fail closed with
+ *   `elevation_claim_in_progress` instead of terminalizing state on
+ *   unprovable liveness.
+ *
+ * ESRCH is independent positive death proof: a pid that provably does not
+ * exist is dead regardless of the persisted incarnation text, so a corrupt
+ * persisted incarnation can never stall recovery forever.
+ */
+export declare function classifyProcessIncarnationLiveness(pid: unknown, incarnation: unknown): ProcessIncarnationLiveness;

package/dist/types/sdk/guides/cache.d.ts

@@ -0,0 +1,98 @@
+import { SDK_STATE_VERSION } from "../broker/state-version";
+import { type GuideEntryV1, type GuideManifestV1 } from "./manifest";
+import { type GuideVerificationErrorCode } from "./verify";
+/**
+ * Verified on-disk cache for trusted advisory guides.
+ *
+ * Layout under `<agentDir>/sdk/guides/cache/` (mode 0700):
+ *   meta.json — atomic commit pointer {version, manifestId, sequence, generation, installedAt}
+ *   meta.json.lock — cross-process install lock (project `withFileLock` convention)
+ *   generations/<generation>/manifest.json — canonical manifest bytes
+ *   generations/<generation>/manifest.sig — detached Ed25519 signature
+ *   generations/<generation>/guides/<sha256> — immutable advisory text
+ *
+ * A complete generation is written and fsynced before `meta.json` is atomically
+ * replaced under the install lock. Readers follow only the committed
+ * generation, so an interrupted install cannot expose a new manifest with
+ * stale metadata or disturb the previously valid cache.
+ */
+export interface GuideCacheMetaV1 {
+    version: typeof SDK_STATE_VERSION;
+    manifestId: string;
+    sequence: number;
+    installedAt: number;
+    generation: string;
+}
+export interface GuideCacheGuideV1 {
+    id: string;
+    title: string;
+    sha256: string;
+    text: string;
+}
+export interface VerifiedGuideCache {
+    manifest: GuideManifestV1;
+    signatureBytes: Uint8Array;
+    meta: GuideCacheMetaV1;
+    guides: GuideCacheGuideV1[];
+}
+export type GuideCacheReadResult = {
+    ok: true;
+    value: VerifiedGuideCache;
+} | {
+    ok: false;
+    error: {
+        code: "missing_cache" | "corrupt_cache" | "expired_cache" | "unsupported_state_version";
+        message: string;
+    };
+};
+export type GuideCacheInstallResult = {
+    ok: true;
+    value: VerifiedGuideCache;
+} | {
+    ok: false;
+    error: {
+        code: GuideVerificationErrorCode | "invalid_input" | "io_error";
+        message: string;
+    };
+};
+export declare function guideCacheDir(agentDir: string): string;
+/**
+ * Reads and re-verifies the cache end to end: manifest parse, meta commit
+ * record, detached signature, expiry against `now`, and every advisory hash.
+ * Any failure is reported as `corrupt_cache` (or `expired_cache` when the
+ * signature is valid but stale) and the cache is left untouched — a corrupt
+ * entry never destroys the data a future, still-valid install may replace.
+ */
+export declare function readGuideCache(params: {
+    agentDir: string;
+    now: number;
+}): Promise<GuideCacheReadResult>;
+/**
+ * Installs a verified manifest plus its advisory content into the cache.
+ *
+ * Order of operations:
+ *   1. Verify the manifest signature, expiry, and every advisory hash before
+ *      any write — a tampered or expired payload never touches disk.
+ *   2. Under the cache's cross-process install lock, enforce the monotonic
+ *      version floor against the committed meta record (`rollback` when the
+ *      candidate does not advance the channel).
+ *   3. Write and fsync a complete immutable generation, then atomically replace
+ *      `meta.json` as the only commit pointer.
+ *
+ * Steps 2–3 are serialized with `<cacheDir>/meta.json.lock` (the project's
+ * `withFileLock` convention): the floor is re-read under the same lock that
+ * guards the commit pointer replacement, so a concurrent install can never
+ * read an older floor, observe a newer commit, and then downgrade the channel.
+ * Any failure aborts before the commit, leaving the prior valid cache fully
+ * intact and readable.
+ */
+export declare function installGuideCache(params: {
+    agentDir: string;
+    manifest: GuideManifestV1;
+    signatureBytes: Uint8Array;
+    advisories: readonly {
+        entry: GuideEntryV1;
+        text: Uint8Array;
+    }[];
+    now: number;
+}): Promise<GuideCacheInstallResult>;

package/dist/types/sdk/guides/catalog.d.ts

@@ -0,0 +1,156 @@
+import { type VerifiedGuideCache } from "./cache";
+import { type GuideManifestV1 } from "./manifest";
+/**
+ * HTTPS-only, allowlisted, credential-free fetch boundary for advisory guides.
+ *
+ * The catalog refuses any URL that is not https, whose host is not in the
+ * allowlist, whose path is outside the allowlisted prefix, or that carries
+ * userinfo. Every request uses `credentials: "omit"`, no authorization or
+ * cookie headers, and `redirect: "error"` so a redirect can never escape the
+ * allowlist. Responses are bounded by byte caps and a timeout. This boundary
+ * is the only network surface of the guide subsystem — advisories are fetched
+ * as data, verified against the signed manifest, and never executed.
+ */
+export interface GuideFetchAllowlistEntry {
+    host: string;
+    /** Every fetched path must start with this prefix. */
+    pathPrefix: string;
+}
+export declare const GUIDE_FETCH_ALLOWLIST: readonly GuideFetchAllowlistEntry[];
+export declare const GUIDE_FETCH_TIMEOUT_MS = 10000;
+export declare const GUIDE_FETCH_MAX_MANIFEST_BYTES: number;
+export declare const GUIDE_FETCH_MAX_SIGNATURE_BYTES = 1024;
+export declare const GUIDE_FETCH_USER_AGENT = "gajae-code-sdk-guides/1";
+export interface GuideFetchPolicy {
+    httpsOnly: true;
+    credentials: "omit";
+    redirect: "error";
+    allowlist: readonly GuideFetchAllowlistEntry[];
+    maxManifestBytes: number;
+    maxSignatureBytes: number;
+    timeoutMs: number;
+    userAgent: string;
+}
+export declare function guideFetchPolicy(): GuideFetchPolicy;
+/** True when a URL satisfies the HTTPS allowlist boundary. */
+export declare function isGuideFetchUrlAllowed(url: string): boolean;
+export type GuideFetchErrorCode = "fetch_forbidden" | "fetch_failed" | "oversize" | "timeout" | "network_error" | "invalid_manifest" | "unsupported_version" | (string & {});
+export interface GuideOnlineManifest {
+    url: string;
+    manifest: GuideManifestV1;
+    signatureBytes: Uint8Array;
+    fetchedAt: number;
+}
+export type GuideFetchResult = {
+    ok: true;
+    value: GuideOnlineManifest;
+} | {
+    ok: false;
+    error: {
+        code: GuideFetchErrorCode;
+        message: string;
+        status?: number;
+    };
+};
+/**
+ * Fetches the manifest at `url` and its detached signature at `<url>.sig`,
+ * bounded by the HTTPS allowlist policy. The manifest is parsed and shape
+ * validated here; signature verification and advisory hash checks happen in
+ * the caller so a rejected refresh can fall back to cache/bundled.
+ */
+export declare function fetchGuideManifestOnline(params: {
+    url: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    now?: number;
+}): Promise<GuideFetchResult>;
+/**
+ * Trusted-by-compilation bundled manifests. The seed manifest is signed by the
+ * bundled pinned key (`verify.ts`), and every bundled advisory ships its text
+ * so fresh-install `list`/`show` work offline with no cache. The seed is
+ * selected only when no valid online or cached manifest exists; because the
+ * bundled manifest is itself signature-verified at module load, bundling the
+ * signature here preserves the normal verify path for bundled content.
+ */
+export declare const BUNDLED_GUIDE_MANIFESTS: readonly GuideManifestV1[];
+export type GuideCatalogSource = "online" | "cache" | "bundled";
+export interface GuideCatalogGuideV1 {
+    id: string;
+    title: string;
+    sha256: string;
+    /** Advisory text; undefined when the bundled manifest does not ship content for this guide. */
+    text: string | undefined;
+}
+export interface GuideCatalogSelection {
+    source: GuideCatalogSource;
+    manifest: GuideManifestV1;
+    guides: GuideCatalogGuideV1[];
+    /** Present when the selection is served from (or was installed into) the verified cache. */
+    cache?: VerifiedGuideCache;
+    /** Online provenance. */
+    url?: string;
+    fetchedAt?: number;
+    /** Non-fatal provenance notes (e.g. an online refresh was rejected and selection fell back). */
+    warnings: string[];
+}
+export type GuideCatalogResult = {
+    ok: true;
+    value: GuideCatalogSelection;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export interface GuideCatalogOptions {
+    agentDir: string;
+    /** Online manifest URL; undefined disables the network entirely. */
+    onlineUrl?: string;
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    /** Trusted-by-compilation bundled manifests; defaults to `BUNDLED_GUIDE_MANIFESTS`. */
+    disableBundled?: boolean;
+}
+/**
+ * Advisory guide catalog service.
+ *
+ * Selection precedence is `valid online -> valid cache -> bundled`: a freshly
+ * fetched, verified manifest wins; otherwise the verified cache; otherwise the
+ * bundled seed. Verification failures never throw — they surface as warnings
+ * (for online) or as selection fallback, and the cache is never destroyed.
+ */
+export declare class GuideCatalog {
+    #private;
+    constructor(options: GuideCatalogOptions);
+    /**
+     * Fetches, verifies, and installs the online manifest when `onlineUrl` is
+     * configured, then selects per the online/cache/bundled precedence. The
+     * verified cache is always the source of advisory text for online and
+     * cached selections, so a single verified read path serves both.
+     */
+    refresh(): Promise<GuideCatalogResult>;
+    /** Offline selection: verified cache first, then bundled. Never touches the network. */
+    load(): Promise<GuideCatalogResult>;
+    /**
+     * Returns the advisory text for a guide in the currently selected
+     * manifest. Advisory text is data only: it is rendered and never executed
+     * or applied as configuration.
+     */
+    advisory(guideId: string): Promise<{
+        ok: true;
+        value: {
+            source: GuideCatalogSource;
+            guideId: string;
+            title: string;
+            text: string;
+        };
+    } | {
+        ok: false;
+        error: {
+            code: string;
+            message: string;
+        };
+    }>;
+}

package/dist/types/sdk/guides/cli.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `gjc sdk guides` command family (routing lives in `src/commands/sdk.ts`).
+ *
+ * Verbs:
+ *   refresh --url <https url>  fetch + verify the online manifest and advisory
+ *                              text, install the verified cache, report selection.
+ *                              Fails operationally (exit 1) whenever the online
+ *                              manifest is not selected: fallback cache/bundled
+ *                              content is reported as a failure, never as a
+ *                              successful refresh
+ *   list                       offline selection: verified cache, else bundled
+ *   show <guideId>             render the advisory text for one guide (data only)
+ *   status                     selection provenance, cache health, fetch policy
+ *   trust                      pinned key ids and the no-credential fetch boundary
+ *
+ * The subsystem is advisory-text only: it never executes guide content, never
+ * mutates configuration, and never accepts or emits credentials. The only
+ * state it writes is the verified guide cache during `refresh`.
+ */
+export type SdkGuidesCliAction = "refresh" | "list" | "show" | "status" | "trust";
+export interface SdkGuidesCliArgs {
+    action?: string;
+    /** Guide id for `show`. */
+    guideId?: string;
+    /** Online manifest URL for `refresh`; must satisfy the HTTPS allowlist. */
+    url?: string;
+    agentDir?: string;
+    /** Bounded fetch timeout for `refresh`. */
+    timeoutMs?: number;
+    /** Fetch implementation override for `refresh` (test seam); defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Runs the `gjc sdk guides` command family. Exported for command routing from
+ * `src/commands/sdk.ts` and for direct service use; the injected `write` /
+ * `setExitCode` hooks keep the surface testable without touching stdout or
+ * the process exit code.
+ */
+export declare function runSdkGuidesCli(args: SdkGuidesCliArgs, writeOutput?: (value: unknown) => void, setExitCode?: (exitCode: 1 | 2) => void): Promise<void>;

package/dist/types/sdk/guides/manifest.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Trusted advisory guide manifest: types, canonical encoding, and parsing.
+ *
+ * A manifest is a signed, time-boxed bundle of advisory guide bindings. Each
+ * entry binds a stable guide id to the SHA-256 digest of its advisory text, so
+ * the advisory content can be fetched separately and verified against the
+ * signed manifest. Manifests are advisory text only: they never carry
+ * instructions to execute or configuration to apply.
+ */
+export declare const GUIDES_MANIFEST_VERSION = 1;
+/** Maximum byte length of a single advisory text file. */
+export declare const GUIDE_ADVISORY_MAX_BYTES: number;
+/** Maximum number of guides bound by a single manifest. */
+export declare const GUIDE_MANIFEST_MAX_ENTRIES = 256;
+/** Maximum manifest JSON byte length (enforced at fetch and cache read time). */
+export declare const GUIDE_MANIFEST_MAX_BYTES: number;
+export declare const GUIDE_ID_MAX_LENGTH = 128;
+export declare const GUIDE_TITLE_MAX_LENGTH = 256;
+export interface GuideEntryV1 {
+    /** Path-safe, stable guide id, e.g. "troubleshooting/socket". */
+    id: string;
+    /** Human-readable advisory title. */
+    title: string;
+    /** Hex SHA-256 of the advisory text bytes; binds content to the signed manifest. */
+    sha256: string;
+}
+export interface GuideManifestV1 {
+    version: 1;
+    /** Stable channel identity the signature binds to; the rollback floor is per manifestId. */
+    manifestId: string;
+    /** Key id of the pinned Ed25519 public key that detached-signed the canonical manifest bytes. */
+    keyId: string;
+    /** Monotonic per-manifestId sequence; the cache refuses installs at or below the floor. */
+    sequence: number;
+    /** Milliseconds since epoch; the manifest is not authoritative before this instant. */
+    issuedAt: number;
+    /** Milliseconds since epoch; the manifest is not authoritative after this instant. */
+    expiresAt: number;
+    /** Minimum SDK advisory client version required to consume this manifest. */
+    minimumSdkVersion: number;
+    guides: GuideEntryV1[];
+}
+/**
+ * Deterministic UTF-8 encoding of a guide manifest. Object keys are sorted,
+ * separators are compact, and the output is byte-identical for semantically
+ * equal manifests regardless of the original JSON formatting. The detached
+ * Ed25519 signature is verified over exactly these bytes, so a re-formatted
+ * manifest file still verifies while any semantic change breaks the signature.
+ */
+export declare function canonicalGuideManifestBytes(manifest: GuideManifestV1): Buffer;
+export type GuideManifestParseResult = {
+    ok: true;
+    manifest: GuideManifestV1;
+} | {
+    ok: false;
+    error: {
+        code: "invalid_manifest" | "unsupported_version";
+        message: string;
+    };
+};
+/**
+ * Strict shape validation for a parsed manifest value. Fails closed on any
+ * out-of-bounds field; a manifest for a newer format version is refused with
+ * `unsupported_version` so callers can distinguish "too new" from "malformed".
+ */
+export declare function parseGuideManifest(value: unknown): GuideManifestParseResult;

package/dist/types/sdk/guides/verify.d.ts

@@ -0,0 +1,66 @@
+import { type GuideEntryV1, type GuideManifestV1 } from "./manifest";
+/**
+ * Version of the SDK advisory guide client. Manifests carry a
+ * `minimumSdkVersion` compatibility floor; a manifest that requires a newer
+ * client is refused (`incompatible`) instead of being partially understood.
+ */
+export declare const GUIDE_CLIENT_VERSION = 1;
+/** Ed25519 detached signatures are always exactly 64 bytes. */
+export declare const GUIDE_SIGNATURE_BYTES = 64;
+export interface GuidePinnedKey {
+    keyId: string;
+    /** DER-encoded SPKI public key, hex. */
+    spkiDerHex: string;
+    source: "bundled";
+}
+export declare const GUIDE_PINNED_KEYS: readonly GuidePinnedKey[];
+export declare const GUIDE_PINNED_KEY_IDS: readonly string[];
+export type GuideVerificationErrorCode = "invalid_manifest" | "unsupported_version" | "unknown_key" | "corrupt_signature" | "invalid_signature" | "not_yet_valid" | "expired" | "incompatible" | "rollback" | "hash_mismatch" | (string & {});
+export type GuideVerificationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: GuideVerificationErrorCode;
+        message: string;
+    };
+};
+/** Test-only override: installs an additional trusted key for deterministic tests. */
+export declare function addTestGuidePinnedKey(key: GuidePinnedKey): void;
+/** Test-only override: removes a previously installed test key. */
+export declare function removeTestGuidePinnedKey(keyId: string): void;
+/**
+ * Verifies a guide manifest end to end and fails closed on the first broken
+ * property. Order matters: identity and tamper checks (unknown key, malformed
+ * or mismatched signature) run before temporal and compatibility checks, so a
+ * tampered or untrusted manifest is never masked by an expiry message.
+ */
+export declare function verifyGuideManifest(params: {
+    manifest: GuideManifestV1;
+    signatureBytes: Uint8Array;
+    now: number;
+}): GuideVerificationResult<{
+    keyId: string;
+}>;
+/**
+ * Monotonic floor check: a candidate manifest for a channel must strictly
+ * advance that channel's sequence, otherwise an older (but still validly
+ * signed) manifest is refused as a rollback.
+ */
+export declare function guideRollbackCheck(previous: {
+    manifestId: string;
+    sequence: number;
+} | undefined, candidate: GuideManifestV1): GuideVerificationResult<{
+    monotonic: boolean;
+}>;
+export declare function guideAdvisoryDigest(text: Uint8Array): string;
+/**
+ * Per-guide SHA-256 binding: the advisory text must match the digest the
+ * signed manifest binds for that guide id. This is the tamper check for the
+ * advisory payload itself — the manifest signature cannot cover content that
+ * is fetched separately, so every advisory is hash-verified against it.
+ */
+export declare function verifyGuideAdvisoryText(entry: GuideEntryV1, text: Uint8Array): GuideVerificationResult<{
+    sha256: string;
+}>;

package/dist/types/sdk/host/control/dispatch.d.ts

@@ -7,6 +7,8 @@ export interface ControlRequest {
     expectedRevision?: string;
     idempotencyKey?: string;
     confirm?: boolean;
+    /** Top-level elevation claim selector, preserved from the control frame. */
+    elevationRequestId?: string;
 }
 export type ControlErrorCode = string;
 export interface ControlError {
@@ -30,5 +32,11 @@ export declare class TypedControlError extends Error {
 export declare class BusyError extends TypedControlError {
     constructor(message?: string);
 }
+/**
+ * Build the typed control request from a wire frame. Every runtime transport
+ * mapper uses this helper so the top-level elevation claim selector cannot
+ * drift between callsites.
+ */
+export declare function controlRequestFromFrame(frame: Record<string, unknown>): ControlRequest;
 /** Dispatches a registry-defined per-session control operation. */
 export declare function dispatchControl(surface: ControlSurface, registryRow: Operation | undefined, request: ControlRequest): Promise<ControlResponse>;

package/dist/types/sdk/host/control/index.d.ts

@@ -1,2 +1,2 @@
-export { BusyError, type ControlError, type ControlErrorCode, type ControlRequest, type ControlResponse, dispatchControl, TypedControlError, } from "./dispatch";
+export { BusyError, type ControlError, type ControlErrorCode, type ControlRequest, type ControlResponse, controlRequestFromFrame, dispatchControl, TypedControlError, } from "./dispatch";
 export type { ControlInput, ControlSurface, ControlValue } from "./operations";