gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/move/facts-mapper.js

@@ -0,0 +1,534 @@
+/**
+ * Thin facts → graph mapper.
+ *
+ * Consumes the move-flow `facts` query response (the compiler's full-fidelity,
+ * per-module structured facts) and produces standard GraphNode / GraphRelationship
+ * objects. This is the heart of the compiler-first Move ingestion: there is
+ * **no raw-source scanning** — every fact (visibility, entry/view, attributes,
+ * acquires, resource reads/writes, enum variants, friends, locations) comes
+ * straight from move-flow.
+ */
+import { moveModuleNodeId, moveFunctionNodeId, moveStructNodeId, moveEnumNodeId, moveConstNodeId, moveEnumVariantNodeId, moveFieldNodeId, moveLocalName, moveRelId, parseMoveLambdaHostName, parseMoveModuleQualifiedName, } from './symbol-id.js';
+import { ERROR_CODE_PATTERN, MOVE_ABILITY, MOVE_ATTR, MOVE_EDGE_REASON, MOVE_LANGUAGE, moveRepoRelativePath, } from './constants.js';
+import { extractTypeNames } from './type-parser.js';
+import { toZeroBasedLine } from '../ingestion/utils/line-base.js';
+const spanLine = (span, idx) => span ? toZeroBasedLine(span[idx]) : undefined;
+/** Strip generic type arguments: `CoinStore<CoinType>` → `CoinStore`. */
+function stripTypeArgs(typeName) {
+    const idx = typeName.indexOf('<');
+    return (idx === -1 ? typeName : typeName.slice(0, idx)).trim();
+}
+/** Defensive: move-flow omits optional array fields for some symbols. */
+function arr(value) {
+    return Array.isArray(value) ? value : [];
+}
+function typeParamsJson(typeParams) {
+    const list = arr(typeParams).map((tp) => ({
+        name: tp.name,
+        constraints: arr(tp.abilities),
+        isPhantom: tp.isPhantom,
+    }));
+    return JSON.stringify(list);
+}
+function attributeNames(attributes) {
+    return arr(attributes).map((a) => a.name);
+}
+/** Full attribute payload (nested `args` / assignment `value`s) as JSON;
+ *  undefined (not `"[]"`) when the symbol carries no attributes. */
+function attributesJson(attributes) {
+    const list = arr(attributes);
+    return list.length > 0 ? JSON.stringify(list) : undefined;
+}
+/** `#[resource_group_member(group = <qualified struct>)]` -> the group struct ref. */
+function resourceGroupOf(attributes) {
+    for (const a of arr(attributes)) {
+        if (a.name !== MOVE_ATTR.RESOURCE_GROUP_MEMBER)
+            continue;
+        for (const groupArg of arr(a.args)) {
+            if (groupArg.name === 'group' && typeof groupArg.value === 'string') {
+                return groupArg.value;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Scalar projection of `returnTypes` for the lbug `returnType` STRING column:
+ * `[]` -> undefined, single -> the element, tuple -> `'(a, b)'`.
+ */
+function returnTypeProjection(returnTypes) {
+    if (returnTypes.length === 0)
+        return undefined;
+    return returnTypes.length === 1 ? returnTypes[0] : `(${returnTypes.join(', ')})`;
+}
+/**
+ * Boundary shape sentinel: reject the legacy scalar `returnType` shape. The
+ * mapper requires `returnTypes: string[]`; silently mapping the old scalar
+ * `returnType` would drop every return-type fact, so hard-fail with an
+ * operator-actionable upgrade message. The shape is uniform across a payload,
+ * so the first function encountered decides for all of them.
+ */
+function assertFactsShape(facts) {
+    for (const mod of Object.values(facts)) {
+        for (const fn of arr(mod.functions)) {
+            if (!Array.isArray(fn.returnTypes) && 'returnType' in fn) {
+                throw Object.assign(new Error('move-flow returned the legacy scalar `returnType` facts shape - upgrade ' +
+                    'move-flow to a build that emits `returnTypes: string[]` (>=2.0.0).'), { userActionable: true });
+            }
+            return;
+        }
+    }
+}
+/**
+ * Map a full `facts` response (covering every module in a package) to graph
+ * nodes + edges. `packageRoot` is used only as a location fallback when the
+ * compiler omits a per-symbol file (it never does today, but the field is
+ * optional in the schema). When `repoPath` is given, absolute file paths from
+ * the compiler are made repo-relative so node IDs align with `File:` nodes.
+ */
+export function mapFactsToGraph(facts, packageRoot, repoPath) {
+    assertFactsShape(facts);
+    const nodes = [];
+    const edges = [];
+    const moduleFileMap = new Map();
+    const functionNodeMap = new Map();
+    const structNodeMap = new Map();
+    const edge = (sourceId, targetId, type, confidence, reason) => {
+        edges.push({
+            id: moveRelId(sourceId, type, targetId, reason),
+            sourceId,
+            targetId,
+            type,
+            confidence,
+            reason,
+        });
+    };
+    // Deferred work that needs the full struct/module index (pass B).
+    const pendingResource = [];
+    const pendingFriends = [];
+    const pendingTypeRef = [];
+    const pendingLambdaHosts = [];
+    // ── Pass A: nodes (modules, functions, types, constants) ─────────────────
+    for (const [moduleQualified, mod] of Object.entries(facts)) {
+        const moduleFileAbs = mod.file ?? packageRoot;
+        const file = moveRepoRelativePath(moduleFileAbs, repoPath);
+        const { address, moduleName } = parseMoveModuleQualifiedName(moduleQualified);
+        moduleFileMap.set(moduleQualified, file);
+        const moduleNodeId = moveModuleNodeId(moduleQualified, file);
+        nodes.push({
+            id: moduleNodeId,
+            label: 'Module',
+            properties: {
+                name: moduleName,
+                filePath: file,
+                language: MOVE_LANGUAGE,
+                qualifiedName: moduleQualified,
+                moduleQualifiedName: moduleQualified,
+                moduleAddress: address,
+                startLine: spanLine(mod.span, 0),
+                endLine: spanLine(mod.span, 1),
+                attributes: attributeNames(mod.attributes),
+                attributesJson: attributesJson(mod.attributes),
+                locationFidelity: mod.file ? 'precise' : 'package',
+            },
+        });
+        for (const friend of arr(mod.friends)) {
+            pendingFriends.push({ moduleNodeId, friend: friend.module });
+        }
+        // Functions
+        for (const fn of arr(mod.functions)) {
+            const fnQualified = `${moduleQualified}::${fn.name}`;
+            const fnFile = moveRepoRelativePath(fn.file ?? moduleFileAbs, repoPath);
+            const fnNodeId = moveFunctionNodeId(fnQualified, fnFile);
+            functionNodeMap.set(fnQualified, fnNodeId);
+            const attrs = attributeNames(fn.attributes);
+            const seenTypeRefs = new Set();
+            // Skip the function's own type parameters (e.g. `CoinType`): they are not
+            // nominal types and would create spurious USES_TYPE edges.
+            const fnTypeParamNames = new Set(arr(fn.typeParams).map((tp) => tp.name));
+            const addSignatureTypes = (typeExpr, reason) => {
+                if (!typeExpr)
+                    return;
+                for (const typeName of extractTypeNames(typeExpr)) {
+                    if (fnTypeParamNames.has(typeName))
+                        continue;
+                    const key = `${reason}\0${typeName}`;
+                    if (seenTypeRefs.has(key))
+                        continue;
+                    seenTypeRefs.add(key);
+                    pendingTypeRef.push({
+                        sourceNodeId: fnNodeId,
+                        moduleQualified,
+                        target: typeName,
+                        reason,
+                    });
+                }
+            };
+            for (const p of arr(fn.params)) {
+                addSignatureTypes(p.type, MOVE_EDGE_REASON.fnParamType);
+            }
+            for (const rt of arr(fn.returnTypes)) {
+                addSignatureTypes(rt, MOVE_EDGE_REASON.fnReturnType);
+            }
+            const fnProps = {
+                name: fn.name,
+                filePath: fnFile,
+                language: MOVE_LANGUAGE,
+                qualifiedName: fnQualified,
+                moduleQualifiedName: moduleQualified,
+                startLine: spanLine(fn.span, 0),
+                endLine: spanLine(fn.span, 1),
+                visibility: fn.visibility === 'internal' ? 'private' : fn.visibility,
+                visibilityModifier: fn.visibility,
+                isEntry: fn.isEntry,
+                isView: fn.isView,
+                isInline: fn.isInline,
+                isNative: fn.isNative,
+                attributes: attrs,
+                attributesJson: attributesJson(fn.attributes),
+                typeParamsJson: typeParamsJson(fn.typeParams),
+                acquires: arr(fn.acquiresInferred),
+                usedTypes: [],
+                returnType: returnTypeProjection(arr(fn.returnTypes)),
+                parameterCount: arr(fn.params).length,
+                locationFidelity: fn.file ? 'precise' : 'package',
+            };
+            // Lambda → host link queued for Pass 2 (host fn node may not yet exist
+            // when this lambda is mapped). The canonical Cypher path for "is this a
+            // lambda?" is the inbound CALLS edge with reason 'move-lambda-of-host';
+            // we do not project an `isLambda` boolean property because the lbug
+            // Function table does not carry it. move-flow reports the host explicitly
+            // via `definedIn` (resolved through nested closures); the
+            // `__lambda__N__<host>` name parse remains as fallback.
+            const lambdaHostLocal = (fn.isLambdaLifted ? fn.definedIn : undefined) ?? parseMoveLambdaHostName(fn.name);
+            if (lambdaHostLocal) {
+                pendingLambdaHosts.push({
+                    lambdaFnNodeId: fnNodeId,
+                    hostQualified: `${moduleQualified}::${lambdaHostLocal}`,
+                });
+            }
+            nodes.push({
+                id: fnNodeId,
+                label: 'Function',
+                properties: fnProps,
+            });
+            edge(moduleNodeId, fnNodeId, 'DEFINES', 1.0, MOVE_EDGE_REASON.definesFunction);
+            for (const r of arr(fn.resourceAccess?.reads)) {
+                pendingResource.push({
+                    fnNodeId,
+                    moduleQualified,
+                    type: 'READS_RESOURCE',
+                    target: stripTypeArgs(r),
+                    reason: MOVE_EDGE_REASON.readsResource,
+                });
+            }
+            for (const w of arr(fn.resourceAccess?.writes)) {
+                pendingResource.push({
+                    fnNodeId,
+                    moduleQualified,
+                    type: 'WRITES_RESOURCE',
+                    target: stripTypeArgs(w),
+                    reason: MOVE_EDGE_REASON.writesResource,
+                });
+            }
+            for (const a of arr(fn.acquiresInferred)) {
+                pendingResource.push({
+                    fnNodeId,
+                    moduleQualified,
+                    type: 'ACQUIRES',
+                    target: a,
+                    reason: MOVE_EDGE_REASON.acquires,
+                });
+            }
+        }
+        // Types (structs + enums)
+        for (const ty of arr(mod.structs)) {
+            const tyQualified = `${moduleQualified}::${ty.name}`;
+            const tyFile = moveRepoRelativePath(ty.file ?? moduleFileAbs, repoPath);
+            const attrs = attributeNames(ty.attributes);
+            if (ty.kind === 'struct') {
+                const structNodeId = moveStructNodeId(tyQualified, tyFile);
+                structNodeMap.set(tyQualified, structNodeId);
+                nodes.push({
+                    id: structNodeId,
+                    label: 'Struct',
+                    properties: {
+                        name: ty.name,
+                        filePath: tyFile,
+                        language: MOVE_LANGUAGE,
+                        qualifiedName: tyQualified,
+                        moduleQualifiedName: moduleQualified,
+                        moduleAddress: address,
+                        startLine: spanLine(ty.span, 0),
+                        endLine: spanLine(ty.span, 1),
+                        abilities: arr(ty.abilities),
+                        isResource: arr(ty.abilities).includes(MOVE_ABILITY.KEY),
+                        isEvent: attrs.includes(MOVE_ATTR.EVENT),
+                        attributes: attrs,
+                        attributesJson: attributesJson(ty.attributes),
+                        typeParamsJson: typeParamsJson(ty.typeParams),
+                        fields: (ty.fields ?? []).map((f) => ({
+                            name: f.name,
+                            type: f.type,
+                            positional: f.positional,
+                        })),
+                        // STRING[] projection persisted to lbug (`fieldList` column).
+                        fieldList: (ty.fields ?? []).map((f) => `${f.name}: ${f.type}`),
+                        moveDeclarationKind: 'struct',
+                        locationFidelity: ty.file ? 'precise' : 'package',
+                    },
+                });
+                edge(moduleNodeId, structNodeId, 'DEFINES', 1.0, MOVE_EDGE_REASON.definesStruct);
+                // `#[resource_group_member(group = ...)]` carries an exact qualified
+                // struct ref (e.g. '0xa::vault::Group') - queue a membership USES_TYPE
+                // edge resolved against the cross-package type index in Pass B.
+                const resourceGroup = resourceGroupOf(ty.attributes);
+                if (resourceGroup) {
+                    pendingTypeRef.push({
+                        sourceNodeId: structNodeId,
+                        moduleQualified,
+                        target: resourceGroup,
+                        reason: MOVE_EDGE_REASON.resourceGroupMember,
+                    });
+                }
+                // Per-field Property nodes + HAS_PROPERTY edges so ACCESSES queries and
+                // field-level taint can target individual fields. The composite name +
+                // type live on the Struct as a `fields` array projection, but only the
+                // per-field nodes let Cypher join on `(:Struct)-[:HAS_PROPERTY]->(:Property)`.
+                for (const field of arr(ty.fields)) {
+                    const propId = moveFieldNodeId(tyQualified, field.name, tyFile);
+                    nodes.push({
+                        id: propId,
+                        label: 'Property',
+                        properties: {
+                            name: field.name,
+                            filePath: tyFile,
+                            language: MOVE_LANGUAGE,
+                            qualifiedName: `${tyQualified}.${field.name}`,
+                            parentStruct: tyQualified,
+                            moduleQualifiedName: moduleQualified,
+                            declaredType: field.type,
+                            positional: field.positional,
+                            startLine: spanLine(ty.span, 0),
+                        },
+                    });
+                    edge(structNodeId, propId, 'HAS_PROPERTY', 1.0, MOVE_EDGE_REASON.hasField);
+                }
+            }
+            else {
+                const eId = moveEnumNodeId(tyQualified, tyFile);
+                structNodeMap.set(tyQualified, eId);
+                nodes.push({
+                    id: eId,
+                    label: 'Enum',
+                    properties: {
+                        name: ty.name,
+                        filePath: tyFile,
+                        language: MOVE_LANGUAGE,
+                        qualifiedName: tyQualified,
+                        moduleQualifiedName: moduleQualified,
+                        moduleAddress: address,
+                        startLine: spanLine(ty.span, 0),
+                        endLine: spanLine(ty.span, 1),
+                        abilities: arr(ty.abilities),
+                        isResource: arr(ty.abilities).includes(MOVE_ABILITY.KEY),
+                        isEvent: attrs.includes(MOVE_ATTR.EVENT),
+                        attributes: attrs,
+                        attributesJson: attributesJson(ty.attributes),
+                        typeParamsJson: typeParamsJson(ty.typeParams),
+                        moveDeclarationKind: 'enum',
+                        locationFidelity: ty.file ? 'precise' : 'package',
+                    },
+                });
+                edge(moduleNodeId, eId, 'DEFINES', 1.0, MOVE_EDGE_REASON.definesEnum);
+                for (const variant of arr(ty.variants)) {
+                    const vId = moveEnumVariantNodeId(tyQualified, variant.name, tyFile);
+                    nodes.push({
+                        id: vId,
+                        label: 'EnumVariant',
+                        properties: {
+                            name: variant.name,
+                            filePath: tyFile,
+                            language: MOVE_LANGUAGE,
+                            qualifiedName: `${tyQualified}::${variant.name}`,
+                            parentEnum: tyQualified,
+                            moduleQualifiedName: moduleQualified,
+                            variantKind: variant.kind,
+                            fieldsJson: JSON.stringify(arr(variant.fields).map((f) => ({
+                                name: f.name,
+                                type: f.type,
+                                positional: f.positional,
+                            }))),
+                            attributes: attributeNames(variant.attributes),
+                            attributesJson: attributesJson(variant.attributes),
+                            locationFidelity: ty.file ? 'module' : 'package',
+                        },
+                    });
+                    edge(eId, vId, 'CONTAINS', 1.0, MOVE_EDGE_REASON.containsVariant);
+                }
+            }
+        }
+        // Constants
+        for (const c of arr(mod.constants)) {
+            const cQualified = `${moduleQualified}::${c.name}`;
+            const cNodeId = moveConstNodeId(cQualified, file);
+            nodes.push({
+                id: cNodeId,
+                label: 'Const',
+                properties: {
+                    name: c.name,
+                    filePath: file,
+                    language: MOVE_LANGUAGE,
+                    qualifiedName: cQualified,
+                    moduleQualifiedName: moduleQualified,
+                    constType: c.type,
+                    constValue: c.value,
+                    isErrorCode: ERROR_CODE_PATTERN.test(c.name),
+                    locationFidelity: mod.file ? 'module' : 'package',
+                },
+            });
+            edge(moduleNodeId, cNodeId, 'DEFINES', 1.0, MOVE_EDGE_REASON.definesConst);
+        }
+    }
+    return {
+        nodes,
+        edges,
+        moduleFileMap,
+        functionNodeMap,
+        structNodeMap,
+        pendingResource,
+        pendingFriends,
+        pendingTypeRef,
+        pendingLambdaHosts,
+    };
+}
+/**
+ * Resolve queued lambda→host links into CALLS edges. Run after every package's
+ * facts have been mapped so the host's Function node is guaranteed to exist
+ * (the host may be defined in a different module within the package, or — for
+ * cross-package lambda capture — in another package altogether).
+ */
+export function resolveLambdaHostEdges(pendingLambdaHosts, functionNodeMap, edgeSink) {
+    const seen = new Set();
+    for (const p of pendingLambdaHosts) {
+        const hostId = functionNodeMap.get(p.hostQualified);
+        if (!hostId)
+            continue;
+        const key = `${hostId}\0${p.lambdaFnNodeId}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        edgeSink({
+            id: moveRelId(hostId, 'CALLS', p.lambdaFnNodeId, MOVE_EDGE_REASON.lambdaHost),
+            sourceId: hostId,
+            targetId: p.lambdaFnNodeId,
+            type: 'CALLS',
+            confidence: 0.9,
+            reason: MOVE_EDGE_REASON.lambdaHost,
+        });
+    }
+}
+export function buildLocalNameIndex(structNodeMap) {
+    const structIdsByLocalName = new Map();
+    for (const [qn, id] of structNodeMap) {
+        const key = moveLocalName(qn);
+        const list = structIdsByLocalName.get(key);
+        if (list)
+            list.push(id);
+        else
+            structIdsByLocalName.set(key, [id]);
+    }
+    return structIdsByLocalName;
+}
+function resolveStructRef(localOrQualified, callerModule, structNodeMap, structIdsByLocalName) {
+    const exact = structNodeMap.get(localOrQualified);
+    if (exact)
+        return { targetId: exact };
+    const base = stripTypeArgs(localOrQualified);
+    const baseExact = structNodeMap.get(base);
+    if (baseExact)
+        return { targetId: baseExact };
+    // move-flow emits every resourceAccess/param/return ref fully qualified, so a
+    // qualified ref that misses the exact lookup is a type outside the indexed
+    // graph (e.g. a dependency-only 0x1::coin::CoinStore). Falling through to the
+    // bare-name heuristic would silently mis-bind it to a same-named repo struct
+    // under a different address - report unresolved instead. The heuristics below
+    // remain only for unqualified inputs.
+    if (base.includes('::'))
+        return { unresolved: true };
+    const sameModule = structNodeMap.get(`${callerModule}::${base}`);
+    if (sameModule)
+        return { targetId: sameModule };
+    const matches = structIdsByLocalName.get(moveLocalName(base)) ?? [];
+    if (matches.length === 1)
+        return { targetId: matches[0] };
+    return matches.length > 1 ? { ambiguous: true } : { unresolved: true };
+}
+export function resolveResourceEdges(pendingResource, structNodeMap, structIdsByLocalName, edgeSink, onUnresolved, onAmbiguous) {
+    const seenResourceEdges = new Set();
+    for (const pr of pendingResource) {
+        const resolved = resolveStructRef(pr.target, pr.moduleQualified, structNodeMap, structIdsByLocalName);
+        if ('unresolved' in resolved) {
+            onUnresolved?.(pr);
+            continue;
+        }
+        if ('ambiguous' in resolved) {
+            onAmbiguous?.(pr);
+            continue;
+        }
+        const key = `${pr.fnNodeId}\0${pr.type}\0${resolved.targetId}`;
+        if (seenResourceEdges.has(key))
+            continue;
+        seenResourceEdges.add(key);
+        edgeSink({
+            id: moveRelId(pr.fnNodeId, pr.type, resolved.targetId, pr.reason),
+            sourceId: pr.fnNodeId,
+            targetId: resolved.targetId,
+            type: pr.type,
+            confidence: 1.0,
+            reason: pr.reason,
+        });
+    }
+}
+export function resolveFriendEdges(pendingFriends, moduleFileMap, edgeSink) {
+    for (const pf of pendingFriends) {
+        const friendFile = moduleFileMap.get(pf.friend);
+        if (!friendFile)
+            continue;
+        const targetId = moveModuleNodeId(pf.friend, friendFile);
+        edgeSink({
+            id: moveRelId(pf.moduleNodeId, 'FRIEND_OF', targetId, MOVE_EDGE_REASON.friend),
+            sourceId: pf.moduleNodeId,
+            targetId,
+            type: 'FRIEND_OF',
+            confidence: 1.0,
+            reason: MOVE_EDGE_REASON.friend,
+        });
+    }
+}
+export function resolveTypeRefEdges(pendingTypeRef, structNodeMap, structIdsByLocalName, edgeSink, onUnresolved, onAmbiguous) {
+    const seenTypeEdges = new Set();
+    for (const pr of pendingTypeRef) {
+        const resolved = resolveStructRef(pr.target, pr.moduleQualified, structNodeMap, structIdsByLocalName);
+        if ('unresolved' in resolved) {
+            onUnresolved?.(pr);
+            continue;
+        }
+        if ('ambiguous' in resolved) {
+            onAmbiguous?.(pr);
+            continue;
+        }
+        const key = `${pr.sourceNodeId}\0${pr.reason}\0${resolved.targetId}`;
+        if (seenTypeEdges.has(key))
+            continue;
+        seenTypeEdges.add(key);
+        edgeSink({
+            id: moveRelId(pr.sourceNodeId, 'USES_TYPE', resolved.targetId, pr.reason),
+            sourceId: pr.sourceNodeId,
+            targetId: resolved.targetId,
+            type: 'USES_TYPE',
+            confidence: 1.0,
+            reason: pr.reason,
+        });
+    }
+}

package/dist/core/move/install-lock.d.ts

@@ -0,0 +1,14 @@
+import { type FileHandle } from 'node:fs/promises';
+export interface LockOptions {
+    waitTimeoutMs?: number;
+    leaseMs?: number;
+    heartbeatMs?: number;
+    retryMs?: number;
+}
+export interface InstallLockIo {
+    openLock(lockPath: string): Promise<FileHandle>;
+    removeLock(lockPath: string): Promise<void>;
+}
+/** Allow for the artifact download, extraction, publication, and version probe. */
+export declare const moveFlowInstallLockWaitMs: (httpTimeoutMs: number) => number;
+export declare function acquireInstallLock(lockPath: string, options?: LockOptions, io?: InstallLockIo): Promise<() => Promise<void>>;

package/dist/core/move/install-lock.js

@@ -0,0 +1,102 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rm, stat, utimes } from 'node:fs/promises';
+import path from 'node:path';
+import { setTimeout as wait } from 'node:timers/promises';
+const DEFAULT_LOCK_WAIT_MS = 60_000;
+const INSTALL_COMPLETION_GRACE_MS = 60_000;
+const DEFAULT_LOCK_LEASE_MS = 60_000;
+const DEFAULT_HEARTBEAT_MS = 5_000;
+const DEFAULT_LOCK_RETRY_MS = 100;
+const defaultLockIo = {
+    openLock: (lockPath) => open(lockPath, 'wx'),
+    removeLock: async (lockPath) => {
+        await rm(lockPath, { force: true });
+    },
+};
+/** Allow for the artifact download, extraction, publication, and version probe. */
+export const moveFlowInstallLockWaitMs = (httpTimeoutMs) => Math.max(DEFAULT_LOCK_WAIT_MS, httpTimeoutMs * 2 + INSTALL_COMPLETION_GRACE_MS);
+const readLock = async (lockPath) => {
+    try {
+        const parsed = JSON.parse(await readFile(lockPath, 'utf8'));
+        return typeof parsed.token === 'string' ? parsed.token : null;
+    }
+    catch {
+        return null;
+    }
+};
+const statOrNull = async (file) => {
+    try {
+        return await stat(file);
+    }
+    catch {
+        return null;
+    }
+};
+const removeStaleLock = async (lockPath, leaseMs) => {
+    const first = await statOrNull(lockPath);
+    if (!first || Date.now() - first.mtimeMs <= leaseMs)
+        return;
+    const token = await readLock(lockPath);
+    await wait(25);
+    const second = await statOrNull(lockPath);
+    if (!second ||
+        second.mtimeMs !== first.mtimeMs ||
+        Date.now() - second.mtimeMs <= leaseMs ||
+        (await readLock(lockPath)) !== token) {
+        return;
+    }
+    await rm(lockPath, { force: true });
+};
+export async function acquireInstallLock(lockPath, options = {}, io = defaultLockIo) {
+    const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_LOCK_WAIT_MS;
+    const leaseMs = options.leaseMs ?? DEFAULT_LOCK_LEASE_MS;
+    const heartbeatMs = options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
+    const retryMs = options.retryMs ?? DEFAULT_LOCK_RETRY_MS;
+    const deadline = Date.now() + waitTimeoutMs;
+    const token = randomUUID();
+    await mkdir(path.dirname(lockPath), { recursive: true });
+    while (Date.now() < deadline) {
+        let created = false;
+        try {
+            const handle = await io.openLock(lockPath);
+            created = true;
+            try {
+                await handle.writeFile(JSON.stringify({ token, pid: process.pid }));
+            }
+            finally {
+                await handle.close();
+            }
+            let heartbeatRunning = false;
+            const heartbeat = setInterval(() => {
+                if (heartbeatRunning)
+                    return;
+                heartbeatRunning = true;
+                void (async () => {
+                    if ((await readLock(lockPath)) !== token)
+                        return;
+                    const now = new Date();
+                    await utimes(lockPath, now, now);
+                })()
+                    .catch(() => { })
+                    .finally(() => {
+                    heartbeatRunning = false;
+                });
+            }, heartbeatMs);
+            heartbeat.unref();
+            return async () => {
+                clearInterval(heartbeat);
+                if ((await readLock(lockPath)) === token)
+                    await rm(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            if (created)
+                await io.removeLock(lockPath).catch(() => { });
+            if (error.code !== 'EEXIST')
+                throw error;
+            await removeStaleLock(lockPath, leaseMs);
+            await wait(retryMs);
+        }
+    }
+    throw new Error('timed out waiting for another move-flow installation');
+}

package/dist/core/move/install.d.ts

@@ -0,0 +1,39 @@
+import type { MoveFlowReleaseSelection } from './constants.js';
+export interface VerifiedMoveFlowBinary {
+    binaryPath: string;
+    version: string;
+    fingerprint: string;
+}
+export type MoveFlowInstallStatus = 'available' | 'installed' | 'skipped' | 'unsupported' | 'failed';
+export interface MoveFlowInstallResult {
+    status: MoveFlowInstallStatus;
+    message?: string;
+    /** Verified runtime descriptor, set on 'available' and 'installed'. */
+    binary?: VerifiedMoveFlowBinary;
+}
+export interface MoveFlowInstallConfig {
+    version: string;
+    repository: string;
+    tag: string;
+    releaseTarget: string;
+    assetName: string;
+    releaseBase: string;
+    binaryName: string;
+    installDir: string;
+    binaryPath: string;
+    metadataPath: string;
+    lockPath: string;
+    httpTimeoutMs: number;
+}
+interface PowerShellInvocation {
+    args: string[];
+    env: NodeJS.ProcessEnv;
+}
+export declare function getMoveFlowInstallConfig(env?: NodeJS.ProcessEnv): Promise<MoveFlowInstallConfig | null>;
+/** Resolve the configured release without downloading or starting move-flow. */
+export declare function getMoveFlowReleaseSelection(env?: NodeJS.ProcessEnv): Promise<MoveFlowReleaseSelection | undefined>;
+export declare const powershellExpandArchiveInvocation: (archive: string, destination: string) => PowerShellInvocation;
+export declare const reportedMoveFlowVersion: (output: string) => string | null;
+export declare function findCachedMoveFlowBinary(env?: NodeJS.ProcessEnv): Promise<VerifiedMoveFlowBinary | null>;
+export declare function installMoveFlow(env?: NodeJS.ProcessEnv): Promise<MoveFlowInstallResult>;
+export {};