wowbagger 0.1.0-alpha.9 → 0.5.0

package/src/git-autocommit.js

@@ -50,6 +50,8 @@ const GIT_ENVIRONMENT = Object.fromEntries(
 const COMMIT_SUBJECT_VERBS = {
   create: 'create',
   transition: 'transition',
+  'parent-migrate': 'parent-migrate',
+  snooze: 'snooze',
   patch: 'patch',
   'publish-claimed': 'publish claimed',
 };
@@ -117,17 +119,28 @@ async function finalize({
 }) {
   const { root, prefix } = placement;
   const logPath = ledgerRelative(ledgerDirectory, claimReconcileLogPath(path.resolve(ledgerDirectory), namespace));
-  const journalOwned = command !== 'create';
+  // Every mutation, create included, appends its own journal entries and
+  // rebuilds the derived reconciliation log, so every commit set carries that
+  // log alongside the item.
+  //
+  // Log dirt that predates the invocation is a separate question. A mutation on
+  // an existing item rebuilds residue its own prior claim operations left in
+  // this checkout; a create allocates a fresh identity and has no standing to
+  // absorb bytes that were already there, so it refuses instead.
+  const absorbsPriorLogDirt = command !== 'create';
 
-  // Preflight, before any Wowbagger write. Any staged path anywhere and any
-  // dirty path under the ledger refuses: a broad commit would otherwise absorb
-  // foreign work, and this profile has no temporary index to protect it.
+  // Preflight, before any Wowbagger write. Any staged path and every dirty
+  // ledger path except an absorbable derived log refuse: a broad commit would
+  // otherwise take in foreign work.
   const before = await inspectWorktree(root, prefix);
   if (before.staged.length > 0) {
     return shape.preflightFailed('staged-paths-present', { staged_paths: bounded(before.staged) });
   }
-  if (before.dirtyLedger.length > 0) {
-    return shape.preflightFailed('ledger-not-clean', { dirty_paths: bounded(before.dirtyLedger) });
+  const foreignDirtyBefore = before.dirtyLedger.filter((entry) => (
+    !(absorbsPriorLogDirt && entry === logPath)
+  ));
+  if (foreignDirtyBefore.length > 0) {
+    return shape.preflightFailed('ledger-not-clean', { dirty_paths: bounded(foreignDirtyBefore) });
   }
   if (!await hasCommitIdentity(root)) {
     return shape.preflightFailed('identity-unavailable', {});
@@ -141,24 +154,32 @@ async function finalize({
   //
   // A nonzero claim-verify is exactly the unsafe claim state, so this one check
   // is the whole gate. An invalid ledger is deliberately NOT re-checked here:
-  // every one of the four mutations already refuses it with ledger-invalid and
-  // state unchanged, and duplicating that would add a branch no fixture can
-  // distinguish from the mutation's own refusal.
-  const verified = await verifyClaimJournal({ ledgerDirectory, gitCommonDir, namespace, targetItemId });
+  // every one of the auto-commit mutations already refuses it with
+  // ledger-invalid and state unchanged, and duplicating that would add a
+  // branch no fixture can distinguish from the mutation's own refusal.
+  const verified = await verifyClaimJournal({
+    ledgerDirectory,
+    gitCommonDir,
+    namespace,
+    targetItemId,
+    writeLogOnUnsafe: false,
+    writeLogWhenEmpty: false,
+  });
   if (verified.exit !== 0 || verified.stdout.ok !== true) {
+    const details = claimVerificationFailureDetails(verified);
     return shape.preflightFailed('claim-state-unreconciled', {
-      claim_verify_code: verified.stdout.error?.code ?? null,
-      findings: verified.stdout.result?.findings ?? [],
+      ...details,
+      retryable: details.claim_verify_reason === 'claim-store-locked',
     });
   }
 
-  // Reconciliation rewrites the tracked log. Only a command that will commit
-  // that log may proceed with it dirty; create commits the item alone.
+  // Reconciliation rewrites the tracked log. Every command here will commit
+  // that log, so its own rewrite is never stray; anything else is.
   const afterVerify = await inspectWorktree(root, prefix);
   if (afterVerify.staged.length > 0) {
     return shape.preflightFailed('staged-paths-present', { staged_paths: bounded(afterVerify.staged) });
   }
-  const strayBefore = afterVerify.dirtyLedger.filter((entry) => !(journalOwned && entry === logPath));
+  const strayBefore = afterVerify.dirtyLedger.filter((entry) => entry !== logPath);
   if (strayBefore.length > 0) {
     return shape.preflightFailed('ledger-not-clean', { dirty_paths: bounded(strayBefore) });
   }
@@ -194,10 +215,13 @@ async function finalize({
     });
   }
   published.revision = identity.revision;
-
-  const commitSet = [published.path, ...(journalOwned ? [logPath] : [])].sort(compareText);
+  const itemChanged = await itemDiffersFromHead(root, prefix, published.path, published.revision);
+  const commitSet = [
+    ...(itemChanged ? [published.path] : []),
+    logPath,
+  ].sort(compareText);
   const subject = commitSubject(command, published.number, published.id);
-  const witness = journalOwned ? shape.terminalWitness(outcome, published) : null;
+  const witness = shape.terminalWitness(outcome, published);
   const context = {
     command,
     head,
@@ -216,7 +240,6 @@ async function finalize({
     context,
     commitSet,
     digests,
-    journalOwned,
     ledgerDirectory,
     logPath,
     ownArtifacts: shape.recoveryArtifactPaths(outcome),
@@ -271,6 +294,7 @@ async function finalize({
     gitCommonDir,
     namespace,
     targetItemId: published.id,
+    writeLogWhenEmpty: true,
   });
   const reconciliation = reconciliationFailureReason(reconciled, commit.commit, context.operationId, published.id);
   if (reconciliation) {
@@ -279,8 +303,7 @@ async function finalize({
       published_revision: published.revision,
       git_commit: commit.commit,
       commit_paths: commitSet,
-      reason: reconciliation.reason,
-      findings: reconciliation.findings,
+      ...reconciliation,
     });
   }
   return shape.decorate(outcome, evidence);
@@ -289,7 +312,7 @@ async function finalize({
 // Every check that must hold between publication and staging. Returning a
 // reason here means the item is published and no Git write has happened yet.
 async function prepareCommitSet({
-  context, commitSet, digests, journalOwned, ledgerDirectory, logPath, ownArtifacts, prefix, root, witness,
+  context, commitSet, digests, ledgerDirectory, logPath, ownArtifacts, prefix, root, witness,
 }) {
   let itemBytes;
   try {
@@ -314,7 +337,6 @@ async function prepareCommitSet({
   ));
   if (stray.length > 0) return { stage: 'prepare-commit-set', reason: 'tree-changed' };
 
-  if (!journalOwned) return null;
   let logBytes;
   try {
     logBytes = await readFile(path.join(path.resolve(ledgerDirectory), logPath));
@@ -388,12 +410,27 @@ async function verifyCommit(root, commit, parent, subject, gitPaths, digests, pr
   return { ok: true, reason: null };
 }
 
+function claimVerificationFailureDetails(verified) {
+  const error = verified.stdout.error;
+  const findings = verified.stdout.result?.findings ?? error?.details?.findings;
+  return {
+    ...(error?.code ? { claim_verify_code: error.code } : {}),
+    ...(error?.details?.reason ? { claim_verify_reason: error.details.reason } : {}),
+    // Why the claim store could not be read travels with the refusal: an
+    // operator told only that a store is unreadable cannot find the two
+    // worktrees answering to one identity.
+    ...(error?.details?.identity_diagnostic
+      ? { identity_diagnostic: error.details.identity_diagnostic }
+      : {}),
+    ...(findings ? { findings } : {}),
+  };
+}
+
 function reconciliationFailureReason(verified, commit, operationId, itemId) {
   if (verified.exit !== 0 || verified.stdout.ok !== true) {
-    return { reason: 'claim-verify-refused', findings: verified.stdout.result?.findings ?? [] };
+    return { reason: 'claim-verify-refused', ...claimVerificationFailureDetails(verified) };
   }
   const result = verified.stdout.result;
-  if (result.findings.length > 0) return { reason: 'claim-findings-present', findings: result.findings };
   if (result.ledger_validation.valid !== true) return { reason: 'ledger-invalid', findings: [] };
   if (operationId === null) return null;
   const row = result.publications.find((entry) => (
@@ -509,6 +546,13 @@ async function locateItem(ledgerDirectory, itemId) {
   };
 }
 
+// An auto-commit republishing the bytes HEAD already carries has no item change
+// to stage, so the item joins the commit set only when it actually differs.
+async function itemDiffersFromHead(root, prefix, itemPath, publishedRevision) {
+  const observed = await git(root, ['show', `HEAD:${prefix}${itemPath}`]);
+  return observed.code !== 0 || revisionFor(observed.stdout) !== publishedRevision;
+}
+
 // The one test-only seam in this module: it pauses between item publication and
 // staging so a fixture can prove that a late foreign change, a moved HEAD, or a
 // held index becomes a named failure instead of being absorbed into the commit.
@@ -633,7 +677,7 @@ function coreShape(command) {
     identityDetails: (identity) => ({ id: identity.id }),
     operationId: () => null,
     preflightFailed: (reason, details) => coreError('auto-commit-preflight-failed',
-      'Auto-commit refused before the mutation ran.', 'unchanged', 4, { reason, ...details }),
+      'Auto-commit refused before the mutation ran.', 'unchanged', 4, preflightDetails(reason, details)),
     publishedIdentity: (outcome) => (outcome.ok === true
       ? { id: outcome.item.id, revision: outcome.item.revision }
       : { id: outcome.error.details.id, revision: outcome.error.details.revision ?? null }),
@@ -660,6 +704,12 @@ function coreError(code, message, state, exit, details) {
   return { ok: false, exit, state, error: { code, message, details } };
 }
 
+// Both shapes report the same preflight refusal. Mutex contention is retryable
+// here; an underlying claim-store lock overrides this default in `details`.
+function preflightDetails(reason, details) {
+  return { reason, retryable: reason === 'mutex-held', ...details };
+}
+
 // Every envelope this shape builds keeps the claimed-publication domain and its
 // top-level operation_id, so a failure answers where the success would have.
 function publicationShape(operationId) {
@@ -697,7 +747,7 @@ function publicationShape(operationId) {
     }),
     operationId: (outcome) => outcome.stdout.operation_id ?? null,
     preflightFailed: (reason, details) => error('auto-commit-preflight-failed',
-      'Auto-commit refused before the mutation ran.', 'unchanged', 4, { reason, ...details }),
+      'Auto-commit refused before the mutation ran.', 'unchanged', 4, preflightDetails(reason, details)),
     publishedIdentity: (outcome) => ({
       id: outcome.stdout.result?.item_id ?? outcome.stdout.error?.details?.item_id,
       revision: outcome.stdout.result?.committed_revision ?? null,
@@ -808,7 +858,6 @@ export async function finalizeFromRecoveryToken({ ledgerDirectory, token }) {
 
 async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload, placement }) {
   const { root, prefix } = placement;
-  const journalOwned = payload.command !== 'create';
   const logPath = ledgerRelative(ledgerDirectory, claimReconcileLogPath(path.resolve(ledgerDirectory), namespace));
   const witness = payload.terminal_witness ?? null;
 
@@ -820,27 +869,43 @@ async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload,
   } catch {
     return finalizeRefused('item-not-readable', {});
   }
-  const commitSet = [derived.path, ...(journalOwned ? [logPath] : [])].sort(compareText);
-  const tokenPaths = payload.commit_set.map((entry) => entry.path);
   const subject = commitSubject(payload.command, derived.number, derived.id);
+  const digests = new Map(payload.commit_set.map((entry) => [entry.path, entry.sha256]));
+  digests.set(derived.path, payload.published_revision);
+  const head = await headOid(root);
+  if (head === null) return finalizeRefused('unborn-head', {});
+  const headUnchanged = head === payload.pre_commit_head;
+
+  const tokenPaths = payload.commit_set.map((entry) => entry.path);
+  let commitSet;
+  if (headUnchanged) {
+    const itemChanged = await itemDiffersFromHead(root, prefix, derived.path, payload.published_revision);
+    commitSet = [
+      ...(itemChanged ? [derived.path] : []),
+      logPath,
+    ].sort(compareText);
+  } else {
+    commitSet = [...tokenPaths].sort(compareText);
+  }
+  // A token is only ever issued by the auto-commit path above, where every
+  // command owns its reconciliation log, so recovery accepts the same two
+  // shapes for every command.
+  const allowedCommitSets = [[logPath], [derived.path, logPath]];
+  const tokenMatchesMutation = allowedCommitSets.some((allowed) => sameSet(tokenPaths, allowed));
   if (payload.item_path !== derived.path
-    || !sameSet(tokenPaths, commitSet)
+    || !tokenMatchesMutation
+    || (headUnchanged && !sameSet(tokenPaths, commitSet))
     || payload.message !== subject) {
     return finalizeRefused('commit-set-mismatch', {
       expected_path: derived.path,
       commit_paths: commitSet,
     });
   }
-
-  const digests = new Map(payload.commit_set.map((entry) => [entry.path, entry.sha256]));
-  digests.set(derived.path, payload.published_revision);
   const gitPaths = commitSet.map((entry) => `${prefix}${entry}`);
-  const head = await headOid(root);
-  if (head === null) return finalizeRefused('unborn-head', {});
 
   // The commit may already exist: a lost response is the same condition as a
   // failed commit, and both recover through this one command.
-  if (head !== payload.pre_commit_head) {
+  if (!headUnchanged) {
     const verification = await verifyCommit(
       root, head, payload.pre_commit_head, subject, gitPaths, digests, prefix, witness,
     );
@@ -851,7 +916,7 @@ async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload,
   }
 
   const refusal = await finalizePreconditions({
-    commitSet, derived, digests, gitPaths, journalOwned, ledgerDirectory, logPath, payload, prefix, root, witness,
+    commitSet, derived, digests, gitPaths, ledgerDirectory, logPath, payload, prefix, root, witness,
   });
   if (refusal) return finalizeRefused(refusal.reason, refusal.details);
 
@@ -893,7 +958,7 @@ async function runFinalize({ gitCommonDir, ledgerDirectory, namespace, payload,
 }
 
 async function finalizePreconditions({
-  commitSet, derived, digests, gitPaths, journalOwned, ledgerDirectory, logPath, payload, prefix, root, witness,
+  commitSet, derived, digests, gitPaths, ledgerDirectory, logPath, payload, prefix, root, witness,
 }) {
   let itemBytes;
   try {
@@ -914,7 +979,6 @@ async function finalizePreconditions({
   }
   const stray = observed.dirtyLedger.filter((entry) => !commitSet.includes(entry));
   if (stray.length > 0) return { reason: 'ledger-not-clean', details: { dirty_paths: bounded(stray) } };
-  if (!journalOwned) return null;
   let logBytes;
   try {
     logBytes = await readFile(path.join(path.resolve(ledgerDirectory), logPath));
@@ -951,8 +1015,7 @@ async function finalizeVerified({
         ...(operationId === null ? {} : { operation_id: operationId }),
         git_commit: commit,
         commit_paths: commitSet,
-        reason: reconciliation.reason,
-        findings: reconciliation.findings,
+        ...reconciliation,
       });
   }
   return {
@@ -978,7 +1041,7 @@ async function finalizeVerified({
 
 function commitFailedInWorkClaim(payload, commitSet, digests, failure) {
   return workClaimError('git-commit-failed',
-    'The item is published, but its Git commit was not established.', 'unchanged', 6, {
+    'The item is published, but its Git commit was not established.', 'committed', 6, {
       ledger_namespace: payload.ledger_namespace,
       item_id: payload.item_id,
       published_revision: payload.published_revision,

package/src/git-reconciliation.js

@@ -2,6 +2,7 @@ import { execFile, spawn } from 'node:child_process';
 import { realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import { listWorktrees } from './git-worktrees.js';
 import { recordCount, timePhase } from './instrumentation.js';
 import { revisionFor } from './mutation.js';
 
@@ -63,30 +64,84 @@ export async function readGitTreeFile(ledgerDirectory, treeish, relativePath) {
   return gitBuffer(root, ['show', `${treeish}:${gitPath}`]);
 }
 
-// Which local ref carries the revision the journal expects. A finding may name
-// only ownership it can prove from reachable history, so a revision no ref
-// contains stays unattributed rather than guessed from the item path.
+// Which active worktree carries the revision the journal expects. Reachability
+// alone proves nothing about ownership: a tag, a remote-tracking ref, or a
+// branch nobody has checked out names no worktree that could publish anything.
+// So the evidence is the worktree roster, this worktree first, and a revision
+// reachable only outside it stays unowned rather than attributed to a ref.
+//
+// Returns `{ kind, ref?, commit? }`, where `kind` is one of:
+//   `current`           this worktree's own history reaches the revision;
+//   `named-sibling`     a live sibling worktree on a branch reaches it;
+//   `reachable-unowned` Git reaches it, but no live named worktree does;
+//   `unreachable`       no reachable commit carries the expected bytes.
 export async function findRevisionOwner(ledgerDirectory, itemPath, expectedRevision) {
   const { root, relativeLedger } = await resolveWorktreeLedger(ledgerDirectory);
   const gitPath = toGitPath(path.join(relativeLedger, itemPath));
-  for (const commit of gitLines(await gitText(root, ['rev-list', '--all', '--', gitPath]))) {
-    let bytes;
-    try {
-      bytes = await gitBuffer(root, ['show', `${commit}:${gitPath}`]);
-    } catch {
-      // The path does not exist in this commit, so it cannot carry the revision.
-      continue;
+  const carrierIn = revisionCarrier(root, gitPath, expectedRevision);
+  const current = await carrierIn(await pathHistory(root, 'HEAD', gitPath));
+  if (current) return { kind: 'current', commit: current };
+  const live = (await listWorktrees(root)).filter((record) => (
+    !record.bare && !record.prunable && record.head !== null
+  ));
+  // One expected revision can sit in several live worktrees at once. Branch ref
+  // then path is the only ordering both stable across runs and independent of
+  // the order Git happened to register the worktrees in.
+  for (const record of live.filter((entry) => entry.branch !== null).sort(byBranchThenPath)) {
+    const commit = await carrierIn(await pathHistory(root, record.head, gitPath));
+    if (commit) return { kind: 'named-sibling', ref: record.branch, commit };
+  }
+  // A detached worktree is a real writer with no ref to wait on, so it proves
+  // reachability and nothing else. So does any remaining ref: a tag, a
+  // remote-tracking ref, or a branch no worktree has checked out.
+  for (const record of live.filter((entry) => entry.branch === null)) {
+    const commit = await carrierIn(await pathHistory(root, record.head, gitPath));
+    if (commit) return { kind: 'reachable-unowned', commit };
+  }
+  const reachable = await carrierIn(await pathHistory(root, '--all', gitPath));
+  return reachable ? { kind: 'reachable-unowned', commit: reachable } : { kind: 'unreachable' };
+}
+
+// The first commit of a history whose item bytes are the expected revision, or
+// null. Sibling histories overlap almost entirely and every answer costs a
+// `git show`, so one commit is read at most once per lookup.
+function revisionCarrier(root, gitPath, expectedRevision) {
+  const answered = new Map();
+  return async (commits) => {
+    for (const commit of commits) {
+      if (!answered.has(commit)) {
+        answered.set(commit, await carriesRevision(root, commit, gitPath, expectedRevision));
+      }
+      if (answered.get(commit)) return commit;
     }
-    if (revisionFor(bytes) !== expectedRevision) continue;
-    const [ownerRef] = gitLines(await gitText(root, [
-      'for-each-ref',
-      '--contains',
-      commit,
-      '--format=%(refname)',
-    ])).sort();
-    return ownerRef ? { owner_ref: ownerRef, owner_commit: commit } : { owner_unavailable: true };
+    return null;
+  };
+}
+
+async function carriesRevision(root, commit, gitPath, expectedRevision) {
+  try {
+    const bytes = await gitBuffer(root, ['show', `${commit}:${gitPath}`]);
+    return revisionFor(bytes) === expectedRevision;
+  } catch {
+    // The path does not exist in this commit, so it cannot carry the revision.
+    return false;
   }
-  return { owner_unavailable: true };
+}
+
+// The commits one revision range reaches that touch the item path, newest
+// first. An unborn `HEAD` names no commit, so a worktree Git cannot resolve
+// reaches nothing.
+async function pathHistory(root, revisionRange, gitPath) {
+  try {
+    return gitLines(await gitText(root, ['rev-list', revisionRange, '--', gitPath]));
+  } catch {
+    return [];
+  }
+}
+
+function byBranchThenPath(a, b) {
+  if (a.branch !== b.branch) return a.branch < b.branch ? -1 : 1;
+  return a.path < b.path ? -1 : 1;
 }
 
 async function gitText(cwd, argumentsList) {

package/src/git-worktrees.js

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+// Git answers `GIT_DIR` and its siblings before it answers `cwd`, so an
+// inherited value would report a repository the caller never named.
+const GIT_ENVIRONMENT = Object.fromEntries(
+  Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')),
+);
+
+// Every worktree of one repository owns a private Git directory: the common
+// directory itself for the main worktree, `<common>/worktrees/<name>` for a
+// linked one. Anything a single worktree must not share with its siblings
+// belongs there. Git resolves it; nothing here parses a `.git` file.
+export async function resolvePrivateGitDir(directory) {
+  const { stdout } = await execFileAsync('git', ['rev-parse', '--absolute-git-dir'], {
+    cwd: path.resolve(directory),
+    encoding: 'utf8',
+    env: GIT_ENVIRONMENT,
+    maxBuffer: 1024 * 1024,
+  });
+  return stdout.trim();
+}
+
+// The registered worktrees of one repository, as Git itself reports them.
+// `--porcelain -z` terminates every attribute with NUL and separates records
+// with one extra NUL, so a worktree path holding a newline still parses; the
+// newline-delimited spelling cannot promise that. Git emits `worktree <path>`
+// first, then `HEAD <oid>` and either `branch <ref>` or `detached`, plus the
+// bare, locked, and prunable markers where they apply. An attribute before the
+// first `worktree` line cannot exist, and one that does belongs to no record.
+export async function listWorktrees(directory) {
+  const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain', '-z'], {
+    cwd: path.resolve(directory),
+    encoding: 'utf8',
+    env: GIT_ENVIRONMENT,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  const worktrees = [];
+  let record = null;
+  for (const field of stdout.split('\0')) {
+    if (field === '') {
+      if (record) worktrees.push(record);
+      record = null;
+      continue;
+    }
+    const boundary = field.indexOf(' ');
+    const name = boundary === -1 ? field : field.slice(0, boundary);
+    const value = boundary === -1 ? '' : field.slice(boundary + 1);
+    if (name === 'worktree') {
+      record = {
+        path: path.normalize(value),
+        head: null,
+        branch: null,
+        detached: false,
+        bare: false,
+        locked: false,
+        prunable: false,
+      };
+      continue;
+    }
+    if (!record) continue;
+    if (name === 'HEAD') record.head = value;
+    else if (name === 'branch') record.branch = value;
+    else if (name === 'detached') record.detached = true;
+    else if (name === 'bare') record.bare = true;
+    else if (name === 'locked') record.locked = true;
+    else if (name === 'prunable') record.prunable = true;
+  }
+  if (record) worktrees.push(record);
+  return worktrees;
+}

package/src/instrumentation.js

@@ -16,6 +16,7 @@ const COUNTER_NAMES = [
   'item_lock_fsyncs',
   'item_lock_releases',
   'namespace_lock_acquisitions',
+  'worktree_identity_lock_acquisitions',
   'head_tree_entries',
   'head_blobs_read',
   'head_bytes_read',

package/src/launch.js

@@ -17,8 +17,8 @@ import { fileURLToPath } from 'node:url';
 
 // The engine floor the package declares. A host that resolves its own Node
 // executable rather than reusing `process.execPath` must check it, because a
-// Node 18 executable will fail somewhere inside the core rather than at launch.
-export const MINIMUM_NODE_MAJOR = 20;
+// Node 22 executable will fail somewhere inside the core rather than at launch.
+export const MINIMUM_NODE_MAJOR = 24;
 
 // The absolute path of the core script. It is resolved from this module's own
 // URL, so it is correct for a global install, a local install, a workspace