gitnexus 1.6.9 → 1.6.10-aptos.0

package/dist/core/move/artifact-download.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { rename, rm } from 'node:fs/promises';
+import { get as httpsGet } from 'node:https';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { setTimeout as wait } from 'node:timers/promises';
+export const MAX_ARCHIVE_BYTES = 256 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+const MAX_ATTEMPTS = 3;
+const RETRYABLE_CODES = new Set([
+    'EAI_AGAIN',
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'EPIPE',
+    'ETIMEDOUT',
+    'ERR_STREAM_PREMATURE_CLOSE',
+    'ENETDOWN',
+    'ENETUNREACH',
+]);
+class RetryableDownloadError extends Error {
+    retryAfterMs;
+    constructor(message, retryAfterMs = 0) {
+        super(message);
+        this.retryAfterMs = retryAfterMs;
+    }
+}
+const parseRetryAfter = (value) => {
+    const raw = Array.isArray(value) ? value[0] : value;
+    if (!raw)
+        return 0;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1_000;
+    const date = Date.parse(raw);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+};
+const safeRequestLabel = (target) => {
+    const parsed = new URL(target);
+    return `${parsed.origin}${parsed.pathname}`;
+};
+const isRetryableError = (error) => error instanceof RetryableDownloadError ||
+    (error instanceof Error && RETRYABLE_CODES.has(error.code ?? ''));
+const downloadAttempt = async (initialUrl, partial, deadline, get, maxBytes) => {
+    if (new URL(initialUrl).protocol !== 'https:') {
+        throw new Error('move-flow downloads require HTTPS');
+    }
+    let target = initialUrl;
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error('download timed out');
+        const result = await new Promise((resolve, reject) => {
+            let activeResponse = null;
+            let pipelineStarted = false;
+            const req = get(target, {}, (response) => {
+                const status = response.statusCode ?? 0;
+                if (status >= 300 && status < 400 && response.headers.location) {
+                    let redirect;
+                    try {
+                        redirect = new URL(response.headers.location, target);
+                    }
+                    catch {
+                        response.destroy();
+                        reject(new Error(`invalid redirect from ${safeRequestLabel(target)}`));
+                        return;
+                    }
+                    response.destroy();
+                    if (redirect.protocol !== 'https:') {
+                        reject(new Error(`refusing non-HTTPS redirect to ${redirect.protocol}`));
+                        return;
+                    }
+                    resolve({ redirect: redirect.toString() });
+                    return;
+                }
+                if (status !== 200) {
+                    response.destroy();
+                    const message = `HTTP ${status} for ${safeRequestLabel(target)}`;
+                    if (status === 408 || status === 429 || status >= 500) {
+                        reject(new RetryableDownloadError(message, parseRetryAfter(response.headers['retry-after'])));
+                    }
+                    else {
+                        reject(new Error(message));
+                    }
+                    return;
+                }
+                const rawLength = response.headers['content-length'];
+                const contentLength = Number(Array.isArray(rawLength) ? rawLength[0] : rawLength);
+                if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+                    response.destroy();
+                    reject(new Error(`download exceeds ${maxBytes} bytes`));
+                    return;
+                }
+                let received = 0;
+                const limit = new Transform({
+                    transform(chunk, _encoding, callback) {
+                        received += chunk.length;
+                        callback(received > maxBytes ? new Error(`download exceeds ${maxBytes} bytes`) : null, chunk);
+                    },
+                });
+                activeResponse = response;
+                pipelineStarted = true;
+                void pipeline(response, limit, createWriteStream(partial)).then(() => resolve({}), reject);
+            });
+            const timeout = setTimeout(() => req.destroy(Object.assign(new Error('download timed out'), { code: 'ETIMEDOUT' })), Math.max(1, remaining));
+            req.once('close', () => clearTimeout(timeout));
+            req.once('error', (error) => {
+                if (pipelineStarted) {
+                    // Once the body pipeline owns the response, it must be the only
+                    // operation that settles this attempt. Otherwise cleanup/retry can
+                    // reuse the partial path while the old response is still writing.
+                    activeResponse?.destroy(error);
+                    return;
+                }
+                reject(error);
+            });
+        });
+        if (!result.redirect)
+            return;
+        target = result.redirect;
+    }
+    throw new Error('too many redirects');
+};
+export const downloadToFile = async (url, destination, timeoutMs, get = httpsGet, maxBytes = MAX_ARCHIVE_BYTES) => {
+    const partial = `${destination}.partial`;
+    const deadline = Date.now() + timeoutMs;
+    try {
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
+            await rm(partial, { force: true });
+            try {
+                await downloadAttempt(url, partial, deadline, get, maxBytes);
+                await rename(partial, destination);
+                return;
+            }
+            catch (error) {
+                await rm(partial, { force: true });
+                if (!isRetryableError(error) || attempt === MAX_ATTEMPTS)
+                    throw error;
+                const retryAfter = error instanceof RetryableDownloadError ? error.retryAfterMs : attempt * 100;
+                const remaining = deadline - Date.now();
+                if (remaining <= 1)
+                    throw error;
+                await wait(Math.min(Math.max(0, retryAfter), remaining - 1));
+            }
+        }
+    }
+    finally {
+        await rm(partial, { force: true });
+    }
+};
+export const sha256File = async (file) => {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(file))
+        hash.update(chunk);
+    return hash.digest('hex');
+};
+export const expectedSha = (sumsText, assetName) => {
+    for (const raw of sumsText.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        const standard = /^([0-9a-f]{64})[ \t*]+(\S.*)$/i.exec(line);
+        if (standard && standard[2] === assetName)
+            return standard[1].toLowerCase();
+        const bsd = /^SHA256\s*\((.*)\)\s*=\s*([0-9a-f]{64})$/i.exec(line);
+        if (bsd && bsd[1] === assetName)
+            return bsd[2].toLowerCase();
+    }
+    return null;
+};
+export const verifyArchiveChecksum = async (sumsText, assetName, archivePath) => {
+    const expected = expectedSha(sumsText, assetName);
+    if (!expected)
+        return { status: 'missing' };
+    const actual = await sha256File(archivePath);
+    return actual === expected
+        ? { status: 'match', expected, actual }
+        : { status: 'mismatch', expected, actual };
+};

package/dist/core/move/compiler-facts.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Normalized compiler facts for Move.
+ *
+ * `move-flow` is the authoritative source for package/module/function facts.
+ * This module keeps the raw MCP shapes in one place and exposes a stable,
+ * parsed representation that downstream projections can consume without
+ * re-querying move-flow or reparsing signatures independently.
+ */
+export interface MoveFlowConstant {
+    name: string;
+    type: string;
+    value: string;
+}
+export type CallGraphMap = Record<string, string[]>;
+/** A generic type parameter as reported by the facts query. */
+export interface MoveFactsTypeParam {
+    name: string;
+    abilities: string[];
+    isPhantom: boolean;
+}
+/** A struct field or enum-variant field. */
+export interface MoveFactsField {
+    /** Field name, or the positional index (`"0"`, `"1"`, …) for positional fields. */
+    name: string;
+    type: string;
+    positional: boolean;
+}
+/**
+ * A parsed attribute. Recursive shape: nested `args` and assignment `value`s
+ * are serialized (keys absent when none/empty, per serde skip rules). Examples:
+ *   `{ name: "view" }`
+ *   `{ name: "lint::skip", args: [{ name: "needless_bool" }] }`
+ *   `{ name: "resource_group_member", args: [{ name: "group", value: "0xa::vault::Group" }] }`
+ */
+export interface MoveFactsAttribute {
+    name: string;
+    /** Assignment value, e.g. `group = "0xa::vault::Group"` -> `"0xa::vault::Group"`. */
+    value?: string;
+    /** Nested attribute arguments (recursive). */
+    args?: MoveFactsAttribute[];
+    [key: string]: unknown;
+}
+/** A `friend` declaration target. */
+export interface MoveFactsFriend {
+    module: string;
+}
+/** One enum variant. */
+export interface MoveFactsVariant {
+    name: string;
+    kind: 'unit' | 'positional' | 'named';
+    fields: MoveFactsField[];
+    attributes: MoveFactsAttribute[];
+}
+/** AST-derived resource access for a function. Every value is a
+ *  fully-qualified type expression such as `"0xa::vault::Holding"`
+ *  (lowercase, non-zero-padded hex addresses). */
+export interface MoveFactsResourceAccess {
+    reads: string[];
+    writes: string[];
+}
+/** A function as reported by the facts query. */
+export interface MoveFactsFunction {
+    name: string;
+    file?: string;
+    span?: [number, number];
+    visibility: string;
+    isEntry: boolean;
+    isInline: boolean;
+    isNative: boolean;
+    isView: boolean;
+    attributes?: MoveFactsAttribute[];
+    typeParams?: MoveFactsTypeParam[];
+    params?: {
+        name: string;
+        type: string;
+    }[];
+    /**
+     * Return types, one entry per tuple element: `[]` for no return, one entry
+     * for a scalar, N entries for a tuple.
+     */
+    returnTypes: string[];
+    /** Fully-qualified resource names the function acquires (e.g. `0xa::coin::CoinStore`). */
+    acquiresInferred?: string[];
+    resourceAccess?: MoveFactsResourceAccess;
+    /** Compiler-synthesized lambda-lifted function. */
+    isLambdaLifted?: boolean;
+    /** Host function's local name for lambda-lifted functions (resolved through
+     *  nested closures by move-flow). */
+    definedIn?: string;
+}
+/**
+ * A struct or enum as reported by the facts query. move-flow groups both under
+ * the module's `structs` array and distinguishes them by `kind`.
+ */
+export interface MoveFactsType {
+    kind: 'struct' | 'enum';
+    name: string;
+    file?: string;
+    span?: [number, number];
+    abilities: string[];
+    typeParams: MoveFactsTypeParam[];
+    /** Present for structs. */
+    fields?: MoveFactsField[];
+    /** Present for enums. */
+    variants?: MoveFactsVariant[];
+    attributes: MoveFactsAttribute[];
+}
+/** Per-module facts. */
+export interface MoveFactsModule {
+    file?: string;
+    span?: [number, number];
+    friends?: MoveFactsFriend[];
+    attributes?: MoveFactsAttribute[];
+    functions?: MoveFactsFunction[];
+    /** Structs *and* enums (each tagged by `kind`), per the facts `structs` key. */
+    structs?: MoveFactsType[];
+    constants?: MoveFlowConstant[];
+}
+/** The full facts query response: qualified module name → facts. */
+export type MoveFactsMap = Record<string, MoveFactsModule>;

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

@@ -0,0 +1,9 @@
+/**
+ * Normalized compiler facts for Move.
+ *
+ * `move-flow` is the authoritative source for package/module/function facts.
+ * This module keeps the raw MCP shapes in one place and exposes a stable,
+ * parsed representation that downstream projections can consume without
+ * re-querying move-flow or reparsing signatures independently.
+ */
+export {};

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

@@ -0,0 +1,28 @@
+import type { KnowledgeGraph } from '../graph/types.js';
+import type { MovePackageStatus } from './mcp-client.js';
+import type { MoveIngestOutput } from './move-ingest.js';
+export type MoveConsistencySeverity = 'warning' | 'error';
+export interface MoveConsistencyIssue {
+    code: 'missing-owned-caller' | 'missing-owned-callee' | 'malformed-source-evidence' | 'unresolved-resource-target'
+    /** Package with .move sources returned facts `{}` - severity policy in
+     *  `emptyFactsIssue` below. */
+     | 'empty-package-facts';
+    severity: MoveConsistencySeverity;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/** A sources-but-empty-facts package plus what `move_package_status` said
+ *  (`null` = build status unavailable: older move-flow, or probe failure). */
+export interface EmptyFactsPackage {
+    pkgRoot: string;
+    moveFileCount: number;
+    status: MovePackageStatus | null;
+}
+/**
+ * Severity policy for a package whose facts came back `{}` despite .move
+ * sources: compiling -> warning (likely test-only, elided from facts), failing
+ * -> error carrying the compiler diagnostics, status unavailable -> pessimistic
+ * error. Pure mapping - probing the status (client I/O) stays in the phase.
+ */
+export declare function emptyFactsIssue(pkg: EmptyFactsPackage): MoveConsistencyIssue;
+export declare function validateMoveIngestOutput(graph: KnowledgeGraph, moveIngest: MoveIngestOutput): MoveConsistencyIssue[];

package/dist/core/move/consistency.js

@@ -0,0 +1,98 @@
+import { moveModuleQualifiedName } from './symbol-id.js';
+/**
+ * Severity policy for a package whose facts came back `{}` despite .move
+ * sources: compiling -> warning (likely test-only, elided from facts), failing
+ * -> error carrying the compiler diagnostics, status unavailable -> pessimistic
+ * error. Pure mapping - probing the status (client I/O) stays in the phase.
+ */
+export function emptyFactsIssue(pkg) {
+    const { pkgRoot, moveFileCount, status } = pkg;
+    if (status === null) {
+        return {
+            code: 'empty-package-facts',
+            severity: 'error',
+            message: `Move package produced no facts despite containing .move sources ` +
+                `(does it compile? check \`move_package_status\`): ${pkgRoot}`,
+            details: { packageRoot: pkgRoot, moveFileCount },
+        };
+    }
+    if (status.ok) {
+        return {
+            code: 'empty-package-facts',
+            severity: 'warning',
+            message: `Move package compiles but produced no facts - likely test-only ` +
+                `(#[test]/#[test_only] items are elided); its .move files stay un-ingested: ${pkgRoot}`,
+            details: { packageRoot: pkgRoot, moveFileCount },
+        };
+    }
+    const firstLine = status.diagnostics.split('\n', 1)[0]?.trim();
+    return {
+        code: 'empty-package-facts',
+        severity: 'error',
+        message: `Move package produced no facts because it does not compile` +
+            (firstLine ? ` (${firstLine})` : '') +
+            `: ${pkgRoot}`,
+        details: { packageRoot: pkgRoot, moveFileCount, diagnostics: status.diagnostics },
+    };
+}
+export function validateMoveIngestOutput(graph, moveIngest) {
+    const issues = [];
+    for (const [moduleQualified, filePath] of moveIngest.moduleFileMap) {
+        if (!filePath.endsWith('.move')) {
+            issues.push({
+                code: 'malformed-source-evidence',
+                severity: 'warning',
+                message: `Move module ${moduleQualified} has non-Move source evidence: ${filePath}`,
+                details: { moduleQualified, filePath },
+            });
+            continue;
+        }
+        const fileNode = graph.getNode(`File:${filePath}`);
+        const knownSource = moveIngest.ingestedFiles.has(filePath) || !!fileNode;
+        if (!knownSource) {
+            issues.push({
+                code: 'malformed-source-evidence',
+                severity: 'warning',
+                message: `Move module ${moduleQualified} points at a source file not seen by ingestion: ${filePath}`,
+                details: { moduleQualified, filePath },
+            });
+        }
+    }
+    for (const [packageRoot, callGraph] of moveIngest.callGraphByPackage) {
+        for (const [callerQualified, callees] of Object.entries(callGraph)) {
+            const callerModule = moveModuleQualifiedName(callerQualified);
+            if (moveIngest.modulePackageMap.has(callerModule) &&
+                !moveIngest.functionNodeMap.has(callerQualified)) {
+                issues.push({
+                    code: 'missing-owned-caller',
+                    severity: 'warning',
+                    message: `Move call graph caller has package ownership but no function node: ${callerQualified}`,
+                    details: { packageRoot, callerQualified },
+                });
+            }
+            for (const calleeQualified of callees) {
+                const calleeModule = moveModuleQualifiedName(calleeQualified);
+                if (!moveIngest.modulePackageMap.has(calleeModule))
+                    continue;
+                if (moveIngest.functionNodeMap.has(calleeQualified))
+                    continue;
+                issues.push({
+                    code: 'missing-owned-callee',
+                    severity: 'warning',
+                    message: `Move call graph callee belongs to this repo but has no function node: ${calleeQualified}`,
+                    details: { packageRoot, callerQualified, calleeQualified },
+                });
+            }
+        }
+    }
+    const dropped = moveIngest.droppedResourceRefs;
+    if (dropped && dropped.length > 0) {
+        issues.push({
+            code: 'unresolved-resource-target',
+            severity: 'warning',
+            message: `${dropped.length} resource read/write/acquires target(s) could not be resolved.`,
+            details: { count: dropped.length, sample: dropped.slice(0, 5) },
+        });
+    }
+    return issues;
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Shared Move/Aptos constants and helpers — single source of truth for the
+ * magic strings that span the mapper, the ingest phase, the entry-point linker,
+ * and the MCP backend. A typo in any duplicated literal silently breaks a query
+ * with no compile error, so they live here.
+ */
+/** `NodeProperties.language` tag for every Move symbol. */
+export declare const MOVE_LANGUAGE = "move";
+/**
+ * Parsed Move attribute names of interest. The mapper persists the full
+ * attribute list on every Function node as `attributes: STRING[]`, so the
+ * canonical Cypher query is `WHERE '<name>' IN f.attributes`. These constants
+ * exist so the mapper, downstream filters, and tests share a typo-resistant
+ * single source of truth for the names that matter (compiler attribute names
+ * follow the move-flow `facts` payload verbatim).
+ */
+export declare const MOVE_ATTR: {
+    readonly EVENT: "event";
+    /** `#[persistent]` — vault burn reentrancy guard and similar invariants. */
+    readonly PERSISTENT: "persistent";
+    /** `#[randomness]` — randomness-attestation entry function. */
+    readonly RANDOMNESS: "randomness";
+    /** `#[deprecated]` — marked obsolete; flagged by Move lints. */
+    readonly DEPRECATED: "deprecated";
+    /** `#[lint::skip(...)]` — suppresses one or more Move lints. */
+    readonly LINT_SKIP: "lint::skip";
+    /** `#[resource_group(scope = ...)]` - declares a resource group. */
+    readonly RESOURCE_GROUP: "resource_group";
+    /** `#[resource_group_member(group = <qualified struct>)]` - group membership. */
+    readonly RESOURCE_GROUP_MEMBER: "resource_group_member";
+    /** `#[verify_only]` — visible to the Move Prover only; excluded from runtime. */
+    readonly VERIFY_ONLY: "verify_only";
+    /** `#[view]` — read-only view function. */
+    readonly VIEW: "view";
+};
+/** Move struct abilities of interest. */
+export declare const MOVE_ABILITY: {
+    readonly KEY: "key";
+};
+/**
+ * `reason` strings for Move graph edges.
+ *
+ * Note on `friend`: move-flow's `friends` array on a module is a *compiler-
+ * derived* set that conflates two source-level concepts: explicit
+ * `friend X::Y;` declarations and the Move-2 cross-module visibility that
+ * `package fun` (and friend-restricted `public(friend)`) implicitly grants.
+ * The facts payload does not preserve which of the two produced each entry,
+ * so the `move-friend-or-package` reason is intentionally ambiguous; a
+ * downstream filter (e.g. re-parsing source) is needed to distinguish them.
+ */
+export declare const MOVE_EDGE_REASON: {
+    readonly definesFunction: "move-module-defines-function";
+    readonly definesStruct: "move-module-defines-struct";
+    readonly definesEnum: "move-module-defines-enum";
+    readonly definesConst: "move-module-defines-const";
+    readonly containsVariant: "move-enum-contains-variant";
+    readonly friend: "move-friend-or-package";
+    readonly calls: "move-compiler-call-graph";
+    readonly crossModuleDependency: "move-cross-module-dependency";
+    readonly moduleInFile: "move-module-in-file";
+    readonly readsResource: "move-reads_resource";
+    readonly writesResource: "move-writes_resource";
+    readonly acquires: "move-acquires";
+    readonly fnParamType: "move-fn-param-type";
+    readonly fnReturnType: "move-fn-return-type";
+    readonly resourceGroupMember: "move-resource-group-member";
+    readonly hasField: "move-struct-has-field";
+    readonly lambdaHost: "move-lambda-of-host";
+    readonly entryFunction: "move-entry-function";
+    readonly viewFunction: "move-view-function";
+};
+/** Error-code constant naming convention (e.g. `E_NOT_REGISTERED`). */
+export declare const ERROR_CODE_PATTERN: RegExp;
+/** True when a file can change compiler facts for an entire Move package. */
+export declare function isMoveCompilerInputPath(filePath: string): boolean;
+export interface MoveCompilerIdentity {
+    version: string;
+    source: 'release' | 'explicit' | 'path';
+    fingerprint: string;
+}
+/** Dynamic release coordinates used to produce a managed move-flow runtime. */
+export interface MoveFlowReleaseSelection {
+    version: string;
+    repository: string;
+    tag: string;
+    assetName: string;
+}
+/** Legacy metadata with recorded Move inputs is treated conservatively. */
+export declare function persistedMoveGraphRequiresCompiler(moveIngestAvailable: boolean | undefined, fileHashes: Record<string, string> | undefined): boolean;
+/** Decide whether managed provisioning must run before the clean-repo fast path. */
+export declare function shouldProvisionMoveFlowBeforeFastPath(hasMovePackages: boolean, persistedGraphRequiresCompiler: boolean, indexedCompiler: MoveCompilerIdentity | undefined, indexedRelease: MoveFlowReleaseSelection | undefined, desiredRelease: MoveFlowReleaseSelection | undefined): boolean;
+/** Compiler-backed facts must be rebuilt when their producer changes. */
+export declare function moveCompilerRequiresFullRebuild(hasMovePackages: boolean, compiler: MoveCompilerIdentity | undefined, indexedWithCompiler: boolean | undefined, indexedCompiler: MoveCompilerIdentity | undefined): boolean;
+/**
+ * Make an absolute path repo-relative so node IDs and `File:` node links align.
+ * Returns the input unchanged when `repoPath` is absent or non-matching.
+ */
+export declare function moveRepoRelativePath(absPath: string, repoPath?: string): string;

package/dist/core/move/constants.js

@@ -0,0 +1,136 @@
+/**
+ * Shared Move/Aptos constants and helpers — single source of truth for the
+ * magic strings that span the mapper, the ingest phase, the entry-point linker,
+ * and the MCP backend. A typo in any duplicated literal silently breaks a query
+ * with no compile error, so they live here.
+ */
+import path from 'node:path';
+/** `NodeProperties.language` tag for every Move symbol. */
+export const MOVE_LANGUAGE = 'move';
+/**
+ * Parsed Move attribute names of interest. The mapper persists the full
+ * attribute list on every Function node as `attributes: STRING[]`, so the
+ * canonical Cypher query is `WHERE '<name>' IN f.attributes`. These constants
+ * exist so the mapper, downstream filters, and tests share a typo-resistant
+ * single source of truth for the names that matter (compiler attribute names
+ * follow the move-flow `facts` payload verbatim).
+ */
+export const MOVE_ATTR = {
+    EVENT: 'event',
+    /** `#[persistent]` — vault burn reentrancy guard and similar invariants. */
+    PERSISTENT: 'persistent',
+    /** `#[randomness]` — randomness-attestation entry function. */
+    RANDOMNESS: 'randomness',
+    /** `#[deprecated]` — marked obsolete; flagged by Move lints. */
+    DEPRECATED: 'deprecated',
+    /** `#[lint::skip(...)]` — suppresses one or more Move lints. */
+    LINT_SKIP: 'lint::skip',
+    /** `#[resource_group(scope = ...)]` - declares a resource group. */
+    RESOURCE_GROUP: 'resource_group',
+    /** `#[resource_group_member(group = <qualified struct>)]` - group membership. */
+    RESOURCE_GROUP_MEMBER: 'resource_group_member',
+    /** `#[verify_only]` — visible to the Move Prover only; excluded from runtime. */
+    VERIFY_ONLY: 'verify_only',
+    /** `#[view]` — read-only view function. */
+    VIEW: 'view',
+};
+/** Move struct abilities of interest. */
+export const MOVE_ABILITY = {
+    KEY: 'key',
+};
+/**
+ * `reason` strings for Move graph edges.
+ *
+ * Note on `friend`: move-flow's `friends` array on a module is a *compiler-
+ * derived* set that conflates two source-level concepts: explicit
+ * `friend X::Y;` declarations and the Move-2 cross-module visibility that
+ * `package fun` (and friend-restricted `public(friend)`) implicitly grants.
+ * The facts payload does not preserve which of the two produced each entry,
+ * so the `move-friend-or-package` reason is intentionally ambiguous; a
+ * downstream filter (e.g. re-parsing source) is needed to distinguish them.
+ */
+export const MOVE_EDGE_REASON = {
+    definesFunction: 'move-module-defines-function',
+    definesStruct: 'move-module-defines-struct',
+    definesEnum: 'move-module-defines-enum',
+    definesConst: 'move-module-defines-const',
+    containsVariant: 'move-enum-contains-variant',
+    friend: 'move-friend-or-package',
+    calls: 'move-compiler-call-graph',
+    crossModuleDependency: 'move-cross-module-dependency',
+    moduleInFile: 'move-module-in-file',
+    // Resource-access edges (function → resource struct)
+    readsResource: 'move-reads_resource',
+    writesResource: 'move-writes_resource',
+    acquires: 'move-acquires',
+    fnParamType: 'move-fn-param-type',
+    fnReturnType: 'move-fn-return-type',
+    // Struct -> resource-group struct (from `#[resource_group_member(group = ...)]`)
+    resourceGroupMember: 'move-resource-group-member',
+    // Field edges (struct → field)
+    hasField: 'move-struct-has-field',
+    // Lambda → host edges (host fn → __lambda__N__host)
+    lambdaHost: 'move-lambda-of-host',
+    // Entry-point edge reasons (ENTRY_POINT_OF)
+    entryFunction: 'move-entry-function',
+    viewFunction: 'move-view-function',
+};
+/** Error-code constant naming convention (e.g. `E_NOT_REGISTERED`). */
+export const ERROR_CODE_PATTERN = /^E[_A-Z]/;
+/** True when a file can change compiler facts for an entire Move package. */
+export function isMoveCompilerInputPath(filePath) {
+    const normalized = filePath.replaceAll('\\', '/');
+    const basename = normalized.slice(normalized.lastIndexOf('/') + 1);
+    return normalized.endsWith('.move') || basename === 'Move.toml' || basename === 'Move.lock';
+}
+function sameMoveFlowReleaseSelection(left, right) {
+    return (left !== undefined &&
+        right !== undefined &&
+        left.version === right.version &&
+        left.repository === right.repository &&
+        left.tag === right.tag &&
+        left.assetName === right.assetName);
+}
+/** Legacy metadata with recorded Move inputs is treated conservatively. */
+export function persistedMoveGraphRequiresCompiler(moveIngestAvailable, fileHashes) {
+    if (moveIngestAvailable !== undefined)
+        return moveIngestAvailable;
+    return Object.keys(fileHashes ?? {}).some(isMoveCompilerInputPath);
+}
+/** Decide whether managed provisioning must run before the clean-repo fast path. */
+export function shouldProvisionMoveFlowBeforeFastPath(hasMovePackages, persistedGraphRequiresCompiler, indexedCompiler, indexedRelease, desiredRelease) {
+    if (!hasMovePackages)
+        return false;
+    if (!persistedGraphRequiresCompiler)
+        return true;
+    if (!indexedCompiler)
+        return true;
+    if (indexedCompiler.source !== 'release')
+        return false;
+    return !sameMoveFlowReleaseSelection(indexedRelease, desiredRelease);
+}
+/** Compiler-backed facts must be rebuilt when their producer changes. */
+export function moveCompilerRequiresFullRebuild(hasMovePackages, compiler, indexedWithCompiler, indexedCompiler) {
+    if (!hasMovePackages || !compiler)
+        return false;
+    return (indexedWithCompiler !== true ||
+        !indexedCompiler ||
+        indexedCompiler.version !== compiler.version ||
+        indexedCompiler.source !== compiler.source ||
+        indexedCompiler.fingerprint !== compiler.fingerprint);
+}
+/**
+ * Make an absolute path repo-relative so node IDs and `File:` node links align.
+ * Returns the input unchanged when `repoPath` is absent or non-matching.
+ */
+export function moveRepoRelativePath(absPath, repoPath) {
+    if (!repoPath)
+        return absPath;
+    const relative = path.relative(repoPath, absPath);
+    if (relative === '')
+        return relative;
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return absPath;
+    }
+    return relative.replaceAll(path.sep, '/');
+}