Feat: add qw warpspace locate

CHANGELOG.md

@@ -8,6 +8,9 @@
   `ContinuumEvidenceStatus` survives runtime-boundary artifact generation.
 - Added `qw warpspace lock`, `verify`, `sync`, and `doctor` for the first
   pinned-Git constellation workflow, plus a `jedit`/Echo preview manifest.
+- Added `qw warpspace locate` as the first TACHYON resolver surface for turning
+  runtime paths into typed `warp://` locators with runtime projection metadata
+  excluded from hash scope.
 - Made devcontainer runtime projection require explicit
   `[runtime.default].mount` and `[runtime.default.image]` declarations instead
   of silently defaulting runtime topology, and rejected comma-bearing mount

apps/warp/README.md

@@ -32,6 +32,7 @@ Prototype commands available here today:
   - `qw warpspace verify`
   - `qw warpspace sync`
   - `qw warpspace doctor`
+  - `qw warpspace locate`
 
 Current posture:
 
@@ -53,6 +54,9 @@ Current posture:
   `qw warpspace lock <manifest.toml>` writes a JSON lock, `verify` checks
   local checkouts, `sync` clones/fetches/checks out the locked commits, and
   `doctor` reports verification health
+- supports a first TACHYON locator flow:
+  `qw warpspace locate <path>` converts a runtime path projection into a typed
+  `warp://` locator scoped to repos declared in `warpspace.lock.json`
 - supports a first `qw install` cut for constellation-style
   `warpspace.toml` files: it refreshes `warpspace.lock.json`, syncs declared
   repo checkouts, writes `.devcontainer/devcontainer.json` for a
@@ -80,6 +84,7 @@ qw install
 qw warpspace lock docs/warpspaces/jedit-echo-dev.toml --lock /tmp/jedit-echo-dev.lock.json
 qw warpspace sync /tmp/jedit-echo-dev.lock.json --root ~/warpspaces/jedit-echo-dev
 qw warpspace verify /tmp/jedit-echo-dev.lock.json --root ~/warpspaces/jedit-echo-dev
+qw warpspace locate ../echo/src/lib.rs --lock warpspace.lock.json --root /warpspaces/jim --cwd /warpspaces/jim/jedit --json
 ```
 
 For repo-local development before packaging, the same CLI can be invoked with:

apps/warp/src/cli.mjs

@@ -1,4 +1,5 @@
 import { initWarp } from './init.mjs';
+import { locateWarpspacePath } from './locator.mjs';
 import {
   doctorWarpspace,
   installWarpspace,
@@ -293,6 +294,39 @@ async function runWarpspace(argv, { stdout, stderr }) {
     }
   }
 
+  if (command === 'locate') {
+    const usage = renderWarpspaceLocateUsage();
+    if (hasHelpFlag(rest)) {
+      stdout(usage);
+      return 0;
+    }
+    const wantsJson = rest.includes('--json');
+    try {
+      const { options, positionals } = parseWarpspaceLocateArgs(rest, usage);
+      if (positionals.length !== 1) {
+        throw new UsageError('Expected exactly one path to locate.', usage);
+      }
+      const result = await locateWarpspacePath({
+        lockPath: options.lock ?? 'warpspace.lock.json',
+        root: options.root ?? null,
+        cwd: options.cwd ?? null,
+        basis: options.basis ?? null,
+        inputPath: positionals[0]
+      });
+      if (options.json) {
+        stdout(JSON.stringify(result, null, 2) + '\n');
+      } else {
+        stdout(`${result.basisLocator ?? result.locator}\n`);
+      }
+      return 0;
+    } catch (error) {
+      if (wantsJson) {
+        return writeJsonCommandError(stdout, error, 'warp.warpspace.locate.error.v1', 'EWARP_LOCATE_FAILED');
+      }
+      return writeCommandError(stderr, error);
+    }
+  }
+
   stderr(`Unknown warpspace command: ${command}\n\n`);
   stderr(renderWarpspaceUsage());
   return 1;
@@ -329,12 +363,12 @@ function writeCommandError(stderr, error) {
   return 1;
 }
 
-function writeJsonCommandError(stdout, error, kind) {
+function writeJsonCommandError(stdout, error, kind, fallbackCode = 'EINSTALL') {
   stdout(JSON.stringify({
     kind,
     ok: false,
     error: {
-      code: error?.code ?? 'EINSTALL',
+      code: error?.code ?? fallbackCode,
       message: error?.message ?? String(error)
     }
   }, null, 2) + '\n');
@@ -473,6 +507,42 @@ function parseWarpspaceArgs(argv, usage, allowedFlags = new Set()) {
   return { options, positionals };
 }
 
+function parseWarpspaceLocateArgs(argv, usage) {
+  const options = {};
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+
+    switch (token) {
+      case '--lock':
+        options.lock = requireValue(argv, ++index, token, usage);
+        break;
+      case '--root':
+        options.root = requireValue(argv, ++index, token, usage);
+        break;
+      case '--cwd':
+        options.cwd = requireValue(argv, ++index, token, usage);
+        break;
+      case '--basis':
+        options.basis = requireValue(argv, ++index, token, usage);
+        break;
+      case '--json':
+        options.json = true;
+        break;
+      default:
+        throw new UsageError(`Unknown option: ${token}`, usage);
+    }
+  }
+
+  return { options, positionals };
+}
+
 function requireValue(argv, index, flag, usage) {
   const value = argv[index];
   if (value == null || value.startsWith('-')) {
@@ -526,6 +596,7 @@ function renderWarpspaceUsage() {
     '  qw warpspace verify <warpspace.lock.json> [--root <dir>] [--allow-dirty] [--json]',
     '  qw warpspace sync <warpspace.lock.json> --root <dir> [--json]',
     '  qw warpspace doctor <warpspace.lock.json> [--root <dir>] [--allow-dirty] [--json]',
+    '  qw warpspace locate <path> [--lock <path>] [--root <dir>] [--cwd <dir>] [--basis <ref>] [--json]',
     ''
   ].join('\n');
 }
@@ -546,6 +617,10 @@ function renderWarpspaceDoctorUsage() {
   return 'Usage: qw warpspace doctor <warpspace.lock.json> [--root <dir>] [--allow-dirty] [--json]\n';
 }
 
+function renderWarpspaceLocateUsage() {
+  return 'Usage: qw warpspace locate <path> [--lock <warpspace.lock.json>] [--root <dir>] [--cwd <dir>] [--basis <ref>] [--json]\n';
+}
+
 function renderWarpspaceIssues(result) {
   const lines = [
     `WARPspace verification failed: ${result.root}`,