@adhdev/mesh-shared 1.0.60-rc.73 → 1.0.60-rc.74

package/dist/magi.d.ts

@@ -1,281 +0,0 @@
-/**
- * MAGI — Multi-Agent Ground-truth Insight.
- *
- * Pure shared types for the mesh cross-verification quorum: the per-task_kind
- * panel binding (machine-local config, stored in ~/.adhdev/meshes.json
- * `magiKindPanels`), the agent-agnostic common output schema every dispatched
- * replica answers with, and the synthesis result shapes. These cross the
- * daemon-core (storage / accessors) ↔ mcp-server (fan-out / synthesis) boundary,
- * so they live in the dependency-free mesh-shared leaf — no runtime, no Node/DOM APIs.
- *
- * Design: docs/design/2026-06-28-mesh-magi-review.md. Core stance: no personas,
- * no named lenses — a panel slot is just one `(node × provider)` target that
- * answers the SAME question. The value is the friction (contested / singleton /
- * source-coupled findings), NOT a majority vote.
- *
- * NOTE: the former named-panel model (MagiPanel / MagiPanelMember / MagiPanelMap
- * and inline `members`) was REMOVED. A MAGI review resolves its fan-out slots
- * EXCLUSIVELY from the `magiKindPanels` binding for the review's `task_kind`; an
- * unconfigured kind is a hard error, never a synthesized or named-panel fallback.
- */
-/**
- * One kind-panel slot: a `(node × provider [× model])` target. `provider` required;
- * `nodeId` pins a concrete mesh node; `model` optionally selects the agent model at
- * launch; `capabilityTags` route by tag when no nodeId is given; `n` is an optional
- * per-slot replica count. This is the SOLE panel-member shape — the fan-out planner
- * (buildMagiFanoutPlan) resolves a `MagiSlot[]` directly.
- *
- * ─── DELIBERATELY REDUCED SCHEMA — not a missing feature ─────────────────────
- *
- * A MagiSlot is a strict subset of a node's `NodeCapabilitySlot`. It accepts
- * `provider` + optional `model` / `nodeId` / `capabilityTags` / `n`, and it
- * deliberately does NOT accept the node-capability routing axes — `thinkingLevel`,
- * `difficulty`, `maxParallel`. That asymmetry is the design, not an oversight:
- *
- *   - A node capability slot answers **"which work goes where"** — routing FITNESS.
- *     Difficulty and thinking level exist there to match a task against the slot best
- *     suited to run it.
- *   - A MAGI panel slot answers **"who answers independently"** — cross-verification
- *     DIVERSITY. Its whole value is that the replicas are NOT selected for fitness.
- *
- * Reviving the difficulty/thinking axes here would couple panel membership to routing
- * optimization, and the best-fitting provider would win every slot. The panel would
- * collapse toward one provider — which is precisely the failure MAGI exists to
- * prevent, since agreement among coupled agents carries no information (see the
- * `source_coupled` weighting in synthesis). A reduced schema is what keeps the two
- * axes orthogonal.
- *
- * Consistent with that, `mesh_magi_review` enqueues every replica with a fixed
- * `difficulty: 'freeform'` sentinel rather than a caller-chosen grade — the panel has
- * already pinned the (node, provider) target, so any difficulty would be inert at best
- * and would fight the panel's own slot selection at worst. To change how hard a
- * replica thinks or how much parallelism a node grants, edit that NODE's capability
- * slots (`mesh_node_slots` action "set"); it is a different axis, on purpose.
- *
- * Unknown keys are dropped rather than rejected, so slots written by another version
- * stay readable. Write paths pair the normalizer with
- * `collectIgnoredMagiSlotFields()` and report the drops as `ignoredFields`, so the
- * reduction is visible instead of silent.
- */
-export interface MagiSlot {
-    /** Optional — pin to a specific mesh node id. Absent → route by capabilityTags + provider. */
-    nodeId?: string;
-    /** REQUIRED — provider type, e.g. 'claude-cli' | 'codex-cli' | 'gemini-cli'. */
-    provider: string;
-    /**
-     * Optional model override applied at replica launch (e.g. 'opus' | 'sonnet' for
-     * claude-cli). Threaded through enqueueTask → the auto-launched session's
-     * `launch_cli` payload as `initialModel`. For ACP providers it drives
-     * setConfigOption('model', …); for CLI providers it is expanded via the provider
-     * manifest's `modelLaunchArgs` template into launch args (a provider with no
-     * template silently ignores it — model is best-effort, never fatal).
-     */
-    model?: string;
-    /** Optional routing tags, ANDed with the provider tag when nodeId is absent. */
-    capabilityTags?: string[];
-    /** Optional per-slot replica count; defaults to the kind-panel defaultN / global n / 1. */
-    n?: number;
-}
-/**
- * Per-task_kind panel binding for ONE mesh, stored machine-local in
- * `~/.adhdev/meshes.json` under that mesh's entry (`meshes[].magiKindPanels`). The
- * scope is per mesh: two meshes on the same machine hold independent bindings for
- * the same task_kind. (It formerly sat at the config root keyed by task_kind alone,
- * which let one mesh's write clobber another's.) A kind absent from the map has NO
- * configured panel → `mesh_magi_review({task_kind})` errors with
- * `magi_kind_not_configured` rather than synthesizing one. `freeform` MAY be bound
- * like any other kind (a direct kind→slots binding).
- */
-export type MagiKindPanelMap = Partial<Record<MagiTaskKind, MagiSlot[]>>;
-/**
- * The output-schema selector a MAGI fan-out injects into every replica prompt and
- * the strict parser used at collection. Code-orthogonal to the panel's slot set
- * (the fan-out planner never reads it) — it ONLY shapes the per-replica prompt /
- * parse contract. SSOT lives here (mesh-shared leaf) so both daemon-core (slot
- * normalization) and mcp-server (resolution / prompt assembly) consume one union.
- *
- * - claim_audit (default, backward-compatible), rca, design → require evidence[].
- * - freeform → no schema, no evidence; contributes NO structured claims to
- *   synthesis. It MAY still be bound as a kind-panel key (a direct kind→slots
- *   binding), unlike the removed named-panel `defaultKind`.
- */
-export type MagiTaskKind = 'claim_audit' | 'rca' | 'design' | 'freeform';
-/**
- * Synthesis emphasis hint. Affects weighting / labels only — NEVER the agent
- * count or the common schema. (Per-mode weighting tuning is a deferred refinement;
- * the field is accepted now so callers and panels are forward-stable.)
- */
-export type MagiMode = 'rca' | 'investigation' | 'claim_audit' | 'design_review' | 'code_audit';
-export type MagiClaimStance = 'support' | 'oppose' | 'uncertain';
-/**
- * One claim from one agent. `evidence` carries `file:line` or external-source
- * strings; `confidence` is 0..1. Identical regardless of which provider/machine
- * produced it — this is the forced structured-output contract injected into each
- * dispatched task prompt.
- */
-export interface MagiClaim {
-    claim: string;
-    stance: MagiClaimStance;
-    evidence: string[];
-    confidence: number;
-}
-/** The agent-agnostic response every dispatched replica returns. */
-export interface MagiAgentResponse {
-    claims: MagiClaim[];
-    top_findings: string[];
-    open_questions: string[];
-}
-/**
- * Where one response came from — the `(node × provider)` identity that backs a
- * claim's independence. `ok=false` marks a replica that died / produced no
- * parseable common-schema output (excluded from clusters, counted as missing).
- */
-export interface MagiResponseSource {
-    /** Mesh task id of the dispatched replica. */
-    taskId: string;
-    nodeId?: string;
-    provider?: string;
-    /** False when the replica failed or its output could not be parsed. */
-    ok: boolean;
-    /** Reason when ok=false (timeout / failed / unparseable / stale). */
-    error?: string;
-    /**
-     * True when the replica was detected STALE during collection — assigned to a
-     * node/session no longer present in the live mesh (so it will never reach a
-     * terminal state). Distinguishes a dead-assignment replica from one that is
-     * merely still generating. Always implies ok=false.
-     */
-    stale?: boolean;
-    /**
-     * Git ref of the node this replica ran on, captured at collection time from the
-     * live mesh node's compact git summary. Lets synthesis (and a dashboard) detect
-     * GIT SKEW across the panel — if the answering replicas span different branches
-     * or diverge (ahead/behind), their file:line evidence is comparing different code
-     * and "agreement" is less meaningful. Best-effort; absent when the node carried
-     * no git summary.
-     */
-    git?: MagiReplicaGitRef;
-    /**
-     * The replica's raw end-user answer text as read from its session transcript at
-     * collection time, truncated to MAGI_RAW_ANSWER_CAP chars (with `rawAnswerTruncated`
-     * set when it was longer). This is the human-readable original a replica produced —
-     * useful when the structured claim parse dropped nuance, or for a cluster member that
-     * needs the source prose. GATED: stripped from the persisted `magi_synthesis` ledger
-     * entry (to bound ledger payload growth) and from the default mesh_magi_collect
-     * response; surfaced ONLY in mesh_magi_collect verbose. Best-effort; absent for a
-     * replica that produced no readable transcript (failed / stale / unparseable).
-     */
-    rawAnswer?: string;
-    /** True when `rawAnswer` was truncated at MAGI_RAW_ANSWER_CAP. */
-    rawAnswerTruncated?: boolean;
-}
-/** Max chars of a replica's raw answer retained on MagiResponseSource.rawAnswer. */
-export declare const MAGI_RAW_ANSWER_CAP = 4000;
-/** Compact git ref of the node a replica ran on (subset of GitRepoStatus). */
-export interface MagiReplicaGitRef {
-    branch?: string | null;
-    /** HEAD commit sha of the node's workspace — the exact code the replica saw. */
-    headCommit?: string | null;
-    ahead?: number;
-    behind?: number;
-    dirty?: boolean;
-}
-/**
- * Cross-replica git divergence assessment. `skewed` is true when the answering
- * replicas span more than one branch OR any replica diverges from its upstream
- * (ahead/behind > 0) — both mean the panel is not all looking at the same code, so
- * file:line evidence and agreement are git-skewed. Always present on a synthesis
- * (skewed=false / distinctBranches≤1 when there is nothing to flag).
- */
-export interface MagiGitSkew {
-    skewed: boolean;
-    /** Number of distinct branches across the answering replicas with a known branch. */
-    distinctBranches: number;
-    /** The distinct branch names (sorted), for display. */
-    branches: string[];
-    /** Replicas whose branch/divergence differs from the panel baseline. */
-    divergentReplicas: number;
-    note?: string;
-}
-/** A parsed replica response paired with its source identity. */
-export interface MagiSynthesizedResponse {
-    source: MagiResponseSource;
-    response: MagiAgentResponse;
-}
-/**
- * Synthesis category for a claim cluster. `needs_verification` is the PRIMARY
- * OUTPUT = contested ∪ singleton ∪ source_coupled ∪ (high-impact claims lacking
- * independent evidence). `agreed` is the only "safe to trust, low priority" bucket.
- */
-export type MagiClusterCategory = 'agreed' | 'contested' | 'dissent' | 'singleton' | 'source_coupled';
-/** One member observation inside a claim cluster. */
-export interface MagiClusterMember {
-    taskId: string;
-    nodeId?: string;
-    provider?: string;
-    claim: string;
-    stance: MagiClaimStance;
-    evidence: string[];
-    confidence: number;
-}
-/**
- * A cluster of semantically-equivalent claims across responses, with its
- * stance tally and diversity-weighted independence assessment.
- */
-export interface MagiClaimCluster {
-    /** Representative (first / longest) claim text for the cluster. */
-    claim: string;
-    category: MagiClusterCategory;
-    members: MagiClusterMember[];
-    stance: {
-        support: number;
-        oppose: number;
-        uncertain: number;
-    };
-    /** Distinct providers / nodes / evidence sources backing the cluster. */
-    distinctProviders: number;
-    distinctNodes: number;
-    distinctEvidence: number;
-    /** Diversity-weighted independence score (NOT the raw agent count). */
-    independenceScore: number;
-    /** True when this cluster is routed to needs_verification. */
-    needsVerification: boolean;
-    /** Why it needs verification (contested / singleton / source_coupled / no_independent_evidence). */
-    reasons: string[];
-}
-/** The full synthesis result — N-agnostic, diversity-weighted, not a vote. */
-export interface MagiSynthesis {
-    /** How many replicas were expected vs. produced parseable output. */
-    replicasExpected: number;
-    replicasAnswered: number;
-    replicasMissing: number;
-    /** Distinct providers / nodes across the answering replicas. */
-    distinctProviders: number;
-    distinctNodes: number;
-    /**
-     * Set when the resolved panel collapsed to a single provider or single
-     * machine — agreements are then flagged source-coupled. Null when independence
-     * was achieved.
-     */
-    independenceBanner: string | null;
-    clusters: MagiClaimCluster[];
-    /** PRIMARY OUTPUT — clusters routed to needs_verification, highest priority first. */
-    needsVerification: MagiClaimCluster[];
-    /** High-independence agreements — safe to trust, lowest review priority. */
-    agreed: MagiClaimCluster[];
-    /** Union of every response's open_questions (deduped). */
-    openQuestions: string[];
-    /**
-     * Per-replica source identity (taskId / nodeId / provider / ok / stale / git) for
-     * every replica in the fan-out. Lets a consumer (the dashboard's extractMagiActivity)
-     * read which node × provider answered and the git ref each ran at — the inputs behind
-     * the gitSkew assessment.
-     */
-    replicas: MagiResponseSource[];
-    /**
-     * Cross-replica git divergence. When skewed, the answering replicas were not all
-     * on the same code (different branches / ahead-behind), so evidence and agreement
-     * should be read with that caveat. Always present.
-     */
-    gitSkew: MagiGitSkew;
-}

package/dist/turn-ipc-graph.d.ts

@@ -1,195 +0,0 @@
-/**
- * turn-ipc — graph gates, task stats and maintenance commands: graph_gate_claim,
- * graph_gate_release, graph_gate_abandon, graph_node_patch, graph_view_query,
- * task_stats_query, prune_stale_direct, orphaned_pin_notify. Part of the turn-ipc
- * wire contract (./turn-ipc.ts).
- */
-import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
-export interface GraphGateClaimRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    gateId: string;
-    coordinatorSessionId: string;
-    leaseSeconds?: number;
-    extendDeadlineSeconds?: number;
-    /** Also collect `collectGateConvergenceEvidence` on a successful claim (mesh_graph_gate action=claim's own behavior). */
-    probeConvergenceEvidence?: boolean;
-}
-export interface GraphGateClaimResponse {
-    claimed: boolean;
-    /** gate_not_found / gate_not_eligible / gate_not_awaiting / gate_lease_held / gate_claim_race / gate_terminal:<state> / gate_not_claimable, when `claimed: false`. */
-    reason?: string;
-    /** `MeshGraphGateRow`, JSON passthrough; present whenever the core found the gate. */
-    gate?: Record<string, unknown>;
-    leaseGeneration?: number;
-    fencingToken?: string;
-    leaseExpiresAt?: string;
-    deadlineAt?: string;
-    ambiguousExternalOutcome?: boolean;
-    previousLeaseOwnerSessionId?: string;
-    /** `GateConvergenceEvidence`, JSON passthrough; present only when requested and found. */
-    convergenceEvidence?: Record<string, unknown>;
-}
-export declare function decodeGraphGateClaimRequest(value: unknown): GraphGateClaimRequest | null;
-export declare function decodeGraphGateClaimResponse(value: unknown): GraphGateClaimResponse | null;
-export interface GraphGateReleaseRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    gateId: string;
-    fencingToken: string;
-    leaseGeneration: number;
-    idempotencyKey: string;
-    outcome: string;
-    /** Action-specific structured result/evidence the CALLER supplied — JSON passthrough, echoed back unmodified. */
-    result?: unknown;
-    evidence?: unknown;
-    patches?: readonly {
-        node: string;
-        baseSpecPatch: Record<string, unknown>;
-    }[];
-}
-export type GraphGateReleaseResponse = {
-    released: true;
-    duplicate: boolean;
-    gate?: Record<string, unknown>;
-    materializedNodeIds: readonly string[];
-    downstreamNodeCount?: number;
-    graphCompleted?: boolean;
-} | {
-    released: false;
-    refusalCode?: string;
-    message: string;
-};
-export declare function decodeGraphGateReleaseRequest(value: unknown): GraphGateReleaseRequest | null;
-export declare function decodeGraphGateReleaseResponse(value: unknown): GraphGateReleaseResponse | null;
-export interface GraphGateAbandonRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    gateId: string;
-    reason: string;
-    coordinatorSessionId?: string;
-    force?: boolean;
-}
-export interface GraphGateAbandonResponse {
-    abandoned: boolean;
-    /** gate_not_found / gate_lease_held / gate_abandon_race / gate_terminal:<state> / gate_not_abandonable, when `abandoned: false`. */
-    reason?: string;
-    gate?: Record<string, unknown>;
-    cancelledNodeIds: readonly string[];
-    cancelledTaskIds: readonly string[];
-    graphStatus?: string;
-}
-export declare function decodeGraphGateAbandonRequest(value: unknown): GraphGateAbandonRequest | null;
-export declare function decodeGraphGateAbandonResponse(value: unknown): GraphGateAbandonResponse | null;
-export interface GraphNodePatchRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    node: string;
-    graphId?: string;
-    /** Only {@link MESH_NODE_PATCH_KEYS}-shaped keys are permitted; the daemon enforces the allow-list. */
-    baseSpecPatch: Record<string, unknown>;
-}
-export type GraphNodePatchResponse = {
-    patched: true;
-    graphId: string;
-    nodeId: string;
-    ref?: string;
-    queueTaskId?: string;
-    materializationVersion: number;
-    state: string;
-    /** `SettleOutcome['kind']` — materialized / deferred / skipped / error. */
-    outcomeKind: string;
-    /** Present when `outcomeKind === 'skipped'`. */
-    skippedReason?: string;
-    blockedReason?: string;
-} | {
-    patched: false;
-    refusalCode?: string;
-    message: string;
-};
-export declare function decodeGraphNodePatchRequest(value: unknown): GraphNodePatchRequest | null;
-export declare function decodeGraphNodePatchResponse(value: unknown): GraphNodePatchResponse | null;
-export interface GraphViewQueryRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    graphId?: string;
-    batchId?: string;
-    /** Default true: only graphs that still need attention. */
-    activeOnly?: boolean;
-    limit?: number;
-    /** Attach `collectGateConvergenceEvidence` to the first few waiting gates (mesh_graph_view's G4 opt-in probe). */
-    probeGateEvidence?: boolean;
-}
-export interface GraphViewQueryResponse {
-    /** `MeshGraphView[]`, JSON passthrough — see this section's content-boundary note. */
-    graphs: readonly Record<string, unknown>[];
-}
-export declare function isGraphViewQueryRequest(value: unknown): value is GraphViewQueryRequest;
-export declare function decodeGraphViewQueryRequest(value: unknown): GraphViewQueryRequest | null;
-export declare function decodeGraphViewQueryResponse(value: unknown): GraphViewQueryResponse | null;
-export interface TaskStatsQueryRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    taskIds?: readonly string[];
-    missionId?: string;
-    tail?: number;
-    /** Also compute `computeMeshMissionStats` — requires `missionId`. */
-    rollup?: boolean;
-    /**
-     * Batch rollups: `computeMeshMissionStats` for every id, over ONE queue read and
-     * ONE record read (answers `missions`, `tasks` empty). Exclusive with
-     * `taskIds`/`missionId`. An older daemon rejects the key.
-     */
-    missionIds?: readonly string[];
-}
-export interface TaskStatsQueryResponse {
-    /** `MeshTaskStats[]`, JSON passthrough. */
-    tasks: readonly Record<string, unknown>[];
-    /** `MeshMissionStats`, JSON passthrough; present only when `rollup: true` was requested and satisfiable. */
-    mission?: Record<string, unknown>;
-    /** Batch mode: `MeshMissionStats` per requested mission id, JSON passthrough. */
-    missions?: Record<string, Record<string, unknown>>;
-}
-export declare function decodeTaskStatsQueryRequest(value: unknown): TaskStatsQueryRequest | null;
-export declare function decodeTaskStatsQueryResponse(value: unknown): TaskStatsQueryResponse | null;
-export interface PruneStaleDirectRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    execute?: boolean;
-    includeTerminal?: boolean;
-    source?: string;
-}
-export interface PruneStaleDirectResponse {
-    mode: 'execute' | 'dry_run';
-    includeTerminal: boolean;
-    candidateCount: number;
-    /** `MeshActiveWorkRecord[]`, JSON passthrough. */
-    prunable: readonly Record<string, unknown>[];
-    prunedCount: number;
-    preservedUnacknowledged: readonly Record<string, unknown>[];
-    preservedLedgerOnly: readonly Record<string, unknown>[];
-    preservedNotOrphan: readonly Record<string, unknown>[];
-}
-export declare function decodePruneStaleDirectRequest(value: unknown): PruneStaleDirectRequest | null;
-export declare function decodePruneStaleDirectResponse(value: unknown): PruneStaleDirectResponse | null;
-export interface OrphanedPinNotifyRequest {
-    v: typeof TURN_IPC_PROTOCOL_VERSION;
-    meshId: string;
-    stoppedSessionId: string;
-    excludeTaskId?: string;
-    cause?: string;
-    nodeId?: string;
-    coordinatorSessionId?: string;
-}
-export interface OrphanedPinnedTaskWire {
-    taskId: string;
-    title: string;
-    targetSessionId: string;
-    targetNodeId?: string;
-    missionId?: string;
-}
-export interface OrphanedPinNotifyResponse {
-    orphans: readonly OrphanedPinnedTaskWire[];
-}
-export declare function decodeOrphanedPinNotifyRequest(value: unknown): OrphanedPinNotifyRequest | null;
-export declare function decodeOrphanedPinNotifyResponse(value: unknown): OrphanedPinNotifyResponse | null;