# @lssm-tech/integration.opa-calendar-bridge

Bridge adapting the real CalendarProvider (e.g. GoogleCalendarProvider from integration.provider-calendar) to the organization-planning module's CalendarExecutionAdapterPort. Port → provider; no new Google SDK code.

## Source and release context

- Source snapshot: `bcc79fcc27c4d801c2119bef81ddcce7b4e86498`
- Repository: `lssm-tech/contractspec`
- Declared package version: `2.0.5`
- Package path: `packages/integrations/opa-calendar-bridge`
- Manifest path: `packages/integrations/opa-calendar-bridge/package.json`
- Manifest Git blob: `da2078ee46ae2916ea874687a720bde55ff8c479`
- Manifest origin: pinned GitHub manifest fetch
- Manual: [@lssm-tech/integration.opa-calendar-bridge](https://lssm.co/docs/packages/integration.opa-calendar-bridge/)
- 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/opa-calendar-bridge)
- [Manifest source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/package.json)
- [Readme source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/README.md)
- [Guide source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/integration.opa-calendar-bridge.txt)

## Package metadata

```json
{
  "layer": "integrations",
  "physicalArea": null,
  "primaryArea": "company-and-work",
  "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: [Company, work and service operations](https://lssm.co/docs/areas/company-and-work/)

## Package guide

```json
{
  "status": "available",
  "sourcePath": "packages/integrations/opa-calendar-bridge/README.md",
  "sourceUrl": "https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/README.md",
  "blobSha": "fdd62c48ffb011de3f5cd019176fad89488e07c9",
  "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.opa-calendar-bridge

Bridge that binds the **organization-planning** module's
`CalendarExecutionAdapterPort` (`kind: 'calendar_execution'`) to a real
`CalendarProvider` — without reimplementing any provider SDK. This is the
port→provider seam: the module declares the typed port; this package adapts it to
a concrete provider (e.g. the `GoogleCalendarProvider` owned by
`@lssm-tech/integration.provider-calendar`).

## Why it exists

OPA proposes bookings and agendas as fail-closed drafts. To actually *execute* a
confirmed booking (write a calendar event), the runtime needs a bound
`calendar_execution` adapter. This bridge provides one over an existing provider,
keeping Google and Microsoft Graph SDK/transport code out of the runtime and
the module.

## Usage

```ts
import { createOpaCalendarExecutionBridge } from '@lssm-tech/integration.opa-calendar-bridge';
import { GoogleCalendarProvider } from '@lssm-tech/integration.provider-calendar/impls/google-calendar';

// Any CalendarProvider works (Google, a fake, a future provider).
const calendar = createOpaCalendarExecutionBridge(
  new GoogleCalendarProvider({ auth })
);

// Or the convenience factory (./google):
import { createGoogleOpaCalendarExecutionBridge } from '@lssm-tech/integration.opa-calendar-bridge/google';
const calendar = createGoogleOpaCalendarExecutionBridge({ auth });

// Outlook/Exchange via a host-authenticated Microsoft Graph client:
import { createMicrosoftGraphOpaCalendarExecutionBridge } from '@lssm-tech/integration.opa-calendar-bridge/microsoft-graph';
const outlookCalendar = createMicrosoftGraphOpaCalendarExecutionBridge({ client });

// Bind into the OPA runtime so booking.confirm can write on the authorized path:
buildOpaOps({ rbac, calendar });
```


## Fail-closed posture

The bridge only forwards a method call when invoked. The OPA runtime invokes
`createEvent` **exclusively** on the authorized + approval-satisfied confirm path
(`isOpaExecutionAllowed`); every other path performs no external write.

## Exports

| Subpath     | Export                                                    |
| ----------- | --------------------------------------------------------- |
| `.`         | generic bridge plus Google and Microsoft convenience factories |
| `./bridge`  | provider-agnostic bridge (no Google SDK)                  |
| `./google`  | Google convenience factory                                |
| `./google-protected-booking` | `resolveGoogleProtectedBooking` and `googleBookingResolverQuery`: protected OPA booking intent → `GoogleBookingEventInput` (decrypt via the host protector, attendee validation, Meet only for a live `google_meet` conference; a booking without its own summary is titled from the OPA catalog key `calendar.booking.defaultSummary` in the optional `locale`, `en` by default) |
| `./google-oauth-state` | `PostgresGoogleOAuthStateStore`, the durable one-use `GoogleOAuthStatePort` adapter over `opa_outbox` |
| `./microsoft-graph` | Microsoft Outlook/Graph convenience factory          |

`createGoogleBookingProviderBridge` is the booking-specific seam for the G015
known-ID saga port. A host-provided resolver supplies protected booking effect
details; the bridge forwards only provider-neutral create/get/cancel outcomes.
For an original create, the provider retains its deterministic tenant/booking ID
derivation. For a reschedule, the resolver must authorize the exact persisted
replacement ID and active replacement interval; the bridge forwards that known
ID unchanged for create and ambiguity recovery. Google SDK calls remain in
`integration.provider-calendar`.

The bridge also forwards normalized conference readiness without interpreting
provider payloads. A Meet booking is not terminal until the provider reports a
verified ready link; pending, ambiguous, or failed conference creation remains
recoverable through exact known-ID lookup.

`createOpaMeetingOccurrenceFingerprint` projects calendar occurrences into
PII-free recorder-matching evidence. Its event digest uses the provider event id
shared by Google/Outlook and recorder metadata, while participant identities are
normalized, sorted, and digested. Calendar ids and participant addresses never
cross the OPA binding boundary.

`PostgresGoogleOAuthStateStore` issues HMAC-signed OAuth state, persists only
its SHA-256 digest plus the account ref and redirect URI in `opa_outbox`
through the runtime `OpaSqlExecutor`, and consumes it exactly once before
expiry. It uses Web Crypto so the bridge stays free of `node:` imports, and
rejects an empty signing key.


## Declared capabilities

### Integration Opa Calendar Bridge

Capability ID: `package.lssm.tech.integration.opa.calendar.bridge`

Bridge adapting the real CalendarProvider (e.g. GoogleCalendarProvider from integration.provider-calendar) to the organization-planning module's CalendarExecutionAdapterPort. Port → provider; no new Google SDK code.

Use cases:

- Adopt bridge adapting the real calendarprovider (e.g. googlecalendarprovider from integration.provider-calendar) to the organization-planning module's calendarexecutionadapterport. port → provider; no new google sdk code

Constraints:

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

Other capability declarations:

```json
{
  "status": "active",
  "aliases": [
    "integration",
    "opa",
    "calendar",
    "bridge"
  ],
  "pythonEquivalents": [],
  "alternatives": [],
  "relationships": [],
  "resolutionPriority": 50
}
```

Capability imports:

```json
[
  {
    "from": "@lssm-tech/integration.opa-calendar-bridge",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.opa-calendar-bridge/booking",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.opa-calendar-bridge/bridge",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.opa-calendar-bridge/google",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.opa-calendar-bridge/meeting-occurrence",
    "symbols": []
  },
  {
    "from": "@lssm-tech/integration.opa-calendar-bridge/microsoft-graph",
    "symbols": []
  }
]
```

## Catalogue metadata

```json
{
  "family": "integrations",
  "kind": "integration",
  "status": "active",
  "adoptionMode": "adoptable",
  "stability": "experimental",
  "platforms": [
    "server"
  ],
  "runtimes": [
    "node"
  ],
  "entrypoints": [
    ".",
    "./booking",
    "./bridge",
    "./google",
    "./google-oauth-state",
    "./google-protected-booking",
    "./meeting-occurrence",
    "./microsoft-graph"
  ],
  "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.opa.calendar.bridge",
    "from": "@lssm-tech/integration.opa-calendar-bridge",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.opa.calendar.bridge",
    "from": "@lssm-tech/integration.opa-calendar-bridge/booking",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.opa.calendar.bridge",
    "from": "@lssm-tech/integration.opa-calendar-bridge/bridge",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.opa.calendar.bridge",
    "from": "@lssm-tech/integration.opa-calendar-bridge/google",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.opa.calendar.bridge",
    "from": "@lssm-tech/integration.opa-calendar-bridge/meeting-occurrence",
    "symbols": []
  },
  {
    "capabilityId": "package.lssm.tech.integration.opa.calendar.bridge",
    "from": "@lssm-tech/integration.opa-calendar-bridge/microsoft-graph",
    "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.opa-calendar-bridge` — subpath `.`
  - `unconditional`: `./src/index.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/src/index.ts); verified source file.

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

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

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

- `@lssm-tech/integration.opa-calendar-bridge/google-oauth-state` — subpath `./google-oauth-state`
  - `unconditional`: `./src/google-oauth-state.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/src/google-oauth-state.ts); verified source file.

- `@lssm-tech/integration.opa-calendar-bridge/google-protected-booking` — subpath `./google-protected-booking`
  - `unconditional`: `./src/google-protected-booking.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/src/google-protected-booking.ts); verified source file.

- `@lssm-tech/integration.opa-calendar-bridge/meeting-occurrence` — subpath `./meeting-occurrence`
  - `unconditional`: `./src/meeting-occurrence.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/src/meeting-occurrence.ts); verified source file.

- `@lssm-tech/integration.opa-calendar-bridge/microsoft-graph` — subpath `./microsoft-graph`
  - `unconditional`: `./src/microsoft-graph.ts` — [pinned source](https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/integrations/opa-calendar-bridge/src/microsoft-graph.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",
    "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"
    },
    "./booking": {
      "types": "./dist/booking.d.ts",
      "browser": "./dist/browser/booking.js",
      "bun": "./dist/booking.js",
      "node": "./dist/node/booking.js",
      "default": "./dist/booking.js"
    },
    "./bridge": {
      "types": "./dist/bridge.d.ts",
      "browser": "./dist/browser/bridge.js",
      "bun": "./dist/bridge.js",
      "node": "./dist/node/bridge.js",
      "default": "./dist/bridge.js"
    },
    "./google": {
      "types": "./dist/google.d.ts",
      "browser": "./dist/browser/google.js",
      "bun": "./dist/google.js",
      "node": "./dist/node/google.js",
      "default": "./dist/google.js"
    },
    "./google-oauth-state": {
      "types": "./dist/google-oauth-state.d.ts",
      "browser": "./dist/browser/google-oauth-state.js",
      "bun": "./dist/google-oauth-state.js",
      "node": "./dist/node/google-oauth-state.js",
      "default": "./dist/google-oauth-state.js"
    },
    "./google-protected-booking": {
      "types": "./dist/google-protected-booking.d.ts",
      "browser": "./dist/browser/google-protected-booking.js",
      "bun": "./dist/google-protected-booking.js",
      "node": "./dist/node/google-protected-booking.js",
      "default": "./dist/google-protected-booking.js"
    },
    "./meeting-occurrence": {
      "types": "./dist/meeting-occurrence.d.ts",
      "browser": "./dist/browser/meeting-occurrence.js",
      "bun": "./dist/meeting-occurrence.js",
      "node": "./dist/node/meeting-occurrence.js",
      "default": "./dist/meeting-occurrence.js"
    },
    "./microsoft-graph": {
      "types": "./dist/microsoft-graph.d.ts",
      "browser": "./dist/browser/microsoft-graph.js",
      "bun": "./dist/microsoft-graph.js",
      "node": "./dist/node/microsoft-graph.js",
      "default": "./dist/microsoft-graph.js"
    }
  }
}
```

## Dependencies

Metadata status: complete pinned manifest.

### Runtime dependencies

- [@lssm-tech/integration.provider-calendar](https://lssm.co/docs/packages/integration.provider-calendar/): `workspace:^`
- [@lssm-tech/lib.contracts-integrations](https://lssm.co/docs/packages/lib.contracts-integrations/): `workspace:^`
- [@lssm-tech/lib.organization-planning-runtime](https://lssm.co/docs/packages/lib.organization-planning-runtime/): `workspace:^`
- [@lssm-tech/lib.organization-planning-spec](https://lssm.co/docs/packages/lib.organization-planning-spec/): `workspace:^`

### Peer dependencies

No declarations in the inspected manifest.

### Optional dependencies

No declarations in the inspected manifest.

### Development dependencies

- [@lssm-tech/module.organization-planning](https://lssm.co/docs/packages/module.organization-planning/): `workspace:*`
- [@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`
- `googleapis`: `catalog:integrations`
- `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",
  "dev": "contractspec-bun-build dev",
  "clean": "rimraf dist .turbo",
  "lint:check": "node ../../../scripts/biome.cjs check .",
  "lint:fix": "node ../../../scripts/biome.cjs check --write .",
  "test": "bun test",
  "prebuild": "contractspec-bun-build prebuild",
  "typecheck": "tsgo --noEmit"
}
```

## Declared documentation links

- [Integration Opa Calendar Bridge documentation](https://www.npmjs.com/package/%40lssm-tech%2Fintegration.opa-calendar-bridge) — declared link; destination not verified.

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

## Existing agent-guide projection

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