@sayknow-cli/coding-agent 0.3.13 → 0.3.16

package/dist/types/setup/credential-import.d.ts

@@ -0,0 +1,82 @@
+import type { AuthCredential } from "@sayknow-cli/ai";
+/** skc provider ids that external credentials map onto. */
+export type ExternalProvider = "anthropic" | "openai-codex";
+/** Where a discovered credential came from. */
+export type CredentialOrigin = "claude-code-file" | "claude-code-keychain" | "codex-file";
+export declare const AUTO_IMPORT_OAUTH_PROVIDER_ORIGINS: Record<ExternalProvider, ReadonlySet<CredentialOrigin>>;
+/** Human labels for providers, used in redacted summaries. */
+export declare const EXTERNAL_PROVIDER_LABELS: Record<ExternalProvider, string>;
+/** A credential that can be safely imported into skc's store. */
+export interface ImportableCredential {
+    provider: ExternalProvider;
+    origin: CredentialOrigin;
+    /** Redacted, human-readable description of where this came from. */
+    source: string;
+    kind: AuthCredential["type"];
+    identity?: {
+        email?: string;
+        accountId?: string;
+    };
+    /** Epoch-ms expiry for OAuth credentials, when known. */
+    expiresAt?: number;
+    /** Redacted access token / API key — safe to display. */
+    redactedToken: string;
+    /** Opaque credential payload. Never include this in any summary output. */
+    credential: AuthCredential;
+}
+/** A source that was found but could not be imported. */
+export interface SkippedCredential {
+    origin: CredentialOrigin;
+    source: string;
+    reason: string;
+}
+/** Ambient environment-backed auth that is already usable without import. */
+export interface EnvironmentCredentialHint {
+    provider: ExternalProvider;
+    variable: string;
+    redactedValue: string;
+}
+export interface CredentialDiscoveryResult {
+    importable: ImportableCredential[];
+    skipped: SkippedCredential[];
+    environment: EnvironmentCredentialHint[];
+}
+export interface DiscoveryOptions {
+    /** Override the home directory (defaults to `os.homedir()`). */
+    homeDir?: string;
+    /** Override the environment (defaults to `process.env`). */
+    env?: Record<string, string | undefined>;
+    /** Override the platform (defaults to `process.platform`). */
+    platform?: NodeJS.Platform;
+    /**
+     * Reader for the macOS Keychain `Claude Code-credentials` entry. Defaults to
+     * shelling out to `security`; injected in tests. Returns the raw JSON string,
+     * or `null` when no entry exists.
+     */
+    readClaudeKeychain?: () => Promise<string | null>;
+}
+export type CredentialUpserter = (provider: string, credential: AuthCredential) => unknown | Promise<unknown>;
+export interface ImportSummary {
+    imported: ImportableCredential[];
+    failed: Array<{
+        credential: ImportableCredential;
+        error: string;
+    }>;
+}
+/**
+ * Discover Claude Code and Codex CLI credentials across files, the macOS
+ * Keychain, and environment variables. Never throws for individual unreadable or
+ * malformed sources — those land in {@link CredentialDiscoveryResult.skipped}.
+ */
+export declare function discoverExternalCredentials(options?: DiscoveryOptions): Promise<CredentialDiscoveryResult>;
+/** Redacted one-line summary of an importable credential. Never includes secrets. */
+export declare function formatCredentialSummary(credential: ImportableCredential): string;
+/** Redacted summary lines for an entire discovery result. Never includes secrets. */
+export declare function formatDiscoverySummary(result: CredentialDiscoveryResult): string[];
+export declare function isAutoImportOAuthCredential(credential: ImportableCredential): boolean;
+export declare function filterAutoImportOAuthCredentials(credentials: readonly ImportableCredential[]): ImportableCredential[];
+/**
+ * Persist discovered credentials via `upsert`. Each credential is imported
+ * independently; a failure on one is recorded without aborting the rest.
+ */
+export declare function importCredentials(credentials: readonly ImportableCredential[], upsert: CredentialUpserter): Promise<ImportSummary>;

package/dist/types/setup/hermes-setup.d.ts

@@ -0,0 +1,78 @@
+import { COORDINATOR_MCP_PROTOCOL_VERSION, COORDINATOR_MCP_SERVER_NAME } from "../coordinator/contract";
+export type HermesMutationClass = "sessions" | "questions" | "reports";
+export type HermesSetupMode = "render" | "install" | "check" | "smoke";
+export interface HermesSetupFlags {
+    json?: boolean;
+    check?: boolean;
+    smoke?: boolean;
+    install?: boolean;
+    force?: boolean;
+    root?: string[];
+    repo?: string;
+    profile?: string;
+    sessionCommand?: string;
+    noWorktree?: boolean;
+    worktreeName?: string;
+    stateRoot?: string;
+    mutation?: string[];
+    artifactByteCap?: string;
+    serverKey?: string;
+    skcCommand?: string;
+    target?: string;
+    profileDir?: string;
+}
+export interface CoordinatorSetupSpec {
+    schemaVersion: 1;
+    coordinator: "hermes";
+    serverKey: string;
+    serverName: typeof COORDINATOR_MCP_SERVER_NAME;
+    protocolVersion: typeof COORDINATOR_MCP_PROTOCOL_VERSION;
+    skcCommand: string;
+    args: ["mcp-serve", "coordinator"];
+    roots: string[];
+    namespace: {
+        profile?: string;
+        repo?: string;
+    };
+    sessionCommand?: string;
+    sessionCommandSource: "default" | "explicit";
+    worktree: {
+        enabled: boolean;
+        name?: string;
+    };
+    stateRoot?: string;
+    mutationPolicy: {
+        classes: HermesMutationClass[];
+        perCallConsentRequired: true;
+    };
+    artifactByteCap?: number;
+    installTarget?: {
+        kind: "profile-dir" | "config-file";
+        path: string;
+    };
+    operatorTemplateVersion: 1;
+    contractDocVersion: 1;
+}
+export interface HermesSetupResult {
+    ok: boolean;
+    mode: HermesSetupMode;
+    files_written: string[];
+    previews: Array<{
+        path: string;
+        content: string;
+    }>;
+    warnings: string[];
+    smoke: null | {
+        ok: boolean;
+        protocolVersion: string;
+        serverName: string;
+        requiredTools: string[];
+        missingTools: string[];
+    };
+}
+export declare function buildHermesSetupSpec(flags: HermesSetupFlags): CoordinatorSetupSpec;
+export declare function computeHermesSetupSignature(spec: CoordinatorSetupSpec): string;
+export declare function renderHermesServerBlock(spec: CoordinatorSetupSpec): Record<string, unknown>;
+export declare function runHermesSetup(flags: HermesSetupFlags): Promise<HermesSetupResult>;
+export declare function formatHermesSetupResult(result: HermesSetupResult): string;
+export declare function hermesSetupExitCode(error: unknown): number;

package/dist/types/setup/host-plugin-setup.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Host plugin setup for `skc setup claude` and `skc setup codex`.
+ *
+ * Renders install guidance and a fail-closed coordinator MCP config preview for
+ * the canonical generated plugin bundle under `plugins/`. This is intentionally
+ * render-only and fail-closed: the workdir allowlist is scoped to the project
+ * root and no mutation class is enabled until the user opts in.
+ */
+export type HostPluginKind = "claude" | "codex";
+export interface HostPluginSetupFlags {
+    json?: boolean;
+    check?: boolean;
+    root?: string[];
+    repo?: string;
+}
+export interface HostPluginSetupResult {
+    ok: true;
+    host: HostPluginKind;
+    mode: "render";
+    gated: boolean;
+    pluginPath: string;
+    manifestPath: string;
+    marketplacePath: string;
+    installGuidance: string[];
+    coordinatorConfigPreview: {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+    mutationPolicy: string;
+    notes: string[];
+    check?: {
+        ok: boolean;
+        checked: string[];
+        missing: string[];
+    };
+}
+export declare function buildHostPluginSetup(host: HostPluginKind, flags?: HostPluginSetupFlags): HostPluginSetupResult;
+export declare function formatHostPluginSetup(result: HostPluginSetupResult): string;

package/dist/types/setup/model-onboarding-guidance.d.ts

@@ -0,0 +1,9 @@
+export declare const MODEL_ONBOARDING_API_PROVIDER_COMMAND = "/provider add --compat <openai|anthropic> --provider <id> --base-url <url> --api-key-env <ENV> --model <model>";
+export declare const MODEL_ONBOARDING_PROVIDER_PRESET_COMMAND = "/provider add --preset <minimax|minimax-cn|glm>";
+export declare const MODEL_ONBOARDING_SETUP_COMMAND = "skc setup provider";
+export declare const MODEL_ONBOARDING_OAUTH_COMMAND = "/provider login [provider-id] or /login [provider-id]";
+export declare function formatModelOnboardingGuidance(): string;
+export declare function formatModelOnboardingInlineHint(): string;
+export declare function formatNoModelOnboardingError(): string;
+export declare function formatNoCredentialOnboardingError(providerId: string): string;
+export declare function formatNoModelsAvailableFallback(): string;

package/dist/types/setup/provider-onboarding.d.ts

@@ -0,0 +1,52 @@
+import { type ModelsConfig } from "../config/models-config-schema";
+export type ProviderCompatibility = "openai" | "anthropic";
+export type ProviderSetupApi = "openai-responses" | "openai-completions" | "anthropic-messages";
+export interface ProviderSetupInput {
+    compatibility?: ProviderCompatibility;
+    preset?: string;
+    providerId?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    models?: string[];
+    modelsPath?: string;
+    force?: boolean;
+}
+export interface ProviderSetupResult {
+    providerId: string;
+    compatibility: ProviderCompatibility;
+    api: ProviderSetupApi;
+    baseUrl: string;
+    modelIds: string[];
+    modelsPath: string;
+    redactedApiKey: string;
+    credentialSource: "literal" | "env";
+    preset?: string;
+    presetName?: string;
+}
+type ProviderConfig = NonNullable<NonNullable<ModelsConfig["providers"]>[string]>;
+type ProviderCompatConfig = NonNullable<ProviderConfig["compat"]>;
+interface ProviderPreset {
+    id: string;
+    aliases: readonly string[];
+    name: string;
+    description: string;
+    compatibility: ProviderCompatibility;
+    api: ProviderSetupApi;
+    providerId: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    models: readonly string[];
+    compat?: ProviderCompatConfig;
+}
+export declare const PROVIDER_PRESETS: readonly ProviderPreset[];
+export declare function getDefaultModelsPath(): string;
+export declare function normalizeProviderId(providerId: string): string;
+export declare function parseProviderCompatibility(value: string): ProviderCompatibility;
+export declare function findProviderPreset(value: string | undefined): ProviderPreset | undefined;
+export declare function formatProviderPresetList(): string;
+export declare function parseModelList(values: readonly string[]): string[];
+export declare function redactSecret(secret: string): string;
+export declare function addApiCompatibleProvider(input: ProviderSetupInput): Promise<ProviderSetupResult>;
+export declare function formatProviderSetupResult(result: ProviderSetupResult): string;
+export {};

package/dist/types/skc-runtime/cli-write-receipt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CLI write/mutation receipt shaping (Workstream B, v4).
+ *
+ * `CliWriteReceipt` is the compact **stdout presentation** returned by a SKC
+ * mutation command. It carries only routing/audit fields a caller needs; it
+ * NEVER echoes the persisted body (full `state` envelope, ultragoal `plan`,
+ * team task body, ralplan `task`, etc.) — echoing those back is a redundant
+ * token leak because the caller already has the content it just wrote.
+ *
+ * This is intentionally a *separate* concept from the persisted
+ * `WorkflowStateReceipt` (the on-disk envelope `receipt` integrity field).
+ * Do NOT use `CliWriteReceipt` as a persistence schema or validate persisted
+ * envelopes against it.
+ */
+export interface CliWriteReceipt {
+    ok: boolean;
+    [field: string]: unknown;
+}
+/**
+ * Serialize a write/mutation receipt to compact stdout JSON.
+ * `undefined` fields are dropped so optional routing fields stay absent
+ * rather than serialized as `null`.
+ */
+export declare function renderCliWriteReceipt(receipt: Record<string, unknown>): string;

package/dist/types/skc-runtime/deep-interview-ambiguity.d.ts

@@ -0,0 +1,39 @@
+import { type DeepInterviewStateEnvelope } from "./deep-interview-state";
+export interface AmbiguityFloorBreakdown {
+    floor: number;
+    disputed_fact_count: number;
+    unscored_active_component_count: number;
+    auto_answer_ratio: number;
+}
+export interface AmbiguityClampResult {
+    effective: number;
+    clamped: boolean;
+}
+/** Compute the deterministic floor from the inner deep-interview `state` object. */
+export declare function computeAmbiguityFloor(inner: unknown): AmbiguityFloorBreakdown;
+/** Clamp an LLM-reported ambiguity to the deterministic floor: `max(reported, floor)`. */
+export declare function clampReportedAmbiguity(reported: number, floor: number): AmbiguityClampResult;
+/**
+ * Mark every established fact recorded in `retractedRound` as disputed. This is the
+ * mechanical contradiction signal for answer retraction: when the user replaces an
+ * already-scored answer (A -> B pivot), the facts that answer established can no
+ * longer be trusted, so they raise the floor until re-confirmed or superseded.
+ * Returns new arrays/objects; never mutates the input.
+ */
+export declare function disputeFactsFromRetractedRound(facts: readonly unknown[], retractedRound: number): {
+    facts: Record<string, unknown>[];
+    disputedIds: string[];
+};
+export interface AppliedAmbiguityFloor {
+    envelope: DeepInterviewStateEnvelope;
+    breakdown: AmbiguityFloorBreakdown;
+    clamped: boolean;
+}
+/**
+ * Enforce the floor invariant on a full deep-interview envelope: recompute the floor
+ * from persisted evidence, clamp `state.current_ambiguity`, and clamp the latest
+ * scored round (preserving the original value as `reported_ambiguity` for audit).
+ * Historical rounds are never rewritten. Idempotent and non-mutating; every writer
+ * (state CLI write/reconcile, recorder) applies this immediately before persisting.
+ */
+export declare function applyAmbiguityFloorToEnvelope(value: unknown): AppliedAmbiguityFloor;

package/dist/types/skc-runtime/deep-interview-recorder.d.ts

@@ -0,0 +1,114 @@
+import { type DeepInterviewEstablishedFact, type DeepInterviewRoundRecord, type DeepInterviewStateEnvelope, type DeepInterviewTriggerMetadata } from "./deep-interview-state";
+export * from "./deep-interview-ambiguity";
+export * from "./deep-interview-state";
+/**
+ * Runtime-owned deep-interview round recorder (conflict-aware scoring support).
+ *
+ * Ownership boundary (per the approved consensus plan): this module owns durable
+ * round-record semantics — stable identity, append-or-merge, lifecycle, compact
+ * reads, replay detection, and the pure scored-transition validator. Callers such
+ * as the `ask` tool only resolve an answer and invoke these helpers; they never
+ * compute state paths, merge records, or write `.skc` files directly. All writes
+ * go through the sanctioned state-writer (`writeWorkflowEnvelopeAtomic`).
+ */
+export interface DeepInterviewAnswerInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    questionText: string;
+    component?: string;
+    dimension?: string;
+    ambiguity?: number;
+    selectedOptions?: string[];
+    customInput?: string;
+}
+export interface DeepInterviewScoringInput {
+    interviewId?: string;
+    round: number;
+    round_id?: string;
+    questionId?: string;
+    scores: Record<string, number>;
+    ambiguity: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export type AppendOrMergeAction = "created" | "noop" | "replaced";
+export interface AppendOrMergeResult {
+    rounds: DeepInterviewRoundRecord[];
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+}
+export interface DeepInterviewCompactState {
+    threshold?: number;
+    threshold_source?: string;
+    current_ambiguity?: number;
+    topology_summary?: {
+        active: number;
+        deferred: number;
+        components: string[];
+    };
+    established_facts: DeepInterviewEstablishedFact[];
+    unresolved_triggers: DeepInterviewTriggerMetadata[];
+    recent_scored_rounds: DeepInterviewRoundRecord[];
+    pending_shells: DeepInterviewRoundRecord[];
+}
+export interface TransitionValidationResult {
+    ok: boolean;
+    violations: string[];
+}
+export declare function buildAnswerShell(input: DeepInterviewAnswerInput, now?: string): DeepInterviewRoundRecord;
+/**
+ * Append-or-merge by `round_key`. Exactly one record per key:
+ * - no existing record -> append (`created`);
+ * - identical question_hash + answer_hash -> deterministic no-op (`noop`);
+ * - same key, different hashes -> deterministic replacement of the prior shell
+ *   (`replaced`); the prior answer for that key is superseded and lifecycle resets.
+ */
+export declare function appendOrMergeRound(rounds: readonly DeepInterviewRoundRecord[], shell: DeepInterviewRoundRecord): AppendOrMergeResult;
+/**
+ * Merge scoring output into the existing record for the derived key, transitioning
+ * it to `scored`. Never appends a second record for the same key; if no shell exists
+ * yet (scoring without a prior ask), a scored record is created so data is not lost.
+ */
+export declare function enrichRoundWithScoring(rounds: readonly DeepInterviewRoundRecord[], input: DeepInterviewScoringInput, now?: string): {
+    rounds: DeepInterviewRoundRecord[];
+    record: DeepInterviewRoundRecord;
+};
+/**
+ * Bidirectional invariant: if `next` carries an `active` trigger, the affected
+ * dimension must not improve and overall ambiguity must rise vs the prior scored
+ * round. `disputed`/`unresolved` triggers are exempt but must carry a rationale.
+ */
+export declare function validateDeepInterviewScoredTransition(prior: DeepInterviewRoundRecord | undefined, next: DeepInterviewRoundRecord): TransitionValidationResult;
+/** Back-compat wrapper: normalize a deep-interview envelope to its canonical nested shape. */
+export declare function ensureDeepInterviewStateShape(value: unknown): DeepInterviewStateEnvelope;
+export declare function projectCompactState(value: unknown, options?: {
+    lastN?: number;
+}): DeepInterviewCompactState;
+/** Refresh the best-effort HUD cache from persisted deep-interview state. */
+export declare function syncDeepInterviewRecorderHud(cwd: string, statePath: string, sessionId: string | undefined): Promise<void>;
+/**
+ * Record an `answered` shell for one round (append-or-merge by durable key).
+ *
+ * Retraction dynamics: replacing an already-`scored` answer is a mechanical
+ * contradiction signal (the user pivoted). The facts that round established are
+ * marked disputed, which raises the deterministic ambiguity floor immediately —
+ * without waiting for the LLM scorer to self-report a trigger.
+ */
+export declare function appendOrMergeDeepInterviewRound(cwd: string, statePath: string, input: DeepInterviewAnswerInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    action: AppendOrMergeAction;
+    record: DeepInterviewRoundRecord;
+    disputedFactIds?: string[];
+}>;
+/** Merge scoring output into the same round record, transitioning to `scored`. */
+export declare function enrichDeepInterviewRoundScoring(cwd: string, statePath: string, input: DeepInterviewScoringInput, options?: {
+    sessionId?: string;
+}): Promise<{
+    record: DeepInterviewRoundRecord;
+}>;
+/** Compact projection so callers read a slice instead of the full transcript. */
+export declare function readDeepInterviewStateCompact(statePath: string, options?: {
+    lastN?: number;
+}): Promise<DeepInterviewCompactState>;

package/dist/types/skc-runtime/deep-interview-runtime.d.ts

@@ -0,0 +1,36 @@
+export * from "./deep-interview-recorder";
+/**
+ * Native implementation of `skc deep-interview`.
+ *
+ * The CLI itself does not run the Socratic interview; that lives inside the `/skill:deep-interview`
+ * skill executed by the agent. This handler validates the documented argument-hint surface
+ * (`[--quick|--standard|--deep] <idea>`), seeds `.skc/state/deep-interview-state.json`, and
+ * updates the shared HUD rail via `syncSkillActiveState` so the active interview is visible to
+ * the TUI.
+ */
+export interface DeepInterviewCommandResult {
+    status: number;
+    stdout?: string;
+    stderr?: string;
+}
+export declare function deepInterviewStatePath(cwd: string, sessionId?: string): string;
+export interface ResolvedDeepInterviewSpecWriteArgs {
+    stage: "final";
+    slug: string;
+    spec: string;
+    sessionId: string;
+    json: boolean;
+    deliberate: boolean;
+    handoff?: "ralplan";
+    force: boolean;
+}
+export interface PersistedDeepInterviewSpec {
+    slug: string;
+    path: string;
+    stage: "final";
+    sha256: string;
+    createdAt: string;
+    statePath: string;
+}
+export declare function persistDeepInterviewSpec(cwd: string, resolved: ResolvedDeepInterviewSpecWriteArgs): Promise<PersistedDeepInterviewSpec>;
+export declare function runNativeDeepInterviewCommand(args: string[], cwd?: string): Promise<DeepInterviewCommandResult>;

package/dist/types/skc-runtime/deep-interview-state.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Pure, dependency-free foundation for deep-interview state shape.
+ *
+ * Ownership boundary (per the approved consensus plan): this leaf module owns the
+ * canonical persisted shape (interview data nested under `state`), durable round
+ * identity/hashing, lossless legacy normalization, and the deep-interview-specific
+ * envelope/round merge used by every writer (`deep-interview-recorder`,
+ * `state-runtime` write/reconcile, seed, and handoff). It MUST NOT import the
+ * active-state, state-writer, CLI runtime, or filesystem so it stays cycle-free and
+ * trivially testable.
+ */
+export type DeepInterviewRoundLifecycle = "answered" | "pending_scoring" | "scored";
+export type DeepInterviewTriggerKind = "A" | "B" | "C" | "D";
+/** `active` triggers must satisfy the bidirectional invariant; disputed/unresolved are exempt with rationale. */
+export type DeepInterviewTriggerStatus = "active" | "disputed" | "unresolved";
+export interface DeepInterviewEstablishedFact {
+    id: string;
+    statement: string;
+    round: number;
+    component?: string;
+    dimension?: string;
+    evidence?: string;
+    disputed: boolean;
+    /**
+     * Resolution pointer for a disputed fact: the id of the fact that replaced it
+     * after the user confirmed a pivot. A disputed fact without `superseded_by`
+     * keeps the deterministic ambiguity floor elevated; setting it releases the
+     * pressure while preserving the contradicted fact for audit.
+     */
+    superseded_by?: string;
+}
+export interface DeepInterviewTriggerMetadata {
+    kind: DeepInterviewTriggerKind;
+    name: string;
+    status: DeepInterviewTriggerStatus;
+    component: string;
+    dimension: string;
+    priorDimensionScore?: number;
+    newDimensionScore?: number;
+    priorAmbiguity?: number;
+    newAmbiguity?: number;
+    evidence?: string;
+    contradictedFactId?: string;
+    /** Required when status is `disputed` or `unresolved` to exempt the invariant. */
+    rationale?: string;
+}
+export interface DeepInterviewRoundRecord {
+    round_key: string;
+    round_id?: string;
+    round: number;
+    question_id?: string;
+    question_text?: string;
+    question_hash: string;
+    answer_hash: string;
+    selected_options?: string[];
+    custom_input?: string;
+    component?: string;
+    dimension?: string;
+    ambiguity_at_ask?: number;
+    lifecycle: DeepInterviewRoundLifecycle;
+    answered_at: string;
+    scored_at?: string;
+    scores?: Record<string, number>;
+    /** Effective ambiguity after the deterministic floor clamp (`max(reported, floor)`). */
+    ambiguity?: number;
+    /** Original LLM-reported ambiguity, preserved for audit when the floor clamped it. */
+    reported_ambiguity?: number;
+    /** Deterministic floor in effect when this round was scored, when it clamped. */
+    ambiguity_floor?: number;
+    triggers?: DeepInterviewTriggerMetadata[];
+}
+export interface DeepInterviewStateEnvelope {
+    threshold?: number;
+    threshold_source?: string;
+    state?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function hashContent(value: string): string;
+export declare function questionHash(questionText: string): string;
+export declare function answerHash(selectedOptions: string[] | undefined, customInput: string | undefined): string;
+/**
+ * Durable round identity. Prefer `interview_id + round_id`; fall back to
+ * `interview_id + round + question.id` when no caller-supplied `round_id` exists.
+ */
+export declare function deriveRoundKey(interviewId: string | undefined, input: {
+    round_id?: string;
+    round: number;
+    questionId?: string;
+}): string;
+/**
+ * Canonicalize a deep-interview envelope: interview data nested under `state`,
+ * legacy flattened fields hoisted in losslessly, transcript duplicates removed
+ * from the top level, and `rounds`/`established_facts` guaranteed to be arrays.
+ *
+ * Idempotent: a canonical envelope is returned unchanged in shape. Preserves all
+ * unknown envelope and nested fields except the envelope-reserved keys that leak
+ * into `state` (see `ENVELOPE_RESERVED_STATE_KEYS`), which are stripped so a
+ * malformed envelope-in-state write cannot permanently nest state. Never mutates
+ * the input.
+ */
+export declare function normalizeDeepInterviewEnvelope(value: unknown): DeepInterviewStateEnvelope;
+/**
+ * Lossless, idempotent merge of two round arrays.
+ *
+ * - Records sharing a durable key (`round_key`, or synthesized from
+ *   `round_id`/`question_id`) merge into one, preferring scored over answered.
+ * - Records without any durable identity are preserved verbatim; an exact
+ *   duplicate is skipped so repeated writes stay idempotent, but distinct records
+ *   are never collapsed.
+ *
+ * Deliberate refinement of the approved plan: rather than mutating opaque legacy
+ * records with synthetic `legacy:<index>` keys, they are preserved verbatim with
+ * exact-duplicate dedupe. This satisfies the plan's intent (lossless, idempotent,
+ * never collapse distinct rounds) without rewriting user-supplied round objects,
+ * and keeps free-form extension preservation intact. Recorder-produced records
+ * always carry a `round_key`, so the synthetic path is unnecessary in practice.
+ */
+export declare function mergeDeepInterviewRounds(existing: readonly Record<string, unknown>[], incoming: readonly Record<string, unknown>[]): Record<string, unknown>[];
+/**
+ * Deep-interview-specific envelope merge. Unlike the generic shallow null-delete
+ * merge, this keeps interview data nested under `state`, never deletes `state`,
+ * and merges `rounds` losslessly by durable key so a partial write (e.g. a
+ * scoring update) cannot drop recorder-written transcript history.
+ */
+export declare function mergeDeepInterviewEnvelope(existing: unknown, incoming: unknown, options?: {
+    replace?: boolean;
+}): DeepInterviewStateEnvelope;

package/dist/types/skc-runtime/gc-render.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Text rendering for `skc gc` reports. JSON output is produced directly in
+ * `gc-runtime.ts`; this module owns the human-readable grouped report.
+ */
+import type { GcReport } from "./gc-runtime";
+export declare function buildGcReportText(report: GcReport): string;