diff --git a/CHANGELOG.md b/CHANGELOG.md
index b913e27..d75000d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.2] — JSDoc total coverage (2026-02-28)
+
+### Added
+- `tsconfig.checkjs.json` — strict `checkJs` configuration; `tsc --noEmit` passes with zero errors.
+- `src/types/ambient.d.ts` — ambient type declarations for `@git-stunts/plumbing` and `bun` modules.
+- `@types/node` dev dependency for typecheck support.
+- JSDoc `@typedef` types: `EncryptionMeta`, `KdfParamSet`, `DeriveKeyParams` (CryptoPort); `VaultMetadata`, `VaultState`, `VaultEncryptionMeta` (VaultService).
+
+### Changed
+- Every exported and internal function, class method, and callback across all 32 source files now has complete JSDoc `@param`/`@returns` annotations.
+- CryptoPort return types widened to `string | Promise<string>` (sha256), `Buffer | Uint8Array` (randomBytes), sync-or-async for encrypt/decrypt — accurately reflecting adapter implementations.
+- Port `@param` names corrected to match underscore-prefixed abstract parameters (fixes TS8024).
+- Observer adapter methods (`SilentObserver`, `EventEmitterObserver`, `StatsCollector`) fully typed.
+- CLI files (`bin/`) comprehensively annotated with JSDoc types for all Commander callbacks and TUI render functions.
+
 ## [5.2.1] — Carousel polish (2026-02-28)
 
 ### Added
diff --git a/bin/actions.js b/bin/actions.js
index c4d58ec..d1cb54a 100644
--- a/bin/actions.js
+++ b/bin/actions.js
@@ -2,6 +2,9 @@
  * CLI error handler — wraps command actions with structured error output.
  */
 
+/** @typedef {{ code?: string, message?: string }} ErrorLike */
+
+/** @type {Readonly<Record<string, string>>} */
 const HINTS = {
   MISSING_KEY: 'Provide --key-file or --vault-passphrase',
   MANIFEST_NOT_FOUND: 'Verify the tree OID contains a manifest',
@@ -19,38 +22,52 @@ const HINTS = {
 /**
  * Format and write an error to stderr.
  *
- * @param {Error} err
+ * @param {ErrorLike} err
  * @param {boolean} json - Whether to output JSON.
  */
 function writeError(err, json) {
   const message = err?.message ?? String(err);
   const code = typeof err?.code === 'string' ? err.code : undefined;
   if (json) {
+    /** @type {{ error: string, code?: string }} */
     const obj = { error: message };
     if (code) { obj.code = code; }
     process.stderr.write(`${JSON.stringify(obj)}\n`);
   } else {
     const prefix = code ? `error [${code}]: ` : 'error: ';
     process.stderr.write(`${prefix}${message}\n`);
-    const hint = code ? HINTS[code] : undefined;
+    const hint = getHint(code);
     if (hint) {
       process.stderr.write(`hint: ${hint}\n`);
     }
   }
 }
 
+/**
+ * Look up a hint for the given error code, guarding against prototype keys.
+ *
+ * @param {string | undefined} code
+ * @returns {string | undefined}
+ */
+function getHint(code) {
+  if (code && Object.prototype.hasOwnProperty.call(HINTS, code)) {
+    return HINTS[code];
+  }
+  return undefined;
+}
+
 /**
  * Wrap a command action with structured error handling.
  *
- * @param {Function} fn - The async action function.
- * @param {Function} getJson - Lazy getter for --json flag value.
- * @returns {Function} Wrapped action.
+ * @param {(...args: any[]) => Promise<void>} fn - The async action function.
+ * @param {() => boolean} getJson - Lazy getter for --json flag value.
+ * @returns {(...args: any[]) => Promise<void>} Wrapped action.
  */
 export function runAction(fn, getJson) {
-  return async (...args) => {
+  return async (/** @type {any[]} */ ...args) => {
     try {
       await fn(...args);
-    } catch (err) {
+    } catch (/** @type {any} */ err) {
       writeError(err, getJson());
       process.exitCode = 1;
     }
diff --git a/bin/git-cas.js b/bin/git-cas.js
index f572745..5e0f30d 100755
--- a/bin/git-cas.js
+++ b/bin/git-cas.js
@@ -18,35 +18,54 @@ const getJson = () => program.opts().json;
 program
   .name('git-cas')
   .description('Content Addressable Storage backed by Git')
-  .version('5.2.1')
+  .version('5.2.2')
   .option('-q, --quiet', 'Suppress progress output')
   .option('--json', 'Output results as JSON');
 
 /**
  * Read a 32-byte raw encryption key from a file.
+ *
+ * @param {string} keyFilePath
+ * @returns {Buffer}
  */
 function readKeyFile(keyFilePath) {
-  return readFileSync(keyFilePath);
+  const buf = readFileSync(keyFilePath);
+  if (buf.length !== 32) {
+    throw new Error(`Invalid key length: expected 32 bytes, got ${buf.length} (${keyFilePath})`);
+  }
+  return buf;
 }
 
 /**
  * Create a CAS instance for the given working directory with an optional observability adapter.
+ *
+ * @param {string} cwd
+ * @param {{ observability?: import('../index.js').ObservabilityPort }} [opts]
+ * @returns {ContentAddressableStore}
  */
-function createCas(cwd, { observability } = {}) {
+function createCas(cwd, opts = {}) {
   const runner = ShellRunnerFactory.create();
   const plumbing = new GitPlumbing({ runner, cwd });
-  return new ContentAddressableStore({ plumbing, observability });
+  return new ContentAddressableStore({ plumbing, observability: opts.observability });
 }
 
 /**
  * Derive the encryption key from vault metadata + passphrase.
+ *
+ * @param {ContentAddressableStore} cas
+ * @param {import('../index.js').VaultMetadata} metadata
+ * @param {string} passphrase
+ * @returns {Promise<Buffer>}
  */
 async function deriveVaultKey(cas, metadata, passphrase) {
+  if (!metadata.encryption?.kdf) {
+    throw new Error('Missing or malformed encryption metadata');
+  }
   const { kdf } = metadata.encryption;
   const { key } = await cas.deriveKey({
     passphrase,
     salt: Buffer.from(kdf.salt, 'base64'),
-    algorithm: kdf.algorithm,
+    algorithm: /** @type {"pbkdf2" | "scrypt"} */ (kdf.algorithm),
     iterations: kdf.iterations,
     cost: kdf.cost,
     blockSize: kdf.blockSize,
@@ -57,6 +76,9 @@ async function deriveVaultKey(cas, metadata, passphrase) {
 
 /**
  * Resolve passphrase from --vault-passphrase flag or GIT_CAS_PASSPHRASE env var.
+ *
+ * @param {Record<string, any>} opts
+ * @returns {string | undefined}
  */
 function resolvePassphrase(opts) {
   return opts.vaultPassphrase ?? process.env.GIT_CAS_PASSPHRASE;
@@ -64,6 +86,10 @@ function resolvePassphrase(opts) {
 
 /**
  * Resolve encryption key from --key-file or --vault-passphrase / GIT_CAS_PASSPHRASE.
+ *
+ * @param {ContentAddressableStore} cas
+ * @param {Record<string, any>} opts
+ * @returns {Promise<Buffer | undefined>}
  */
 async function resolveEncryptionKey(cas, opts) {
   if (opts.keyFile) {
@@ -83,6 +109,8 @@ async function resolveEncryptionKey(cas, opts) {
 
 /**
  * Validate --slug / --oid flags (exactly one required).
+ *
+ * @param {Record<string, any>} opts
  */
 function validateRestoreFlags(opts) {
   if (opts.slug && opts.oid) {
@@ -96,10 +124,25 @@ function validateRestoreFlags(opts) {
 // ---------------------------------------------------------------------------
 // store
 // ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} StoreFileOpts
+ * @property {string} filePath - Path to the file to store.
+ * @property {string} slug - Asset slug identifier.
+ * @property {Buffer} [encryptionKey] - 32-byte AES-256-GCM key.
+ * @property {Array<{ label: string, key: Buffer }>} [recipients] - Envelope recipients.
+ */
+
 /**
  * Build store options, resolving encryption key or recipients.
+ *
+ * @param {ContentAddressableStore} cas
+ * @param {string} file
+ * @param {Record<string, any>} opts
+ * @returns {Promise<StoreFileOpts>}
  */
 async function buildStoreOpts(cas, file, opts) {
+  /** @type {StoreFileOpts} */
   const storeOpts = { filePath: file, slug: opts.slug };
   if (opts.recipient) {
     storeOpts.recipients = opts.recipient;
@@ -113,6 +156,10 @@ async function buildStoreOpts(cas, file, opts) {
 /**
  * Parse a --recipient flag value into { label, key }.
  * Format: label:keyfile
+ *
+ * @param {string} value
+ * @param {Array<{ label: string, key: Buffer }>} [previous]
+ * @returns {Array<{ label: string, key: Buffer }>}
  */
 function parseRecipient(value, previous) {
   const sep = value.indexOf(':');
@@ -140,7 +187,7 @@ program
   .option('--force', 'Overwrite existing vault entry')
   .option('--vault-passphrase <pass>', 'Vault-level passphrase for encryption (prefer GIT_CAS_PASSPHRASE env var)')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (file, opts) => {
+  .action(runAction(async (/** @type {string} */ file, /** @type {Record<string, any>} */ opts) => {
     if (opts.recipient && (opts.keyFile || resolvePassphrase(opts))) {
       throw new Error('Provide --key-file/--vault-passphrase or --recipient, not both');
     }
@@ -176,7 +223,7 @@ program
   .description('Create a Git tree from a manifest')
   .requiredOption('--manifest <path>', 'Path to manifest JSON file')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const raw = readFileSync(opts.manifest, 'utf8');
     const manifest = new Manifest(JSON.parse(raw));
@@ -199,7 +246,7 @@ program
   .option('--oid <tree-oid>', 'Direct tree OID')
   .option('--heatmap', 'Show chunk heatmap visualization')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     validateRestoreFlags(opts);
     const cas = createCas(opts.cwd);
     const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
@@ -229,7 +276,7 @@ program
   .option('--key-file <path>', 'Path to 32-byte raw encryption key file')
   .option('--vault-passphrase <pass>', 'Vault-level passphrase for decryption (prefer GIT_CAS_PASSPHRASE env var)')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     validateRestoreFlags(opts);
     const quiet = program.opts().quiet || program.opts().json;
     const observer = new EventEmitterObserver();
@@ -237,11 +284,7 @@ program
     const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
     const manifest = await cas.readManifest({ treeOid });
 
-    const restoreOpts = { manifest };
     const encryptionKey = await resolveEncryptionKey(cas, opts);
-    if (encryptionKey) {
-      restoreOpts.encryptionKey = encryptionKey;
-    }
 
     const progress = createRestoreProgress({
       totalChunks: manifest.chunks.length, quiet,
@@ -250,7 +293,8 @@ program
     let bytesWritten;
     try {
       ({ bytesWritten } = await cas.restoreFile({
-        ...restoreOpts,
+        manifest,
+        ...(encryptionKey ? { encryptionKey } : {}),
         outputPath: opts.out,
       }));
     } finally {
@@ -273,7 +317,7 @@ program
   .option('--slug <slug>', 'Resolve tree OID from vault slug')
   .option('--oid <tree-oid>', 'Direct tree OID')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     validateRestoreFlags(opts);
     const cas = createCas(opts.cwd);
     const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
@@ -303,13 +347,14 @@ vault
   .option('--vault-passphrase <pass>', 'Passphrase for vault-level encryption (prefer GIT_CAS_PASSPHRASE env var)')
   .option('--algorithm <alg>', 'KDF algorithm (pbkdf2 or scrypt)', 'pbkdf2')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
+    /** @type {{ passphrase?: string, kdfOptions?: { algorithm: 'pbkdf2' | 'scrypt' } }} */
     const initOpts = {};
     const passphrase = resolvePassphrase(opts);
     if (passphrase) {
       initOpts.passphrase = passphrase;
-      initOpts.kdfOptions = { algorithm: opts.algorithm };
+      initOpts.kdfOptions = { algorithm: /** @type {'pbkdf2' | 'scrypt'} */ (opts.algorithm) };
     }
     const { commitOid } = await cas.initVault(initOpts);
     const json = program.opts().json;
@@ -328,7 +373,7 @@ vault
   .description('List vault entries')
   .option('--filter <pattern>', 'Filter entries by glob pattern')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const all = await cas.listVault();
     const entries = filterEntries(all, opts.filter);
@@ -349,7 +394,7 @@ vault
   .command('remove <slug>')
   .description('Remove an entry from the vault')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (slug, opts) => {
+  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const { commitOid, removedTreeOid } = await cas.removeFromVault({ slug });
     const json = program.opts().json;
@@ -368,11 +413,12 @@ vault
   .description('Show info for a vault entry')
   .option('--encryption', 'Show vault encryption details')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (slug, opts) => {
+  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const treeOid = await cas.resolveVaultEntry({ slug });
     const json = program.opts().json;
     if (json) {
+      /** @type {Record<string, any>} */
       const result = { slug, treeOid };
       if (opts.encryption) {
         const metadata = await cas.getVaultMetadata();
@@ -400,7 +446,7 @@ vault
   .option('--cwd <dir>', 'Git working directory', '.')
   .option('-n, --max-count <n>', 'Limit number of commits')
   .option('--pretty', 'Render as color-coded timeline')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     const runner = ShellRunnerFactory.create();
     const plumbing = new GitPlumbing({ runner, cwd: opts.cwd || '.' });
     const args = ['log', '--oneline', ContentAddressableStore.VAULT_REF];
@@ -417,7 +463,7 @@ vault
       const history = output
         .split('\n')
         .filter(Boolean)
-        .map((line) => {
+        .map((/** @type {string} */ line) => {
           const [commitOid, ...messageParts] = line.trim().split(/\s+/);
           return { commitOid, message: messageParts.join(' ') };
         });
@@ -439,14 +485,15 @@ vault
   .requiredOption('--new-passphrase <pass>', 'New vault passphrase')
   .option('--algorithm <alg>', 'KDF algorithm (pbkdf2 or scrypt)')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
+    /** @type {{ oldPassphrase: string, newPassphrase: string, kdfOptions?: { algorithm: 'pbkdf2' | 'scrypt' } }} */
     const rotateOpts = {
       oldPassphrase: opts.oldPassphrase,
       newPassphrase: opts.newPassphrase,
     };
     if (opts.algorithm) {
-      rotateOpts.kdfOptions = { algorithm: opts.algorithm };
+      rotateOpts.kdfOptions = { algorithm: /** @type {'pbkdf2' | 'scrypt'} */ (opts.algorithm) };
     }
     const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase(rotateOpts);
     const json = program.opts().json;
@@ -470,7 +517,7 @@ vault
   .command('dashboard')
   .description('Interactive vault explorer')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const { launchDashboard } = await import('./ui/dashboard.js');
     await launchDashboard(cas);
@@ -488,7 +535,7 @@ program
   .requiredOption('--new-key-file <path>', 'Path to new 32-byte key file')
   .option('--label <label>', 'Rotate only the named recipient')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (opts) => {
+  .action(runAction(async (/** @type {Record<string, any>} */ opts) => {
     validateRestoreFlags(opts);
     const cas = createCas(opts.cwd);
     const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
@@ -497,6 +544,7 @@ program
     const oldKey = readKeyFile(opts.oldKeyFile);
     const newKey = readKeyFile(opts.newKeyFile);
 
+    /** @type {{ manifest: Manifest, oldKey: Buffer, newKey: Buffer, label?: string }} */
     const rotateOpts = { manifest, oldKey, newKey };
     if (opts.label) { rotateOpts.label = opts.label; }
 
@@ -507,7 +555,7 @@ program
       const newTreeOid = await cas.createTree({ manifest: updated });
       await cas.addToVault({ slug: opts.slug, treeOid: newTreeOid, force: true });
       if (json) {
-        process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid, keyVersion: updated.encryption.keyVersion })}\n`);
+        process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid, keyVersion: updated.encryption?.keyVersion })}\n`);
       } else {
         process.stdout.write(`${newTreeOid}\n`);
       }
@@ -532,7 +580,7 @@ recipient
   .requiredOption('--key-file <path>', 'Path to 32-byte key file for the new recipient')
   .requiredOption('--existing-key-file <path>', 'Path to key file of an existing recipient')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (slug, opts) => {
+  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const treeOid = await cas.resolveVaultEntry({ slug });
     const manifest = await cas.readManifest({ treeOid });
@@ -563,7 +611,7 @@ recipient
   .description('Remove a recipient from an envelope-encrypted asset')
   .requiredOption('--label <label>', 'Label of the recipient to remove')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (slug, opts) => {
+  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const treeOid = await cas.resolveVaultEntry({ slug });
     const manifest = await cas.readManifest({ treeOid });
@@ -585,7 +633,7 @@ recipient
   .command('list <slug>')
   .description('List recipients of an envelope-encrypted asset')
   .option('--cwd <dir>', 'Git working directory', '.')
-  .action(runAction(async (slug, opts) => {
+  .action(runAction(async (/** @type {string} */ slug, /** @type {Record<string, any>} */ opts) => {
     const cas = createCas(opts.cwd);
     const treeOid = await cas.resolveVaultEntry({ slug });
     const manifest = await cas.readManifest({ treeOid });
diff --git a/bin/ui/context.js b/bin/ui/context.js
index 5a72f2f..96a7438 100644
--- a/bin/ui/context.js
+++ b/bin/ui/context.js
@@ -5,11 +5,14 @@
 import { createBijou } from '@flyingrobots/bijou';
 import { nodeRuntime, chalkStyle } from '@flyingrobots/bijou-node';
 
+/** @type {import('@flyingrobots/bijou').BijouContext | null} */
 let ctx = null;
 
 /**
  * Returns a bijou context that writes to stderr instead of stdout.
  * Stdout is reserved for structured output (OIDs, JSON).
+ *
+ * @returns {import('@flyingrobots/bijou').BijouContext}
  */
 export function getCliContext() {
   if (ctx) {
@@ -25,8 +28,12 @@ export function getCliContext() {
   return ctx;
 }
 
+/**
+ * @returns {import('@flyingrobots/bijou').IOPort}
+ */
 function stderrIO() {
   return {
+    /** @param {string} data */
     write(data) {
       process.stderr.write(data);
     },
@@ -36,6 +43,7 @@ function stderrIO() {
     rawInput() {
       throw new Error('rawInput() not supported in CLI context');
     },
+    /** @param {(cols: number, rows: number) => void} callback */
     onResize(callback) {
       const handler = () => {
         callback(process.stderr.columns ?? 80, process.stderr.rows ?? 24);
@@ -43,12 +51,17 @@ function stderrIO() {
       process.stderr.on('resize', handler);
       return { dispose() { process.stderr.removeListener('resize', handler); } };
     },
+    /**
+     * @param {() => void} callback
+     * @param {number} ms
+     */
     setInterval(callback, ms) {
       const id = globalThis.setInterval(callback, ms);
       return { dispose() { globalThis.clearInterval(id); } };
     },
     readFile() { throw new Error('readFile() not supported'); },
     readDir() { throw new Error('readDir() not supported'); },
+    /** @param {string[]} segments */
     joinPath(...segments) { return segments.join('/'); },
   };
 }
diff --git a/bin/ui/dashboard-cmds.js b/bin/ui/dashboard-cmds.js
index 0096170..8a88a06 100644
--- a/bin/ui/dashboard-cmds.js
+++ b/bin/ui/dashboard-cmds.js
@@ -2,8 +2,12 @@
  * Async command factories for the vault dashboard.
  */
 
+/** @typedef {import('../../index.js').default} ContentAddressableStore */
+
 /**
  * Load vault entries and metadata in parallel.
+ *
+ * @param {ContentAddressableStore} cas
  */
 export function loadEntriesCmd(cas) {
   return async () => {
@@ -12,23 +16,27 @@ export function loadEntriesCmd(cas) {
         cas.listVault(),
         cas.getVaultMetadata(),
       ]);
-      return { type: 'loaded-entries', entries, metadata };
-    } catch (err) {
-      return { type: 'load-error', source: 'entries', error: err.message };
+      return /** @type {const} */ ({ type: 'loaded-entries', entries, metadata });
+    } catch (/** @type {any} */ err) {
+      return /** @type {const} */ ({ type: 'load-error', source: 'entries', error: /** @type {Error} */ (err).message });
     }
   };
 }
 
 /**
  * Load a single manifest by slug and tree OID.
+ *
+ * @param {ContentAddressableStore} cas
+ * @param {string} slug
+ * @param {string} treeOid
  */
 export function loadManifestCmd(cas, slug, treeOid) {
   return async () => {
     try {
       const manifest = await cas.readManifest({ treeOid });
-      return { type: 'loaded-manifest', slug, manifest };
-    } catch (err) {
-      return { type: 'load-error', source: 'manifest', slug, error: err.message };
+      return /** @type {const} */ ({ type: 'loaded-manifest', slug, manifest });
+    } catch (/** @type {any} */ err) {
+      return /** @type {const} */ ({ type: 'load-error', source: 'manifest', slug, error: /** @type {Error} */ (err).message });
     }
   };
 }
diff --git a/bin/ui/dashboard-view.js b/bin/ui/dashboard-view.js
index bb93f42..09cb5b4 100644
--- a/bin/ui/dashboard-view.js
+++ b/bin/ui/dashboard-view.js
@@ -6,8 +6,18 @@ import { badge } from '@flyingrobots/bijou';
 import { flex, viewport } from '@flyingrobots/bijou-tui';
 import { renderManifestView } from './manifest-view.js';
 
+/**
+ * @typedef {import('./dashboard.js').DashModel} DashModel
+ * @typedef {import('./dashboard.js').DashDeps} DashDeps
+ * @typedef {import('@flyingrobots/bijou').BijouContext} BijouContext
+ * @typedef {import('../../src/domain/value-objects/Manifest.js').default} Manifest
+ */
+
 /**
  * Format bytes as compact string.
+ *
+ * @param {number} bytes
+ * @returns {string}
  */
 function formatSize(bytes) {
   if (bytes < 1024) { return `${bytes}B`; }
@@ -18,6 +28,9 @@ function formatSize(bytes) {
 
 /**
  * Format manifest stats for the list.
+ *
+ * @param {Manifest} manifest
+ * @returns {string}
  */
 function formatStats(manifest) {
   const m = manifest.toJSON ? manifest.toJSON() : manifest;
@@ -26,6 +39,11 @@ function formatStats(manifest) {
 
 /**
  * Render a single list item.
+ *
+ * @param {{ slug: string, treeOid: string }} entry
+ * @param {number} index
+ * @param {{ model: DashModel, width?: number }} opts
+ * @returns {string}
  */
 function renderListItem(entry, index, opts) {
   const prefix = index === opts.model.cursor ? '> ' : '  ';
@@ -37,6 +55,11 @@ function renderListItem(entry, index, opts) {
 
 /**
  * Compute visible window for cursor scrolling.
+ *
+ * @param {number} cursor
+ * @param {number} total
+ * @param {number} height
+ * @returns {{ start: number, end: number }}
  */
 function visibleRange(cursor, total, height) {
   const start = Math.max(0, Math.min(cursor - Math.floor(height / 2), total - height));
@@ -45,6 +68,10 @@ function visibleRange(cursor, total, height) {
 
 /**
  * Render the header line.
+ *
+ * @param {DashModel} model
+ * @param {BijouContext} ctx
+ * @returns {string}
  */
 function renderHeader(model, ctx) {
   const parts = [];
@@ -58,9 +85,13 @@ function renderHeader(model, ctx) {
 
 /**
  * Render the list pane.
+ *
+ * @param {DashModel} model
+ * @param {{ height: number, width?: number }} size
+ * @returns {string}
  */
 function renderListPane(model, size) {
-  const clamp = (s) => (size.width ? s.slice(0, size.width) : s);
+  const clamp = (/** @type {string} */ s) => (typeof size.width === 'number' && size.width > 0 ? s.slice(0, size.width) : s);
   const filterLine = model.filtering ? clamp(`/${model.filterText}\u2588`) : '';
   const listHeight = model.filtering ? size.height - 1 : size.height;
   const items = model.filtered;
@@ -86,6 +117,11 @@ function renderListPane(model, size) {
 
 /**
  * Pad content to target height, optionally appending a suffix line.
+ *
+ * @param {string} content
+ * @param {number} height
+ * @param {string} suffix
+ * @returns {string}
  */
 function padToHeight(content, height, suffix) {
   const lines = content.split('\n');
@@ -95,6 +131,10 @@ function padToHeight(content, height, suffix) {
 
 /**
  * Render the detail pane with viewport scrolling.
+ *
+ * @param {DashModel} model
+ * @param {{ width: number, height: number, ctx: BijouContext }} opts
+ * @returns {string}
  */
 function renderDetailPane(model, opts) {
   const entry = model.filtered[model.cursor];
@@ -107,26 +147,35 @@ function renderDetailPane(model, opts) {
 
 /**
  * Render the body with list and detail panes.
+ *
+ * @param {DashModel} model
+ * @param {DashDeps} deps
+ * @param {{ width: number, height: number }} size
+ * @returns {string}
  */
 function renderBody(model, deps, size) {
   const listBasis = Math.floor(size.width * 0.35);
   return flex(
     { direction: 'row', width: size.width, height: size.height, gap: 1 },
-    { content: (w, h) => renderListPane(model, { height: h, width: w }), basis: listBasis },
-    { content: (w, h) => renderDetailPane(model, { width: w, height: h, ctx: deps.ctx }), flex: 1 },
+    { content: (/** @type {number} */ w, /** @type {number} */ h) => renderListPane(model, { height: h, width: w }), basis: listBasis },
+    { content: (/** @type {number} */ w, /** @type {number} */ h) => renderDetailPane(model, { width: w, height: h, ctx: deps.ctx }), flex: 1 },
   );
 }
 
 /**
  * Render the full dashboard layout.
+ *
+ * @param {DashModel} model
+ * @param {DashDeps} deps
+ * @returns {string}
  */
 export function renderDashboard(model, deps) {
   return flex(
     { direction: 'column', width: model.columns, height: model.rows },
     { content: renderHeader(model, deps.ctx), basis: 1 },
-    { content: (w, _h) => '\u2500'.repeat(w), basis: 1 },
-    { content: (w, h) => renderBody(model, deps, { width: w, height: h }), flex: 1 },
-    { content: (w, _h) => '\u2500'.repeat(w), basis: 1 },
+    { content: (/** @type {number} */ w, /** @type {number} */ _h) => '\u2500'.repeat(w), basis: 1 },
+    { content: (/** @type {number} */ w, /** @type {number} */ h) => renderBody(model, deps, { width: w, height: h }), flex: 1 },
+    { content: (/** @type {number} */ w, /** @type {number} */ _h) => '\u2500'.repeat(w), basis: 1 },
     { content: 'j/k Navigate  enter Load  / Filter  J/K Scroll  q Quit', basis: 1 },
   );
 }
diff --git a/bin/ui/dashboard.js b/bin/ui/dashboard.js
index 0a89fce..5810059 100644
--- a/bin/ui/dashboard.js
+++ b/bin/ui/dashboard.js
@@ -7,8 +7,61 @@ import { createNodeContext } from '@flyingrobots/bijou-node';
 import { loadEntriesCmd, loadManifestCmd } from './dashboard-cmds.js';
 import { renderDashboard } from './dashboard-view.js';
 
+/**
+ * @typedef {import('@flyingrobots/bijou').BijouContext} BijouContext
+ * @typedef {import('@flyingrobots/bijou-tui').KeyMsg} KeyMsg
+ * @typedef {import('@flyingrobots/bijou-tui').ResizeMsg} ResizeMsg
+ * @typedef {import('@flyingrobots/bijou-tui').Cmd<DashMsg>} DashCmd
+ * @typedef {import('@flyingrobots/bijou-tui').KeyMap<DashAction>} DashKeyMap
+ * @typedef {import('../../index.js').default} ContentAddressableStore
+ * @typedef {import('../../src/domain/value-objects/Manifest.js').default} Manifest
+ * @typedef {{ slug: string, treeOid: string }} VaultEntry
+ */
+
+/**
+ * @typedef {{ type: 'quit' }
+ *   | { type: 'move', delta: number }
+ *   | { type: 'select' }
+ *   | { type: 'filter-start' }
+ *   | { type: 'scroll-detail', delta: number }
+ * } DashAction
+ */
+
+/**
+ * @typedef {{ type: 'loaded-entries', entries: VaultEntry[], metadata: any }
+ *   | { type: 'loaded-manifest', slug: string, manifest: Manifest }
+ *   | { type: 'load-error', source: string, slug?: string, error: string }
+ * } DashMsg
+ */
+
+/**
+ * @typedef {Object} DashModel
+ * @property {string} status
+ * @property {number} columns
+ * @property {number} rows
+ * @property {VaultEntry[]} entries
+ * @property {VaultEntry[]} filtered
+ * @property {number} cursor
+ * @property {string} filterText
+ * @property {boolean} filtering
+ * @property {any} metadata
+ * @property {Map<string, Manifest>} manifestCache
+ * @property {string | null} loadingSlug
+ * @property {number} detailScroll
+ * @property {string | null} error
+ */
+
+/**
+ * @typedef {Object} DashDeps
+ * @property {DashKeyMap} keyMap
+ * @property {ContentAddressableStore} cas
+ * @property {BijouContext} ctx
+ */
+
 /**
  * Create keyboard bindings for normal mode.
+ *
+ * @returns {DashKeyMap}
  */
 export function createKeyBindings() {
   return createKeyMap()
@@ -25,6 +78,8 @@ export function createKeyBindings() {
 
 /**
  * Create the initial model.
+ *
+ * @returns {DashModel}
  */
 function createInitModel() {
   return {
@@ -46,19 +101,28 @@ function createInitModel() {
 
 /**
  * Apply filter text to entries.
+ *
+ * @param {VaultEntry[]} entries
+ * @param {string} text
+ * @returns {VaultEntry[]}
  */
 function applyFilter(entries, text) {
   if (!text) { return entries; }
-  return entries.filter(e => e.slug.includes(text));
+  return entries.filter((/** @type {VaultEntry} */ e) => e.slug.includes(text));
 }
 
 /**
  * Handle the loaded-entries message.
+ *
+ * @param {DashMsg & { type: 'loaded-entries' }} msg
+ * @param {DashModel} model
+ * @param {ContentAddressableStore} cas
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleLoadedEntries(msg, model, cas) {
   const filtered = applyFilter(msg.entries, model.filterText);
   const cursor = Math.max(0, Math.min(model.cursor, filtered.length - 1));
-  const cmds = msg.entries.map(e => loadManifestCmd(cas, e.slug, e.treeOid));
+  const cmds = /** @type {DashCmd[]} */ (msg.entries.map((/** @type {VaultEntry} */ e) => loadManifestCmd(cas, e.slug, e.treeOid)));
   return [{
     ...model,
     status: 'ready',
@@ -71,6 +135,10 @@ function handleLoadedEntries(msg, model, cas) {
 
 /**
  * Handle a loaded-manifest message.
+ *
+ * @param {DashMsg & { type: 'loaded-manifest' }} msg
+ * @param {DashModel} model
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleLoadedManifest(msg, model) {
   const cache = new Map(model.manifestCache);
@@ -80,6 +148,10 @@ function handleLoadedManifest(msg, model) {
 
 /**
  * Handle cursor movement.
+ *
+ * @param {{ type: 'move', delta: number }} msg
+ * @param {DashModel} model
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleMove(msg, model) {
   const max = model.filtered.length - 1;
@@ -89,6 +161,10 @@ function handleMove(msg, model) {
 
 /**
  * Handle filter key input in filter mode.
+ *
+ * @param {KeyMsg} msg
+ * @param {DashModel} model
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleFilterKey(msg, model) {
   if (msg.key === 'escape' || msg.key === 'enter') {
@@ -109,18 +185,27 @@ function handleFilterKey(msg, model) {
 
 /**
  * Handle select (enter key) to load manifest.
+ *
+ * @param {DashModel} model
+ * @param {DashDeps} deps
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleSelect(model, deps) {
   const entry = model.filtered[model.cursor];
   if (!entry || model.manifestCache.has(entry.slug)) {
     return [model, []];
   }
-  const cmd = loadManifestCmd(deps.cas, entry.slug, entry.treeOid);
+  const cmd = /** @type {DashCmd} */ (loadManifestCmd(deps.cas, entry.slug, entry.treeOid));
   return [{ ...model, loadingSlug: entry.slug }, [cmd]];
 }
 
 /**
  * Handle keymap actions.
+ *
+ * @param {DashAction} action
+ * @param {DashModel} model
+ * @param {DashDeps} deps
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleAction(action, model, deps) {
   if (action.type === 'quit') { return [model, [quit()]]; }
@@ -138,6 +223,11 @@ function handleAction(action, model, deps) {
 
 /**
  * Handle app-level messages (data loading results).
+ *
+ * @param {DashMsg} msg
+ * @param {DashModel} model
+ * @param {ContentAddressableStore} cas
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleAppMsg(msg, model, cas) {
   if (msg.type === 'loaded-entries') { return handleLoadedEntries(msg, model, cas); }
@@ -153,6 +243,11 @@ function handleAppMsg(msg, model, cas) {
 
 /**
  * Route all update messages to the appropriate handler.
+ *
+ * @param {KeyMsg | ResizeMsg | DashMsg} msg
+ * @param {DashModel} model
+ * @param {DashDeps} deps
+ * @returns {[DashModel, DashCmd[]]}
  */
 function handleUpdate(msg, model, deps) {
   if (msg.type === 'key' && model.filtering) {
@@ -166,22 +261,27 @@ function handleUpdate(msg, model, deps) {
   if (msg.type === 'resize') {
     return [{ ...model, columns: msg.columns, rows: msg.rows }, []];
   }
-  return handleAppMsg(msg, model, deps.cas);
+  return handleAppMsg(/** @type {DashMsg} */ (msg), model, deps.cas);
 }
 
 /**
  * Create the TEA app object for the dashboard.
+ *
+ * @param {DashDeps} deps
+ * @returns {import('@flyingrobots/bijou-tui').App<DashModel, DashMsg>}
  */
 export function createDashboardApp(deps) {
   return {
-    init: () => [createInitModel(), [loadEntriesCmd(deps.cas)]],
-    update: (msg, model) => handleUpdate(msg, model, deps),
-    view: (model) => renderDashboard(model, deps),
+    init: () => /** @type {[DashModel, DashCmd[]]} */ ([createInitModel(), [/** @type {DashCmd} */ (loadEntriesCmd(deps.cas))]]),
+    update: (/** @type {KeyMsg | ResizeMsg | DashMsg} */ msg, /** @type {DashModel} */ model) => handleUpdate(msg, model, deps),
+    view: (/** @type {DashModel} */ model) => renderDashboard(model, deps),
   };
 }
 
 /**
  * Print static list for non-TTY environments.
+ *
+ * @param {ContentAddressableStore} cas
  */
 async function printStaticList(cas) {
   const entries = await cas.listVault();
@@ -192,6 +292,8 @@ async function printStaticList(cas) {
 
 /**
  * Launch the interactive vault dashboard.
+ *
+ * @param {ContentAddressableStore} cas
  */
 export async function launchDashboard(cas) {
   if (!process.stdout.isTTY) {
diff --git a/bin/ui/encryption-card.js b/bin/ui/encryption-card.js
index ab6a595..1143617 100644
--- a/bin/ui/encryption-card.js
+++ b/bin/ui/encryption-card.js
@@ -9,7 +9,7 @@ import { getCliContext } from './context.js';
  * Render an encryption info card for the vault.
  *
  * @param {Object} options
- * @param {Object|null} options.metadata - Vault metadata (from getVaultMetadata()).
+ * @param {import('../../index.js').VaultMetadata | null} options.metadata - Vault metadata (from getVaultMetadata()).
  * @param {boolean} [options.unlocked] - Whether a key/passphrase was provided.
  * @returns {string}
  */
@@ -33,7 +33,7 @@ export function renderEncryptionCard({ metadata, unlocked = false }) {
   ];
 
   if (kdf.algorithm === 'pbkdf2') {
-    rows.push(`  iterations  ${kdf.iterations.toLocaleString()}`);
+    rows.push(`  iterations  ${/** @type {number} */ (kdf.iterations).toLocaleString()}`);
   } else if (kdf.algorithm === 'scrypt') {
     rows.push(`  cost        ${kdf.cost}`);
     rows.push(`  blockSize   ${kdf.blockSize}`);
diff --git a/bin/ui/heatmap.js b/bin/ui/heatmap.js
index 9d01d38..50c13f6 100644
--- a/bin/ui/heatmap.js
+++ b/bin/ui/heatmap.js
@@ -5,6 +5,12 @@
 import { gradientText } from '@flyingrobots/bijou';
 import { getCliContext } from './context.js';
 
+/**
+ * @typedef {import('../../src/domain/value-objects/Manifest.js').ManifestData} ManifestData
+ * @typedef {import('../../src/domain/value-objects/Manifest.js').SubManifestRef} SubManifestRef
+ */
+
+/** @type {import('@flyingrobots/bijou').GradientStop[]} */
 const GRADIENT_STOPS = [
   { pos: 0, color: [0, 255, 255] },
   { pos: 1, color: [255, 0, 255] },
@@ -12,6 +18,9 @@ const GRADIENT_STOPS = [
 
 /**
  * Format bytes as human-readable string.
+ *
+ * @param {number} bytes
+ * @returns {string}
  */
 function formatBytes(bytes) {
   if (bytes < 1024) {
@@ -28,6 +37,11 @@ function formatBytes(bytes) {
 
 /**
  * Build the block grid string from chunks.
+ *
+ * @param {ManifestData['chunks']} chunks
+ * @param {Set<number>} boundaries
+ * @param {number} width
+ * @returns {string}
  */
 function buildGrid(chunks, boundaries, width) {
   let grid = '';
@@ -56,6 +70,10 @@ function buildGrid(chunks, boundaries, width) {
 
 /**
  * Build the legend line.
+ *
+ * @param {ManifestData['chunks']} chunks
+ * @param {SubManifestRef[]} subManifests
+ * @returns {string}
  */
 function buildLegend(chunks, subManifests) {
   const chunkSize = chunks.length > 0 ? chunks[0].size : 0;
@@ -73,12 +91,12 @@ function buildLegend(chunks, subManifests) {
  * Render a chunk heatmap for a manifest.
  *
  * @param {Object} options
- * @param {Object} options.manifest - The manifest (from readManifest).
+ * @param {ManifestData | { toJSON(): ManifestData }} options.manifest - The manifest (Manifest instance or plain ManifestData).
  * @returns {string}
  */
 export function renderHeatmap({ manifest }) {
   const ctx = getCliContext();
-  const m = manifest.toJSON ? manifest.toJSON() : manifest;
+  const m = /** @type {ManifestData} */ ('toJSON' in manifest ? manifest.toJSON() : manifest);
   const chunks = m.chunks || [];
 
   if (chunks.length === 0) {
diff --git a/bin/ui/history-timeline.js b/bin/ui/history-timeline.js
index f915db1..fc4bc7c 100644
--- a/bin/ui/history-timeline.js
+++ b/bin/ui/history-timeline.js
@@ -34,6 +34,7 @@ function parseCommitLine(line) {
   return { oid, operation: match[1], slug: match[2] || null };
 }
 
+/** @type {Record<string, string>} */
 const STATUS_MAP = {
   init: 'info',
   add: 'success',
@@ -65,14 +66,15 @@ export function renderHistoryTimeline(gitLogOutput, options = {}) {
   const start = (page - 1) * perPage;
   const pageLines = lines.slice(start, start + perPage);
 
-  const events = pageLines
-    .map(parseCommitLine)
-    .filter(Boolean)
-    .map(({ oid, operation, slug }) => ({
+  const parsed = pageLines.map(parseCommitLine).filter(Boolean);
+  const events = parsed.map((entry) => {
+    const { oid, operation, slug } = /** @type {{ oid: string, operation: string, slug: string | null }} */ (entry);
+    return {
       label: slug ? `vault: ${operation} ${slug}` : `vault: ${operation}`,
       description: oid,
-      status: STATUS_MAP[operation] || 'pending',
-    }));
+      status: /** @type {import('@flyingrobots/bijou').BaseStatusKey} */ (STATUS_MAP[operation] || 'pending'),
+    };
+  });
 
   let output = timeline(events, { ctx });
 
diff --git a/bin/ui/manifest-view.js b/bin/ui/manifest-view.js
index 8f06f89..1be14aa 100644
--- a/bin/ui/manifest-view.js
+++ b/bin/ui/manifest-view.js
@@ -5,8 +5,16 @@
 import { box, badge, table, tree, headerBox } from '@flyingrobots/bijou';
 import { getCliContext } from './context.js';
 
+/**
+ * @typedef {import('../../src/domain/value-objects/Manifest.js').ManifestData} ManifestData
+ * @typedef {import('@flyingrobots/bijou').BijouContext} BijouContext
+ */
+
 /**
  * Format bytes as human-readable string.
+ *
+ * @param {number} bytes
+ * @returns {string}
  */
 function formatBytes(bytes) {
   if (bytes < 1024) {
@@ -23,6 +31,10 @@ function formatBytes(bytes) {
 
 /**
  * Build the header badges line.
+ *
+ * @param {ManifestData} m
+ * @param {BijouContext} ctx
+ * @returns {string}
  */
 function renderBadges(m, ctx) {
   const badges = [badge(`v${m.version}`, { ctx })];
@@ -40,6 +52,10 @@ function renderBadges(m, ctx) {
 
 /**
  * Build the encryption section.
+ *
+ * @param {NonNullable<ManifestData['encryption']>} enc
+ * @param {BijouContext} ctx
+ * @returns {string}
  */
 function renderEncryptionSection(enc, ctx) {
   const rows = [`  algorithm  ${enc.algorithm}`];
@@ -63,14 +79,18 @@ function renderEncryptionSection(enc, ctx) {
 
 /**
  * Build the chunks section.
+ *
+ * @param {ManifestData['chunks']} chunks
+ * @param {BijouContext} ctx
+ * @returns {string}
  */
 function renderChunksSection(chunks, ctx) {
   const displayChunks = chunks.slice(0, 20);
-  const chunkRows = displayChunks.map(c => [
+  const chunkRows = displayChunks.map((/** @type {{ index: number, size: number, digest: string, blob?: string }} */ c) => [
     String(c.index),
     formatBytes(c.size),
-    `${c.digest.slice(0, 12)}...`,
-    `${c.blob.slice(0, 12)}...`,
+    typeof c.digest === 'string' ? `${c.digest.slice(0, 12)}...` : '-',
+    typeof c.blob === 'string' ? `${c.blob.slice(0, 12)}...` : '-',
   ]);
   const chunkTable = table({
     columns: [{ header: '#' }, { header: 'Size' }, { header: 'Digest' }, { header: 'Blob' }],
@@ -85,6 +105,10 @@ function renderChunksSection(chunks, ctx) {
 
 /**
  * Build the metadata section.
+ *
+ * @param {ManifestData} m
+ * @param {BijouContext} ctx
+ * @returns {string}
  */
 function renderMetadataSection(m, ctx) {
   const meta = [
@@ -98,24 +122,29 @@ function renderMetadataSection(m, ctx) {
 
 /**
  * Build the sub-manifests section.
+ *
+ * @param {ManifestData} m
+ * @param {BijouContext} ctx
+ * @returns {string}
  */
 function renderSubManifestsSection(m, ctx) {
-  const nodes = m.subManifests.map((sm, i) => ({
+  const subs = m.subManifests || [];
+  const nodes = subs.map((/** @type {import('../../src/domain/value-objects/Manifest.js').SubManifestRef} */ sm, /** @type {number} */ i) => ({
     label: `sub-${i}  ${sm.chunkCount} chunks  start: ${sm.startIndex}  oid: ${sm.oid.slice(0, 8)}...`,
   }));
-  return `${headerBox(`Sub-manifests (${m.subManifests.length})`, { ctx })}\n${tree(nodes, { ctx })}`;
+  return `${headerBox(`Sub-manifests (${subs.length})`, { ctx })}\n${tree(nodes, { ctx })}`;
 }
 
 /**
  * Render a full manifest anatomy view.
  *
  * @param {Object} options
- * @param {Object} options.manifest - The manifest (from readManifest).
- * @param {Object} [options.ctx] - Optional bijou context override.
+ * @param {ManifestData | { toJSON(): ManifestData }} options.manifest - The manifest (Manifest instance or plain ManifestData).
+ * @param {BijouContext} [options.ctx] - Optional bijou context override.
  * @returns {string}
  */
 export function renderManifestView({ manifest, ctx = getCliContext() }) {
-  const m = manifest.toJSON ? manifest.toJSON() : manifest;
+  const m = /** @type {ManifestData} */ ('toJSON' in manifest ? manifest.toJSON() : manifest);
   const sections = [renderBadges(m, ctx), renderMetadataSection(m, ctx)];
 
   if (m.encryption) {
diff --git a/bin/ui/progress.js b/bin/ui/progress.js
index 583d4fc..bc629fb 100644
--- a/bin/ui/progress.js
+++ b/bin/ui/progress.js
@@ -9,6 +9,9 @@ import { getCliContext } from './context.js';
 
 /**
  * Format bytes as human-readable string.
+ *
+ * @param {number} bytes
+ * @returns {string}
  */
 function formatBytes(bytes) {
   if (bytes < 1024) {
@@ -23,6 +26,12 @@ function formatBytes(bytes) {
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GiB`;
 }
 
+/**
+ * @typedef {import('../actions.js')} ActionsModule
+ * @typedef {{ on(event: string, fn: Function): void, removeListener(event: string, fn: Function): void }} Observer
+ * @typedef {{ attach(observer: Observer): void, detach(): void }} ProgressTracker
+ */
+
 /**
  * Create a progress tracker for store operations.
  *
@@ -30,7 +39,9 @@ function formatBytes(bytes) {
  * @param {string} options.filePath - Path to the file being stored.
  * @param {number} options.chunkSize - Chunk size in bytes.
  * @param {boolean} [options.quiet] - Suppress all progress output.
- * @returns {{ attach(observer: { on(event: string, fn: Function): void, removeListener(event: string, fn: Function): void }): void, detach(): void }}
+ * @param {number} [options.fileSize] - Pre-computed file size (avoids stat).
+ * @param {import('@flyingrobots/bijou').BijouContext} [options.ctx] - Context override.
+ * @returns {ProgressTracker}
  */
 export function createStoreProgress({ filePath, chunkSize, quiet, fileSize: providedSize, ctx: providedCtx }) {
   if (quiet) {
@@ -58,7 +69,8 @@ export function createStoreProgress({ filePath, chunkSize, quiet, fileSize: prov
  * @param {Object} options
  * @param {number} options.totalChunks - Number of chunks to restore.
  * @param {boolean} [options.quiet] - Suppress all progress output.
- * @returns {{ attach(observer: { on(event: string, fn: Function): void, removeListener(event: string, fn: Function): void }): void, detach(): void }}
+ * @param {import('@flyingrobots/bijou').BijouContext} [options.ctx] - Context override.
+ * @returns {ProgressTracker}
  */
 export function createRestoreProgress({ totalChunks, quiet, ctx: providedCtx }) {
   if (quiet || totalChunks === 0) {
@@ -73,54 +85,64 @@ export function createRestoreProgress({ totalChunks, quiet, ctx: providedCtx })
   return createProgressTracker({ ctx, totalChunks, event: 'chunk:restored', label: 'Restoring' });
 }
 
+/**
+ * @typedef {Object} TrackerState
+ * @property {number} chunksProcessed
+ * @property {number} bytesProcessed
+ * @property {number | null} startTime
+ * @property {Observer | null} service
+ * @property {((evt: { size: number }) => void) | null} handler
+ */
+
+/**
+ * Handle a single chunk event (shared by store/restore).
+ *
+ * @param {{ size: number }} evt
+ * @param {TrackerState} state
+ * @param {{ ctx: import('@flyingrobots/bijou').BijouContext, totalChunks: number, label: string, bar: { update(pct: number): void } }} deps
+ */
+function handleChunkEvent({ size }, state, deps) {
+  if (!state.startTime) { state.startTime = Date.now(); }
+  state.chunksProcessed++;
+  state.bytesProcessed += size;
+  const pct = (state.chunksProcessed / deps.totalChunks) * 100;
+  const elapsed = (Date.now() - state.startTime) / 1000;
+  const throughput = elapsed > 0 ? state.bytesProcessed / elapsed : 0;
+  if (deps.ctx.mode === 'interactive') {
+    const status = `  ${deps.label} ${state.chunksProcessed}/${deps.totalChunks}  ${formatBytes(throughput)}/s  `;
+    deps.ctx.io.write(`\r\x1b[K${status}`);
+    deps.bar.update(pct);
+  } else if (state.chunksProcessed === 1 || state.chunksProcessed === deps.totalChunks || state.chunksProcessed % 10 === 0) {
+    deps.ctx.io.write(`${deps.label} ${state.chunksProcessed}/${deps.totalChunks}  ${Math.round(pct)}%\n`);
+  }
+}
+
 /**
  * Internal: builds the progress tracker object.
+ *
+ * @param {{ ctx: import('@flyingrobots/bijou').BijouContext, totalChunks: number, event: string, label: string }} params
+ * @returns {ProgressTracker}
  */
 function createProgressTracker({ ctx, totalChunks, event, label }) {
   const width = Math.min(40, (ctx.runtime.columns || 80) - 30);
   const bar = createAnimatedProgressBar({ width, showPercent: false, ctx });
-
-  let chunksProcessed = 0;
-  let bytesProcessed = 0;
-  let startTime = null;
-  let service = null;
-  let handler = null;
-
-  function onChunk({ size }) {
-    if (!startTime) {
-      startTime = Date.now();
-    }
-    chunksProcessed++;
-    bytesProcessed += size;
-
-    const pct = (chunksProcessed / totalChunks) * 100;
-    const elapsed = (Date.now() - startTime) / 1000;
-    const throughput = elapsed > 0 ? bytesProcessed / elapsed : 0;
-
-    if (ctx.mode === 'interactive') {
-      const status = `  ${label} ${chunksProcessed}/${totalChunks}  ${formatBytes(throughput)}/s  `;
-      process.stderr.write(`\r\x1b[K${status}`);
-      bar.update(pct);
-    } else if (chunksProcessed === 1 || chunksProcessed === totalChunks || chunksProcessed % 10 === 0) {
-      ctx.io.write(`${label} ${chunksProcessed}/${totalChunks}  ${Math.round(pct)}%\n`);
-    }
-  }
+  /** @type {TrackerState} */
+  const state = { chunksProcessed: 0, bytesProcessed: 0, startTime: null, service: null, handler: null };
+  const deps = { ctx, totalChunks, label, bar };
 
   return {
+    /** @param {Observer} svc */
     attach(svc) {
-      service = svc;
-      handler = onChunk;
+      state.service = svc;
+      state.handler = (/** @type {{ size: number }} */ evt) => handleChunkEvent(evt, state, deps);
       bar.start();
-      service.on(event, handler);
+      state.service.on(event, state.handler);
     },
     detach() {
-      if (service && handler) {
-        service.removeListener(event, handler);
-      }
-      const elapsed = startTime ? (Date.now() - startTime) / 1000 : 0;
-      const throughput = elapsed > 0 ? bytesProcessed / elapsed : 0;
-      const msg = `  ${label} ${chunksProcessed}/${totalChunks} done  ${formatBytes(throughput)}/s`;
-      bar.stop(msg);
+      if (state.service && state.handler) { state.service.removeListener(event, state.handler); }
+      const elapsed = state.startTime ? (Date.now() - state.startTime) / 1000 : 0;
+      const throughput = elapsed > 0 ? state.bytesProcessed / elapsed : 0;
+      bar.stop(`  ${label} ${state.chunksProcessed}/${totalChunks} done  ${formatBytes(throughput)}/s`);
     },
   };
 }
diff --git a/jsr.json b/jsr.json
index 354a84c..103ca72 100644
--- a/jsr.json
+++ b/jsr.json
@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-cas",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "exports": {
     ".": "./index.js",
     "./service": "./src/domain/services/CasService.js",
diff --git a/package.json b/package.json
index c3341ff..19f3e55 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-cas",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "description": "Content-addressed storage backed by Git's object database, with optional encryption and pluggable codecs",
   "type": "module",
   "main": "index.js",
@@ -83,6 +83,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
+    "@types/node": "^25.3.2",
     "eslint": "^9.17.0",
     "jsr": "^0.14.2",
     "prettier": "^3.4.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 488d30a..5e4d3e8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -36,6 +36,9 @@ importers:
       '@eslint/js':
         specifier: ^9.17.0
         version: 9.39.2
+      '@types/node':
+        specifier: ^25.3.2
+        version: 25.3.2
       eslint:
         specifier: ^9.17.0
         version: 9.39.2
@@ -47,7 +50,7 @@ importers:
         version: 3.8.1
       vitest:
         specifier: ^2.1.8
-        version: 2.1.9
+        version: 2.1.9(@types/node@25.3.2)
 
 packages:
 
@@ -440,6 +443,9 @@ packages:
   '@types/json-schema@7.0.15':
     resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
 
+  '@types/node@25.3.2':
+    resolution: {integrity: sha512-RpV6r/ij22zRRdyBPcxDeKAzH43phWVKEjL2iksqo1Vz3CuBUrgmPpPhALKiRfU7OMCmeeO9vECBMsV0hMTG8Q==}
+
   '@vitest/expect@2.1.9':
     resolution: {integrity: sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==}
 
@@ -867,6 +873,9 @@ packages:
     resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
     engines: {node: '>= 0.8.0'}
 
+  undici-types@7.18.2:
+    resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
+
   uri-js@4.4.1:
     resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
 
@@ -1196,6 +1205,10 @@ snapshots:
 
   '@types/json-schema@7.0.15': {}
 
+  '@types/node@25.3.2':
+    dependencies:
+      undici-types: 7.18.2
+
   '@vitest/expect@2.1.9':
     dependencies:
       '@vitest/spy': 2.1.9
@@ -1203,13 +1216,13 @@ snapshots:
       chai: 5.3.3
       tinyrainbow: 1.2.0
 
-  '@vitest/mocker@2.1.9(vite@5.4.21)':
+  '@vitest/mocker@2.1.9(vite@5.4.21(@types/node@25.3.2))':
     dependencies:
       '@vitest/spy': 2.1.9
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 5.4.21
+      vite: 5.4.21(@types/node@25.3.2)
 
   '@vitest/pretty-format@2.1.9':
     dependencies:
@@ -1645,17 +1658,19 @@ snapshots:
     dependencies:
       prelude-ls: 1.2.1
 
+  undici-types@7.18.2: {}
+
   uri-js@4.4.1:
     dependencies:
       punycode: 2.3.1
 
-  vite-node@2.1.9:
+  vite-node@2.1.9(@types/node@25.3.2):
     dependencies:
       cac: 6.7.14
       debug: 4.4.3
       es-module-lexer: 1.7.0
       pathe: 1.1.2
-      vite: 5.4.21
+      vite: 5.4.21(@types/node@25.3.2)
     transitivePeerDependencies:
       - '@types/node'
       - less
@@ -1667,18 +1682,19 @@ snapshots:
       - supports-color
       - terser
 
-  vite@5.4.21:
+  vite@5.4.21(@types/node@25.3.2):
     dependencies:
       esbuild: 0.21.5
       postcss: 8.5.6
       rollup: 4.57.1
     optionalDependencies:
+      '@types/node': 25.3.2
       fsevents: 2.3.3
 
-  vitest@2.1.9:
+  vitest@2.1.9(@types/node@25.3.2):
     dependencies:
       '@vitest/expect': 2.1.9
-      '@vitest/mocker': 2.1.9(vite@5.4.21)
+      '@vitest/mocker': 2.1.9(vite@5.4.21(@types/node@25.3.2))
       '@vitest/pretty-format': 2.1.9
       '@vitest/runner': 2.1.9
       '@vitest/snapshot': 2.1.9
@@ -1694,9 +1710,11 @@ snapshots:
       tinyexec: 0.3.2
       tinypool: 1.1.1
       tinyrainbow: 1.2.0
-      vite: 5.4.21
-      vite-node: 2.1.9
+      vite: 5.4.21(@types/node@25.3.2)
+      vite-node: 2.1.9(@types/node@25.3.2)
       why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 25.3.2
     transitivePeerDependencies:
       - less
       - lightningcss
diff --git a/src/domain/services/Semaphore.js b/src/domain/services/Semaphore.js
index 266bda2..507ed14 100644
--- a/src/domain/services/Semaphore.js
+++ b/src/domain/services/Semaphore.js
@@ -4,6 +4,7 @@
 export default class Semaphore {
   #max;
   #active = 0;
+  /** @type {Array<() => void>} */
   #queue = [];
 
   /**
@@ -35,8 +36,7 @@ export default class Semaphore {
    */
   release() {
     if (this.#queue.length > 0) {
-      const next = this.#queue.shift();
-      next();
+      /** @type {() => void} */ (this.#queue.shift())();
     } else {
       if (this.#active === 0) {
         throw new Error('Semaphore release called without an active permit');
diff --git a/src/domain/services/VaultService.js b/src/domain/services/VaultService.js
index ae8989f..2650ad3 100644
--- a/src/domain/services/VaultService.js
+++ b/src/domain/services/VaultService.js
@@ -7,6 +7,28 @@ const VAULT_REF = 'refs/cas/vault';
 const MAX_CAS_RETRIES = 3;
 const CAS_RETRY_BASE_MS = 50;
 
+/**
+ * Vault encryption metadata stored in .vault.json.
+ * @typedef {Object} VaultEncryptionMeta
+ * @property {string} cipher - Cipher algorithm (e.g. 'aes-256-gcm').
+ * @property {{ algorithm: string, salt: string, iterations?: number, cost?: number, blockSize?: number, parallelization?: number, keyLength: number }} kdf - KDF parameters.
+ */
+
+/**
+ * Vault metadata stored in .vault.json.
+ * @typedef {Object} VaultMetadata
+ * @property {number} version - Metadata version (currently 1).
+ * @property {VaultEncryptionMeta} [encryption] - Encryption configuration.
+ */
+
+/**
+ * Vault state read from refs/cas/vault.
+ * @typedef {Object} VaultState
+ * @property {Map<string, string>} entries - Slug→treeOid map.
+ * @property {string|null} parentCommitOid - Parent commit OID.
+ * @property {VaultMetadata|null} metadata - Vault metadata.
+ */
+
 /**
  * Percent-encodes a vault slug for use as a git tree entry name.
  * Git tree entry names cannot contain '/'.
@@ -59,9 +81,9 @@ export default class VaultService {
 
   /**
    * @param {Object} options
-   * @param {import('../../../src/ports/GitPersistencePort.js').default} options.persistence
-   * @param {import('../../../src/ports/GitRefPort.js').default} options.ref
-   * @param {import('../../../src/ports/CryptoPort.js').default} options.crypto
+   * @param {import('../../ports/GitPersistencePort.js').default} options.persistence
+   * @param {import('../../ports/GitRefPort.js').default} options.ref
+   * @param {import('../../ports/CryptoPort.js').default} options.crypto
    */
   constructor({ persistence, ref, crypto }) {
     this.persistence = persistence;
@@ -75,7 +97,8 @@ export default class VaultService {
 
   /**
    * Validates a single slug segment.
-   * @private
+   * @param {string} seg - Segment to validate.
+   * @param {string} slug - Full slug (for error context).
    */
   static #validateSegment(seg, slug) {
     if (seg.length === 0) {
@@ -118,7 +141,8 @@ export default class VaultService {
 
   /**
    * Validates encryption-specific metadata fields.
-   * @private
+   * @param {VaultEncryptionMeta} encryption - Encryption metadata.
+   * @param {VaultMetadata} metadata - Full metadata (for error context).
    */
   static #validateEncryption(encryption, metadata) {
     const { cipher, kdf } = encryption;
@@ -133,7 +157,7 @@ export default class VaultService {
 
   /**
    * Validates vault metadata object structure.
-   * @private
+   * @param {VaultMetadata} metadata - Metadata to validate.
    */
   static #validateMetadata(metadata) {
     if (typeof metadata.version !== 'number' || metadata.version !== 1) {
@@ -150,7 +174,8 @@ export default class VaultService {
 
   /**
    * Reads and validates vault metadata from a blob OID.
-   * @private
+   * @param {string} blobOid - Git blob OID of the .vault.json file.
+   * @returns {Promise<VaultMetadata>}
    */
   async #readMetadataBlob(blobOid) {
     try {
@@ -161,7 +186,7 @@ export default class VaultService {
     } catch (err) {
       if (err instanceof CasError) { throw err; }
       throw new CasError(
-        `Failed to parse .vault.json: ${err.message}`,
+        `Failed to parse .vault.json: ${/** @type {Error} */ (err).message}`,
         'VAULT_METADATA_INVALID',
         { originalError: err },
       );
@@ -174,8 +199,8 @@ export default class VaultService {
 
   /**
    * Separates vault tree entries into slug→OID map and metadata blob OID.
-   * @private
    * @param {Array<{ mode: string, type: string, oid: string, name: string }>} treeEntries
+   * @returns {{ entries: Map<string, string>, metadataBlobOid: string|null }}
    */
   static #parseTreeEntries(treeEntries) {
     const entries = new Map();
@@ -192,7 +217,7 @@ export default class VaultService {
 
   /**
    * Reads the current vault state from refs/cas/vault.
-   * @returns {Promise<{ entries: Map<string, string>, parentCommitOid: string|null, metadata: object|null }>}
+   * @returns {Promise<VaultState>}
    */
   async readState() {
     let commitOid;
@@ -216,7 +241,7 @@ export default class VaultService {
    * Writes a new vault commit and updates the ref atomically.
    * @param {Object} options
    * @param {Map<string, string>} options.entries - Slug→treeOid map.
-   * @param {object} options.metadata - Vault metadata (.vault.json contents).
+   * @param {VaultMetadata} options.metadata - Vault metadata (.vault.json contents).
    * @param {string|null} options.parentCommitOid - Parent commit OID (null for first commit).
    * @param {string} options.message - Commit message.
    * @returns {Promise<{ commitOid: string }>}
@@ -244,7 +269,8 @@ export default class VaultService {
 
   /**
    * Atomically updates the vault ref with CAS semantics.
-   * @private
+   * @param {string} newOid - New commit OID.
+   * @param {string|null} expectedOldOid - Expected current commit OID.
    */
   async #casUpdateRef(newOid, expectedOldOid) {
     try {
@@ -264,8 +290,7 @@ export default class VaultService {
 
   /**
    * Wraps a vault mutation with CAS retry logic.
-   * @private
-   * @param {function} mutationFn - Async function(state) → { entries, metadata, message }
+   * @param {(state: VaultState) => { entries: Map<string, string>, metadata: VaultMetadata, message: string }|Promise<{ entries: Map<string, string>, metadata: VaultMetadata, message: string }>} mutationFn - Mutation function (sync or async).
    * @returns {Promise<{ commitOid: string }>}
    */
   async #retryMutation(mutationFn) {
@@ -295,7 +320,9 @@ export default class VaultService {
 
   /**
    * Builds vault encryption metadata from KDF result.
-   * @private
+   * @param {Buffer} salt - KDF salt.
+   * @param {import('../../ports/CryptoPort.js').KdfParamSet} params - KDF parameters.
+   * @returns {VaultEncryptionMeta}
    */
   static #buildEncryptionMeta(salt, params) {
     return {
@@ -333,6 +360,7 @@ export default class VaultService {
       );
     }
 
+    /** @type {VaultMetadata} */
     const metadata = { version: 1 };
     if (passphrase) {
       const { salt, params } = await this.crypto.deriveKey({ passphrase, ...kdfOptions });
@@ -394,6 +422,7 @@ export default class VaultService {
    * @returns {Promise<{ commitOid: string, removedTreeOid: string }>}
    */
   async removeFromVault({ slug }) {
+    /** @type {string|undefined} */
     let removedTreeOid;
 
     const result = await this.#retryMutation((state) => {
@@ -413,7 +442,7 @@ export default class VaultService {
       };
     });
 
-    return { commitOid: result.commitOid, removedTreeOid };
+    return { commitOid: result.commitOid, removedTreeOid: /** @type {string} */ (removedTreeOid) };
   }
 
   /**
@@ -431,12 +460,12 @@ export default class VaultService {
         { slug },
       );
     }
-    return entries.get(slug);
+    return /** @type {string} */ (entries.get(slug));
   }
 
   /**
    * Returns the vault metadata, or null if no vault exists.
-   * @returns {Promise<object|null>}
+   * @returns {Promise<VaultMetadata|null>}
    */
   async getVaultMetadata() {
     const { metadata } = await this.readState();
diff --git a/src/infrastructure/adapters/BunCryptoAdapter.js b/src/infrastructure/adapters/BunCryptoAdapter.js
index c5b8e74..1d8b8ce 100644
--- a/src/infrastructure/adapters/BunCryptoAdapter.js
+++ b/src/infrastructure/adapters/BunCryptoAdapter.js
@@ -1,3 +1,4 @@
+// @ts-ignore -- 'bun' module only available in Bun runtime
 import { CryptoHasher } from 'bun';
 import CryptoPort from '../../ports/CryptoPort.js';
 import CasError from '../../domain/errors/CasError.js';
@@ -14,18 +15,31 @@ import { promisify } from 'node:util';
  * AES-256-GCM (Bun's Node compat layer is heavily optimized for these APIs).
  */
 export default class BunCryptoAdapter extends CryptoPort {
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buf - Data to hash.
+   * @returns {Promise<string>} 64-char hex digest.
+   */
   async sha256(buf) {
     return new CryptoHasher('sha256').update(buf).digest('hex');
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {number} n - Number of random bytes.
+   * @returns {Buffer}
+   */
   randomBytes(n) {
     const uint8 = globalThis.crypto.getRandomValues(new Uint8Array(n));
     return Buffer.from(uint8.buffer, uint8.byteOffset, uint8.byteLength);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buffer - Plaintext to encrypt.
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @returns {Promise<{ buf: Buffer, meta: import('../../ports/CryptoPort.js').EncryptionMeta }>}
+   */
   async encryptBuffer(buffer, key) {
     this._validateKey(key);
     const nonce = this.randomBytes(12);
@@ -38,7 +52,13 @@ export default class BunCryptoAdapter extends CryptoPort {
     };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buffer - Ciphertext to decrypt.
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @param {import('../../ports/CryptoPort.js').EncryptionMeta} meta - Encryption metadata.
+   * @returns {Promise<Buffer>}
+   */
   async decryptBuffer(buffer, key, meta) {
     this._validateKey(key);
     const nonce = Buffer.from(meta.nonce, 'base64');
@@ -48,13 +68,18 @@ export default class BunCryptoAdapter extends CryptoPort {
     return Buffer.concat([decipher.update(buffer), decipher.final()]);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @returns {{ encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>, finalize: () => import('../../ports/CryptoPort.js').EncryptionMeta }}
+   */
   createEncryptionStream(key) {
     this._validateKey(key);
     const nonce = this.randomBytes(12);
     const cipher = createCipheriv('aes-256-gcm', key, nonce);
     let streamFinalized = false;
 
+    /** @param {AsyncIterable<Buffer>} source */
     const encrypt = async function* (source) {
       for await (const chunk of source) {
         const encrypted = cipher.update(chunk);
@@ -83,11 +108,18 @@ export default class BunCryptoAdapter extends CryptoPort {
     return { encrypt, finalize };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} passphrase - The passphrase.
+   * @param {Buffer|Uint8Array} saltBuf - Salt bytes.
+   * @param {import('../../ports/CryptoPort.js').DeriveKeyParams} params - KDF parameters.
+   * @returns {Promise<Buffer>}
+   */
   async _doDeriveKey(passphrase, saltBuf, { algorithm, iterations, cost, blockSize, parallelization, keyLength }) {
     if (algorithm === 'pbkdf2') {
       return promisify(pbkdf2)(passphrase, saltBuf, iterations, keyLength, 'sha512');
     }
+    // @ts-ignore -- promisify(scrypt) accepts options as 4th arg at runtime
     return promisify(scrypt)(passphrase, saltBuf, keyLength, {
       N: cost,
       r: blockSize,
diff --git a/src/infrastructure/adapters/EventEmitterObserver.js b/src/infrastructure/adapters/EventEmitterObserver.js
index 2c227bb..163fc4c 100644
--- a/src/infrastructure/adapters/EventEmitterObserver.js
+++ b/src/infrastructure/adapters/EventEmitterObserver.js
@@ -16,8 +16,8 @@ export default class EventEmitterObserver {
    * Error metrics are only emitted when listeners are attached (matching
    * the previous CasService behavior that guarded `this.emit('error', ...)`).
    *
-   * @param {string} channel
-   * @param {Object} data - Must include `action` to form the event name.
+   * @param {string} channel - Metric channel.
+   * @param {Record<string, unknown> & { action: string }} data - Must include `action` to form the event name.
    */
   metric(channel, data) {
     if (channel === 'error') {
@@ -26,21 +26,33 @@ export default class EventEmitterObserver {
       }
       return;
     }
+    if (typeof data.action !== 'string') {
+      return;
+    }
     const eventName = `${channel}:${data.action}`;
     const payload = Object.fromEntries(Object.entries(data).filter(([k]) => k !== 'action'));
     this.#emitter.emit(eventName, payload);
   }
 
+  /**
+   * @param {'debug'|'info'|'warn'|'error'} _level - Log level.
+   * @param {string} _msg - Log message.
+   * @param {Record<string, unknown>} [_meta] - Optional metadata.
+   */
   log(_level, _msg, _meta) {}
 
+  /**
+   * @param {string} _name - Span name.
+   * @returns {{ end(meta?: Record<string, unknown>): void }}
+   */
   span(_name) {
     return { end() {} };
   }
 
   /**
    * Subscribe to an event.
-   * @param {string} event
-   * @param {Function} listener
+   * @param {string} event - Event name.
+   * @param {(...args: unknown[]) => void} listener - Event listener.
    * @returns {this}
    */
   on(event, listener) {
@@ -50,8 +62,8 @@ export default class EventEmitterObserver {
 
   /**
    * Remove a listener.
-   * @param {string} event
-   * @param {Function} listener
+   * @param {string} event - Event name.
+   * @param {(...args: unknown[]) => void} listener - Event listener.
    * @returns {this}
    */
   removeListener(event, listener) {
@@ -61,7 +73,7 @@ export default class EventEmitterObserver {
 
   /**
    * Return the number of listeners for an event.
-   * @param {string} event
+   * @param {string} event - Event name.
    * @returns {number}
    */
   listenerCount(event) {
diff --git a/src/infrastructure/adapters/GitPersistenceAdapter.js b/src/infrastructure/adapters/GitPersistenceAdapter.js
index 9e0805e..797be53 100644
--- a/src/infrastructure/adapters/GitPersistenceAdapter.js
+++ b/src/infrastructure/adapters/GitPersistenceAdapter.js
@@ -30,7 +30,11 @@ export default class GitPersistenceAdapter extends GitPersistencePort {
     this.policy = policy ?? DEFAULT_POLICY;
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|string} content - Data to store.
+   * @returns {Promise<string>} The Git OID of the stored blob.
+   */
   async writeBlob(content) {
     return this.policy.execute(() =>
       this.plumbing.execute({
@@ -40,7 +44,11 @@ export default class GitPersistenceAdapter extends GitPersistencePort {
     );
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string[]} entries - Lines in `git mktree` format.
+   * @returns {Promise<string>} The Git OID of the created tree.
+   */
   async writeTree(entries) {
     return this.policy.execute(() =>
       this.plumbing.execute({
@@ -50,7 +58,11 @@ export default class GitPersistenceAdapter extends GitPersistencePort {
     );
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} oid - Git object ID.
+   * @returns {Promise<Buffer>} The blob content.
+   */
   async readBlob(oid) {
     return this.policy.execute(async () => {
       const stream = await this.plumbing.executeStream({
@@ -62,7 +74,11 @@ export default class GitPersistenceAdapter extends GitPersistencePort {
     });
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} treeOid - Git tree OID.
+   * @returns {Promise<Array<{ mode: string, type: string, oid: string, name: string }>>}
+   */
   async readTree(treeOid) {
     return this.policy.execute(async () => {
       const output = await this.plumbing.execute({
@@ -73,7 +89,7 @@ export default class GitPersistenceAdapter extends GitPersistencePort {
         return [];
       }
 
-      return output.split('\0').filter(Boolean).map((entry) => {
+      return output.split('\0').filter(Boolean).map((/** @type {string} */ entry) => {
         // Format: <mode> <type> <oid>\t<name>
         const tabIndex = entry.indexOf('\t');
         if (tabIndex === -1) {
diff --git a/src/infrastructure/adapters/GitRefAdapter.js b/src/infrastructure/adapters/GitRefAdapter.js
index 1c70517..20759a6 100644
--- a/src/infrastructure/adapters/GitRefAdapter.js
+++ b/src/infrastructure/adapters/GitRefAdapter.js
@@ -29,21 +29,36 @@ export default class GitRefAdapter extends GitRefPort {
     this.policy = policy ?? DEFAULT_POLICY;
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} ref - Git ref to resolve.
+   * @returns {Promise<string>} The commit OID.
+   */
   async resolveRef(ref) {
     return this.policy.execute(() =>
       this.plumbing.execute({ args: ['rev-parse', ref] }),
     );
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} commitOid - Git commit OID.
+   * @returns {Promise<string>} The tree OID.
+   */
   async resolveTree(commitOid) {
     return this.policy.execute(() =>
       this.plumbing.execute({ args: ['rev-parse', `${commitOid}^{tree}`] }),
     );
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Object} options
+   * @param {string} options.treeOid - Tree OID for the commit.
+   * @param {string|null} [options.parentOid] - Parent commit OID.
+   * @param {string} options.message - Commit message.
+   * @returns {Promise<string>} The new commit OID.
+   */
   async createCommit({ treeOid, parentOid, message }) {
     const args = ['commit-tree', treeOid, '-m', message];
     if (parentOid) {
@@ -54,13 +69,20 @@ export default class GitRefAdapter extends GitRefPort {
     );
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Object} options
+   * @param {string} options.ref - Git ref to update.
+   * @param {string} options.newOid - New OID to set.
+   * @param {string|null} [options.expectedOldOid] - Expected current OID for CAS.
+   * @returns {Promise<void>}
+   */
   async updateRef({ ref, newOid, expectedOldOid }) {
     const args = ['update-ref', ref, newOid];
     if (expectedOldOid) {
       args.push(expectedOldOid);
     }
-    return this.policy.execute(() =>
+    await this.policy.execute(() =>
       this.plumbing.execute({ args }),
     );
   }
diff --git a/src/infrastructure/adapters/NodeCryptoAdapter.js b/src/infrastructure/adapters/NodeCryptoAdapter.js
index 255f04f..ea6c963 100644
--- a/src/infrastructure/adapters/NodeCryptoAdapter.js
+++ b/src/infrastructure/adapters/NodeCryptoAdapter.js
@@ -6,17 +6,30 @@ import CryptoPort from '../../ports/CryptoPort.js';
  * Node.js implementation of CryptoPort using node:crypto.
  */
 export default class NodeCryptoAdapter extends CryptoPort {
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buf - Data to hash.
+   * @returns {string} 64-char hex digest.
+   */
   sha256(buf) {
     return createHash('sha256').update(buf).digest('hex');
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {number} n - Number of random bytes.
+   * @returns {Buffer}
+   */
   randomBytes(n) {
     return randomBytes(n);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buffer - Plaintext to encrypt.
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @returns {{ buf: Buffer, meta: import('../../ports/CryptoPort.js').EncryptionMeta }}
+   */
   encryptBuffer(buffer, key) {
     this._validateKey(key);
     const nonce = randomBytes(12);
@@ -29,7 +42,13 @@ export default class NodeCryptoAdapter extends CryptoPort {
     };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buffer - Ciphertext to decrypt.
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @param {import('../../ports/CryptoPort.js').EncryptionMeta} meta - Encryption metadata.
+   * @returns {Buffer}
+   */
   decryptBuffer(buffer, key, meta) {
     const nonce = Buffer.from(meta.nonce, 'base64');
     const tag = Buffer.from(meta.tag, 'base64');
@@ -38,12 +57,17 @@ export default class NodeCryptoAdapter extends CryptoPort {
     return Buffer.concat([decipher.update(buffer), decipher.final()]);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @returns {{ encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>, finalize: () => import('../../ports/CryptoPort.js').EncryptionMeta }}
+   */
   createEncryptionStream(key) {
     this._validateKey(key);
     const nonce = randomBytes(12);
     const cipher = createCipheriv('aes-256-gcm', key, nonce);
 
+    /** @param {AsyncIterable<Buffer>} source */
     const encrypt = async function* (source) {
       for await (const chunk of source) {
         const encrypted = cipher.update(chunk);
@@ -65,11 +89,18 @@ export default class NodeCryptoAdapter extends CryptoPort {
     return { encrypt, finalize };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} passphrase - The passphrase.
+   * @param {Buffer|Uint8Array} saltBuf - Salt bytes.
+   * @param {import('../../ports/CryptoPort.js').DeriveKeyParams} params - KDF parameters.
+   * @returns {Promise<Buffer>}
+   */
   async _doDeriveKey(passphrase, saltBuf, { algorithm, iterations, cost, blockSize, parallelization, keyLength }) {
     if (algorithm === 'pbkdf2') {
       return await promisify(pbkdf2)(passphrase, saltBuf, iterations, keyLength, 'sha512');
     }
+    // @ts-ignore -- promisify(scrypt) accepts options as 4th arg at runtime
     return await promisify(scrypt)(passphrase, saltBuf, keyLength, {
       N: cost,
       r: blockSize,
diff --git a/src/infrastructure/adapters/SilentObserver.js b/src/infrastructure/adapters/SilentObserver.js
index e05e415..9e93d1f 100644
--- a/src/infrastructure/adapters/SilentObserver.js
+++ b/src/infrastructure/adapters/SilentObserver.js
@@ -3,8 +3,23 @@
  * Used as the default when no observability is configured.
  */
 export default class SilentObserver {
+  /**
+   * @param {string} _channel - Metric channel.
+   * @param {Record<string, unknown>} _data - Metric payload.
+   */
   metric(_channel, _data) {}
+
+  /**
+   * @param {'debug'|'info'|'warn'|'error'} _level - Log level.
+   * @param {string} _msg - Log message.
+   * @param {Record<string, unknown>} [_meta] - Optional metadata.
+   */
   log(_level, _msg, _meta) {}
+
+  /**
+   * @param {string} _name - Span name.
+   * @returns {{ end(meta?: Record<string, unknown>): void }}
+   */
   span(_name) {
     return { end() {} };
   }
diff --git a/src/infrastructure/adapters/StatsCollector.js b/src/infrastructure/adapters/StatsCollector.js
index a19a58a..4e6a90d 100644
--- a/src/infrastructure/adapters/StatsCollector.js
+++ b/src/infrastructure/adapters/StatsCollector.js
@@ -5,15 +5,20 @@ export default class StatsCollector {
   #chunksProcessed = 0;
   #bytesTotal = 0;
   #errors = 0;
+  /** @type {number|null} */
   #startTime = null;
 
+  /**
+   * @param {string} channel - Metric channel.
+   * @param {Record<string, unknown>} data - Metric payload.
+   */
   metric(channel, data) {
     if (!this.#startTime) {
       this.#startTime = Date.now();
     }
     if (channel === 'chunk') {
       this.#chunksProcessed++;
-      const size = Number.isFinite(data?.size) ? data.size : 0;
+      const size = Number.isFinite(data?.size) ? /** @type {number} */ (data.size) : 0;
       this.#bytesTotal += size;
     }
     if (channel === 'error') {
@@ -21,8 +26,17 @@ export default class StatsCollector {
     }
   }
 
+  /**
+   * @param {'debug'|'info'|'warn'|'error'} _level - Log level.
+   * @param {string} _msg - Log message.
+   * @param {Record<string, unknown>} [_meta] - Optional metadata.
+   */
   log(_level, _msg, _meta) {}
 
+  /**
+   * @param {string} _name - Span name.
+   * @returns {{ end(meta?: Record<string, unknown>): void }}
+   */
   span(_name) {
     return { end() {} };
   }
diff --git a/src/infrastructure/adapters/WebCryptoAdapter.js b/src/infrastructure/adapters/WebCryptoAdapter.js
index a6ffd51..5a70733 100644
--- a/src/infrastructure/adapters/WebCryptoAdapter.js
+++ b/src/infrastructure/adapters/WebCryptoAdapter.js
@@ -9,15 +9,24 @@ import CasError from '../../domain/errors/CasError.js';
  * AES-GCM is a one-shot API (the GCM tag is computed over the entire plaintext).
  */
 export default class WebCryptoAdapter extends CryptoPort {
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buf - Data to hash.
+   * @returns {Promise<string>} 64-char hex digest.
+   */
   async sha256(buf) {
+    // @ts-ignore -- Buffer satisfies BufferSource at runtime; TS strictness mismatch
     const hashBuffer = await globalThis.crypto.subtle.digest('SHA-256', buf);
     return Array.from(new Uint8Array(hashBuffer))
       .map(b => b.toString(16).padStart(2, '0'))
       .join('');
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {number} n - Number of random bytes.
+   * @returns {Buffer|Uint8Array}
+   */
   randomBytes(n) {
     const uint8 = globalThis.crypto.getRandomValues(new Uint8Array(n));
     if (globalThis.Buffer) {
@@ -26,7 +35,12 @@ export default class WebCryptoAdapter extends CryptoPort {
     return uint8;
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buffer - Plaintext to encrypt.
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @returns {Promise<{ buf: Buffer, meta: import('../../ports/CryptoPort.js').EncryptionMeta }>}
+   */
   async encryptBuffer(buffer, key) {
     this._validateKey(key);
     const nonce = this.randomBytes(12);
@@ -34,7 +48,8 @@ export default class WebCryptoAdapter extends CryptoPort {
 
     // AES-GCM in Web Crypto includes the tag at the end of the ciphertext
     const encrypted = await globalThis.crypto.subtle.encrypt(
-      { name: 'AES-GCM', iv: nonce },
+      // @ts-ignore -- Uint8Array satisfies BufferSource at runtime
+      { name: 'AES-GCM', iv: /** @type {Uint8Array} */ (nonce) },
       cryptoKey,
       buffer
     );
@@ -50,7 +65,13 @@ export default class WebCryptoAdapter extends CryptoPort {
     };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} buffer - Ciphertext to decrypt.
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @param {import('../../ports/CryptoPort.js').EncryptionMeta} meta - Encryption metadata.
+   * @returns {Promise<Buffer>}
+   */
   async decryptBuffer(buffer, key, meta) {
     const nonce = this.#fromBase64(meta.nonce);
     const tag = this.#fromBase64(meta.tag);
@@ -63,7 +84,8 @@ export default class WebCryptoAdapter extends CryptoPort {
 
     try {
       const decrypted = await globalThis.crypto.subtle.decrypt(
-        { name: 'AES-GCM', iv: nonce },
+        // @ts-ignore -- Uint8Array satisfies BufferSource at runtime
+        { name: 'AES-GCM', iv: /** @type {Uint8Array} */ (nonce) },
         cryptoKey,
         combined
       );
@@ -73,20 +95,24 @@ export default class WebCryptoAdapter extends CryptoPort {
     }
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|Uint8Array} key - 32-byte encryption key.
+   * @returns {{ encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>, finalize: () => import('../../ports/CryptoPort.js').EncryptionMeta }}
+   */
   createEncryptionStream(key) {
     this._validateKey(key);
     const nonce = this.randomBytes(12);
     const cryptoKeyPromise = this.#importKey(key);
 
-    // Web Crypto doesn't have a native streaming AES-GCM API like Node
-    // We have to buffer for the one-shot call because GCM tag is computed over the whole thing.
-    // NOTE: This limits the "stream" to memory capacity, matching the project's
-    // current CasService.restore limitation.
+    // Web Crypto buffers all data for the one-shot AES-GCM call (GCM tag spans the whole plaintext).
+    /** @type {Buffer[]} */
     const chunks = [];
+    /** @type {Uint8Array|null} */
     let finalTag = null;
     let streamConsumed = false;
 
+    /** @param {AsyncIterable<Buffer>} source */
     const encrypt = async function* (source) {
       for await (const chunk of source) {
         chunks.push(chunk);
@@ -95,7 +121,8 @@ export default class WebCryptoAdapter extends CryptoPort {
       const buffer = Buffer.concat(chunks);
       const cryptoKey = await cryptoKeyPromise;
       const encrypted = await globalThis.crypto.subtle.encrypt(
-        { name: 'AES-GCM', iv: nonce },
+        // @ts-ignore -- Uint8Array satisfies BufferSource at runtime
+        { name: 'AES-GCM', iv: /** @type {Uint8Array} */ (nonce) },
         cryptoKey,
         buffer
       );
@@ -116,13 +143,19 @@ export default class WebCryptoAdapter extends CryptoPort {
           'STREAM_NOT_CONSUMED',
         );
       }
-      return this._buildMeta(this.#toBase64(nonce), this.#toBase64(finalTag));
+      return this._buildMeta(this.#toBase64(nonce), this.#toBase64(/** @type {Uint8Array} */ (finalTag)));
     };
 
     return { encrypt, finalize };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {string} passphrase - The passphrase.
+   * @param {Buffer|Uint8Array} saltBuf - Salt bytes.
+   * @param {import('../../ports/CryptoPort.js').DeriveKeyParams} params - KDF parameters.
+   * @returns {Promise<Buffer>}
+   */
   async _doDeriveKey(passphrase, saltBuf, { algorithm, iterations, cost, blockSize, parallelization, keyLength }) {
     if (algorithm === 'pbkdf2') {
       return this.#derivePbkdf2(passphrase, saltBuf, { iterations, keyLength });
@@ -130,18 +163,33 @@ export default class WebCryptoAdapter extends CryptoPort {
     return this.#deriveScrypt(passphrase, saltBuf, { cost, blockSize, parallelization, keyLength });
   }
 
+  /**
+   * Derives a key using PBKDF2 via Web Crypto.
+   * @param {string} passphrase - The passphrase.
+   * @param {Buffer|Uint8Array} saltBuf - Salt bytes.
+   * @param {{ iterations: number, keyLength: number }} params - PBKDF2 parameters.
+   * @returns {Promise<Buffer>}
+   */
   async #derivePbkdf2(passphrase, saltBuf, params) {
     const enc = new globalThis.TextEncoder();
     const baseKey = await globalThis.crypto.subtle.importKey(
       'raw', enc.encode(passphrase), 'PBKDF2', false, ['deriveBits'],
     );
     const bits = await globalThis.crypto.subtle.deriveBits(
-      { name: 'PBKDF2', salt: saltBuf, iterations: params.iterations, hash: 'SHA-512' },
+      // @ts-ignore -- Uint8Array satisfies BufferSource at runtime
+      { name: 'PBKDF2', salt: /** @type {Uint8Array} */ (saltBuf), iterations: params.iterations, hash: 'SHA-512' },
       baseKey, params.keyLength * 8,
     );
     return Buffer.from(bits);
   }
 
+  /**
+   * Derives a key using scrypt via Node's crypto module (fallback).
+   * @param {string} passphrase - The passphrase.
+   * @param {Buffer|Uint8Array} saltBuf - Salt bytes.
+   * @param {{ cost: number, blockSize: number, parallelization: number, keyLength: number }} params - scrypt parameters.
+   * @returns {Promise<Buffer>}
+   */
   async #deriveScrypt(passphrase, saltBuf, params) {
     let scryptCb;
     let promisifyFn;
@@ -151,6 +199,7 @@ export default class WebCryptoAdapter extends CryptoPort {
     } catch {
       throw new Error('scrypt KDF requires a Node.js-compatible runtime (node:crypto unavailable)');
     }
+    // @ts-ignore -- promisify(scrypt) accepts options as 4th arg at runtime
     return promisifyFn(scryptCb)(passphrase, saltBuf, params.keyLength, {
       N: params.cost, r: params.blockSize, p: params.parallelization,
     });
@@ -164,7 +213,8 @@ export default class WebCryptoAdapter extends CryptoPort {
   async #importKey(rawKey) {
     return globalThis.crypto.subtle.importKey(
       'raw',
-      rawKey,
+      // @ts-ignore -- Buffer/Uint8Array satisfies BufferSource at runtime
+      /** @type {Uint8Array} */ (rawKey),
       { name: 'AES-GCM' },
       false,
       ['encrypt', 'decrypt']
@@ -173,7 +223,7 @@ export default class WebCryptoAdapter extends CryptoPort {
 
   /**
    * Encodes binary data to base64, using Buffer when available.
-   * @param {Uint8Array} buf
+   * @param {Buffer|Uint8Array} buf - Binary data to encode.
    * @returns {string}
    */
   #toBase64(buf) {
@@ -185,7 +235,7 @@ export default class WebCryptoAdapter extends CryptoPort {
 
   /**
    * Decodes a base64 string to binary, using Buffer when available.
-   * @param {string} str
+   * @param {string} str - Base64-encoded string.
    * @returns {Buffer|Uint8Array}
    */
   #fromBase64(str) {
diff --git a/src/infrastructure/chunkers/FixedChunker.js b/src/infrastructure/chunkers/FixedChunker.js
index 0f904fa..1477e18 100644
--- a/src/infrastructure/chunkers/FixedChunker.js
+++ b/src/infrastructure/chunkers/FixedChunker.js
@@ -30,7 +30,11 @@ export default class FixedChunker extends ChunkingPort {
     return { chunkSize: this.#chunkSize };
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {AsyncIterable<Buffer>} source - The input byte stream.
+   * @yields {Buffer}
+   */
   async *chunk(source) {
     let buffer = Buffer.alloc(0);
 
diff --git a/src/infrastructure/codecs/CborCodec.js b/src/infrastructure/codecs/CborCodec.js
index ec0d1b4..b89984e 100644
--- a/src/infrastructure/codecs/CborCodec.js
+++ b/src/infrastructure/codecs/CborCodec.js
@@ -5,14 +5,22 @@ import { encode, decode } from 'cbor-x';
  * {@link CodecPort} implementation that serializes manifests as CBOR (binary).
  */
 export default class CborCodec extends CodecPort {
-  /** @override */
+  /**
+   * @override
+   * @param {Record<string, unknown>} data - Data to encode.
+   * @returns {Buffer}
+   */
   encode(data) {
     return encode(data);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|string} buffer - CBOR-encoded data.
+   * @returns {Record<string, unknown>}
+   */
   decode(buffer) {
-    return decode(buffer);
+    return decode(/** @type {Buffer} */ (buffer));
   }
 
   /** @override */
diff --git a/src/infrastructure/codecs/JsonCodec.js b/src/infrastructure/codecs/JsonCodec.js
index 8f219f5..f45db3b 100644
--- a/src/infrastructure/codecs/JsonCodec.js
+++ b/src/infrastructure/codecs/JsonCodec.js
@@ -4,14 +4,22 @@ import CodecPort from '../../ports/CodecPort.js';
  * {@link CodecPort} implementation that serializes manifests as pretty-printed JSON.
  */
 export default class JsonCodec extends CodecPort {
-  /** @override */
+  /**
+   * @override
+   * @param {Record<string, unknown>} data - Data to encode.
+   * @returns {string}
+   */
   encode(data) {
     // Determine if we need to handle Buffers specially for JSON
     // For now, we assume data is JSON-safe or uses toJSON() methods
     return JSON.stringify(data, null, 2);
   }
 
-  /** @override */
+  /**
+   * @override
+   * @param {Buffer|string} buffer - JSON-encoded data.
+   * @returns {Record<string, unknown>}
+   */
   decode(buffer) {
     return JSON.parse(buffer.toString('utf8'));
   }
diff --git a/src/ports/CodecPort.js b/src/ports/CodecPort.js
index c7d1235..46c159c 100644
--- a/src/ports/CodecPort.js
+++ b/src/ports/CodecPort.js
@@ -5,7 +5,7 @@
 export default class CodecPort {
   /**
    * Encodes data to a Buffer or string.
-   * @param {Object} data
+   * @param {Record<string, unknown>} _data - Data to encode.
    * @returns {Buffer|string}
    */
   encode(_data) {
@@ -14,8 +14,8 @@ export default class CodecPort {
 
   /**
    * Decodes data from a Buffer or string.
-   * @param {Buffer|string} buffer
-   * @returns {Object}
+   * @param {Buffer|string} _buffer - Encoded data to decode.
+   * @returns {Record<string, unknown>}
    */
   decode(_buffer) {
     throw new Error('Not implemented');
diff --git a/src/ports/CryptoPort.js b/src/ports/CryptoPort.js
index fcddef7..7259ed5 100644
--- a/src/ports/CryptoPort.js
+++ b/src/ports/CryptoPort.js
@@ -1,5 +1,37 @@
 import CasError from '../domain/errors/CasError.js';
 
+/**
+ * Encryption metadata returned by AES-256-GCM operations.
+ * @typedef {Object} EncryptionMeta
+ * @property {string} algorithm - Cipher algorithm identifier (e.g. `'aes-256-gcm'`).
+ * @property {string} nonce - Base64-encoded 12-byte nonce.
+ * @property {string} tag - Base64-encoded 16-byte GCM authentication tag.
+ * @property {boolean} encrypted - Whether the data is encrypted.
+ */
+
+/**
+ * KDF parameter set stored alongside derived keys.
+ * @typedef {Object} KdfParamSet
+ * @property {'pbkdf2'|'scrypt'} algorithm - KDF algorithm.
+ * @property {string} salt - Base64-encoded salt.
+ * @property {number} [iterations] - PBKDF2 iterations (present when algorithm is pbkdf2).
+ * @property {number} [cost] - scrypt cost N (present when algorithm is scrypt).
+ * @property {number} [blockSize] - scrypt block size r.
+ * @property {number} [parallelization] - scrypt parallelization p.
+ * @property {number} keyLength - Derived key length in bytes.
+ */
+
+/**
+ * Normalized KDF options passed to `_doDeriveKey`.
+ * @typedef {Object} DeriveKeyParams
+ * @property {string} algorithm - KDF algorithm.
+ * @property {number} iterations - PBKDF2 iteration count.
+ * @property {number} cost - scrypt cost (N).
+ * @property {number} blockSize - scrypt block size (r).
+ * @property {number} parallelization - scrypt parallelization (p).
+ * @property {number} keyLength - Derived key length in bytes.
+ */
+
 /**
  * Abstract port for cryptographic operations (hashing, random bytes, AES-256-GCM).
  * @abstract
@@ -7,8 +39,8 @@ import CasError from '../domain/errors/CasError.js';
 export default class CryptoPort {
   /**
    * Returns the SHA-256 hex digest of a buffer.
-   * @param {Buffer} buf
-   * @returns {string} 64-char hex digest
+   * @param {Buffer|Uint8Array} _buf - Data to hash.
+   * @returns {string|Promise<string>} 64-char hex digest.
    */
   sha256(_buf) {
     throw new Error('Not implemented');
@@ -16,8 +48,8 @@ export default class CryptoPort {
 
   /**
    * Returns a Buffer of n cryptographically random bytes.
-   * @param {number} n
-   * @returns {Buffer}
+   * @param {number} _n - Number of random bytes.
+   * @returns {Buffer|Uint8Array}
    */
   randomBytes(_n) {
     throw new Error('Not implemented');
@@ -25,9 +57,9 @@ export default class CryptoPort {
 
   /**
    * Encrypts a buffer using AES-256-GCM.
-   * @param {Buffer} buffer
-   * @param {Buffer} key - 32-byte encryption key
-   * @returns {{ buf: Buffer, meta: { algorithm: string, nonce: string, tag: string, encrypted: boolean } }}
+   * @param {Buffer|Uint8Array} _buffer - Plaintext to encrypt.
+   * @param {Buffer|Uint8Array} _key - 32-byte encryption key.
+   * @returns {{ buf: Buffer, meta: EncryptionMeta }|Promise<{ buf: Buffer, meta: EncryptionMeta }>}
    */
   encryptBuffer(_buffer, _key) {
     throw new Error('Not implemented');
@@ -35,11 +67,11 @@ export default class CryptoPort {
 
   /**
    * Decrypts a buffer using AES-256-GCM.
-   * @param {Buffer} buffer
-   * @param {Buffer} key - 32-byte encryption key
-   * @param {{ algorithm: string, nonce: string, tag: string, encrypted: boolean }} meta
-   * @returns {Buffer}
-   * @throws on authentication failure
+   * @param {Buffer|Uint8Array} _buffer - Ciphertext to decrypt.
+   * @param {Buffer|Uint8Array} _key - 32-byte encryption key.
+   * @param {EncryptionMeta} _meta - Encryption metadata from the encrypt operation.
+   * @returns {Buffer|Promise<Buffer>}
+   * @throws on authentication failure.
    */
   decryptBuffer(_buffer, _key, _meta) {
     throw new Error('Not implemented');
@@ -47,8 +79,8 @@ export default class CryptoPort {
 
   /**
    * Creates a streaming encryption context.
-   * @param {Buffer} key - 32-byte encryption key
-   * @returns {{ encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>, finalize: () => { algorithm: string, nonce: string, tag: string, encrypted: boolean } }}
+   * @param {Buffer|Uint8Array} _key - 32-byte encryption key.
+   * @returns {{ encrypt: (source: AsyncIterable<Buffer>) => AsyncIterable<Buffer>, finalize: () => EncryptionMeta }}
    */
   createEncryptionStream(_key) {
     throw new Error('Not implemented');
@@ -62,14 +94,14 @@ export default class CryptoPort {
    *
    * @param {Object} options
    * @param {string} options.passphrase - The passphrase to derive a key from.
-   * @param {Buffer} [options.salt] - Salt for the KDF (random if omitted).
+   * @param {Buffer|Uint8Array} [options.salt] - Salt for the KDF (random if omitted).
    * @param {'pbkdf2'|'scrypt'} [options.algorithm='pbkdf2'] - KDF algorithm.
    * @param {number} [options.iterations=100000] - PBKDF2 iteration count.
    * @param {number} [options.cost=16384] - scrypt cost parameter (N).
    * @param {number} [options.blockSize=8] - scrypt block size (r).
    * @param {number} [options.parallelization=1] - scrypt parallelization (p).
    * @param {number} [options.keyLength=32] - Derived key length in bytes.
-   * @returns {Promise<{ key: Buffer, salt: Buffer, params: { algorithm: string, salt: string, iterations?: number, cost?: number, blockSize?: number, parallelization?: number, keyLength: number } }>}
+   * @returns {Promise<{ key: Buffer, salt: Buffer, params: KdfParamSet }>}
    */
   async deriveKey({
     passphrase,
@@ -83,6 +115,7 @@ export default class CryptoPort {
   }) {
     const saltBuf = salt || this.randomBytes(32);
 
+    /** @type {KdfParamSet} */
     const params = {
       algorithm,
       salt: Buffer.from(saltBuf).toString('base64'),
@@ -114,9 +147,9 @@ export default class CryptoPort {
   /**
    * Adapter-specific key derivation. Override in subclasses.
    * @abstract
-   * @param {string} passphrase
-   * @param {Buffer|Uint8Array} saltBuf
-   * @param {Object} params - Normalized KDF parameters.
+   * @param {string} _passphrase - The passphrase.
+   * @param {Buffer|Uint8Array} _saltBuf - Salt bytes.
+   * @param {DeriveKeyParams} _params - Normalized KDF parameters.
    * @returns {Promise<Buffer|Uint8Array>} Derived key bytes.
    */
   async _doDeriveKey(_passphrase, _saltBuf, _params) {
@@ -125,9 +158,9 @@ export default class CryptoPort {
 
   /**
    * Validates that a key is a 32-byte Buffer or Uint8Array.
-   * @param {Buffer|Uint8Array} key
-   * @throws {CasError} INVALID_KEY_TYPE if key is not a Buffer or Uint8Array
-   * @throws {CasError} INVALID_KEY_LENGTH if key is not 32 bytes
+   * @param {Buffer|Uint8Array} key - Key to validate.
+   * @throws {CasError} INVALID_KEY_TYPE if key is not a Buffer or Uint8Array.
+   * @throws {CasError} INVALID_KEY_LENGTH if key is not 32 bytes.
    */
   _validateKey(key) {
     if (!globalThis.Buffer?.isBuffer(key) && !(key instanceof Uint8Array)) {
@@ -149,7 +182,7 @@ export default class CryptoPort {
    * Builds the encryption metadata object from base64-encoded nonce and tag.
    * @param {string} nonce64 - Base64-encoded 12-byte AES-GCM nonce.
    * @param {string} tag64 - Base64-encoded 16-byte GCM authentication tag.
-   * @returns {{ algorithm: string, nonce: string, tag: string, encrypted: boolean }}
+   * @returns {EncryptionMeta}
    */
   _buildMeta(nonce64, tag64) {
     return {
diff --git a/src/ports/GitPersistencePort.js b/src/ports/GitPersistencePort.js
index 59352d2..d28526e 100644
--- a/src/ports/GitPersistencePort.js
+++ b/src/ports/GitPersistencePort.js
@@ -5,7 +5,7 @@
 export default class GitPersistencePort {
   /**
    * Writes content as a Git blob object.
-   * @param {Buffer|string} content - Data to store.
+   * @param {Buffer|string} _content - Data to store.
    * @returns {Promise<string>} The Git OID of the stored blob.
    */
   async writeBlob(_content) {
@@ -14,7 +14,7 @@ export default class GitPersistencePort {
 
   /**
    * Creates a Git tree object from formatted entries.
-   * @param {string[]} entries - Lines in `git mktree` format.
+   * @param {string[]} _entries - Lines in `git mktree` format.
    * @returns {Promise<string>} The Git OID of the created tree.
    */
   async writeTree(_entries) {
@@ -23,7 +23,7 @@ export default class GitPersistencePort {
 
   /**
    * Reads a Git blob by its OID.
-   * @param {string} oid - Git object ID.
+   * @param {string} _oid - Git object ID.
    * @returns {Promise<Buffer>} The blob content.
    */
   async readBlob(_oid) {
@@ -32,7 +32,7 @@ export default class GitPersistencePort {
 
   /**
    * Reads and parses a Git tree object.
-   * @param {string} treeOid - Git tree OID.
+   * @param {string} _treeOid - Git tree OID.
    * @returns {Promise<Array<{ mode: string, type: string, oid: string, name: string }>>} Parsed tree entries.
    */
   async readTree(_treeOid) {
diff --git a/src/ports/GitRefPort.js b/src/ports/GitRefPort.js
index 5058b2c..82cf09a 100644
--- a/src/ports/GitRefPort.js
+++ b/src/ports/GitRefPort.js
@@ -5,7 +5,7 @@
 export default class GitRefPort {
   /**
    * Resolves a Git ref to its commit OID.
-   * @param {string} ref - Git ref (e.g. 'refs/cas/vault').
+   * @param {string} _ref - Git ref (e.g. 'refs/cas/vault').
    * @returns {Promise<string>} The commit OID.
    * @throws If the ref does not exist.
    */
@@ -15,7 +15,7 @@ export default class GitRefPort {
 
   /**
    * Resolves the tree OID from a commit OID.
-   * @param {string} commitOid - Git commit OID.
+   * @param {string} _commitOid - Git commit OID.
    * @returns {Promise<string>} The tree OID.
    */
   async resolveTree(_commitOid) {
@@ -24,10 +24,10 @@ export default class GitRefPort {
 
   /**
    * Creates a Git commit object.
-   * @param {Object} options
-   * @param {string} options.treeOid - Tree OID for the commit.
-   * @param {string|null} [options.parentOid] - Parent commit OID (null for root commit).
-   * @param {string} options.message - Commit message.
+   * @param {Object} _options
+   * @param {string} _options.treeOid - Tree OID for the commit.
+   * @param {string|null} [_options.parentOid] - Parent commit OID (null for root commit).
+   * @param {string} _options.message - Commit message.
    * @returns {Promise<string>} The new commit OID.
    */
   async createCommit(_options) {
@@ -36,10 +36,10 @@ export default class GitRefPort {
 
   /**
    * Atomically updates a Git ref with optional CAS (compare-and-swap) semantics.
-   * @param {Object} options
-   * @param {string} options.ref - Git ref to update.
-   * @param {string} options.newOid - New OID to set.
-   * @param {string|null} [options.expectedOldOid] - Expected current OID for CAS. If provided and mismatched, throws.
+   * @param {Object} _options
+   * @param {string} _options.ref - Git ref to update.
+   * @param {string} _options.newOid - New OID to set.
+   * @param {string|null} [_options.expectedOldOid] - Expected current OID for CAS.
    * @returns {Promise<void>}
    */
   async updateRef(_options) {
diff --git a/src/types/ambient.d.ts b/src/types/ambient.d.ts
new file mode 100644
index 0000000..04686c5
--- /dev/null
+++ b/src/types/ambient.d.ts
@@ -0,0 +1,37 @@
+/**
+ * Ambient module declarations for dependencies that lack type definitions.
+ */
+
+declare module '@git-stunts/plumbing' {
+  interface ExecuteOptions {
+    args: string[];
+    input?: string | Buffer;
+  }
+
+  interface StreamResult {
+    collect(options?: { asString?: boolean }): Promise<Uint8Array>;
+  }
+
+  interface ShellRunner {
+    run(command: string, args: string[], options?: Record<string, unknown>): Promise<unknown>;
+  }
+
+  export class ShellRunnerFactory {
+    static create(options?: Record<string, unknown>): ShellRunner;
+  }
+
+  export default class GitPlumbing {
+    constructor(options: { runner: ShellRunner; cwd?: string });
+    execute(options: ExecuteOptions): Promise<string>;
+    executeStream(options: ExecuteOptions): Promise<StreamResult>;
+  }
+}
+
+declare module 'bun' {
+  export class CryptoHasher {
+    constructor(algorithm: string);
+    update(data: Buffer | Uint8Array | string): this;
+    digest(encoding: 'hex'): string;
+    digest(): Uint8Array;
+  }
+}
diff --git a/tsconfig.checkjs.json b/tsconfig.checkjs.json
new file mode 100644
index 0000000..02cc267
--- /dev/null
+++ b/tsconfig.checkjs.json
@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "checkJs": true,
+    "allowJs": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "exactOptionalPropertyTypes": false
+  },
+  "include": [
+    "index.js",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "index.d.ts",
+    "bin/**/*.js"
+  ],
+  "exclude": [
+    "node_modules",
+    "test",
+    "examples"
+  ]
+}