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

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

Authoritative GitHub adapter for the LSSM OS `ProviderExecutionPort`. It owns
only `provider_api` resources whose owner reference is
`lssm-os-provider-github`.

Callers inject a typed `GitHubControlDriver`. The driver may wrap the existing
GitHub provider package, an Octokit boundary, or a recorded fake, but this
package never resolves credentials or performs live network access itself.

```ts
const provider = new GitHubProviderExecutionAdapter({
  driver,
  executions: durableAtomicExecutionStore,
  observations: trustedObservationVerifier,
  receipts: createOnceEd25519ReceiptAuthority,
  webhookSignatures,
  webhookReplay: durableDeliveryStore,
  clock,
  ids,
});

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


The v0 surface discovers/imports repository, environment, workflow,
protection, OIDC, GitHub App, release, and check state. Governed mutations are
restricted to the exported operation allowlist and include repository,
environment, protection, workflow, release, check, and pull-request automation.
Before any provider effect, every execution is durably reserved and its effect
attempt is persisted. The store atomically reserves scoped idempotency,
compare-and-swaps resource fences, preserves indeterminate outcomes, and
completes the receipt plus its externally signed trust record. Successful
completion is read back and independently verified. This supports restart and
multi-instance safety without process-local coordination.

The adapter owns deadlines and abort signals. Discovery follows provider
cursors until a terminal page, bounds pages and records, and rejects snapshots
missing explicit completion evidence for any declared v0 family, including
families with zero resources. Webhooks pass an injected signature verifier
and durable delivery replay store; driver booleans are never trusted.

Only canonical opaque credential references cross the boundary. Compensation
loads the exact signed successful forward execution and derives rollback from
that record; caller-supplied rollback substitutions are ignored. Compensation
and decommission require exact trusted pre- and post-observations. Unknown,
partial, timeout, and unverifiable cleanup outcomes remain explicit or durable
indeterminate. Actual or estimated usage requires quantity, unit, currency,
source, and period. Unavailable usage requires a reason, limitation, and
evidence reference.

The `./conformance` export supplies the offline verifier-owned conformance 0.3
target. It passes all ten required cases with one mutating apply and read-only
observations for fencing and replay. The `./testing` export contains sanitized
fake driver, state, receipt-authority, and fixture implementations. The actual
npm tarball is installed into a clean consumer and imports all three public
subpaths under Node and Bun. Offline conformance is not a live GitHub
qualification claim.

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


## Declared capabilities

### Integration Lssm Os Provider Github

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

GitHub provider execution adapter for LSSM OS.

Use cases:

- Adopt github provider execution adapter for lssm os

Constraints:

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

Other capability declarations:

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

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.lssm-os-provider-github",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.lssm-os-provider-github/conformance",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.lssm-os-provider-github/runtime-node",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.lssm-os-provider-github/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.github",
    "from": "@lssm-tech/integration.lssm-os-provider-github",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.github",
    "from": "@lssm-tech/integration.lssm-os-provider-github/conformance",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.github",
    "from": "@lssm-tech/integration.lssm-os-provider-github/runtime-node",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.lssm.os.provider.github",
    "from": "@lssm-tech/integration.lssm-os-provider-github/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-github` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-github/src/index.ts); verified source file.

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

- `@lssm-tech/integration.lssm-os-provider-github/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-github/src/runtime-node.ts); verified source file.

- `@lssm-tech/integration.lssm-os-provider-github/testing` — subpath `./testing`
  - `unconditional`: `./src/testing.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/lssm-os-provider-github/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.*",
    "!dist/**/*.tsbuildinfo",
    "README.md",
    "evidence"
  ],
  "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 Github documentation](https://www.npmjs.com/package/%40lssm-tech%2Fintegration.lssm-os-provider-github) — declared link; destination not verified.

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

## Existing agent-guide projection

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