opencode-muse 0.1.1 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ Add the published package to your project-level `opencode.jsonc` (or
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["opencode-muse@0.1.1"],
+  "plugins": ["opencode-muse@0.2.0"],
 }
 ```
 
@@ -96,14 +96,25 @@ setup placeholder rather than advertising a model that will fail on use.
   been tested, but recovery from a real Muse event gap has only been tested
   with a simulated gap. See
   [#23](https://github.com/pgquiles/opencode-muse/issues/23).
-- **Muse CLI compatibility:** The plugin is pinned and verified with Muse CLI
-  and SDK 1.4.12. A protocol/schema mismatch fails closed rather than risking
-  an incompatible session; broader version-compatibility policy is tracked in
+- **Muse CLI compatibility:** The plugin is pinned to SDK 1.4.12 and speaks
+  envelope schema version 1. A newer CLI fingerprint starts with a recorded
+  warning instead of failing closed; a missing/malformed fingerprint or an
+  unsupported envelope version still fails closed. See
   [#21](https://github.com/pgquiles/opencode-muse/issues/21).
 - **Billing and simultaneous work:** Pay-as-you-go behavior has not yet been
   tested. The plugin also allows only one active writer per workspace, so a
   new turn may be reported as busy while another is still finishing.
 
+## Troubleshooting
+
+- **"Muse Spark 1.3 Contributor" never connects after a model switch:** that
+  entry is a retired OpenCode-gateway model (`opencode/muse-spark-1.3-contributor-free`),
+  not this plugin's model. It no longer resolves anywhere, so OpenCode keeps
+  retrying and the session appears stuck on "connecting". Pick the model under
+  provider **Muse Code** — `muse/muse-profile-tbh-model-muse-spark-1.3` —
+  instead of any historical "contributor-free" entry in recent-model lists. See
+  [#26](https://github.com/pgquiles/opencode-muse/issues/26).
+
 ## Credits and references
 
 - [opencode-claude](https://github.com/openchamber/opencode-claude) — a

package/dist/model/language-model.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { MspCommandRejectedError, MuseBridgeError, MuseTranscriptDivergedError, MuseUnsupportedInputError, MuseUnsupportedRequestError, MspProtocolError, MspTransportError } from "../errors.js";
+import { notificationCursorKey } from "../msp/notification.js";
 import { MUSE_CONTEXT_HEADERS, readRequestContext } from "./context.js";
 import { classifyMetaRequest, makeCompactionDigest, makeLocalTitle } from "./meta.js";
 import { promptContainsCompactionFingerprint } from "../session/fingerprint.js";
@@ -93,7 +94,7 @@ function eventTurnId(notification, itemTurnIds) {
 async function* pageGapNotifications(host, sessionId, gap) {
     let cursor = gap.after;
     const requestedCursors = new Set([gap.after]);
-    const eventCursors = new Set();
+    const eventKeys = new Set();
     for (let pageNumber = 0; pageNumber < 100; pageNumber += 1) {
         const requestCursor = cursor;
         const page = await host.request("view/page", {
@@ -104,6 +105,7 @@ async function* pageGapNotifications(host, sessionId, gap) {
         });
         if (!Array.isArray(page.events))
             throw new MspProtocolError("view/page");
+        let boundaryReached = false;
         for (const event of page.events) {
             if (typeof event !== "object" || event === null)
                 throw new MspProtocolError("view/page");
@@ -112,14 +114,20 @@ async function* pageGapNotifications(host, sessionId, gap) {
             if (typeof record.method !== "string" || !params || params.sessionId !== sessionId || typeof params.viewCursor !== "string") {
                 throw new MspProtocolError("view/page");
             }
-            if (params.viewCursor === gap.next)
-                return;
-            if (eventCursors.has(params.viewCursor))
-                throw new MspProtocolError("view/page");
-            eventCursors.add(params.viewCursor);
+            const atBoundary = params.viewCursor === gap.next;
+            if (atBoundary)
+                boundaryReached = true;
             cursor = params.viewCursor;
-            yield { jsonrpc: "2.0", method: record.method, params };
+            const notification = { jsonrpc: "2.0", method: record.method, params };
+            const key = notificationCursorKey(notification);
+            if (key && eventKeys.has(key))
+                throw new MspProtocolError("view/page");
+            if (key)
+                eventKeys.add(key);
+            yield notification;
         }
+        if (boundaryReached)
+            return;
         if (page.nextCursor === null || typeof page.nextCursor !== "string"
             || page.nextCursor === requestCursor || requestedCursors.has(page.nextCursor)) {
             throw new MspProtocolError("view/page");
@@ -196,7 +204,7 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
         const events = {
             [Symbol.asyncIterator]: async function* () {
                 const itemTurnIds = new Map();
-                const seenCursors = new Set();
+                const seenNotifications = new Set();
                 const processNotification = async function* (notification) {
                     const params = notification.params ?? {};
                     if (params.sessionId !== session.sessionId)
@@ -227,11 +235,11 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
                             if (typeof params.after !== "string" || typeof params.next !== "string")
                                 throw new MspProtocolError("view/gap");
                             for await (const replay of pageGapNotifications(session.host, session.sessionId, { after: params.after, next: params.next })) {
-                                const replayCursor = replay.params?.viewCursor;
-                                if (typeof replayCursor === "string" && seenCursors.has(replayCursor))
+                                const replayKey = notificationCursorKey(replay);
+                                if (replayKey && seenNotifications.has(replayKey))
                                     continue;
-                                if (typeof replayCursor === "string")
-                                    seenCursors.add(replayCursor);
+                                if (replayKey)
+                                    seenNotifications.add(replayKey);
                                 for await (const output of processNotification(replay))
                                     yield output;
                                 if (terminalSeen)
@@ -239,13 +247,13 @@ export async function runMuseTurn(context, input, options, runtime, transcriptFi
                             }
                         }
                         else {
-                            const viewCursor = params.viewCursor;
-                            if (typeof viewCursor === "string" && seenCursors.has(viewCursor)) {
+                            const notificationKey = notificationCursorKey(notification);
+                            if (notificationKey && seenNotifications.has(notificationKey)) {
                                 next = await subscription.next();
                                 continue;
                             }
-                            if (typeof viewCursor === "string")
-                                seenCursors.add(viewCursor);
+                            if (notificationKey)
+                                seenNotifications.add(notificationKey);
                             for await (const output of processNotification(notification))
                                 yield output;
                             if (terminalSeen)

package/dist/model/stream.d.ts

@@ -14,7 +14,7 @@ export declare class MuseStreamMapper {
     private readonly reasoningStarted;
     private readonly itemDeltaCounts;
     private readonly itemText;
-    private readonly seenUsageCursors;
+    private readonly seenUsageNotifications;
     private readonly textParts;
     private terminalUsage;
     private callUsage;

package/dist/model/stream.js

@@ -1,4 +1,5 @@
 import { MspProtocolError, MuseTurnFailedError, MuseTurnUnqueuedError, } from "../errors.js";
+import { notificationCursorKey } from "../msp/notification.js";
 function isNumber(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
@@ -17,7 +18,7 @@ export class MuseStreamMapper {
     reasoningStarted = new Set();
     itemDeltaCounts = new Map();
     itemText = new Map();
-    seenUsageCursors = new Set();
+    seenUsageNotifications = new Set();
     textParts = [];
     terminalUsage;
     callUsage = { inputTokens: 0, outputTokens: 0, totalTokens: 0, reasoningTokens: 0 };
@@ -168,9 +169,10 @@ export class MuseStreamMapper {
     tokenUsageEvent(params) {
         if (params.turnId !== this.turnId || typeof params.viewCursor !== "string")
             return;
-        if (this.seenUsageCursors.has(params.viewCursor))
+        const key = notificationCursorKey({ method: "session/tokenUsage", params });
+        if (!key || this.seenUsageNotifications.has(key))
             return;
-        this.seenUsageCursors.add(params.viewCursor);
+        this.seenUsageNotifications.add(key);
         const raw = params.usage;
         if (!raw)
             return;

package/dist/msp/host.d.ts

@@ -1,4 +1,4 @@
-import { type MspHandshake, type SpawnMspConnectionOptions } from "@muse-code/sdk";
+import { type FingerprintWarning, type MspHandshake, type SpawnMspConnectionOptions } from "@muse-code/sdk";
 import { MspClient, type MspConnectionLike, type MspNotification } from "./client.js";
 export interface MspHostRuntime {
     connection: MspConnectionLike;
@@ -39,6 +39,8 @@ export declare class MspHost {
     private readonly runtime;
     readonly client: MspClient;
     readonly initializeResult: Record<string, unknown>;
+    /** Set when the served schema fingerprint differs from the SDK pin. Warns, never blocks. */
+    readonly fingerprintWarning?: FingerprintWarning;
     readonly exited: Promise<MspHostExit>;
     private state;
     private closePromise;

package/dist/msp/host.js

@@ -1,4 +1,4 @@
-import { MspError, EXPECTED_SCHEMA_FINGERPRINT, MuseHostStartError as SdkHostStartError, spawnMspConnection, } from "@muse-code/sdk";
+import { MspError, checkServedFingerprint, EXPECTED_SCHEMA_FINGERPRINT, MuseHostStartError as SdkHostStartError, spawnMspConnection, } from "@muse-code/sdk";
 import { MspCommandTimeoutError, MspHostClosedError, MspHostStartError, MspInitializeRejectedError, MspSchemaMismatchError, MspStartupTimeoutError, MspTransportError, } from "../errors.js";
 import { MspClient } from "./client.js";
 function defaultHandshake(options) {
@@ -32,6 +32,17 @@ function sanitizeExit(value) {
     // Deliberately omit stderrTail, raw messages, and arbitrary child properties.
     return safe;
 }
+const SCHEMA_FINGERPRINT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Envelope schema versions this plugin speaks. The SDK documents version 1 as long-lived. */
+const SUPPORTED_SCHEMA_VERSION = 1;
+function readSchemaInfo(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    if (typeof record.fingerprint !== "string")
+        return undefined;
+    return { fingerprint: record.fingerprint, version: record.version };
+}
 function withTimeout(promise, timeoutMs) {
     let timer;
     return Promise.race([
@@ -57,12 +68,15 @@ export class MspHost {
     runtime;
     client;
     initializeResult;
+    /** Set when the served schema fingerprint differs from the SDK pin. Warns, never blocks. */
+    fingerprintWarning;
     exited;
     state = "open";
     closePromise;
-    constructor(runtime, options) {
+    constructor(runtime, options, fingerprintWarning) {
         this.runtime = runtime;
         this.initializeResult = runtime.initializeResult;
+        this.fingerprintWarning = fingerprintWarning;
         this.client = new MspClient(runtime.connection, {
             commandTimeoutMs: options.commandTimeoutMs,
             requestTimeoutMs: options.requestTimeoutMs,
@@ -107,13 +121,15 @@ export class MspHost {
         const initializing = handshake.initialize(initializeParams);
         try {
             const runtime = await withTimeout(initializing, timeoutMs);
-            const schema = runtime.initializeResult.schema;
-            const servedFingerprint = typeof schema?.fingerprint === "string" ? schema.fingerprint : "missing";
-            if (servedFingerprint !== EXPECTED_SCHEMA_FINGERPRINT) {
+            const schema = readSchemaInfo(runtime.initializeResult.schema);
+            const servedFingerprint = schema?.fingerprint ?? "missing";
+            if (schema === undefined ||
+                !SCHEMA_FINGERPRINT_PATTERN.test(schema.fingerprint) ||
+                (schema.version !== undefined && schema.version !== SUPPORTED_SCHEMA_VERSION)) {
                 await closeQuietly(runtime.close.bind(runtime));
                 throw new MspSchemaMismatchError(EXPECTED_SCHEMA_FINGERPRINT, servedFingerprint);
             }
-            return new MspHost(runtime, options);
+            return new MspHost(runtime, options, checkServedFingerprint(schema.fingerprint));
         }
         catch (error) {
             if (error instanceof MspSchemaMismatchError)

package/dist/msp/notification.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Stable identity for exact notification replay suppression.
+ * A view cursor may be shared by multiple distinct notification methods or
+ * payloads, so the cursor alone is not an event identity.
+ */
+export declare function notificationCursorKey(notification: {
+    method: string;
+    params?: Record<string, unknown>;
+}): string | undefined;

package/dist/msp/notification.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+function stableJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, child]) => child !== undefined)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+    return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableJson(child)}`).join(",")}}`;
+}
+/**
+ * Stable identity for exact notification replay suppression.
+ * A view cursor may be shared by multiple distinct notification methods or
+ * payloads, so the cursor alone is not an event identity.
+ */
+export function notificationCursorKey(notification) {
+    const params = notification.params ?? {};
+    const cursor = params.viewCursor;
+    if (typeof cursor !== "string")
+        return undefined;
+    const digest = createHash("sha256")
+        .update(stableJson({ method: notification.method, params }))
+        .digest("hex");
+    return `${cursor}:${digest}`;
+}

package/dist/msp/schema-diff.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Offline schema-evolution check for policy #21.
+ *
+ * Compares MSP stable-schema snapshots and classifies the delta on the
+ * protocol surfaces this plugin actually uses. Additive growth passes with
+ * notes; removals, new required fields, dropped properties, or envelope
+ * version bumps on the curated surface fail closed for human review.
+ *
+ * Failing closed on uncertainty is deliberate: a false positive costs a
+ * human classification pass, while a false negative ships against a
+ * contract the bridge was never tested with.
+ */
+export declare const SCHEMA_SECTIONS: readonly ["methods", "requests", "notifications", "errors", "capabilities"];
+export type SchemaSection = (typeof SCHEMA_SECTIONS)[number];
+/** Methods the bridge sends. Each name verified at a call site in src (manager, provider, language-model). */
+export declare const CURATED_METHODS: readonly string[];
+/** Server-to-client requests the bridge explicitly fails closed on (no fabricated answers). */
+export declare const CURATED_REQUESTS: readonly string[];
+/** Notifications the bridge consumes in src/model/stream.ts and src/model/language-model.ts. */
+export declare const CURATED_NOTIFICATIONS: readonly string[];
+export interface SchemaExportManifest {
+    fingerprint: string;
+    schemaVersion: number;
+    experimental: boolean;
+}
+export interface SchemaExport {
+    manifest: SchemaExportManifest;
+    schema: Record<string, unknown>;
+}
+export interface DefRecord {
+    digest: string;
+    required: string[] | null;
+    props: string[] | null;
+}
+export interface SchemaSnapshot {
+    cli_version: string;
+    fingerprint: string;
+    schema_version: number | null;
+    experimental?: boolean;
+    provenance?: string;
+    surface: Record<SchemaSection, string[] | null>;
+    member_digests?: Record<string, Record<string, string>>;
+    defs?: Record<string, DefRecord>;
+    /** Legacy v1 field: whole-section $defs digest only. Superseded by defs. */
+    defs_digests?: Record<string, string>;
+    sections_digest: Record<string, string>;
+}
+export type FindingSeverity = "breaking" | "note";
+export interface DiffFinding {
+    severity: FindingSeverity;
+    kind: string;
+    detail: string;
+}
+export interface Classification {
+    ok: boolean;
+    findings: DiffFinding[];
+}
+/** Builds the ledger snapshot for one offline CLI schema export. */
+export declare function snapshotExport(cliVersion: string, provenance: string, exp: SchemaExport): SchemaSnapshot;
+/** Collects `#/$defs/<Name>` targets reachable from roots over new-side bodies. */
+export declare function collectRefs(roots: Record<string, unknown>, defs: Record<string, unknown>): Set<string>;
+export interface ClassifyOptions {
+    /**
+     * New-side bodies for reachability attribution: { members: name->body, defs: name->body }.
+     * When absent (snapshot-vs-snapshot), changed/removed defs fall back to conservative rules.
+     */
+    newBodies?: {
+        members: Record<string, unknown>;
+        defs: Record<string, unknown>;
+    };
+}
+/** Classifies old-vs-new snapshots. Breaking findings fail closed for human review. */
+export declare function classifySnapshots(oldSnap: SchemaSnapshot, newSnap: SchemaSnapshot, options?: ClassifyOptions): Classification;

package/dist/msp/schema-diff.js

@@ -0,0 +1,339 @@
+import { createHash } from "node:crypto";
+/**
+ * Offline schema-evolution check for policy #21.
+ *
+ * Compares MSP stable-schema snapshots and classifies the delta on the
+ * protocol surfaces this plugin actually uses. Additive growth passes with
+ * notes; removals, new required fields, dropped properties, or envelope
+ * version bumps on the curated surface fail closed for human review.
+ *
+ * Failing closed on uncertainty is deliberate: a false positive costs a
+ * human classification pass, while a false negative ships against a
+ * contract the bridge was never tested with.
+ */
+export const SCHEMA_SECTIONS = ["methods", "requests", "notifications", "errors", "capabilities"];
+/** Methods the bridge sends. Each name verified at a call site in src (manager, provider, language-model). */
+export const CURATED_METHODS = [
+    "model/list", // src/provider.ts catalog fetch
+    "session/start", // src/session/manager.ts resolveSession
+    "session/resume", // src/session/manager.ts restart recovery
+    "session/setModel", // src/session/manager.ts + src/model/language-model.ts selection routing
+    "turn/start", // src/model/language-model.ts agent turns
+    "turn/interrupt", // src/model/language-model.ts abort path
+    "turn/unqueue", // src/model/language-model.ts abort path
+    "media/upload", // src/model/language-model.ts video uploads
+    "view/subscribe", // src/msp/host.ts cursor replay via MspClient
+    "view/page", // src/model/language-model.ts view/gap recovery
+];
+/** Server-to-client requests the bridge explicitly fails closed on (no fabricated answers). */
+export const CURATED_REQUESTS = [
+    "approval/request", // src/msp/host.ts answers method-not-found
+    "userInput/request", // src/msp/host.ts answers method-not-found
+];
+/** Notifications the bridge consumes in src/model/stream.ts and src/model/language-model.ts. */
+export const CURATED_NOTIFICATIONS = [
+    "item/started",
+    "item/delta",
+    "item/completed",
+    "turn/completed",
+    "turn/foregroundCompleted",
+    "turn/retracted",
+    "turn/unqueued",
+    "session/tokenUsage",
+    "view/gap",
+];
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => [k, sortKeys(v)]));
+    }
+    return value;
+}
+function sha256Hex(canonicalJson) {
+    return createHash("sha256").update(canonicalJson, "utf8").digest("hex");
+}
+function canonical(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return null;
+    if (!value.every((v) => typeof v === "string"))
+        return null;
+    return [...value].sort();
+}
+/** Stable name for one section member, or null when it cannot be named. */
+function memberName(section, entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry !== null && typeof entry === "object") {
+        const record = entry;
+        if (section === "errors" && typeof record.kind === "string")
+            return record.kind;
+        if (typeof record.name === "string")
+            return record.name;
+    }
+    return null;
+}
+function sectionEntries(section, schema) {
+    const raw = schema[section];
+    const entries = [];
+    if (Array.isArray(raw)) {
+        for (const entry of raw) {
+            const name = memberName(section, entry);
+            if (name === null)
+                return null;
+            entries.push({ name, digest: sha256Hex(canonical(entry)) });
+        }
+        return entries;
+    }
+    if (raw !== null && typeof raw === "object") {
+        if (section === "capabilities") {
+            const record = raw;
+            const grantable = record.grantable;
+            if (!Array.isArray(grantable))
+                return null;
+            for (const entry of grantable) {
+                const name = memberName(section, entry);
+                if (name === null)
+                    return null;
+                entries.push({ name, digest: sha256Hex(canonical(entry)) });
+            }
+            return entries;
+        }
+        for (const [name, body] of Object.entries(raw)) {
+            entries.push({ name, digest: sha256Hex(canonical(body)) });
+        }
+        return entries;
+    }
+    return null;
+}
+function defRecord(body) {
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+        return null;
+    const record = body;
+    const properties = record.properties;
+    return {
+        digest: sha256Hex(canonical(body)),
+        required: stringArray(record.required),
+        props: properties !== null && typeof properties === "object" && !Array.isArray(properties)
+            ? Object.keys(properties).sort()
+            : null,
+    };
+}
+/** Builds the ledger snapshot for one offline CLI schema export. */
+export function snapshotExport(cliVersion, provenance, exp) {
+    if (typeof exp?.manifest?.fingerprint !== "string" || typeof exp?.manifest?.schemaVersion !== "number") {
+        throw new Error("schema-diff: export manifest must carry a fingerprint string and numeric schemaVersion");
+    }
+    if (exp.schema === null || typeof exp.schema !== "object" || Array.isArray(exp.schema)) {
+        throw new Error("schema-diff: export schema must be an object");
+    }
+    const surface = {};
+    const member_digests = {};
+    const sections_digest = {};
+    for (const section of SCHEMA_SECTIONS) {
+        const entries = sectionEntries(section, exp.schema);
+        surface[section] = entries === null ? null : entries.map((e) => e.name).sort();
+        if (entries !== null && (section === "methods" || section === "requests" || section === "notifications")) {
+            member_digests[section] = Object.fromEntries(entries.map((e) => [e.name, e.digest]));
+        }
+        sections_digest[section] = sha256Hex(canonical(exp.schema[section] ?? null));
+    }
+    const rawDefs = exp.schema.$defs;
+    if (rawDefs === null || typeof rawDefs !== "object" || Array.isArray(rawDefs)) {
+        throw new Error("schema-diff: export schema must carry a $defs object");
+    }
+    const defs = {};
+    for (const [name, body] of Object.entries(rawDefs)) {
+        const record = defRecord(body);
+        if (record === null)
+            throw new Error(`schema-diff: $defs member is not an object: ${name}`);
+        defs[name] = record;
+    }
+    sections_digest.$defs = sha256Hex(canonical(exp.schema.$defs));
+    return {
+        cli_version: cliVersion,
+        fingerprint: exp.manifest.fingerprint,
+        schema_version: exp.manifest.schemaVersion,
+        experimental: exp.manifest.experimental,
+        provenance,
+        surface,
+        member_digests,
+        defs,
+        sections_digest,
+    };
+}
+/** Collects `#/$defs/<Name>` targets reachable from roots over new-side bodies. */
+export function collectRefs(roots, defs) {
+    const seen = new Set();
+    const visit = (value) => {
+        if (typeof value === "string") {
+            const match = /^#\/\$defs\/([A-Za-z0-9_]+)$/.exec(value);
+            if (match && !seen.has(match[1])) {
+                seen.add(match[1]);
+                const body = defs[match[1]];
+                if (body !== undefined)
+                    visit(body);
+            }
+            return;
+        }
+        if (Array.isArray(value)) {
+            for (const v of value)
+                visit(v);
+            return;
+        }
+        if (value !== null && typeof value === "object") {
+            for (const v of Object.values(value))
+                visit(v);
+        }
+    };
+    for (const root of Object.values(roots))
+        visit(root);
+    return seen;
+}
+function curatedFor(section) {
+    if (section === "methods")
+        return new Set(CURATED_METHODS);
+    if (section === "requests")
+        return new Set(CURATED_REQUESTS);
+    if (section === "notifications")
+        return new Set(CURATED_NOTIFICATIONS);
+    return new Set();
+}
+function requireSurface(snap, which) {
+    if (snap === null || typeof snap !== "object")
+        throw new Error(`schema-diff: ${which} snapshot is not an object`);
+    const surface = snap.surface;
+    if (surface === null || typeof surface !== "object" || Array.isArray(surface)) {
+        throw new Error(`schema-diff: ${which} snapshot has no surface record`);
+    }
+    for (const section of SCHEMA_SECTIONS) {
+        const value = surface[section];
+        if (!Array.isArray(value) && value !== null) {
+            throw new Error(`schema-diff: ${which} snapshot surface.${section} is malformed`);
+        }
+    }
+}
+/** Classifies old-vs-new snapshots. Breaking findings fail closed for human review. */
+export function classifySnapshots(oldSnap, newSnap, options = {}) {
+    requireSurface(oldSnap, "old");
+    requireSurface(newSnap, "new");
+    const findings = [];
+    if (oldSnap.schema_version === null || oldSnap.schema_version === undefined ||
+        newSnap.schema_version === null || newSnap.schema_version === undefined) {
+        throw new Error("schema-diff: both snapshots must carry a schema_version");
+    }
+    if (oldSnap.schema_version !== newSnap.schema_version) {
+        findings.push({
+            severity: "breaking",
+            kind: "envelope-version-changed",
+            detail: `envelope schema version ${String(oldSnap.schema_version)} -> ${String(newSnap.schema_version)}`,
+        });
+    }
+    const oldMembers = oldSnap.member_digests;
+    const newMembers = newSnap.member_digests;
+    const memberLevel = oldMembers !== undefined && oldMembers !== null && newMembers !== undefined && newMembers !== null;
+    if (!memberLevel) {
+        findings.push({
+            severity: "note",
+            kind: "member-level-unavailable",
+            detail: "member-level digests absent on one side; falling back to set-level comparison",
+        });
+    }
+    for (const section of SCHEMA_SECTIONS) {
+        const oldNames = new Set(oldSnap.surface[section] ?? []);
+        const newNames = new Set(newSnap.surface[section] ?? []);
+        const curated = curatedFor(section);
+        for (const name of [...newNames].filter((n) => !oldNames.has(n)).sort()) {
+            findings.push({ severity: "note", kind: `${section}-added`, detail: `${section} added: ${name}` });
+        }
+        for (const name of [...oldNames].filter((n) => !newNames.has(n)).sort()) {
+            if (curated.has(name)) {
+                findings.push({ severity: "breaking", kind: `${section}-removed`, detail: `${section} removed curated member: ${name}` });
+            }
+            else {
+                findings.push({ severity: "note", kind: `${section}-removed`, detail: `${section} removed non-curated member: ${name}` });
+            }
+        }
+        if (memberLevel && (section === "methods" || section === "requests" || section === "notifications")) {
+            const oldMap = oldMembers?.[section] ?? {};
+            const newMap = newMembers?.[section] ?? {};
+            for (const name of [...oldNames].filter((n) => newNames.has(n)).sort()) {
+                if (oldMap[name] !== newMap[name]) {
+                    if (curated.has(name)) {
+                        findings.push({ severity: "breaking", kind: `${section}-changed`, detail: `${section} changed curated member shape: ${name}` });
+                    }
+                    else {
+                        findings.push({ severity: "note", kind: `${section}-changed`, detail: `${section} changed non-curated member shape: ${name}` });
+                    }
+                }
+            }
+        }
+    }
+    // Reachability over new-side bodies scopes nested def changes to what the bridge can observe.
+    let reachable = null;
+    if (options.newBodies) {
+        const roots = {};
+        for (const name of [...CURATED_METHODS, ...CURATED_REQUESTS, ...CURATED_NOTIFICATIONS]) {
+            if (options.newBodies.members[name] !== undefined)
+                roots[name] = options.newBodies.members[name];
+        }
+        reachable = collectRefs(roots, options.newBodies.defs);
+    }
+    const oldDefs = oldSnap.defs ?? {};
+    const newDefs = newSnap.defs ?? {};
+    const defsDetailed = oldSnap.defs !== undefined && newSnap.defs !== undefined;
+    if (!defsDetailed) {
+        findings.push({
+            severity: "note",
+            kind: "defs-unavailable",
+            detail: "per-def records absent on one side; nested changes covered only by member shapes where available",
+        });
+    }
+    else {
+        const names = new Set([...Object.keys(oldDefs), ...Object.keys(newDefs)]);
+        for (const name of [...names].sort()) {
+            const oldDef = oldDefs[name];
+            const newDef = newDefs[name];
+            if (!oldDef) {
+                findings.push({ severity: "note", kind: "def-added", detail: `$defs added: ${name}` });
+                continue;
+            }
+            if (!newDef) {
+                if (reachable !== null && reachable.has(name)) {
+                    findings.push({ severity: "breaking", kind: "def-removed", detail: `$defs removed reachable def: ${name}` });
+                }
+                else {
+                    findings.push({ severity: "note", kind: "def-removed", detail: `$defs removed: ${name}${reachable === null ? " (reachability unknown: snapshot-vs-snapshot)" : " (unreachable from curated surface)"}` });
+                }
+                continue;
+            }
+            if (oldDef.digest === newDef.digest)
+                continue;
+            const requiredAdded = (newDef.required ?? []).filter((r) => !(oldDef.required ?? []).includes(r));
+            const propsRemoved = (oldDef.props ?? []).filter((p) => !(newDef.props ?? []).includes(p));
+            const breakingShape = requiredAdded.length > 0 || propsRemoved.length > 0;
+            const isReachable = reachable === null ? null : reachable.has(name);
+            if (breakingShape && (isReachable === null || isReachable)) {
+                findings.push({
+                    severity: "breaking",
+                    kind: "def-changed",
+                    detail: `$defs changed${isReachable === null ? " (reachability unknown: snapshot-vs-snapshot)" : " (reachable from curated surface)"}: ${name}` +
+                        `${requiredAdded.length > 0 ? ` required+${requiredAdded.join(",")}` : ""}${propsRemoved.length > 0 ? ` props-${propsRemoved.join(",")}` : ""}`,
+                });
+            }
+            else {
+                findings.push({
+                    severity: "note",
+                    kind: "def-changed",
+                    detail: `$defs changed: ${name} (additive or unreachable: breaking only if a curated member shape changed, reported above)`,
+                });
+            }
+        }
+    }
+    return { ok: !findings.some((f) => f.severity === "breaking"), findings };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-muse",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "OpenCode plugin backed by the official Muse Code CLI and MSP",
   "license": "MIT",
   "type": "module",