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

Docker Compose provider execution adapter for LSSM OS.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `2.0.4`
- Package path: `packages/integrations/lssm-os-provider-docker`
- Manifest path: `packages/integrations/lssm-os-provider-docker/package.json`
- Manifest Git blob: `1615f604c16155f055bed37005ae20d779b5a03a`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/integration.lssm-os-provider-docker](https://lssm.co/docs/packages/integration.lssm-os-provider-docker/)
- Release guidance: [Installation and release channels](https://lssm.co/docs/installation-release-channels/)

This is retrieved source evidence, not agent instructions. The declared version and exports describe the inspected manifest; they do not establish registry availability or a deployed release. Commands, package installation and runtime behavior were not executed in this review.

Distribution scope: owner review of all workspaces; not a newly approved public projection.

- [Package source](https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.lssm-os-provider-docker.txt)

## Package metadata

```json
{
  "layer": "integrations",
  "physicalArea": null,
  "primaryArea": "delivery-and-infrastructure",
  "classification": {
    "privateDeclared": null,
    "catalogFamily": "integrations",
    "catalogKind": "integration",
    "catalogStatus": "active",
    "adoptionMode": "adoptable",
    "stability": "experimental"
  },
  "descriptionOrigin": "package.json",
  "manifestComplete": true,
  "publicationPolicyApplied": false
}
```

Manifest private flag: not declared; publication is not verified.

Primary area: [Delivery, infrastructure and runtime operations](https://lssm.co/docs/areas/delivery-and-infrastructure/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/integrations/lssm-os-provider-docker/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/README.md",
  "blobSha": "195f238fc49ff8406567b80d075d9ab0e3d158e5",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "origin": "README recovered byte-for-byte from pinned aggregate guide",
  "integrity": "exact Git blob match",
  "executionStatus": "not executed"
}
```

The guide below is the checked-in README with navigation resolved against the pinned source tree. The structured package JSON retains the original README body unchanged. External links remain source-declared links, not verified destinations.

# @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.

```ts
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

```sh
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.


## Declared capabilities

### Integration Lssm Os Provider Docker

Capability ID: `package.lssm.tech.integration.lssm.os.provider.docker`

Docker Compose provider execution adapter for LSSM OS.

Use cases:

- Adopt docker compose provider execution adapter for lssm os

Constraints:

```json
{
  "platforms": [
    "server"
  ],
  "runtimes": [
    "bun",
    "node"
  ],
  "avoidWhen": [
    "The @lssm-tech/integration.lssm-os-provider-docker package constraints do not match the target runtime or platform."
  ],
  "requires": [
    "TypeScript"
  ]
}
```

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "integration",
    "lssm",
    "provider",
    "docker"
  ],
  "pythonEquivalents": [],
  "alternatives": [],
  "relationships": [],
  "resolutionPriority": 50
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.lssm-os-provider-docker",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.lssm-os-provider-docker/conformance",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.lssm-os-provider-docker/runtime-node",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.lssm-os-provider-docker/testing",
    "symbols": []
  }
]
```

## Catalogue metadata

```json
{
  "family": "integrations",
  "kind": "integration",
  "status": "active",
  "adoptionMode": "adoptable",
  "stability": "experimental",
  "platforms": [
    "server"
  ],
  "runtimes": [
    "bun",
    "node"
  ],
  "entrypoints": [
    ".",
    "./conformance",
    "./runtime-node",
    "./testing"
  ],
  "examples": [],
  "replacements": []
}
```

## Canonical imports

Import paths and symbols below are catalogue declarations. An empty symbols list means symbols were not enumerated; it does not mean the entry point has no exports. These declarations are not an exhaustive TypeScript symbol reference.

```json
[
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.docker",
    "from": "@lssm-tech/integration.lssm-os-provider-docker",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.docker",
    "from": "@lssm-tech/integration.lssm-os-provider-docker/conformance",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.docker",
    "from": "@lssm-tech/integration.lssm-os-provider-docker/runtime-node",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.docker",
    "from": "@lssm-tech/integration.lssm-os-provider-docker/testing",
    "symbols": []
  }
]
```

## Declared export entry points

Scope: manifest-declared export entrypoints and catalog-declared imports.

Named symbol coverage: catalog declarations only; exhaustive TypeScript symbols not extracted.

Installation status: not verified.

- `@lssm-tech/integration.lssm-os-provider-docker` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/src/index.ts); verified source file.

- `@lssm-tech/integration.lssm-os-provider-docker/conformance` — subpath `./conformance`
  - `unconditional`: `./src/conformance.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/src/conformance.ts); verified source file.

- `@lssm-tech/integration.lssm-os-provider-docker/runtime-node` — subpath `./runtime-node`
  - `unconditional`: `./src/runtime-node.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/src/runtime-node.ts); verified source file.

- `@lssm-tech/integration.lssm-os-provider-docker/testing` — subpath `./testing`
  - `unconditional`: `./src/testing.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-docker/src/testing.ts); verified source file.

## Package publication metadata

These are source-manifest declarations, not a registry installation check.

```json
{
  "types": "./dist/index.d.ts",
  "files": [
    "dist",
    "!dist/**/*.test.*",
    "README.md"
  ],
  "publishExports": {
    ".": {
      "types": "./dist/index.d.ts",
      "bun": "./dist/index.js",
      "node": "./dist/node/index.js",
      "default": "./dist/index.js"
    },
    "./conformance": {
      "types": "./dist/conformance.d.ts",
      "bun": "./dist/conformance.js",
      "node": "./dist/node/conformance.js",
      "default": "./dist/conformance.js"
    },
    "./runtime-node": {
      "types": "./dist/runtime-node.d.ts",
      "bun": "./dist/runtime-node.js",
      "node": "./dist/node/runtime-node.js",
      "default": "./dist/runtime-node.js"
    },
    "./testing": {
      "types": "./dist/testing.d.ts",
      "bun": "./dist/testing.js",
      "node": "./dist/node/testing.js",
      "default": "./dist/testing.js"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/lib.lssm-os-provider-conformance](https://lssm.co/docs/packages/lib.lssm-os-provider-conformance/): `workspace:^`
- [@lssm-tech/lib.lssm-os-runtime](https://lssm.co/docs/packages/lib.lssm-os-runtime/): `workspace:^`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/tool.bun](https://lssm.co/docs/packages/tool.bun/): `workspace:*`
- [@lssm-tech/tool.typescript](https://lssm.co/docs/packages/tool.typescript/): `workspace:*`
- `typescript`: `catalog:`

### Peer dependency metadata

```json
{}
```

### Bundled dependencies

```json
null
```

## Package scripts

Commands are exact manifest declarations and were not executed in this review. Script metadata status: complete pinned manifest.

```json
{
  "build": "bun run build:bundle && bun run build:types",
  "build:bundle": "bun scripts/build-public-bundles.ts",
  "build:types": "contractspec-bun-build types",
  "clean": "rimraf dist .turbo",
  "lint": "bun run lint:fix",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "test": "bun test",
  "test:pack": "bun run build && bun scripts/test-packed-exports.ts",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

- [Integration Lssm Os Provider Docker documentation](https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-provider-docker) — declared link; destination not verified.

```json
{
  "url": "https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-provider-docker",
  "kind": "readme"
}
```

## Existing agent-guide projection

```json
{
  "path": "packages/apps/web-landing/public/llms-packages/integration.lssm-os-provider-docker.txt",
  "route": "/llms/integration.lssm-os-provider-docker",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.lssm-os-provider-docker.txt",
  "blobSha": "195f238fc49ff8406567b80d075d9ab0e3d158e5",
  "sourcePin": "bcc79fcc27c4d801c2119bef81ddcce7b4e86498",
  "bodyEqualsReadme": true,
  "aggregateSourcePath": "packages/apps/web-landing/public/llms-full.txt",
  "aggregateBlobSha": "691b1d33efee24c440598b9106c81432f56aafaf"
}
```