openplanr 1.25.3 → 2.0.1

package/dist/services/pipeline-package-service.js

@@ -1,19 +1,879 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pathToFileURL } from 'node:url';
+import { sha256CanonicalJson } from './canonical-json.js';
 const require = createRequire(import.meta.url);
+const PIPELINE_ROOT_API_NAMES = [
+    'LIVE_EVIDENCE_ABSENCE_KINDS_V2',
+    'LIVE_EVIDENCE_EFFECT_CLASS_V2',
+    'LIVE_EVIDENCE_PORTABLE_AUTHORITY_V2',
+    'OPERATING_OUTCOME_EVALUATION_OPERATORS_V2',
+    'OperatingLiveEvidenceErrorV2',
+    'assertAcceptedLiveEvidenceBridgeV2',
+    'assertAcceptedLiveEvidenceSourceV2',
+    'assertLiveEvidenceProviderRegistrationV2',
+    'assertLiveEvidenceProviderRegistryV2',
+    'assertOperatingConnectorCheckpointV2',
+    'assertOperatingEvidenceObservationV2',
+    'assertOperatingLearningReceiptV2',
+    'assertOperatingLiveEvidenceConsentRecordV2',
+    'assertOperatingLiveEvidenceIngestionV2',
+    'assertOperatingMeasurementPlanV2',
+    'assertOperatingMeasurementScheduleReceiptV2',
+    'assertOperatingMeasurementScheduleV2',
+    'assertOperatingOutcomeEvaluationV2',
+    'deriveOperatingLiveEvidenceContentDigestV2',
+    'deriveOperatingLiveEvidenceRequestHashV2',
+    'evaluateOperatingOutcomeV2',
+    'reduceOperatingConnectorCheckpointV2',
+    'reduceOperatingMeasurementScheduleV2',
+    'registerLiveEvidenceProviderV2',
+    'LANDING_PORTABLE_AUTHORITY',
+    'LANDING_PROTOCOL_VERSION',
+    'LANDING_SHIP_PROTOCOL_VERSION',
+    'LandingContractError',
+    'assertLandingConfirmation',
+    'assertLandingEvent',
+    'assertLandingOperationRegistry',
+    'assertLandingPhaseReceipt',
+    'assertLandingPlan',
+    'assertLandingReceipt',
+    'createLandingEventState',
+    'reduceLandingEvents',
+];
+const PIPELINE_PROTOCOL_API_NAMES = [
+    'LANDING_CONTRACT_KINDS_V1',
+    'OPERATE_LIVE_EVIDENCE_CONTRACT_KINDS_V2',
+    'OPERATE_RUNTIME_CONTRACT_KINDS',
+    'loadLandingContract',
+    'loadOperateLiveEvidenceContract',
+    'loadOperateRuntimeContract',
+    'loadProtocolContract',
+];
+const PIPELINE_EVIDENCE_API_NAMES = ['OPEN_REFERENCE_EVIDENCE_REGISTRY_V2'];
+const PACKAGE_B_LIVE_EVIDENCE_PROVIDERS = [
+    'business-metrics',
+    'deployment-health',
+    'github-delivery',
+    'linear-jira-work',
+    'posthog-product',
+    'sentry-error',
+];
+const LIVE_EVIDENCE_CONTRACT_KINDS = [
+    'operate-live-evidence-provider-registration',
+    'operate-live-evidence-provider-registry',
+    'operating-live-evidence-consent-record',
+    'operating-connector-checkpoint',
+    'operating-live-evidence-ingestion',
+    'operating-measurement-plan',
+    'operating-measurement-schedule',
+    'operating-measurement-schedule-receipt',
+    'operating-evidence-observation',
+    'operating-outcome-evaluation',
+    'operating-learning-receipt',
+];
+const LANDING_CONTRACT_KINDS = [
+    'landing-plan',
+    'landing-confirmation',
+    'landing-event',
+    'landing-phase-receipt',
+    'landing-receipt',
+    'landing-operation-registry',
+];
+const ROOT_FUNCTION_API_NAMES = new Set([
+    'OperatingLiveEvidenceErrorV2',
+    'assertAcceptedLiveEvidenceBridgeV2',
+    'assertAcceptedLiveEvidenceSourceV2',
+    'assertLiveEvidenceProviderRegistrationV2',
+    'assertLiveEvidenceProviderRegistryV2',
+    'assertOperatingConnectorCheckpointV2',
+    'assertOperatingEvidenceObservationV2',
+    'assertOperatingLearningReceiptV2',
+    'assertOperatingLiveEvidenceConsentRecordV2',
+    'assertOperatingLiveEvidenceIngestionV2',
+    'assertOperatingMeasurementPlanV2',
+    'assertOperatingMeasurementScheduleReceiptV2',
+    'assertOperatingMeasurementScheduleV2',
+    'assertOperatingOutcomeEvaluationV2',
+    'deriveOperatingLiveEvidenceContentDigestV2',
+    'deriveOperatingLiveEvidenceRequestHashV2',
+    'evaluateOperatingOutcomeV2',
+    'reduceOperatingConnectorCheckpointV2',
+    'reduceOperatingMeasurementScheduleV2',
+    'registerLiveEvidenceProviderV2',
+    'LandingContractError',
+    'assertLandingConfirmation',
+    'assertLandingEvent',
+    'assertLandingOperationRegistry',
+    'assertLandingPhaseReceipt',
+    'assertLandingPlan',
+    'assertLandingReceipt',
+    'createLandingEventState',
+    'reduceLandingEvents',
+]);
+/** Node error codes are enum-like tokens; anything else may embed a path this boundary withholds. */
+const SAFE_ERROR_CODE = /^[A-Z][A-Z0-9_]*$/u;
+/**
+ * The identity of a caught error, without the filesystem paths this boundary deliberately
+ * withholds. `ERR_MODULE_NOT_FOUND` alone distinguishes a missing dependency from a changed API.
+ */
+function causeCode(error) {
+    if (!(error instanceof Error))
+        return null;
+    const { code } = error;
+    return typeof code === 'string' && SAFE_ERROR_CODE.test(code) ? code : null;
+}
+function withCauseCode(message, error) {
+    const code = causeCode(error);
+    return code === null ? message : `${message} (${code})`;
+}
+export class PipelinePackageHandoffError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PipelinePackageHandoffError';
+        this.code = code;
+    }
+}
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const HANDOFF_KEYS = [
+    'archiveDigest',
+    'contractCatalogDigest',
+    'packageRoot',
+    'sourceInventoryDigest',
+];
+function failHandoff(code, message, cause) {
+    throw new PipelinePackageHandoffError(code, withCauseCode(message, cause));
+}
+function sha256Bytes(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+function deepFreeze(value) {
+    if (typeof value === 'object' && value !== null) {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}
+function isContained(root, target) {
+    const child = path.relative(root, target);
+    return (child.length > 0 &&
+        child !== '..' &&
+        !child.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(child));
+}
+function assertHandoffInput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package handoff must be one closed object.');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package handoff must be plain JSON data.');
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== 'string') ||
+        JSON.stringify(keys.sort()) !== JSON.stringify(HANDOFF_KEYS)) {
+        failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package handoff must contain exactly the four frozen fields.');
+    }
+    for (const digest of [
+        value.archiveDigest,
+        value.sourceInventoryDigest,
+        value.contractCatalogDigest,
+    ]) {
+        if (typeof digest !== 'string' || !DIGEST_PATTERN.test(digest)) {
+            failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package handoff digest is invalid.');
+        }
+    }
+    if (typeof value.packageRoot !== 'string' || !path.isAbsolute(value.packageRoot)) {
+        failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package handoff root must be absolute.');
+    }
+}
+function assertVerificationOptions(options) {
+    const keys = Reflect.ownKeys(options);
+    if (keys.some((key) => key !== 'archivePath')) {
+        failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package verification options are invalid.');
+    }
+    if (options.archivePath !== undefined &&
+        (typeof options.archivePath !== 'string' || !path.isAbsolute(options.archivePath))) {
+        failHandoff('E_PIPELINE_HANDOFF_INVALID', 'Pipeline package archive path must be absolute.');
+    }
+}
+function realPackageRoot(candidate) {
+    const lexical = path.resolve(candidate);
+    const stat = lstatSync(lexical);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package root is not a real directory.');
+    }
+    const root = realpathSync(lexical);
+    if (root !== lexical) {
+        failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package root traverses a symbolic link.');
+    }
+    return root;
+}
+function packageInventory(root) {
+    const entries = [];
+    const visit = (directory) => {
+        for (const name of readdirSync(directory).sort((left, right) => left.localeCompare(right))) {
+            const absolute = path.join(directory, name);
+            const stat = lstatSync(absolute);
+            if (stat.isSymbolicLink()) {
+                failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package tree contains a symbolic link.');
+            }
+            if (stat.isDirectory()) {
+                visit(absolute);
+                continue;
+            }
+            if (!stat.isFile()) {
+                failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package tree contains a non-regular entry.');
+            }
+            const target = realpathSync(absolute);
+            if (!isContained(root, target)) {
+                failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package entry escapes its root.');
+            }
+            const bytes = readFileSync(target);
+            entries.push({
+                path: path.relative(root, target).split(path.sep).join('/'),
+                mode: (stat.mode & 0o111) === 0 ? 0o644 : 0o755,
+                size: bytes.byteLength,
+                contentDigest: sha256Bytes(bytes),
+            });
+        }
+    };
+    visit(root);
+    entries.sort((left, right) => left.path.localeCompare(right.path));
+    return {
+        digest: sha256CanonicalJson(entries),
+        paths: new Set(entries.map((entry) => entry.path)),
+    };
+}
+function safePackageFile(root, relativePath, inventory) {
+    const portable = relativePath.replaceAll('\\', '/').replace(/^\.\//u, '');
+    const normalized = path.posix.normalize(portable);
+    if (!normalized ||
+        normalized === '..' ||
+        normalized.startsWith('../') ||
+        path.posix.isAbsolute(normalized) ||
+        !inventory.has(normalized)) {
+        failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package asset is outside the frozen inventory.');
+    }
+    const target = realpathSync(path.join(root, ...normalized.split('/')));
+    const stat = lstatSync(target);
+    if (!isContained(root, target) || !stat.isFile() || stat.isSymbolicLink()) {
+        failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package asset is not a contained regular file.');
+    }
+    return target;
+}
+function runtimeExportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const target = runtimeExportTarget(entry);
+            if (target !== null)
+                return target;
+        }
+        return null;
+    }
+    if (!value || typeof value !== 'object')
+        return null;
+    const conditions = value;
+    return runtimeExportTarget(conditions.import) ?? runtimeExportTarget(conditions.default);
+}
+function publicExportPath(root, exportsField, subpath, inventory) {
+    if (!exportsField || typeof exportsField !== 'object' || Array.isArray(exportsField)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline package exports are invalid.');
+    }
+    const exportsRecord = exportsField;
+    let value = exportsRecord[subpath];
+    let capture = null;
+    if (value === undefined) {
+        const matches = Object.keys(exportsRecord)
+            .filter((key) => key.includes('*'))
+            .flatMap((key) => {
+            const star = key.indexOf('*');
+            if (star !== key.lastIndexOf('*'))
+                return [];
+            const prefix = key.slice(0, star);
+            const suffix = key.slice(star + 1);
+            if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix))
+                return [];
+            return [{ key, capture: subpath.slice(prefix.length, subpath.length - suffix.length) }];
+        })
+            .sort((left, right) => right.key.length - left.key.length);
+        const match = matches[0];
+        if (match !== undefined) {
+            value = exportsRecord[match.key];
+            capture = match.capture;
+        }
+    }
+    let target = runtimeExportTarget(value);
+    if (target === null || !target.startsWith('./')) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Required pipeline public export is missing.');
+    }
+    if (capture !== null)
+        target = target.replace('*', capture);
+    if (target.includes('*')) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline public export is ambiguous.');
+    }
+    return safePackageFile(root, target, inventory);
+}
+function parseJsonAsset(pathname) {
+    const parsed = JSON.parse(readFileSync(pathname, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline package JSON asset is invalid.');
+    }
+    return parsed;
+}
+function pickNamedApis(loaded, names, functionNames) {
+    const picked = {};
+    for (const name of names) {
+        if (!(name in loaded) || (functionNames.has(name) && typeof loaded[name] !== 'function')) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Required pipeline public API is missing.');
+        }
+        picked[name] = loaded[name];
+    }
+    return Object.freeze(picked);
+}
+function sameList(actual, expected) {
+    return Array.isArray(actual) && JSON.stringify(actual) === JSON.stringify(expected);
+}
+function assertBaseEvidenceRegistry(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline base-evidence registry is invalid.');
+    }
+    const registry = value;
+    if (registry.protocolVersion !== '2.0.0' ||
+        !Array.isArray(registry.providers) ||
+        !Array.isArray(registry.resolvers)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline base-evidence registry is invalid.');
+    }
+    const artifactProvider = registry.providers.filter((entry) => entry !== null &&
+        typeof entry === 'object' &&
+        !Array.isArray(entry) &&
+        entry.providerId ===
+            'local-operate-artifact-evidence-provider' &&
+        entry.providerVersion === '2.0.0');
+    const artifactResolver = registry.resolvers.filter((entry) => entry !== null &&
+        typeof entry === 'object' &&
+        !Array.isArray(entry) &&
+        entry.resolverId ===
+            'local-operate-artifact-evidence-resolver' &&
+        entry.resolverVersion === '2.0.0' &&
+        Array.isArray(entry.supportedEvidenceKinds) &&
+        entry.supportedEvidenceKinds.includes('operate-artifact'));
+    if (artifactProvider.length !== 1 || artifactResolver.length !== 1) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline base-evidence registry lacks the canonical operate-artifact bridge.');
+    }
+    return deepFreeze(structuredClone(registry));
+}
+function assertLiveEvidenceProviderMembership(providers) {
+    if (!Array.isArray(providers)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline provider registry is invalid.');
+    }
+    if (providers.length === 0)
+        return;
+    const identities = providers.map((entry) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline provider registry is invalid.');
+        }
+        const provider = entry;
+        if (typeof provider.providerId !== 'string' || provider.providerVersion !== '1.0.0') {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline provider registry contains an unsupported identity.');
+        }
+        return provider.providerId;
+    });
+    if (!sameList(identities, PACKAGE_B_LIVE_EVIDENCE_PROVIDERS)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline provider registry is neither Package-A nor the frozen Package-B membership.');
+    }
+}
+async function verifyPipelinePackageHandoffInternal(handoff, options) {
+    assertHandoffInput(handoff);
+    assertVerificationOptions(options);
+    const root = realPackageRoot(handoff.packageRoot);
+    const inventory = packageInventory(root);
+    if (inventory.digest !== handoff.sourceInventoryDigest) {
+        failHandoff('E_PIPELINE_HANDOFF_DIGEST_MISMATCH', 'Pipeline package source inventory digest does not match.');
+    }
+    const manifestPath = safePackageFile(root, 'package.json', inventory.paths);
+    const manifest = parseJsonAsset(manifestPath);
+    if (manifest.name !== 'planr-pipeline') {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline package identity is incompatible.');
+    }
+    const rootEntry = publicExportPath(root, manifest.exports, '.', inventory.paths);
+    const protocolEntry = publicExportPath(root, manifest.exports, './protocol', inventory.paths);
+    const evidenceEntry = publicExportPath(root, manifest.exports, './operate/evidence-v2', inventory.paths);
+    const contractCatalog = safePackageFile(root, 'lib/protocol/generated/contract-catalog-v2.mjs', inventory.paths);
+    if (sha256Bytes(readFileSync(contractCatalog)) !== handoff.contractCatalogDigest) {
+        failHandoff('E_PIPELINE_HANDOFF_DIGEST_MISMATCH', 'Pipeline contract catalog digest does not match.');
+    }
+    let archiveVerification = 'externally-preverified';
+    if (options.archivePath !== undefined) {
+        const lexicalArchive = path.resolve(options.archivePath);
+        const stat = lstatSync(lexicalArchive);
+        if (!stat.isFile() ||
+            stat.isSymbolicLink() ||
+            realpathSync(lexicalArchive) !== lexicalArchive) {
+            failHandoff('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package archive is not a real file.');
+        }
+        if (sha256Bytes(readFileSync(lexicalArchive)) !== handoff.archiveDigest) {
+            failHandoff('E_PIPELINE_HANDOFF_DIGEST_MISMATCH', 'Pipeline package archive digest does not match.');
+        }
+        archiveVerification = 'verified';
+    }
+    let rootModule;
+    let protocolModule;
+    let evidenceModule;
+    try {
+        [rootModule, protocolModule, evidenceModule] = (await Promise.all([
+            import(pathToFileURL(rootEntry).href),
+            import(pathToFileURL(protocolEntry).href),
+            import(pathToFileURL(evidenceEntry).href),
+        ]));
+    }
+    catch (error) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline public exports could not be loaded from verified package bytes.', error);
+    }
+    const rootApi = pickNamedApis(rootModule, PIPELINE_ROOT_API_NAMES, ROOT_FUNCTION_API_NAMES);
+    const protocolApi = pickNamedApis(protocolModule, PIPELINE_PROTOCOL_API_NAMES, new Set([
+        'loadLandingContract',
+        'loadOperateLiveEvidenceContract',
+        'loadOperateRuntimeContract',
+        'loadProtocolContract',
+    ]));
+    const evidenceApi = pickNamedApis(evidenceModule, PIPELINE_EVIDENCE_API_NAMES, new Set());
+    const baseEvidenceRegistry = assertBaseEvidenceRegistry(evidenceApi.OPEN_REFERENCE_EVIDENCE_REGISTRY_V2);
+    if (!sameList(protocolApi.OPERATE_LIVE_EVIDENCE_CONTRACT_KINDS_V2, LIVE_EVIDENCE_CONTRACT_KINDS) ||
+        !sameList(protocolApi.LANDING_CONTRACT_KINDS_V1, LANDING_CONTRACT_KINDS)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline contract families changed.');
+    }
+    const operateContractRegistry = publicExportPath(root, manifest.exports, './registry/operate-v2-contracts.json', inventory.paths);
+    const registry = parseJsonAsset(operateContractRegistry);
+    if (!Array.isArray(registry.contracts)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline contract registry is invalid.');
+    }
+    const registryRows = registry.contracts
+        .map((value) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline contract row is invalid.');
+        }
+        const row = value;
+        if (typeof row.id !== 'string' ||
+            typeof row.schemaPath !== 'string' ||
+            !Number.isInteger(row.runtimeOrder)) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline contract row is invalid.');
+        }
+        return {
+            id: row.id,
+            runtimeOrder: row.runtimeOrder,
+            schemaPath: row.schemaPath,
+        };
+    })
+        .sort((left, right) => left.runtimeOrder - right.runtimeOrder);
+    if (new Set(registryRows.map(({ id }) => id)).size !== registryRows.length ||
+        new Set(registryRows.map(({ runtimeOrder }) => runtimeOrder)).size !== registryRows.length ||
+        !sameList(protocolApi.OPERATE_RUNTIME_CONTRACT_KINDS, registryRows.map(({ id }) => id))) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline runtime catalog is inconsistent.');
+    }
+    const liveRows = registryRows.filter(({ id }) => LIVE_EVIDENCE_CONTRACT_KINDS.includes(id));
+    if (!sameList(liveRows.map(({ id }) => id), LIVE_EVIDENCE_CONTRACT_KINDS) ||
+        liveRows.some(({ runtimeOrder }, index) => runtimeOrder !== 70 + index)) {
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline live-evidence catalog changed.');
+    }
+    const loadLive = protocolApi.loadOperateLiveEvidenceContract;
+    const liveEvidenceSchemas = liveRows.map(({ id, schemaPath }) => {
+        const schemaAsset = publicExportPath(root, manifest.exports, `./${schemaPath}`, inventory.paths);
+        const schema = parseJsonAsset(schemaAsset);
+        const loaded = loadLive(id, { protocolVersion: '2.0.0' });
+        if (loaded.kind !== id ||
+            loaded.protocolVersion !== '2.0.0' ||
+            loaded.schema?.properties?.kind?.const !== id ||
+            schema.properties?.kind?.const !== id) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline live-evidence schema changed.');
+        }
+        return { kind: id, path: schemaAsset };
+    });
+    const loadLanding = protocolApi.loadLandingContract;
+    const landingSchemas = LANDING_CONTRACT_KINDS.map((kind) => {
+        const schemaAsset = publicExportPath(root, manifest.exports, `./schemas/v1.2.0/${kind}.schema.json`, inventory.paths);
+        const loaded = loadLanding(kind, { protocolVersion: '1.2.0' });
+        if (loaded.kind !== kind ||
+            loaded.protocolVersion !== '1.2.0' ||
+            loaded.schema?.properties?.kind?.const !== kind) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline landing schema changed.');
+        }
+        return { kind, path: schemaAsset };
+    });
+    const liveEvidenceProviderRegistry = publicExportPath(root, manifest.exports, './registry/live-evidence-providers.json', inventory.paths);
+    const landingOperationRegistry = publicExportPath(root, manifest.exports, './registry/landing-operations.json', inventory.paths);
+    const liveRegistry = parseJsonAsset(liveEvidenceProviderRegistry);
+    const landingRegistry = parseJsonAsset(landingOperationRegistry);
+    assertLiveEvidenceProviderMembership(liveRegistry.providers);
+    let validatedLiveRegistry;
+    try {
+        const validated = rootApi.assertLiveEvidenceProviderRegistryV2(liveRegistry, {
+            baseEvidenceProviders: baseEvidenceRegistry.providers,
+            baseResolvers: baseEvidenceRegistry.resolvers,
+        });
+        if (!validated || typeof validated !== 'object' || Array.isArray(validated)) {
+            failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline provider registry is invalid.');
+        }
+        validatedLiveRegistry = deepFreeze(structuredClone(validated));
+        rootApi.assertLandingOperationRegistry(landingRegistry);
+    }
+    catch (error) {
+        if (error instanceof PipelinePackageHandoffError)
+            throw error;
+        failHandoff('E_PIPELINE_HANDOFF_INCOMPATIBLE', 'Pipeline registry validation failed.');
+    }
+    return deepFreeze({
+        archiveDigest: handoff.archiveDigest,
+        packageRoot: root,
+        sourceInventoryDigest: handoff.sourceInventoryDigest,
+        contractCatalogDigest: handoff.contractCatalogDigest,
+        archiveVerification,
+        publicEntries: { root: rootEntry, protocol: protocolEntry, evidence: evidenceEntry },
+        rootApi,
+        protocolApi,
+        evidenceApi,
+        registryValues: {
+            liveEvidenceProviderRegistry: validatedLiveRegistry,
+            baseEvidenceRegistry,
+        },
+        assets: {
+            contractCatalog,
+            operateContractRegistry,
+            liveEvidenceProviderRegistry,
+            landingOperationRegistry,
+            liveEvidenceSchemas,
+            landingSchemas,
+        },
+    });
+}
+/**
+ * Verify one explicit Package-A or Package-B custody handoff without consulting
+ * an installed sibling, environment variable, source checkout, or legacy resolver.
+ */
+export async function verifyPipelinePackageHandoff(handoff, options = {}) {
+    try {
+        return await verifyPipelinePackageHandoffInternal(handoff, options);
+    }
+    catch (error) {
+        if (error instanceof PipelinePackageHandoffError)
+            throw error;
+        throw new PipelinePackageHandoffError('E_PIPELINE_HANDOFF_UNSAFE', 'Pipeline package handoff verification failed.');
+    }
+}
+const LANDING_HANDOFF_KEYS = [
+    'archiveDigest',
+    'landingManifestDigest',
+    'packageRoot',
+    'sourceInventoryDigest',
+];
+const LANDING_ROOT_API_NAMES = [
+    'LANDING_OPERATION_REGISTRY_PATH',
+    'LANDING_WORKFLOW_ASSET_PATHS',
+    'LANDING_WORKFLOW_CATALOG_PATH',
+    'LANDING_WORKFLOW_ID',
+    'LANDING_WORKFLOW_MANIFEST_PATH',
+    'advanceLanding',
+    'assertCurrentShipClosureForLanding',
+    'assertLandingOperationRegistry',
+    'assertLandingWorkflowCatalog',
+    'assertLandingWorkflowManifest',
+    'bindLandingPlan',
+    'createLandingOwnerRuntimeHost',
+    'inspectShipClosureForLanding',
+    'landingStatus',
+    'prepareLanding',
+    'previewLandingDocket',
+    'readLandingOperationRegistry',
+    'readLandingWorkflowCatalog',
+    'readLandingWorkflowManifest',
+    'showLanding',
+];
+const LANDING_ROOT_FUNCTION_NAMES = new Set([
+    'advanceLanding',
+    'assertCurrentShipClosureForLanding',
+    'assertLandingOperationRegistry',
+    'assertLandingWorkflowCatalog',
+    'assertLandingWorkflowManifest',
+    'bindLandingPlan',
+    'createLandingOwnerRuntimeHost',
+    'inspectShipClosureForLanding',
+    'landingStatus',
+    'prepareLanding',
+    'previewLandingDocket',
+    'readLandingOperationRegistry',
+    'readLandingWorkflowCatalog',
+    'readLandingWorkflowManifest',
+    'showLanding',
+]);
+const LANDING_PRIVATE_ROOT_EXPORTS = [
+    'createLandingTrustedRuntimeHost',
+    'issueLandingOwnerConfirmation',
+    'createLandingEvent',
+    'createLandingPhaseReceipt',
+    'createLandingReceipt',
+];
+export class LandingPackageHandoffError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'LandingPackageHandoffError';
+        this.code = code;
+    }
+}
+function failLandingHandoff(code, message, cause) {
+    throw new LandingPackageHandoffError(code, withCauseCode(message, cause));
+}
+function assertLandingHandoffInput(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing package handoff is invalid.');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing package handoff must be plain data.');
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.some((key) => typeof key !== 'string') ||
+        JSON.stringify(keys.sort()) !== JSON.stringify(LANDING_HANDOFF_KEYS)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing package handoff must contain exactly the four frozen fields.');
+    }
+    for (const digest of [
+        value.archiveDigest,
+        value.sourceInventoryDigest,
+        value.landingManifestDigest,
+    ]) {
+        if (typeof digest !== 'string' || !DIGEST_PATTERN.test(digest)) {
+            failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing handoff digest is invalid.');
+        }
+    }
+    if (typeof value.packageRoot !== 'string' || !path.isAbsolute(value.packageRoot)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing package root must be absolute.');
+    }
+}
+function assertLandingVerificationOptions(options) {
+    const keys = Reflect.ownKeys(options);
+    if (keys.some((key) => key !== 'archivePath')) {
+        failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing verification options are invalid.');
+    }
+    if (options.archivePath !== undefined &&
+        (typeof options.archivePath !== 'string' || !path.isAbsolute(options.archivePath))) {
+        failLandingHandoff('E_LANDING_HANDOFF_INVALID', 'Landing archive path must be absolute.');
+    }
+}
+function assertExactLandingWorkflow(catalog) {
+    const workflow = catalog.workflow;
+    const commands = workflow?.commands;
+    const hostAssets = workflow?.hostAssets;
+    if (catalog.kind !== 'landing-workflow-catalog' ||
+        catalog.schemaVersion !== '1.0.0' ||
+        catalog.protocolVersion !== '1.2.0' ||
+        catalog.authority !== 'none' ||
+        workflow?.workflowId !== 'planr-land' ||
+        workflow.authorityBoundary !== 'portable-json-is-not-effect-authority' ||
+        !Array.isArray(commands) ||
+        !Array.isArray(hostAssets)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing workflow catalog changed.');
+    }
+    const commandTruth = commands.map(({ id, access, effect, agentCallable, machineJson, requiresTty }) => ({
+        id,
+        access,
+        effect,
+        agentCallable,
+        machineJson,
+        requiresTty,
+    }));
+    const expectedCommandTruth = [
+        {
+            id: 'prepare',
+            access: 'read-only',
+            effect: 'none',
+            agentCallable: true,
+            machineJson: true,
+            requiresTty: false,
+        },
+        {
+            id: 'show',
+            access: 'read-only',
+            effect: 'none',
+            agentCallable: true,
+            machineJson: true,
+            requiresTty: false,
+        },
+        {
+            id: 'status',
+            access: 'read-only',
+            effect: 'none',
+            agentCallable: true,
+            machineJson: true,
+            requiresTty: false,
+        },
+        {
+            id: 'advance',
+            access: 'owner-interactive',
+            effect: 'runtime-dispatch',
+            agentCallable: false,
+            machineJson: false,
+            requiresTty: true,
+        },
+    ];
+    const exactHosts = [
+        'skills/planr-land/SKILL.md',
+        'adapters/codex/skills/planr-land/SKILL.md',
+        'adapters/cursor/rules/openplanr-land.mdc',
+    ];
+    if (JSON.stringify(commandTruth) !== JSON.stringify(expectedCommandTruth) ||
+        JSON.stringify(hostAssets.map(({ path: assetPath }) => assetPath)) !==
+            JSON.stringify(exactHosts)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing workflow authority changed.');
+    }
+}
+async function verifyLandingPackageHandoffInternal(handoff, options) {
+    assertLandingHandoffInput(handoff);
+    assertLandingVerificationOptions(options);
+    const root = realPackageRoot(handoff.packageRoot);
+    const inventory = packageInventory(root);
+    if (inventory.digest !== handoff.sourceInventoryDigest) {
+        failLandingHandoff('E_LANDING_HANDOFF_DIGEST_MISMATCH', 'Landing package source inventory digest does not match.');
+    }
+    const packageManifest = parseJsonAsset(safePackageFile(root, 'package.json', inventory.paths));
+    if (packageManifest.name !== 'planr-pipeline') {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing package identity changed.');
+    }
+    const workflowManifest = safePackageFile(root, 'conformance/fixtures/landing-workflow/generated-assets.json', inventory.paths);
+    if (sha256Bytes(readFileSync(workflowManifest)) !== handoff.landingManifestDigest) {
+        failLandingHandoff('E_LANDING_HANDOFF_DIGEST_MISMATCH', 'Landing workflow manifest digest does not match.');
+    }
+    const publicEntry = publicExportPath(root, packageManifest.exports, '.', inventory.paths);
+    let loaded;
+    try {
+        loaded = (await import(pathToFileURL(publicEntry).href));
+    }
+    catch (error) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing public API is unavailable.', error);
+    }
+    for (const name of LANDING_PRIVATE_ROOT_EXPORTS) {
+        if (Object.hasOwn(loaded, name)) {
+            failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing private authority escaped.');
+        }
+    }
+    const landingApi = pickNamedApis(loaded, LANDING_ROOT_API_NAMES, LANDING_ROOT_FUNCTION_NAMES);
+    if (landingApi.LANDING_WORKFLOW_ID !== 'planr-land' ||
+        landingApi.LANDING_WORKFLOW_CATALOG_PATH !== 'registry/landing-workflows.json' ||
+        landingApi.LANDING_OPERATION_REGISTRY_PATH !== 'registry/landing-operations.json' ||
+        landingApi.LANDING_WORKFLOW_MANIFEST_PATH !==
+            'conformance/fixtures/landing-workflow/generated-assets.json' ||
+        !Array.isArray(landingApi.LANDING_WORKFLOW_ASSET_PATHS)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing public identity changed.');
+    }
+    const workflowAssetPaths = landingApi.LANDING_WORKFLOW_ASSET_PATHS;
+    const workflowCatalog = safePackageFile(root, 'registry/landing-workflows.json', inventory.paths);
+    const operationRegistry = safePackageFile(root, 'registry/landing-operations.json', inventory.paths);
+    const workflowSchema = safePackageFile(root, 'schemas/v1.2.0/landing-workflow-catalog.schema.json', inventory.paths);
+    const catalogValue = parseJsonAsset(workflowCatalog);
+    const operationValue = parseJsonAsset(operationRegistry);
+    const manifestValue = parseJsonAsset(workflowManifest);
+    let validatedCatalog;
+    let validatedRegistry;
+    let validatedManifest;
+    try {
+        validatedCatalog = landingApi.assertLandingWorkflowCatalog(catalogValue);
+        validatedRegistry = landingApi.assertLandingOperationRegistry(operationValue);
+        validatedManifest = landingApi.assertLandingWorkflowManifest(manifestValue, { verifyFiles: false });
+    }
+    catch (error) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing assets are invalid.', error);
+    }
+    assertExactLandingWorkflow(validatedCatalog);
+    const manifestAssets = validatedManifest.assets;
+    if (!Array.isArray(manifestAssets) ||
+        JSON.stringify(manifestAssets.map(({ path: assetPath }) => assetPath)) !==
+            JSON.stringify(workflowAssetPaths)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing asset membership changed.');
+    }
+    for (const asset of manifestAssets) {
+        if (typeof asset.path !== 'string' ||
+            typeof asset.digest !== 'string' ||
+            sha256Bytes(readFileSync(safePackageFile(root, asset.path, inventory.paths))) !== asset.digest) {
+            failLandingHandoff('E_LANDING_HANDOFF_DIGEST_MISMATCH', 'Landing asset digest changed.');
+        }
+    }
+    const readCatalog = landingApi.readLandingWorkflowCatalog();
+    const readRegistry = landingApi.readLandingOperationRegistry();
+    const readManifest = landingApi.readLandingWorkflowManifest({ verifyFiles: false });
+    if (sha256CanonicalJson(readCatalog) !== sha256CanonicalJson(validatedCatalog) ||
+        sha256CanonicalJson(readRegistry) !== sha256CanonicalJson(validatedRegistry) ||
+        sha256CanonicalJson(readManifest) !== sha256CanonicalJson(validatedManifest)) {
+        failLandingHandoff('E_LANDING_HANDOFF_INCOMPATIBLE', 'Landing public readers changed.');
+    }
+    let archiveVerification = 'externally-preverified';
+    if (options.archivePath !== undefined) {
+        const archive = path.resolve(options.archivePath);
+        const stat = lstatSync(archive);
+        if (!stat.isFile() || stat.isSymbolicLink() || realpathSync(archive) !== archive) {
+            failLandingHandoff('E_LANDING_HANDOFF_UNSAFE', 'Landing archive is not a real file.');
+        }
+        if (sha256Bytes(readFileSync(archive)) !== handoff.archiveDigest) {
+            failLandingHandoff('E_LANDING_HANDOFF_DIGEST_MISMATCH', 'Landing archive digest changed.');
+        }
+        archiveVerification = 'verified';
+    }
+    // Protocol 1.2 keeps the historical host-asset references readable, but the
+    // public pipeline tarball is deliberately prompt-free under Protocol 1.8.
+    // Host-native Plan/Land skills are distributed by their owning plugin.
+    const hostAssets = [];
+    return deepFreeze({
+        archiveDigest: handoff.archiveDigest,
+        packageRoot: root,
+        sourceInventoryDigest: handoff.sourceInventoryDigest,
+        landingManifestDigest: handoff.landingManifestDigest,
+        archiveVerification,
+        publicEntry,
+        landingApi,
+        registryValues: {
+            operationRegistry: structuredClone(validatedRegistry),
+            workflowCatalog: structuredClone(validatedCatalog),
+            workflowManifest: structuredClone(validatedManifest),
+        },
+        assets: {
+            operationRegistry,
+            workflowCatalog,
+            workflowManifest,
+            workflowSchema,
+            landingModule: safePackageFile(root, 'lib/pipeline/landing.mjs', inventory.paths),
+            landingTypes: safePackageFile(root, 'lib/pipeline/landing.d.mts', inventory.paths),
+            hostAssets,
+        },
+    });
+}
+/** Verify one explicit, content-bound landing Package-B handoff. */
+export async function verifyLandingPackageHandoff(handoff, options = {}) {
+    try {
+        return await verifyLandingPackageHandoffInternal(handoff, options);
+    }
+    catch (error) {
+        if (error instanceof LandingPackageHandoffError)
+            throw error;
+        if (error instanceof PipelinePackageHandoffError) {
+            const code = error.code.replace('E_PIPELINE_', 'E_LANDING_');
+            throw new LandingPackageHandoffError(code, error.message);
+        }
+        throw new LandingPackageHandoffError('E_LANDING_HANDOFF_UNSAFE', 'Landing package handoff verification failed.');
+    }
+}
 function candidateRoots() {
-    const here = path.dirname(fileURLToPath(import.meta.url));
-    const roots = [process.env.OPENPLANR_PIPELINE_ROOT].filter((value) => Boolean(value));
+    const roots = [];
     try {
-        const entry = require.resolve('planr-pipeline');
-        roots.push(path.resolve(path.dirname(entry), '../..'));
+        const packageManifest = require.resolve('planr-pipeline/package.json');
+        roots.push(path.dirname(packageManifest));
     }
     catch {
         // Optional dependency may be omitted by the minimal installer.
     }
-    roots.push(path.resolve(here, '../../../planr-pipeline'), path.resolve(process.cwd(), '../planr-pipeline'));
     return [...new Set(roots.map((root) => path.resolve(root)))];
 }
 export function resolvePipelinePackage(required = true) {