@aopslabs/aops 0.2.0

package/dist/lib/community-native-application-recovery.js

@@ -0,0 +1,425 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { compareCanonicalText } from '@aopslabs/artifact-trust-contracts';
+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 SHA256 = /^sha256:[a-f0-9]{64}$/;
+const RAW_SHA256 = /^[a-f0-9]{64}$/;
+const INSTANCE_NAME = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+const MAX_RECORD_BYTES = 1024 * 1024;
+function sha256Json(value) {
+    return `sha256:${createHash('sha256').update(JSON.stringify(value)).digest('hex')}`;
+}
+function samePath(left, right) {
+    const a = path.resolve(left);
+    const b = path.resolve(right);
+    return process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b;
+}
+function fsyncDirectoryBestEffortOnWindows(directory) {
+    let descriptor;
+    try {
+        descriptor = openSync(directory, 'r');
+        fsyncSync(descriptor);
+    }
+    catch (error) {
+        const code = String(error?.code ?? '');
+        if (process.platform !== 'win32' || !['EACCES', 'EBADF', 'EINVAL', 'EISDIR', 'EPERM'].includes(code))
+            throw error;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function ensureRecordRoot(paths) {
+    const root = path.resolve(paths.applicationUpdateRoot);
+    if (!samePath(path.dirname(root), paths.runtimeRoot)) {
+        throw new Error('community_native_application_update_root_unsafe');
+    }
+    const existed = existsSync(root);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const stats = lstatSync(root);
+    if (!stats.isDirectory() || stats.isSymbolicLink() || !samePath(realpathSync.native(root), root)) {
+        throw new Error('community_native_application_update_root_unsafe');
+    }
+    if (!existed)
+        fsyncDirectoryBestEffortOnWindows(paths.runtimeRoot);
+    return root;
+}
+function writeExclusive(paths, fileName, value) {
+    const root = ensureRecordRoot(paths);
+    const target = path.join(root, fileName);
+    if (!samePath(path.dirname(target), root) || existsSync(target)) {
+        throw new Error('community_native_application_recovery_record_already_exists');
+    }
+    const temp = path.join(root, `.${fileName}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    let descriptor;
+    try {
+        descriptor = openSync(temp, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+        writeFileSync(descriptor, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8' });
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        try {
+            linkSync(temp, target);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                throw new Error('community_native_application_recovery_record_already_exists');
+            }
+            throw error;
+        }
+        fsyncDirectoryBestEffortOnWindows(root);
+        rmSync(temp, { force: true });
+        fsyncDirectoryBestEffortOnWindows(root);
+        return target;
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        rmSync(temp, { force: true });
+    }
+}
+function readRecord(paths, fileName) {
+    const root = ensureRecordRoot(paths);
+    const target = path.join(root, fileName);
+    if (!existsSync(target))
+        return null;
+    const stats = lstatSync(target, { bigint: true });
+    if (!stats.isFile() || stats.isSymbolicLink() || stats.size < 1n || stats.size > BigInt(MAX_RECORD_BYTES) ||
+        !samePath(realpathSync.native(target), target) || !samePath(path.dirname(target), root)) {
+        throw new Error('community_native_application_recovery_record_unsafe');
+    }
+    let descriptor;
+    try {
+        const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+        descriptor = openSync(target, constants.O_RDONLY | noFollow);
+        const before = fstatSync(descriptor, { bigint: true });
+        if (before.dev !== stats.dev || before.ino !== stats.ino || before.size !== stats.size || before.nlink !== 1n) {
+            throw new Error('community_native_application_recovery_record_unsafe');
+        }
+        const value = JSON.parse(readFileSync(descriptor, 'utf8'));
+        const after = fstatSync(descriptor, { bigint: true });
+        if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size ||
+            after.nlink !== before.nlink || after.mtimeNs !== before.mtimeNs) {
+            throw new Error('community_native_application_recovery_record_unsafe');
+        }
+        return value;
+    }
+    catch {
+        throw new Error('community_native_application_recovery_record_invalid');
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+function exactKeys(value, expected, code) {
+    const keys = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (keys.length !== wanted.length || keys.some((key, index) => key !== wanted[index]))
+        throw new Error(code);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function assertReference(value) {
+    if (!isRecord(value))
+        throw new Error('community_native_application_reference_invalid');
+    exactKeys(value, ['sourceRoot', 'sourceFingerprint', 'buildFingerprint', 'content'], 'community_native_application_reference_invalid');
+    if (!path.isAbsolute(String(value.sourceRoot)) || !SHA256.test(String(value.sourceFingerprint)) ||
+        !SHA256.test(String(value.buildFingerprint)) || !isRecord(value.content)) {
+        throw new Error('community_native_application_reference_invalid');
+    }
+    exactKeys(value.content, [
+        'schemaVersion', 'releaseVersion', 'packageSha256', 'lockfileSha256', 'sourceFileCount',
+        'sourceInventorySha256', 'hostEntrySha256', 'handlerEntrySha256', 'cockpitIndexSha256',
+        'runtimeFileCount', 'runtimeInventorySha256', 'applicationContentSha256',
+    ], 'community_native_application_content_invalid');
+    if (value.content.schemaVersion !== 1 || typeof value.content.releaseVersion !== 'string' ||
+        !Number.isSafeInteger(value.content.sourceFileCount) || value.content.sourceFileCount < 1 ||
+        !Number.isSafeInteger(value.content.runtimeFileCount) || value.content.runtimeFileCount < 1 ||
+        ![
+            value.content.packageSha256, value.content.lockfileSha256, value.content.sourceInventorySha256,
+            value.content.hostEntrySha256, value.content.handlerEntrySha256, value.content.cockpitIndexSha256,
+            value.content.runtimeInventorySha256, value.content.applicationContentSha256,
+        ].every((item) => SHA256.test(String(item)))) {
+        throw new Error('community_native_application_content_invalid');
+    }
+    const content = { ...value.content };
+    const claimed = content.applicationContentSha256;
+    delete content.applicationContentSha256;
+    if (sha256Json(content) !== claimed)
+        throw new Error('community_native_application_content_hash_mismatch');
+    return value;
+}
+function migrationSummary(receipt) {
+    return {
+        action: receipt.action,
+        acceptedPlanSha256: receipt.acceptedPlanSha256,
+        sourceMigrationStateFingerprintSha256: receipt.sourceMigrationStateFingerprintSha256,
+        resultMigrationStateFingerprintSha256: receipt.resultMigrationStateFingerprintSha256,
+        snapshotEvidenceKind: receipt.snapshotEvidenceKind,
+        snapshotEvidenceSha256: receipt.snapshotEvidenceSha256,
+    };
+}
+function assertMigrationSummary(value) {
+    if (!isRecord(value))
+        throw new Error('community_native_application_migration_summary_invalid');
+    exactKeys(value, [
+        'action', 'acceptedPlanSha256', 'sourceMigrationStateFingerprintSha256',
+        'resultMigrationStateFingerprintSha256', 'snapshotEvidenceKind', 'snapshotEvidenceSha256',
+    ], 'community_native_application_migration_summary_invalid');
+    if (!['migrate', 'verify-only'].includes(String(value.action)) ||
+        ![value.acceptedPlanSha256, value.sourceMigrationStateFingerprintSha256,
+            value.resultMigrationStateFingerprintSha256].every((item) => RAW_SHA256.test(String(item))) ||
+        !['managed-verified-backup', 'external-snapshot-attestation', null].includes(value.snapshotEvidenceKind) ||
+        (value.snapshotEvidenceSha256 !== null && !RAW_SHA256.test(String(value.snapshotEvidenceSha256))) ||
+        (value.snapshotEvidenceKind === null) !== (value.snapshotEvidenceSha256 === null)) {
+        throw new Error('community_native_application_migration_summary_invalid');
+    }
+    return value;
+}
+function assertUpdateOutcome(value, updateId) {
+    if (!isRecord(value))
+        throw new Error('community_native_application_update_outcome_invalid');
+    exactKeys(value, ['schemaVersion', 'status', 'updateId', 'completedAt', 'migration', 'failure'], 'community_native_application_update_outcome_invalid');
+    if (value.schemaVersion !== 1 || value.updateId !== updateId ||
+        !['community-native-application-update-succeeded', 'community-native-application-update-failed'].includes(String(value.status)) ||
+        Number.isNaN(Date.parse(String(value.completedAt)))) {
+        throw new Error('community_native_application_update_outcome_invalid');
+    }
+    if (value.status === 'community-native-application-update-succeeded') {
+        if (value.failure !== null)
+            throw new Error('community_native_application_update_outcome_invalid');
+        return { ...value, migration: assertMigrationSummary(value.migration) };
+    }
+    if (typeof value.failure !== 'string' || value.failure.length < 1 || value.failure.length > 300) {
+        throw new Error('community_native_application_update_outcome_invalid');
+    }
+    return {
+        ...value,
+        migration: value.migration === null ? null : assertMigrationSummary(value.migration),
+    };
+}
+function assertRollbackPrepared(value, updateId) {
+    if (!isRecord(value))
+        throw new Error('community_native_application_rollback_prepared_invalid');
+    exactKeys(value, ['schemaVersion', 'status', 'updateId', 'rollbackId', 'createdAt', 'candidate', 'databasePlan'], 'community_native_application_rollback_prepared_invalid');
+    if (value.schemaVersion !== 1 || value.status !== 'community-native-application-rollback-prepared' ||
+        value.updateId !== updateId || !UUID.test(String(value.rollbackId)) ||
+        Number.isNaN(Date.parse(String(value.createdAt))) || !isRecord(value.databasePlan)) {
+        throw new Error('community_native_application_rollback_prepared_invalid');
+    }
+    exactKeys(value.databasePlan, [
+        'action', 'acceptedPlanSha256', 'sourceMigrationStateFingerprintSha256', 'stateFingerprintSha256',
+    ], 'community_native_application_rollback_prepared_invalid');
+    if (value.databasePlan.action !== 'verify-only' ||
+        ![value.databasePlan.acceptedPlanSha256, value.databasePlan.sourceMigrationStateFingerprintSha256,
+            value.databasePlan.stateFingerprintSha256].every((item) => RAW_SHA256.test(String(item)))) {
+        throw new Error('community_native_application_rollback_prepared_invalid');
+    }
+    return {
+        ...value,
+        candidate: assertReference(value.candidate),
+    };
+}
+function assertRollbackOutcome(value, updateId, rollbackId) {
+    if (!isRecord(value))
+        throw new Error('community_native_application_rollback_outcome_invalid');
+    exactKeys(value, ['schemaVersion', 'status', 'updateId', 'rollbackId', 'completedAt', 'migration', 'failure'], 'community_native_application_rollback_outcome_invalid');
+    if (value.schemaVersion !== 1 || value.updateId !== updateId || value.rollbackId !== rollbackId ||
+        !['community-native-application-rolled-back', 'community-native-application-rollback-failed'].includes(String(value.status)) ||
+        Number.isNaN(Date.parse(String(value.completedAt)))) {
+        throw new Error('community_native_application_rollback_outcome_invalid');
+    }
+    if (value.status === 'community-native-application-rolled-back') {
+        if (value.failure !== null)
+            throw new Error('community_native_application_rollback_outcome_invalid');
+        return { ...value, migration: assertMigrationSummary(value.migration) };
+    }
+    if (typeof value.failure !== 'string' || value.failure.length < 1 || value.failure.length > 300) {
+        throw new Error('community_native_application_rollback_outcome_invalid');
+    }
+    return {
+        ...value,
+        migration: value.migration === null ? null : assertMigrationSummary(value.migration),
+    };
+}
+export function createCommunityNativeApplicationReferenceV1(input) {
+    const contentBase = {
+        schemaVersion: 1,
+        releaseVersion: input.source.releaseVersion,
+        packageSha256: input.source.packageSha256,
+        lockfileSha256: input.source.lockfileSha256,
+        sourceFileCount: input.source.sourceFileCount,
+        sourceInventorySha256: input.source.sourceInventorySha256,
+        hostEntrySha256: input.build.hostEntrySha256,
+        handlerEntrySha256: input.build.handlerEntrySha256,
+        cockpitIndexSha256: input.build.cockpitIndexSha256,
+        runtimeFileCount: input.build.runtimeFileCount,
+        runtimeInventorySha256: input.build.runtimeInventorySha256,
+    };
+    return assertReference({
+        sourceRoot: input.source.root,
+        sourceFingerprint: input.source.sourceFingerprint,
+        buildFingerprint: input.build.buildFingerprint,
+        content: { ...contentBase, applicationContentSha256: sha256Json(contentBase) },
+    });
+}
+export function sameCommunityNativeApplicationContent(left, right) {
+    return left.content.applicationContentSha256 === right.content.applicationContentSha256;
+}
+export function writeCommunityNativeApplicationUpdatePrepared(params) {
+    if (!UUID.test(params.updateId) || params.prior.instanceName !== params.target.instanceName ||
+        params.prior.installId !== params.target.installId) {
+        throw new Error('community_native_application_update_identity_invalid');
+    }
+    const prepared = {
+        schemaVersion: 1,
+        status: 'community-native-application-update-prepared',
+        updateId: params.updateId,
+        instanceName: params.target.instanceName,
+        installId: params.target.installId,
+        createdAt: (params.now ?? (() => new Date()))().toISOString(),
+        prior: createCommunityNativeApplicationReferenceV1(params.prior),
+        target: createCommunityNativeApplicationReferenceV1(params.target),
+    };
+    if (sameCommunityNativeApplicationContent(prepared.prior, prepared.target)) {
+        throw new Error('community_native_application_update_content_unchanged');
+    }
+    writeExclusive(params.paths, `${params.updateId}.prepared.json`, prepared);
+    return prepared;
+}
+export function writeCommunityNativeApplicationUpdateOutcome(params) {
+    const succeeded = params.error === undefined;
+    if (!UUID.test(params.updateId) || (succeeded && !params.receipt) || (!succeeded && params.error === undefined)) {
+        throw new Error('community_native_application_update_outcome_invalid');
+    }
+    const outcome = {
+        schemaVersion: 1,
+        status: succeeded
+            ? 'community-native-application-update-succeeded'
+            : 'community-native-application-update-failed',
+        updateId: params.updateId,
+        completedAt: (params.now ?? (() => new Date()))().toISOString(),
+        migration: params.receipt ? migrationSummary(params.receipt) : null,
+        failure: succeeded ? null :
+            (String(params.error instanceof Error ? params.error.message : params.error).slice(0, 300) ||
+                'community_native_application_update_failed'),
+    };
+    writeExclusive(params.paths, `${params.updateId}.${succeeded ? 'succeeded' : 'failed'}.json`, outcome);
+    return outcome;
+}
+export function writeCommunityNativeApplicationRollbackPrepared(params) {
+    if (!UUID.test(params.updateId) || !UUID.test(params.rollbackId) || params.databasePlan.action !== 'verify-only' ||
+        ![params.databasePlan.acceptedPlanSha256, params.databasePlan.sourceMigrationStateFingerprintSha256,
+            params.databasePlan.stateFingerprintSha256].every((value) => RAW_SHA256.test(value))) {
+        throw new Error('community_native_application_rollback_prepared_invalid');
+    }
+    const prepared = {
+        schemaVersion: 1,
+        status: 'community-native-application-rollback-prepared',
+        updateId: params.updateId,
+        rollbackId: params.rollbackId,
+        createdAt: (params.now ?? (() => new Date()))().toISOString(),
+        candidate: assertReference(params.candidate),
+        databasePlan: params.databasePlan,
+    };
+    writeExclusive(params.paths, `${params.updateId}.${params.rollbackId}.rollback-prepared.json`, prepared);
+    return prepared;
+}
+export function writeCommunityNativeApplicationRollbackOutcome(params) {
+    const succeeded = params.error === undefined;
+    if (!UUID.test(params.updateId) || !UUID.test(params.rollbackId) ||
+        (succeeded && !params.receipt) || (!succeeded && params.error === undefined)) {
+        throw new Error('community_native_application_rollback_outcome_invalid');
+    }
+    const outcome = {
+        schemaVersion: 1,
+        status: succeeded
+            ? 'community-native-application-rolled-back'
+            : 'community-native-application-rollback-failed',
+        updateId: params.updateId,
+        rollbackId: params.rollbackId,
+        completedAt: (params.now ?? (() => new Date()))().toISOString(),
+        migration: params.receipt ? migrationSummary(params.receipt) : null,
+        failure: succeeded ? null :
+            (String(params.error instanceof Error ? params.error.message : params.error).slice(0, 300) ||
+                'community_native_application_rollback_failed'),
+    };
+    writeExclusive(params.paths, `${params.updateId}.${params.rollbackId}.${succeeded ? 'rolled-back' : 'rollback-failed'}.json`, outcome);
+    return outcome;
+}
+export function readCommunityNativeApplicationUpdate(paths, updateId) {
+    if (!UUID.test(updateId))
+        throw new Error('community_native_application_update_id_invalid');
+    const rawPrepared = readRecord(paths, `${updateId}.prepared.json`);
+    if (!isRecord(rawPrepared))
+        throw new Error('community_native_application_update_not_found');
+    exactKeys(rawPrepared, ['schemaVersion', 'status', 'updateId', 'instanceName', 'installId', 'createdAt', 'prior', 'target'], 'community_native_application_update_record_invalid');
+    if (rawPrepared.schemaVersion !== 1 || rawPrepared.status !== 'community-native-application-update-prepared' ||
+        rawPrepared.updateId !== updateId || !INSTANCE_NAME.test(String(rawPrepared.instanceName)) ||
+        !UUID.test(String(rawPrepared.installId)) ||
+        Number.isNaN(Date.parse(String(rawPrepared.createdAt)))) {
+        throw new Error('community_native_application_update_record_invalid');
+    }
+    const prepared = { ...rawPrepared, prior: assertReference(rawPrepared.prior), target: assertReference(rawPrepared.target) };
+    if (sameCommunityNativeApplicationContent(prepared.prior, prepared.target)) {
+        throw new Error('community_native_application_update_content_unchanged');
+    }
+    const succeeded = readRecord(paths, `${updateId}.succeeded.json`);
+    const failed = readRecord(paths, `${updateId}.failed.json`);
+    if (succeeded && failed)
+        throw new Error('community_native_application_update_outcome_conflict');
+    const rawOutcome = succeeded ?? failed;
+    const outcome = rawOutcome === null ? null : assertUpdateOutcome(rawOutcome, updateId);
+    const rollbackCandidates = existsSync(paths.applicationUpdateRoot)
+        ? readdirSync(paths.applicationUpdateRoot)
+            .filter((name) => name.startsWith(`${updateId}.`) && name.endsWith('.rollback-prepared.json'))
+        : [];
+    if (rollbackCandidates.length > 1)
+        throw new Error('community_native_application_rollback_ambiguous');
+    const rollbackPrepared = rollbackCandidates[0]
+        ? assertRollbackPrepared(readRecord(paths, rollbackCandidates[0]), updateId)
+        : null;
+    if (rollbackPrepared && !sameCommunityNativeApplicationContent(rollbackPrepared.candidate, prepared.prior)) {
+        throw new Error('community_native_application_rollback_candidate_mismatch');
+    }
+    let rollbackOutcome = null;
+    if (rollbackPrepared) {
+        const rolledBack = readRecord(paths, `${updateId}.${rollbackPrepared.rollbackId}.rolled-back.json`);
+        const rollbackFailed = readRecord(paths, `${updateId}.${rollbackPrepared.rollbackId}.rollback-failed.json`);
+        if (rolledBack && rollbackFailed)
+            throw new Error('community_native_application_rollback_outcome_conflict');
+        const rawRollbackOutcome = rolledBack ?? rollbackFailed;
+        rollbackOutcome = rawRollbackOutcome === null
+            ? null
+            : assertRollbackOutcome(rawRollbackOutcome, updateId, rollbackPrepared.rollbackId);
+    }
+    return { prepared, outcome, rollbackPrepared, rollbackOutcome };
+}
+export function inspectCommunityNativeApplicationRecoveryStatus(paths) {
+    if (!existsSync(paths.applicationUpdateRoot))
+        return null;
+    const root = ensureRecordRoot(paths);
+    const records = readdirSync(root)
+        .filter((name) => UUID.test(name.slice(0, -'.prepared.json'.length)) && name.endsWith('.prepared.json'))
+        .map((name) => readCommunityNativeApplicationUpdate(paths, name.slice(0, -'.prepared.json'.length)))
+        .sort((left, right) => {
+        const byTime = Date.parse(right.prepared.createdAt) - Date.parse(left.prepared.createdAt);
+        return byTime === 0 ? compareCanonicalText(right.prepared.updateId, left.prepared.updateId) : byTime;
+    });
+    const latest = records[0];
+    if (!latest)
+        return null;
+    return {
+        updateId: latest.prepared.updateId,
+        preparedAt: latest.prepared.createdAt,
+        updateStatus: latest.outcome?.status ?? latest.prepared.status,
+        updateCompletedAt: latest.outcome?.completedAt ?? null,
+        rollbackId: latest.rollbackPrepared?.rollbackId ?? null,
+        rollbackStatus: latest.rollbackOutcome?.status ?? latest.rollbackPrepared?.status ?? null,
+        rollbackCompletedAt: latest.rollbackOutcome?.completedAt ?? null,
+    };
+}

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

@@ -0,0 +1,240 @@
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const COMMUNITY_NATIVE_CHILD_PROTOCOL = 'aops-community-native-child-v1';
+export const COMMUNITY_NATIVE_CONTROL_PROTOCOL = 'aops-community-native-control-v1';
+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 SHA256 = /^sha256:[a-f0-9]{64}$/;
+const HOST_STOP_GRACE_MS = 2_000;
+function requiredEnv(env, key) {
+    const value = String(env[key] ?? '').trim();
+    if (!value)
+        throw new Error(`community_native_child_env_required:${key}`);
+    return value;
+}
+function parsePort(value) {
+    if (!/^[1-9]\d{0,4}$/.test(value) || Number(value) > 65_535) {
+        throw new Error('community_native_child_port_invalid');
+    }
+    return Number(value);
+}
+function atomicJsonWrite(targetPath, value) {
+    const parent = path.dirname(targetPath);
+    if (!existsSync(parent))
+        throw new Error('community_native_child_identity_parent_missing');
+    const tempPath = path.join(parent, `.${path.basename(targetPath)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        renameSync(tempPath, targetPath);
+    }
+    finally {
+        rmSync(tempPath, { force: true });
+    }
+}
+export function buildCommunityNativeChildIdentity(env = process.env, pid = process.pid, hostPid = pid) {
+    const launchId = requiredEnv(env, 'AOPS_NATIVE_LAUNCH_ID');
+    const startedAt = requiredEnv(env, 'AOPS_NATIVE_STARTED_AT');
+    const sourceFingerprint = requiredEnv(env, 'AOPS_NATIVE_SOURCE_FINGERPRINT');
+    const hostEntry = path.resolve(requiredEnv(env, 'AOPS_NATIVE_HOST_ENTRY'));
+    const controlPathInput = requiredEnv(env, 'AOPS_NATIVE_CONTROL_PATH');
+    if (!path.isAbsolute(controlPathInput))
+        throw new Error('community_native_child_control_path_invalid');
+    const controlPath = path.resolve(controlPathInput);
+    if (!UUID.test(launchId))
+        throw new Error('community_native_child_launch_id_invalid');
+    if (!Number.isSafeInteger(pid) || pid < 1 || !Number.isSafeInteger(hostPid) || hostPid < 1) {
+        throw new Error('community_native_child_pid_invalid');
+    }
+    if (Number.isNaN(Date.parse(startedAt)))
+        throw new Error('community_native_child_started_at_invalid');
+    if (!SHA256.test(sourceFingerprint))
+        throw new Error('community_native_child_source_fingerprint_invalid');
+    if (!path.isAbsolute(hostEntry))
+        throw new Error('community_native_child_host_entry_invalid');
+    return {
+        schemaVersion: 1,
+        protocol: COMMUNITY_NATIVE_CHILD_PROTOCOL,
+        launchId,
+        pid,
+        hostPid,
+        startedAt,
+        sourceFingerprint,
+        hostEntry,
+        controlPath,
+        port: parsePort(requiredEnv(env, 'AOPS_NATIVE_PORT')),
+    };
+}
+function removeIdentityIfOwned(identityPath, launchId) {
+    try {
+        const parsed = JSON.parse(readFileSync(identityPath, 'utf8'));
+        if (parsed.protocol === COMMUNITY_NATIVE_CHILD_PROTOCOL && parsed.launchId === launchId) {
+            rmSync(identityPath, { force: true });
+        }
+    }
+    catch {
+    }
+}
+function readOwnedStopRequest(controlPath, launchId) {
+    try {
+        const parsed = JSON.parse(readFileSync(controlPath, 'utf8'));
+        if (parsed.schemaVersion !== 1 || parsed.protocol !== COMMUNITY_NATIVE_CONTROL_PROTOCOL ||
+            parsed.launchId !== launchId || parsed.command !== 'stop' ||
+            Number.isNaN(Date.parse(String(parsed.requestedAt))) ||
+            Object.keys(parsed).sort().join(',') !== 'command,launchId,protocol,requestedAt,schemaVersion')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function removeControlIfOwned(controlPath, launchId) {
+    if (readOwnedStopRequest(controlPath, launchId))
+        rmSync(controlPath, { force: true });
+}
+function spawnCommunityNativeHost(hostEntry, env) {
+    return spawn(process.execPath, [hostEntry], {
+        cwd: process.cwd(),
+        env,
+        detached: false,
+        windowsHide: true,
+        stdio: 'inherit',
+    });
+}
+async function waitForHostSpawn(host) {
+    await new Promise((resolve, reject) => {
+        const onSpawn = () => {
+            host.off('error', onError);
+            resolve();
+        };
+        const onError = (error) => {
+            host.off('spawn', onSpawn);
+            reject(error);
+        };
+        host.once('spawn', onSpawn);
+        host.once('error', onError);
+    });
+}
+function observeHostOutcome(host) {
+    if (host.exitCode !== null || host.signalCode !== null) {
+        return Promise.resolve({
+            kind: 'exit',
+            value: { exitCode: host.exitCode, signal: host.signalCode },
+        });
+    }
+    return new Promise((resolve) => {
+        const onExit = (exitCode, signal) => {
+            host.off('error', onError);
+            resolve({ kind: 'exit', value: { exitCode, signal } });
+        };
+        const onError = (error) => {
+            host.off('exit', onExit);
+            resolve({ kind: 'error', error });
+        };
+        host.once('exit', onExit);
+        host.once('error', onError);
+    });
+}
+async function terminateAndReapHost(host) {
+    if (host.exitCode !== null || host.signalCode !== null)
+        return;
+    const exited = new Promise((resolve) => {
+        host.once('exit', () => resolve());
+    });
+    host.kill('SIGKILL');
+    await exited;
+}
+export async function runCommunityNativeChild(env = process.env, runtime = {}) {
+    const identityPathInput = requiredEnv(env, 'AOPS_NATIVE_IDENTITY_PATH');
+    if (!path.isAbsolute(identityPathInput))
+        throw new Error('community_native_child_identity_path_invalid');
+    const identityPath = path.resolve(identityPathInput);
+    const controlPathInput = requiredEnv(env, 'AOPS_NATIVE_CONTROL_PATH');
+    if (!path.isAbsolute(controlPathInput))
+        throw new Error('community_native_child_control_path_invalid');
+    const controlPath = path.resolve(controlPathInput);
+    const hostEntry = path.resolve(requiredEnv(env, 'AOPS_NATIVE_HOST_ENTRY'));
+    if (!existsSync(hostEntry))
+        throw new Error('community_native_child_host_entry_missing');
+    mkdirSync(path.dirname(identityPath), { recursive: true, mode: 0o700 });
+    const host = (runtime.spawnHost ?? spawnCommunityNativeHost)(hostEntry, env);
+    await waitForHostSpawn(host);
+    const hostOutcome = observeHostOutcome(host);
+    let cleanup;
+    let controlTimer;
+    let forceStopTimer;
+    let stopping = false;
+    const forward = (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        try {
+            host.kill(signal);
+        }
+        catch { }
+        forceStopTimer = setTimeout(() => {
+            if (host.exitCode === null && host.signalCode === null) {
+                try {
+                    host.kill('SIGKILL');
+                }
+                catch { }
+            }
+        }, HOST_STOP_GRACE_MS);
+        forceStopTimer.unref();
+    };
+    const onSigint = () => forward('SIGINT');
+    const onSigterm = () => forward('SIGTERM');
+    try {
+        if (!host.pid)
+            throw new Error('community_native_child_host_pid_missing');
+        const identity = buildCommunityNativeChildIdentity(env, process.pid, host.pid);
+        atomicJsonWrite(identityPath, identity);
+        cleanup = () => {
+            removeIdentityIfOwned(identityPath, identity.launchId);
+            removeControlIfOwned(controlPath, identity.launchId);
+        };
+        process.once('exit', cleanup);
+        process.once('SIGINT', onSigint);
+        process.once('SIGTERM', onSigterm);
+        controlTimer = setInterval(() => {
+            if (readOwnedStopRequest(controlPath, identity.launchId)) {
+                removeControlIfOwned(controlPath, identity.launchId);
+                forward('SIGTERM');
+            }
+        }, 100);
+        const outcome = await hostOutcome;
+        if (outcome.kind === 'error')
+            throw outcome.error;
+        if (!stopping && outcome.value.exitCode !== 0) {
+            throw new Error(`community_native_child_host_failed:${outcome.value.exitCode ?? outcome.value.signal ?? 'unknown'}`);
+        }
+    }
+    catch (error) {
+        await terminateAndReapHost(host);
+        throw error;
+    }
+    finally {
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+        if (cleanup)
+            process.off('exit', cleanup);
+        if (controlTimer)
+            clearInterval(controlTimer);
+        if (forceStopTimer)
+            clearTimeout(forceStopTimer);
+        cleanup?.();
+    }
+}
+export function isCommunityNativeChildEntry(moduleUrl = import.meta.url, argvPath = process.argv[1]) {
+    return typeof argvPath === 'string' &&
+        /^community-native-child\.[cm]?[jt]s$/i.test(path.basename(argvPath)) &&
+        moduleUrl === pathToFileURL(argvPath).href;
+}
+if (isCommunityNativeChildEntry()) {
+    runCommunityNativeChild().catch((error) => {
+        process.stderr.write(`[aops-community] native child failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}