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

Scoped Cloud Run transport for governed LSSM OS hosting lifecycle composition.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `0.2.4`
- Package path: `packages/integrations/lssm-os-provider-gcp`
- Manifest path: `packages/integrations/lssm-os-provider-gcp/package.json`
- Manifest Git blob: `bf4f1de3b62d26c78d401e7d1827cc7931c992d1`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/integration.lssm-os-provider-gcp](https://lssm.co/docs/packages/integration.lssm-os-provider-gcp/)
- 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-gcp)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-gcp/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-gcp/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.lssm-os-provider-gcp.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-gcp/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-gcp/README.md",
  "blobSha": "a168630ac9f01a23c9f597d6206463ac494c1834",
  "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.

# GCP hosting transport for LSSM OS

`CloudRunClient` implements scoped Cloud Run v2 service discovery, creation,
inspection, guarded update/deletion and asynchronous operation readback. It uses
native fetch and an injected token provider, with no mandatory cloud SDK or
Kubernetes component.

## Boundary and ownership

This is a server transport for composition behind the existing Runtime Node
`ProviderLifecyclePortV1`. It does not issue execution authority, journal effects,
reserve budgets, or introduce another agent/task store. The execution host must
load current Connect authority, record the effect intent before mutation, persist
returned operation handles and reconcile unknown outcomes before another effect.
A returned operation handle means accepted, not deployed or deleted.

The initial transport targets single-container, request-driven services with one
CPU and 256/512 MiB memory. Scope fixes the project, region, service account and
maximum scaling ceiling. Plans require image digests and a parent plan digest; the host must bind that
digest to the authorized plan, since syntax validation is not attestation verification.
New services scale to zero with IAM invocation checks enabled. The client does
not grant `allUsers` or change IAM policies; enabling IAM checks alone does not
remove preexisting IAM grants on adopted services.

Updates require a current resource UID/etag and an explicitly adopted target.
They preserve existing environment/secret references, probes, protocol, warm
capacity, request timeout and unrelated network configuration. Changes to service
identity, port, GPU/multi-container/always-allocated-CPU topology require a
separate reviewed migration. An update never creates a missing service.

Deletion checks UID/etag again and sends an etag precondition. A same-named
replacement cannot be silently deleted. The host must verify operation completion
and resource absence before marking cleanup complete.

## Usage

Import `CloudRunClient` from
`@lssm-tech/integration.lssm-os-provider-gcp/cloud-run`.

```ts
const client = new CloudRunClient({
  scope: {
    projectId: 'example-project',
    region: 'europe-west1',
    serviceAccount: 'example-worker@example-project.iam.gserviceaccount.com',
    maximumInstances: 1,
  },
  accessToken: (signal) => credentialProvider.getAccessToken(signal),
});
const services = await client.listServices();
```


Provide a trusted token source from the host connection service. Do not pass
credentials in plans, observations, browser UI or logs. Calls stay on Google's
fixed API origin, refuse redirects, bound token acquisition and response reads,
and never automatically retry mutations. `CloudRunRequestError.indeterminate`
distinguishes an uncertain external effect from an admission/authentication failure
before dispatch. Caller abort signals bound composed operations.

Discovery fails on unreachable regions, repeated pagination tokens or conflicting
resource identities instead of returning a partial inventory. Observations omit
container environment values and provider error messages. Readiness requires a
successful terminal condition and matching observed generation/revision.

## Qualification status

Implementation and local transport regression tests are available. Live Cloud Run
qualification requires an active, separately budgeted test environment. No Cloud Run workload, GKE, VM, jobs, full cloud
lifecycle or production Runtime Node authority qualification is claimed here.

Run `bun test`, `bun run typecheck`, `bun run build`, and `bun run test:pack`.
The package test installs its actual tarball without network access and imports
both public subpaths using Node and Bun. That does not prove npm publication.


## Declared capabilities

### Scoped Cloud Run service transport

Capability ID: `gcp.cloud-run.transport`

Discover, create, inspect, update and delete Cloud Run services with pinned artifacts, explicit operation handles and guarded resource versions. Runtime Node authorization and hosting qualification remain separate.

Use cases:

- Implement a GCP Cloud Run hosting driver

Constraints:

```json
{
  "platforms": [
    "server"
  ],
  "runtimes": [
    "node",
    "bun"
  ],
  "avoidWhen": [
    "GKE, VM, job, secret-management or full GCP lifecycle qualification is required."
  ],
  "requires": [
    "An authorized token provider and operation journal in the execution host."
  ]
}
```

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "GCP Cloud Run",
    "managed containers",
    "Cloud Run service lifecycle"
  ]
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.lssm-os-provider-gcp/cloud-run",
    "symbols": [
      "CloudRunClient"
    ]
  }
]
```

## Catalogue metadata

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

## 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": "gcp.cloud-run.transport",
    "from": "@lssm-tech/integration.lssm-os-provider-gcp/cloud-run",
    "symbols": [
      "CloudRunClient"
    ]
  }
]
```

## 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-gcp` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-gcp/src/index.ts); verified source file.

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

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

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

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

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

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

- `@lssm-tech/integration.lssm-os-provider-gcp/validation` — subpath `./validation`
  - `unconditional`: `./src/validation.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-gcp/src/validation.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",
      "browser": "./dist/browser/index.js",
      "bun": "./dist/index.js",
      "node": "./dist/node/index.js",
      "default": "./dist/index.js"
    },
    "./cloud-run": {
      "types": "./dist/cloud-run.d.ts",
      "browser": "./dist/browser/cloud-run.js",
      "bun": "./dist/cloud-run.js",
      "node": "./dist/node/cloud-run.js",
      "default": "./dist/cloud-run.js"
    },
    "./http": {
      "types": "./dist/http.d.ts",
      "browser": "./dist/browser/http.js",
      "bun": "./dist/http.js",
      "node": "./dist/node/http.js",
      "default": "./dist/http.js"
    },
    "./observation": {
      "types": "./dist/observation.d.ts",
      "browser": "./dist/browser/observation.js",
      "bun": "./dist/observation.js",
      "node": "./dist/node/observation.js",
      "default": "./dist/observation.js"
    },
    "./payload": {
      "types": "./dist/payload.d.ts",
      "browser": "./dist/browser/payload.js",
      "bun": "./dist/payload.js",
      "node": "./dist/node/payload.js",
      "default": "./dist/payload.js"
    },
    "./types": {
      "types": "./dist/types.d.ts",
      "browser": "./dist/browser/types.js",
      "bun": "./dist/types.js",
      "node": "./dist/node/types.js",
      "default": "./dist/types.js"
    },
    "./update": {
      "types": "./dist/update.d.ts",
      "browser": "./dist/browser/update.js",
      "bun": "./dist/update.js",
      "node": "./dist/node/update.js",
      "default": "./dist/update.js"
    },
    "./validation": {
      "types": "./dist/validation.d.ts",
      "browser": "./dist/browser/validation.js",
      "bun": "./dist/validation.js",
      "node": "./dist/node/validation.js",
      "default": "./dist/validation.js"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

No declarations in the inspected manifest.

### 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:*`
- `@types/bun`: `catalog:types`
- `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": "contractspec-bun-build build",
  "build:bundle": "contractspec-bun-build transpile",
  "build:types": "contractspec-bun-build types",
  "test": "bun test",
  "typecheck": "tsgo --noEmit",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "test:pack": "bun scripts/test-packed-exports.ts",
  "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose"
}
```

## Declared documentation links

- [Cloud Run transport](https://github.com/lssm-tech/contractspec/tree/tboutron/adaptive-delivery-platform/packages/integrations/lssm-os-provider-gcp) — declared link; destination not verified.

```json
{
  "url": "https://github.com/lssm-tech/contractspec/tree/tboutron/adaptive-delivery-platform/packages/integrations/lssm-os-provider-gcp",
  "kind": "readme"
}
```

## Existing agent-guide projection

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