# Version negotiation

One carrier per transport, and the four transports that have no counterparty to
negotiate with.

Generated from `libs/oshun/workbench-kit/src/negotiation.ts` by
`node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs`. Ledger:
S1.11. Do not edit by hand.

## Summary

- `src/negotiation.ts`

| Entry point                        | Runtime class | Authorized by |
| ---------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/negotiation` | `contract`    | S1.11         |

## Exports

| Symbol                                                      | Kind        | Summary                                                                        |
| ----------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------ |
| [bindVersion](#bindversion)                                 | function    | Derive the binding from a negotiated version.                                  |
| [CapabilitySupport](#capabilitysupport)                     | interface   | —                                                                              |
| [CARRIER_MECHANISMS](#carrier_mechanisms)                   | enumeration | —                                                                              |
| [CarrierMechanism](#carriermechanism)                       | type        | —                                                                              |
| [discoveryDocument](#discoverydocument)                     | function    | Build the discovery document, for an AUTHENTICATED caller only.                |
| [DiscoveryDocument](#discoverydocument)                     | interface   | —                                                                              |
| [DiscoveryEntry](#discoveryentry)                           | interface   | —                                                                              |
| [negotiate](#negotiate)                                     | function    | Choose a version, or refuse with a code that says which way the mismatch went. |
| [NEGOTIATION_REASONS](#negotiation_reasons)                 | enumeration | —                                                                              |
| [NEGOTIATION_VIOLATION_KINDS](#negotiation_violation_kinds) | enumeration | —                                                                              |
| [NegotiationOutcome](#negotiationoutcome)                   | type        | —                                                                              |
| [NegotiationReason](#negotiationreason)                     | type        | —                                                                              |
| [NegotiationRequest](#negotiationrequest)                   | interface   | —                                                                              |
| [NegotiationViolation](#negotiationviolation)               | interface   | —                                                                              |
| [NegotiationViolationKind](#negotiationviolationkind)       | type        | —                                                                              |
| [REFUSAL_CODES](#refusal_codes)                             | enumeration | —                                                                              |
| [RefusalCode](#refusalcode)                                 | type        | —                                                                              |
| [SYNCHRONOUS_TRANSPORTS](#synchronous_transports)           | enumeration | The transports with a live counterparty at the moment the version is chosen.   |
| [Transport](#transport)                                     | type        | —                                                                              |
| [TRANSPORTS](#transports)                                   | enumeration | —                                                                              |
| [validateBinding](#validatebinding)                         | function    | S1.11.f — the negotiated version must reach every downstream key.              |
| [validateCarriers](#validatecarriers)                       | function    | —                                                                              |
| [validateDiscovery](#validatediscovery)                     | function    | —                                                                              |
| [validateSupport](#validatesupport)                         | function    | —                                                                              |
| [VERSION_CARRIERS](#version_carriers)                       | constant    | The carriers, one per transport.                                               |
| [VersionBinding](#versionbinding)                           | interface   | —                                                                              |
| [VersionCarrier](#versioncarrier)                           | interface   | —                                                                              |
| [VersionDeprecation](#versiondeprecation)                   | interface   | —                                                                              |

## Shapes

#### bindVersion

Derive the binding from a negotiated version.

```ts
bindVersion(capability: CapabilityId, version: number): VersionBinding
```

#### CapabilitySupport

| Field            | Type                                       | Required | Notes                                                                   |
| ---------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------- |
| `capability`     | [CapabilityId](./identity.md#capabilityid) | required | —                                                                       |
| `supported`      | `readonly number[]`                        | required | Exact versions this deployment implements, ascending. Never a range.    |
| `defaultVersion` | `number`                                   | required | What a client that declared nothing gets, when the carrier allows that. |
| `preference`     | `readonly number[]`                        | required | The server's own preference order, most preferred first.                |
| `enabled`        | `boolean`                                  | required | False when the deployment has switched the capability off entirely.     |

#### CARRIER_MECHANISMS

Values: `media-type-parameter`, `header`, `envelope-field`, `manifest-field`,
`handshake`, `compiled-constant`

#### CarrierMechanism

```ts
(typeof CARRIER_MECHANISMS)[number];
```

#### discoveryDocument

Build the discovery document, for an AUTHENTICATED caller only.

```ts
discoveryDocument(entries: readonly DiscoveryEntry[], caller: { readonly authenticated: boolean; readonly subject: string }): ParseResult<DiscoveryDocument>
```

#### DiscoveryDocument

| Field          | Type                                                            | Required | Notes |
| -------------- | --------------------------------------------------------------- | -------- | ----- |
| `generatedFor` | `string`                                                        | required | —     |
| `entries`      | `readonly DiscoveryEntry[]` — [DiscoveryEntry](#discoveryentry) | required | —     |

#### DiscoveryEntry

| Field            | Type                                                                        | Required | Notes |
| ---------------- | --------------------------------------------------------------------------- | -------- | ----- |
| `capability`     | [CapabilityId](./identity.md#capabilityid)                                  | required | —     |
| `owner`          | `string`                                                                    | required | —     |
| `lifecycle`      | [Lifecycle](./capability.md#lifecycle)                                      | required | —     |
| `supported`      | `readonly number[]`                                                         | required | —     |
| `defaultVersion` | `number`                                                                    | required | —     |
| `deprecations`   | `readonly VersionDeprecation[]` — [VersionDeprecation](#versiondeprecation) | required | —     |
| `docsUrl`        | `string`                                                                    | required | —     |
| `enabled`        | `boolean`                                                                   | required | —     |

#### negotiate

Choose a version, or refuse with a code that says which way the mismatch went.

```ts
negotiate(request: NegotiationRequest, support: CapabilitySupport): NegotiationOutcome
```

#### NEGOTIATION_REASONS

Values: `exact-single-offer`, `server-preference`, `highest-common`,
`server-default`

#### NEGOTIATION_VIOLATION_KINDS

Values: `duplicate-carrier-for-transport`, `transport-without-carrier`,
`asynchronous-transport-claims-negotiation`, `carrier-without-example`,
`empty-supported-set`, `unsorted-supported-set`, `duplicate-supported-version`,
`default-version-not-supported`, `preference-outside-supported`,
`deprecated-version-without-replacement`, `sunset-version-still-supported`,
`discovery-entry-without-owner`, `discovery-entry-without-docs`,
`discovery-entry-hides-a-served-version`, `cache-key-without-version`,
`idempotency-key-without-version`, `binding-without-audit-field`,
`binding-without-telemetry-attribute`, `binding-version-not-negotiated`

#### NegotiationOutcome

```ts
| { readonly outcome: 'negotiated'; readonly version: number; readonly reason: NegotiationReason; readonly departedFrom: number | null; readonly direction: 'upgrade' | 'downgrade' | null; }
| { readonly outcome: 'refused'; readonly code: RefusalCode; readonly supported: readonly number[]; readonly detail: string; }
| { readonly outcome: 'unavailable'; readonly capability: CapabilityId; readonly reason: string }
```

#### NegotiationReason

```ts
(typeof NEGOTIATION_REASONS)[number];
```

#### NegotiationRequest

| Field               | Type                    | Required | Notes                                                                                                                                                                          |
| ------------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `offers`            | `readonly number[]`     | required | The versions the client offered, in ITS preference order. An empty array means the client declared nothing, which is a different case from offering a version nobody supports. |
| `transport`         | [Transport](#transport) | required | —                                                                                                                                                                              |
| `unparseableOffers` | `readonly string[]`     | optional | Offered values that were carried but are not versions at all.                                                                                                                  |

#### NegotiationViolation

| Field     | Type                                                  | Required | Notes |
| --------- | ----------------------------------------------------- | -------- | ----- |
| `kind`    | [NegotiationViolationKind](#negotiationviolationkind) | required | —     |
| `subject` | `string`                                              | required | —     |
| `detail`  | `string`                                              | required | —     |

#### NegotiationViolationKind

```ts
(typeof NEGOTIATION_VIOLATION_KINDS)[number];
```

#### REFUSAL_CODES

Values: `validation.version_missing`, `validation.version_too_old`,
`validation.version_too_new`, `validation.version_unsupported`,
`validation.version_unknown`

#### RefusalCode

```ts
(typeof REFUSAL_CODES)[number];
```

#### SYNCHRONOUS_TRANSPORTS

The transports with a live counterparty at the moment the version is chosen.

Values: `http`, `bridge`

#### Transport

```ts
(typeof TRANSPORTS)[number];
```

#### TRANSPORTS

Values: `http`, `event`, `job`, `bundle`, `bridge`, `generated-client`

#### validateBinding

S1.11.f — the negotiated version must reach every downstream key.

```ts
validateBinding(binding: VersionBinding, negotiatedVersion: number): readonly NegotiationViolation[]
```

#### validateCarriers

```ts
validateCarriers(carriers: readonly VersionCarrier[]): readonly NegotiationViolation[]
```

#### validateDiscovery

```ts
validateDiscovery(entries: readonly DiscoveryEntry[], now: Instant): readonly NegotiationViolation[]
```

#### validateSupport

```ts
validateSupport(support: CapabilitySupport): readonly NegotiationViolation[]
```

#### VERSION_CARRIERS

The carriers, one per transport.

#### VersionBinding

| Field                  | Type     | Required | Notes |
| ---------------------- | -------- | -------- | ----- |
| `version`              | `number` | required | —     |
| `validatorId`          | `string` | required | —     |
| `serializerId`         | `string` | required | —     |
| `cacheKeyPrefix`       | `string` | required | —     |
| `idempotencyKeyPrefix` | `string` | required | —     |
| `auditField`           | `string` | required | —     |
| `telemetryAttribute`   | `string` | required | —     |

#### VersionCarrier

| Field        | Type                                  | Required | Notes                                                           |
| ------------ | ------------------------------------- | -------- | --------------------------------------------------------------- |
| `transport`  | [Transport](#transport)               | required | —                                                               |
| `mechanism`  | [CarrierMechanism](#carriermechanism) | required | —                                                               |
| `name`       | `string`                              | required | The header, field or parameter name. One name, one place.       |
| `required`   | `boolean`                             | required | Whether a message with no version at all is refused.            |
| `negotiable` | `boolean`                             | required | Whether the receiving side may answer with a different version. |
| `example`    | `string`                              | required | —                                                               |

#### VersionDeprecation

| Field          | Type                             | Required | Notes                                                            |
| -------------- | -------------------------------- | -------- | ---------------------------------------------------------------- |
| `version`      | `number`                         | required | —                                                                |
| `deprecatedIn` | `number`                         | required | —                                                                |
| `sunsetOn`     | [Instant](./identity.md#instant) | required | The date after which the version stops being served. Never null. |
| `replacedBy`   | `number`                         | required | —                                                                |

## Valid examples

##### binding/a-derived-binding-carries-the-version-everywhere

the positive case, and the one the propagation test builds on

```json
{
  "auditField": "contractVersion",
  "cacheKeyPrefix": "capability-demo-workbench:v2:",
  "idempotencyKeyPrefix": "capability-demo-workbench:v2:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}
```

## Invalid examples

##### binding/a-cache-key-shared-across-versions

it serves a v1 body to a v2 client, and it looks like a working system until
somebody upgrades

Must produce: `cache-key-without-version`

```json
{
  "auditField": "contractVersion",
  "cacheKeyPrefix": "capability-demo-workbench:",
  "idempotencyKeyPrefix": "capability-demo-workbench:v2:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}
```

##### binding/an-audit-row-that-does-not-name-the-contract

an audit row that does not say which contract was in force cannot be replayed

Must produce: `binding-without-audit-field`

```json
{
  "auditField": "",
  "cacheKeyPrefix": "capability-demo-workbench:v2:",
  "idempotencyKeyPrefix": "capability-demo-workbench:v2:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}
```

##### binding/an-idempotency-key-shared-across-versions

a retried command at a new version deduped against the old one returns the OLD
shape with a 200, which is the failure a client is least likely to detect

Must produce: `idempotency-key-without-version`

```json
{
  "auditField": "contractVersion",
  "cacheKeyPrefix": "capability-demo-workbench:v2:",
  "idempotencyKeyPrefix": "capability-demo-workbench:",
  "serializerId": "capability-demo-workbench@v2",
  "telemetryAttribute": "oshun.contract_version",
  "validatorId": "capability-demo-workbench@v2",
  "version": 2
}
```

3 of 5 refused case(s) shown. The full corpus is committed at
`evidence/v1-workbenches/workbench-kit-negotiation-fixtures.json` and is what
the gate runs.

## Authorization and scope

Not applicable: nothing on this page carries an actor, a grant, a scope or a
tenant, so authorization is decided entirely by the caller.

## Idempotency and concurrency

| Symbol                                | Type     | Notes |
| ------------------------------------- | -------- | ----- |
| `VersionBinding.idempotencyKeyPrefix` | `string` | —     |

## Pagination

Not applicable: nothing on this page returns a collection a caller reads in
pages.

## State and failure

| Symbol                        | Type          | Notes |
| ----------------------------- | ------------- | ----- |
| `NEGOTIATION_VIOLATION_KINDS` | `enumeration` | —     |
| `NegotiationOutcome`          | `type`        | —     |
| `NegotiationViolationKind`    | `type`        | —     |
| `REFUSAL_CODES`               | `enumeration` | —     |
| `RefusalCode`                 | `type`        | —     |

## Compatibility

| Symbol                             | Type                | Notes                                                                          |
| ---------------------------------- | ------------------- | ------------------------------------------------------------------------------ |
| `bindVersion`                      | `function`          | Derive the binding from a negotiated version.                                  |
| `CapabilitySupport.defaultVersion` | `number`            | What a client that declared nothing gets, when the carrier allows that.        |
| `CapabilitySupport.supported`      | `readonly number[]` | Exact versions this deployment implements, ascending. Never a range.           |
| `CARRIER_MECHANISMS`               | `enumeration`       | —                                                                              |
| `CarrierMechanism`                 | `type`              | —                                                                              |
| `DiscoveryEntry.defaultVersion`    | `number`            | —                                                                              |
| `DiscoveryEntry.supported`         | `readonly number[]` | —                                                                              |
| `negotiate`                        | `function`          | Choose a version, or refuse with a code that says which way the mismatch went. |
| `NEGOTIATION_REASONS`              | `enumeration`       | —                                                                              |
| `NEGOTIATION_VIOLATION_KINDS`      | `enumeration`       | —                                                                              |
| `NegotiationOutcome`               | `type`              | —                                                                              |
| `NegotiationReason`                | `type`              | —                                                                              |
| `NegotiationViolationKind`         | `type`              | —                                                                              |
| `validateCarriers`                 | `function`          | —                                                                              |
| `VERSION_CARRIERS`                 | `constant`          | The carriers, one per transport.                                               |
| `VersionBinding.version`           | `number`            | —                                                                              |
| `VersionCarrier.negotiable`        | `boolean`           | Whether the receiving side may answer with a different version.                |
| `VersionDeprecation.version`       | `number`            | —                                                                              |

## Deprecation

| Symbol                            | Type                            | Notes                                                            |
| --------------------------------- | ------------------------------- | ---------------------------------------------------------------- |
| `DiscoveryEntry.deprecations`     | `readonly VersionDeprecation[]` | —                                                                |
| `DiscoveryEntry.lifecycle`        | `Lifecycle`                     | —                                                                |
| `VersionDeprecation.deprecatedIn` | `number`                        | —                                                                |
| `VersionDeprecation.sunsetOn`     | `Instant`                       | The date after which the version stops being served. Never null. |

## Evidence

- `evidence/v1-workbenches/workbench-kit-export-map.json`
- `evidence/v1-workbenches/workbench-kit-negotiation-fixtures.json`
- `libs/oshun/workbench-kit/src/negotiation.ts`
