agentic-workflow-manager 9.5.0 → 9.6.0

package/dist/src/commands/sensors/migrate.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planV2Migration = planV2Migration;
+exports.replaceV2ManifestWithV3 = replaceV2ManifestWithV3;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const contract_1 = require("./compatibility/contract");
+const manifest_1 = require("./compatibility/manifest");
+const safe_file_1 = require("./compatibility/safe-file");
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function sameSensorField(v2, v3, pick) {
+    const names = Object.keys(v2.sensors);
+    return names.length === Object.keys(v3.sensors).length
+        && names.every(name => name in v3.sensors && JSON.stringify(pick(v2.sensors[name])) === JSON.stringify(pick(v3.sensors[name])));
+}
+function compareV2Semantics(v2, v3, registry) {
+    return Object.freeze({
+        pack: v2.pack === v3.pack && v2.packSelection === v3.packSelection,
+        enabledDisabled: sameSensorField(v2, v3, sensor => sensor.enabled),
+        structuredCommands: sameSensorField(v2, v3, sensor => sensor.command),
+        assets: sameSensorField(v2, v3, sensor => sensor.assets),
+        timeouts: sameSensorField(v2, v3, sensor => sensor.timeout),
+        fast: sameSensorField(v2, v3, sensor => sensor.fast),
+        variants: sameSensorField(v2, v3, sensor => sensor.variantId),
+        policies: sameSensorField(v2, v3, sensor => sensor.policyRef),
+        sensorIdentityAndOrder: JSON.stringify(Object.keys(v2.sensors)) === JSON.stringify(Object.keys(v3.sensors)),
+        concurrency: v2.concurrency === v3.concurrency,
+        compatibilityEvidence: sameSensorField(v2, v3, sensor => sensor.initializedCompatibility),
+        packageRoot: v2.packageRoot === v3.packageRoot,
+        logicalSourceBinding: v3.source.registry === registry,
+    });
+}
+function allEquivalent(report) {
+    return Object.values(report).every(value => value === true);
+}
+function exactLogicalSource(input, pack) {
+    if (!isRecord(input))
+        throw new Error('v2 migration source is required');
+    if (input.kind === 'source-unavailable')
+        throw new Error('v2 migration source is unavailable');
+    if (input.kind === 'source-ambiguous')
+        throw new Error('v2 migration source is ambiguous');
+    if ((input.kind !== 'logical' && input.kind !== 'legacy-rebound') || !isRecord(input.source))
+        throw new Error('v2 migration source must be a unique logical resolution');
+    const source = input.source;
+    if (Object.keys(source).some(key => !['path', 'content', 'registry'].includes(key))
+        || typeof source.path !== 'string' || typeof source.content !== 'string' || !isRecord(source.registry)) {
+        throw new Error('v2 migration source must contain an exact resolved pack');
+    }
+    const registry = source.registry;
+    if (Object.keys(registry).some(key => !['name', 'remote', 'contentRoot'].includes(key))
+        || typeof registry.name !== 'string' || !/^[a-z][a-z0-9-]*$/.test(registry.name)
+        || typeof registry.remote !== 'string' || registry.remote.trim() === '' || /[\0\r\n]/.test(registry.remote)
+        || typeof registry.contentRoot !== 'string' || !path_1.default.isAbsolute(registry.contentRoot) || path_1.default.normalize(registry.contentRoot) !== registry.contentRoot) {
+        throw new Error('v2 migration source registry must be a stable logical registry');
+    }
+    // `resolveSensorSource` already selected and read this exact source. The
+    // migration planner consumes that immutable snapshot; re-canonicalizing its
+    // host directory would make a no-write plan depend on later filesystem state.
+    const expectedPath = path_1.default.join(registry.contentRoot, 'sensor-packs', pack, 'pack.json');
+    if (source.path !== expectedPath)
+        throw new Error('v2 migration source must contain an exact resolved pack');
+    let parsedSource;
+    try {
+        parsedSource = (0, contract_1.parseSensorPack)(JSON.parse(source.content), 'v2 migration resolved source');
+    }
+    catch {
+        throw new Error('v2 migration source exact v2 pack is invalid');
+    }
+    if (parsedSource.kind !== 'v2' || parsedSource.pack.name !== pack)
+        throw new Error('v2 migration source must contain the exact v2 pack');
+    return source;
+}
+function assertSourceCompatibleWithManifest(source, manifest) {
+    let parsedSource;
+    try {
+        parsedSource = (0, contract_1.parseSensorPack)(JSON.parse(source.content), 'v2 migration resolved source');
+    }
+    catch {
+        throw new Error('v2 migration source exact v2 pack is invalid');
+    }
+    if (parsedSource.kind !== 'v2' || parsedSource.pack.name !== manifest.pack) {
+        throw new Error('v2 migration source must contain the exact v2 pack');
+    }
+    for (const [name, sensor] of Object.entries(manifest.sensors)) {
+        const selected = parsedSource.pack.sensors[name];
+        if (!selected || !selected.variants.some(variant => variant.id === sensor.variantId)) {
+            throw new Error('v2 migration source is not compatible with selected manifest sensors');
+        }
+    }
+}
+function hasPhysicalSensorPath(value, registryRoots) {
+    if (typeof value === 'string') {
+        const normalized = path_1.default.posix.normalize(value.replace(/\\/g, '/')).toLowerCase();
+        const withoutWebUrls = value.replace(/https?:\/\/[^\s"']+/gi, '');
+        const roots = registryRoots
+            .filter((root) => typeof root === 'string' && root.length > 0)
+            .map(root => path_1.default.posix.normalize(root.replace(/\\/g, '/')).toLowerCase());
+        const hasAbsolutePathAtTokenBoundary = /(?:^|[^A-Za-z0-9_.~\/\\-])["']?(?:\/|\\|[A-Za-z]:|\/\/)/.test(withoutWebUrls);
+        return roots.some(root => normalized.includes(root))
+            || hasAbsolutePathAtTokenBoundary;
+    }
+    return Array.isArray(value) ? value.some(item => hasPhysicalSensorPath(item, registryRoots))
+        : isRecord(value) && Object.values(value).some(item => hasPhysicalSensorPath(item, registryRoots));
+}
+function inspectManifest(manifestPath, failure) {
+    let stat;
+    try {
+        stat = fs_1.default.lstatSync(manifestPath, { bigint: true });
+    }
+    catch {
+        throw failure('open');
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw failure('regular');
+    return { stat, ...(0, safe_file_1.readInspectedBoundedFileWithIdentity)(manifestPath, stat, 1024 * 1024, failure) };
+}
+function assertManifestUnchanged(manifestPath, original) {
+    const changed = () => new Error('v2 migration original manifest changed before commit');
+    const current = inspectManifest(manifestPath, () => changed());
+    if (current.stat.dev !== original.stat.dev || current.stat.ino !== original.stat.ino
+        || current.stat.size !== original.stat.size || !current.content.equals(original.content)) {
+        throw changed();
+    }
+}
+/** Build, but never persist, a portable v3 replacement for a validated v2 manifest. */
+function planV2Migration(input) {
+    if (!input || typeof input !== 'object')
+        throw new Error('v2 migration input is required');
+    const parsed = (0, manifest_1.parseSensorManifest)(input.manifest, 'v2 migration manifest');
+    if (parsed.kind !== 'v2')
+        throw new Error('v2 migration requires a v2 project-sensors manifest');
+    const source = exactLogicalSource(input.source, parsed.pack.pack);
+    assertSourceCompatibleWithManifest(source, parsed.pack);
+    if (hasPhysicalSensorPath(parsed.pack.sensors, [parsed.pack.registryRoot, source.registry.contentRoot])
+        || hasPhysicalSensorPath(parsed.pack.packageRoot, []))
+        throw new Error('v2 migration sensor semantics contain a physical path');
+    const candidate = {
+        schemaVersion: 3,
+        mode: 'project-sensors',
+        pack: parsed.pack.pack,
+        ...(parsed.pack.packSelection === 'explicit' ? { packSelection: 'explicit' } : {}),
+        source: { registry: source.registry.name },
+        ...(parsed.pack.packageRoot ? { packageRoot: parsed.pack.packageRoot } : {}),
+        sensors: parsed.pack.sensors,
+        ...(parsed.pack.concurrency ? { concurrency: parsed.pack.concurrency } : {}),
+    };
+    const validated = (0, manifest_1.parseSensorManifest)(candidate, 'v2 migration candidate');
+    if (validated.kind !== 'v3' || validated.pack.mode !== 'project-sensors') {
+        throw new Error('v2 migration candidate semantic mismatch');
+    }
+    const equivalence = compareV2Semantics(parsed.pack, validated.pack, source.registry.name);
+    if (!allEquivalent(equivalence))
+        throw new Error('v2 migration candidate semantic mismatch');
+    return { candidate: validated.pack, equivalent: true, equivalence };
+}
+/** Validate the old and new durable contracts, then atomically replace only the manifest. */
+function replaceV2ManifestWithV3(manifestPath, candidate, source) {
+    if (typeof manifestPath !== 'string' || !path_1.default.isAbsolute(manifestPath) || path_1.default.normalize(manifestPath) !== manifestPath
+        || manifestPath.includes('\0') || path_1.default.basename(manifestPath) !== 'sensors.json'
+        || path_1.default.basename(path_1.default.dirname(manifestPath)) !== '.awm') {
+        throw new Error('v2 migration manifest path must be the canonical project manifest <project>/.awm/sensors.json');
+    }
+    const manifestDirectory = path_1.default.dirname(manifestPath);
+    const projectRoot = path_1.default.dirname(manifestDirectory);
+    const destination = '.awm/sensors.json';
+    (0, safe_file_1.withProjectLease)(projectRoot, () => {
+        const originalFailure = (_reason) => new Error('v2 migration original manifest must be readable JSON');
+        let inspected;
+        let original;
+        try {
+            inspected = inspectManifest(manifestPath, originalFailure);
+            original = JSON.parse(inspected.content.toString('utf8'));
+        }
+        catch {
+            throw new Error('v2 migration original manifest must be readable JSON');
+        }
+        const before = (0, manifest_1.parseSensorManifest)(original, manifestPath);
+        const after = (0, manifest_1.parseSensorManifest)(candidate, 'v2 migration candidate');
+        if (before.kind !== 'v2' || after.kind !== 'v3' || after.pack.mode !== 'project-sensors') {
+            throw new Error('v2 migration candidate semantic mismatch');
+        }
+        const logicalSource = exactLogicalSource(source, before.pack.pack);
+        assertSourceCompatibleWithManifest(logicalSource, before.pack);
+        if (after.pack.source.registry !== logicalSource.registry.name) {
+            throw new Error('v2 migration candidate semantic mismatch');
+        }
+        if (hasPhysicalSensorPath(before.pack.sensors, [before.pack.registryRoot, logicalSource.registry.contentRoot])
+            || hasPhysicalSensorPath(after.pack.sensors, [before.pack.registryRoot, logicalSource.registry.contentRoot])
+            || hasPhysicalSensorPath(before.pack.packageRoot, []) || hasPhysicalSensorPath(after.pack.packageRoot, [])) {
+            throw new Error('v2 migration candidate contains a physical path');
+        }
+        if (!allEquivalent(compareV2Semantics(before.pack, after.pack, logicalSource.registry.name))) {
+            throw new Error('v2 migration candidate semantic mismatch');
+        }
+        // The native implementation reopens every ancestor without following links,
+        // verifies these exact bytes at the publication fence, and preserves a
+        // competing target instead of replacing it.
+        assertManifestUnchanged(manifestPath, inspected);
+        (0, safe_file_1.writeProjectFile)(projectRoot, destination, Buffer.from((0, manifest_1.serializeManifestV3)(after.pack), 'utf8'), {
+            mode: 'replace', expected: inspected.content, expectedIdentity: inspected.identity, createParents: false,
+        });
+    });
+}

package/dist/src/commands/sensors/run.js

@@ -16,7 +16,7 @@ Object.defineProperty(exports, "applyBaseline", { enumerable: true, get: functio
 const changed_1 = require("./changed");
 // Solo `detectStack` (puro, lee el arbol) — NO `initSensors`, que escribe. `run` es un
 // verbo de lectura: no debe tener a mano ninguna funcion capaz de mutar el proyecto.
-const init_1 = require("./init");
+const detection_1 = require("./detection");
 const live_1 = require("./compatibility/live");
 const contract_1 = require("./compatibility/contract");
 const source_1 = require("./compatibility/source");
@@ -67,7 +67,7 @@ function findManifestDir(startCwd) {
  * and failed on by preflight's `pack` check.
  */
 function detectPackDrift(manifestDir, manifest) {
-    const detection = (0, init_1.detectStack)(manifestDir);
+    const detection = (0, detection_1.detectStack)(manifestDir);
     if (manifest.pack !== 'generic' || detection.pack === 'generic')
         return { detection };
     return {

package/dist/src/core/init/steps.js

@@ -23,7 +23,8 @@ exports.stepContextInjection = stepContextInjection;
 const registries_1 = require("../registries");
 const install_1 = require("../../commands/hooks/install");
 const bundle_install_1 = require("../bundle-install");
-const init_1 = require("../../commands/sensors/init");
+const bootstrap_1 = require("../../commands/sensors/bootstrap");
+const detection_1 = require("../../commands/sensors/detection");
 const profile_1 = require("../profile");
 const context_1 = require("../diagnostics/context");
 const detector_1 = require("./detector");
@@ -66,15 +67,15 @@ exports.defaultActions = {
         contentDir: o.contentDir,
     }),
     initSensors: async (o) => {
-        const result = await (0, init_1.initSensors)({ cwd: o.cwd, registryRoot: o.registryRoot, configure: o.configure });
-        // `unavailablePack`/`manifest` viajan a proposito: `stepSensors` los reporta.
-        // Este wrapper proyectaba solo `detection`, asi que cualquier hallazgo nuevo de
-        // initSensors moria aca en silencio antes de llegar al step que lo muestra.
-        return {
-            detection: result.detection,
-            manifest: { pack: result.manifest.pack },
-            ...(result.unavailablePack ? { unavailablePack: result.unavailablePack } : {}),
-        };
+        const plan = await (0, bootstrap_1.planSensorBootstrap)(o.cwd, { mode: 'project-sensors', registryRoot: o.registryRoot, configure: o.configure });
+        if (plan.kind === 'blocked')
+            throw new Error(`sensor bootstrap blocked: ${plan.reason}; ${plan.remedy}`);
+        if (plan.kind === 'migrate')
+            throw new Error('sensor init does not migrate an existing v2 manifest; run awm sensors bootstrap');
+        if (plan.kind === 'create')
+            (0, bootstrap_1.applySensorBootstrap)(plan);
+        const pack = plan.kind === 'create' && plan.manifest.mode === 'project-sensors' ? plan.manifest.pack : (0, detection_1.detectStack)(o.cwd).pack;
+        return { detection: { pack }, manifest: { pack } };
     },
     addExtension: (root, name) => { (0, profile_1.addExtension)(root, name); },
     ensureProfile: (root) => { (0, profile_1.ensureProfile)(root); },
@@ -325,7 +326,19 @@ async function stepSensors(d) {
         return ok('project.sensors', 'project', 'skipped', 'no project');
     if (proj.sensors.present)
         return ok('project.sensors', 'project', 'skipped');
-    const res = await d.actions.initSensors({ cwd: proj.root, registryRoot: d.sensorPacksRoot, configure: true });
+    if (!d.sensorPacksRoot)
+        return ok('project.sensors', 'project', 'skipped', 'no configured sensor-pack registry');
+    let res;
+    try {
+        res = await d.actions.initSensors({ cwd: proj.root, registryRoot: d.sensorPacksRoot, configure: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/^(?:source-unavailable|source-unsupported|registry-root-not-configured|sensor-variant-unresolvable):/.test(message)) {
+            return ok('project.sensors', 'project', 'skipped', message);
+        }
+        throw error;
+    }
     // A registry without the detected pack yields a fallback (or empty) manifest. The
     // step still succeeded — a manifest was written — but reporting a bare 'applied'
     // would let `awm init` hand back a quality gate that measures less than the

package/dist/src/core/secure-fs/native-bridge.js

@@ -0,0 +1,209 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureFs = exports.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE = void 0;
+exports.nativeArtifactStatus = nativeArtifactStatus;
+exports.loadNativeSecureFsBridge = loadNativeSecureFsBridge;
+exports.createSecureFsBoundary = createSecureFsBoundary;
+exports.resolvePackageRoot = resolvePackageRoot;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const supportedPlatforms = new Set(['linux', 'darwin', 'win32']);
+const supportedArchitectures = new Set(['x64', 'arm64']);
+function artifactPath(root, platform, arch) {
+    if (!supportedPlatforms.has(platform) || !supportedArchitectures.has(arch)) {
+        throw new Error(`secure-fs native bridge does not support ${platform}-${arch}`);
+    }
+    return path_1.default.join(root, 'prebuilds', `${platform}-${arch}`, 'secure_fs.node');
+}
+function nativeArtifactStatus(options) {
+    const artifact = artifactPath(options.root, options.platform, options.arch);
+    return { status: fs_1.default.existsSync(artifact) ? 'available' : 'missing', platform: options.platform, arch: options.arch, path: artifact };
+}
+function loadNativeSecureFsBridge(options) {
+    const status = nativeArtifactStatus(options);
+    if (status.status !== 'available')
+        throw new Error(`secure-fs native artifact is unavailable for ${status.platform}-${status.arch}`);
+    let loaded;
+    try {
+        loaded = options.load(status.path);
+    }
+    catch {
+        throw new Error(`secure-fs native artifact is incompatible for ${status.platform}-${status.arch}`);
+    }
+    if (!loaded || typeof loaded !== 'object'
+        || typeof loaded.acquireProjectLease !== 'function'
+        || typeof loaded.releaseProjectLease !== 'function'
+        || typeof loaded.readRegularFile !== 'function'
+        || typeof loaded.writeProjectTransaction !== 'function'
+        || typeof loaded.removeObservedProjectFile !== 'function') {
+        throw new Error(`secure-fs native artifact is incompatible for ${status.platform}-${status.arch}`);
+    }
+    return loaded;
+}
+const IDENTITY_TOKEN_BYTES = 24;
+const NATIVE_DESTINATION_EXISTS_CODE = 'AWM_SECURE_FS_DESTINATION_EXISTS';
+exports.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE = 'project destination already exists';
+const identityObservations = new WeakMap();
+function absoluteFile(value, label) {
+    if (typeof value === 'string' && value.includes('\0'))
+        throw new Error(`${label} must not contain a NUL byte`);
+    if (typeof value !== 'string' || !path_1.default.isAbsolute(value) || path_1.default.normalize(value) !== value)
+        throw new Error(`${label} must be an absolute normalized path`);
+    return value;
+}
+function isNativeDestinationExistsError(error) {
+    return !!error && typeof error === 'object'
+        && error.code === NATIVE_DESTINATION_EXISTS_CODE;
+}
+function boundedBytes(value, label) {
+    if (!Buffer.isBuffer(value))
+        throw new Error(`${label} must be a Buffer`);
+    return value;
+}
+function projectDestination(value) {
+    if (typeof value !== 'string' || !value || value.includes('\\')
+        || path_1.default.posix.isAbsolute(value) || path_1.default.win32.isAbsolute(value) || /^[A-Za-z]:/.test(value)) {
+        throw new Error('destination must be a canonical project-relative path');
+    }
+    const components = value.split('/');
+    if (components.some(component => !component || component === '.' || component === '..' || component.includes(':') || component.includes('\0'))) {
+        throw new Error('destination must contain only safe project-relative components');
+    }
+    return components.join(path_1.default.sep);
+}
+function positiveSafeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error(`${label} must be a positive safe integer`);
+    return value;
+}
+function nativeIdentity(value) {
+    if (!Buffer.isBuffer(value) || value.length !== IDENTITY_TOKEN_BYTES
+        || value.toString('ascii', 0, 4) !== 'SFSI' || value[4] !== 1
+        || (value[5] !== 1 && value[5] !== 2) || value[6] !== 0 || value[7] !== 0) {
+        throw new Error('secure-fs native bridge returned invalid read identity');
+    }
+    const expectedKind = process.platform === 'win32' ? 2 : 1;
+    if (value[5] !== expectedKind)
+        throw new Error('secure-fs native bridge returned identity for the wrong platform');
+    return Buffer.from(value);
+}
+function secureReadResult(file, value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('secure-fs native bridge returned invalid read result');
+    const candidate = value;
+    if (!Buffer.isBuffer(candidate.bytes))
+        throw new Error('secure-fs native bridge returned invalid read bytes');
+    const bytes = Buffer.from(candidate.bytes);
+    const token = Object.freeze({});
+    identityObservations.set(token, { file, bytes: Buffer.from(bytes), identity: nativeIdentity(candidate.identity) });
+    return Object.freeze({ bytes, identity: token });
+}
+function writeOptions(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('transaction options must be an object');
+    const candidate = value;
+    if (candidate.mode !== 'create' && candidate.mode !== 'replace')
+        throw new Error('transaction mode must be create or replace');
+    if (typeof candidate.createParents !== 'boolean')
+        throw new Error('transaction createParents must be boolean');
+    if (candidate.mode === 'create') {
+        if (candidate.expected !== undefined || candidate.expectedIdentity !== undefined)
+            throw new Error('create transaction cannot have replacement expectations');
+        return { mode: 'create', createParents: candidate.createParents };
+    }
+    if (!Buffer.isBuffer(candidate.expected))
+        throw new Error('replace transaction requires expected Buffer bytes');
+    if (!candidate.expectedIdentity || typeof candidate.expectedIdentity !== 'object')
+        throw new Error('replace transaction requires expected identity token');
+    const observation = identityObservations.get(candidate.expectedIdentity);
+    if (!observation)
+        throw new Error('replace transaction requires an opaque identity token from readRegularFile');
+    if (!candidate.expected.equals(observation.bytes))
+        throw new Error('replace expected bytes do not match the identity observation');
+    return {
+        mode: 'replace',
+        expected: Buffer.from(observation.bytes),
+        expectedIdentity: Buffer.from(observation.identity),
+        createParents: candidate.createParents,
+    };
+}
+function createSecureFsBoundary(load) {
+    return Object.freeze({
+        withProjectLease(projectRoot, operation) {
+            const validatedRoot = absoluteFile(projectRoot, 'projectRoot');
+            if (typeof operation !== 'function')
+                throw new Error('project lease operation must be a function');
+            const binding = load();
+            let token;
+            try {
+                token = binding.acquireProjectLease(validatedRoot);
+            }
+            catch (error) {
+                const message = String(error);
+                if (message.includes('project lease is already held'))
+                    throw new Error('project lease conflict');
+                if (message.includes('rejected path ancestor'))
+                    throw new Error('project destination is unsafe for lease');
+                throw new Error('project lease acquisition failed');
+            }
+            if (!token || typeof token !== 'object' || Array.isArray(token)) {
+                throw new Error('secure-fs native bridge returned invalid project lease token');
+            }
+            try {
+                return operation();
+            }
+            finally {
+                binding.releaseProjectLease(token);
+            }
+        },
+        readRegularFile(file, maxBytes) {
+            const validatedFile = absoluteFile(file, 'file');
+            const validatedMaxBytes = positiveSafeInteger(maxBytes, 'maxBytes');
+            const result = load().readRegularFile(validatedFile, validatedMaxBytes);
+            return secureReadResult(validatedFile, result);
+        },
+        writeProjectTransaction(projectRoot, destination, content, options) {
+            const validatedRoot = absoluteFile(projectRoot, 'projectRoot');
+            const validatedDestination = projectDestination(destination);
+            const validatedContent = boundedBytes(content, 'content');
+            const validatedOptions = writeOptions(options);
+            try {
+                load().writeProjectTransaction(validatedRoot, validatedDestination, validatedContent, validatedOptions);
+            }
+            catch (error) {
+                if (isNativeDestinationExistsError(error))
+                    throw new Error(exports.PROJECT_DESTINATION_ALREADY_EXISTS_MESSAGE);
+                throw error;
+            }
+        },
+        removeObservedProjectFile(projectRoot, destination, identity) {
+            const validatedRoot = absoluteFile(projectRoot, 'projectRoot');
+            const validatedDestination = projectDestination(destination);
+            if (!identity || typeof identity !== 'object')
+                throw new Error('remove requires an opaque identity token from readRegularFile');
+            const observation = identityObservations.get(identity);
+            if (!observation)
+                throw new Error('remove requires an opaque identity token from readRegularFile');
+            const observedDestination = path_1.default.join(validatedRoot, validatedDestination);
+            if (observation.file !== observedDestination)
+                throw new Error('remove requires the exact observed destination');
+            load().removeObservedProjectFile(validatedRoot, validatedDestination, Buffer.from(observation.identity));
+        },
+    });
+}
+function resolvePackageRoot(moduleDirectory) {
+    const sourceLayout = path_1.default.resolve(moduleDirectory, '..', '..', '..');
+    return fs_1.default.existsSync(path_1.default.join(sourceLayout, 'package.json'))
+        ? sourceLayout
+        : path_1.default.resolve(sourceLayout, '..');
+}
+const packageRoot = resolvePackageRoot(__dirname);
+exports.secureFs = createSecureFsBoundary(() => loadNativeSecureFsBridge({
+    root: packageRoot,
+    platform: process.platform,
+    arch: process.arch,
+    load: artifact => require(artifact),
+}));

package/dist/tests/commands/sensors/bootstrap-observational.test.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const bootstrap_1 = require("../../../src/commands/sensors/bootstrap");
+describe('planSensorBootstrap observational boundary', () => {
+    it('does not create project files while reporting a missing explicit mode', async () => {
+        const project = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-bootstrap-observe-'));
+        try {
+            fs_1.default.writeFileSync(path_1.default.join(project, 'package.json'), '{"name":"fixture"}\n');
+            const before = fs_1.default.readdirSync(project).sort();
+            await expect((0, bootstrap_1.planSensorBootstrap)(project)).resolves.toMatchObject({ kind: 'blocked', reason: 'mode-required', changes: [] });
+            expect(fs_1.default.readdirSync(project).sort()).toEqual(before);
+            expect(fs_1.default.existsSync(path_1.default.join(project, '.awm'))).toBe(false);
+        }
+        finally {
+            fs_1.default.rmSync(project, { recursive: true, force: true });
+        }
+    });
+});