@aiwg/cli 2026.8.0 → 2026.8.2

package/dist/src/sessions/output-registration.js

@@ -0,0 +1,338 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { SessionContractError, sha256 } from './contracts.js';
+const DigestSchema = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const ReferenceSchema = z.string().min(1).max(512).refine(value => !/[\r\n\0]/.test(value), 'references must be single-line inert locators');
+export const OutputSourceReferenceSchema = z.object({
+    kind: z.enum(['file', 'url', 'note', 'session', 'artifact', 'context-pack']),
+    ref: ReferenceSchema,
+    digest: DigestSchema.nullable().default(null),
+    span: z.object({
+        start: z.number().int().nonnegative(),
+        end: z.number().int().positive(),
+        quoteDigest: DigestSchema,
+    }).strict().nullable().default(null),
+}).strict().superRefine((value, context) => {
+    if (value.span && value.span.end <= value.span.start) {
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'source span end must exceed start' });
+    }
+});
+export const OutputRegistrationRequestSchema = z.object({
+    outputPath: z.string().min(1),
+    mediaType: z.string().min(1).max(128),
+    contextPack: z.object({
+        id: ReferenceSchema,
+        digest: DigestSchema,
+        sources: z.array(OutputSourceReferenceSchema).min(1).max(256),
+    }).strict(),
+    supersedes: z.array(ReferenceSchema).max(128).default([]),
+    conflictsWith: z.array(ReferenceSchema).max(128).default([]),
+}).strict();
+/**
+ * Minimal incremental index sink. Each registration is independently atomic,
+ * discoverable, and replay-safe; corpus-wide index builders can consume these
+ * bounded records without rescanning output bodies.
+ */
+export class FilesystemDerivedOutputIndex {
+    root;
+    constructor(projectRoot) {
+        this.root = resolve(projectRoot, '.aiwg/memory/output-registration/index');
+        assertStorageRootInsideProject(projectRoot, this.root);
+    }
+    register(registration) {
+        if (!/^sha256:[0-9a-f]{64}$/.test(registration.registrationId)) {
+            throw new Error('invalid output registration identity');
+        }
+        const filePath = resolve(this.root, `${registration.registrationId.replace(':', '_')}.json`);
+        const existing = readJsonIfPresent(filePath);
+        if (existing) {
+            if (JSON.stringify(existing) !== JSON.stringify(registration)) {
+                throw new SessionContractError('IMPORT_CONFLICT', 'derived output index identity already has different content');
+            }
+            return;
+        }
+        writeJsonAtomic(filePath, registration);
+    }
+    registrations() {
+        if (!existsSync(this.root))
+            return [];
+        return readdirSync(this.root)
+            .filter(name => /^sha256_[0-9a-f]{64}\.json$/.test(name))
+            .sort()
+            .map(name => JSON.parse(readFileSync(resolve(this.root, name), 'utf8')));
+    }
+}
+function canonicalReference(value) {
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            parsed.username = '';
+            parsed.password = '';
+            parsed.search = '';
+            parsed.hash = '';
+            return parsed.toString();
+        }
+    }
+    catch {
+        // Non-URL references are opaque inert identifiers.
+    }
+    return value;
+}
+function assertStorageRootInsideProject(projectRoot, storageRoot) {
+    const root = realpathSync(projectRoot);
+    const candidate = resolve(projectRoot, storageRoot);
+    if (candidate !== resolve(projectRoot) && !candidate.startsWith(`${resolve(projectRoot)}${sep}`)) {
+        throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'memory storage must be inside the project');
+    }
+    let ancestor = candidate;
+    while (!existsSync(ancestor)) {
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        ancestor = parent;
+    }
+    const actualAncestor = realpathSync(ancestor);
+    if (actualAncestor !== root && !actualAncestor.startsWith(`${root}${sep}`)) {
+        throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'memory storage cannot traverse a link outside the project');
+    }
+}
+function assertNoSecretMaterial(value, field) {
+    const secretAssignment = /(?:^|[?&;:\s])(?:api[_-]?key|access[_-]?token|token|secret|password|passwd|authorization)\s*[:=]\s*[^\s&;]+/i;
+    const privateKey = /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/;
+    const providerToken = /(?:^|[^a-z0-9])(?:ghp|github_pat|sk|xox[baprs])_[a-z0-9_-]{16,}/i;
+    if (secretAssignment.test(value) || privateKey.test(value) || providerToken.test(value)) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `${field} appears to contain secret material; store only a non-secret locator`);
+    }
+}
+function canonicalRequest(request) {
+    const canonical = {
+        ...request,
+        contextPack: {
+            ...request.contextPack,
+            id: canonicalReference(request.contextPack.id),
+            sources: request.contextPack.sources.map(source => ({
+                ...source,
+                ref: canonicalReference(source.ref),
+            })),
+        },
+        supersedes: [...new Set(request.supersedes.map(canonicalReference))].sort(),
+        conflictsWith: [...new Set(request.conflictsWith.map(canonicalReference))].sort(),
+    };
+    assertNoSecretMaterial(canonical.contextPack.id, 'context-pack identity');
+    for (const source of canonical.contextPack.sources) {
+        assertNoSecretMaterial(source.ref, 'source reference');
+    }
+    for (const value of [...canonical.supersedes, ...canonical.conflictsWith]) {
+        assertNoSecretMaterial(value, 'lifecycle reference');
+    }
+    return canonical;
+}
+function resolveImmutableOutput(projectRoot, requestedPath) {
+    if (requestedPath.includes('\0')) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'output path contains a null byte');
+    }
+    const pathSegments = requestedPath.toLocaleLowerCase().split(/[\\/]+/);
+    if (pathSegments.some(segment => segment === '.env'
+        || segment === '.ssh'
+        || /^(?:credentials?|secrets?|tokens?)(?:\.|$)/.test(segment))) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'sensitive credential/secret paths cannot be registered as ordinary outputs');
+    }
+    const root = realpathSync(projectRoot);
+    const candidate = realpathSync(resolve(root, requestedPath));
+    if (candidate !== root && !candidate.startsWith(`${root}${sep}`)) {
+        throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'registered output must resolve inside the project');
+    }
+    return { absolute: candidate, locator: relative(root, candidate).split(sep).join('/') };
+}
+function registrationFor(projectRoot, raw) {
+    const request = canonicalRequest(OutputRegistrationRequestSchema.parse(raw));
+    const output = resolveImmutableOutput(projectRoot, request.outputPath);
+    const content = readFileSync(output.absolute);
+    const digest = `sha256:${createHash('sha256').update(content).digest('hex')}`;
+    const identity = {
+        output: { locator: output.locator, mediaType: request.mediaType, digest, byteLength: content.length },
+        contextPack: request.contextPack,
+        supersedes: request.supersedes,
+        conflictsWith: request.conflictsWith,
+    };
+    return {
+        schemaVersion: 'aiwg.output-registration.v1',
+        registrationId: sha256(JSON.stringify(identity)),
+        ...identity,
+    };
+}
+export class FilesystemOutputRegistrationStore {
+    root;
+    outboxRoot;
+    receiptRoot;
+    constructor(projectRoot) {
+        this.root = resolve(projectRoot, '.aiwg/memory/output-registration');
+        assertStorageRootInsideProject(projectRoot, this.root);
+        this.outboxRoot = resolve(this.root, 'outbox');
+        this.receiptRoot = resolve(this.root, 'receipts');
+    }
+    getReceipt(registrationId) {
+        return readJsonIfPresent(this.receiptPath(registrationId));
+    }
+    begin(operationId, registration) {
+        const existing = readJsonIfPresent(this.outboxPath(registration.registrationId));
+        if (existing)
+            return existing;
+        const record = {
+            schemaVersion: 'aiwg.output-registration-outbox.v1',
+            operationId,
+            registration,
+            state: 'pending',
+            attempts: 0,
+            lastError: null,
+            updatedAt: new Date().toISOString(),
+        };
+        writeJsonAtomic(this.outboxPath(registration.registrationId), record);
+        return record;
+    }
+    fail(registrationId, message) {
+        const path = this.outboxPath(registrationId);
+        const record = readJsonIfPresent(path);
+        if (!record)
+            throw new Error(`missing output-registration outbox record: ${registrationId}`);
+        const failed = {
+            ...record,
+            attempts: record.attempts + 1,
+            lastError: message.slice(0, 512),
+            updatedAt: new Date().toISOString(),
+        };
+        writeJsonAtomic(path, failed);
+        return failed;
+    }
+    complete(operationId, registration) {
+        const existing = this.getReceipt(registration.registrationId);
+        if (existing) {
+            unlinkIfPresent(this.outboxPath(registration.registrationId));
+            return { ...existing, duplicate: true };
+        }
+        const receipt = {
+            schemaVersion: 'aiwg.output-registration-receipt.v1',
+            receiptId: sha256(`${operationId}\0${registration.registrationId}`),
+            registrationId: registration.registrationId,
+            operationId,
+            outputLocator: registration.output.locator,
+            outputDigest: registration.output.digest,
+            contextPackId: registration.contextPack.id,
+            contextPackDigest: registration.contextPack.digest,
+            sourceRefs: registration.contextPack.sources.map(source => source.ref),
+            registeredAt: new Date().toISOString(),
+            duplicate: false,
+        };
+        writeJsonAtomic(this.receiptPath(registration.registrationId), receipt);
+        unlinkIfPresent(this.outboxPath(registration.registrationId));
+        return receipt;
+    }
+    pending() {
+        if (!existsSync(this.outboxRoot))
+            return [];
+        return readdirSync(this.outboxRoot)
+            .filter(name => /^sha256_[0-9a-f]{64}\.json$/.test(name))
+            .sort()
+            .map(name => JSON.parse(readFileSync(resolve(this.outboxRoot, name), 'utf8')));
+    }
+    safeName(registrationId) {
+        if (!/^sha256:[0-9a-f]{64}$/.test(registrationId)) {
+            throw new Error('invalid output registration identity');
+        }
+        return `${registrationId.replace(':', '_')}.json`;
+    }
+    outboxPath(registrationId) {
+        return resolve(this.outboxRoot, this.safeName(registrationId));
+    }
+    receiptPath(registrationId) {
+        return resolve(this.receiptRoot, this.safeName(registrationId));
+    }
+}
+export class OutputRegistrationCoordinator {
+    store;
+    index;
+    projectRoot;
+    constructor(projectRoot, store, index) {
+        this.store = store;
+        this.index = index;
+        this.projectRoot = resolve(projectRoot);
+    }
+    preview(request) {
+        const registration = registrationFor(this.projectRoot, request);
+        const operationId = sha256(JSON.stringify({
+            registrationId: registration.registrationId,
+            outputDigest: registration.output.digest,
+            contextPackDigest: registration.contextPack.digest,
+        }));
+        return {
+            ...registration,
+            operationId,
+            duplicate: Boolean(this.store.getReceipt(registration.registrationId)),
+            confirmationRequired: true,
+        };
+    }
+    async register(input) {
+        const preview = this.preview(input.request);
+        if (preview.operationId !== input.operationId) {
+            throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'output registration requires confirmation of the exact current preview');
+        }
+        const existing = this.store.getReceipt(preview.registrationId);
+        if (existing)
+            return { ...existing, duplicate: true };
+        const registration = registrationFor(this.projectRoot, input.request);
+        if (registration.registrationId !== preview.registrationId
+            || registration.output.digest !== preview.output.digest) {
+            throw new SessionContractError('IMPORT_CONFLICT', 'output changed after registration preview');
+        }
+        this.store.begin(input.operationId, registration);
+        try {
+            await this.index.register(registration);
+        }
+        catch (error) {
+            this.store.fail(registration.registrationId, error instanceof Error ? error.message : String(error));
+            throw error;
+        }
+        return this.store.complete(input.operationId, registration);
+    }
+    async replayPending() {
+        const receipts = [];
+        for (const record of this.store.pending()) {
+            try {
+                await this.index.register(record.registration);
+                receipts.push(this.store.complete(record.operationId, record.registration));
+            }
+            catch (error) {
+                this.store.fail(record.registration.registrationId, error instanceof Error ? error.message : String(error));
+            }
+        }
+        return receipts;
+    }
+}
+function readJsonIfPresent(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function writeJsonAtomic(filePath, value) {
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(temporary, filePath);
+}
+function unlinkIfPresent(filePath) {
+    try {
+        unlinkSync(filePath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+//# sourceMappingURL=output-registration.js.map

package/dist/src/sessions/promotion.js

@@ -12,7 +12,7 @@ export class MemoryPromotionGateway {
             throw new SessionContractError('MALFORMED_SOURCE', 'candidate version does not exist');
         }
         const existing = this.store.getPromotionReceipt(input.candidateId, input.version, input.destination.consumer);
-        if (candidate.reviewState !== 'accepted' && !(candidate.reviewState === 'promoted' && existing)) {
+        if (candidate.reviewState !== 'accepted' && candidate.reviewState !== 'promoted') {
             throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'promotion requires an accepted exact candidate version');
         }
         const security = candidateSecurity(candidate);
@@ -165,7 +165,7 @@ export class FilesystemPromotionDispositionCoordinator {
             if (!decision) {
                 throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'every promoted artifact requires an explicit disposition');
             }
-            this.authorizedPath(dependent.destinationRef);
+            this.authorizedDispositionRef(dependent.destinationRef);
             return {
                 dependentId: dependent.dependentId,
                 destinationRef: dependent.destinationRef,
@@ -194,6 +194,12 @@ export class FilesystemPromotionDispositionCoordinator {
         for (const effect of journal.effects) {
             if (effect.outcome !== 'pending')
                 continue;
+            const lineMemory = this.lineMemoryRef(effect.destinationRef);
+            if (lineMemory) {
+                effect.outcome = this.applyLineMemoryDisposition(lineMemory.metadataPath, lineMemory.handle, purge.operationId, effect);
+                this.writeJournal(journalPath, journal);
+                continue;
+            }
             const target = this.authorizedPath(effect.destinationRef);
             const marker = dispositionMarker(purge.operationId, effect);
             if (effect.action === 'delete') {
@@ -252,6 +258,65 @@ export class FilesystemPromotionDispositionCoordinator {
         }
         return target;
     }
+    authorizedDispositionRef(destinationRef) {
+        if (this.lineMemoryRef(destinationRef))
+            return;
+        this.authorizedPath(destinationRef);
+    }
+    lineMemoryRef(destinationRef) {
+        const separator = destinationRef.lastIndexOf('#');
+        if (separator < 1)
+            return null;
+        const metadataRef = destinationRef.slice(0, separator);
+        const handle = destinationRef.slice(separator + 1);
+        if (!/^lm_[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(handle)) {
+            return null;
+        }
+        return { metadataPath: this.authorizedPath(metadataRef), handle };
+    }
+    applyLineMemoryDisposition(metadataPath, handle, operationId, effect) {
+        if (!existsSync(metadataPath))
+            return 'already-applied';
+        const metadata = JSON.parse(readFileSync(metadataPath, 'utf8'));
+        if (metadata.schemaVersion !== 'aiwg.line-memory.v1' || !metadata.entries) {
+            throw new SessionContractError('IMPORT_CONFLICT', 'line-memory metadata schema is invalid');
+        }
+        const entry = metadata.entries[handle];
+        if (!entry)
+            return 'already-applied';
+        const priorOperation = entry.disposition?.operationId;
+        if (priorOperation === operationId)
+            return 'already-applied';
+        const memoryRef = metadata.store?.memoryPath ?? '.aiwg/memory/line-memory.txt';
+        const memoryPath = this.authorizedPath(memoryRef);
+        const lines = existsSync(memoryPath)
+            ? readFileSync(memoryPath, 'utf8').split(/\r?\n/).filter(Boolean)
+            : [];
+        const removesActiveFact = ['delete', 'revoke', 'supersede'].includes(effect.action);
+        const nextLines = removesActiveFact
+            ? removeFirstExact(lines, entry.value)
+            : lines;
+        if (effect.action === 'delete')
+            delete metadata.entries[handle];
+        else {
+            entry.status = effect.action === 'revoke' ? 'revoked'
+                : effect.action === 'supersede' ? 'superseded'
+                    : effect.action === 'origin_unavailable' ? 'origin-unavailable'
+                        : 'active';
+            entry.updatedAt = new Date().toISOString();
+            entry.disposition = {
+                operationId,
+                action: effect.action,
+                effect: effect.effect,
+                originAvailable: effect.action !== 'origin_unavailable',
+            };
+        }
+        if (removesActiveFact) {
+            this.atomicWrite(memoryPath, nextLines.length ? `${nextLines.join('\n')}\n` : '');
+        }
+        this.atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+        return 'applied';
+    }
     journalPath(operationId) {
         return resolve(this.journalRoot, `${operationId.replace(':', '-')}.json`);
     }
@@ -290,6 +355,12 @@ function requireJournalFiles(root) {
         .sort()
         .map((name) => resolve(root, name));
 }
+function removeFirstExact(lines, value) {
+    const index = lines.indexOf(value);
+    return index < 0
+        ? [...lines]
+        : lines.filter((_, candidate) => candidate !== index);
+}
 export function resolveMemoryConsumerManifest(projectRoot, consumer) {
     const safeConsumer = assertConsumerId(consumer);
     const candidates = [

package/dist/src/sessions/repository.js

@@ -1219,7 +1219,8 @@ export class SessionRepository {
             if (existing)
                 return { ...existing, duplicate: true };
             const candidate = this.getCandidate(receipt.candidateId, receipt.candidateVersion);
-            if (!candidate || candidate.reviewState !== 'accepted') {
+            if (!candidate
+                || (candidate.reviewState !== 'accepted' && candidate.reviewState !== 'promoted')) {
                 throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'promotion requires an accepted exact candidate version');
             }
             const evidenceIds = [...new Set(candidate.evidence.map((item) => item.eventId))].sort();

package/dist/src/update/notifier.mjs

@@ -157,6 +157,16 @@ function readCurrentVersion(packageRoot) {
   }
 }
 
+/**
+ * Return true when a cached check belongs to the package currently handling
+ * the command. A global launcher can dispatch into a newer development
+ * checkout, so cache age alone is not sufficient.
+ */
+export function cacheMatchesPackage(cache, packageRoot) {
+  const currentVersion = readCurrentVersion(packageRoot);
+  return !!(currentVersion && cache?.current === currentVersion);
+}
+
 /**
  * Run the actual update check and write the cache file. Invoked by the
  * spawned background child via `node src/update/notifier.mjs --check`.
@@ -183,7 +193,7 @@ export function scheduleBackgroundCheck(packageRoot) {
   if (isDisabled()) return;
 
   const cache = readCache();
-  if (cache?.lastCheckAt) {
+  if (cacheMatchesPackage(cache, packageRoot) && cache?.lastCheckAt) {
     const age = Date.now() - new Date(cache.lastCheckAt).getTime();
     if (age < CHECK_INTERVAL_MS) return; // recent enough — skip
   }
@@ -213,9 +223,10 @@ export function scheduleBackgroundCheck(packageRoot) {
  * is interactive, print a single-line notice to stderr. Never prompts.
  * Safe to call unconditionally from `bin/aiwg.mjs` — gated by isDisabled().
  */
-export function maybePrintNotice() {
+export function maybePrintNotice(packageRoot) {
   if (isDisabled()) return;
   const cache = readCache();
+  if (!cacheMatchesPackage(cache, packageRoot)) return;
   if (!cache?.hasUpdate || !cache.current || !cache.latest) return;
   // One-line, non-intrusive. Users who want to update run `aiwg update`.
   const msg = `aiwg: update available ${cache.current} → ${cache.latest} (run: aiwg update)`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.0",
+  "version": "2026.8.2",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",
@@ -25,12 +25,19 @@
   "files": [
     "LICENSE",
     "bin/",
+    "agentic/code/providers/",
     "dist/src/",
     "!dist/**/*.d.ts",
     "!dist/**/*.map",
     "dist/src/api/index.d.ts",
     "dist/src/resources/index.d.ts",
     "dist/src/resources/web-release.d.ts",
+    "tools/_resolve-impl.mjs",
+    "tools/agents/deploy-agents.mjs",
+    "tools/agents/providers/",
+    "tools/commands/deploy-prompts-codex.mjs",
+    "tools/plugin/package-plugins.mjs",
+    "tools/skills/deploy-skills-codex.mjs",
     "README.md"
   ],
   "repository": {

package/tools/_resolve-impl.mjs

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+function findPackageRoot(callerUrl) {
+  let dir = dirname(fileURLToPath(callerUrl));
+  for (let i = 0; i < 12; i += 1) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (pkg.name === 'aiwg' || pkg.name === '@aiwg/cli') return dir;
+      } catch {
+        // Keep walking.
+      }
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(`Could not locate AIWG package root from ${callerUrl}`);
+}
+
+function candidatesFor(root, relativeFromSrc, base) {
+  const primary = resolve(root, base, relativeFromSrc);
+  const candidates = [primary];
+
+  if (base === 'src' && extname(primary) === '.js') {
+    candidates.push(primary.slice(0, -3) + '.ts');
+  }
+
+  return candidates;
+}
+
+function resolveCandidate(root, relativeFromSrc, base) {
+  for (const candidate of candidatesFor(root, relativeFromSrc, base)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Resolve a module that may live under compiled dist/src/ or source src/.
+ *
+ * Prefers dist/src/ when present. Set AIWG_RESOLVE_IMPL_FROM=dist or src to
+ * force a side during CI/package-layout checks.
+ */
+export function resolveImpl(callerUrl, relativeFromSrc) {
+  const root = findPackageRoot(callerUrl);
+  const forced = process.env.AIWG_RESOLVE_IMPL_FROM;
+
+  const order = forced === 'src'
+    ? ['src']
+    : forced === 'dist'
+      ? ['dist/src']
+      : ['dist/src', 'src'];
+
+  for (const base of order) {
+    const candidate = resolveCandidate(root, relativeFromSrc, base);
+    if (candidate) return candidate;
+  }
+
+  const attempted = order
+    .flatMap((base) => candidatesFor(root, relativeFromSrc, base))
+    .join(', ');
+  throw new Error(`Could not resolve ${relativeFromSrc}; attempted: ${attempted}`);
+}
+
+export async function importImpl(callerUrl, relativeFromSrc) {
+  const modulePath = resolveImpl(callerUrl, relativeFromSrc);
+  return import(pathToFileURL(modulePath).href);
+}