@tiphareth/dsh-hardssh 0.1.2

package/src/base/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @tiphareth/dsh-hardssh/base — the generic workspace base.
+ *
+ * Provider-agnostic core: workspace model, provider/connection/capability
+ * contracts, registry, ledger, namespace codec, router, and the plugin
+ * registration API. No SSH, no Cordis, no React.
+ *
+ * @module @tiphareth/dsh-hardssh/base
+ */
+
+export * from './model.ts'
+export * from './capability.ts'
+export * from './registry.ts'
+export * from './ledger.ts'
+export * from './namespace.ts'
+export * from './router.ts'
+export * from './ledger-router.ts'
+export * from './plugin.ts'

package/src/base/ledger-router.ts

@@ -0,0 +1,128 @@
+/**
+ * Ledger-backed workspace router — the concrete `WorkspaceRouter` that ties
+ * the ledger's anchor index, the namespace codec, and the provider registry
+ * together. Any provider can be routed through this router with zero SSH
+ * knowledge: a session cwd inside a workspace's anchor resolves to that
+ * workspace's provider connection; an explicit `wfs://…` (or legacy `ssh:…`)
+ * target key resolves to the owning connection.
+ *
+ * The router opens connections lazily and caches them per workspace id;
+ * removed workspaces drop their connections so stale keys fail closed.
+ *
+ * @module @tiphareth/dsh-hardssh/base/ledger-router
+ */
+
+import type { WorkspaceConnection, WorkspaceRecord } from './model.ts'
+import { defaultNamespaceCodec, type WorkspaceNamespaceCodec, type WorkspaceRoute } from './namespace.ts'
+import type { WorkspaceRegistry } from './registry.ts'
+import { isPathUnderAnchor, normalizeAnchorPath, type WorkspaceLedger } from './ledger.ts'
+import type { WorkspaceResolution, WorkspaceRouter } from './router.ts'
+
+/** Open-or-reuse strategy for workspace connections. */
+export interface LedgerRouterOptions {
+  codec?: WorkspaceNamespaceCodec
+  /** Called with the record; resolves to a connection (undefined = cannot open). */
+  open(record: WorkspaceRecord, signal?: AbortSignal): Promise<WorkspaceConnection | undefined>
+  /** Called when a workspace is removed (drop cache / pool leases). */
+  onRemoved?(workspaceId: string): void
+}
+
+/** Ledger + registry based router. */
+export class LedgerWorkspaceRouter implements WorkspaceRouter {
+  readonly codec: WorkspaceNamespaceCodec
+  private readonly connections = new Map<string, WorkspaceConnection>()
+  private readonly anchors: Array<{ anchor: string; record: WorkspaceRecord }> = []
+
+  constructor(
+    private readonly ledger: WorkspaceLedger,
+    private readonly registry: WorkspaceRegistry,
+    private readonly options: LedgerRouterOptions,
+  ) {
+    this.codec = options.codec ?? defaultNamespaceCodec
+    this.reindex()
+    // Keep the anchor index fresh on every ledger commit.
+    this.ledger.subscribe(() => this.reindex())
+  }
+
+  private reindex(): void {
+    const snapshot = this.ledger.snapshotSync()
+    const seen = new Set<string>()
+    const anchors: Array<{ anchor: string; record: WorkspaceRecord }> = []
+    for (const record of snapshot.records) {
+      seen.add(record.id.toLowerCase())
+      if (record.anchor !== undefined) {
+        anchors.push({ anchor: normalizeAnchorPath(record.anchor.path), record })
+      }
+    }
+    anchors.sort((a, b) => b.anchor.length - a.anchor.length)
+    this.anchors.length = 0
+    this.anchors.push(...anchors)
+    // Drop connections of removed workspaces (fail-closed on stale keys).
+    for (const id of [...this.connections.keys()]) {
+      if (!seen.has(id.toLowerCase())) {
+        const connection = this.connections.get(id)
+        this.connections.delete(id)
+        this.options.onRemoved?.(id)
+        void connection?.close().catch(() => undefined)
+      }
+    }
+  }
+
+  private async openFor(record: WorkspaceRecord, signal?: AbortSignal): Promise<WorkspaceConnection | undefined> {
+    const id = record.id
+    const existing = this.connections.get(id)
+    if (existing !== undefined) return existing
+    const opened = await this.options.open(record, signal)
+    if (opened !== undefined) this.connections.set(id, opened)
+    return opened
+  }
+
+  fromNamespace(key: string): WorkspaceResolution | undefined {
+    const route = this.codec.decode(key)
+    if (route === undefined) return undefined
+    const resolution = this.resolveRoute(route)
+    if (resolution === undefined) return undefined
+    // Preserve the raw path as the raw key.
+    return { ...resolution, rawKey: route.path }
+  }
+
+  fromAnchor(cwd: string | undefined): WorkspaceConnection | undefined {
+    if (cwd === undefined || cwd === '') return undefined
+    for (const { anchor, record } of this.anchors) {
+      if (isPathUnderAnchor(anchor, cwd)) {
+        // Synchronous best-effort: return a cached connection; opening is async.
+        const existing = this.connections.get(record.id)
+        if (existing !== undefined) return existing
+        // Keep routing crisp: the runtime pre-opens active records; a miss
+        // here simply means the DSH adapter awaits openFor at mount time.
+        return undefined
+      }
+    }
+    return undefined
+  }
+
+  resolveRoute(route: WorkspaceRoute): WorkspaceResolution | undefined {
+    const record = this.ledger.snapshotSync().records.find(candidate => candidate.id === route.workspaceId)
+    if (record === undefined) return undefined
+    const connection = this.connections.get(record.id)
+    if (connection === undefined) return undefined
+    return { connection, rawKey: route.path }
+  }
+
+  /** Async open used by the adapter at mount time (pre-warm active records). */
+  async ensureOpen(record: WorkspaceRecord, signal?: AbortSignal): Promise<WorkspaceConnection | undefined> {
+    return this.openFor(record, signal)
+  }
+
+  /** All currently cached connections (for lifecycle/teardown). */
+  connectionsSnapshot(): WorkspaceConnection[] {
+    return [...this.connections.values()]
+  }
+
+  /** Close every cached connection (plugin teardown). */
+  async closeAll(): Promise<void> {
+    const connections = [...this.connections.values()]
+    this.connections.clear()
+    await Promise.all(connections.map(connection => connection.close().catch(() => undefined)))
+  }
+}

package/src/base/ledger.ts

@@ -0,0 +1,299 @@
+/**
+ * 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
+ */
+
+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'
+
+/** One committed ledger snapshot. */
+export interface LedgerSnapshot {
+  revision: number
+  records: readonly WorkspaceRecord[]
+}
+
+/** One committed mutation delivered to subscribers. */
+export type LedgerChange =
+  | { type: 'created'; revision: number; record: WorkspaceRecord }
+  | { type: 'renamed'; revision: number; before: WorkspaceRecord; record: WorkspaceRecord }
+  | { type: 'removed'; revision: number; record: WorkspaceRecord }
+
+export type LedgerListener = (change: LedgerChange) => void
+
+type LedgerChangeWithoutRevision =
+  | { type: 'created'; record: WorkspaceRecord }
+  | { type: 'renamed'; before: WorkspaceRecord; record: WorkspaceRecord }
+  | { type: 'removed'; record: WorkspaceRecord }
+
+/** Normalize an anchor for comparison (Windows case-insensitive; POSIX not). */
+export function normalizeAnchorPath(path: string): string {
+  const windowsStyle = /^[a-zA-Z]:[\\/]/.test(path) || path.includes('\\')
+  if (windowsStyle) {
+    const normalized = path.replace(/\//g, '\\')
+    const rootLength = /^[a-zA-Z]:\\/.test(normalized) ? 3 : 0
+    return trimTrailing(normalized, rootLength).toLowerCase()
+  }
+  const rootLength = path.startsWith('/') ? 1 : 0
+  return trimTrailing(path, rootLength)
+}
+
+/** True when `candidate` equals `anchor` or is one of its descendants (lexical). */
+export function isPathUnderAnchor(anchor: string, candidate: string): boolean {
+  const normAnchor = normalizeAnchorPath(anchor)
+  const normCandidate = normalizeAnchorPath(candidate)
+  if (normCandidate === normAnchor) return true
+  const sep = normAnchor.includes('\\') ? '\\' : '/'
+  const prefix = normAnchor.endsWith(sep) ? normAnchor : `${normAnchor}${sep}`
+  return normCandidate.startsWith(prefix)
+}
+
+function trimTrailing(path: string, minimumLength: number): string {
+  let end = path.length
+  while (end > minimumLength && (path[end - 1] === '/' || path[end - 1] === '\\')) end -= 1
+  return path.slice(0, end)
+}
+
+/**
+ * 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.
+ */
+export class WorkspaceLedger {
+  private records: WorkspaceRecord[] | undefined
+  private loadPromise: Promise<void> | undefined
+  private anchorIndex: Array<{ anchor: string; record: WorkspaceRecord }> = []
+  private mutationTail: Promise<void> = Promise.resolve()
+  private currentRevision = 0
+  private readonly listeners = new Set<LedgerListener>()
+
+  constructor(
+    private readonly fileOverride?: string,
+    private readonly anchorOverride?: string,
+  ) {}
+
+  private file(): string { return this.fileOverride ?? '' }
+  private anchors(): string { return this.anchorOverride ?? '' }
+
+  private async ensureLoaded(): Promise<void> {
+    if (this.records !== undefined) return
+    if (this.loadPromise === undefined) this.loadPromise = this.readRecords()
+    await this.loadPromise
+  }
+
+  private async readRecords(): Promise<void> {
+    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 = []
+    }
+    this.reindex()
+  }
+
+  private reindex(): void {
+    this.anchorIndex = (this.records ?? [])
+      .filter(record => record.anchor !== undefined)
+      .map(record => ({ anchor: normalizeAnchorPath(record.anchor!.path), record }))
+      .sort((a, b) => b.anchor.length - a.anchor.length)
+  }
+
+  private async save(nextRecords: readonly WorkspaceRecord[]): Promise<void> {
+    const target = this.file()
+    if (target === '') throw new Error('WorkspaceLedger: no persistence file configured')
+    await mkdir(join(target, '..'), { recursive: true })
+    const temporary = `${target}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`
+    try {
+      await writeFile(temporary, JSON.stringify(nextRecords, null, 2), 'utf8')
+      await renameFile(temporary, target)
+    } catch (error) {
+      await rm(temporary, { force: true }).catch(() => undefined)
+      throw error
+    }
+  }
+
+  private enqueueMutation<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.mutationTail.then(operation)
+    this.mutationTail = result.then(() => undefined, () => undefined)
+    return result
+  }
+
+  private commit(nextRecords: WorkspaceRecord[], change: LedgerChangeWithoutRevision): void {
+    this.records = nextRecords
+    this.reindex()
+    this.currentRevision += 1
+    this.emit({ ...change, revision: this.currentRevision } as LedgerChange)
+  }
+
+  private emit(change: LedgerChange): void {
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(cloneChange(change))
+      } catch (error) {
+        console.warn('[dsh-workspace] ledger subscriber failed:', error instanceof Error ? error.message : String(error))
+      }
+    }
+  }
+
+  async load(): Promise<WorkspaceRecord[]> {
+    await this.ensureLoaded()
+    return cloneRecords(this.records ?? [])
+  }
+
+  async list(): Promise<WorkspaceRecord[]> {
+    await this.ensureLoaded()
+    return cloneRecords(this.records ?? [])
+  }
+
+  async snapshot(): Promise<LedgerSnapshot> {
+    await this.ensureLoaded()
+    return { revision: this.currentRevision, records: cloneRecords(this.records ?? []) }
+  }
+
+  snapshotSync(): LedgerSnapshot {
+    return { revision: this.currentRevision, records: this.records ?? [] }
+  }
+
+  revision(): number {
+    return this.currentRevision
+  }
+
+  subscribe(listener: LedgerListener): () => void {
+    this.listeners.add(listener)
+    let disposed = false
+    return () => {
+      if (disposed) return
+      disposed = true
+      this.listeners.delete(listener)
+    }
+  }
+
+  async get(id: string): Promise<WorkspaceRecord | undefined> {
+    await this.ensureLoaded()
+    const record = this.records?.find(candidate => candidate.id === id)
+    return record === undefined ? undefined : cloneRecord(record)
+  }
+
+  async findByAnchor(path: string): Promise<WorkspaceRecord | undefined> {
+    await this.ensureLoaded()
+    return this.findByAnchorSync(path)
+  }
+
+  findByAnchorSync(path: string): WorkspaceRecord | undefined {
+    const canonical = safeRealpathSync(path)
+    if (canonical === undefined) return undefined
+    for (const { anchor, record } of this.anchorIndex) {
+      if (isPathUnderAnchor(anchor, canonical)) return cloneRecord(record)
+    }
+    return undefined
+  }
+
+  /** Create a record: materialize the anchor (managed mode), persist, commit. */
+  async create(input: Omit<WorkspaceRecord, 'id' | 'createdAt' | 'updatedAt'> & { id?: string }): Promise<WorkspaceRecord> {
+    return this.enqueueMutation(async () => {
+      await this.ensureLoaded()
+      const now = new Date().toISOString()
+      const id = input.id ?? randomUUID()
+      const record: WorkspaceRecord = {
+        schemaVersion: input.schemaVersion,
+        id,
+        title: input.title,
+        provider: input.provider,
+        location: input.location,
+        anchor: input.anchor,
+        createdAt: now,
+        updatedAt: now,
+        labels: input.labels,
+        extensions: input.extensions,
+      }
+      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)
+    })
+  }
+
+  async rename(id: string, title: string): 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 nextRecords = [...records]
+      nextRecords[index] = record
+      await this.save(nextRecords)
+      this.commit(nextRecords, { type: 'renamed', before, record })
+      return cloneRecord(record)
+    })
+  }
+
+  /** Remove a record. The anchor directory is left in place (caller decides). */
+  async remove(id: string): Promise<boolean> {
+    return this.enqueueMutation(async () => {
+      await this.ensureLoaded()
+      const records = this.records ?? []
+      const index = records.findIndex(record => record.id === id)
+      if (index < 0) return false
+      const record = records[index]
+      const nextRecords = [...records.slice(0, index), ...records.slice(index + 1)]
+      await this.save(nextRecords)
+      this.commit(nextRecords, { type: 'removed', record })
+      return true
+    })
+  }
+
+  anchorsRoot(): string {
+    return this.anchors()
+  }
+}
+
+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'
+}
+
+function safeRealpathSync(path: string): string | undefined {
+  try { return realpathSync(path) } catch { return undefined }
+}
+
+function cloneRecord(record: WorkspaceRecord): WorkspaceRecord {
+  return { ...record, provider: { ...record.provider }, location: { ...record.location } }
+}
+
+function cloneRecords(records: readonly WorkspaceRecord[]): WorkspaceRecord[] {
+  return records.map(cloneRecord)
+}
+
+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 'removed': return { ...change, record: cloneRecord(change.record) }
+  }
+}

package/src/base/model.ts

@@ -0,0 +1,118 @@
+/**
+ * The generic workspace model — the platform-neutral core of the workspace
+ * base. A `WorkspaceRecord` describes ONE bound workspace: a local anchor
+ * directory (what sessions see as their cwd) mapped to a location on some
+ * provider (local disk, SSH host, container, object store, …). The record
+ * never holds secrets — only references into a provider-managed credential
+ * store.
+ *
+ * Everything in this module is provider-agnostic: it imports no SSH, no
+ * Cordis, no React, and no `@deepseek-ai/*` runtime package.
+ *
+ * @module @tiphareth/dsh-hardssh/base/model
+ */
+
+/** Opaque workspace id (uuid or provider-assigned). */
+export type WorkspaceId = string
+
+/** A connection reference into a provider's own credential/config store. */
+export interface ConnectionRef {
+  /** Provider-local stable id (e.g. the SSH host record id). */
+  id: string
+  /** Optional display alias kept for humans; never used as identity. */
+  alias?: string
+}
+
+/** Identifies which provider owns a workspace and how to reach its config. */
+export interface WorkspaceProviderRef {
+  /** Provider type id: 'local' | 'ssh' | 'docker' | 'wsl' | … (registry key). */
+  id: string
+  /** Optional multiple-config instance within one provider. */
+  instanceId?: string
+  /** Reference into the provider's credential/config store (no secrets). */
+  connectionRef?: ConnectionRef
+}
+
+/** Where a workspace lives, interpreted by its provider. */
+export interface WorkspaceLocation {
+  /** Path kind: 'native' | 'posix' | 'uri' | 'object-prefix' | … */
+  kind: string
+  /** Provider-specific root (e.g. /srv/repo, C:\repo, bucket/prefix). */
+  root: string
+  /** Provider-defined options; must be JSON-serializable. No secrets. */
+  options?: Record<string, unknown>
+}
+
+/** How the workspace is anchored on the local host (the session-visible dir). */
+export interface WorkspaceAnchor {
+  /** Absolute local anchor directory path. */
+  path: string
+  /** 'managed' = base owns a dir under its anchor root; 'existing' = user dir. */
+  mode: 'managed' | 'existing'
+}
+
+/** One persisted workspace record. */
+export interface WorkspaceRecord {
+  /** Schema identifier so future migrations can be detected. */
+  schemaVersion: number
+  id: WorkspaceId
+  /** Human-readable sidebar title. */
+  title: string
+  provider: WorkspaceProviderRef
+  location: WorkspaceLocation
+  anchor?: WorkspaceAnchor
+  createdAt: string
+  updatedAt: string
+  /** Free-form labels (env, team, …). */
+  labels?: Record<string, string>
+  /** Provider/feature extension bag. Never holds secrets. */
+  extensions?: Record<string, unknown>
+}
+
+/** One provider capability key (extensible via module augmentation). */
+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
+}
+
+/** A resolved, open connection to one workspace's provider. */
+export interface WorkspaceConnection {
+  readonly workspaceId: WorkspaceId
+  readonly providerId: string
+  /** Fetch a capability; undefined when this provider does not offer it. */
+  get<K extends keyof WorkspaceCapabilityMap>(capability: K): WorkspaceCapabilityMap[K] | undefined
+  /** Connection lifecycle status. */
+  status(): 'connecting' | 'ready' | 'degraded' | 'closed'
+  /** Release every resource (connections, pool leases, PTYs). Idempotent. */
+  close(): Promise<void>
+}
+
+/** Context handed to a provider when opening a workspace. */
+export interface WorkspaceOpenContext {
+  signal?: AbortSignal
+  logger?: Pick<Console, 'warn' | 'error' | 'info' | 'debug'>
+}
+
+/** The interface every workspace provider implements. */
+export interface WorkspaceProvider {
+  /** Static identity (registry key, capabilities, display name). */
+  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>
+}
+
+/** Static provider identity, checked before any plugin code runs. */
+export interface WorkspaceProviderManifest {
+  /** Provider type id (registry key; unique across the deployment). */
+  id: string
+  version: string
+  /** Compatibility gate: big-version mismatches refuse to load. */
+  apiVersion: number
+  displayName: string
+  /** Capabilities this provider implements. */
+  capabilities: Array<keyof WorkspaceCapabilityMap | string>
+}

package/src/base/namespace.ts

@@ -0,0 +1,102 @@
+/**
+ * Workspace namespace codec — how a routable target key is encoded.
+ *
+ * New format is a URI style that carries ONLY the workspace id and the
+ * provider-agnostic path:
+ *
+ *   wfs://<encoded-workspace-id>/<path>
+ *
+ * - The workspace id survives provider migration (ssh → container → …), so
+ *   a key never needs re-routing when a workspace changes providers.
+ * - It cannot collide with Windows drive paths (`C:\…`) or bare POSIX paths.
+ * - It contains no provider name, so the switch layer never branches on
+ *   "which provider" — only on "which workspace".
+ *
+ * The legacy SSH format (`ssh:<recordId>:`) is still accepted (decode only)
+ * so existing persisted targets keep resolving during the migration window.
+ *
+ * @module @tiphareth/dsh-hardssh/base/namespace
+ */
+
+/** The URI scheme used for explicit workspace-namespaced target keys. */
+export const WFS_SCHEME = 'wfs:' as const
+
+/** ASCII-encode a workspace id for safe embedding in a URL-ish key. */
+export function encodeWorkspaceId(id: string): string {
+  return encodeURIComponent(id)
+}
+
+/** Decode a workspace id back from its encoded form. */
+export function decodeWorkspaceId(encoded: string): string {
+  return decodeURIComponent(encoded)
+}
+
+/** One parsed route: which workspace, and the raw path inside it. */
+export interface WorkspaceRoute {
+  workspaceId: string
+  /** The path portion as it appeared (provider-relative). */
+  path: string
+}
+
+/** Namespace codec contract (make the switch layer provider-agnostic). */
+export interface WorkspaceNamespaceCodec {
+  encode(route: WorkspaceRoute): string
+  decode(input: string): WorkspaceRoute | undefined
+  /** True when `input` is an explicit workspace namespace (not a plain path). */
+  isExplicitNamespace(input: string): boolean
+}
+
+/**
+ * Encode a route as `wfs://<id>/<path>`. A leading slash on the path is
+ * preserved after the namespace marker.
+ */
+export function encodeRoute(route: WorkspaceRoute): string {
+  const path = route.path.startsWith('/') ? route.path : `/${route.path}`
+  return `${WFS_SCHEME}//${encodeWorkspaceId(route.workspaceId)}${path}`
+}
+
+/** Decode a `wfs://<id>/<path>` key (strict). */
+export function decodeWfsKey(input: string): WorkspaceRoute | undefined {
+  if (!input.startsWith(`${WFS_SCHEME}//`)) return undefined
+  const rest = input.slice(`${WFS_SCHEME}//`.length)
+  const separator = rest.indexOf('/')
+  if (separator < 0) return undefined
+  const encodedId = rest.slice(0, separator)
+  if (encodedId === '') return undefined
+  let workspaceId: string
+  try {
+    workspaceId = decodeWorkspaceId(encodedId)
+  } catch {
+    return undefined
+  }
+  const path = rest.slice(separator)
+  return { workspaceId, path }
+}
+
+/**
+ * Decode a legacy `ssh:<recordId>:<key>` key. Kept during the migration
+ * window so persisted remote targets keep resolving; the record id maps to
+ * the workspace id 1:1 (old record ids ARE the workspace ids).
+ */
+export function decodeLegacySshKey(input: string): WorkspaceRoute | undefined {
+  if (!input.startsWith('ssh:')) return undefined
+  const rest = input.slice('ssh:'.length)
+  const end = rest.indexOf(':')
+  if (end <= 0) return undefined
+  const recordId = rest.slice(0, end)
+  return { workspaceId: recordId, path: rest.slice(end + 1) }
+}
+
+/**
+ * The default codec: emits `wfs://…` and accepts both `wfs://…` and legacy
+ * `ssh:<id>:…`.
+ */
+export const defaultNamespaceCodec: WorkspaceNamespaceCodec = {
+  encode: encodeRoute,
+  decode(input: string): WorkspaceRoute | undefined {
+    return decodeWfsKey(input) ?? decodeLegacySshKey(input)
+  },
+  isExplicitNamespace(input: string): boolean {
+    return input.startsWith(WFS_SCHEME) || input.startsWith('ssh:')
+  },
+}