dsh-tower 2.1.0-beta.1 → 2.3.0

package/{lib → host}/tool-registry.js

@@ -14,8 +14,15 @@ import {
   isTowerRole,
   isUnknownRole,
 } from '../domain/vocabulary.js'
-import { git, resolveRepo, hasAnyCommit } from './git.js'
+import { git, resolveRepo, hasAnyCommit } from '../adapters/git.js'
 import { runtimeConfig } from './config.js'
+import { runDoctor } from './doctor.js'
+import { createHmrBridge } from './hmr.js'
+import { assertPresetsAvailable } from './presets.js'
+import { readStateLock } from '../adapters/store.js'
+import { lockTiming } from '../adapters/persistence.js'
+import { acquireLease, releaseLease, inspectLeases } from '../adapters/leases.js'
+import { importLegacySnapshot, validateLegacyMap } from '../adapters/legacy.js'
 import { registerDoctorTool } from '../tools/doctor.js'
 import { registerRecoverTool } from '../tools/recover.js'
 import { registerTestTool } from '../tools/test.js'
@@ -43,10 +50,12 @@ import { registerSpawnTool } from '../tools/spawn.js'
 import { registerCompleteTool } from '../tools/complete.js'
 import { registerFindingTool } from '../tools/finding.js'
 import { registerFindingsTool } from '../tools/findings.js'
-import { readDiscoveryConfig, normalizeDiscovery, runDiscovery } from './tests.js'
+import { readDiscoveryConfig, normalizeDiscovery, runDiscovery } from '../adapters/tests.js'
 import { summarize as summarizeBatch } from '../domain/batch.js'
+import { assertPorts } from '../ports/index.js'
 import path from 'node:path'
 import { fsp } from '../adapters/store-fs.js'
+import { createDefaultDeps } from '../adapters/default.js'
 import crypto from 'node:crypto'
 
 // Mutable composition state is grouped in one const object: the registration
@@ -54,6 +63,41 @@ import crypto from 'node:crypto'
 const runtimeState = {
   workspaceHook: null,
   hmrBridge: null,
+  // #69: the host entry builds the adapter set once and passes it in. The lazy
+  // fallback is for tests/embedders that call registerTowerTools() directly;
+  // it is still built once per process.
+  deps: null,
+  // #84: the defined tool names are recorded before the exposure switches run,
+  // so the concept budget measures the full surface rather than one profile's
+  // subset. The number is reported by tower_doctor and compared with the
+  // committed scripts/surface-baseline.json.
+  definedTools: new Set(),
+}
+
+/** The full defined tool surface (names, sorted), independent of exposure flags. */
+export function definedToolNames() {
+  return [...runtimeState.definedTools].sort()
+}
+
+/** The number of tools defined by this build, used by the concept budget (#84). */
+export function definedToolCount() {
+  return runtimeState.definedTools.size
+}
+
+/** The injected port set for the app layer (built once per process). */
+function towerDeps() {
+  if (!runtimeState.deps) runtimeState.deps = createDefaultDeps()
+  return runtimeState.deps
+}
+
+/** Compose the app Tower with the injected ports (never a bare adapter import). */
+function openTower(repoRoot) {
+  return Tower.open(repoRoot, towerDeps())
+}
+
+/** Build a Tower with an explicit config for the read-only doctor path. */
+function createTower(repo, config) {
+  return new Tower(repo, config, towerDeps())
 }
 
 function normalizeToolArgs(args, aliases = {}) {
@@ -324,6 +368,9 @@ function plainSchema(value) {
  */
 function define(ctx, definition) {
   const { aliases, requiresMissionId, board, execute, ...rest } = definition
+  // Record the definition before the exposure gate: the concept budget counts
+  // the tools this build can register, not only the ones a profile exposes.
+  runtimeState.definedTools.add(rest.name)
   const toolsConfig = runtimeConfig().tools ?? {}
   const flag = OPERATIONAL_TOOLS.get(rest.name)
   if (flag && (toolsConfig.exposeOperational === false || toolsConfig[flag] === false)) return
@@ -364,7 +411,7 @@ function define(ctx, definition) {
         }
         if (board === true && typeof normalized.repoRoot === 'string') {
           try {
-            const opened = await Tower.open(normalized.repoRoot)
+            const opened = await openTower(normalized.repoRoot)
             await opened.writeBoard()
           } catch {
             // board output is best effort
@@ -451,6 +498,24 @@ async function observeActivity(ctx, tower) {
 export function registerTowerTools(ctx, options = {}) {
   runtimeState.workspaceHook = options.workspace ?? null
   runtimeState.hmrBridge = options.hmrBridge ?? null
+  // #69: the host entry (index.js) is the composition root. When it supplies the
+  // port set, adopt it — validated once — instead of constructing a second set
+  // here. Tests/embedders that omit deps fall back to one lazily built set.
+  // #75: the event port is bound here to the live Cordis emitter; emitting is
+  // best effort so a listener can never fail the tool that produced the fact.
+  const baseDeps = options.deps ? assertPorts(options.deps) : (runtimeState.deps ?? createDefaultDeps())
+  runtimeState.deps = {
+    ...baseDeps,
+    events: {
+      emit(name, payload) {
+        try {
+          ctx.emit?.(name, payload)
+        } catch {
+          // events are an optional side channel; never fail a tool for them
+        }
+      },
+    },
+  }
   // A lightweight roster watchdog: the authoritative activity comes from the
   // subagents catalog; a missing observation after spawn.staleMs is marked
   // stale (never silently treated as stopped) and blocks merge via the gate.
@@ -460,7 +525,7 @@ export function registerTowerTools(ctx, options = {}) {
       try {
         if (!ctx.get('subagents')) return
         for (const repoRoot of [...WATCHED_REPOS]) {
-          const tower = await Tower.open(repoRoot)
+          const tower = await openTower(repoRoot)
           const view = await tower.rosterView()
           const live = view.roster.filter((entry) => !ROSTER_INACTIVE_STATES.includes(entry.state))
           if (live.length === 0) { WATCHED_REPOS.delete(repoRoot); continue }
@@ -481,59 +546,69 @@ export function registerTowerTools(ctx, options = {}) {
   }, watchMs)
   timer.unref?.()
   ctx.effect(() => () => clearInterval(timer))
-  registerInitTool(ctx, { define, actorFor, requireTowerActor, workspaceHook: runtimeState.workspaceHook, ensureRepository })
+  registerInitTool(ctx, { openTower, define, actorFor, requireTowerActor, workspaceHook: runtimeState.workspaceHook, ensureRepository, resolveRepo, runtimeConfig })
 
-  registerPlanTool(ctx, { define, actorFor, requireTowerActor })
+  registerPlanTool(ctx, { openTower, define, actorFor, requireTowerActor, assertPresetsAvailable })
 
-  registerMissionTool(ctx, { define, actorFor, requireKnownActor })
+  registerMissionTool(ctx, { openTower, define, actorFor, requireKnownActor })
 
-  registerStatusTool(ctx, { define, workspaceHook: runtimeState.workspaceHook, spawnBackoffView, observeActivity })
+  registerStatusTool(ctx, { openTower, define, workspaceHook: runtimeState.workspaceHook, spawnBackoffView, observeActivity })
 
-  registerSpawnTool(ctx, { define, actorFor, requireTowerActor, enqueueSpawn, observeActivity, spawnBackoffState, spawnBackoffView, recordSpawnThrottle, recordSpawnSuccess, runMissionDiscovery, textOf })
+  registerSpawnTool(ctx, { openTower, define, actorFor, requireTowerActor, enqueueSpawn, observeActivity, spawnBackoffState, spawnBackoffView, recordSpawnThrottle, recordSpawnSuccess, runMissionDiscovery, textOf, inspectLeases })
 
-  registerRosterTool(ctx, { define, workspaceHook: runtimeState.workspaceHook, observeActivity, actorFor, requireTowerActor, interruptRosterAgent })
+  registerRosterTool(ctx, { openTower, define, workspaceHook: runtimeState.workspaceHook, observeActivity, actorFor, requireTowerActor, interruptRosterAgent })
 
-  registerInterruptTool(ctx, { define, actorFor, requireTowerActor, interruptRosterAgent })
+  registerInterruptTool(ctx, { openTower, define, actorFor, requireTowerActor, interruptRosterAgent })
 
-  registerDiffTool(ctx, { define, actorFor, requireTowerActor })
+  registerDiffTool(ctx, { openTower, define, actorFor, requireTowerActor })
 
-  registerAdoptTool(ctx, { define, actorFor, requireTowerActor })
+  registerAdoptTool(ctx, { openTower, define, actorFor, requireTowerActor })
 
-  registerSendTool(ctx, { define, actorFor, checkSendRate })
+  registerSendTool(ctx, { openTower, define, actorFor, checkSendRate })
 
-  registerInboxTool(ctx, { define })
+  registerInboxTool(ctx, { openTower, define })
 
-  registerCompleteTool(ctx, { define, runMissionDiscovery })
+  registerCompleteTool(ctx, { openTower, define, runMissionDiscovery })
 
-  registerFindingTool(ctx, { define, actorFor, requireKnownActor })
+  registerFindingTool(ctx, { openTower, define, actorFor, requireKnownActor })
 
-  registerFindingsTool(ctx, { define, actorFor, requireKnownActor })
+  registerFindingsTool(ctx, { openTower, define, actorFor, requireKnownActor })
 
-  registerReviewTool(ctx, { define, actorFor })
+  registerReviewTool(ctx, { openTower, define, actorFor })
 
-  registerPreflightTool(ctx, { define, observeActivity })
+  registerPreflightTool(ctx, { openTower, define, observeActivity })
 
-  registerMergeTool(ctx, { define, actorFor, requireTowerActor, observeActivity })
+  registerMergeTool(ctx, { openTower, define, actorFor, requireTowerActor, observeActivity })
 
-  registerRebaseTool(ctx, { define, actorFor, requireTowerActor, observeActivity })
+  registerRebaseTool(ctx, { openTower, define, actorFor, requireTowerActor, observeActivity })
 
-  registerTeardownTool(ctx, { define, actorFor, requireTowerActor, observeActivity })
+  registerTeardownTool(ctx, { openTower, define, actorFor, requireTowerActor, observeActivity })
 
-  registerDoctorTool(ctx, define)
+  registerDoctorTool(ctx, {
+    openTower,
+    define,
+    createTower,
+    resolveRepo,
+    runtimeConfig,
+    runDoctor,
+    // #84: the doctor reports the live surface; the count is the full defined
+    // tool surface, independent of which operational switches this profile uses.
+    surface: () => ({ tools: definedToolCount() }),
+  })
 
-  registerRecoverTool(ctx, { define, actorFor, requireTowerActor })
+  registerRecoverTool(ctx, { openTower, define, actorFor, requireTowerActor, readStateLock, lockTiming })
 
-  registerTestTool(ctx, { define, actorFor, requireKnownActor, runMissionDiscovery })
+  registerTestTool(ctx, { openTower, define, actorFor, requireKnownActor, runMissionDiscovery })
 
-  registerBatchTool(ctx, { define, actorFor, requireTowerActor, summarizeBatch, verifyBatchReceiptFiles })
+  registerBatchTool(ctx, { openTower, define, actorFor, requireTowerActor, summarizeBatch, verifyBatchReceiptFiles })
 
-  registerResourceTool(ctx, { define, actorFor, requireTowerActor })
+  registerResourceTool(ctx, { openTower, define, actorFor, requireTowerActor, acquireLease, releaseLease, inspectLeases })
 
-  registerImportLegacyTool(ctx, { define, actorFor, requireTowerActor })
+  registerImportLegacyTool(ctx, { openTower, define, actorFor, requireTowerActor, importLegacySnapshot })
 
-  registerLegacyMapTool(ctx, { define, actorFor, requireTowerActor })
+  registerLegacyMapTool(ctx, { openTower, define, actorFor, requireTowerActor, validateLegacyMap })
 
-  registerReloadTool(ctx, { define, actorFor, requireTowerActor, sharedHmrBridge: runtimeState.hmrBridge })
+  registerReloadTool(ctx, { openTower, define, actorFor, requireTowerActor, sharedHmrBridge: runtimeState.hmrBridge, runtimeConfig, createHmrBridge })
 }
 
 export const __testSpawnBackoff = {

package/host/tower.js

@@ -0,0 +1,32 @@
+// Default-deps binding of the Tower app service (#69).
+//
+// The composition root (index.js / host/tool-registry.js) builds one deps object
+// and injects it into the app layer. This module is the convenience binding for
+// embedders and tests that want the process-default adapters; it is the only
+// host/ module besides tool-registry.js that knows the default adapter set.
+//
+// Object layout supplied here is memoised in adapters/default.js, so every
+// caller shares the same adapter instances.
+import { Tower as InjectedTower } from '../app/tower.js'
+import { defaultDeps } from '../adapters/default.js'
+
+export class Tower extends InjectedTower {
+  /**
+   * @param {{ root: string, commonDir: string, branch?: string | null }} repo
+   * @param {import('../types/index.js').TowerConfig} [config]
+   * @param {Record<string, any>} [deps]
+   */
+  constructor(repo, config, deps = defaultDeps) {
+    super(repo, config, deps)
+  }
+
+  /**
+   * @param {string} repoRoot
+   * @param {Record<string, any>} [deps]
+   */
+  static async open(repoRoot, deps = defaultDeps) {
+    const repo = await deps.vcs.resolveRepo(repoRoot)
+    const config = await deps.config.resolveRepoConfig(repo)
+    return new Tower(repo, config, deps)
+  }
+}

package/index.js

@@ -12,21 +12,22 @@
 // plugin from disk when the HMR service is present (dev/linked installs).
 import fs from 'node:fs'
 import { randomUUID } from 'node:crypto'
-import { registerTowerTools } from './lib/tool-registry.js'
-import { loadModes, saveModes, storePath } from './lib/modeStore.js'
-import { ModeState } from './lib/modeState.js'
-import { Config as ConfigSchema, DEFAULT_DENY_TOOLS, configureRuntime, runtimeConfig } from './lib/config.js'
+import { registerTowerTools } from './host/tool-registry.js'
+import { createDefaultDeps } from './adapters/default.js'
+import { loadModes, saveModes, storePath } from './host/modeStore.js'
+import { ModeState } from './host/modeState.js'
+import { Config as ConfigSchema, DEFAULT_DENY_TOOLS, configureRuntime, runtimeConfig } from './host/config.js'
 import { TowerToolError } from './domain/errors.js'
-import { resolveRepo } from './lib/git.js'
+import { resolveRepo } from './adapters/git.js'
 import {
   acquireWorkspaceLock,
   inspectWorkspaceLock,
   releaseWorkspaceLock,
   touchWorkspaceLock,
   workspaceLockToken,
-} from './lib/workspaceLock.js'
-import { createHmrBridge } from './lib/hmr.js'
-import { assertPresetsAvailable } from './lib/presets.js'
+} from './adapters/workspaceLock.js'
+import { createHmrBridge } from './host/hmr.js'
+import { assertPresetsAvailable } from './host/presets.js'
 
 export const name = 'dsh-tower'
 export const inject = ['tools', 'systemPrompt']
@@ -343,7 +344,9 @@ export function apply(ctx, rawConfig) {
     },
   }
 
-  registerTowerTools(ctx, { workspace, hmrBridge })
+  // #69: the host entry is the composition root — the adapters are constructed
+  // once here and injected into the tool layer and every Tower instance.
+  registerTowerTools(ctx, { workspace, hmrBridge, deps: createDefaultDeps() })
 
   // On dispose (including an HMR reload) release advisory workspace locks this
   // process still owns; a reloaded plugin restores the entries from modes.json.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tower",
-  "version": "2.1.0-beta.1",
+  "version": "2.3.0",
   "type": "module",
   "description": "DSH-native Tower: mission planning, worktree isolation, review-gated merges, and a human-owned Tower mode.",
   "license": "MIT",
@@ -41,7 +41,7 @@
     "reviewer.js",
     "skills.js",
     "skills/",
-    "lib/*.js",
+    "host/*.js",
     "domain/**/*.js",
     "app/*.js",
     "tools/*.js",
@@ -58,6 +58,7 @@
     "LICENSE",
     "CONTRIBUTING.md",
     "SECURITY.md",
+    "PRINCIPLES.md",
     "docs/",
     "ui-bundle/",
     "ports/*.js"
@@ -71,22 +72,28 @@
     "test": "node --test tests/*.test.mjs",
     "test:watch": "node --test --watch tests/*.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage tests/*.test.mjs",
+    "test:live": "node tests/live/run.cjs",
     "smoke:mount": "node scripts/mount-smoke.mjs",
     "smoke:fixtures": "node scripts/mount-smoke/fixtures.mjs",
     "release:check": "node scripts/release-check.mjs",
     "audit:issues": "node scripts/issue-audit.mjs",
+    "audit:regressions": "node scripts/regression-audit.mjs",
+    "surface:check": "node scripts/surface-baseline.mjs",
     "dev:hmr": "node scripts/enable-dev-hmr.mjs",
     "docs:check": "node scripts/check-docs.mjs",
+    "docs:check:philosophy": "node scripts/check-philosophy.mjs",
     "docs:generate:errors": "node scripts/generate-error-reference.mjs",
     "docs:check:generated": "node scripts/generate-error-reference.mjs --check",
     "docs:generate:tools": "node scripts/generate-tools-reference.mjs",
     "docs:check:generated:tools": "node scripts/generate-tools-reference.mjs --check",
     "docs:generate:config": "node scripts/generate-config-reference.mjs",
     "docs:check:generated:config": "node scripts/generate-config-reference.mjs --check",
+    "docs:generate:events": "node scripts/generate-events-reference.mjs",
+    "docs:check:generated:events": "node scripts/generate-events-reference.mjs --check",
     "pack:check": "node scripts/check-pack.mjs",
     "architecture:check": "node scripts/architecture.mjs",
     "types:check": "tsc --noEmit",
-    "check": "npm test && npm run docs:check && npm run pack:check && npm run architecture:check && npm run types:check && npm run domain:check",
+    "check": "npm test && npm run docs:check && npm run docs:check:philosophy && npm run docs:check:generated && npm run docs:check:generated:tools && npm run docs:check:generated:config && npm run docs:check:generated:events && npm run surface:check && npm run pack:check && npm run architecture:check && npm run types:check && npm run domain:check",
     "domain:metrics": "node scripts/domain-metrics.mjs",
     "domain:check": "node scripts/domain-metrics.mjs --check"
   },

package/ports/archive.js

@@ -0,0 +1,18 @@
+// Terminal-mission archive port (#69). The readers/writers are store-agnostic:
+// they take the store port and the Tower paths, so the same archive logic runs
+// on the filesystem adapter and on an in-memory store.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} ArchivePort
+ * @property {(store: unknown, paths: { dir: string }) => Promise<{ ok: boolean, file: string, missions: any[], error?: string, exists: boolean }>} readIndex
+ * @property {(store: unknown, paths: { dir: string }, missionId: string) => Promise<any>} readEntry
+ * @property {(store: unknown, paths: { dir: string }, input: { entries: any[], now?: number }) => Promise<any>} writeEntries
+ */
+
+export const ARCHIVE_PORT = definePort('ArchivePort', ['readIndex', 'readEntry', 'writeEntries'])
+
+/** @param {unknown} impl */
+export function assertArchivePort(impl) {
+  return /** @type {ArchivePort} */ (assertPort(impl, ARCHIVE_PORT, 'archive'))
+}

package/ports/caseSensitivity.js

@@ -0,0 +1,15 @@
+// Case-sensitivity probe port (#69). tower_init probes the checkout filesystem
+// once; a composition without a real filesystem injects its own answer.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} CaseSensitivityPort
+ * @property {(root: string) => Promise<boolean | null>} detect
+ */
+
+export const CASE_SENSITIVITY_PORT = definePort('CaseSensitivityPort', ['detect'])
+
+/** @param {unknown} impl */
+export function assertCaseSensitivityPort(impl) {
+  return /** @type {CaseSensitivityPort} */ (assertPort(impl, CASE_SENSITIVITY_PORT, 'caseSensitivity'))
+}

package/ports/clock.js

@@ -1,6 +1,14 @@
-// Clock port (#56).
+// Clock port (#69).
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} ClockPort
  * @property {() => number} now
  */
-export {}
+
+export const CLOCK_PORT = definePort('ClockPort', ['now'])
+
+/** @param {unknown} impl */
+export function assertClockPort(impl) {
+  return /** @type {ClockPort} */ (assertPort(impl, CLOCK_PORT, 'clock'))
+}

package/ports/config.js

@@ -0,0 +1,19 @@
+// Config port (#69).
+//
+// App use cases read the effective Tower config through this port. They do not
+// import host/config.js, so the process-level config store stays a property of
+// the composition root rather than a module-global dependency of the app.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} ConfigPort
+ * @property {() => import('../types/index.js').TowerConfig} runtimeConfig
+ * @property {(repo: { root: string, commonDir: string, branch?: string|null }) => Promise<import('../types/index.js').TowerConfig>} resolveRepoConfig
+ */
+
+export const CONFIG_PORT = definePort('ConfigPort', ['runtimeConfig', 'resolveRepoConfig'])
+
+/** @param {unknown} impl */
+export function assertConfigPort(impl) {
+  return /** @type {ConfigPort} */ (assertPort(impl, CONFIG_PORT, 'config'))
+}

package/ports/contract.js

@@ -0,0 +1,38 @@
+// Port contract primitives (#69).
+//
+// A port is a runtime-checkable contract, not only a JSDoc typedef: the
+// contract object is importable, and `assertPort` rejects a dependency object
+// that does not implement it. That is what makes the seam substitutable at
+// runtime instead of merely documented.
+export function definePort(name, methods) {
+  return Object.freeze({ name, methods: Object.freeze([...methods]) })
+}
+
+/**
+ * @param {unknown} impl
+ * @param {{ name: string, methods: readonly string[] }} contract
+ * @param {string} [label]
+ */
+export function assertPort(impl, contract, label = contract.name) {
+  if (!impl || typeof impl !== 'object') {
+    throw new TypeError(`${label}: expected an object implementing ${contract.name}`)
+  }
+  const missing = contract.methods.filter((method) => typeof (/** @type {any} */ (impl))[method] !== 'function')
+  if (missing.length > 0) {
+    throw new TypeError(`${label} does not implement ${contract.name}; missing: ${missing.join(', ')}`)
+  }
+  return impl
+}
+
+/**
+ * @param {unknown} impl
+ * @param {{ name: string, methods: readonly string[] }} contract
+ */
+export function implementsPort(impl, contract) {
+  try {
+    assertPort(impl, contract)
+    return true
+  } catch {
+    return false
+  }
+}

package/ports/events.js

@@ -0,0 +1,24 @@
+// Domain-event port (#75).
+//
+// The app layer persists a transition and then emits the domain events it
+// described through this port. The host binds it to Cordis `ctx.emit`; tests
+// bind it to a recorder. `emit` is best effort by contract: a listener (or a
+// missing service) must never fail the tool that produced the fact.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} EventPort
+ * @property {(name: string, payload: Record<string, any>) => void} emit
+ */
+
+export const EVENT_PORT = definePort('EventPort', ['emit'])
+
+/** @param {unknown} impl */
+export function assertEventPort(impl) {
+  return /** @type {EventPort} */ (assertPort(impl, EVENT_PORT, 'events'))
+}
+
+/** The no-op default: embedders without an event channel still get a Tower. */
+export const NOOP_EVENT_PORT = Object.freeze({
+  emit() {},
+})

package/ports/ids.js

@@ -1,7 +1,15 @@
-// Ids port (#56).
+// Ids port (#69).
+import { assertPort, definePort } from './contract.js'
+
 /**
  * @typedef {object} IdsPort
  * @property {() => string} uuid
  * @property {(text: string) => string} shortHash
  */
-export {}
+
+export const IDS_PORT = definePort('IdsPort', ['uuid', 'shortHash'])
+
+/** @param {unknown} impl */
+export function assertIdsPort(impl) {
+  return /** @type {IdsPort} */ (assertPort(impl, IDS_PORT, 'ids'))
+}

package/ports/index.js

@@ -1,2 +1,54 @@
-// Explicit ports consumed by app use cases (#56).
-export {}
+// Explicit ports consumed by app use cases (#69).
+//
+// `assertPorts` is the injection check the app layer runs on the dependency
+// object it receives: a composition root that forgets a port fails at
+// construction, not in the middle of a mission.
+import { assertPort } from './contract.js'
+import { STORE_PORT, assertStorePort } from './store.js'
+import { VCS_PORT, assertVcsPort } from './vcs.js'
+import { CLOCK_PORT, assertClockPort } from './clock.js'
+import { IDS_PORT, assertIdsPort } from './ids.js'
+import { CONFIG_PORT, assertConfigPort } from './config.js'
+import { STATE_PORT, assertStatePort } from './state.js'
+import { OWNERSHIP_PORT, assertOwnershipPort } from './ownership.js'
+import { CASE_SENSITIVITY_PORT, assertCaseSensitivityPort } from './caseSensitivity.js'
+import { ARCHIVE_PORT, assertArchivePort } from './archive.js'
+import { EVENT_PORT, assertEventPort } from './events.js'
+
+/** Every port the Tower app layer depends on, keyed by deps member. */
+export const PORTS = Object.freeze({
+  store: { contract: STORE_PORT, assert: assertStorePort },
+  vcs: { contract: VCS_PORT, assert: assertVcsPort },
+  clock: { contract: CLOCK_PORT, assert: assertClockPort },
+  ids: { contract: IDS_PORT, assert: assertIdsPort },
+  config: { contract: CONFIG_PORT, assert: assertConfigPort },
+  state: { contract: STATE_PORT, assert: assertStatePort },
+  ownership: { contract: OWNERSHIP_PORT, assert: assertOwnershipPort },
+  caseSensitivity: { contract: CASE_SENSITIVITY_PORT, assert: assertCaseSensitivityPort },
+  archive: { contract: ARCHIVE_PORT, assert: assertArchivePort },
+  events: { contract: EVENT_PORT, assert: assertEventPort },
+})
+
+/** @param {unknown} deps */
+export function assertPorts(deps) {
+  if (!deps || typeof deps !== 'object') {
+    throw new TypeError('Tower requires an injected deps object assembled by the composition root (see adapters/default.js)')
+  }
+  for (const [name, port] of Object.entries(PORTS)) {
+    if (typeof port.assert === 'function') port.assert(deps[name])
+    else assertPort(deps[name], port.contract, name)
+  }
+  return deps
+}
+
+export { STORE_PORT, assertStorePort } from './store.js'
+export { VCS_PORT, assertVcsPort } from './vcs.js'
+export { CLOCK_PORT, assertClockPort } from './clock.js'
+export { IDS_PORT, assertIdsPort } from './ids.js'
+export { CONFIG_PORT, assertConfigPort } from './config.js'
+export { STATE_PORT, assertStatePort } from './state.js'
+export { OWNERSHIP_PORT, assertOwnershipPort } from './ownership.js'
+export { CASE_SENSITIVITY_PORT, assertCaseSensitivityPort } from './caseSensitivity.js'
+export { ARCHIVE_PORT, assertArchivePort } from './archive.js'
+export { EVENT_PORT, assertEventPort, NOOP_EVENT_PORT } from './events.js'
+export { definePort, assertPort, implementsPort } from './contract.js'

package/ports/ownership.js

@@ -0,0 +1,17 @@
+// Worktree-ownership port (#69). The default implementation verifies a stored
+// worktree against the real filesystem and Git; an in-memory composition can
+// substitute a verifier that matches its own virtual paths.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} OwnershipPort
+ * @property {(input: { storedPath: string, storedRealPath?: string, branch: string, commonDir: string, missionId?: string }) => Promise<{ path: string, realPath: string }>} assertOwnership
+ * @property {(target: string) => Promise<string>} canonicalPath
+ */
+
+export const OWNERSHIP_PORT = definePort('OwnershipPort', ['assertOwnership', 'canonicalPath'])
+
+/** @param {unknown} impl */
+export function assertOwnershipPort(impl) {
+  return /** @type {OwnershipPort} */ (assertPort(impl, OWNERSHIP_PORT, 'ownership'))
+}

package/ports/state.js

@@ -0,0 +1,16 @@
+// State-load port (#69): schema inspection, migration, and the one persisted
+// migration result. The implementation is store-agnostic and receives the
+// store port, so an in-memory store can drive the same load path.
+import { assertPort, definePort } from './contract.js'
+
+/**
+ * @typedef {object} StatePort
+ * @property {(input: { store: unknown, paths: unknown, now?: number, persist?: boolean, migrations?: readonly unknown[] }) => Promise<any>} loadStateFile
+ */
+
+export const STATE_PORT = definePort('StatePort', ['loadStateFile'])
+
+/** @param {unknown} impl */
+export function assertStatePort(impl) {
+  return /** @type {StatePort} */ (assertPort(impl, STATE_PORT, 'state'))
+}