@geastack/compiler 1.0.15

package/dist/preflight/obligations.js

@@ -0,0 +1,36 @@
+/**
+ * The obligation model.
+ *
+ * An obligation is one demanded thing the PLAN needs already installed: a
+ * selected carrier, a call path, a native boundary, a verifier recipe, an
+ * emitter recipe, a physical C++ type. It is not a proof and it does not
+ * compute anything -- it names what was checked, what was expected, what was
+ * actually found, and whether the two agree. `run.ts` walks the sealed
+ * semantic graph and representation plan to build these; nothing here may
+ * synthesize a carrier or invent a fact the earlier layers did not already
+ * publish. Site-level demands -- which conversion a slot needs, which recipe
+ * a receiver takes, which helper a protocol step calls -- are not obligations
+ * any more: `ir/certify.ts` reads them off the lowered IR as capability keys
+ * (the plan's census).
+ */
+export const obligationKinds = [
+    'binding-carrier',
+    'expression-carrier',
+    'return-carrier',
+    'call-abi',
+    'native-boundary',
+    'physical-cpp-type',
+    'verifier-recipe',
+    'emitter-recipe'
+];
+export const predicate = (id, expected, actual) => Object.freeze({ id, expected, actual, pass: expected === actual });
+export const obligationId = (component, kind, discriminator) => `obligation|${component}|${kind}|${discriminator}`;
+/**
+ * A failed predicate is `unsupported` only when the model it queried already
+ * gives an authoritative "never" answer for this coordinate -- a `Never`
+ * conversion node, a helper the manifest lists as never-installable. Every
+ * other failure is `missing`: capability that has not been installed yet, not
+ * capability that cannot exist. Collapsing the two would make an ordinary gap
+ * in an unfinished primitive read as a permanent language limitation.
+ */
+export const localStatusOf = (check, declaredUnsupported) => check.pass ? 'satisfied' : declaredUnsupported ? 'unsupported' : 'missing';

package/dist/preflight/report.d.ts

@@ -0,0 +1,20 @@
+import type { PreflightReport } from './run.js';
+/**
+ * The report, one NDJSON line at a time, each with its newline.
+ *
+ * A generator rather than an array of rows: TypeScript's own compiler has
+ * ~3 million obligations, and the joined report is longer than V8 allows a
+ * single string to be (`RangeError: Invalid string length`, thrown after the
+ * census had already printed, losing only the report). Every consumer either
+ * writes lines as they come (`cli.ts`) or digests them as they come
+ * (`certificate.ts`); nothing needs the whole text in one piece. The order
+ * and the bytes of each line are exactly what the joined form produced, so
+ * the digest a certificate binds to is unchanged.
+ */
+export declare function preflightReportLines(report: PreflightReport): Generator<string, void, undefined>;
+/**
+ * The whole report as one string -- for tests and small reports only. A
+ * report the size of a large program's does not fit in a string at all; use
+ * `preflightReportLines`.
+ */
+export declare const serializePreflightReport: (report: PreflightReport) => string;

package/dist/preflight/report.js

@@ -0,0 +1,61 @@
+const compareComponentId = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/**
+ * The report, one NDJSON line at a time, each with its newline.
+ *
+ * A generator rather than an array of rows: TypeScript's own compiler has
+ * ~3 million obligations, and the joined report is longer than V8 allows a
+ * single string to be (`RangeError: Invalid string length`, thrown after the
+ * census had already printed, losing only the report). Every consumer either
+ * writes lines as they come (`cli.ts`) or digests them as they come
+ * (`certificate.ts`); nothing needs the whole text in one piece. The order
+ * and the bytes of each line are exactly what the joined form produced, so
+ * the digest a certificate binds to is unchanged.
+ */
+export function* preflightReportLines(report) {
+    const line = (row) => `${JSON.stringify(row)}\n`;
+    yield line({ row: 'header', version: 1, componentCount: report.components.length, obligationCount: report.obligations.length });
+    const sortedComponentSummaries = [...report.componentSummaries].sort((left, right) => compareComponentId(left.component, right.component));
+    for (const summary of sortedComponentSummaries) {
+        yield line({
+            row: 'component',
+            component: summary.component,
+            operationCount: summary.operationCount,
+            obligationCount: summary.obligationCount,
+            mandatory: summary.mandatory,
+            optional: summary.optional
+        });
+    }
+    const sortedObligations = [...report.obligations].sort((left, right) => {
+        const byComponent = compareComponentId(left.component, right.component);
+        if (byComponent !== 0)
+            return byComponent;
+        if (left.kind !== right.kind)
+            return left.kind < right.kind ? -1 : 1;
+        return left.id < right.id ? -1 : left.id > right.id ? 1 : 0;
+    });
+    for (const obligation of sortedObligations) {
+        yield line({
+            row: 'obligation',
+            id: obligation.id,
+            kind: obligation.kind,
+            component: obligation.component,
+            derivesFrom: obligation.derivesFrom,
+            optional: obligation.optional,
+            status: obligation.status,
+            predicate: obligation.predicate
+        });
+    }
+    yield line({ row: 'summary', scope: 'total', mandatory: report.totals.mandatory, optional: report.totals.optional });
+    yield line({
+        row: 'completion',
+        clean: report.clean,
+        componentCount: report.components.length,
+        obligationCount: report.obligations.length
+    });
+}
+/**
+ * The whole report as one string -- for tests and small reports only. A
+ * report the size of a large program's does not fit in a string at all; use
+ * `preflightReportLines`.
+ */
+export const serializePreflightReport = (report) => [...preflightReportLines(report)].join('');

package/dist/preflight/run.d.ts

@@ -0,0 +1,39 @@
+import type { ComponentId } from '../identity/ids.js';
+import type { SealedRepresentationPlan } from '../representation/plan.js';
+import type { SemanticGraph } from '../semantics/model/graph.js';
+import type { Obligation, ObligationStatus, TargetRuntimeManifest } from './obligations.js';
+export interface PreflightInput {
+    readonly semanticGraph: SemanticGraph;
+    readonly representationPlan: SealedRepresentationPlan;
+    readonly manifest: TargetRuntimeManifest;
+}
+export interface ObligationTally {
+    readonly satisfied: number;
+    readonly missing: number;
+    readonly unsupported: number;
+    readonly blockedByUpstream: number;
+}
+export interface EvaluatedObligation extends Obligation {
+    readonly status: ObligationStatus;
+}
+export interface PreflightComponentSummary {
+    readonly component: ComponentId;
+    readonly operationCount: number;
+    readonly obligationCount: number;
+    readonly mandatory: ObligationTally;
+    readonly optional: ObligationTally;
+}
+export interface PreflightReport {
+    /** Every authority component that was censused, in the order it was processed. */
+    readonly components: readonly ComponentId[];
+    /** Every obligation row. No caps, no top-N, no clipping -- the complete census. */
+    readonly obligations: readonly EvaluatedObligation[];
+    readonly componentSummaries: readonly PreflightComponentSummary[];
+    readonly totals: {
+        readonly mandatory: ObligationTally;
+        readonly optional: ObligationTally;
+    };
+    /** True only when every mandatory obligation is `satisfied`. Optional gaps never affect this. */
+    readonly clean: boolean;
+}
+export declare const runPreflight: (input: PreflightInput) => PreflightReport;

package/dist/preflight/run.js

@@ -0,0 +1,403 @@
+import { componentId, operationOfResult } from '../identity/ids.js';
+import { representationKey } from '../representation/model.js';
+import { partitionAuthorityComponents } from '../semantics/model/graph.js';
+import { localStatusOf, obligationId, predicate } from './obligations.js';
+/**
+ * The read-only plan-level capability census.
+ *
+ * `runPreflight` takes frozen inputs -- a sealed representation plan, a sealed
+ * semantic graph, and a sealed backend manifest -- and returns a report. It
+ * never mutates any of them, never selects a carrier, never invokes an
+ * emitter; every check below is a membership test against an already-frozen
+ * set. That is what makes this a census and not a second solver: nothing it
+ * computes could change if run again on the same inputs, and nothing it finds
+ * was not already true before this module ran.
+ *
+ * This is the PLAN's census
+ * only: is every selected carrier one the target can spell, does every
+ * invocation have a call path, is every `native-handle` behind an
+ * authenticated protocol, may an ambient binding be an `extern`. Everything
+ * that depended on how a site would LOWER -- which conversion a slot needs,
+ * which property recipe a receiver takes, which runtime helper a protocol
+ * step calls -- is certified once, off the IR lowering actually built
+ * (`ir/certify.ts`), and the seven builders that predicted it here are gone.
+ * What remains gates lowering through the diagnostic sweep; the certificate
+ * is minted from the IR certification.
+ */
+/**
+ * `into.push(...items)` spreads `items` onto the call stack, and V8 caps a
+ * call's argument count. TypeScript's own compiler certifies as ONE component
+ * of the checker's size, whose evaluated obligations no longer fit in a
+ * single call -- `RangeError: Maximum call stack size exceeded`, 20 minutes
+ * in, from a line that only appends to a list. A loop has no such cap.
+ */
+const appendAll = (into, items) => {
+    for (const item of items)
+        into.push(item);
+};
+const carrierKinds = new Set(['binding-carrier', 'expression-carrier', 'return-carrier']);
+const carrierKindFor = (operation) => {
+    if (operation.family === 'binding')
+        return 'binding-carrier';
+    if (operation.family === 'control' && operation.form === 'return')
+        return 'return-carrier';
+    return 'expression-carrier';
+};
+/** The result an operation-level obligation anchors to: its value, else its completion, else its first result. */
+const primaryResultOf = (operation) => {
+    const value = operation.results.find((result) => result.role === 'value');
+    if (value)
+        return value.id;
+    const completion = operation.results.find((result) => result.role === 'completion');
+    if (completion)
+        return completion.id;
+    const first = operation.results[0];
+    return first ? first.id : null;
+};
+/**
+ * The carrier obligation for one published result, plus the backend-capability
+ * triplet (physical type, verifier, emitter) once a carrier was actually
+ * selected. A result the plan left unresolved gets only the carrier row: there
+ * is no carrier kind yet to ask the manifest about.
+ */
+const buildCarrierObligations = (cid, resultId, operation, plan, manifest) => {
+    const kind = carrierKindFor(operation);
+    const representation = plan.selected.get(resultId);
+    const resolved = representation !== undefined && representation.kind !== 'unresolved';
+    const actual = representation === undefined ? 'absent' : representation.kind === 'unresolved' ? `unresolved(${representation.reason})` : 'resolved';
+    const carrierCheck = predicate(`${kind}:selected`, 'resolved', actual);
+    const carrierObligation = {
+        id: obligationId(cid, kind, resultId),
+        kind,
+        component: cid,
+        derivesFrom: resultId,
+        predicate: carrierCheck,
+        optional: false,
+        localStatus: localStatusOf(carrierCheck, false)
+    };
+    if (!resolved || representation === undefined)
+        return [carrierObligation];
+    const key = representationKey(representation);
+    const physicalCheck = predicate(`physical-cpp-type:${key}`, 'registered', manifest.physicalTypes.has(key) ? 'registered' : 'absent');
+    const verifierCheck = predicate(`verifier-recipe:${key}`, 'registered', manifest.verifierRecipes.has(key) ? 'registered' : 'absent');
+    const emitterCheck = predicate(`emitter-recipe:${key}`, 'registered', manifest.emitterRecipes.has(key) ? 'registered' : 'absent');
+    return [
+        carrierObligation,
+        {
+            id: obligationId(cid, 'physical-cpp-type', resultId),
+            kind: 'physical-cpp-type',
+            component: cid,
+            derivesFrom: resultId,
+            predicate: physicalCheck,
+            optional: false,
+            localStatus: localStatusOf(physicalCheck, false)
+        },
+        {
+            id: obligationId(cid, 'verifier-recipe', resultId),
+            kind: 'verifier-recipe',
+            component: cid,
+            derivesFrom: resultId,
+            predicate: verifierCheck,
+            optional: false,
+            localStatus: localStatusOf(verifierCheck, false)
+        },
+        {
+            id: obligationId(cid, 'emitter-recipe', resultId),
+            kind: 'emitter-recipe',
+            component: cid,
+            derivesFrom: resultId,
+            predicate: emitterCheck,
+            optional: false,
+            localStatus: localStatusOf(emitterCheck, false)
+        }
+    ];
+};
+/**
+ * Call ABI obligations. The mandatory row is always the generic dynamic-
+ * dispatch call path -- per the doc, `open` "is a complete, correct answer,"
+ * so every invocation, whatever its target proof, must be able to fall back
+ * to it. `exact`/`closed-family` targets additionally get an `optional`
+ * devirtualization row, reported separately so its absence never fails a
+ * build the generic path already covers.
+ */
+const buildCallAbiObligations = (cid, operation, manifest) => {
+    if (operation.family !== 'invocation')
+        return [];
+    const anchor = primaryResultOf(operation);
+    if (!anchor)
+        return [];
+    const target = operation.target;
+    const obligations = [];
+    const genericCheck = predicate('call-abi:generic', 'installed', manifest.hasGenericCallPath ? 'installed' : 'absent');
+    obligations.push({
+        id: obligationId(cid, 'call-abi', `${anchor}:generic`),
+        kind: 'call-abi',
+        component: cid,
+        derivesFrom: anchor,
+        predicate: genericCheck,
+        optional: false,
+        localStatus: localStatusOf(genericCheck, false)
+    });
+    if (target.kind === 'exact') {
+        const registered = target.target.kind === 'function'
+            ? manifest.functionAbis.has(target.target.functionId)
+            : manifest.implicitConstructorAbis.has(target.target.classDeclaration);
+        const check = predicate('call-abi:exact', 'registered', registered ? 'registered' : 'absent');
+        obligations.push({
+            id: obligationId(cid, 'call-abi', `${anchor}:exact`),
+            kind: 'call-abi',
+            component: cid,
+            derivesFrom: anchor,
+            predicate: check,
+            optional: true,
+            localStatus: localStatusOf(check, false)
+        });
+    }
+    else if (target.kind === 'closed-family') {
+        const total = target.targets.length;
+        const registeredCount = target.targets.filter((member) => member.kind === 'function'
+            ? manifest.functionAbis.has(member.functionId)
+            : manifest.implicitConstructorAbis.has(member.classDeclaration)).length;
+        const check = predicate('call-abi:closed-family', `${total}/${total}`, `${registeredCount}/${total}`);
+        obligations.push({
+            id: obligationId(cid, 'call-abi', `${anchor}:closed-family`),
+            kind: 'call-abi',
+            component: cid,
+            derivesFrom: anchor,
+            predicate: check,
+            optional: true,
+            localStatus: localStatusOf(check, false)
+        });
+    }
+    return obligations;
+};
+/** `native-handle` is admissible only behind a versioned, authenticated host protocol -- never generically. */
+const buildNativeBoundaryObligation = (cid, resultId, representation, manifest) => {
+    if (representation.kind !== 'native-handle')
+        return [];
+    // The carrier is the claim wherever the host stated one. A target either has
+    // `gea::embedded::ui::NodeHandle` or it does not; claiming it thirteen times
+    // under thirteen declared names is thirteen chances for the answers to differ.
+    const key = `${representation.native ?? representation.protocol}@${representation.version}`;
+    const check = predicate(`native-boundary:${key}`, 'registered', manifest.nativeProtocols.has(key) ? 'registered' : 'absent');
+    return [
+        {
+            id: obligationId(cid, 'native-boundary', resultId),
+            kind: 'native-boundary',
+            component: cid,
+            derivesFrom: resultId,
+            predicate: check,
+            optional: false,
+            localStatus: localStatusOf(check, false)
+        }
+    ];
+};
+/**
+ * An ambient value declaration's introduction (`BindingOperation.external`,
+ * semantics/model/operations.ts) is the other way a result crosses into host
+ * territory, alongside `native-handle`. It censuses against
+ * `manifest.supportsExternalBindings` rather than `nativeProtocols`: see that
+ * field's own comment (preflight/obligations.ts) for why this is one flag and
+ * not a set keyed per declaration. Raising the obligation per result rather
+ * than once globally still names exactly which declaration would be blocked
+ * if the flag were ever false, the same way every other obligation in this
+ * file anchors to the result it is actually about.
+ */
+const buildExternalBindingObligation = (cid, resultId, operation, manifest) => {
+    if (operation.family !== 'binding' || !operation.external)
+        return [];
+    const check = predicate('native-boundary:external-binding', 'installed', manifest.supportsExternalBindings ? 'installed' : 'absent');
+    return [
+        {
+            id: obligationId(cid, 'native-boundary', `${resultId}:external-binding`),
+            kind: 'native-boundary',
+            component: cid,
+            derivesFrom: resultId,
+            predicate: check,
+            optional: false,
+            localStatus: localStatusOf(check, false)
+        }
+    ];
+};
+/**
+ * Raise a locally-satisfied carrier obligation to `blocked-by-upstream` when
+ * either (a) a sibling obligation on the same result -- its call ABI,
+ * property access, native boundary, or conversion capability -- did not
+ * itself pass, or (b) the carrier obligation of a result this operation
+ * consumes as an operand did not resolve. This is the one place a status can
+ * differ from `localStatus`, and it is a monotone closure over an already-
+ * computed, finite obligation set: no obligation here invents a fact, and the
+ * loop is bounded by the obligation count, so it is propagation, not solving.
+ */
+const closeBlockedByUpstream = (obligations, graph) => {
+    const byResult = new Map();
+    for (const obligation of obligations) {
+        const siblings = byResult.get(obligation.derivesFrom) ?? [];
+        siblings.push(obligation.id);
+        byResult.set(obligation.derivesFrom, siblings);
+    }
+    const optionalById = new Set(obligations.filter((obligation) => obligation.optional).map((obligation) => obligation.id));
+    const carrierByResult = new Map();
+    for (const obligation of obligations) {
+        if (carrierKinds.has(obligation.kind))
+            carrierByResult.set(obligation.derivesFrom, obligation.id);
+    }
+    const upstreamOf = new Map();
+    for (const obligation of obligations) {
+        if (!carrierKinds.has(obligation.kind))
+            continue;
+        const deps = [];
+        for (const siblingId of byResult.get(obligation.derivesFrom) ?? []) {
+            // An optional sibling is a fast path the mandatory one already covers.
+            // Depending on it would make an unbuilt devirtualization block the
+            // carrier of every value the generic path already carries -- which is
+            // exactly the reading `Obligation.optional` exists to forbid.
+            if (siblingId === obligation.id || optionalById.has(siblingId))
+                continue;
+            deps.push(siblingId);
+        }
+        const operation = graph.operations.get(operationOfResult(obligation.derivesFrom));
+        if (operation) {
+            for (const operand of operation.operands) {
+                if (operand.source.kind !== 'result')
+                    continue;
+                const upstreamCarrier = carrierByResult.get(operand.source.result);
+                if (upstreamCarrier)
+                    deps.push(upstreamCarrier);
+            }
+        }
+        upstreamOf.set(obligation.id, deps);
+    }
+    const status = new Map();
+    for (const obligation of obligations)
+        status.set(obligation.id, obligation.localStatus);
+    let changed = true;
+    let iterations = 0;
+    const limit = obligations.length + 1;
+    while (changed && iterations <= limit) {
+        changed = false;
+        iterations += 1;
+        for (const [id, deps] of upstreamOf) {
+            if (status.get(id) !== 'satisfied')
+                continue;
+            if (deps.some((dep) => status.get(dep) !== 'satisfied')) {
+                status.set(id, 'blocked-by-upstream');
+                changed = true;
+            }
+        }
+    }
+    return obligations.map((obligation) => ({ ...obligation, status: status.get(obligation.id) ?? obligation.localStatus }));
+};
+const emptyTally = () => ({
+    satisfied: 0,
+    missing: 0,
+    unsupported: 0,
+    blockedByUpstream: 0
+});
+const tallyOf = (obligations, optional) => {
+    const tally = emptyTally();
+    for (const obligation of obligations) {
+        if (obligation.optional !== optional)
+            continue;
+        switch (obligation.status) {
+            case 'satisfied':
+                tally.satisfied += 1;
+                break;
+            case 'missing':
+                tally.missing += 1;
+                break;
+            case 'unsupported':
+                tally.unsupported += 1;
+                break;
+            case 'blocked-by-upstream':
+                tally.blockedByUpstream += 1;
+                break;
+        }
+    }
+    return tally;
+};
+/**
+ * Preflight reuses `partitionAuthorityComponents` verbatim -- the same
+ * partition the diagnostic sweep traverses -- and processes components in the
+ * order it returns them. Components are, by construction, connected and
+ * disjoint: no edge crosses two of them, so there is no cross-component
+ * dependency left to order by, and this order already is the SCC/dependency
+ * order the doc requires.
+ */
+/**
+ * The whole-graph result table, dealt out to the component that owns each row.
+ *
+ * The result builders are filters: each keeps the rows whose producer this
+ * component owns. Handing each of them the entire table made the census cost
+ * components x table -- on one measured application, 14,681 components against
+ * 193,082 rows -- so one forward pass deals every row to its own component,
+ * in the table's own order, which is the order the report serializes and the
+ * certificate hashes.
+ */
+const indexResults = (graph, partition) => {
+    const componentOf = new Map();
+    for (const [index, members] of partition.entries())
+        for (const member of members)
+            componentOf.set(member, index);
+    const results = partition.map(() => []);
+    for (const entry of graph.results) {
+        const index = componentOf.get(entry[1]);
+        if (index !== undefined)
+            results[index]?.push(entry);
+    }
+    return results;
+};
+export const runPreflight = (input) => {
+    const { semanticGraph, representationPlan, manifest } = input;
+    const partition = partitionAuthorityComponents(semanticGraph);
+    const indexed = indexResults(semanticGraph, partition);
+    const components = [];
+    const componentSummaries = [];
+    const allObligations = [];
+    for (const [componentIndex, memberOperations] of partition.entries()) {
+        const representative = memberOperations[0];
+        if (representative === undefined)
+            continue;
+        const cid = componentId(representative);
+        components.push(cid);
+        const operationSet = new Set(memberOperations);
+        const componentResults = indexed[componentIndex] ?? [];
+        const componentObligations = [];
+        for (const operationId of operationSet) {
+            const operation = semanticGraph.operations.get(operationId);
+            if (!operation)
+                continue;
+            appendAll(componentObligations, buildCallAbiObligations(cid, operation, manifest));
+        }
+        for (const [resultId, operationId] of componentResults) {
+            if (!operationSet.has(operationId))
+                continue;
+            const operation = semanticGraph.operations.get(operationId);
+            if (!operation)
+                continue;
+            appendAll(componentObligations, buildCarrierObligations(cid, resultId, operation, representationPlan, manifest));
+            const representation = representationPlan.selected.get(resultId);
+            if (representation)
+                appendAll(componentObligations, buildNativeBoundaryObligation(cid, resultId, representation, manifest));
+            appendAll(componentObligations, buildExternalBindingObligation(cid, resultId, operation, manifest));
+        }
+        const evaluated = closeBlockedByUpstream(componentObligations, semanticGraph);
+        appendAll(allObligations, evaluated);
+        componentSummaries.push({
+            component: cid,
+            operationCount: memberOperations.length,
+            obligationCount: evaluated.length,
+            mandatory: tallyOf(evaluated, false),
+            optional: tallyOf(evaluated, true)
+        });
+    }
+    const totals = { mandatory: tallyOf(allObligations, false), optional: tallyOf(allObligations, true) };
+    const clean = totals.mandatory.missing === 0 && totals.mandatory.unsupported === 0 && totals.mandatory.blockedByUpstream === 0;
+    return Object.freeze({
+        components: Object.freeze(components),
+        obligations: Object.freeze(allObligations),
+        componentSummaries: Object.freeze(componentSummaries),
+        totals: Object.freeze(totals),
+        clean
+    });
+};

package/dist/project-preparation.d.ts

@@ -0,0 +1,33 @@
+import type { PackageSource } from './semantics/package-sources.js';
+export type Manifest = Record<string, unknown>;
+export interface SourceFileSystem {
+    readonly exists: (file: string) => boolean;
+    readonly read: (file: string) => string;
+    readonly write: (file: string, text: string) => void;
+    readonly realpath: (file: string) => string;
+}
+export declare const installedPackage: (name: string, from: string, files?: SourceFileSystem) => string | undefined;
+export declare const dependencyInstallCommand: (manifest: Manifest, locks: ReadonlySet<string>) => {
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+};
+/** Install through the project's chosen package manager, without lifecycle execution. */
+export declare const ensureDependencies: (directory: string, log?: (message: string) => void) => void;
+export interface SourceIdentity {
+    readonly url: string;
+    readonly commit: string;
+    readonly directory: string;
+}
+export declare const sourceIdentity: (metadata: Manifest) => SourceIdentity | undefined;
+/** Recover the exact source commit from npm's signed publication provenance when legacy gitHead metadata is absent. */
+export declare const provenanceSourceIdentity: (metadata: Manifest, response: Manifest) => SourceIdentity | undefined;
+export interface PreparationOptions {
+    readonly files?: SourceFileSystem;
+    readonly log?: (message: string) => void;
+    readonly metadata?: (name: string, version: string, root: string) => Promise<Manifest>;
+    readonly attestations?: (url: string, root: string) => Promise<Manifest>;
+    readonly checkout?: (identity: SourceIdentity, destination: string) => void;
+}
+/** Acquire missing typed sources at the installed version; plain JS remains usable. */
+export declare const preparePackageSources: (root: string, options?: PreparationOptions) => Promise<readonly PackageSource[]>;