@tomflow/proflow-execution-browser-extension 0.1.4 → 0.1.5

package/DOCS.md

@@ -0,0 +1,29 @@
+# @tomflow/proflow-execution-browser-extension — Module Docs
+
+Module ref: `execution-browser-extension`  
+Domain: `execution`  
+Kind: `browser-extension`
+
+Execution-owned MV3 Browser executor, evidence provider and browser application surface.
+
+## Standard management surface
+
+`install / uninstall / status / setup / docs / start / stop`
+
+## Provides
+
+- `execution-browser-executor` `1.0.0`
+
+## Requires
+
+- `execution` `>=1.0.0 <2.0.0`
+- `task-orchestration` `>=1.0.0 <2.0.0`
+- `agent-runtime` `>=1.0.0 <2.0.0`
+
+## Public setup inputs
+
+- None. Deterministic/private values and cross-Module shared facts are not public configuration.
+
+## Ownership boundary
+
+Module business APIs and any module-specific extra commands remain package-owned. Platform does not proxy or interpret them. Current human/external preparation is documented in `SETUP.md`.

package/SETUP.md

@@ -0,0 +1,7 @@
+# @tomflow/proflow-execution-browser-extension — Module Setup
+
+After Module.install materializes the deployment directory and deterministic local configuration, load the unpacked extension in Chrome when requested. Confirm the real extension Service Worker is running, then rerun Module.setup so it can re-observe Chrome reality and record evidence. Endpoints, tokens and evidence paths are not user configuration.
+
+## Completion
+
+Setup is complete only when the Module's own `status` reports `setupStatus=READY`. Re-running setup must re-observe reality; it must not resume from a blind historical step index.

package/dist/deployment/adapter.d.ts

@@ -1,77 +1,130 @@
+import { type ModuleCommandContext } from "@tomflow/proflow-module-contract";
+export declare function browserExtensionLoadDir(workspaceRoot: string): string;
+export declare function materializeProductionConfig(input: {
+    moduleRef: string;
+    config: Record<string, string>;
+    workspaceRoot: string;
+}): Promise<{
+    loadDir: string;
+}>;
 export declare const behaviorAdapter: {
-    readonly describe: () => {
+    readonly install: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.4";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            data: {
+                loadDir: string;
+            };
+        };
+        observedEffects: string[];
+    }>;
+    readonly uninstall: (_context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
         };
         observedEffects: never[];
-    };
-    readonly preflight: () => {
+    }>;
+    readonly status: (context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.4";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            data: {
+                setupStatus: "ACTION_REQUIRED" | "READY";
+                runtimeStatus: "RUNNING" | "STOPPED";
+            };
+        };
+        observedEffects: string[];
+    }>;
+    readonly setup: (context: ModuleCommandContext) => Promise<{
+        result: {
+            contract: "deployment.result.v1";
+            moduleRef: "execution-browser-extension";
+            moduleVersion: "0.1.5";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED";
+                message: string;
+                retryable: boolean;
+            };
         };
         observedEffects: never[];
-    };
-    readonly status: () => {
+    } | {
         result: {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.4";
-            ok: boolean;
-            status: string;
-            data: {
-                configStatus: "INCOMPLETE" | "INVALID" | "READY";
-                missingConfig?: string[] | undefined;
-                runtimeStatus: "FAILED" | "RUNNING" | "STOPPED" | "UNKNOWN";
+            moduleVersion: "0.1.5";
+            ok: false;
+            status: "ACTION_REQUIRED";
+            actionRequired: {
+                action: string;
+                description: string;
             };
         };
         observedEffects: never[];
-    };
-    readonly verify: () => {
+    } | {
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
+        };
+        observedEffects: string[];
+    }>;
+    readonly docs: (_context: ModuleCommandContext) => Promise<{
         result: {
             contract: "deployment.result.v1";
+            ok: true;
+            status: "SUCCEEDED";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.4";
-            ok: boolean;
-            status: string;
-            checks: {
-                id: string;
-                status: string;
-                message: string;
-            }[];
+            moduleVersion: "0.1.5";
+            data: {
+                docs: string;
+                setup: string;
+            };
         };
         observedEffects: never[];
-    };
-    readonly doctor: () => {
+    }>;
+    readonly start: (context: ModuleCommandContext) => Promise<{
         result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
+        } | {
             contract: "deployment.result.v1";
             moduleRef: "execution-browser-extension";
-            moduleVersion: "0.1.4";
-            ok: boolean;
-            status: string;
+            moduleVersion: "0.1.5";
+            ok: false;
+            status: "FAILED";
+            error: {
+                code: "SETUP_FAILED" | "START_FAILED";
+                message: string;
+                retryable: boolean;
+            };
         };
         observedEffects: never[];
-    };
-};
-export declare function browserExtensionLoadDir(workspaceRoot: string): string;
-export declare function materializeProductionConfig(input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    workspaceRoot: string;
-}): Promise<{
-    loadDir: string;
-}>;
-export declare function createProductionBinding(input: {
-    moduleRef: string;
-    config: Record<string, string>;
-    workspaceRoot: string;
-}): {
-    behaviorAdapter: Record<string, unknown>;
+    }>;
+    readonly stop: (_context: ModuleCommandContext) => Promise<{
+        result: {
+            readonly contract: "deployment.result.v1";
+            readonly ok: true;
+            readonly status: "SUCCEEDED";
+            readonly moduleRef: "execution-browser-extension";
+            readonly moduleVersion: "0.1.5";
+        };
+        observedEffects: never[];
+    }>;
 };

package/dist/deployment/adapter.js

@@ -1,76 +1,46 @@
 import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { observeDeclaredModuleStatus } from "@tomflow/proflow-module-contract";
+import { deterministicLoopbackPort, ensureModuleSecretFile, moduleWorkspaceStateDirectory, readModuleSharedFacts, writeModuleSharedFacts, } from "@tomflow/proflow-module-contract";
 import { descriptor } from "./descriptor.js";
 const base = {
     contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
     moduleRef: descriptor.moduleRef,
     moduleVersion: descriptor.moduleVersion,
 };
-export const behaviorAdapter = {
-    describe: () => ({
-        result: { ...base, ok: true, status: "SUCCEEDED" },
-        observedEffects: [],
-    }),
-    preflight: () => ({
-        result: { ...base, ok: true, status: "SUCCEEDED" },
-        observedEffects: [],
-    }),
-    status: () => ({
-        result: {
-            ...base,
-            ok: true,
-            status: "SUCCEEDED",
-            data: observeDeclaredModuleStatus(descriptor, undefined, "UNKNOWN"),
-        },
-        observedEffects: [],
-    }),
-    verify: () => ({
-        result: {
-            ...base,
-            ok: true,
-            status: "SUCCEEDED",
-            checks: [
-                {
-                    id: "extension-package",
-                    status: "PASS",
-                    message: "The MV3 package is structurally verified; real Carrier readiness remains ACTION_REQUIRED in status",
-                },
-            ],
-        },
-        observedEffects: [],
-    }),
-    doctor: () => ({
-        result: { ...base, ok: true, status: "SUCCEEDED" },
-        observedEffects: [],
-    }),
-};
-function loopbackEndpoint(value, key) {
-    const url = new URL(value);
-    if (url.protocol !== "http:" ||
-        url.hostname !== "127.0.0.1" ||
-        url.pathname !== "/" ||
-        url.search !== "" ||
-        url.hash !== "") {
-        throw new Error(`${key} must be a loopback HTTP origin`);
-    }
-    return value.replace(/\/$/, "");
-}
-async function credential(file, key) {
-    const token = (await readFile(file, "utf8")).trim();
-    if (token.length < 32)
-        throw new Error(`${key} must contain at least 32 characters`);
-    return token;
-}
+const factString = (facts, name) => (typeof facts?.[name] === "string" ? String(facts[name]) : undefined);
 function packageRoot() {
     const candidate = dirname(dirname(fileURLToPath(import.meta.url)));
     return basename(candidate) === "dist" ? dirname(candidate) : candidate;
 }
 export function browserExtensionLoadDir(workspaceRoot) {
-    return join(workspaceRoot, ".proflow", "deployment", "browser-extension", "execution-browser-extension");
+    return join(resolve(workspaceRoot), ".proflow", "deployment", "browser-extension", "execution-browser-extension");
+}
+const stateDir = (context) => moduleWorkspaceStateDirectory(context, descriptor.moduleRef);
+const setupFile = (context) => join(stateDir(context), "setup.json");
+const verificationFile = (context) => join(stateDir(context), "verification.json");
+const executorConfigFile = (context) => join(stateDir(context), "browser-executor.json");
+async function credential(file) {
+    const value = (await readFile(file, "utf8")).trim();
+    if (value.length < 32)
+        throw new Error(`credential ${file} is invalid`);
+    return value;
+}
+function loopbackEndpoint(value, name) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" ||
+        url.hostname !== "127.0.0.1" ||
+        url.pathname !== "/" ||
+        url.search ||
+        url.hash)
+        throw new Error(`${name} must be a loopback HTTP origin`);
+    return value.replace(/\/$/, "");
 }
 export async function materializeProductionConfig(input) {
+    const context = { workspaceRoot: input.workspaceRoot };
+    const loadDir = await installPackage(context);
     const required = [
         "bridge.endpoint",
         "bridge.token",
@@ -79,31 +49,31 @@ export async function materializeProductionConfig(input) {
         "approvalApplication.endpoint",
         "approvalApplication.token",
     ];
-    for (const key of required) {
-        if (!input.config[key])
-            throw new Error(`missing required browser config ${key}`);
-    }
+    for (const name of required)
+        if (!input.config[name])
+            throw new Error(`missing required browser config ${name}`);
     const runtimeConfig = {
         proflowRuntimeBridge: {
             endpoint: loopbackEndpoint(input.config["bridge.endpoint"] ?? "", "bridge.endpoint"),
-            token: await credential(input.config["bridge.token"] ?? "", "bridge.token"),
+            token: await credential(input.config["bridge.token"] ?? ""),
         },
         proflowTaskApplication: {
             endpoint: loopbackEndpoint(input.config["taskApplication.endpoint"] ?? "", "taskApplication.endpoint"),
-            token: await credential(input.config["taskApplication.token"] ?? "", "taskApplication.token"),
+            token: await credential(input.config["taskApplication.token"] ?? ""),
         },
         proflowApprovalApplication: {
             endpoint: loopbackEndpoint(input.config["approvalApplication.endpoint"] ?? "", "approvalApplication.endpoint"),
-            token: await credential(input.config["approvalApplication.token"] ?? "", "approvalApplication.token"),
+            token: await credential(input.config["approvalApplication.token"] ?? ""),
         },
     };
+    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { mode: 0o600 });
+    return { loadDir };
+}
+async function installPackage(context) {
     const sourceRoot = packageRoot();
-    const loadDir = browserExtensionLoadDir(input.workspaceRoot);
+    const loadDir = browserExtensionLoadDir(context.workspaceRoot);
     await mkdir(join(loadDir, "dist"), { recursive: true });
-    await cp(join(sourceRoot, "dist", "extension"), join(loadDir, "dist", "extension"), {
-        recursive: true,
-        force: true,
-    });
+    await cp(join(sourceRoot, "dist", "extension"), join(loadDir, "dist", "extension"), { recursive: true, force: true });
     await cp(join(sourceRoot, "extension"), join(loadDir, "extension"), {
         recursive: true,
         force: true,
@@ -111,108 +81,221 @@ export async function materializeProductionConfig(input) {
     await cp(join(sourceRoot, "manifest.json"), join(loadDir, "manifest.json"), {
         force: true,
     });
-    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-    return { loadDir };
+    return loadDir;
 }
-async function readBrowserVerificationEvidence(file, expectedLoadDir) {
-    if (!file)
+async function readSetup(context) {
+    try {
+        const raw = JSON.parse(await readFile(setupFile(context), "utf8"));
+        return typeof raw.extensionId === "string" &&
+            /^[a-z]{32}$/.test(raw.extensionId)
+            ? raw
+            : undefined;
+    }
+    catch {
         return undefined;
+    }
+}
+async function readEvidence(context, loadDir) {
     try {
-        const raw = JSON.parse(await readFile(file, "utf8"));
-        if (raw.contract !== "proflow.browser-extension-verification.v1" ||
-            raw.moduleVersion !== descriptor.moduleVersion ||
-            raw.loadDir !== expectedLoadDir ||
-            typeof raw.extensionId !== "string" ||
-            raw.extensionId.length < 16 ||
-            raw.serviceWorker !== "RUNNING" ||
-            typeof raw.observedAt !== "string" ||
-            Number.isNaN(Date.parse(raw.observedAt)))
-            return undefined;
-        return raw;
+        const raw = JSON.parse(await readFile(verificationFile(context), "utf8"));
+        return raw.contract === "proflow.browser-extension-verification.v1" &&
+            raw.moduleVersion === descriptor.moduleVersion &&
+            raw.loadDir === loadDir &&
+            typeof raw.extensionId === "string" &&
+            /^[a-z]{32}$/.test(raw.extensionId) &&
+            raw.serviceWorker === "RUNNING" &&
+            typeof raw.observedAt === "string" &&
+            !Number.isNaN(Date.parse(raw.observedAt))
+            ? raw
+            : undefined;
     }
     catch {
         return undefined;
     }
 }
-export function createProductionBinding(input) {
-    const loadDir = browserExtensionLoadDir(input.workspaceRoot);
-    const verificationEvidenceFile = input.config.verificationEvidenceFile;
-    const boundBase = {
-        contract: "deployment.result.v1",
-        moduleRef: descriptor.moduleRef,
-        moduleVersion: descriptor.moduleVersion,
+function input(context) {
+    const value = context.input;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return {};
+    const extensionId = Reflect.get(value, "extensionId"), serviceWorker = Reflect.get(value, "serviceWorker"), observedAt = Reflect.get(value, "observedAt");
+    return {
+        ...(typeof extensionId === "string" ? { extensionId } : {}),
+        ...(serviceWorker === "RUNNING"
+            ? { serviceWorker: "RUNNING" }
+            : {}),
+        ...(typeof observedAt === "string" ? { observedAt } : {}),
     };
-    const configured = async () => {
-        try {
-            const raw = JSON.parse(await readFile(join(loadDir, "runtime-config.json"), "utf8"));
-            return typeof raw === "object" && raw !== null;
-        }
-        catch {
-            return false;
-        }
+}
+async function ownFacts(context) {
+    await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+    const loadDir = browserExtensionLoadDir(context.workspaceRoot);
+    const bridgeTokenFile = await ensureModuleSecretFile(context, descriptor.moduleRef, "bridge");
+    const bridgePort = deterministicLoopbackPort(context, descriptor.moduleRef, "bridge");
+    const facts = {
+        loadDir,
+        bridgeTokenFile,
+        bridgeEndpoint: `http://127.0.0.1:${bridgePort}`,
+        verificationEvidenceFile: verificationFile(context),
     };
-    return {
-        behaviorAdapter: {
-            ...behaviorAdapter,
-            preflight: async () => ({
-                result: (await configured())
-                    ? { ...boundBase, ok: true, status: "SUCCEEDED" }
-                    : {
-                        ...boundBase,
-                        ok: false,
-                        status: "ACTION_REQUIRED",
-                        actionRequired: {
-                            action: "configure-browser-extension",
-                            description: `Materialize Browser Extension runtime config before loading ${loadDir}`,
-                        },
-                    },
-                observedEffects: [],
-            }),
-            status: async () => {
-                const isConfigured = await configured();
-                const evidence = await readBrowserVerificationEvidence(verificationEvidenceFile, loadDir);
-                return {
-                    result: {
-                        ...boundBase,
-                        ok: true,
-                        status: "SUCCEEDED",
-                        data: observeDeclaredModuleStatus(descriptor, input.config, evidence ? "RUNNING" : "STOPPED", isConfigured),
-                    },
-                    observedEffects: evidence
-                        ? ["Observes real Chrome MV3 load evidence"]
-                        : [],
-                };
+    const setup = await readSetup(context);
+    if (setup)
+        facts.extensionId = setup.extensionId;
+    try {
+        await readFile(executorConfigFile(context), "utf8");
+        facts.browserExecutorConfigPath = executorConfigFile(context);
+    }
+    catch { }
+    await writeModuleSharedFacts(context, descriptor.moduleRef, facts);
+    return facts;
+}
+async function materialize(context, setup) {
+    const host = await readModuleSharedFacts(context, "platform-host");
+    const endpoint = factString(host, "endpoint"), taskTokenFile = factString(host, "taskApplicationTokenFile"), approvalTokenFile = factString(host, "approvalApplicationTokenFile");
+    if (!endpoint || !taskTokenFile || !approvalTokenFile)
+        throw new Error("platform-host application shared facts are unavailable");
+    const facts = await ownFacts(context);
+    const loadDir = String(facts.loadDir);
+    const bridgeTokenFile = String(facts.bridgeTokenFile);
+    const bridgeEndpoint = String(facts.bridgeEndpoint);
+    const runtimeConfig = {
+        proflowRuntimeBridge: {
+            endpoint: bridgeEndpoint,
+            token: await credential(bridgeTokenFile),
+        },
+        proflowTaskApplication: {
+            endpoint,
+            token: await credential(taskTokenFile),
+        },
+        proflowApprovalApplication: {
+            endpoint,
+            token: await credential(approvalTokenFile),
+        },
+    };
+    await writeFile(join(loadDir, "runtime-config.json"), `${JSON.stringify(runtimeConfig, null, 2)}\n`, { mode: 0o600 });
+    await writeFile(executorConfigFile(context), `${JSON.stringify({ platformHost: { endpoint, tokenFile: taskTokenFile }, bridge: { extensionId: setup.extensionId, tokenFile: bridgeTokenFile, host: "127.0.0.1", port: Number(new URL(bridgeEndpoint).port) } }, null, 2)}\n`, { mode: 0o600 });
+    await writeModuleSharedFacts(context, descriptor.moduleRef, {
+        ...facts,
+        extensionId: setup.extensionId,
+        browserExecutorConfigPath: executorConfigFile(context),
+    });
+}
+const failed = (code, message, retryable = true) => ({
+    ...base,
+    ok: false,
+    status: "FAILED",
+    error: { code, message, retryable },
+});
+export const behaviorAdapter = {
+    install: async (context) => {
+        const loadDir = await installPackage(context);
+        return {
+            result: { ...base, data: { ...(await ownFacts(context)), loadDir } },
+            observedEffects: ["Materialize the unpacked MV3 extension package"],
+        };
+    },
+    uninstall: async (_context) => ({
+        result: base,
+        observedEffects: [],
+    }),
+    status: async (context) => {
+        const loadDir = browserExtensionLoadDir(context.workspaceRoot);
+        const setup = await readSetup(context);
+        const evidence = await readEvidence(context, loadDir);
+        return {
+            result: {
+                ...base,
+                data: {
+                    setupStatus: setup && evidence
+                        ? "READY"
+                        : "ACTION_REQUIRED",
+                    runtimeStatus: evidence ? "RUNNING" : "STOPPED",
+                },
             },
-            verify: async () => {
-                const evidence = await readBrowserVerificationEvidence(verificationEvidenceFile, loadDir);
+            observedEffects: evidence
+                ? ["Observes real Chrome MV3 load evidence"]
+                : [],
+        };
+    },
+    setup: async (context) => {
+        await mkdir(stateDir(context), { recursive: true, mode: 0o700 });
+        const supplied = input(context);
+        let setup = await readSetup(context);
+        if (supplied.extensionId) {
+            if (!/^[a-z]{32}$/.test(supplied.extensionId))
                 return {
-                    result: (await configured()) && evidence
-                        ? {
-                            ...boundBase,
-                            ok: true,
-                            status: "SUCCEEDED",
-                            checks: [
-                                {
-                                    id: "real-carrier-e3-e4",
-                                    status: "PASS",
-                                    message: `Real Chrome loaded extension ${evidence.extensionId} from ${loadDir} and its MV3 Service Worker was observed running`,
-                                },
-                            ],
-                        }
-                        : {
-                            ...boundBase,
-                            ok: false,
-                            status: "ACTION_REQUIRED",
-                            actionRequired: {
-                                action: "verify-real-chrome-extension",
-                                description: `Load ${loadDir} in real Chrome and write verified evidence to ${verificationEvidenceFile ?? "the configured verificationEvidenceFile"}`,
-                            },
-                        },
-                    observedEffects: evidence
-                        ? ["Observes real Chrome MV3 load evidence"]
-                        : [],
+                    result: failed("SETUP_FAILED", "extensionId must be a canonical 32-character Chromium extension id", false),
+                    observedEffects: [],
                 };
+            setup = { extensionId: supplied.extensionId };
+            await writeFile(setupFile(context), `${JSON.stringify(setup, null, 2)}\n`, { mode: 0o600 });
+        }
+        if (!setup)
+            return {
+                result: {
+                    ...base,
+                    ok: false,
+                    status: "ACTION_REQUIRED",
+                    actionRequired: {
+                        action: "load-unpacked-extension",
+                        description: `Load ${browserExtensionLoadDir(context.workspaceRoot)} in Chrome, copy its extensionId, then rerun Module.setup with extensionId.`,
+                    },
+                },
+                observedEffects: [],
+            };
+        try {
+            await materialize(context, setup);
+        }
+        catch (error) {
+            return {
+                result: failed("SETUP_FAILED", error instanceof Error
+                    ? error.message
+                    : "browser extension config materialization failed"),
+                observedEffects: [],
+            };
+        }
+        if (supplied.serviceWorker === "RUNNING") {
+            const evidence = {
+                contract: "proflow.browser-extension-verification.v1",
+                moduleVersion: descriptor.moduleVersion,
+                loadDir: browserExtensionLoadDir(context.workspaceRoot),
+                extensionId: setup.extensionId,
+                serviceWorker: "RUNNING",
+                observedAt: supplied.observedAt ?? new Date().toISOString(),
+            };
+            await writeFile(verificationFile(context), `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600 });
+            return {
+                result: base,
+                observedEffects: ["Records real Chrome MV3 load evidence"],
+            };
+        }
+        return {
+            result: {
+                ...base,
+                ok: false,
+                status: "ACTION_REQUIRED",
+                actionRequired: {
+                    action: "reload-and-verify-extension",
+                    description: "Reload the unpacked extension after runtime config materialization, confirm its MV3 service worker is RUNNING, then rerun Module.setup with serviceWorker=RUNNING.",
+                },
             },
-        },
-    };
-}
+            observedEffects: [],
+        };
+    },
+    docs: async (_context) => ({
+        result: { ...base, data: { docs: "DOCS.md", setup: "SETUP.md" } },
+        observedEffects: [],
+    }),
+    start: async (context) => {
+        const loadDir = browserExtensionLoadDir(context.workspaceRoot);
+        return {
+            result: (await readEvidence(context, loadDir))
+                ? base
+                : failed("START_FAILED", "browser extension setup is not READY"),
+            observedEffects: [],
+        };
+    },
+    stop: async (_context) => ({
+        result: base,
+        observedEffects: [],
+    }),
+};

package/dist/deployment/descriptor.d.ts

@@ -3,7 +3,7 @@ export declare const descriptor: {
     readonly contractVersion: "1.0.0";
     readonly moduleRef: "execution-browser-extension";
     readonly packageName: "@tomflow/proflow-execution-browser-extension";
-    readonly moduleVersion: "0.1.4";
+    readonly moduleVersion: "0.1.5";
     readonly kind: "browser-extension";
     readonly templateVersion: "1.0.0";
     readonly platformCompatibility: ">=1.0.0 <2.0.0";
@@ -33,79 +33,14 @@ export declare const descriptor: {
         readonly kind: "human";
         readonly action: "Load and verify the unpacked MV3 extension in the real Chrome profile";
     }];
-    readonly configSlots: readonly [{
-        readonly key: "bridge.endpoint";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Browser Reality Bridge endpoint";
-    }, {
-        readonly key: "bridge.token";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the Browser Reality Bridge extension token";
-    }, {
-        readonly key: "taskApplication.endpoint";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Platform Host Task application endpoint";
-    }, {
-        readonly key: "taskApplication.token";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the Platform Host Task application token";
-    }, {
-        readonly key: "approvalApplication.endpoint";
-        readonly type: "url";
-        readonly required: true;
-        readonly description: "Loopback Platform Host Approval application endpoint";
-    }, {
-        readonly key: "approvalApplication.token";
-        readonly type: "path";
-        readonly required: true;
-        readonly sensitive: true;
-        readonly description: "File containing the Platform Host Approval application token";
-    }, {
-        readonly key: "verificationEvidenceFile";
-        readonly type: "path";
-        readonly required: true;
-        readonly description: "JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs";
-    }, {
-        readonly key: "chromeRuntimeModuleRef";
-        readonly type: "moduleRef";
-        readonly required: false;
-        readonly description: "External resource module governing the Chrome runtime";
-        readonly default: "chrome-runtime";
-    }, {
-        readonly key: "carrierModuleRef";
-        readonly type: "moduleRef";
-        readonly required: false;
-        readonly description: "External resource module governing the Custom GPT carrier";
-        readonly default: "chatgpt-carrier";
-    }];
-    readonly lifecycle: {
-        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor"];
-    };
-    readonly verification: {
-        readonly checks: readonly [{
-            readonly id: "real-carrier-e3-e4";
-            readonly description: "Real Chrome and ChatGPT E3/E4 evidence is present";
-            readonly lifecycle: "verify";
-        }];
-    };
+    readonly configSlots: readonly [];
     readonly effects: readonly [{
         readonly kind: "external-resource";
-        readonly description: "Package an MV3 extension that performs Execution-authorized Browser effects";
+        readonly description: "Materialize the unpacked MV3 extension package";
         readonly retention: "preserve";
     }];
-    readonly documentation: readonly [{
-        readonly id: "overview";
-        readonly path: "./README.md";
-        readonly description: "Package-owned module overview";
-    }, {
-        readonly id: "configuration";
-        readonly path: "./CONFIGURATION.md";
-        readonly description: "Module configuration fields, sources and materialization instructions";
-    }];
+    readonly documentation: {
+        readonly docs: "DOCS.md";
+        readonly setup: "SETUP.md";
+    };
 };

package/dist/deployment/descriptor.js

@@ -3,7 +3,7 @@ export const descriptor = {
     contractVersion: "1.0.0",
     moduleRef: "execution-browser-extension",
     packageName: "@tomflow/proflow-execution-browser-extension",
-    moduleVersion: "0.1.4",
+    moduleVersion: "0.1.5",
     kind: "browser-extension",
     templateVersion: "1.0.0",
     platformCompatibility: ">=1.0.0 <2.0.0",
@@ -42,96 +42,16 @@ export const descriptor = {
             action: "Load and verify the unpacked MV3 extension in the real Chrome profile",
         },
     ],
-    configSlots: [
-        {
-            key: "bridge.endpoint",
-            type: "url",
-            required: true,
-            description: "Loopback Browser Reality Bridge endpoint",
-        },
-        {
-            key: "bridge.token",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the Browser Reality Bridge extension token",
-        },
-        {
-            key: "taskApplication.endpoint",
-            type: "url",
-            required: true,
-            description: "Loopback Platform Host Task application endpoint",
-        },
-        {
-            key: "taskApplication.token",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the Platform Host Task application token",
-        },
-        {
-            key: "approvalApplication.endpoint",
-            type: "url",
-            required: true,
-            description: "Loopback Platform Host Approval application endpoint",
-        },
-        {
-            key: "approvalApplication.token",
-            type: "path",
-            required: true,
-            sensitive: true,
-            description: "File containing the Platform Host Approval application token",
-        },
-        {
-            key: "verificationEvidenceFile",
-            type: "path",
-            required: true,
-            description: "JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs",
-        },
-        {
-            key: "chromeRuntimeModuleRef",
-            type: "moduleRef",
-            required: false,
-            description: "External resource module governing the Chrome runtime",
-            default: "chrome-runtime",
-        },
-        {
-            key: "carrierModuleRef",
-            type: "moduleRef",
-            required: false,
-            description: "External resource module governing the Custom GPT carrier",
-            default: "chatgpt-carrier",
-        },
-    ],
-    lifecycle: {
-        supported: ["describe", "preflight", "status", "verify", "doctor"],
-    },
-    verification: {
-        checks: [
-            {
-                id: "real-carrier-e3-e4",
-                description: "Real Chrome and ChatGPT E3/E4 evidence is present",
-                lifecycle: "verify",
-            },
-        ],
-    },
+    configSlots: [],
     effects: [
         {
             kind: "external-resource",
-            description: "Package an MV3 extension that performs Execution-authorized Browser effects",
+            description: "Materialize the unpacked MV3 extension package",
             retention: "preserve",
         },
     ],
-    documentation: [
-        {
-            id: "overview",
-            path: "./README.md",
-            description: "Package-owned module overview",
-        },
-        {
-            id: "configuration",
-            path: "./CONFIGURATION.md",
-            description: "Module configuration fields, sources and materialization instructions",
-        },
-    ],
+    documentation: {
+        docs: "DOCS.md",
+        setup: "SETUP.md",
+    },
 };

package/manifest.json

@@ -1,7 +1,7 @@
 {
 	"manifest_version": 3,
 	"name": "ProFlow Execution Browser",
-	"version": "0.1.4",
+	"version": "0.1.5",
 	"permissions": ["tabs", "storage", "sidePanel"],
 	"host_permissions": ["https://chatgpt.com/*", "http://127.0.0.1/*"],
 	"background": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomflow/proflow-execution-browser-extension",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Execution-owned MV3 Browser executor, evidence provider and browser application surface.",
   "type": "module",
   "publishConfig": {
@@ -22,15 +22,16 @@
     "proflow.module.json",
     "conformance.json",
     "README.md",
-    "CONFIGURATION.md"
+    "DOCS.md",
+    "SETUP.md"
   ],
   "dependencies": {
-    "@tomflow/proflow-module-contract": "^0.1.2",
-    "@tomflow/proflow-execution-contracts": "^0.1.3"
+    "@tomflow/proflow-execution-contracts": "^0.1.4",
+    "@tomflow/proflow-module-contract": "^0.1.4"
   },
   "devDependencies": {
-    "@tomflow/proflow-deployment-conformance": "^0.1.3",
-    "@tomflow/proflow-execution-runtime": "^0.1.5"
+    "@tomflow/proflow-execution-runtime": "^0.1.7",
+    "@tomflow/proflow-deployment-conformance": "^0.1.4"
   },
   "keywords": [
     "proflow",

package/proflow.module.json

@@ -3,7 +3,7 @@
 	"contractVersion": "1.0.0",
 	"moduleRef": "execution-browser-extension",
 	"packageName": "@tomflow/proflow-execution-browser-extension",
-	"moduleVersion": "0.1.4",
+	"moduleVersion": "0.1.5",
 	"kind": "browser-extension",
 	"templateVersion": "1.0.0",
 	"platformCompatibility": ">=1.0.0 <2.0.0",
@@ -42,96 +42,16 @@
 			"action": "Load and verify the unpacked MV3 extension in the real Chrome profile"
 		}
 	],
-	"configSlots": [
-		{
-			"key": "bridge.endpoint",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Browser Reality Bridge endpoint"
-		},
-		{
-			"key": "bridge.token",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the Browser Reality Bridge extension token"
-		},
-		{
-			"key": "taskApplication.endpoint",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Platform Host Task application endpoint"
-		},
-		{
-			"key": "taskApplication.token",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the Platform Host Task application token"
-		},
-		{
-			"key": "approvalApplication.endpoint",
-			"type": "url",
-			"required": true,
-			"description": "Loopback Platform Host Approval application endpoint"
-		},
-		{
-			"key": "approvalApplication.token",
-			"type": "path",
-			"required": true,
-			"sensitive": true,
-			"description": "File containing the Platform Host Approval application token"
-		},
-		{
-			"key": "verificationEvidenceFile",
-			"type": "path",
-			"required": true,
-			"description": "JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs"
-		},
-		{
-			"key": "chromeRuntimeModuleRef",
-			"type": "moduleRef",
-			"required": false,
-			"description": "External resource module governing the Chrome runtime",
-			"default": "chrome-runtime"
-		},
-		{
-			"key": "carrierModuleRef",
-			"type": "moduleRef",
-			"required": false,
-			"description": "External resource module governing the Custom GPT carrier",
-			"default": "chatgpt-carrier"
-		}
-	],
-	"lifecycle": {
-		"supported": ["describe", "preflight", "status", "verify", "doctor"]
-	},
-	"verification": {
-		"checks": [
-			{
-				"id": "real-carrier-e3-e4",
-				"description": "Real Chrome and ChatGPT E3/E4 evidence is present",
-				"lifecycle": "verify"
-			}
-		]
-	},
+	"configSlots": [],
 	"effects": [
 		{
 			"kind": "external-resource",
-			"description": "Package an MV3 extension that performs Execution-authorized Browser effects",
+			"description": "Materialize the unpacked MV3 extension package",
 			"retention": "preserve"
 		}
 	],
-	"documentation": [
-		{
-			"id": "overview",
-			"path": "./README.md",
-			"description": "Package-owned module overview"
-		},
-		{
-			"id": "configuration",
-			"path": "./CONFIGURATION.md",
-			"description": "Module configuration fields, sources and materialization instructions"
-		}
-	]
+	"documentation": {
+		"docs": "DOCS.md",
+		"setup": "SETUP.md"
+	}
 }

package/CONFIGURATION.md

@@ -1,33 +0,0 @@
-# execution-browser-extension configuration
-
-Canonical public config: `.proflow/config/execution-browser-extension.json`
-
-This file is Workspace-owned data. `platform uninstall` does not delete it. Values are JSON strings. Raw secrets must not be stored here; `secretRef` fields contain opaque references only.
-
-## Fields
-
-| Key | Type | Required | Sensitive | Source | Meaning |
-|---|---|---:|---:|---|---|
-| `bridge.endpoint` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Browser Reality Bridge endpoint |
-| `bridge.token` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the Browser Reality Bridge extension token |
-| `taskApplication.endpoint` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Platform Host Task application endpoint |
-| `taskApplication.token` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the Platform Host Task application token |
-| `approvalApplication.endpoint` | `url` | yes | no | User or owning external/runtime Module supplies the reachable endpoint URL. | Loopback Platform Host Approval application endpoint |
-| `approvalApplication.token` | `path` | yes | yes | User or owning Module supplies an absolute/local path that exists on this Workspace. | File containing the Platform Host Approval application token |
-| `verificationEvidenceFile` | `path` | yes | no | User or owning Module supplies an absolute/local path that exists on this Workspace. | JSON evidence file written after real Chrome loads the Deployment-managed MV3 extension and its Service Worker runs |
-| `chromeRuntimeModuleRef` | `moduleRef` | no | no | Another installed ProFlow Module reference selected from `platform docs` / Module topology. | External resource module governing the Chrome runtime |
-| `carrierModuleRef` | `moduleRef` | no | no | Another installed ProFlow Module reference selected from `platform docs` / Module topology. | External resource module governing the Custom GPT carrier |
-
-## Materialize
-
-Create or update the canonical JSON object at:
-
-`.proflow/config/execution-browser-extension.json`
-
-Use only declared keys and string values. Do not create a second Platform configuration database.
-
-The Browser Extension also requires a package-owned physical runtime config artifact. After the canonical Module config is present, run `proflow-execution-browser-extension materialize-config --workspace <path>`. This package-owned command writes the private runtime artifact under `.proflow/deployment/browser-extension/execution-browser-extension/`; `platform start` must not perform this materialization implicitly.
-
-## Base completion check
-
-Run `platform modules`. This Module should no longer report required keys in `missingConfig`. `platform start` performs the authoritative Module-owned validation before starting anything.