integration.lssm-os-provider-docker

@lssm-tech/integration.lssm-os-provider-docker

Authoritative Docker Compose execution adapter for the LSSM OS ProviderExecutionPort. It owns only plan changes whose ownership tuple is docker_compose / lssm-os-provider-docker.

The ./runtime-node export directly implements ProviderLifecyclePortV1 over closed, secret-free, digest-bound V2 commands. It reserves the exact execution and fence before invoking the Docker driver, persists an exact V2 receipt, supports read-only observation, and replays only independently verified durable state. It never calls the compatibility ProviderExecutionPort or projects a legacy receipt into production authority.

Boundary

The adapter never spawns Docker. Callers inject a DockerRuntimePort that accepts an executable plus an argv array, structured sanitized results, and opaque credential references. This keeps shell parsing and secret values out of the provider contract and makes the adapter deterministic under tests.

import { DockerProviderExecutionAdapter } from
  "@lssm-tech/integration.lssm-os-provider-docker";

const provider = new DockerProviderExecutionAdapter({
  runtime: dockerRuntimePort,
  observations: trustedObservationVerifier,
  receipts: trustedReceiptStore,
  executions: durableExecutionState,
  clock,
  ids,
}, { timeoutMs: 120_000 });

const receipt = await provider.execute(authorizedStep);
if (!(await provider.verifyReceipt(receipt))) {
  throw new Error("Untrusted Docker receipt");
}

The injected runtime is responsible for resolving canonical credential://docker/... references and recording normalized evidence. Values must never be returned in output, evidence references, observations, errors, or fixtures. Production composition must provide durable atomic execution state; the in-memory implementation is testing-only.

Supported v0 behavior

• strict ownership, action, change, resource-limit, and credential-ref decoding;
• optional image builds with OCI source-revision labels and image inspection;
• Compose up, update, delete/decommission, rollback, and create compensation;
• topology import, image/health drift, and runtime status discovery;
• durable restart-safe per-resource fencing and idempotent execution/compensation;
• scope-encoded docker-operation:v2 keys so equal tenant idempotency keys do not collide;
• closed, secret-safe discovery scopes, authority key references, and adapter-owned canonical receipt/reservation IDs validated before runtime or durable-state use;
• canonical effect recomputation and immutable retry fingerprints across scope, plan, authorization attestation, credentials, desired properties, fence, ownership, and action;
• independently verified, read-only, secret-rejecting Docker observations for every discovery and effect read, with exact requested-service health and resource-limit verification;
• service-scoped Compose mutation (up --no-deps) and verified absence after destructive operations;
• current-step cleanup before failed receipts, rollback restoration for partial update/delete effects, and an indeterminate throw when cleanup cannot be verified;
• compensation and rollback only from an exact trusted prior successful apply, including a fresh read-only observation, desired properties, credentials, image provenance, and resource limits;
• one absolute operation deadline; a non-cooperative or unresolved provider call becomes durable indeterminate work and cannot be retried as a new effect;
• receipts bound to scope, plan, authorization decision and attestation, idempotency key, fence, effect, issuance anchor, and canonical receipt attestation;
• create-once receipt issuance through a versioned external Ed25519 authority seal that also binds the durable reservation and operation/resource keys, followed by exact authority and execution-state read-back before success;
• a zero-dollar local-runtime estimate when no provider invoice exists.

The offline conformance target passes all ten required provider-conformance registry/protocol 0.3.0 cases. Its restart and stale-fence cases use one mutating apply and read-only observations; reconciliation never calls the mutation oracle. This is not a live Docker or host-platform qualification claim. The ./testing export supplies fake runtime, execution state, trust ports, and sanitized fixtures for offline consumers.

Pending or indeterminate operations deliberately remain fenced until an external operator or durable-state implementation performs authoritative reconciliation. The adapter never converts an unresolved provider outcome into a definitive failed receipt. Replay requires the stored operation fingerprint to match the current claim, and unverifiable cleanup is durably indeterminate.

Cleanup removes only the exact requested Compose service and verifies absence. It never force-removes an image tag, because a failed build cannot prove that the tag did not pre-exist or that the current effect owns it. Build failure before any Compose mutation never invokes compose down.

All caller execution data and every request crossing an injected port are deep cloned and frozen. Returned authority/state records are cloned and semantically revalidated so a retained external reference cannot rewrite receipt or authorization bindings. Injected-port failures are normalized to adapter-owned codes and never expose external exception text.

Development

bun run lint:check
bun run typecheck
bun test
bun run build
npm_config_offline=true bun run test:pack
npm pack --dry-run

test:pack creates the real tarball, stages governed semver dependencies in a clean consumer, runs npm ls --all, and imports ., ./conformance, and ./testing with Node and Bun.