@aopslabs/aops 0.2.0

package/dist/lib/community-native-lifecycle.js

@@ -0,0 +1,2458 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseEnv } from 'node:util';
+import { COMMUNITY_NATIVE_CHILD_PROTOCOL, COMMUNITY_NATIVE_CONTROL_PROTOCOL, } from './community-native-child.js';
+import { resolveCommunityInstallPaths } from './community-lifecycle.js';
+import { COMMUNITY_NATIVE_POSTGRES_CONTRACT_PATH, assertCommunityNativePostgresInstanceState, assertCommunityNativePostgresState, buildCommunityNativePostgresUrl, setupCommunityNativePostgres, startCommunityNativePostgres, stopCommunityNativePostgres, } from './community-native-postgres.js';
+import { COMMUNITY_NATIVE_MIGRATION_POLICY_PATH, assertCommunityNativeMigrationReceiptV1, planCommunityNativeMigration, runCommunityNativeMigration, } from './community-native-migration.js';
+import { createCommunityExternalSnapshotAttestationV1, writeCommunityExternalSnapshotAttestationV1, } from './community-migration-snapshot.js';
+import { createCommunityNativeApplicationReferenceV1, readCommunityNativeApplicationUpdate, sameCommunityNativeApplicationContent, writeCommunityNativeApplicationRollbackOutcome, writeCommunityNativeApplicationRollbackPrepared, writeCommunityNativeApplicationUpdateOutcome, writeCommunityNativeApplicationUpdatePrepared, } from './community-native-application-recovery.js';
+const PUBLIC_ROOT_NAME = 'aops-community-distribution';
+const PUBLIC_SERVER_PACKAGE_NAME = '@aopslabs/aops-server';
+const PUBLIC_PACKAGE_MANAGER = /^pnpm@(11\.[0-9]+\.[0-9]+)$/;
+const RELEASE_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?(?:\+[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/;
+const INSTANCE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const RAW_SHA256 = /^[a-f0-9]{64}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const MAX_CONFIG_BYTES = 65_536;
+const MAX_TLS_ROOT_CERT_BYTES = 1_048_576;
+const MIN_EXACT_SECRET_REDACTION_LENGTH = 8;
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const DEFAULT_STOP_TIMEOUT_MS = 15_000;
+const READY_POLL_MS = 250;
+const MAX_LOG_TAIL_BYTES = 4 * 1024 * 1024;
+const MAX_INVENTORY_FILES = 50_000;
+const MAX_INVENTORY_BYTES = 2 * 1024 * 1024 * 1024;
+const SOURCE_INVENTORY_EXCLUDED_DIRECTORIES = new Set([
+    '.aops', '.git', '.pnpm-store', '.svelte-kit', '.turbo', 'build', 'coverage', 'dist', 'node_modules',
+]);
+const RUNTIME_INVENTORY_EXCLUDED_DIRECTORIES = new Set([
+    '.aops', '.git', '.pnpm-store', '.svelte-kit', '.turbo', 'coverage', 'node_modules',
+]);
+const CHECKOUT_REQUIRED_SOURCE_PATHS = Object.freeze([
+    'apps/aops-cli/package.json',
+    'apps/aops-cockpit-v2/package.json',
+    'apps/aops-server/package.json',
+    'apps/aops-server/scripts/community-host.mjs',
+    COMMUNITY_NATIVE_MIGRATION_POLICY_PATH,
+    COMMUNITY_NATIVE_POSTGRES_CONTRACT_PATH,
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+]);
+const CHECKOUT_BUILD_PATHS = Object.freeze({
+    hostEntry: 'apps/aops-server/scripts/community-host.mjs',
+    handlerEntry: 'apps/aops-server/build/handler.js',
+    cockpitIndex: 'apps/aops-cockpit-v2/dist/index.html',
+});
+const PACKAGE_REQUIRED_SOURCE_PATHS = Object.freeze([
+    'community-postgres.json',
+    'package.json',
+    'runtime/agentspace-host-adapter.mjs',
+    'runtime/agentspace-tooling.mjs',
+    'runtime/docman-host-adapter.mjs',
+    'runtime/docman-policy.mjs',
+    'runtime/docman-tooling.mjs',
+    'runtime/projectman-host-adapter.mjs',
+    'runtime/scope-context.mjs',
+    'scripts/community-host.mjs',
+    'scripts/community-migration-policy-package-v1.json',
+]);
+const PACKAGE_BUILD_PATHS = Object.freeze({
+    hostEntry: 'scripts/community-host.mjs',
+    handlerEntry: 'build/handler.js',
+    cockpitIndex: 'cockpit/index.html',
+});
+function sha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+function throwIfNativeAborted(signal) {
+    if (signal?.aborted)
+        throw new Error('community_operation_aborted');
+}
+function hashFile(filePath) {
+    const stats = lstatSync(filePath);
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error(`community_native_required_file_invalid:${path.basename(filePath)}`);
+    }
+    return sha256(readFileSync(filePath));
+}
+function isWithin(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function safeRegularFile(root, relativePath) {
+    const candidate = path.resolve(root, relativePath);
+    if (!isWithin(root, candidate))
+        throw new Error(`community_native_source_path_escape:${relativePath}`);
+    let stats;
+    try {
+        stats = lstatSync(candidate);
+    }
+    catch {
+        throw new Error(`community_native_source_file_missing:${relativePath}`);
+    }
+    if (!stats.isFile() || stats.isSymbolicLink()) {
+        throw new Error(`community_native_source_file_invalid:${relativePath}`);
+    }
+    const realRoot = realpathSync(root);
+    const realCandidate = realpathSync(candidate);
+    if (!isWithin(realRoot, realCandidate))
+        throw new Error(`community_native_source_realpath_escape:${relativePath}`);
+    return realCandidate;
+}
+function codepointCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function inventoryCommunityNativeTree(root, excludedDirectories) {
+    const canonicalRoot = realpathSync(root);
+    const records = [];
+    let byteLength = 0;
+    const visit = (directory, prefix) => {
+        const directoryStats = lstatSync(directory);
+        if (!directoryStats.isDirectory() || directoryStats.isSymbolicLink() || realpathSync(directory) !== directory) {
+            throw new Error(`community_native_inventory_directory_unsafe:${prefix || '.'}`);
+        }
+        for (const entry of readdirSync(directory, { withFileTypes: true }).sort((left, right) => codepointCompare(left.name, right.name))) {
+            if (entry.isDirectory() && excludedDirectories.has(entry.name))
+                continue;
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const absolutePath = path.join(directory, entry.name);
+            const stats = lstatSync(absolutePath);
+            if (stats.isSymbolicLink())
+                throw new Error(`community_native_inventory_link_forbidden:${relativePath}`);
+            if (stats.isDirectory()) {
+                visit(absolutePath, relativePath);
+                continue;
+            }
+            if (!stats.isFile() || stats.size < 0) {
+                throw new Error(`community_native_inventory_entry_invalid:${relativePath}`);
+            }
+            const canonicalFile = realpathSync(absolutePath);
+            if (!isWithin(canonicalRoot, canonicalFile)) {
+                throw new Error(`community_native_inventory_path_escape:${relativePath}`);
+            }
+            const content = readFileSync(canonicalFile);
+            byteLength += content.byteLength;
+            records.push({ path: relativePath.replace(/\\/g, '/'), byteLength: content.byteLength, sha256: sha256(content) });
+            if (records.length > MAX_INVENTORY_FILES || byteLength > MAX_INVENTORY_BYTES) {
+                throw new Error('community_native_inventory_bounds_exceeded');
+            }
+        }
+    };
+    visit(canonicalRoot, '');
+    return Object.freeze({
+        fileCount: records.length,
+        byteLength,
+        sha256: sha256(JSON.stringify(records)),
+    });
+}
+function atomicTextWrite(targetPath, content) {
+    const parent = path.dirname(targetPath);
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const tempPath = path.join(parent, `.${path.basename(targetPath)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(tempPath, 'wx', 0o600);
+        writeFileSync(descriptor, content, { encoding: 'utf8' });
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        renameSync(tempPath, targetPath);
+        fsyncDirectoryBestEffortOnWindows(parent);
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        rmSync(tempPath, { force: true });
+    }
+}
+function atomicJsonWrite(targetPath, value) {
+    atomicTextWrite(targetPath, `${JSON.stringify(value, null, 2)}\n`);
+}
+function fsyncDirectoryBestEffortOnWindows(directory) {
+    let descriptor;
+    try {
+        descriptor = openSync(directory, 'r');
+        fsyncSync(descriptor);
+    }
+    catch (error) {
+        const code = error.code;
+        if (process.platform !== 'win32' || !['EACCES', 'EBADF', 'EINVAL', 'EISDIR', 'EPERM'].includes(String(code))) {
+            throw error;
+        }
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function readJson(targetPath, code) {
+    try {
+        return JSON.parse(readFileSync(targetPath, 'utf8'));
+    }
+    catch {
+        throw new Error(code);
+    }
+}
+function exactKeys(input, expected, code) {
+    const actual = Object.keys(input).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+        throw new Error(code);
+    }
+}
+function validPort(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 1 && Number(value) <= 65_535;
+}
+export function resolveCommunityNativeCockpitPort(serverPort) {
+    if (!validPort(serverPort))
+        throw new Error('community_native_server_port_invalid');
+    const candidate = serverPort <= 65_513 ? serverPort + 22 : serverPort - 22;
+    if (!validPort(candidate) || candidate === serverPort) {
+        throw new Error('community_native_cockpit_port_invalid');
+    }
+    return candidate;
+}
+export function resolveCommunityNativePaths(input = {}) {
+    const ociPaths = resolveCommunityInstallPaths(input);
+    return {
+        dataRoot: ociPaths.dataRoot,
+        instanceRoot: ociPaths.instanceRoot,
+        runtimeRoot: ociPaths.runtimeRoot,
+        statePath: path.join(ociPaths.runtimeRoot, 'native-state.json'),
+        processPath: path.join(ociPaths.runtimeRoot, 'native-process.json'),
+        identityPath: path.join(ociPaths.runtimeRoot, 'native-identity.json'),
+        controlPath: path.join(ociPaths.runtimeRoot, 'native-control.json'),
+        secretPath: path.join(ociPaths.runtimeRoot, 'native-secrets.env'),
+        migrationReceiptPath: path.join(ociPaths.runtimeRoot, 'native-migration-receipt.json'),
+        migrationEvidenceRoot: path.join(ociPaths.runtimeRoot, 'native-migration-evidence'),
+        applicationUpdateRoot: path.join(ociPaths.runtimeRoot, 'native-application-updates'),
+        databaseRestoreRoot: path.join(ociPaths.runtimeRoot, 'native-database-restores'),
+        backupRoot: ociPaths.backupRoot,
+        logRoot: path.join(ociPaths.instanceRoot, 'logs'),
+        logPath: path.join(ociPaths.instanceRoot, 'logs', 'native-server.log'),
+        ociStatePath: ociPaths.statePath,
+    };
+}
+function resolveLegacyCommunityNativeMigrationPaths(paths) {
+    return {
+        intentPath: path.join(paths.runtimeRoot, 'native-migration-intent.json'),
+        receiptRoot: path.join(paths.runtimeRoot, 'native-migration-receipts'),
+    };
+}
+function samePhysicalPath(left, right) {
+    return path.relative(path.resolve(left), path.resolve(right)) === '' &&
+        path.relative(path.resolve(right), path.resolve(left)) === '';
+}
+function assertPlainCanonicalDirectory(candidate, code) {
+    const stats = lstatSync(candidate);
+    if (!stats.isDirectory() || stats.isSymbolicLink() || !samePhysicalPath(realpathSync.native(candidate), candidate)) {
+        throw new Error(code);
+    }
+}
+function assertPlainCanonicalFile(candidate, expectedParent, code) {
+    const stats = lstatSync(candidate);
+    if (!stats.isFile() || stats.isSymbolicLink() || !samePhysicalPath(realpathSync.native(candidate), candidate) ||
+        !samePhysicalPath(path.dirname(candidate), expectedParent)) {
+        throw new Error(code);
+    }
+}
+function captureCommunityNativeLocalFile(targetPath, expectedParent) {
+    if (!existsSync(targetPath))
+        return { targetPath, content: null };
+    assertPlainCanonicalFile(targetPath, expectedParent, 'community_native_runtime_file_unsafe');
+    return { targetPath, content: readFileSync(targetPath, 'utf8') };
+}
+function captureCommunityNativeSetupFiles(paths) {
+    return [
+        paths.statePath,
+        paths.migrationReceiptPath,
+        paths.processPath,
+        paths.identityPath,
+        paths.controlPath,
+    ].map((targetPath) => captureCommunityNativeLocalFile(targetPath, paths.runtimeRoot));
+}
+function restoreCommunityNativeLocalFile(snapshot, expectedParent) {
+    if (snapshot.content === null) {
+        if (!existsSync(snapshot.targetPath))
+            return;
+        assertPlainCanonicalFile(snapshot.targetPath, expectedParent, 'community_native_runtime_file_unsafe');
+        rmSync(snapshot.targetPath, { force: true });
+        fsyncDirectoryBestEffortOnWindows(expectedParent);
+        return;
+    }
+    if (existsSync(snapshot.targetPath)) {
+        assertPlainCanonicalFile(snapshot.targetPath, expectedParent, 'community_native_runtime_file_unsafe');
+    }
+    atomicTextWrite(snapshot.targetPath, snapshot.content);
+}
+function restoreCommunityNativeSetupFiles(paths, snapshots) {
+    for (const snapshot of snapshots)
+        restoreCommunityNativeLocalFile(snapshot, paths.runtimeRoot);
+}
+function removeNewCommunityNativeSecret(paths) {
+    if (!existsSync(paths.secretPath))
+        return;
+    assertPlainCanonicalFile(paths.secretPath, paths.runtimeRoot, 'community_native_runtime_file_unsafe');
+    rmSync(paths.secretPath, { force: true });
+    fsyncDirectoryBestEffortOnWindows(paths.runtimeRoot);
+}
+function removeCommunityNativeLaunchArtifactsForRefresh(paths) {
+    for (const targetPath of [paths.processPath, paths.identityPath, paths.controlPath]) {
+        if (!existsSync(targetPath))
+            continue;
+        assertPlainCanonicalFile(targetPath, paths.runtimeRoot, 'community_native_runtime_file_unsafe');
+        rmSync(targetPath, { force: true });
+    }
+    fsyncDirectoryBestEffortOnWindows(paths.runtimeRoot);
+}
+export function assertCommunityNativePathLayout(paths, options = {}) {
+    const legacyMigration = resolveLegacyCommunityNativeMigrationPaths(paths);
+    const instanceExists = existsSync(paths.instanceRoot);
+    if (!instanceExists) {
+        if (options.requireInstanceRoot === true)
+            throw new Error('community_native_instance_root_missing');
+        return;
+    }
+    assertPlainCanonicalDirectory(paths.instanceRoot, 'community_native_instance_root_unsafe');
+    if (existsSync(paths.runtimeRoot)) {
+        if (!samePhysicalPath(path.dirname(paths.runtimeRoot), paths.instanceRoot)) {
+            throw new Error('community_native_runtime_root_unsafe');
+        }
+        assertPlainCanonicalDirectory(paths.runtimeRoot, 'community_native_runtime_root_unsafe');
+    }
+    if (existsSync(paths.logRoot)) {
+        if (!samePhysicalPath(path.dirname(paths.logRoot), paths.instanceRoot)) {
+            throw new Error('community_native_log_root_unsafe');
+        }
+        assertPlainCanonicalDirectory(paths.logRoot, 'community_native_log_root_unsafe');
+    }
+    for (const [candidate, code, expectedParent] of [
+        [legacyMigration.receiptRoot, 'community_native_migration_receipt_root_unsafe', paths.runtimeRoot],
+        [paths.migrationEvidenceRoot, 'community_native_migration_evidence_root_unsafe', paths.runtimeRoot],
+        [paths.applicationUpdateRoot, 'community_native_application_update_root_unsafe', paths.runtimeRoot],
+        [paths.databaseRestoreRoot, 'community_native_database_restore_root_unsafe', paths.runtimeRoot],
+        [paths.backupRoot, 'community_native_backup_root_unsafe', paths.instanceRoot],
+    ]) {
+        if (existsSync(candidate)) {
+            if (!samePhysicalPath(path.dirname(candidate), expectedParent))
+                throw new Error(code);
+            assertPlainCanonicalDirectory(candidate, code);
+        }
+    }
+    for (const candidate of [
+        paths.statePath,
+        paths.processPath,
+        paths.identityPath,
+        paths.controlPath,
+        paths.secretPath,
+        paths.migrationReceiptPath,
+        legacyMigration.intentPath,
+    ]) {
+        if (existsSync(candidate)) {
+            if (!existsSync(paths.runtimeRoot))
+                throw new Error('community_native_runtime_root_unsafe');
+            assertPlainCanonicalFile(candidate, paths.runtimeRoot, 'community_native_runtime_file_unsafe');
+        }
+    }
+    const postgresSecretPath = path.join(paths.runtimeRoot, 'native-postgres.env');
+    if (existsSync(postgresSecretPath)) {
+        if (!existsSync(paths.runtimeRoot))
+            throw new Error('community_native_runtime_root_unsafe');
+        assertPlainCanonicalFile(postgresSecretPath, paths.runtimeRoot, 'community_native_postgres_secret_invalid');
+    }
+    if (existsSync(paths.logPath)) {
+        if (!existsSync(paths.logRoot))
+            throw new Error('community_native_log_root_unsafe');
+        assertPlainCanonicalFile(paths.logPath, paths.logRoot, 'community_native_log_file_invalid');
+    }
+    if (existsSync(paths.ociStatePath)) {
+        assertPlainCanonicalFile(paths.ociStatePath, paths.instanceRoot, 'community_native_oci_state_unsafe');
+    }
+    assertLegacyCommunityNativeMigrationArtifactsSafe(paths);
+}
+function parseNativeState(value, paths) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('community_native_state_invalid');
+    const input = value;
+    const requiredStateKeys = [
+        'schemaVersion', 'runtime', 'instanceName', 'installId', 'profile', 'createdAt', 'updatedAt',
+        'source', 'build', 'postgres', 'server',
+    ];
+    const stateKeys = Object.keys(input);
+    if (requiredStateKeys.some((key) => !stateKeys.includes(key)) ||
+        stateKeys.some((key) => !requiredStateKeys.includes(key) && key !== 'cockpit'))
+        throw new Error('community_native_state_schema_invalid');
+    if (input.schemaVersion !== 1 || input.runtime !== 'native' ||
+        !['native-external-postgres', 'native-container-postgres'].includes(String(input.profile)) ||
+        !INSTANCE_NAME.test(String(input.instanceName)) ||
+        !UUID.test(String(input.installId)) || Number.isNaN(Date.parse(String(input.createdAt))) ||
+        Number.isNaN(Date.parse(String(input.updatedAt))))
+        throw new Error('community_native_state_schema_invalid');
+    exactKeys(input.source, [
+        'root', 'packageManager', 'releaseVersion', 'packageSha256', 'lockfileSha256',
+        'sourceFileCount', 'sourceInventorySha256', 'sourceFingerprint',
+    ], 'community_native_state_source_invalid');
+    exactKeys(input.build, [
+        'completedAt', 'hostEntry', 'handlerEntry', 'cockpitIndex', 'hostEntrySha256',
+        'handlerEntrySha256', 'cockpitIndexSha256', 'runtimeFileCount', 'runtimeInventorySha256',
+        'buildFingerprint',
+    ], 'community_native_state_build_invalid');
+    const serverKeys = Object.keys(input.server ?? {});
+    if (!['host', 'port'].every((key) => serverKeys.includes(key)) ||
+        serverKeys.some((key) => !['host', 'port', 'exposure', 'publicPort', 'authProvider'].includes(key)))
+        throw new Error('community_native_state_server_invalid');
+    const exposure = input.server.exposure ?? 'loopback';
+    const publicPort = input.server.publicPort ?? input.server.port;
+    const cockpit = input.cockpit ?? {
+        host: '127.0.0.1',
+        port: resolveCommunityNativeCockpitPort(publicPort),
+    };
+    const authProvider = input.server.authProvider ?? 'trusted-local';
+    const expectedHost = exposure === 'authenticated-network' ? '0.0.0.0' : '127.0.0.1';
+    if (!path.isAbsolute(input.source.root) || !PUBLIC_PACKAGE_MANAGER.test(input.source.packageManager) ||
+        !RELEASE_VERSION.test(String(input.source.releaseVersion)) ||
+        !Number.isSafeInteger(input.source.sourceFileCount) || input.source.sourceFileCount < 1 ||
+        ![input.source.packageSha256, input.source.lockfileSha256, input.source.sourceInventorySha256,
+            input.source.sourceFingerprint].every((item) => SHA256.test(String(item))) ||
+        Number.isNaN(Date.parse(String(input.build.completedAt))) ||
+        ![input.build.hostEntry, input.build.handlerEntry, input.build.cockpitIndex].every((item) => path.isAbsolute(String(item))) ||
+        !Number.isSafeInteger(input.build.runtimeFileCount) || input.build.runtimeFileCount < 1 ||
+        ![input.build.hostEntrySha256, input.build.handlerEntrySha256, input.build.cockpitIndexSha256,
+            input.build.runtimeInventorySha256, input.build.buildFingerprint]
+            .every((item) => SHA256.test(String(item))) ||
+        input.server.host !== expectedHost || !validPort(input.server.port) ||
+        !['loopback', 'authenticated-network', 'container'].includes(exposure) ||
+        !['trusted-local', 'authv2-jwt-session'].includes(authProvider) || !validPort(publicPort) ||
+        (exposure === 'container' && input.server.port !== 5900) ||
+        (exposure !== 'container' && publicPort !== input.server.port) ||
+        (exposure === 'authenticated-network' && authProvider !== 'authv2-jwt-session') ||
+        (exposure === 'container' && authProvider !== 'trusted-local') ||
+        !cockpit || typeof cockpit !== 'object' || Array.isArray(cockpit) ||
+        Object.keys(cockpit).sort().join(',') !== 'host,port' ||
+        cockpit.host !== '127.0.0.1' || !validPort(cockpit.port) || cockpit.port === publicPort)
+        throw new Error('community_native_state_schema_invalid');
+    const buildPathMatchesKnownLayout = [CHECKOUT_BUILD_PATHS, PACKAGE_BUILD_PATHS].some((buildPaths) => samePhysicalPath(input.build.hostEntry, path.join(input.source.root, buildPaths.hostEntry)) &&
+        samePhysicalPath(input.build.handlerEntry, path.join(input.source.root, buildPaths.handlerEntry)) &&
+        samePhysicalPath(input.build.cockpitIndex, path.join(input.source.root, buildPaths.cockpitIndex)));
+    if (!buildPathMatchesKnownLayout)
+        throw new Error('community_native_state_build_path_mismatch');
+    if (input.profile === 'native-external-postgres') {
+        exactKeys(input.postgres, ['mode', 'configRef', 'tlsPolicy'], 'community_native_state_postgres_invalid');
+        if (input.postgres.mode !== 'external' || !path.isAbsolute(input.postgres.configRef) ||
+            !['disable', 'require', 'verify-full'].includes(input.postgres.tlsPolicy))
+            throw new Error('community_native_state_postgres_invalid');
+    }
+    else {
+        const postgres = assertCommunityNativePostgresInstanceState({
+            state: assertCommunityNativePostgresState(input.postgres),
+            instanceName: String(input.instanceName),
+            instanceRoot: paths.instanceRoot,
+        });
+        if (postgres.mode !== 'container')
+            throw new Error('community_native_state_postgres_invalid');
+        void buildCommunityNativePostgresUrl(postgres);
+    }
+    input.server = { ...input.server, exposure, publicPort, authProvider };
+    input.cockpit = { host: '127.0.0.1', port: cockpit.port };
+    return input;
+}
+function parseNativeProcess(value, paths) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('community_native_process_invalid');
+    const input = value;
+    const required = [
+        'schemaVersion', 'protocol', 'instanceName', 'launchId', 'pid', 'mode', 'status', 'startedAt',
+        'updatedAt', 'sourceFingerprint', 'identityPath', 'controlPath', 'logPath',
+    ];
+    const optional = ['hostPid', 'exitCode', 'signal', 'failure'];
+    const keys = Object.keys(input);
+    if (required.some((key) => !keys.includes(key)) || keys.some((key) => !required.includes(key) && !optional.includes(key))) {
+        throw new Error('community_native_process_schema_invalid');
+    }
+    if (input.schemaVersion !== 1 || input.protocol !== COMMUNITY_NATIVE_CHILD_PROTOCOL ||
+        !INSTANCE_NAME.test(String(input.instanceName)) || !UUID.test(String(input.launchId)) ||
+        !Number.isSafeInteger(input.pid) || input.pid < 1 ||
+        (input.hostPid !== undefined && (!Number.isSafeInteger(input.hostPid) || input.hostPid < 1)) ||
+        !['foreground', 'detached'].includes(input.mode) ||
+        !['starting', 'running', 'exited', 'failed'].includes(input.status) ||
+        Number.isNaN(Date.parse(String(input.startedAt))) || Number.isNaN(Date.parse(String(input.updatedAt))) ||
+        !SHA256.test(String(input.sourceFingerprint)) || !path.isAbsolute(input.identityPath) ||
+        !path.isAbsolute(input.controlPath) ||
+        (input.logPath !== null && !path.isAbsolute(input.logPath)))
+        throw new Error('community_native_process_schema_invalid');
+    const expectedLogPath = input.mode === 'detached' ? paths.logPath : null;
+    if (!samePhysicalPath(input.identityPath, paths.identityPath) ||
+        !samePhysicalPath(input.controlPath, paths.controlPath) ||
+        (expectedLogPath === null ? input.logPath !== null :
+            input.logPath === null || !samePhysicalPath(input.logPath, expectedLogPath)))
+        throw new Error('community_native_process_path_mismatch');
+    return input;
+}
+export function readCommunityNativeState(paths) {
+    assertCommunityNativePathLayout(paths, { requireInstanceRoot: true });
+    return parseNativeState(readJson(paths.statePath, 'community_native_state_json_invalid'), paths);
+}
+export function readCommunityNativeProcess(paths) {
+    assertCommunityNativePathLayout(paths, { requireInstanceRoot: true });
+    if (!existsSync(paths.processPath))
+        return null;
+    return parseNativeProcess(readJson(paths.processPath, 'community_native_process_json_invalid'), paths);
+}
+export function readCommunityNativeMigrationReceipt(paths, state) {
+    assertCommunityNativePathLayout(paths, { requireInstanceRoot: true });
+    if (!existsSync(paths.migrationReceiptPath))
+        return null;
+    let receipt;
+    try {
+        receipt = assertCommunityNativeMigrationReceiptV1(readJson(paths.migrationReceiptPath, 'community_native_migration_receipt_json_invalid'));
+    }
+    catch {
+        return null;
+    }
+    if (state && (receipt.instanceName !== state.instanceName ||
+        receipt.installId !== state.installId ||
+        receipt.sourceFingerprint !== state.source.sourceFingerprint)) {
+        return null;
+    }
+    return receipt;
+}
+function assertLegacyCommunityNativeMigrationArtifactsSafe(paths) {
+    const legacy = resolveLegacyCommunityNativeMigrationPaths(paths);
+    let intentPath = null;
+    if (existsSync(legacy.intentPath)) {
+        assertPlainCanonicalFile(legacy.intentPath, paths.runtimeRoot, 'community_native_migration_intent_unsafe');
+        intentPath = legacy.intentPath;
+    }
+    let receiptRoot = null;
+    if (existsSync(legacy.receiptRoot)) {
+        if (!samePhysicalPath(path.dirname(legacy.receiptRoot), paths.runtimeRoot)) {
+            throw new Error('community_native_migration_receipt_root_unsafe');
+        }
+        assertPlainCanonicalDirectory(legacy.receiptRoot, 'community_native_migration_receipt_root_unsafe');
+        for (const entry of readdirSync(legacy.receiptRoot, { withFileTypes: true })) {
+            const entryPath = path.join(legacy.receiptRoot, entry.name);
+            if (!/^[a-f0-9]{64}\.json$/.test(entry.name) || !entry.isFile() || entry.isSymbolicLink()) {
+                throw new Error('community_native_migration_history_receipt_unsafe');
+            }
+            assertPlainCanonicalFile(entryPath, legacy.receiptRoot, 'community_native_migration_history_receipt_unsafe');
+        }
+        receiptRoot = legacy.receiptRoot;
+    }
+    return { intentPath, receiptRoot };
+}
+function retireLegacyCommunityNativeMigrationArtifacts(paths) {
+    const legacy = assertLegacyCommunityNativeMigrationArtifactsSafe(paths);
+    if (legacy.intentPath)
+        rmSync(legacy.intentPath, { force: true });
+    if (legacy.receiptRoot)
+        rmSync(legacy.receiptRoot, { recursive: true, force: true });
+    if (legacy.intentPath || legacy.receiptRoot)
+        fsyncDirectoryBestEffortOnWindows(paths.runtimeRoot);
+}
+export function persistCommunityNativeMigrationReceipt(params) {
+    assertCommunityNativePathLayout(params.paths, { requireInstanceRoot: true });
+    if (params.receipt.instanceName !== params.state.instanceName ||
+        params.receipt.installId !== params.state.installId ||
+        params.receipt.sourceFingerprint !== params.state.source.sourceFingerprint) {
+        throw new Error('community_native_migration_receipt_identity_mismatch');
+    }
+    atomicJsonWrite(params.paths.migrationReceiptPath, params.receipt);
+    retireLegacyCommunityNativeMigrationArtifacts(params.paths);
+}
+export function inspectCommunityNativeInstall(input = {}) {
+    const paths = resolveCommunityNativePaths(input);
+    const candidates = [
+        paths.statePath,
+        paths.processPath,
+        paths.identityPath,
+        paths.controlPath,
+        paths.secretPath,
+        paths.migrationReceiptPath,
+    ];
+    const installationCandidates = candidates.filter((candidate) => candidate !== paths.migrationReceiptPath);
+    try {
+        assertCommunityNativePathLayout(paths);
+    }
+    catch (error) {
+        return {
+            status: 'partial',
+            paths,
+            error: error instanceof Error ? error.message : 'community_native_path_layout_invalid',
+            presentFiles: [],
+            missingFiles: candidates,
+        };
+    }
+    const presentFiles = candidates.filter(existsSync);
+    const missingFiles = candidates.filter((entry) => !existsSync(entry));
+    if (existsSync(paths.ociStatePath) && existsSync(paths.statePath)) {
+        return { status: 'runtime-conflict', paths, error: 'community_instance_runtime_conflict', presentFiles, missingFiles };
+    }
+    if (!existsSync(paths.statePath)) {
+        if (!installationCandidates.some(existsSync)) {
+            return { status: 'not-installed', paths, presentFiles, missingFiles };
+        }
+        return { status: 'partial', paths, error: 'community_native_state_missing', presentFiles, missingFiles };
+    }
+    if (!existsSync(paths.secretPath)) {
+        return { status: 'partial', paths, error: 'community_native_secret_file_missing', presentFiles, missingFiles };
+    }
+    try {
+        readNativeSecret(paths);
+        const state = readCommunityNativeState(paths);
+        return {
+            status: 'installed',
+            paths,
+            state,
+            process: readCommunityNativeProcess(paths),
+            migration: readCommunityNativeMigrationReceipt(paths, state) ?? undefined,
+            presentFiles,
+            missingFiles,
+        };
+    }
+    catch (error) {
+        return {
+            status: 'partial',
+            paths,
+            error: error instanceof Error ? error.message : 'community_native_state_invalid',
+            presentFiles,
+            missingFiles,
+        };
+    }
+}
+function sourcePackage(root) {
+    const packagePath = safeRegularFile(root, 'package.json');
+    try {
+        return JSON.parse(readFileSync(packagePath, 'utf8'));
+    }
+    catch {
+        throw new Error('community_native_source_package_json_invalid');
+    }
+}
+function sourceLayout(root, manifest = sourcePackage(root)) {
+    if (manifest.name === PUBLIC_ROOT_NAME && manifest.private === true &&
+        typeof manifest.version === 'string' && RELEASE_VERSION.test(manifest.version) &&
+        typeof manifest.packageManager === 'string' && PUBLIC_PACKAGE_MANAGER.test(manifest.packageManager)) {
+        return {
+            kind: 'checkout',
+            requiredSourcePaths: CHECKOUT_REQUIRED_SOURCE_PATHS,
+            lockfilePath: 'pnpm-lock.yaml',
+            buildPaths: CHECKOUT_BUILD_PATHS,
+        };
+    }
+    if (manifest.name === PUBLIC_SERVER_PACKAGE_NAME && manifest.private !== true &&
+        typeof manifest.version === 'string' && RELEASE_VERSION.test(manifest.version) &&
+        typeof manifest.packageManager === 'string' && PUBLIC_PACKAGE_MANAGER.test(manifest.packageManager)) {
+        return {
+            kind: 'npm-package',
+            requiredSourcePaths: PACKAGE_REQUIRED_SOURCE_PATHS,
+            lockfilePath: 'package.json',
+            buildPaths: PACKAGE_BUILD_PATHS,
+        };
+    }
+    throw new Error('community_native_public_source_required');
+}
+function isPackagedCommunityServerSource(source) {
+    return sourceLayout(source.root).kind === 'npm-package';
+}
+export function isCommunityNativeNpmPackageSource(sourceRoot) {
+    const resolved = path.resolve(sourceRoot);
+    return sourceLayout(realpathSync(resolved)).kind === 'npm-package';
+}
+export function resolveCommunityNativeDefaultSourceRoot(fallbackRoot = process.cwd(), moduleUrl = import.meta.url) {
+    try {
+        const require = createRequire(moduleUrl);
+        const packageJsonPath = require.resolve(`${PUBLIC_SERVER_PACKAGE_NAME}/package.json`);
+        const packageRoot = path.dirname(packageJsonPath);
+        sourceLayout(packageRoot);
+        return packageRoot;
+    }
+    catch {
+        return path.resolve(fallbackRoot);
+    }
+}
+export function inspectCommunityNativeSource(sourceRoot = process.cwd()) {
+    const resolved = path.resolve(sourceRoot);
+    let rootStats;
+    try {
+        rootStats = lstatSync(resolved);
+    }
+    catch {
+        throw new Error('community_native_source_root_invalid');
+    }
+    if (!rootStats.isDirectory() || rootStats.isSymbolicLink())
+        throw new Error('community_native_source_root_invalid');
+    const root = realpathSync(resolved);
+    const manifest = sourcePackage(root);
+    const layout = sourceLayout(root, manifest);
+    for (const relativePath of layout.requiredSourcePaths)
+        safeRegularFile(root, relativePath);
+    const packageSha256 = hashFile(path.join(root, 'package.json'));
+    const lockfileSha256 = hashFile(path.join(root, layout.lockfilePath));
+    const postgresProfileSha256 = hashFile(path.join(root, COMMUNITY_NATIVE_POSTGRES_CONTRACT_PATH));
+    const sourceInventory = inventoryCommunityNativeTree(root, SOURCE_INVENTORY_EXCLUDED_DIRECTORIES);
+    return {
+        root,
+        packageManager: manifest.packageManager,
+        releaseVersion: manifest.version,
+        packageSha256,
+        lockfileSha256,
+        sourceFileCount: sourceInventory.fileCount,
+        sourceInventorySha256: sourceInventory.sha256,
+        sourceFingerprint: sha256(JSON.stringify({
+            root,
+            packageManager: manifest.packageManager,
+            releaseVersion: manifest.version,
+            packageSha256,
+            lockfileSha256,
+            postgresProfileSha256,
+            sourceFileCount: sourceInventory.fileCount,
+            sourceInventorySha256: sourceInventory.sha256,
+        })),
+    };
+}
+function inspectCommunityNativeBuild(source, completedAt, currentSource = inspectCommunityNativeSource(source.root)) {
+    if (currentSource.packageSha256 !== source.packageSha256 ||
+        currentSource.lockfileSha256 !== source.lockfileSha256 ||
+        currentSource.sourceFileCount !== source.sourceFileCount ||
+        currentSource.sourceInventorySha256 !== source.sourceInventorySha256 ||
+        currentSource.sourceFingerprint !== source.sourceFingerprint)
+        throw new Error('community_native_source_changed_during_build');
+    const layout = sourceLayout(source.root);
+    const hostEntry = safeRegularFile(source.root, layout.buildPaths.hostEntry);
+    const handlerEntry = safeRegularFile(source.root, layout.buildPaths.handlerEntry);
+    const cockpitIndex = safeRegularFile(source.root, layout.buildPaths.cockpitIndex);
+    const hostEntrySha256 = hashFile(hostEntry);
+    const handlerEntrySha256 = hashFile(handlerEntry);
+    const cockpitIndexSha256 = hashFile(cockpitIndex);
+    const runtimeInventory = inventoryCommunityNativeTree(source.root, RUNTIME_INVENTORY_EXCLUDED_DIRECTORIES);
+    return {
+        completedAt,
+        hostEntry,
+        handlerEntry,
+        cockpitIndex,
+        hostEntrySha256,
+        handlerEntrySha256,
+        cockpitIndexSha256,
+        runtimeFileCount: runtimeInventory.fileCount,
+        runtimeInventorySha256: runtimeInventory.sha256,
+        buildFingerprint: sha256(JSON.stringify({
+            sourceFingerprint: source.sourceFingerprint,
+            hostEntrySha256,
+            handlerEntrySha256,
+            cockpitIndexSha256,
+            runtimeFileCount: runtimeInventory.fileCount,
+            runtimeInventorySha256: runtimeInventory.sha256,
+        })),
+    };
+}
+export function assertCommunityNativeApplicationCurrent(state) {
+    const source = inspectCommunityNativeSource(state.source.root);
+    const sourceFields = [
+        'root', 'packageManager', 'releaseVersion', 'packageSha256', 'lockfileSha256',
+        'sourceFileCount', 'sourceInventorySha256', 'sourceFingerprint',
+    ];
+    if (sourceFields.some((field) => source[field] !== state.source[field])) {
+        throw new Error('community_native_prior_application_source_drift');
+    }
+    const build = inspectCommunityNativeBuild(state.source, state.build.completedAt, source);
+    const buildFields = [
+        'completedAt', 'hostEntry', 'handlerEntry', 'cockpitIndex', 'hostEntrySha256',
+        'handlerEntrySha256', 'cockpitIndexSha256', 'runtimeFileCount',
+        'runtimeInventorySha256', 'buildFingerprint',
+    ];
+    if (buildFields.some((field) => build[field] !== state.build[field])) {
+        throw new Error('community_native_prior_application_build_drift');
+    }
+}
+function compareCommunityReleaseVersions(left, right) {
+    const parse = (value) => {
+        const buildIndex = value.indexOf('+');
+        const withoutBuild = buildIndex === -1 ? value : value.slice(0, buildIndex);
+        const prereleaseIndex = withoutBuild.indexOf('-');
+        const core = prereleaseIndex === -1 ? withoutBuild : withoutBuild.slice(0, prereleaseIndex);
+        const prerelease = prereleaseIndex === -1 ? '' : withoutBuild.slice(prereleaseIndex + 1);
+        return {
+            core: core.split('.').map((part) => BigInt(part)),
+            prerelease: prerelease ? prerelease.split('.') : [],
+        };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    for (let index = 0; index < 3; index += 1) {
+        if (a.core[index] !== b.core[index])
+            return a.core[index] < b.core[index] ? -1 : 1;
+    }
+    if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+        if (a.prerelease.length === b.prerelease.length)
+            return 0;
+        return a.prerelease.length === 0 ? 1 : -1;
+    }
+    const count = Math.max(a.prerelease.length, b.prerelease.length);
+    for (let index = 0; index < count; index += 1) {
+        const leftPart = a.prerelease[index];
+        const rightPart = b.prerelease[index];
+        if (leftPart === undefined || rightPart === undefined)
+            return leftPart === undefined ? -1 : 1;
+        if (leftPart === rightPart)
+            continue;
+        const leftNumeric = /^\d+$/.test(leftPart);
+        const rightNumeric = /^\d+$/.test(rightPart);
+        if (leftNumeric && rightNumeric)
+            return BigInt(leftPart) < BigInt(rightPart) ? -1 : 1;
+        if (leftNumeric !== rightNumeric)
+            return leftNumeric ? -1 : 1;
+        return leftPart < rightPart ? -1 : 1;
+    }
+    return 0;
+}
+export function reconcileCommunityNativePriorApplication(params) {
+    const { state, selectedSource, contract } = params;
+    if (state.instanceName !== contract.instanceId)
+        throw new Error('community_native_instance_mismatch');
+    if (state.profile !== contract.profile) {
+        throw new Error(`community_native_profile_change_refused:${state.profile}:to:${contract.profile}:run_server_reset`);
+    }
+    if (state.profile === 'native-external-postgres') {
+        if (contract.postgres.mode !== 'external' || !params.selectedExternalConfigRef) {
+            throw new Error('community_native_external_postgres_contract_required');
+        }
+    }
+    else if (contract.postgres.mode !== 'container') {
+        throw new Error('community_native_container_postgres_contract_required');
+    }
+    if (!samePhysicalPath(state.source.root, selectedSource.root)) {
+        return 'application-source-adopted';
+    }
+    try {
+        assertCommunityNativeApplicationCurrent(state);
+        return 'current';
+    }
+    catch (error) {
+        const code = error instanceof Error ? error.message : '';
+        if (code !== 'community_native_prior_application_source_drift' &&
+            code !== 'community_native_prior_application_build_drift') {
+            throw error;
+        }
+        const selectedLayout = sourceLayout(selectedSource.root);
+        if (selectedLayout.kind === 'checkout' && code === 'community_native_prior_application_build_drift' &&
+            state.source.sourceFingerprint === selectedSource.sourceFingerprint) {
+            return 'same-source-rebuild';
+        }
+        if (selectedLayout.kind === 'checkout') {
+            return 'in-place-checkout-refresh';
+        }
+        const comparison = compareCommunityReleaseVersions(selectedSource.releaseVersion, state.source.releaseVersion);
+        if (comparison < 0) {
+            throw new Error(`community_native_application_downgrade_refused:${state.source.releaseVersion}:to:${selectedSource.releaseVersion}`);
+        }
+        if (comparison > 0)
+            return 'application-source-adopted';
+        throw error;
+    }
+}
+function nodePackageIdentity(scriptPath) {
+    try {
+        const packageJson = JSON.parse(readFileSync(path.resolve(path.dirname(scriptPath), '..', 'package.json'), 'utf8'));
+        return typeof packageJson.name === 'string' && typeof packageJson.version === 'string'
+            ? { name: packageJson.name, version: packageJson.version }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function sourcePinsPnpm11(cwd) {
+    try {
+        const manifest = JSON.parse(readFileSync(path.join(path.resolve(cwd), 'package.json'), 'utf8'));
+        return typeof manifest.packageManager === 'string' && /^pnpm@11\./.test(manifest.packageManager);
+    }
+    catch {
+        return false;
+    }
+}
+function pnpmScriptCandidates(env) {
+    const candidates = [];
+    if (env.npm_execpath)
+        candidates.push(path.resolve(env.npm_execpath));
+    const roots = [env.PNPM_HOME, ...(String(env.PATH ?? '').split(path.delimiter))]
+        .filter((entry) => Boolean(entry?.trim()));
+    for (const root of roots) {
+        const resolved = path.resolve(root);
+        const packageRoots = [
+            path.join(resolved, 'node_modules', 'pnpm'),
+            path.resolve(resolved, '..', 'lib', 'node_modules', 'pnpm'),
+        ];
+        if (path.basename(resolved).toLowerCase() === '.bin') {
+            packageRoots.push(path.resolve(resolved, '..', 'pnpm'));
+        }
+        for (const packageRoot of packageRoots) {
+            candidates.push(path.join(packageRoot, 'bin', 'pnpm.mjs'), path.join(packageRoot, 'bin', 'pnpm.cjs'));
+        }
+        for (const corepackRoot of [
+            path.join(resolved, 'node_modules', 'corepack'),
+            path.resolve(resolved, '..', 'lib', 'node_modules', 'corepack'),
+            path.resolve(resolved, '..', 'node_modules', 'corepack'),
+        ]) {
+            candidates.push(path.join(corepackRoot, 'dist', 'pnpm.js'));
+        }
+        if (process.platform !== 'win32') {
+            for (const name of ['pnpm', 'pnpm.cjs', 'pnpm.mjs']) {
+                const executable = path.join(resolved, name);
+                try {
+                    candidates.push(realpathSync(executable));
+                }
+                catch { }
+            }
+        }
+    }
+    return [...new Set(candidates)];
+}
+export function buildCommunityPnpmInvocation(cwd, args, env = process.env) {
+    const pinnedBySource = sourcePinsPnpm11(cwd);
+    for (const candidate of pnpmScriptCandidates(env)) {
+        if (!existsSync(candidate) || !lstatSync(candidate).isFile())
+            continue;
+        const identity = nodePackageIdentity(candidate);
+        if (identity?.name === 'pnpm' && identity.version.startsWith('11.')) {
+            return { command: process.execPath, args: [candidate, ...args], cwd };
+        }
+        if (identity?.name === 'corepack' && path.basename(candidate) === 'pnpm.js' && pinnedBySource) {
+            return { command: process.execPath, args: [candidate, ...args], cwd };
+        }
+    }
+    throw new Error('community_pnpm11_not_resolvable:run_via_pnpm_11_or_set_PNPM_HOME');
+}
+export function loadExternalPostgresUrl(configRef, tlsPolicy) {
+    const resolved = path.resolve(configRef);
+    let stats;
+    try {
+        stats = lstatSync(resolved);
+    }
+    catch {
+        throw new Error('community_native_postgres_config_file_invalid');
+    }
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1 || stats.size > MAX_CONFIG_BYTES) {
+        throw new Error('community_native_postgres_config_file_invalid');
+    }
+    let parsed;
+    try {
+        parsed = parseEnv(readFileSync(resolved, 'utf8'));
+    }
+    catch {
+        throw new Error('community_native_postgres_config_parse_failed');
+    }
+    const value = String(parsed.AOPS_PG_URL ?? '').trim();
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('community_native_postgres_url_invalid');
+    }
+    if ((url.protocol !== 'postgres:' && url.protocol !== 'postgresql:') ||
+        !url.hostname || !url.username || !url.password || !url.pathname.slice(1))
+        throw new Error('community_native_postgres_url_invalid');
+    if (url.search || url.hash)
+        throw new Error('community_native_postgres_url_options_refused');
+    const rootCertInput = String(parsed.AOPS_PG_SSL_ROOT_CERT ?? '').trim();
+    if (tlsPolicy === 'disable') {
+        if (rootCertInput)
+            throw new Error('community_native_postgres_tls_root_cert_not_allowed');
+        url.searchParams.set('sslmode', 'disable');
+        return url.toString();
+    }
+    if (tlsPolicy === 'require') {
+        if (rootCertInput)
+            throw new Error('community_native_postgres_tls_root_cert_requires_verify_full');
+        url.searchParams.set('sslmode', 'require');
+        url.searchParams.set('uselibpqcompat', 'true');
+        return url.toString();
+    }
+    if (tlsPolicy !== 'verify-full')
+        throw new Error('community_native_postgres_tls_policy_invalid');
+    url.searchParams.set('sslmode', 'verify-full');
+    if (rootCertInput) {
+        if (path.isAbsolute(rootCertInput)) {
+            throw new Error('community_native_postgres_tls_root_cert_invalid');
+        }
+        const rootCertPath = path.resolve(path.dirname(resolved), rootCertInput);
+        if (!isWithin(path.dirname(resolved), rootCertPath)) {
+            throw new Error('community_native_postgres_tls_root_cert_invalid');
+        }
+        let rootCertStats;
+        try {
+            rootCertStats = lstatSync(rootCertPath);
+        }
+        catch {
+            throw new Error('community_native_postgres_tls_root_cert_invalid');
+        }
+        if (!rootCertStats.isFile() || rootCertStats.isSymbolicLink() ||
+            rootCertStats.size < 1 || rootCertStats.size > MAX_TLS_ROOT_CERT_BYTES)
+            throw new Error('community_native_postgres_tls_root_cert_invalid');
+        const realRootCertPath = realpathSync(rootCertPath);
+        if (!isWithin(realpathSync(path.dirname(resolved)), realRootCertPath)) {
+            throw new Error('community_native_postgres_tls_root_cert_invalid');
+        }
+        url.searchParams.set('sslrootcert', realRootCertPath);
+    }
+    return url.toString();
+}
+export function loadExternalServerAuthConfig(configRef, expectedAuthProvider) {
+    const resolved = path.resolve(configRef);
+    let stats;
+    try {
+        stats = lstatSync(resolved);
+    }
+    catch {
+        throw new Error('community_native_postgres_config_file_invalid');
+    }
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1 || stats.size > MAX_CONFIG_BYTES) {
+        throw new Error('community_native_postgres_config_file_invalid');
+    }
+    let parsed;
+    try {
+        parsed = parseEnv(readFileSync(resolved, 'utf8'));
+    }
+    catch {
+        throw new Error('community_native_postgres_config_parse_failed');
+    }
+    const configuredProvider = String(parsed.AOPS_AUTH_PROVIDER ?? 'trusted-local').trim().toLowerCase();
+    if (configuredProvider === 'authv2-jwt-session' || configuredProvider === 'remote-session') {
+        throw new Error('community_native_legacy_auth_cutover_required:repair_the_private_env_with_trusted-local_and_reconfigure_the_installation');
+    }
+    if (configuredProvider !== 'trusted-local') {
+        throw new Error('community_native_auth_provider_invalid');
+    }
+    if (configuredProvider !== expectedAuthProvider) {
+        throw new Error('community_native_auth_provider_state_mismatch');
+    }
+    return Object.freeze({ authProvider: 'trusted-local' });
+}
+async function resolveInstalledMigrationPlanningContext(input, dependencies = {}) {
+    throwIfNativeAborted(input.signal);
+    const inspection = inspectCommunityNativeInstall(input);
+    if (inspection.status !== 'installed' || !inspection.state) {
+        throw new Error(`community_native_migration_plan_requires_install:${inspection.status}:${inspection.error ?? 'run_server_setup'}`);
+    }
+    assertCommunityNativePathLayout(inspection.paths, { requireInstanceRoot: true });
+    const sourceBefore = inspectCommunityNativeSource(inspection.state.source.root);
+    const postgres = inspection.state.postgres;
+    const repoUrl = postgres.mode === 'external'
+        ? loadExternalPostgresUrl(postgres.configRef, postgres.tlsPolicy)
+        : (() => {
+            assertCommunityNativePostgresInstanceState({
+                state: postgres,
+                instanceName: inspection.state.instanceName,
+                instanceRoot: inspection.paths.instanceRoot,
+            });
+            return buildCommunityNativePostgresUrl(postgres);
+        })();
+    const result = await (dependencies.planMigration ?? planCommunityNativeMigration)({
+        sourceRoot: inspection.state.source.root,
+        repoUrl,
+        signal: input.signal,
+    });
+    throwIfNativeAborted(input.signal);
+    const sourceAfter = inspectCommunityNativeSource(inspection.state.source.root);
+    if (sourceAfter.sourceFingerprint !== sourceBefore.sourceFingerprint) {
+        throw new Error('community_native_source_drift_during_migration_plan');
+    }
+    return {
+        paths: inspection.paths,
+        state: inspection.state,
+        planning: result.planning,
+        policy: result.policy,
+    };
+}
+export async function planCommunityNativeInstalledMigration(input = {}, dependencies = {}) {
+    const context = await resolveInstalledMigrationPlanningContext(input, dependencies);
+    return {
+        schemaVersion: 1,
+        instanceName: context.state.instanceName,
+        profile: context.state.profile,
+        evidencePath: context.planning.requiresSnapshotEvidence
+            ? path.join(context.paths.migrationEvidenceRoot, `${context.state.profile === 'native-external-postgres' ? 'external' : 'managed'}-${context.planning.acceptedPlanSha256}.json`)
+            : null,
+        planning: context.planning,
+    };
+}
+export async function attestCommunityNativeExternalSnapshot(params, dependencies = {}) {
+    if (!RAW_SHA256.test(params.expectedPlanSha256)) {
+        throw new Error('community_external_snapshot_expected_plan_sha256_invalid');
+    }
+    if (params.preview === true && params.apply === true) {
+        throw new Error('community_external_snapshot_mode_conflict:choose_--preview_or_--apply');
+    }
+    if (params.preview !== true && params.apply !== true) {
+        throw new Error('community_external_snapshot_mode_required:use_--preview_or_--apply');
+    }
+    if (params.apply === true && params.confirmExternalRecoveryOwner !== true) {
+        throw new Error('community_external_snapshot_recovery_owner_confirmation_required');
+    }
+    const context = await resolveInstalledMigrationPlanningContext(params, dependencies);
+    if (context.state.profile !== 'native-external-postgres') {
+        throw new Error('community_external_snapshot_attestation_requires_external_postgres');
+    }
+    if (context.planning.acceptedPlanSha256 !== params.expectedPlanSha256) {
+        throw new Error(`community_external_snapshot_plan_mismatch:expected=${params.expectedPlanSha256}:actual=${context.planning.acceptedPlanSha256}`);
+    }
+    const evidencePath = path.join(context.paths.migrationEvidenceRoot, `external-${context.planning.acceptedPlanSha256}.json`);
+    const createdAt = (dependencies.now ?? (() => new Date()))();
+    const evidenceParams = {
+        planning: context.planning,
+        policy: context.policy,
+        provider: params.provider,
+        snapshotRef: params.snapshotRef,
+        snapshotDigest: params.snapshotDigest ?? null,
+        attestedBy: params.attestedBy,
+        restoreInstructionsRef: params.restoreInstructionsRef,
+        now: () => createdAt,
+    };
+    const evidence = params.apply === true
+        ? (dependencies.writeExternalAttestation ?? writeCommunityExternalSnapshotAttestationV1)({
+            ...evidenceParams,
+            evidenceRoot: context.paths.migrationEvidenceRoot,
+        }).evidence
+        : createCommunityExternalSnapshotAttestationV1(evidenceParams);
+    return {
+        schemaVersion: 1,
+        instanceName: context.state.instanceName,
+        profile: context.state.profile,
+        applied: params.apply === true,
+        evidencePath,
+        evidence,
+    };
+}
+function childEnvironment(params) {
+    const env = { ...(params.env ?? process.env) };
+    for (const key of Object.keys(env)) {
+        const upper = key.toUpperCase();
+        if (/^PG[A-Z0-9_]+$/i.test(key) ||
+            /(?:^|_)(?:AUTH|COOKIE|DATABASE|ENCRYPT|JWT|PASSWORD|PG|POSTGRES|REPO|SECRET|SESSION|SQLITE|TOKEN)(?:_|$)/i.test(key) ||
+            /^(?:AOPS|PROJECTMAN|DOCMAN|AGENTSPACE|CHATV3|AUTHV2|KANBAN|SPRINT|TASKER|FILEMAN|SYS)_/i.test(key) ||
+            /_(?:REPO|PG|SQLITE)_URL$/i.test(key) ||
+            /^NODE_/i.test(key) || /^DYLD_/i.test(key) ||
+            ['DATABASE_URL', 'DEV_PG_URL', 'HOST', 'PORT', 'ORIGIN', 'LD_PRELOAD', 'LD_LIBRARY_PATH',
+                'SSLKEYLOGFILE', 'HTTP_PROXY', 'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY',
+                'ADDRESS_HEADER', 'XFF_DEPTH', 'PROTOCOL_HEADER', 'HOST_HEADER'].includes(upper))
+            delete env[key];
+    }
+    const child = {
+        ...env,
+        NODE_ENV: 'production',
+        AOPS_DB_BOOTSTRAP_MODE: 'explicit',
+        AOPS_PG_URL: params.postgresUrl,
+        AOPS_RELEASE_VERSION: params.state.source.releaseVersion,
+        CHATV3_SERVER_KEY_ID: 'k1',
+        CHATV3_SERVER_KEY_SECRET: params.chatv3ServerKeySecret,
+        AOPS_NATIVE_LAUNCH_ID: params.launchId,
+        AOPS_NATIVE_STARTED_AT: params.startedAt,
+        AOPS_NATIVE_SOURCE_FINGERPRINT: params.state.source.sourceFingerprint,
+        AOPS_NATIVE_HOST_ENTRY: params.state.build.hostEntry,
+        AOPS_NATIVE_IDENTITY_PATH: params.paths.identityPath,
+        AOPS_NATIVE_CONTROL_PATH: params.paths.controlPath,
+        AOPS_NATIVE_PORT: String(params.state.server.port),
+        COMMUNITY_PORT: String(params.state.server.port),
+        AOPS_COMMUNITY_HOST_MODE: params.state.server.exposure,
+        AOPS_COMMUNITY_PUBLIC_PORT: String(params.state.server.publicPort),
+        AOPS_COMMUNITY_COCKPIT_PORT: String(params.state.cockpit.port),
+        AOPS_AUTH_PROVIDER: params.authConfig.authProvider,
+    };
+    return child;
+}
+function readNativeSecret(paths) {
+    try {
+        const stats = lstatSync(paths.secretPath);
+        if (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1 || stats.size > 4_096) {
+            throw new Error('invalid');
+        }
+    }
+    catch {
+        throw new Error('community_native_secret_file_invalid');
+    }
+    let parsed;
+    try {
+        parsed = parseEnv(readFileSync(paths.secretPath, 'utf8'));
+    }
+    catch {
+        throw new Error('community_native_secret_file_invalid');
+    }
+    const secret = String(parsed.CHATV3_SERVER_KEY_SECRET ?? '').trim();
+    if (parsed.CHATV3_SERVER_KEY_ID !== 'k1' || !/^[A-Za-z0-9_-]{32,}$/.test(secret) ||
+        Object.keys(parsed).some((key) => !['CHATV3_SERVER_KEY_ID', 'CHATV3_SERVER_KEY_SECRET'].includes(key)))
+        throw new Error('community_native_secret_file_invalid');
+    return secret;
+}
+function ensureNativeSecret(paths, createSecret) {
+    if (existsSync(paths.secretPath))
+        return readNativeSecret(paths);
+    const secret = createSecret();
+    if (!/^[A-Za-z0-9_-]{32,}$/.test(secret))
+        throw new Error('community_native_generated_secret_invalid');
+    mkdirSync(path.dirname(paths.secretPath), { recursive: true, mode: 0o700 });
+    writeFileSync(paths.secretPath, `CHATV3_SERVER_KEY_ID=k1\nCHATV3_SERVER_KEY_SECRET=${secret}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    return secret;
+}
+function parseChildIdentity(paths, processRecord) {
+    const value = readJson(paths.identityPath, 'community_native_child_identity_json_invalid');
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('community_native_child_identity_invalid');
+    exactKeys(value, [
+        'schemaVersion', 'protocol', 'launchId', 'pid', 'hostPid', 'startedAt',
+        'sourceFingerprint', 'hostEntry', 'controlPath', 'port',
+    ], 'community_native_child_identity_schema_invalid');
+    const identity = value;
+    if (identity.schemaVersion !== 1 || identity.protocol !== COMMUNITY_NATIVE_CHILD_PROTOCOL ||
+        identity.launchId !== processRecord.launchId || identity.pid !== processRecord.pid ||
+        !Number.isSafeInteger(identity.hostPid) || identity.hostPid < 1 ||
+        identity.startedAt !== processRecord.startedAt || identity.sourceFingerprint !== processRecord.sourceFingerprint ||
+        path.resolve(identity.controlPath) !== path.resolve(paths.controlPath) ||
+        path.resolve(processRecord.controlPath) !== path.resolve(paths.controlPath))
+        throw new Error('community_native_child_identity_mismatch');
+    return identity;
+}
+function removeIdentityIfExact(paths, processRecord) {
+    if (!existsSync(paths.identityPath))
+        return;
+    parseChildIdentity(paths, processRecord);
+    rmSync(paths.identityPath, { force: true });
+}
+async function stopSpawnedNative(params) {
+    writeStopRequest(params.paths, params.processRecord.launchId, params.now);
+    let identity = null;
+    const observe = () => {
+        if (existsSync(params.paths.identityPath)) {
+            const current = parseChildIdentity(params.paths, params.processRecord);
+            if (current.hostEntry !== params.state.build.hostEntry || current.port !== params.state.server.port ||
+                current.sourceFingerprint !== params.state.source.sourceFingerprint)
+                throw new Error('community_native_child_identity_mismatch');
+            identity = current;
+        }
+        return {
+            supervisorAlive: params.runtime.processExists(params.processRecord.pid),
+            hostAlive: identity ? params.runtime.processExists(identity.hostPid) : false,
+        };
+    };
+    const pollCount = Math.max(1, Math.ceil(params.timeoutMs / READY_POLL_MS));
+    for (let attempt = 0; attempt < pollCount; attempt += 1) {
+        const live = observe();
+        if (!live.supervisorAlive && !live.hostAlive) {
+            removeIdentityIfExact(params.paths, params.processRecord);
+            removeControlIfExact(params.paths, params.processRecord.launchId);
+            return;
+        }
+        await params.runtime.sleep(READY_POLL_MS);
+    }
+    const live = observe();
+    if (live.hostAlive) {
+        throw new Error('community_native_child_cleanup_timeout:verified_host_left_running');
+    }
+    if (live.supervisorAlive)
+        await params.handle.terminate();
+    if (params.runtime.processExists(params.processRecord.pid)) {
+        throw new Error('community_native_child_cleanup_timeout:supervisor_still_running');
+    }
+    removeIdentityIfExact(params.paths, params.processRecord);
+    removeControlIfExact(params.paths, params.processRecord.launchId);
+}
+async function waitUntilReady(params) {
+    const deadline = Date.now() + params.timeoutMs;
+    const childState = {};
+    void params.handle.wait.then((value) => { childState.exit = value; }, (error) => { childState.failure = error; });
+    try {
+        while (Date.now() < deadline) {
+            throwIfNativeAborted(params.signal);
+            if (childState.failure)
+                throw new Error('community_native_child_launch_failed');
+            if (childState.exit) {
+                throw new Error(`community_native_child_exited_before_ready:${childState.exit.exitCode ?? 'signal'}:${childState.exit.signal ?? 'none'}`);
+            }
+            if (existsSync(params.paths.identityPath)) {
+                try {
+                    const identity = parseChildIdentity(params.paths, params.processRecord);
+                    if (identity.hostEntry !== params.state.build.hostEntry || identity.port !== params.state.server.port ||
+                        identity.sourceFingerprint !== params.state.source.sourceFingerprint)
+                        throw new Error('community_native_child_identity_mismatch');
+                    const healthy = await params.runtime.health(`http://127.0.0.1:${params.state.server.port}/api/health`, params.signal);
+                    throwIfNativeAborted(params.signal);
+                    if (healthy)
+                        return identity;
+                }
+                catch (error) {
+                    if (params.signal?.aborted)
+                        throw new Error('community_operation_aborted');
+                    if (error instanceof Error && /identity_mismatch/.test(error.message))
+                        throw error;
+                }
+            }
+            await params.runtime.sleep(READY_POLL_MS, params.signal);
+            throwIfNativeAborted(params.signal);
+        }
+        throw new Error('community_native_child_ready_timeout');
+    }
+    catch (error) {
+        await stopSpawnedNative({ ...params, timeoutMs: DEFAULT_STOP_TIMEOUT_MS });
+        throw error;
+    }
+}
+function writeProcess(paths, record) {
+    assertCommunityNativePathLayout(paths, { requireInstanceRoot: true });
+    atomicJsonWrite(paths.processPath, record);
+}
+export function resolveCommunityNativeChildEntry(moduleUrl = import.meta.url) {
+    const moduleDirectory = path.dirname(fileURLToPath(moduleUrl));
+    return path.join(path.basename(moduleDirectory) === 'launchers' ? path.dirname(moduleDirectory) : moduleDirectory, 'community-native-child.js');
+}
+function defaultRunBuild(invocation) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(invocation.command, invocation.args, {
+            cwd: invocation.cwd,
+            env: process.env,
+            shell: false,
+            windowsHide: true,
+            stdio: 'inherit',
+            signal: invocation.signal,
+        });
+        child.once('error', reject);
+        child.once('exit', (exitCode, signal) => resolve({ exitCode, signal }));
+    });
+}
+async function defaultSpawnChild(params) {
+    mkdirSync(path.dirname(params.logPath), { recursive: true, mode: 0o700 });
+    const logRootStats = lstatSync(path.dirname(params.logPath));
+    if (!logRootStats.isDirectory() || logRootStats.isSymbolicLink()) {
+        throw new Error('community_native_log_root_invalid');
+    }
+    if (existsSync(params.logPath)) {
+        const logStats = lstatSync(params.logPath);
+        if (!logStats.isFile() || logStats.isSymbolicLink())
+            throw new Error('community_native_log_file_invalid');
+    }
+    let logFd;
+    if (params.mode === 'detached')
+        logFd = openSync(params.logPath, 'a', 0o600);
+    const child = spawn(process.execPath, [params.childEntry], {
+        cwd: params.cwd,
+        env: params.env,
+        detached: params.mode === 'detached',
+        windowsHide: params.mode === 'detached',
+        stdio: params.mode === 'foreground' ? 'inherit' : ['ignore', logFd, logFd],
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            child.once('spawn', resolve);
+            child.once('error', reject);
+        });
+    }
+    finally {
+        if (logFd !== undefined)
+            closeSync(logFd);
+    }
+    if (!child.pid)
+        throw new Error('community_native_child_pid_missing');
+    const wait = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', (exitCode, signal) => resolve({ exitCode, signal }));
+    });
+    let termination;
+    return {
+        pid: child.pid,
+        wait,
+        detach: () => child.unref(),
+        terminate: () => {
+            termination ??= (async () => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return;
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { }
+                let forceTimer;
+                await Promise.race([
+                    wait.then(() => undefined),
+                    new Promise((resolve) => {
+                        forceTimer = setTimeout(() => {
+                            if (child.exitCode === null && child.signalCode === null) {
+                                try {
+                                    child.kill('SIGKILL');
+                                }
+                                catch { }
+                            }
+                            resolve();
+                        }, 5_000);
+                    }),
+                ]);
+                if (forceTimer)
+                    clearTimeout(forceTimer);
+                await wait.then(() => undefined);
+            })();
+            return termination;
+        },
+    };
+}
+export const communityNativeRuntime = {
+    runBuild: defaultRunBuild,
+    migrate: runCommunityNativeMigration,
+    spawnChild: defaultSpawnChild,
+    async health(url, signal) {
+        try {
+            const timeout = AbortSignal.timeout(2_000);
+            const response = await fetch(url, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout });
+            return response.ok;
+        }
+        catch {
+            if (signal?.aborted)
+                throw new Error('community_operation_aborted');
+            return false;
+        }
+    },
+    processExists(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'EPERM');
+        }
+    },
+    sleep: (milliseconds, signal) => new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new Error('community_operation_aborted'));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(new Error('community_operation_aborted'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    }),
+};
+function parseControlRequest(paths) {
+    const value = readJson(paths.controlPath, 'community_native_control_json_invalid');
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('community_native_control_invalid');
+    exactKeys(value, [
+        'schemaVersion', 'protocol', 'launchId', 'command', 'requestedAt',
+    ], 'community_native_control_schema_invalid');
+    const request = value;
+    if (request.schemaVersion !== 1 || request.protocol !== COMMUNITY_NATIVE_CONTROL_PROTOCOL ||
+        !UUID.test(request.launchId) || request.command !== 'stop' ||
+        Number.isNaN(Date.parse(request.requestedAt)))
+        throw new Error('community_native_control_schema_invalid');
+    return request;
+}
+function removeControlIfExact(paths, launchId) {
+    if (!existsSync(paths.controlPath))
+        return;
+    const request = parseControlRequest(paths);
+    if (request.launchId !== launchId)
+        throw new Error('community_native_control_launch_mismatch');
+    rmSync(paths.controlPath, { force: true });
+}
+async function observeInstalledNative(params) {
+    const record = params.processRecord;
+    const identityPresent = existsSync(params.paths.identityPath);
+    if (!record) {
+        return {
+            runtimeState: identityPresent ? 'identity-conflict' : 'stopped',
+            recoverable: !identityPresent,
+            process: null,
+            identity: null,
+            supervisorAlive: false,
+            hostAlive: false,
+            health: 'not-checked',
+            reason: identityPresent ? 'community_native_identity_without_process_record' : null,
+        };
+    }
+    const supervisorAlive = params.runtime.processExists(record.pid);
+    let identity = null;
+    if (identityPresent) {
+        try {
+            identity = parseChildIdentity(params.paths, record);
+        }
+        catch (error) {
+            return {
+                runtimeState: 'identity-conflict',
+                recoverable: false,
+                process: record,
+                identity: null,
+                supervisorAlive,
+                hostAlive: record.hostPid ? params.runtime.processExists(record.hostPid) : false,
+                health: 'not-checked',
+                reason: error instanceof Error ? error.message : 'community_native_child_identity_invalid',
+            };
+        }
+    }
+    const hostPid = identity?.hostPid ?? record.hostPid;
+    const hostAlive = hostPid ? params.runtime.processExists(hostPid) : false;
+    const activeRecord = record.status === 'starting' || record.status === 'running';
+    if (!activeRecord && !identityPresent && !supervisorAlive && !hostAlive &&
+        record.instanceName === params.state.instanceName) {
+        return {
+            runtimeState: 'stopped', recoverable: true, process: record, identity: null,
+            supervisorAlive: false, hostAlive: false, health: 'not-checked', reason: null,
+        };
+    }
+    if (record.instanceName !== params.state.instanceName ||
+        record.sourceFingerprint !== params.state.source.sourceFingerprint ||
+        (identity && (identity.sourceFingerprint !== params.state.source.sourceFingerprint ||
+            !samePhysicalPath(identity.hostEntry, params.state.build.hostEntry) ||
+            identity.port !== params.state.server.port))) {
+        return {
+            runtimeState: 'identity-conflict', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'not-checked',
+            reason: 'community_native_process_state_identity_mismatch',
+        };
+    }
+    if (!activeRecord) {
+        if (!identityPresent && !supervisorAlive && !hostAlive) {
+            return {
+                runtimeState: 'stopped', recoverable: true, process: record, identity: null,
+                supervisorAlive: false, hostAlive: false, health: 'not-checked', reason: null,
+            };
+        }
+        if (identity && !supervisorAlive && !hostAlive) {
+            return {
+                runtimeState: 'stopped', recoverable: true, process: record, identity,
+                supervisorAlive: false, hostAlive: false, health: 'not-checked',
+                reason: 'community_native_terminal_identity_stale',
+            };
+        }
+        return {
+            runtimeState: 'identity-conflict', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'not-checked',
+            reason: 'community_native_terminal_record_with_live_or_unowned_process',
+        };
+    }
+    if (!identity) {
+        if (!supervisorAlive && !hostAlive) {
+            return {
+                runtimeState: 'crashed', recoverable: true, process: record, identity: null,
+                supervisorAlive: false, hostAlive: false, health: 'not-checked',
+                reason: 'community_native_process_disappeared_without_identity',
+            };
+        }
+        return {
+            runtimeState: 'identity-conflict', recoverable: false, process: record, identity: null,
+            supervisorAlive, hostAlive, health: 'not-checked',
+            reason: 'community_native_live_process_without_matching_identity',
+        };
+    }
+    if (!supervisorAlive && !hostAlive) {
+        return {
+            runtimeState: 'crashed', recoverable: true, process: record, identity,
+            supervisorAlive: false, hostAlive: false, health: 'not-checked',
+            reason: 'community_native_process_disappeared',
+        };
+    }
+    if (!supervisorAlive && hostAlive) {
+        return {
+            runtimeState: 'orphaned', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'not-checked', reason: 'community_native_host_orphaned',
+        };
+    }
+    if (supervisorAlive && !hostAlive) {
+        return {
+            runtimeState: 'unhealthy', recoverable: false, process: record, identity,
+            supervisorAlive, hostAlive, health: 'unhealthy', reason: 'community_native_host_process_missing',
+        };
+    }
+    const healthy = await params.runtime.health(`http://127.0.0.1:${params.state.server.port}/api/health`);
+    return {
+        runtimeState: healthy ? 'running' : record.status === 'starting' ? 'starting' : 'unhealthy',
+        recoverable: false, process: record, identity,
+        supervisorAlive, hostAlive, health: healthy ? 'healthy' : 'unhealthy',
+        reason: healthy ? null : 'community_native_health_failed',
+    };
+}
+export async function inspectCommunityNativeRuntime(params = {}) {
+    const inspection = inspectCommunityNativeInstall({ instanceName: params.instanceName, dataRoot: params.dataRoot });
+    if (inspection.status !== 'installed' || !inspection.state) {
+        throw new Error(`community_native_not_installed:${inspection.status}:${inspection.error ?? 'run_server_setup'}`);
+    }
+    return observeInstalledNative({
+        paths: inspection.paths,
+        state: inspection.state,
+        processRecord: inspection.process ?? null,
+        runtime: params.runtime ?? communityNativeRuntime,
+        now: params.now ?? (() => new Date()),
+    });
+}
+function writeStopRequest(paths, launchId, now) {
+    if (existsSync(paths.controlPath)) {
+        const existing = parseControlRequest(paths);
+        if (existing.launchId === launchId)
+            return;
+        throw new Error('community_native_control_launch_mismatch');
+    }
+    atomicJsonWrite(paths.controlPath, {
+        schemaVersion: 1,
+        protocol: COMMUNITY_NATIVE_CONTROL_PROTOCOL,
+        launchId,
+        command: 'stop',
+        requestedAt: now().toISOString(),
+    });
+}
+export async function stopCommunityNativeInstall(params = {}) {
+    throwIfNativeAborted(params.signal);
+    const inspection = inspectCommunityNativeInstall({ instanceName: params.instanceName, dataRoot: params.dataRoot });
+    if (inspection.status !== 'installed' || !inspection.state) {
+        throw new Error(`community_native_not_installed:${inspection.status}:${inspection.error ?? 'run_server_setup'}`);
+    }
+    const runtime = params.runtime ?? communityNativeRuntime;
+    const now = params.now ?? (() => new Date());
+    const observed = await observeInstalledNative({
+        paths: inspection.paths,
+        state: inspection.state,
+        processRecord: inspection.process ?? null,
+        runtime,
+        now,
+    });
+    if (observed.runtimeState === 'stopped' || observed.runtimeState === 'crashed') {
+        if (inspection.state.postgres.mode === 'container') {
+            await stopCommunityNativePostgres({
+                state: inspection.state.postgres,
+                instanceName: inspection.state.instanceName,
+                instanceRoot: inspection.paths.instanceRoot,
+                runtime: params.postgresRuntime,
+                signal: params.signal,
+            });
+        }
+        return { status: 'already-stopped', state: inspection.state, process: observed.process };
+    }
+    if (!observed.process || !observed.identity || !observed.supervisorAlive ||
+        !['starting', 'running', 'unhealthy'].includes(observed.runtimeState)) {
+        throw new Error(`community_native_stop_refused:${observed.runtimeState}:${observed.reason ?? 'identity_not_verified'}`);
+    }
+    writeStopRequest(inspection.paths, observed.process.launchId, now);
+    const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_STOP_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+        throwIfNativeAborted(params.signal);
+        if (existsSync(inspection.paths.identityPath))
+            parseChildIdentity(inspection.paths, observed.process);
+        const supervisorAlive = runtime.processExists(observed.process.pid);
+        const hostAlive = runtime.processExists(observed.identity.hostPid);
+        if (!supervisorAlive && !hostAlive && !existsSync(inspection.paths.identityPath)) {
+            removeControlIfExact(inspection.paths, observed.process.launchId);
+            const stopped = {
+                ...observed.process,
+                status: 'exited',
+                updatedAt: now().toISOString(),
+                exitCode: 0,
+                signal: null,
+            };
+            delete stopped.failure;
+            writeProcess(inspection.paths, stopped);
+            if (inspection.state.postgres.mode === 'container') {
+                await stopCommunityNativePostgres({
+                    state: inspection.state.postgres,
+                    instanceName: inspection.state.instanceName,
+                    instanceRoot: inspection.paths.instanceRoot,
+                    runtime: params.postgresRuntime,
+                    signal: params.signal,
+                });
+            }
+            return { status: 'stopped', state: inspection.state, process: stopped };
+        }
+        await runtime.sleep(READY_POLL_MS, params.signal);
+        throwIfNativeAborted(params.signal);
+    }
+    throw new Error('community_native_stop_timeout:no_unverified_pid_kill');
+}
+export function redactNativeLog(content, paths, state) {
+    const exactSecrets = [];
+    try {
+        exactSecrets.push(readNativeSecret(paths));
+    }
+    catch { }
+    if (state.postgres.mode === 'external') {
+        try {
+            const parsed = parseEnv(readFileSync(state.postgres.configRef, 'utf8'));
+            for (const key of ['JWT_SECRET', 'JWT_ENC_SECRET', 'AOPS_ADMIN_KEY']) {
+                const value = String(parsed[key] ?? '').trim();
+                if (value)
+                    exactSecrets.push(value);
+            }
+            if (parsed.AOPS_PG_URL) {
+                const rawUrl = String(parsed.AOPS_PG_URL);
+                exactSecrets.push(rawUrl);
+                try {
+                    const url = new URL(rawUrl);
+                    if (url.password) {
+                        exactSecrets.push(url.password);
+                        try {
+                            exactSecrets.push(decodeURIComponent(url.password));
+                        }
+                        catch { }
+                    }
+                }
+                catch { }
+            }
+        }
+        catch { }
+    }
+    else {
+        try {
+            const rawUrl = buildCommunityNativePostgresUrl(state.postgres);
+            exactSecrets.push(rawUrl);
+            const url = new URL(rawUrl);
+            if (url.password) {
+                exactSecrets.push(url.password);
+                try {
+                    exactSecrets.push(decodeURIComponent(url.password));
+                }
+                catch { }
+            }
+        }
+        catch { }
+    }
+    let redacted = content;
+    for (const secret of exactSecrets
+        .filter((value) => value.length >= MIN_EXACT_SECRET_REDACTION_LENGTH)
+        .sort((left, right) => right.length - left.length)) {
+        redacted = redacted.split(secret).join('[REDACTED]');
+    }
+    return redacted
+        .replace(/postgres(?:ql)?:\/\/[^\s"']+/gi, 'postgresql://[REDACTED]')
+        .replace(/(CHATV3_SERVER_KEY_SECRET\s*[=:]\s*)[^\s]+/gi, '$1[REDACTED]')
+        .replace(/(["']?(?:JWT_SECRET|JWT_ENC_SECRET|AOPS_ADMIN_KEY)["']?\s*[=:]\s*)(?:"[^"\r\n]*"|'[^'\r\n]*'|[^,;\s}\]]+)/gi, '$1[REDACTED]')
+        .replace(/((?:password|pwd)\s*[=:]\s*)[^;\s]+/gi, '$1[REDACTED]');
+}
+export function readCommunityNativeLogs(params = {}) {
+    const inspection = inspectCommunityNativeInstall({ instanceName: params.instanceName, dataRoot: params.dataRoot });
+    if (inspection.status !== 'installed' || !inspection.state) {
+        throw new Error(`community_native_not_installed:${inspection.status}:${inspection.error ?? 'run_server_setup'}`);
+    }
+    const tail = params.tail ?? 100;
+    if (!Number.isSafeInteger(tail) || tail < 1 || tail > 10_000)
+        throw new Error('community_logs_tail_invalid');
+    if (!existsSync(inspection.paths.logPath)) {
+        return { content: '', lineCount: 0, truncated: false, logPath: inspection.paths.logPath };
+    }
+    const stats = lstatSync(inspection.paths.logPath);
+    if (!stats.isFile() || stats.isSymbolicLink())
+        throw new Error('community_native_log_file_invalid');
+    const realLog = realpathSync(inspection.paths.logPath);
+    if (!isWithin(realpathSync(inspection.paths.instanceRoot), realLog))
+        throw new Error('community_native_log_path_escape');
+    const byteLength = Math.min(stats.size, MAX_LOG_TAIL_BYTES);
+    const start = stats.size - byteLength;
+    const buffer = Buffer.alloc(byteLength);
+    const fd = openSync(realLog, 'r');
+    try {
+        if (byteLength > 0)
+            readSync(fd, buffer, 0, byteLength, start);
+    }
+    finally {
+        closeSync(fd);
+    }
+    let content = buffer.toString('utf8');
+    let truncated = start > 0;
+    if (truncated) {
+        const firstNewline = content.indexOf('\n');
+        content = firstNewline >= 0 ? content.slice(firstNewline + 1) : '';
+    }
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    const selected = lines.slice(-tail);
+    truncated ||= selected.length < lines.length;
+    const safe = redactNativeLog(selected.join('\n'), inspection.paths, inspection.state);
+    return { content: safe, lineCount: selected.length, truncated, logPath: inspection.paths.logPath };
+}
+async function runBuildChecked(runtime, invocation, step) {
+    throwIfNativeAborted(invocation.signal);
+    let result;
+    try {
+        result = await runtime.runBuild(invocation);
+    }
+    catch (error) {
+        if (invocation.signal?.aborted)
+            throw new Error('community_operation_aborted');
+        throw error;
+    }
+    throwIfNativeAborted(invocation.signal);
+    if (result.exitCode !== 0)
+        throw new Error(`community_native_${step}_failed:${result.exitCode ?? result.signal ?? 'unknown'}`);
+}
+export function resolveCommunityNativeLaunchMode(input) {
+    if (input.foreground === true && input.detach === true)
+        throw new Error('community_native_launch_mode_conflict');
+    return input.foreground === true ? 'foreground' : 'detached';
+}
+async function launchInstalledNative(params) {
+    throwIfNativeAborted(params.signal);
+    assertCommunityNativePathLayout(params.paths, { requireInstanceRoot: true });
+    const priorProcess = readCommunityNativeProcess(params.paths);
+    const observed = await observeInstalledNative({
+        paths: params.paths,
+        state: params.state,
+        processRecord: priorProcess,
+        runtime: params.runtime,
+        now: params.now,
+    });
+    if (observed.runtimeState !== 'stopped' && observed.runtimeState !== 'crashed') {
+        throw new Error(`community_native_process_active:${observed.runtimeState}:${observed.reason ?? 'run_server_status'}`);
+    }
+    const packagedSource = isPackagedCommunityServerSource(params.state.source);
+    const currentSource = inspectCommunityNativeSource(params.state.source.root);
+    if (packagedSource && currentSource.sourceFingerprint !== params.state.source.sourceFingerprint) {
+        throw new Error('community_native_source_drift:run_server_setup_--apply');
+    }
+    const currentBuild = inspectCommunityNativeBuild(packagedSource ? params.state.source : currentSource, params.state.build.completedAt, currentSource);
+    if (packagedSource && currentBuild.buildFingerprint !== params.state.build.buildFingerprint) {
+        throw new Error('community_native_build_drift:run_server_setup_--apply');
+    }
+    const buildFields = [
+        'completedAt', 'hostEntry', 'handlerEntry', 'cockpitIndex', 'hostEntrySha256',
+        'handlerEntrySha256', 'cockpitIndexSha256', 'runtimeFileCount',
+        'runtimeInventorySha256', 'buildFingerprint',
+    ];
+    if (packagedSource && buildFields.some((field) => currentBuild[field] !== params.state.build[field])) {
+        throw new Error('community_native_build_identity_drift:run_server_setup_--apply');
+    }
+    const postgres = params.state.postgres;
+    params.progress?.({
+        stage: 'postgres',
+        message: postgres.mode === 'external'
+            ? 'Connecting to the selected PostgreSQL database...'
+            : 'Starting and checking the AOPS-managed PostgreSQL database...',
+    });
+    const postgresUrl = postgres.mode === 'external'
+        ? loadExternalPostgresUrl(postgres.configRef, postgres.tlsPolicy)
+        : await (async () => {
+            await startCommunityNativePostgres({
+                state: postgres,
+                instanceName: params.state.instanceName,
+                instanceRoot: params.paths.instanceRoot,
+                runtime: params.postgresRuntime,
+                signal: params.signal,
+            });
+            return buildCommunityNativePostgresUrl(postgres);
+        })();
+    if (params.state.server.authProvider !== 'trusted-local') {
+        throw new Error('community_native_legacy_auth_cutover_required:run_aops_setup_server-env_--auth_trusted-local_then_reconfigure_without_reset');
+    }
+    const authConfig = postgres.mode === 'external'
+        ? loadExternalServerAuthConfig(postgres.configRef, params.state.server.authProvider)
+        : Object.freeze({ authProvider: 'trusted-local' });
+    throwIfNativeAborted(params.signal);
+    params.progress?.({
+        stage: 'migration-plan',
+        message: 'Inspecting the PostgreSQL schema and planning migrations...',
+    });
+    const migration = assertCommunityNativeMigrationReceiptV1(await params.runtime.migrate({
+        sourceRoot: params.state.source.root,
+        repoUrl: postgresUrl,
+        instanceName: params.state.instanceName,
+        installId: params.state.installId,
+        sourceFingerprint: params.state.source.sourceFingerprint,
+        requiredPlanSha256: params.requiredMigrationPlanSha256,
+        requiredAction: params.requiredMigrationAction,
+        onPlanAccepted: (context) => {
+            const pendingMigrationCount = context.migrationPlan.pendingMigrations.length;
+            params.progress?.({
+                stage: 'migration-apply',
+                message: context.migrationPlan.action === 'migrate'
+                    ? `Applying and verifying ${pendingMigrationCount} PostgreSQL migration${pendingMigrationCount === 1 ? '' : 's'}...`
+                    : 'No pending migrations; verifying the current PostgreSQL schema...',
+                migrationAction: context.migrationPlan.action,
+                pendingMigrationCount,
+            });
+        },
+        signal: params.signal,
+    }));
+    throwIfNativeAborted(params.signal);
+    if (migration.instanceName !== params.state.instanceName ||
+        migration.installId !== params.state.installId ||
+        migration.sourceFingerprint !== params.state.source.sourceFingerprint) {
+        throw new Error('community_native_migration_receipt_identity_mismatch');
+    }
+    const sourceAfterMigration = inspectCommunityNativeSource(params.state.source.root);
+    const expectedSourceFingerprint = packagedSource
+        ? params.state.source.sourceFingerprint
+        : currentSource.sourceFingerprint;
+    if (sourceAfterMigration.sourceFingerprint !== expectedSourceFingerprint) {
+        throw new Error('community_native_source_drift_during_migration:run_server_setup_--apply');
+    }
+    const buildAfterMigration = inspectCommunityNativeBuild(packagedSource ? params.state.source : sourceAfterMigration, params.state.build.completedAt, sourceAfterMigration);
+    const expectedBuild = packagedSource ? params.state.build : currentBuild;
+    if (buildAfterMigration.buildFingerprint !== expectedBuild.buildFingerprint ||
+        buildFields.some((field) => buildAfterMigration[field] !== expectedBuild[field])) {
+        throw new Error('community_native_build_drift_during_migration:run_server_setup_--apply');
+    }
+    persistCommunityNativeMigrationReceipt({ paths: params.paths, state: params.state, receipt: migration });
+    const chatv3ServerKeySecret = readNativeSecret(params.paths);
+    throwIfNativeAborted(params.signal);
+    params.progress?.({
+        stage: 'server-start',
+        message: 'Starting the local AOPS server process...',
+    });
+    rmSync(params.paths.identityPath, { force: true });
+    rmSync(params.paths.controlPath, { force: true });
+    mkdirSync(params.paths.logRoot, { recursive: true, mode: 0o700 });
+    const launchId = params.createId();
+    const startedAt = params.now().toISOString();
+    const handle = await params.runtime.spawnChild({
+        childEntry: resolveCommunityNativeChildEntry(),
+        cwd: params.state.source.root,
+        env: childEnvironment({
+            state: params.state,
+            paths: params.paths,
+            launchId,
+            startedAt,
+            postgresUrl,
+            chatv3ServerKeySecret,
+            authConfig,
+            env: params.env,
+        }),
+        mode: params.mode,
+        logPath: params.paths.logPath,
+    });
+    let processRecord = {
+        schemaVersion: 1,
+        protocol: COMMUNITY_NATIVE_CHILD_PROTOCOL,
+        instanceName: params.state.instanceName,
+        launchId,
+        pid: handle.pid,
+        mode: params.mode,
+        status: 'starting',
+        startedAt,
+        updatedAt: startedAt,
+        sourceFingerprint: params.state.source.sourceFingerprint,
+        identityPath: params.paths.identityPath,
+        controlPath: params.paths.controlPath,
+        logPath: params.mode === 'detached' ? params.paths.logPath : null,
+    };
+    writeProcess(params.paths, processRecord);
+    try {
+        params.progress?.({
+            stage: 'server-health',
+            message: 'Waiting for the AOPS server health check...',
+        });
+        const identity = await waitUntilReady({
+            paths: params.paths,
+            state: params.state,
+            processRecord,
+            handle,
+            runtime: params.runtime,
+            timeoutMs: params.readyTimeoutMs,
+            now: params.now,
+            signal: params.signal,
+        });
+        processRecord = { ...processRecord, hostPid: identity.hostPid };
+    }
+    catch (error) {
+        const liveAfterFailure = params.runtime.processExists(processRecord.pid) || (() => {
+            try {
+                return existsSync(params.paths.identityPath) &&
+                    params.runtime.processExists(parseChildIdentity(params.paths, processRecord).hostPid);
+            }
+            catch {
+                return false;
+            }
+        })();
+        processRecord = {
+            ...processRecord,
+            status: liveAfterFailure ? 'starting' : 'failed',
+            updatedAt: params.now().toISOString(),
+            failure: error instanceof Error ? error.message.slice(0, 300) : 'community_native_child_launch_failed',
+        };
+        writeProcess(params.paths, processRecord);
+        throw error;
+    }
+    processRecord = { ...processRecord, status: 'running', updatedAt: params.now().toISOString() };
+    writeProcess(params.paths, processRecord);
+    if (params.mode === 'detached') {
+        handle.detach();
+        return { paths: params.paths, state: params.state, process: processRecord, migration, mode: params.mode };
+    }
+    return {
+        paths: params.paths,
+        state: params.state,
+        process: processRecord,
+        migration,
+        mode: params.mode,
+        waitForExit: async () => {
+            let aborted = params.signal?.aborted === true;
+            let onAbort;
+            let exit;
+            if (params.signal && !aborted) {
+                const outcome = await Promise.race([
+                    handle.wait.then((value) => ({ kind: 'exit', value })),
+                    new Promise((resolve) => {
+                        onAbort = () => resolve({ kind: 'abort' });
+                        params.signal.addEventListener('abort', onAbort, { once: true });
+                    }),
+                ]);
+                if (onAbort)
+                    params.signal.removeEventListener('abort', onAbort);
+                if (outcome.kind === 'abort') {
+                    aborted = true;
+                    await stopSpawnedNative({
+                        paths: params.paths,
+                        state: params.state,
+                        processRecord,
+                        handle,
+                        runtime: params.runtime,
+                        timeoutMs: DEFAULT_STOP_TIMEOUT_MS,
+                        now: params.now,
+                    });
+                    exit = await handle.wait;
+                }
+                else {
+                    exit = outcome.value;
+                }
+            }
+            else if (aborted) {
+                await stopSpawnedNative({
+                    paths: params.paths,
+                    state: params.state,
+                    processRecord,
+                    handle,
+                    runtime: params.runtime,
+                    timeoutMs: DEFAULT_STOP_TIMEOUT_MS,
+                    now: params.now,
+                });
+                exit = await handle.wait;
+            }
+            else {
+                exit = await handle.wait;
+            }
+            writeProcess(params.paths, {
+                ...processRecord,
+                status: !aborted && exit.exitCode === 0 ? 'exited' : 'failed',
+                updatedAt: params.now().toISOString(),
+                exitCode: exit.exitCode,
+                signal: exit.signal,
+                ...(!aborted && exit.exitCode === 0
+                    ? {}
+                    : { failure: aborted ? 'community_operation_aborted' : `community_native_child_exit:${exit.exitCode ?? exit.signal ?? 'unknown'}` }),
+            });
+            if (aborted)
+                throw new Error('community_operation_aborted');
+            if (exit.exitCode !== 0)
+                throw new Error(`community_native_child_failed:${exit.exitCode ?? exit.signal ?? 'unknown'}`);
+            return exit;
+        },
+    };
+}
+export async function setupCommunityNativeInstall(params) {
+    if (params.contract.runtime !== 'native')
+        throw new Error('community_native_contract_required');
+    if (params.contract.profile !== 'native-external-postgres' &&
+        params.contract.profile !== 'native-container-postgres')
+        throw new Error('community_native_postgres_contract_required');
+    const runtime = params.runtime ?? communityNativeRuntime;
+    throwIfNativeAborted(params.signal);
+    params.progress?.({
+        stage: 'runtime',
+        message: 'Validating the installed AOPS server runtime...',
+    });
+    const now = params.now ?? (() => new Date());
+    const createId = params.createId ?? randomUUID;
+    const paths = resolveCommunityNativePaths({ instanceName: params.contract.instanceId, dataRoot: params.dataRoot });
+    assertCommunityNativePathLayout(paths);
+    mkdirSync(paths.instanceRoot, { recursive: true, mode: 0o700 });
+    assertCommunityNativePathLayout(paths, { requireInstanceRoot: true });
+    if (existsSync(paths.ociStatePath))
+        throw new Error('community_instance_runtime_conflict:oci_already_installed');
+    const inspection = inspectCommunityNativeInstall({ instanceName: params.contract.instanceId, dataRoot: params.dataRoot });
+    if (inspection.status === 'partial' || inspection.status === 'runtime-conflict') {
+        throw new Error(`community_native_install_${inspection.status}:${inspection.error ?? 'unknown'}:run_doctor`);
+    }
+    const defaultSourceRoot = resolveCommunityNativeDefaultSourceRoot();
+    const source = inspectCommunityNativeSource(params.sourceRoot ?? defaultSourceRoot);
+    let configRef;
+    if (params.contract.profile === 'native-external-postgres') {
+        if (params.contract.postgres.mode !== 'external' || !params.contract.postgres.configRef ||
+            !params.contract.postgres.tlsPolicy)
+            throw new Error('community_native_external_postgres_contract_required');
+        const configInput = path.resolve(params.contract.postgres.configRef);
+        loadExternalPostgresUrl(configInput, params.contract.postgres.tlsPolicy);
+        configRef = realpathSync(configInput);
+    }
+    else if (params.contract.postgres.mode !== 'container') {
+        throw new Error('community_native_container_postgres_contract_required');
+    }
+    let priorApplicationReconciliation = 'current';
+    if (inspection.status === 'installed' && inspection.state) {
+        const observed = await observeInstalledNative({
+            paths: inspection.paths,
+            state: inspection.state,
+            processRecord: inspection.process ?? null,
+            runtime,
+            now,
+        });
+        if (observed.runtimeState !== 'stopped' && observed.runtimeState !== 'crashed') {
+            throw new Error(`community_native_process_active:${observed.runtimeState}:run_server_status_before_setup`);
+        }
+        priorApplicationReconciliation = reconcileCommunityNativePriorApplication({
+            state: inspection.state,
+            selectedSource: source,
+            contract: params.contract,
+            selectedExternalConfigRef: configRef,
+        });
+    }
+    if (!isPackagedCommunityServerSource(source)) {
+        await runBuildChecked(runtime, { ...buildCommunityPnpmInvocation(source.root, ['install', '--frozen-lockfile'], params.env), signal: params.signal }, 'install');
+        await runBuildChecked(runtime, { ...buildCommunityPnpmInvocation(source.root, ['run', 'build'], params.env), signal: params.signal }, 'build');
+    }
+    throwIfNativeAborted(params.signal);
+    const updatedAt = now().toISOString();
+    const build = inspectCommunityNativeBuild(source, updatedAt);
+    const existing = inspection.status === 'installed' ? inspection.state : undefined;
+    if (existing && existing.instanceName !== params.contract.instanceId)
+        throw new Error('community_native_instance_mismatch');
+    if (existing && existing.profile !== params.contract.profile) {
+        throw new Error(`community_native_profile_change_refused:${existing.profile}:to:${params.contract.profile}:run_server_reset`);
+    }
+    mkdirSync(paths.runtimeRoot, { recursive: true, mode: 0o700 });
+    const baseState = {
+        schemaVersion: 1,
+        runtime: 'native',
+        instanceName: params.contract.instanceId,
+        installId: existing?.installId ?? createId(),
+        createdAt: existing?.createdAt ?? updatedAt,
+        updatedAt,
+        source,
+        build,
+        server: {
+            host: params.contract.server.host,
+            port: params.contract.server.port,
+            exposure: params.contract.server.exposure,
+            publicPort: params.contract.server.publicPort,
+            authProvider: params.contract.server.authProvider,
+        },
+        cockpit: {
+            host: '127.0.0.1',
+            port: resolveCommunityNativeCockpitPort(params.contract.server.publicPort),
+        },
+    };
+    const state = params.contract.profile === 'native-external-postgres'
+        ? {
+            ...baseState,
+            profile: 'native-external-postgres',
+            postgres: {
+                mode: 'external',
+                configRef: configRef,
+                tlsPolicy: params.contract.postgres.tlsPolicy,
+            },
+        }
+        : {
+            ...baseState,
+            profile: 'native-container-postgres',
+            postgres: await setupCommunityNativePostgres({
+                sourceRoot: source.root,
+                instanceRoot: paths.instanceRoot,
+                runtimeRoot: paths.runtimeRoot,
+                instanceName: params.contract.instanceId,
+                runtime: params.postgresRuntime,
+                createSecret: params.createPostgresSecret,
+                readyTimeoutMs: params.readyTimeoutMs,
+                signal: params.signal,
+            }),
+        };
+    let applicationUpdatePrepared = null;
+    const sameSourceIdentity = existing !== undefined &&
+        samePhysicalPath(existing.source.root, state.source.root) &&
+        existing.source.sourceFingerprint === state.source.sourceFingerprint;
+    const inPlaceCheckoutRefresh = priorApplicationReconciliation === 'in-place-checkout-refresh';
+    const selectedCheckout = sourceLayout(state.source.root).kind === 'checkout';
+    let retryableInPlaceRefresh = false;
+    let refreshLaunchArtifacts = false;
+    if (existing) {
+        const priorReference = createCommunityNativeApplicationReferenceV1(existing);
+        const targetReference = createCommunityNativeApplicationReferenceV1(state);
+        const applicationContentChanged = !sameCommunityNativeApplicationContent(priorReference, targetReference);
+        refreshLaunchArtifacts = applicationContentChanged;
+        if (applicationContentChanged && sameSourceIdentity) {
+            if (!selectedCheckout)
+                throw new Error('community_native_prior_application_build_drift');
+            retryableInPlaceRefresh = true;
+        }
+        if (applicationContentChanged && !sameSourceIdentity) {
+            if (params.requireApplicationUpdate === true && !inPlaceCheckoutRefresh) {
+                applicationUpdatePrepared = writeCommunityNativeApplicationUpdatePrepared({
+                    paths,
+                    updateId: createId(),
+                    prior: existing,
+                    target: state,
+                    now,
+                });
+            }
+            else if (samePhysicalPath(existing.source.root, state.source.root)) {
+                retryableInPlaceRefresh = true;
+            }
+        }
+    }
+    if (params.requireApplicationUpdate === true && !applicationUpdatePrepared) {
+        throw new Error(existing
+            ? 'community_native_application_update_content_unchanged'
+            : 'community_native_application_update_requires_existing_install');
+    }
+    const setupFileSnapshots = captureCommunityNativeSetupFiles(paths);
+    const nativeSecretExisted = existsSync(paths.secretPath);
+    let launch;
+    try {
+        if (refreshLaunchArtifacts)
+            removeCommunityNativeLaunchArtifactsForRefresh(paths);
+        ensureNativeSecret(paths, params.createSecret ?? (() => randomBytes(32).toString('base64url')));
+        atomicJsonWrite(paths.statePath, state);
+        throwIfNativeAborted(params.signal);
+        launch = await launchInstalledNative({
+            paths,
+            state,
+            mode: params.mode ?? 'detached',
+            runtime,
+            postgresRuntime: params.postgresRuntime,
+            now,
+            createId,
+            readyTimeoutMs: params.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+            progress: params.progress,
+            env: params.env,
+            signal: params.signal,
+        });
+        if (applicationUpdatePrepared) {
+            writeCommunityNativeApplicationUpdateOutcome({
+                paths,
+                updateId: applicationUpdatePrepared.updateId,
+                receipt: launch.migration,
+                now,
+            });
+        }
+    }
+    catch (error) {
+        let restoreFailure;
+        if (!launch) {
+            try {
+                restoreCommunityNativeSetupFiles(paths, setupFileSnapshots);
+                if (retryableInPlaceRefresh && existing) {
+                    atomicJsonWrite(paths.statePath, state);
+                    removeCommunityNativeLaunchArtifactsForRefresh(paths);
+                }
+            }
+            catch (restoreError) {
+                restoreFailure = restoreError;
+            }
+            if (!nativeSecretExisted) {
+                try {
+                    removeNewCommunityNativeSecret(paths);
+                }
+                catch (secretRestoreError) {
+                    restoreFailure = restoreFailure
+                        ? new AggregateError([restoreFailure, secretRestoreError])
+                        : secretRestoreError;
+                }
+            }
+        }
+        if (applicationUpdatePrepared) {
+            let succeededOutcomeDurable = false;
+            try {
+                succeededOutcomeDurable = readCommunityNativeApplicationUpdate(paths, applicationUpdatePrepared.updateId)
+                    .outcome?.status === 'community-native-application-update-succeeded';
+            }
+            catch { }
+            if (!succeededOutcomeDurable) {
+                writeCommunityNativeApplicationUpdateOutcome({
+                    paths,
+                    updateId: applicationUpdatePrepared.updateId,
+                    receipt: launch?.migration,
+                    error,
+                    now,
+                });
+            }
+        }
+        if (restoreFailure) {
+            throw new Error('community_native_setup_local_state_restore_failed', {
+                cause: new AggregateError([error, restoreFailure]),
+            });
+        }
+        throw error;
+    }
+    if (!launch)
+        throw new Error('community_native_application_launch_missing');
+    return {
+        status: existing ? 'refreshed' : 'created',
+        paths,
+        state,
+        launch,
+        applicationUpdate: applicationUpdatePrepared
+            ? readCommunityNativeApplicationUpdate(paths, applicationUpdatePrepared.updateId)
+            : null,
+    };
+}
+export async function rollbackCommunityNativeApplication(params) {
+    throwIfNativeAborted(params.signal);
+    const runtime = params.runtime ?? communityNativeRuntime;
+    const now = params.now ?? (() => new Date());
+    const createId = params.createId ?? randomUUID;
+    const inspection = inspectCommunityNativeInstall({ instanceName: params.instanceName, dataRoot: params.dataRoot });
+    if (inspection.status !== 'installed' || !inspection.state) {
+        throw new Error(`community_native_not_installed:${inspection.status}:${inspection.error ?? 'run_server_setup'}`);
+    }
+    assertCommunityNativeApplicationCurrent(inspection.state);
+    const observed = await observeInstalledNative({
+        paths: inspection.paths,
+        state: inspection.state,
+        processRecord: inspection.process ?? null,
+        runtime,
+        now,
+    });
+    if (observed.runtimeState !== 'stopped' && observed.runtimeState !== 'crashed') {
+        throw new Error(`community_native_process_active:${observed.runtimeState}:run_server_stop_before_rollback`);
+    }
+    const update = readCommunityNativeApplicationUpdate(inspection.paths, params.updateId);
+    if (update.prepared.instanceName !== inspection.state.instanceName ||
+        update.prepared.installId !== inspection.state.installId) {
+        throw new Error('community_native_application_update_instance_mismatch');
+    }
+    if (update.rollbackPrepared || update.rollbackOutcome) {
+        throw new Error('community_native_application_rollback_already_recorded');
+    }
+    const activeReference = createCommunityNativeApplicationReferenceV1(inspection.state);
+    if (!sameCommunityNativeApplicationContent(activeReference, update.prepared.target)) {
+        throw new Error('community_native_application_update_target_not_active');
+    }
+    const source = inspectCommunityNativeSource(params.sourceRoot);
+    if (!isPackagedCommunityServerSource(source)) {
+        await runBuildChecked(runtime, { ...buildCommunityPnpmInvocation(source.root, ['install', '--frozen-lockfile'], params.env), signal: params.signal }, 'rollback_install');
+        await runBuildChecked(runtime, { ...buildCommunityPnpmInvocation(source.root, ['run', 'build'], params.env), signal: params.signal }, 'rollback_build');
+    }
+    throwIfNativeAborted(params.signal);
+    const updatedAt = now().toISOString();
+    const build = inspectCommunityNativeBuild(source, updatedAt);
+    const candidateState = inspection.state.profile === 'native-external-postgres'
+        ? {
+            ...inspection.state,
+            updatedAt,
+            source,
+            build,
+        }
+        : {
+            ...inspection.state,
+            updatedAt,
+            source,
+            build,
+        };
+    const candidateReference = createCommunityNativeApplicationReferenceV1(candidateState);
+    if (!sameCommunityNativeApplicationContent(candidateReference, update.prepared.prior)) {
+        throw new Error('community_native_application_rollback_source_content_mismatch');
+    }
+    const postgresUrl = candidateState.profile === 'native-external-postgres'
+        ? loadExternalPostgresUrl(candidateState.postgres.configRef, candidateState.postgres.tlsPolicy)
+        : await (async () => {
+            await startCommunityNativePostgres({
+                state: candidateState.postgres,
+                instanceName: candidateState.instanceName,
+                instanceRoot: inspection.paths.instanceRoot,
+                runtime: params.postgresRuntime,
+                signal: params.signal,
+            });
+            return buildCommunityNativePostgresUrl(candidateState.postgres);
+        })();
+    const databasePlan = await (params.planMigration ?? planCommunityNativeMigration)({
+        sourceRoot: candidateState.source.root,
+        repoUrl: postgresUrl,
+        signal: params.signal,
+    });
+    throwIfNativeAborted(params.signal);
+    if (databasePlan.planning.migrationPlan.action !== 'verify-only') {
+        throw new Error(`community_native_database_restore_required:update=${params.updateId}:action=${databasePlan.planning.migrationPlan.action}`);
+    }
+    const rollbackId = createId();
+    writeCommunityNativeApplicationRollbackPrepared({
+        paths: inspection.paths,
+        updateId: params.updateId,
+        rollbackId,
+        candidate: candidateReference,
+        databasePlan: {
+            action: 'verify-only',
+            acceptedPlanSha256: databasePlan.planning.acceptedPlanSha256,
+            sourceMigrationStateFingerprintSha256: databasePlan.planning.sourceFingerprintSha256,
+            stateFingerprintSha256: databasePlan.planning.stateFingerprintSha256,
+        },
+        now,
+    });
+    let launch;
+    try {
+        atomicJsonWrite(inspection.paths.statePath, candidateState);
+        launch = await launchInstalledNative({
+            paths: inspection.paths,
+            state: candidateState,
+            mode: params.mode ?? 'detached',
+            runtime,
+            postgresRuntime: params.postgresRuntime,
+            now,
+            createId,
+            readyTimeoutMs: params.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+            env: params.env,
+            requiredMigrationPlanSha256: databasePlan.planning.acceptedPlanSha256,
+            requiredMigrationAction: 'verify-only',
+            signal: params.signal,
+        });
+        writeCommunityNativeApplicationRollbackOutcome({
+            paths: inspection.paths,
+            updateId: params.updateId,
+            rollbackId,
+            receipt: launch.migration,
+            now,
+        });
+    }
+    catch (error) {
+        let succeededOutcomeDurable = false;
+        try {
+            succeededOutcomeDurable = readCommunityNativeApplicationUpdate(inspection.paths, params.updateId)
+                .rollbackOutcome?.status === 'community-native-application-rolled-back';
+        }
+        catch { }
+        if (!succeededOutcomeDurable) {
+            writeCommunityNativeApplicationRollbackOutcome({
+                paths: inspection.paths,
+                updateId: params.updateId,
+                rollbackId,
+                receipt: launch?.migration,
+                error,
+                now,
+            });
+        }
+        throw error;
+    }
+    if (!launch)
+        throw new Error('community_native_application_rollback_launch_missing');
+    return {
+        paths: inspection.paths,
+        state: candidateState,
+        launch,
+        applicationUpdate: readCommunityNativeApplicationUpdate(inspection.paths, params.updateId),
+    };
+}
+export async function startCommunityNativeInstall(params) {
+    const inspection = inspectCommunityNativeInstall({ instanceName: params.instanceName, dataRoot: params.dataRoot });
+    if (inspection.status !== 'installed' || !inspection.state) {
+        throw new Error(`community_native_not_installed:${inspection.status}:${inspection.error ?? 'run_server_setup'}`);
+    }
+    return launchInstalledNative({
+        paths: inspection.paths,
+        state: inspection.state,
+        mode: params.mode ?? 'detached',
+        runtime: params.runtime ?? communityNativeRuntime,
+        postgresRuntime: params.postgresRuntime,
+        now: params.now ?? (() => new Date()),
+        createId: params.createId ?? randomUUID,
+        readyTimeoutMs: params.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+        env: params.env,
+        signal: params.signal,
+    });
+}