integration.lssm-os-provider-github

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

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.