@tiphareth/dsh-hardssh 0.1.2-alpha → 0.2.2

package/src/base/ledger.ts

@@ -1,22 +1,13 @@
 /**
- * Generic workspace ledger — the provider-agnostic persistence and routing
- * index for workspace records. It generalizes the SSH-bound ledger's proven
- * mechanics (atomic write, sync anchor index, subscription) without any
- * SSH-typed fields: a record is a `WorkspaceRecord` whose `provider` ref
- * names the owning provider, and anchors are plain local directories.
- *
- * Concrete providers keep their own specialized stores (e.g. the SSH host
- * store) and reference them through `provider.connectionRef`; the ledger
- * itself never touches provider configs.
- *
- * @module @tiphareth/dsh-hardssh/base/ledger
+ * Provider-neutral workspace ledger with strict loading, atomic persistence,
+ * detached snapshots, and one serialized mutation queue.
  */
 
 import { randomUUID } from 'node:crypto'
 import { realpathSync } from 'node:fs'
-import { mkdir, readFile, rename as renameFile, rm, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import type { WorkspaceRecord } from './model.ts'
+import { copyFile, mkdir, readFile, rename as renameFile, rm, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { WorkspaceCreateInput, WorkspaceRecord, WorkspaceUpdate } from './model.ts'
 
 /** One committed ledger snapshot. */
 export interface LedgerSnapshot {
@@ -28,14 +19,18 @@ export interface LedgerSnapshot {
 export type LedgerChange =
   | { type: 'created'; revision: number; record: WorkspaceRecord }
   | { type: 'renamed'; revision: number; before: WorkspaceRecord; record: WorkspaceRecord }
+  | { type: 'updated'; revision: number; before: WorkspaceRecord; record: WorkspaceRecord }
   | { type: 'removed'; revision: number; record: WorkspaceRecord }
+  | { type: 'replaced'; revision: number; before: WorkspaceRecord[]; records: WorkspaceRecord[] }
 
 export type LedgerListener = (change: LedgerChange) => void
 
 type LedgerChangeWithoutRevision =
   | { type: 'created'; record: WorkspaceRecord }
   | { type: 'renamed'; before: WorkspaceRecord; record: WorkspaceRecord }
+  | { type: 'updated'; before: WorkspaceRecord; record: WorkspaceRecord }
   | { type: 'removed'; record: WorkspaceRecord }
+  | { type: 'replaced'; before: WorkspaceRecord[]; records: WorkspaceRecord[] }
 
 /** Normalize an anchor for comparison (Windows case-insensitive; POSIX not). */
 export function normalizeAnchorPath(path: string): string {
@@ -65,10 +60,18 @@ function trimTrailing(path: string, minimumLength: number): string {
   return path.slice(0, end)
 }
 
+/** Options for one atomic whole-ledger replacement. */
+export interface LedgerReplaceOptions {
+  /** Copy the current persisted ledger here before overwriting it. */
+  backupPath?: string
+}
+
+/** Generic ledger schema currently accepted by strict loading. */
+export const WORKSPACE_LEDGER_SCHEMA_VERSION = 1 as const
+
 /**
- * The generic ledger. Persisted as a JSON file; mutations serialized through
- * a per-instance queue with atomic rename; a synchronous anchor index is
- * maintained so the switch layer can resolve a cwd without awaiting I/O.
+ * The generic ledger. The in-memory state changes only after an atomic save,
+ * and every public observation is detached from that state.
  */
 export class WorkspaceLedger {
   private records: WorkspaceRecord[] | undefined
@@ -93,13 +96,21 @@ export class WorkspaceLedger {
   }
 
   private async readRecords(): Promise<void> {
+    let parsed: unknown
     try {
       const text = await readFile(this.file(), 'utf8')
-      const parsed = JSON.parse(text) as unknown
-      this.records = Array.isArray(parsed) ? parsed.filter(isRecord).map(cloneRecord) : []
-    } catch {
-      this.records = []
+      parsed = JSON.parse(text) as unknown
+    } catch (error) {
+      if (isNodeErrorCode(error, 'ENOENT')) {
+        this.records = []
+        this.reindex()
+        return
+      }
+      throw error
     }
+    if (!Array.isArray(parsed)) throw new Error('WorkspaceLedger: expected a JSON array')
+    assertValidRecords(parsed)
+    this.records = cloneRecords(parsed)
     this.reindex()
   }
 
@@ -111,13 +122,34 @@ export class WorkspaceLedger {
   }
 
   private async save(nextRecords: readonly WorkspaceRecord[]): Promise<void> {
+    assertValidRecords(nextRecords)
     const target = this.file()
     if (target === '') throw new Error('WorkspaceLedger: no persistence file configured')
-    await mkdir(join(target, '..'), { recursive: true })
+    await mkdir(dirname(target), { recursive: true })
     const temporary = `${target}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`
+    const lastGood = `${target}.last-good`
     try {
       await writeFile(temporary, JSON.stringify(nextRecords, null, 2), 'utf8')
+      // Recovery net: keep a known-good copy beside the ledger so a MISSING or
+      // UNPARSEABLE ledger can be rebuilt at startup (recoverGenericLedger), so
+      // removing the file can no longer silently drop every workspace.
+      //
+      // Trade-off, stated exactly: the copy is taken BEFORE the rename, so it
+      // holds the PREVIOUS committed state — recovering from it loses the LAST
+      // committed mutation. That is deliberate: a copy mirroring the new state
+      // would be worthless precisely when the new state is what got corrupted.
+      // (On the very first commit there is nothing to copy, so the new state is
+      // seeded.) Best-effort: it must never block the real write.
+      const hadPrevious = await copyFile(target, lastGood).then(() => true, (error: unknown) => {
+        if (!isNodeErrorCode(error, 'ENOENT')) {
+          console.warn(`[dsh-hardssh] could not refresh the ledger recovery copy: ${error instanceof Error ? error.message : String(error)}`)
+        }
+        return false
+      })
       await renameFile(temporary, target)
+      if (!hadPrevious) {
+        await copyFile(target, lastGood).catch(() => undefined)
+      }
     } catch (error) {
       await rm(temporary, { force: true }).catch(() => undefined)
       throw error
@@ -131,7 +163,7 @@ export class WorkspaceLedger {
   }
 
   private commit(nextRecords: WorkspaceRecord[], change: LedgerChangeWithoutRevision): void {
-    this.records = nextRecords
+    this.records = cloneRecords(nextRecords)
     this.reindex()
     this.currentRevision += 1
     this.emit({ ...change, revision: this.currentRevision } as LedgerChange)
@@ -163,7 +195,7 @@ export class WorkspaceLedger {
   }
 
   snapshotSync(): LedgerSnapshot {
-    return { revision: this.currentRevision, records: this.records ?? [] }
+    return { revision: this.currentRevision, records: cloneRecords(this.records ?? []) }
   }
 
   revision(): number {
@@ -200,15 +232,14 @@ export class WorkspaceLedger {
     return undefined
   }
 
-  /** Create a record: materialize the anchor (managed mode), persist, commit. */
-  async create(input: Omit<WorkspaceRecord, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }): Promise<WorkspaceRecord> {
+  /** Create cannot preserve caller timestamps, so migration uses replaceAll instead. */
+  async create(input: WorkspaceCreateInput): Promise<WorkspaceRecord> {
     return this.enqueueMutation(async () => {
       await this.ensureLoaded()
       const now = new Date().toISOString()
-      const id = input.id ?? randomUUID()
-      const record: WorkspaceRecord = {
+      const record: WorkspaceRecord = cloneRecord({
         schemaVersion: input.schemaVersion,
-        id,
+        id: input.id ?? randomUUID(),
         title: input.title,
         provider: input.provider,
         location: input.location,
@@ -217,11 +248,12 @@ export class WorkspaceLedger {
         updatedAt: now,
         labels: input.labels,
         extensions: input.extensions,
-      }
+      })
+      const nextRecords = [...(this.records ?? []), record]
+      assertValidRecords(nextRecords)
       if (record.anchor !== undefined && record.anchor.mode === 'managed') {
         await mkdir(record.anchor.path, { recursive: true })
       }
-      const nextRecords = [...(this.records ?? []), record]
       await this.save(nextRecords)
       this.commit(nextRecords, { type: 'created', record })
       return cloneRecord(record)
@@ -229,21 +261,50 @@ export class WorkspaceLedger {
   }
 
   async rename(id: string, title: string): Promise<WorkspaceRecord | undefined> {
+    const before = await this.get(id)
+    const record = await this.update(id, { title: title.trim() })
+    if (before === undefined || record === undefined) return undefined
+    return record
+  }
+
+  /** WorkspaceLedger.rename cannot change provider bindings or extension data, so update applies a generic patch. */
+  async update(id: string, patch: WorkspaceUpdate): Promise<WorkspaceRecord | undefined> {
     return this.enqueueMutation(async () => {
       await this.ensureLoaded()
       const records = this.records ?? []
       const index = records.findIndex(record => record.id === id)
       if (index < 0) return undefined
-      const before = records[index]
-      const record: WorkspaceRecord = { ...before, title: title.trim(), updatedAt: new Date().toISOString() }
+      const before = cloneRecord(records[index]!)
+      const record = cloneRecord({ ...before, ...structuredClone(patch), id: before.id, schemaVersion: before.schemaVersion, createdAt: before.createdAt, updatedAt: new Date().toISOString() })
       const nextRecords = [...records]
       nextRecords[index] = record
+      assertValidRecords(nextRecords)
       await this.save(nextRecords)
-      this.commit(nextRecords, { type: 'renamed', before, record })
+      this.commit(nextRecords, { type: 'updated', before, record })
       return cloneRecord(record)
     })
   }
 
+  /** WorkspaceLedger.create persists one generated record, so it cannot atomically import a complete authoritative snapshot. */
+  async replaceAll(records: readonly WorkspaceRecord[], options: LedgerReplaceOptions = {}): Promise<void> {
+    return this.enqueueMutation(async () => {
+      await this.ensureLoaded()
+      const nextRecords = cloneRecords(records)
+      assertValidRecords(nextRecords)
+      const before = cloneRecords(this.records ?? [])
+      if (options.backupPath !== undefined) {
+        await mkdir(dirname(options.backupPath), { recursive: true })
+        try {
+          await copyFile(this.file(), options.backupPath)
+        } catch (error) {
+          if (!isNodeErrorCode(error, 'ENOENT')) throw error
+        }
+      }
+      await this.save(nextRecords)
+      this.commit(nextRecords, { type: 'replaced', before, records: nextRecords })
+    })
+  }
+
   /** Remove a record. The anchor directory is left in place (caller decides). */
   async remove(id: string): Promise<boolean> {
     return this.enqueueMutation(async () => {
@@ -251,7 +312,7 @@ export class WorkspaceLedger {
       const records = this.records ?? []
       const index = records.findIndex(record => record.id === id)
       if (index < 0) return false
-      const record = records[index]
+      const record = records[index]!
       const nextRecords = [...records.slice(0, index), ...records.slice(index + 1)]
       await this.save(nextRecords)
       this.commit(nextRecords, { type: 'removed', record })
@@ -264,18 +325,77 @@ export class WorkspaceLedger {
   }
 }
 
+/** isRecord validates one shape only, so this validator also rejects duplicate ids and ambiguous anchors across records. */
+export function assertValidRecords(values: readonly unknown[]): asserts values is readonly WorkspaceRecord[] {
+  const ids = new Set<string>()
+  const anchors: Array<{ id: string; path: string }> = []
+  for (const value of values) {
+    if (!isRecord(value)) throw new Error('WorkspaceLedger: invalid workspace record')
+    if (ids.has(value.id)) throw new Error(`WorkspaceLedger: duplicate workspace id '${value.id}'`)
+    ids.add(value.id)
+    if (value.anchor !== undefined) anchors.push({ id: value.id, path: normalizeAnchorPath(value.anchor.path) })
+  }
+  for (let left = 0; left < anchors.length; left += 1) {
+    for (let right = left + 1; right < anchors.length; right += 1) {
+      const a = anchors[left]!
+      const b = anchors[right]!
+      if (isPathUnderAnchor(a.path, b.path) || isPathUnderAnchor(b.path, a.path)) {
+        throw new Error(`WorkspaceLedger: duplicate or overlapping anchors for '${a.id}' and '${b.id}'`)
+      }
+    }
+  }
+}
+
 function isRecord(value: unknown): value is WorkspaceRecord {
-  if (typeof value !== 'object' || value === null) return false
-  const record = value as Record<string, unknown>
-  return typeof record.id === 'string'
-    && typeof record.title === 'string'
-    && typeof record.schemaVersion === 'number'
-    && typeof record.provider === 'object' && record.provider !== null
-    && typeof (record.provider as Record<string, unknown>).id === 'string'
-    && typeof record.location === 'object' && record.location !== null
-    && typeof (record.location as Record<string, unknown>).root === 'string'
-    && typeof record.createdAt === 'string'
-    && typeof record.updatedAt === 'string'
+  if (!isPlainObject(value)) return false
+  const provider = value.provider
+  const location = value.location
+  const anchor = value.anchor
+  const labels = value.labels
+  const extensions = value.extensions
+  if (value.schemaVersion !== WORKSPACE_LEDGER_SCHEMA_VERSION
+    || typeof value.id !== 'string' || value.id === ''
+    || typeof value.title !== 'string'
+    || !isPlainObject(provider) || typeof provider.id !== 'string' || provider.id === ''
+    || (provider.instanceId !== undefined && typeof provider.instanceId !== 'string')
+    || !isConnectionRef(provider.connectionRef)
+    || !isPlainObject(location) || typeof location.kind !== 'string' || location.kind === '' || typeof location.root !== 'string' || location.root === ''
+    || (location.options !== undefined && (!isPlainObject(location.options) || !isJsonValue(location.options)))
+    || !isAnchor(anchor)
+    || typeof value.createdAt !== 'string' || typeof value.updatedAt !== 'string'
+    || (labels !== undefined && (!isPlainObject(labels) || Object.values(labels).some(label => typeof label !== 'string')))
+    || (extensions !== undefined && (!isPlainObject(extensions) || !isJsonValue(extensions)))) return false
+  return true
+}
+
+/** isRecord cannot distinguish an absent connectionRef from a malformed present one without this focused guard. */
+function isConnectionRef(value: unknown): boolean {
+  return value === undefined || (isPlainObject(value)
+    && typeof value.id === 'string' && value.id !== ''
+    && (value.alias === undefined || typeof value.alias === 'string'))
+}
+
+/** isRecord delegates optional anchor validation here because anchor has a discriminated mode shape. */
+function isAnchor(value: unknown): boolean {
+  return value === undefined || (isPlainObject(value)
+    && typeof value.path === 'string' && value.path !== ''
+    && (value.mode === 'managed' || value.mode === 'existing'))
+}
+
+/** typeof object also accepts arrays and prototypes, so isRecord needs this stricter object check. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value) as unknown
+  return prototype === Object.prototype || prototype === null
+}
+
+/** isRecord cannot validate arbitrarily nested options/extensions inline, so this recursive JSON-value guard closes that gap. */
+function isJsonValue(value: unknown): boolean {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true
+  if (typeof value === 'number') return Number.isFinite(value)
+  if (Array.isArray(value)) return value.every(isJsonValue)
+  if (!isPlainObject(value)) return false
+  return Object.values(value).every(isJsonValue)
 }
 
 function safeRealpathSync(path: string): string | undefined {
@@ -283,7 +403,7 @@ function safeRealpathSync(path: string): string | undefined {
 }
 
 function cloneRecord(record: WorkspaceRecord): WorkspaceRecord {
-  return { ...record, provider: { ...record.provider }, location: { ...record.location } }
+  return structuredClone(record)
 }
 
 function cloneRecords(records: readonly WorkspaceRecord[]): WorkspaceRecord[] {
@@ -294,6 +414,13 @@ function cloneChange(change: LedgerChange): LedgerChange {
   switch (change.type) {
     case 'created': return { ...change, record: cloneRecord(change.record) }
     case 'renamed': return { ...change, before: cloneRecord(change.before), record: cloneRecord(change.record) }
+    case 'updated': return { ...change, before: cloneRecord(change.before), record: cloneRecord(change.record) }
     case 'removed': return { ...change, record: cloneRecord(change.record) }
+    case 'replaced': return { ...change, before: cloneRecords(change.before), records: cloneRecords(change.records) }
   }
-}
+}
+
+/** Error.message cannot reliably identify ENOENT, so strict loading checks Node's machine-readable code. */
+function isNodeErrorCode(error: unknown, code: string): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && (error as { code?: unknown }).code === code
+}

package/src/base/model.ts

@@ -69,14 +69,24 @@ export interface WorkspaceRecord {
   extensions?: Record<string, unknown>
 }
 
-/** One provider capability key (extensible via module augmentation). */
+/** Provider API major implemented by the generic workspace foundations. */
+export const WORKSPACE_PROVIDER_API_VERSION = 2 as const
+
+/**
+ * Provider capability augmentation point. Runtime packages add their official
+ * capability types here; the platform-neutral base deliberately defines none.
+ */
 export interface WorkspaceCapabilityMap {
-  'workspace.fs': import('./capability.ts').WorkspaceFileSystem
-  'workspace.process': import('./capability.ts').WorkspaceProcessRuntime
-  'workspace.terminal': import('./capability.ts').WorkspaceTerminalService
-  'workspace.search': import('./capability.ts').WorkspaceSearchService
+  /** Unaugmented providers may carry private keys; runtime-known keys gain precise types through augmentation. */
+  [capability: string]: unknown
 }
 
+/** Input accepted when creating a record; identity and timestamps are ledger-owned. */
+export type WorkspaceCreateInput = Omit<WorkspaceRecord, 'id' | 'createdAt' | 'updatedAt'> & { id?: WorkspaceId }
+
+/** Mutable record fields; identity, schema, and creation time remain immutable. */
+export type WorkspaceUpdate = Partial<Pick<WorkspaceRecord, 'title' | 'provider' | 'location' | 'anchor' | 'labels' | 'extensions'>>
+
 /** A resolved, open connection to one workspace's provider. */
 export interface WorkspaceConnection {
   readonly workspaceId: WorkspaceId
@@ -101,8 +111,8 @@ export interface WorkspaceProvider {
   readonly manifest: WorkspaceProviderManifest
   /** Validate a record before open (e.g. root shape, ref resolvable). */
   validate(record: WorkspaceRecord): void | Promise<void>
-  /** Open a connection for one record. */
-  open(record: WorkspaceRecord, context?: WorkspaceOpenContext): Promise<WorkspaceConnection>
+  /** Open a connection for one record under the router-owned lifecycle context. */
+  open(record: WorkspaceRecord, context: WorkspaceOpenContext): Promise<WorkspaceConnection>
 }
 
 /** Static provider identity, checked before any plugin code runs. */
@@ -114,5 +124,5 @@ export interface WorkspaceProviderManifest {
   apiVersion: number
   displayName: string
   /** Capabilities this provider implements. */
-  capabilities: Array<keyof WorkspaceCapabilityMap | string>
+  capabilities: string[]
 }

package/src/base/plugin.ts

@@ -84,6 +84,17 @@ export interface WorkspacePlugin {
 /**
  * Registry of loaded plugins (provider + feature plugins together). Keeps
  * the workspace registry and plugin lifecycle in one place.
+ *
+ * NOT WIRED INTO PRODUCTION YET: the DSH runtime registers the builtin
+ * providers directly (`runtime/workspace-core.ts`) and no third-party plugin
+ * loads through this host — only tests do. It is kept because it is the
+ * documented distribution contract for out-of-tree providers (see SKILLS.md);
+ * provider teardown stays ownership-correct for when it is wired up: each
+ * registration releases the disposer that `register()` returned for THAT call,
+ * so a duplicate (same id+version) registration never unregisters a provider it
+ * does not own.
+ *
+ * @internal Not reachable from any production assembly today.
  */
 export class WorkspacePluginHost {
   private readonly plugins = new Map<string, WorkspacePlugin>()
@@ -144,14 +155,14 @@ export class WorkspacePluginHost {
   }
 
   private registerProvider(provider: WorkspaceProvider): () => void {
-    // The registry returns a disposer on register; a same-version duplicate
-    // no-ops, so the disposer may be a no-op too — unload still runs it.
+    // Preserve registry ownership: a duplicate registration's no-op disposer
+    // must never unregister the provider owned by another plugin.
+    const disposeRegistration = this.registries.workspaces.register(provider)
     let disposed = false
-    this.registries.workspaces.register(provider)
     return () => {
       if (disposed) return
       disposed = true
-      this.registries.workspaces.unregister?.(provider.manifest.id)
+      disposeRegistration()
     }
   }
 

package/src/base/registry.ts

@@ -1,20 +1,13 @@
-/**
- * Workspace provider registry — the single place providers register and are
- * looked up by id. The registry is provider-agnostic: SSH, local, and any
- * future provider all register here, and the switch layer resolves
- * workspaces through the registry without knowing which provider backs them.
- *
- * Registration is idempotent per (id, version, apiVersion): re-registering
- * the same provider is a no-op / reuse; registering a different or
- * incompatible implementation with the same id is an error.
- *
- * @module @tiphareth/dsh-hardssh/base/registry
- */
+/** Provider-neutral registry with observable, ownership-safe registration lifecycle. */
 
 import type { WorkspaceProvider, WorkspaceProviderManifest } from './model.ts'
 
-/** Fired when a provider registers (for surface mounts / cache invalidation). */
-export type ProviderListener = (provider: WorkspaceProvider) => void
+/** Provider registration lifecycle event consumed by routers. */
+export type ProviderChange =
+  | { type: 'registered'; provider: WorkspaceProvider }
+  | { type: 'unregistered'; provider: WorkspaceProvider }
+
+export type ProviderListener = (change: ProviderChange) => void
 
 /** Duplicate / incompatible registration error. */
 export class ProviderRegistrationError extends Error {
@@ -29,7 +22,7 @@ export class WorkspaceProviderRegistry {
   private readonly providers = new Map<string, WorkspaceProvider>()
   private readonly listeners = new Set<ProviderListener>()
 
-  /** Register a provider. Throws on id collision with an incompatible impl. */
+  /** Register a provider and return a disposer that only removes that exact registration. */
   register(provider: WorkspaceProvider): () => void {
     const id = provider.manifest.id
     const existing = this.providers.get(id)
@@ -41,15 +34,18 @@ export class WorkspaceProviderRegistry {
           `provider '${id}' already registered (${existing.manifest.version}, api ${existing.manifest.apiVersion}); refusing incompatible duplicate`,
         )
       }
-      // Same version: reuse. No-op.
-      return () => { /* already registered */ }
+      return () => { /* The original registration retains ownership. */ }
     }
     this.providers.set(id, provider)
-    const disposer = () => { this.providers.delete(id) }
-    for (const listener of [...this.listeners]) {
-      try { listener(provider) } catch { /* listener isolation */ }
+    this.emit({ type: 'registered', provider })
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      if (this.providers.get(id) !== provider) return
+      this.providers.delete(id)
+      this.emit({ type: 'unregistered', provider })
     }
-    return disposer
   }
 
   /** Look up a provider by id. */
@@ -57,10 +53,19 @@ export class WorkspaceProviderRegistry {
     return this.providers.get(id)
   }
 
-  /** Unregister a provider by id (no-op when absent or different version). */
+  /**
+   * Remove a provider by id, whoever registered it.
+   *
+   * Ownership-unsafe by construction: callers that registered a provider must
+   * use the disposer returned by register() instead, otherwise teardown can
+   * delete a provider owned by another plugin. Kept for whole-registry
+   * operations (tests, process-level resets).
+   */
   unregister(id: string): void {
-    if (!this.providers.has(id)) return
+    const provider = this.providers.get(id)
+    if (provider === undefined) return
     this.providers.delete(id)
+    this.emit({ type: 'unregistered', provider })
   }
 
   /** All registered providers. */
@@ -68,10 +73,15 @@ export class WorkspaceProviderRegistry {
     return [...this.providers.values()]
   }
 
-  /** Subscribe to registrations. Returns a disposer. */
+  /** Subscribe must expose both registration and removal, which the old registration-only listener could not report. */
   subscribe(listener: ProviderListener): () => void {
     this.listeners.add(listener)
-    return () => { this.listeners.delete(listener) }
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      this.listeners.delete(listener)
+    }
   }
 
   /** True when a provider id is registered. */
@@ -83,27 +93,25 @@ export class WorkspaceProviderRegistry {
   manifestOf(id: string): WorkspaceProviderManifest | undefined {
     return this.providers.get(id)?.manifest
   }
-}
 
-/** The process-wide shared registry. */
-export const globalWorkspaceRegistry = new WorkspaceProviderRegistry()
+  /** register() cannot safely repeat listener isolation for both lifecycle directions, so emit centralizes it. */
+  private emit(change: ProviderChange): void {
+    for (const listener of [...this.listeners]) {
+      try { listener(change) } catch { /* listener isolation */ }
+    }
+  }
+}
 
-/**
- * Workspace registry surface used by plugins: list / watch workspace records
- * and register providers. Implemented by the runtime over the ledger + the
- * provider registry.
- */
+/** Plugin-facing workspace registry surface. */
 export interface WorkspaceRegistry {
-  /** All known workspace records (provider-agnostic). */
   listWorkspaces(): Promise<import('./model.ts').WorkspaceRecord[]>
-  /** Subscribe to workspace record changes. Returns a disposer. */
   subscribe(listener: (workspace: import('./model.ts').WorkspaceRecord) => void): () => void
-  /** Register a provider (idempotent same-version; throws on conflict). */
-  register(provider: WorkspaceProvider): void
-  /** Unregister a provider by id (no-op when absent). */
+  register(provider: WorkspaceProvider): () => void
+  /**
+   * Ownership-unsafe id-based removal; plugin teardown must release the
+   * disposer returned by `register()` instead of calling this.
+   */
   unregister?(providerId: string): void
-  /** Look up a provider by id. */
   provider(id: string): WorkspaceProvider | undefined
-  /** All registered providers. */
   providers(): WorkspaceProvider[]
-}
+}

package/src/base/router.ts

@@ -32,12 +32,4 @@ export interface WorkspaceRouter {
   codec: WorkspaceNamespaceCodec
   /** Map a route back to a resolution (used by the switch to re-encode child keys). */
   resolveRoute(route: WorkspaceRoute): WorkspaceResolution | undefined
-}
-
-/** Convenience base: default codec wiring plus helper for resolution lookup. */
-export abstract class BaseWorkspaceRouter implements WorkspaceRouter {
-  abstract readonly codec: WorkspaceNamespaceCodec
-  abstract fromNamespace(key: string): WorkspaceResolution | undefined
-  abstract fromAnchor(cwd: string | undefined): WorkspaceConnection | undefined
-  abstract resolveRoute(route: WorkspaceRoute): WorkspaceResolution | undefined
 }