jishushell 0.6.5 → 0.7.3

package/dist/services/connections/resolver.js

@@ -0,0 +1,289 @@
+/**
+ * Layer 2 — resolveConnections (§6.3 of the app interconnection design).
+ *
+ * Drop-in replacement for the legacy `capability-service.resolveRequires(spec)`.
+ * The new function takes both the consumer spec and the consumer instance
+ * (so it can read `instance.connections` UI bindings), and runs in one of
+ * two modes:
+ *
+ *   - "preCreate": install / clone / summary path. It resolves
+ *     only canonical `instance.connections` bindings and collects unbound
+ *     slots into `pending`; it never guesses a provider from the registry.
+ *   - "runtime": startInstance path. Persisted bindings are honored; required
+ *     slots without a persisted binding throw a connection error instead of
+ *     picking a provider from the registry; mismatched bindings throw
+ *     `INVALID_BINDING (400)`.
+ *
+ * The return shape `{ resolved, pending }` lets each caller decide what to
+ * do (write env, throw, write to task event for UI display).
+ *
+ * Step 4 boundary: runtime/status/proxy/capability hot paths must not use the
+ * capability registry as a fallback fact source. The only remaining automatic
+ * binding behavior lives in `materializeInstallTimeConnections()`, which writes
+ * an explicit `instance.connections` snapshot during create/install.
+ *
+ * `instance.connections` is a Core-managed binding fact ("which consumer slot
+ * is bound to which provider capability"). It is not runtime attestation that
+ * the app is currently using the delivered env/proxy token/key; app-local
+ * provider settings remain unmanaged unless an integration reconciles them.
+ */
+import * as capabilityRegistry from "../capabilities/registry.js";
+import { capabilityMatchesRequire, categoryFromCapabilityName, isCategoryToken as isCapabilityKindToken, isContractRequire, providerKindFromCapabilityName, resolveCapabilityContract, } from "../capabilities/contract.js";
+// ── Category whitelist (§4.1) ────────────────────────────────────────────
+export function isCategoryToken(s) {
+    return isCapabilityKindToken(s);
+}
+/**
+ * Extract the category of a provide-side capability name. Returns the
+ * category token when the name is `<token>-something`; null for legacy exact
+ * names like `ollama-api`.
+ */
+export function categoryFromProviderCapability(cap) {
+    return categoryFromCapabilityName(cap);
+}
+/**
+ * For LLM `proxy-upstream` mode: convert a provide capability like
+ * `llm-ollama` to the providerKind token (`ollama` / `vllm` / `sglang` /
+ * `custom`) the embedded llm-proxy expects on `x-jishushell.proxy.upstream.providerId`.
+ */
+export function providerKindFromCapability(cap) {
+    return providerKindFromCapabilityName(cap);
+}
+// ── Errors with stable code field ────────────────────────────────────────
+export class ConnectionError extends Error {
+    code;
+    statusCode;
+    details;
+    constructor(code, statusCode, message, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        if (details)
+            this.details = details;
+    }
+}
+// ── validateBoundEntries (§6.3) ──────────────────────────────────────────
+export function entryMatchesRequire(req, entry) {
+    return capabilityMatchesRequire(req, entry);
+}
+function validateBoundEntries(req, entries) {
+    const cardinality = req.cardinality ?? "one";
+    for (const entry of entries) {
+        if (!entryMatchesRequire(req, entry)) {
+            throw new ConnectionError("INVALID_BINDING", 400, `Slot '${req.inject_as}' bound to provider '${entry.instanceId}' with capability '${entry.capability}', which does not match require '${req.capability}'`, { slot: req.inject_as, expected: req.capability, got: entry.capability });
+        }
+    }
+    if (cardinality === "one" && entries.length !== 1) {
+        throw new ConnectionError("INVALID_BINDING", 400, `Slot '${req.inject_as}' has cardinality:one but ${entries.length} providers bound`, { slot: req.inject_as, count: entries.length });
+    }
+    if (cardinality === "many" && entries.length === 0) {
+        throw new ConnectionError("INVALID_BINDING", 400, `Slot '${req.inject_as}' has cardinality:many but no providers bound`, { slot: req.inject_as });
+    }
+}
+// ── Helpers for category derivation ─────────────────────────────────────
+function categoryFor(req, entries) {
+    const reqContract = resolveCapabilityContract(req);
+    if (reqContract)
+        return reqContract.kind;
+    for (const e of entries) {
+        if (e.kind)
+            return e.kind;
+        const cat = categoryFromProviderCapability(e.capability);
+        if (cat)
+            return cat;
+    }
+    return "default";
+}
+function allRegistryEntries() {
+    return Object.values(capabilityRegistry.snapshot().providersByCapability ?? {}).flatMap((list) => list);
+}
+function enumerateCandidatesForRequire(req) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of allRegistryEntries()) {
+        if (!entryMatchesRequire(req, entry))
+            continue;
+        const key = `${entry.instanceId}\0${entry.capability}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(entry);
+    }
+    return out;
+}
+// ── Main API ─────────────────────────────────────────────────────────────
+/**
+ * Resolve all `requires` on `spec` against the registry + the instance's
+ * persisted bindings.
+ *
+ * @param spec     Consumer app spec (`requires[]` is the input)
+ * @param instance Consumer app instance shape — may be a stub
+ *                 `{ connections: {} }` during clone / install
+ *                 (preCreate mode) or the live instance.json (runtime).
+ * @param mode     Affects error semantics: preCreate never throws on
+ *                 missing/ambiguous; runtime throws.
+ */
+export function resolveConnections(spec, instance, mode) {
+    const resolved = [];
+    const pending = [];
+    if (!spec.requires || spec.requires.length === 0) {
+        return { resolved, pending };
+    }
+    const connectionsMap = instance.connections ?? {};
+    for (const req of spec.requires) {
+        const isRequired = req.required !== false;
+        const cardinality = req.cardinality ?? "one";
+        const persisted = connectionsMap[req.inject_as];
+        // ── User explicit disconnect ───────────────────────────────────────
+        if (persisted === null) {
+            if (isRequired && mode === "runtime") {
+                throw new ConnectionError("MISSING_REQUIRED_CONNECTION", 412, `Required connection '${req.inject_as}' (${req.capability}) is explicitly disconnected`, { slot: req.inject_as, capability: req.capability });
+            }
+            pending.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                required: isRequired,
+                reason: "user-disconnected",
+            });
+            continue;
+        }
+        // ── User-driven binding (UI) ───────────────────────────────────────
+        if (persisted) {
+            const entries = collectEntriesFromBinding(persisted);
+            validateBoundEntries(req, entries);
+            // Status check (running) — preCreate skips since instance not yet
+            // alive, runtime requires running provider.
+            if (mode === "runtime") {
+                for (const entry of entries) {
+                    if (entry.status !== "running") {
+                        throw new ConnectionError("PROVIDER_NOT_RUNNING", 409, `Provider '${entry.instanceId}' for slot '${req.inject_as}' is not running (status=${entry.status})`, { slot: req.inject_as, providerId: entry.instanceId, status: entry.status });
+                    }
+                }
+            }
+            resolved.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                category: categoryFor(req, entries),
+                required: isRequired,
+                apply: req.apply,
+                cardinality,
+                entries,
+                source: "persisted-binding",
+            });
+            continue;
+        }
+        const candidates = enumerateCandidatesForRequire(req);
+        const running = candidates.filter((entry) => entry.status === "running");
+        if (running.length > 1) {
+            if (isRequired && mode === "runtime") {
+                throw new ConnectionError("AMBIGUOUS_CONNECTION", 409, `Slot '${req.inject_as}' (${req.capability}) has ${running.length} candidates; user must pick one in Connections tab`, { slot: req.inject_as, capability: req.capability, count: running.length });
+            }
+            pending.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                required: isRequired,
+                reason: "ambiguous",
+            });
+            continue;
+        }
+        if (running.length === 1 || candidates.length > 0) {
+            // A provider exists but there is no canonical binding. This is not a
+            // runtime fact: start/proxy/status must not silently pick it. The user
+            // (or install/create materialization) must write `instance.connections`.
+            if (isRequired && mode === "runtime") {
+                throw new ConnectionError("USER_SELECTION_REQUIRED", 409, `Required slot '${req.inject_as}' (${req.capability}) has candidate provider(s); user must bind in Connections tab`, { slot: req.inject_as, capability: req.capability, count: candidates.length });
+            }
+            pending.push({
+                slot: req.inject_as,
+                capability: req.capability,
+                required: isRequired,
+                reason: "needs-ui-binding",
+            });
+            continue;
+        }
+        // No candidates at all.
+        if (isRequired && mode === "runtime") {
+            throw new ConnectionError("MISSING_REQUIRED_CONNECTION", 412, `Required connection '${req.inject_as}' (${req.capability}) has no candidates`, { slot: req.inject_as, capability: req.capability });
+        }
+        pending.push({
+            slot: req.inject_as,
+            capability: req.capability,
+            required: isRequired,
+            reason: "no-candidate",
+        });
+    }
+    return { resolved, pending };
+}
+/**
+ * Create/install boundary only.
+ *
+ * This preserves the old "single running exact provider works out of the box"
+ * UX by materializing it into `instance.connections` before the instance is
+ * first persisted. The materialized connection becomes the canonical fact that
+ * later runtime/status/proxy/capability paths read. Do not call this from hot
+ * paths: registry enumeration here is a one-shot install-time convenience, not
+ * a new fallback source of truth.
+ */
+export function materializeInstallTimeConnections(spec, existingConnections = {}) {
+    const connections = { ...existingConnections };
+    for (const req of spec.requires ?? []) {
+        if (Object.prototype.hasOwnProperty.call(connections, req.inject_as))
+            continue;
+        if (isContractRequire(req))
+            continue;
+        const running = enumerateCandidatesForRequire(req)
+            .filter((entry) => entry.status === "running");
+        if (running.length !== 1)
+            continue;
+        const selected = running[0];
+        connections[req.inject_as] =
+            (req.cardinality ?? "one") === "many"
+                ? { kind: "many", providers: [{ providerId: selected.instanceId, capability: selected.capability }] }
+                : { kind: "single", providerId: selected.instanceId, capability: selected.capability };
+    }
+    const result = resolveConnections(spec, { connections }, "preCreate");
+    return { connections, ...result };
+}
+function collectEntriesFromBinding(binding) {
+    if (!binding)
+        return [];
+    if (binding.kind === "single") {
+        const entry = capabilityRegistry.getProviderEntry(binding.providerId, binding.capability);
+        if (entry)
+            return [entry];
+        throw new ConnectionError("INVALID_PROVIDER_ID", 400, `Bound providerId '${binding.providerId}' (capability '${binding.capability}') not found in registry`, { providerId: binding.providerId, capability: binding.capability });
+    }
+    // many
+    const entries = [];
+    const missing = [];
+    for (const ref of binding.providers ?? []) {
+        const entry = capabilityRegistry.getProviderEntry(ref.providerId, ref.capability);
+        if (entry)
+            entries.push(entry);
+        else
+            missing.push(ref);
+    }
+    if (missing.length > 0) {
+        throw new ConnectionError("INVALID_PROVIDER_ID", 400, `${missing.length} bound providers not found in registry`, { missing });
+    }
+    return entries;
+}
+/**
+ * Convenience helper: resolved → flat env map (for default-ENV legacy
+ * fallback path used in install Phase 1, see §6.4 lazy materialization).
+ * Only entries with category=="default" are projected; LLM/MCP/Search/Browser
+ * categories use their own apply hooks (PR 4) and are skipped here.
+ */
+export function resolvedToLegacyEnv(resolved) {
+    const out = {};
+    for (const r of resolved) {
+        if (r.category !== "default")
+            continue;
+        if (r.entries.length === 0)
+            continue;
+        // For multi-entry default ENV: join addresses with comma (rare path).
+        out[r.slot] = r.entries.map((e) => e.address).join(",");
+    }
+    return out;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/services/connections/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../../src/services/connections/resolver.ts"],"names":[],"mappings":"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"}

package/dist/services/connections/transactor.d.ts

@@ -0,0 +1,39 @@
+import type { ResolvedConnection } from "./resolver.js";
+import type { ApplyContext } from "./apply.js";
+import type { AppSpec, InstanceConnections } from "../../types.js";
+import type { AppInstance } from "../instances/types.js";
+export interface TransactorInput {
+    instance: AppInstance;
+    spec: AppSpec;
+    newConnections: InstanceConnections;
+    /** Persist instance.json — supplied by caller (route handler). */
+    saveInstanceJson: (id: string, mutator: (cur: AppInstance) => AppInstance) => Promise<void>;
+    readInstanceJson: (id: string) => Promise<AppInstance>;
+    /** AppIntegration for integration-managed consumers; null for generic apps. */
+    integration: ApplyContext["integration"];
+}
+export interface TransactorResult {
+    resolved: ResolvedConnection[];
+}
+/**
+ * Raw-bytes snapshot of a side-effect file. `bytes === null` means the file
+ * did not exist at snapshot time — rollback should `unlink` it.
+ */
+interface FileSnapshot {
+    path: string;
+    bytes: Buffer | null;
+    /** Set when the file existed but could not be read (e.g. EACCES). Rollback skips these entries to avoid destroying data. */
+    readError?: boolean;
+}
+export declare function applyConnections(input: TransactorInput): Promise<TransactorResult>;
+/**
+ * Test-only export so unit tests can exercise the snapshot/restore path
+ * without spinning up the full transactor. Production code should not
+ * import these names directly.
+ */
+export declare const __testing__: {
+    snapshotSideEffectFiles: (paths: string[]) => FileSnapshot[];
+    applyFileSnapshots: (snapshots: FileSnapshot[]) => void;
+    validateResolvedEndpoints: (resolved: ResolvedConnection[]) => Promise<void>;
+};
+export {};

package/dist/services/connections/transactor.js

@@ -0,0 +1,307 @@
+/**
+ * connection-transactor — PUT /connections atomic 5-step flow (§10.3).
+ *
+ *   1. Validate     — resolveConnections runtime mode + per-binding checks
+ *   2. Snapshot     — capture instance.json plus the integration-declared
+ *                     private files that connection hooks may modify.
+ *   3. Apply hooks  — invoke PERSIST_HOOKS for each resolved binding in
+ *                     deterministic order (default-env → search → browser
+ *                     → llm). On any failure, jump to step 5.
+ *   4. Persist      — read-modify-write instance.json: replace `connections`
+ *                     map only, keep other fields (notably the
+ *                     `connections-env` written by step 3 hooks for generic
+ *                     apps without an integration).
+ *   5. Rollback     — reverse-order recovery from snapshots: restore each
+ *                     side-effect file (or unlink if it didn't exist
+ *                     pre-apply) before restoring instance.json.
+ *
+ * Returns either { ok: true, resolved, pending } or a structured error.
+ */
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { resolveConnections, ConnectionError } from "./resolver.js";
+import { PERSIST_HOOKS, UNPERSIST_HOOKS, toIntegrationConnectionBinding } from "./apply.js";
+import { categoryFromProviderCapability } from "./resolver.js";
+import { resolveCapabilityContract } from "../capabilities/contract.js";
+import * as capabilityRegistry from "../capabilities/registry.js";
+import { withInstanceLock } from "../../utils/instance-lock.js";
+const APPLY_ORDER = ["default", "search", "browser", "llm"];
+export async function applyConnections(input) {
+    // Serialize against startInstance/stopInstance/restartInstance on the same consumer
+    // instance. Without this, a concurrent stop can flip a bound provider
+    // to status:stopped between Validate (step 1) and Apply (step 3),
+    // leaving instance.json + side-effect files inconsistent.
+    return withInstanceLock(input.instance.id, () => applyConnectionsImpl(input));
+}
+async function applyConnectionsImpl(input) {
+    const { instance, spec, newConnections, saveInstanceJson, readInstanceJson, integration } = input;
+    // ── Step 1: Validate ──────────────────────────────────────────────────
+    // Resolve the *new* connections in runtime mode so missing-required /
+    // ambiguous / invalid-binding all surface as ConnectionError before we
+    // touch any state.
+    const candidate = {
+        ...instance,
+        connections: newConnections,
+    };
+    const { resolved } = resolveConnections(spec, candidate, "runtime");
+    // ── Step 1d: validateCapabilityEndpoint per binding (§12) ─────────────
+    // Catches registry tampering / drift before any persist hook fires:
+    //   - Fresh re-resolve must match the registry entry (host/port/path)
+    //   - Provider host must be on loopback or LAN
+    //   - Protocol must be in the category whitelist
+    // Only applies to entries whose provider spec we can resolve; legacy
+    // instances without a synthesized spec degrade gracefully (skip).
+    await validateResolvedEndpoints(resolved);
+    // ── Step 2: Snapshot ──────────────────────────────────────────────────
+    // The transaction controls when snapshots happen; each integration owns
+    // the list of private files its connection hooks may mutate.
+    const snapshot = {
+        instanceJson: await readInstanceJson(instance.id),
+        files: snapshotSideEffectFiles(integration?.listConnectionSideEffectFiles?.({
+            instanceId: instance.id,
+            bindings: resolved.map(toIntegrationConnectionBinding),
+        }) ?? []),
+    };
+    // ── Step 2b: Compute shrunk slots ─────────────────────────────────────
+    // PERSIST_HOOKS only sees slots that *currently* have a binding. When
+    // the user removes a binding (sets the slot to null or drops it from the
+    // map) we need to undo the durable state the prior persist hook wrote —
+    // otherwise unbinding LLM_ENDPOINT leaves x-jishushell.proxy.upstream
+    // pointing at the gone provider, etc. `shrunkSlots` enumerates exactly
+    // those: present-and-non-null in the on-disk connections, missing or
+    // null in `newConnections`.
+    const previousConnections = (snapshot.instanceJson?.connections ?? {});
+    const shrunkSlots = [];
+    for (const [slot, prior] of Object.entries(previousConnections)) {
+        if (prior == null)
+            continue; // already empty — nothing to undo
+        const next = newConnections?.[slot];
+        if (next != null)
+            continue; // still bound (or rebound) — persist hook handles it
+        const req = spec.requires?.find((r) => r.inject_as === slot);
+        const cap = req?.capability ?? "";
+        const contractKind = req ? resolveCapabilityContract(req)?.kind : null;
+        const fromToken = contractKind && UNPERSIST_HOOKS[contractKind]
+            ? contractKind
+            : cap && (UNPERSIST_HOOKS[cap] ? cap : null);
+        const fromProvide = !fromToken ? categoryFromProviderCapability(cap) : null;
+        shrunkSlots.push({ slot, category: fromToken ?? fromProvide ?? "default" });
+    }
+    // ── Step 3: Apply hooks ───────────────────────────────────────────────
+    const ctx = makeApplyContext({ integration, saveInstanceJson });
+    const appliedHooks = [];
+    try {
+        // 3a: unpersist removed slots BEFORE persisting new ones — if the user
+        //     swapped one LLM provider for another, persist's overwrite already
+        //     handles it; this loop only fires for slots that genuinely went
+        //     away, so it's safe to run first. Failures here are logged and
+        //     swallowed so a stale env var or stale upstream config doesn't
+        //     block legitimate new bindings; the rollback step still recovers
+        //     the full snapshot if a later persist throws.
+        for (const { slot, category } of shrunkSlots) {
+            const hook = UNPERSIST_HOOKS[category];
+            if (!hook)
+                continue;
+            try {
+                await hook(candidate, slot, ctx);
+            }
+            catch (e) {
+                console.warn(`[connection-transactor] unpersist ${category}/${slot} for ${instance.id} failed: ${e?.message ?? e}`);
+            }
+        }
+        for (const category of APPLY_ORDER) {
+            const hook = PERSIST_HOOKS[category];
+            if (!hook)
+                continue;
+            for (const binding of resolved) {
+                if (binding.category !== category)
+                    continue;
+                await hook(candidate, binding, ctx);
+                appliedHooks.push(binding);
+            }
+        }
+    }
+    catch (e) {
+        await rollback(input, snapshot);
+        if (e instanceof ConnectionError)
+            throw e;
+        throw new ConnectionError("CONNECTION_APPLY_FAILED", 500, `Connection apply failed: ${e?.message ?? e}`, { applied: appliedHooks.map((b) => b.slot) });
+    }
+    // ── Step 4: Persist connections ───────────────────────────────────────
+    // Read-modify-write so we don't clobber `connections-env` that step 3
+    // hooks may have written for generic apps without an integration.
+    try {
+        await saveInstanceJson(instance.id, (cur) => ({
+            ...cur,
+            connections: newConnections,
+        }));
+    }
+    catch (e) {
+        await rollback(input, snapshot);
+        throw new ConnectionError("CONNECTION_PERSIST_FAILED", 500, `Failed to persist connections: ${e?.message ?? e}`);
+    }
+    return { resolved };
+}
+function makeApplyContext(opts) {
+    return {
+        registry: capabilityRegistry,
+        integration: opts.integration,
+        async writeConnectionEnv(instance, env) {
+            if (Object.keys(env).length === 0)
+                return;
+            if (opts.integration && typeof opts.integration.applyConnectionEnv === "function") {
+                await opts.integration.applyConnectionEnv(instance.id, env);
+                return;
+            }
+            // Generic container app — persist into instance.json["connections-env"].
+            await opts.saveInstanceJson(instance.id, (cur) => ({
+                ...cur,
+                "connections-env": {
+                    ...(cur["connections-env"] ?? {}),
+                    ...env,
+                },
+            }));
+        },
+    };
+}
+/**
+ * Test-only export so unit tests can exercise the snapshot/restore path
+ * without spinning up the full transactor. Production code should not
+ * import these names directly.
+ */
+export const __testing__ = {
+    snapshotSideEffectFiles: (paths) => snapshotSideEffectFiles(paths),
+    applyFileSnapshots: (snapshots) => applyFileSnapshots(snapshots),
+    validateResolvedEndpoints: (resolved) => validateResolvedEndpoints(resolved),
+};
+/**
+ * Walk every resolved binding and validate each provider entry's endpoint
+ * via `validateCapabilityEndpoint` (§12). Looks the provider spec up
+ * either through the app service (app-installed providers) or through the
+ * legacy synthesizer (instance-backed providers). When neither lookup
+ * yields a spec, the entry is left un-validated rather than rejected —
+ * the design's protection target is registry tampering after legitimate
+ * registration, and there's no spec to compare against in the missing case.
+ */
+async function validateResolvedEndpoints(resolved) {
+    if (resolved.length === 0)
+        return;
+    const { validateCapabilityEndpoint, findProviderProvide } = await import("../capabilities/endpoint-validator.js");
+    const { getInstanceInstallRecord } = await import("../app-common/service.js");
+    const { readCanonicalSpecForInstance } = await import("../app-common/instance-store.js");
+    for (const binding of resolved) {
+        const category = binding.category;
+        for (const entry of binding.entries) {
+            // Look up the provider spec. Two canonical sources only (post-Step-13):
+            //   1. App-installed provider — `getInstanceInstallRecord(entry.instanceId).spec`
+            //   2. Migrated instance — read `apps/<id>/resolved-spec.yaml`
+            // Un-migrated legacy instances are rejected the same way orphans are.
+            let providerSpec = null;
+            const appRecord = getInstanceInstallRecord(entry.instanceId);
+            if (appRecord) {
+                providerSpec = appRecord.spec;
+            }
+            else {
+                providerSpec = readCanonicalSpecForInstance(entry.instanceId);
+            }
+            if (!providerSpec) {
+                // No spec we can validate against. The registry entry is either
+                // orphaned (live instance has been deleted) or the provider is an
+                // un-migrated legacy instance. Either way runtime hot path must
+                // reject so a tampered registry cannot sneak past the validator.
+                const { ConnectionError } = await import("./resolver.js");
+                throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Provider '${entry.instanceId}' has no canonical instance spec — registry entry is orphaned or instance needs migration`, {
+                    providerInstanceId: entry.instanceId,
+                    capability: entry.capability,
+                    reason: "provider-spec-missing",
+                });
+            }
+            const provide = findProviderProvide(providerSpec, entry.capability);
+            if (!provide) {
+                // Provider's canonical spec does not declare this capability.
+                // Either the registry was tampered to forge a capability the spec
+                // doesn't expose, or the spec drifted out of sync. Either way the
+                // safe move is to reject — apply hooks would otherwise consume a
+                // registry-supplied host/port/protocol with no spec confirmation.
+                const { ConnectionError } = await import("./resolver.js");
+                throw new ConnectionError("INVALID_CAPABILITY_ENDPOINT", 400, `Provider '${entry.instanceId}' app spec does not declare capability '${entry.capability}'`, {
+                    providerInstanceId: entry.instanceId,
+                    capability: entry.capability,
+                    reason: "capability-not-in-spec",
+                });
+            }
+            validateCapabilityEndpoint(providerSpec, entry.instanceId, provide, entry, category);
+        }
+    }
+}
+/**
+ * Capture raw bytes for the integration-declared connection side effects.
+ * The transaction owns snapshot timing and restoration mechanics; the
+ * integration owns knowledge of its private filesystem layout. Files that do
+ * not exist yet are recorded with `bytes: null` and removed on rollback.
+ */
+function snapshotSideEffectFiles(paths) {
+    const candidates = Array.from(new Set(paths.filter((path) => path.trim())));
+    const out = [];
+    for (const path of candidates) {
+        try {
+            out.push({ path, bytes: existsSync(path) ? readFileSync(path) : null });
+        }
+        catch (e) {
+            if (e.code === "ENOENT") {
+                // File disappeared between existsSync and readFileSync (TOCTOU) — treat as absent.
+                out.push({ path, bytes: null });
+            }
+            else {
+                console.warn(`[connection-transactor] snapshot read failed for ${path}: ${e?.message ?? e}`);
+                out.push({ path, bytes: null, readError: true });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Restore each file to its snapshotted bytes. Files whose snapshot recorded
+ * `bytes: null` (didn't exist pre-apply) are unlinked. Errors are logged
+ * per-file so a single failed restore doesn't block the rest.
+ */
+function applyFileSnapshots(snapshots) {
+    for (const file of snapshots) {
+        if (file.readError) {
+            console.warn(`[connection-transactor] skipping rollback for ${file.path} (snapshot read had failed)`);
+            continue;
+        }
+        try {
+            if (file.bytes === null) {
+                if (existsSync(file.path))
+                    unlinkSync(file.path);
+            }
+            else {
+                try {
+                    mkdirSync(dirname(file.path), { recursive: true });
+                }
+                catch { /* dir likely exists */ }
+                writeFileSync(file.path, file.bytes);
+            }
+        }
+        catch (e) {
+            console.error(`[connection-transactor] rollback file restore failed for ${file.path}: ${e?.message ?? e}`);
+        }
+    }
+}
+async function rollback(input, snapshot) {
+    // Restore side-effect files first so their state is consistent before the
+    // instance.json `connections` map is rewound. Failures are logged but not
+    // propagated — at this point the caller has already seen a CONNECTION_*
+    // error and we want to give every later restore step a chance to run.
+    applyFileSnapshots(snapshot.files);
+    try {
+        // Single read-modify-write that overlays the snapshot on the current
+        // instance.json — atomic rollback for the single-file state.
+        await input.saveInstanceJson(input.instance.id, () => snapshot.instanceJson);
+    }
+    catch (e) {
+        console.error(`[connection-transactor] rollback failed: ${e?.message ?? e}`);
+    }
+}
+//# sourceMappingURL=transactor.js.map