# Lifecycle and deprecation

The notice, the out-of-band warning, the tenant-safe usage record, and the
removal decision.

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

## Summary

- `src/deprecation.ts`

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

## Exports

| Symbol                                                        | Kind        | Summary                                                                                                                                                                                                                   |
| ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ALERT_SEVERITIES](#alert_severities)                         | enumeration | —                                                                                                                                                                                                                         |
| [AlertSeverity](#alertseverity)                               | type        | —                                                                                                                                                                                                                         |
| [ATTACHMENT_KINDS](#attachment_kinds)                         | enumeration | —                                                                                                                                                                                                                         |
| [AttachmentKind](#attachmentkind)                             | type        | —                                                                                                                                                                                                                         |
| [callerIndependenceViolation](#callerindependenceviolation)   | function    | —                                                                                                                                                                                                                         |
| [CLOSURE_ITEMS](#closure_items)                               | enumeration | What has to go WITH the surface.                                                                                                                                                                                          |
| [closureChecklist](#closurechecklist)                         | function    | A fresh checklist, with every item open.                                                                                                                                                                                  |
| [ClosureChecklist](#closurechecklist)                         | interface   | —                                                                                                                                                                                                                         |
| [ClosureItem](#closureitem)                                   | interface   | —                                                                                                                                                                                                                         |
| [ClosureItemId](#closureitemid)                               | type        | —                                                                                                                                                                                                                         |
| [Cohort](#cohort)                                             | type        | —                                                                                                                                                                                                                         |
| [COHORT_ANONYMITY_THRESHOLD](#cohort_anonymity_threshold)     | constant    | Fewer distinct tenants than this and a cohort identifies somebody.                                                                                                                                                        |
| [COHORTS](#cohorts)                                           | enumeration | Tenant-safe cohorts: buckets, never identities.                                                                                                                                                                           |
| [CONSUMER_CLASSES](#consumer_classes)                         | enumeration | —                                                                                                                                                                                                                         |
| [ConsumerClass](#consumerclass)                               | type        | —                                                                                                                                                                                                                         |
| [DEPRECATABLE_SURFACES](#deprecatable_surfaces)               | enumeration | The nine surfaces. `event` and `job` are separate rather than the ledger's "event/job", because they deprecate differently: an event has consumers the producer cannot enumerate, and a job has exactly one worker fleet. |
| [DeprecatableSurface](#deprecatablesurface)                   | type        | —                                                                                                                                                                                                                         |
| [DEPRECATION_VIOLATION_KINDS](#deprecation_violation_kinds)   | enumeration | —                                                                                                                                                                                                                         |
| [DeprecationAlert](#deprecationalert)                         | interface   | —                                                                                                                                                                                                                         |
| [deprecationAlerts](#deprecationalerts)                       | function    | Alert on usage that has passed a date somebody committed to.                                                                                                                                                              |
| [DeprecationNotice](#deprecationnotice)                       | interface   | —                                                                                                                                                                                                                         |
| [DeprecationViolation](#deprecationviolation)                 | interface   | —                                                                                                                                                                                                                         |
| [DeprecationViolationKind](#deprecationviolationkind)         | type        | —                                                                                                                                                                                                                         |
| [DeprecationWarning](#deprecationwarning)                     | interface   | —                                                                                                                                                                                                                         |
| [Environment](#environment)                                   | type        | —                                                                                                                                                                                                                         |
| [ENVIRONMENTS](#environments)                                 | enumeration | —                                                                                                                                                                                                                         |
| [MAX_USAGE_WINDOW_HOURS](#max_usage_window_hours)             | constant    | A window longer than this is a counter nobody can alert on.                                                                                                                                                               |
| [removalDecision](#removaldecision)                           | function    | Decide whether a deprecated surface may be removed.                                                                                                                                                                       |
| [RemovalDecision](#removaldecision)                           | type        | —                                                                                                                                                                                                                         |
| [RemovalException](#removalexception)                         | interface   | An approved extension past the sunset. Expires by itself.                                                                                                                                                                 |
| [Replacement](#replacement)                                   | type        | What replaces the deprecated thing.                                                                                                                                                                                       |
| [SURFACE_ATTACHMENTS](#surface_attachments)                   | constant    | Where a deprecation notice can be attached today, per surface.                                                                                                                                                            |
| [SurfaceAttachment](#surfaceattachment)                       | interface   | —                                                                                                                                                                                                                         |
| [UsageRecord](#usagerecord)                                   | interface   | —                                                                                                                                                                                                                         |
| [validateAttachments](#validateattachments)                   | function    | —                                                                                                                                                                                                                         |
| [validateClosure](#validateclosure)                           | function    | —                                                                                                                                                                                                                         |
| [validateNotice](#validatenotice)                             | function    | —                                                                                                                                                                                                                         |
| [validateUsage](#validateusage)                               | function    | —                                                                                                                                                                                                                         |
| [WARNING_PROTOCOLS](#warning_protocols)                       | enumeration | —                                                                                                                                                                                                                         |
| [warningFor](#warningfor)                                     | function    | —                                                                                                                                                                                                                         |
| [WarningProtocol](#warningprotocol)                           | type        | —                                                                                                                                                                                                                         |
| [warningsAreCallerIndependent](#warningsarecallerindependent) | function    | Prove a warning is caller-independent by comparing two of them.                                                                                                                                                           |

## Shapes

#### ALERT_SEVERITIES

Values: `warning`, `critical`

#### AlertSeverity

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

#### ATTACHMENT_KINDS

Values: `descriptor-field`, `version-range`, `sidecar-register`

#### AttachmentKind

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

#### callerIndependenceViolation

```ts
callerIndependenceViolation(first: DeprecationWarning, second: DeprecationWarning, surfaceId: string): readonly DeprecationViolation[]
```

#### CLOSURE_ITEMS

What has to go WITH the surface.

Values: `surface-removed`, `compatibility-adapter-removed`,
`telemetry-counter-removed`, `warning-emitter-removed`, `notice-archived`,
`exception-record-closed`

#### closureChecklist

A fresh checklist, with every item open.

```ts
closureChecklist(notice: DeprecationNotice): ClosureChecklist
```

#### ClosureChecklist

| Field       | Type                                                   | Required | Notes |
| ----------- | ------------------------------------------------------ | -------- | ----- |
| `surfaceId` | `string`                                               | required | —     |
| `items`     | `readonly ClosureItem[]` — [ClosureItem](#closureitem) | required | —     |
| `completed` | `boolean`                                              | required | —     |

#### ClosureItem

| Field  | Type                            | Required | Notes |
| ------ | ------------------------------- | -------- | ----- |
| `id`   | [ClosureItemId](#closureitemid) | required | —     |
| `done` | `boolean`                       | required | —     |

#### ClosureItemId

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

#### Cohort

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

#### COHORT_ANONYMITY_THRESHOLD

Fewer distinct tenants than this and a cohort identifies somebody.

Value: `5`

#### COHORTS

Tenant-safe cohorts: buckets, never identities.

Values: `internal`, `design-partner`, `general-availability`, `below-threshold`

#### CONSUMER_CLASSES

Values: `first-party-web`, `first-party-desktop`, `first-party-worker`,
`third-party-integration`, `unattributed`

#### ConsumerClass

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

#### DEPRECATABLE_SURFACES

The nine surfaces. `event` and `job` are separate rather than the ledger's
"event/job", because they deprecate differently: an event has consumers the
producer cannot enumerate, and a job has exactly one worker fleet.

Values: `capability`, `contract`, `field`, `route`, `event`, `job`,
`package-export`, `bundle-profile`, `plugin-version`

#### DeprecatableSurface

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

#### DEPRECATION_VIOLATION_KINDS

Values: `notice-without-migration-guide`, `warning-key-not-a-key`,
`notice-without-owner`, `supported-through-before-deprecation`,
`sunset-before-supported-through`, `replacement-is-the-surface-itself`,
`no-replacement-without-reason`, `exception-without-approver`,
`exception-expiring-before-sunset`, `exception-already-expired`,
`surface-without-attachment`, `duplicate-surface-attachment`,
`sidecar-attachment-without-register`, `cohort-names-a-tenant`,
`cohort-below-anonymity-threshold`, `usage-window-inverted`,
`usage-window-too-long`, `usage-without-a-surface`,
`closure-completed-with-open-items`, `closure-missing-an-item`,
`warning-varies-by-caller`

#### DeprecationAlert

| Field           | Type                            | Required | Notes |
| --------------- | ------------------------------- | -------- | ----- |
| `surfaceId`     | `string`                        | required | —     |
| `severity`      | [AlertSeverity](#alertseverity) | required | —     |
| `consumerClass` | [ConsumerClass](#consumerclass) | required | —     |
| `count`         | `number`                        | required | —     |
| `detail`        | `string`                        | required | —     |

#### deprecationAlerts

Alert on usage that has passed a date somebody committed to.

```ts
deprecationAlerts(notice: DeprecationNotice, usage: readonly UsageRecord[], now: Instant): readonly DeprecationAlert[]
```

#### DeprecationNotice

| Field               | Type                                                               | Required | Notes                                                                       |
| ------------------- | ------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------- |
| `surface`           | [DeprecatableSurface](#deprecatablesurface)                        | required | —                                                                           |
| `surfaceId`         | `string`                                                           | required | —                                                                           |
| `deprecatedSince`   | [Instant](./identity.md#instant)                                   | required | —                                                                           |
| `replacement`       | [Replacement](#replacement)                                        | required | —                                                                           |
| `migrationGuideUrl` | `string`                                                           | required | Where the migration is written down. A deprecation without one is a demand. |
| `warningKey`        | `string`                                                           | required | An i18n key. The warning text lives with the translations.                  |
| `owner`             | `string`                                                           | required | —                                                                           |
| `supportedThrough`  | [Instant](./identity.md#instant)                                   | required | The last date the surface is SUPPORTED — questions answered, bugs fixed.    |
| `sunsetOn`          | [Instant](./identity.md#instant)                                   | required | The date it stops being served at all. Never before supportedThrough.       |
| `removalVersion`    | `number \| null`                                                   | required | The contract version it disappears in, or null while undecided.             |
| `exception`         | `RemovalException \| null` — [RemovalException](#removalexception) | required | —                                                                           |

#### DeprecationViolation

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

#### DeprecationViolationKind

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

#### DeprecationWarning

| Field      | Type                                | Required | Notes                                                                                                                                                                                                                      |
| ---------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `protocol` | [WarningProtocol](#warningprotocol) | required | —                                                                                                                                                                                                                          |
| `channel`  | `string`                            | required | —                                                                                                                                                                                                                          |
| `fields`   | `Readonly<Record<string, string>>`  | required | Derived from the NOTICE and from nothing about the caller, so two callers receive byte-identical warnings. A warning that named who else was still on the old version would be a migration lever and a disclosure at once. |

#### Environment

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

#### ENVIRONMENTS

Values: `development`, `staging`, `production`

#### MAX_USAGE_WINDOW_HOURS

A window longer than this is a counter nobody can alert on.

Value: `24`

#### removalDecision

Decide whether a deprecated surface may be removed.

```ts
removalDecision(notice: DeprecationNotice, usage: readonly UsageRecord[], now: Instant): RemovalDecision
```

#### RemovalDecision

```ts
| { readonly decision: 'not-due'; readonly daysUntilSunset: number }
| { readonly decision: 'removable' }
| { readonly decision: 'blocked'; readonly consumerClasses: readonly ConsumerClass[]; readonly totalCalls: number; }
| { readonly decision: 'permitted-by-exception'; readonly approvedBy: string; readonly expiresOn: Instant; readonly totalCalls: number; }
```

#### RemovalException

An approved extension past the sunset. Expires by itself.

| Field        | Type                             | Required | Notes |
| ------------ | -------------------------------- | -------- | ----- |
| `approvedBy` | `string`                         | required | —     |
| `reason`     | `string`                         | required | —     |
| `expiresOn`  | [Instant](./identity.md#instant) | required | —     |

#### Replacement

What replaces the deprecated thing.

```ts
| { readonly kind: 'replaced-by'; readonly surfaceId: string }
| { readonly kind: 'no-replacement'; readonly reason: string }
```

#### SURFACE_ATTACHMENTS

Where a deprecation notice can be attached today, per surface.

#### SurfaceAttachment

| Field        | Type                                        | Required | Notes                                                      |
| ------------ | ------------------------------------------- | -------- | ---------------------------------------------------------- |
| `surface`    | [DeprecatableSurface](#deprecatablesurface) | required | —                                                          |
| `attachment` | [AttachmentKind](#attachmentkind)           | required | —                                                          |
| `carrier`    | `string`                                    | required | Where the notice actually lives, in this repository.       |
| `register`   | `string \| null`                            | required | Required when the attachment is a sidecar; null otherwise. |

#### UsageRecord

| Field             | Type                             | Required | Notes |
| ----------------- | -------------------------------- | -------- | ----- |
| `surfaceId`       | `string`                         | required | —     |
| `version`         | `number`                         | required | —     |
| `consumerClass`   | [ConsumerClass](#consumerclass)  | required | —     |
| `environment`     | [Environment](#environment)      | required | —     |
| `cohort`          | [Cohort](#cohort)                | required | —     |
| `distinctTenants` | `number`                         | required | —     |
| `count`           | `number`                         | required | —     |
| `windowStart`     | [Instant](./identity.md#instant) | required | —     |
| `windowEnd`       | [Instant](./identity.md#instant) | required | —     |

#### validateAttachments

```ts
validateAttachments(attachments: readonly SurfaceAttachment[]): readonly DeprecationViolation[]
```

#### validateClosure

```ts
validateClosure(checklist: ClosureChecklist): readonly DeprecationViolation[]
```

#### validateNotice

```ts
validateNotice(notice: DeprecationNotice): readonly DeprecationViolation[]
```

#### validateUsage

```ts
validateUsage(usage: readonly UsageRecord[], knownSurfaceIds: readonly string[]): readonly DeprecationViolation[]
```

#### WARNING_PROTOCOLS

Values: `http`, `event`, `job`, `bridge`, `cli`

#### warningFor

```ts
warningFor(notice: DeprecationNotice, protocol: WarningProtocol): DeprecationWarning
```

#### WarningProtocol

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

#### warningsAreCallerIndependent

Prove a warning is caller-independent by comparing two of them.

```ts
warningsAreCallerIndependent(first: DeprecationWarning, second: DeprecationWarning): ParseResult<null>
```

## Valid examples

##### alert/inside-the-supported-window-there-is-nothing-to-say

alerting on use of something that is still supported trains everybody to ignore
the alert

```json
[
  {
    "cohort": "general-availability",
    "consumerClass": "third-party-integration",
    "count": 137,
    "distinctTenants": 42,
    "environment": "production",
    "surfaceId": "route:studio.isis.legacy-runs",
    "version": 2,
    "windowEnd": "2026-08-01T00:00:00Z",
    "windowStart": "2026-07-31T00:00:00Z"
  }
]
```

##### alert/past-support-but-before-sunset-is-a-warning

it still answers and nobody will fix it, which is worth knowing and is not yet
an incident

```json
[
  {
    "cohort": "general-availability",
    "consumerClass": "third-party-integration",
    "count": 137,
    "distinctTenants": 42,
    "environment": "production",
    "surfaceId": "route:studio.isis.legacy-runs",
    "version": 2,
    "windowEnd": "2026-08-01T00:00:00Z",
    "windowStart": "2026-07-31T00:00:00Z"
  }
]
```

##### alert/past-the-sunset-is-critical

either the migration did not happen or the removal did not, and both are
somebody failing to do a thing they said they would

```json
[
  {
    "cohort": "general-availability",
    "consumerClass": "third-party-integration",
    "count": 137,
    "distinctTenants": 42,
    "environment": "production",
    "surfaceId": "route:studio.isis.legacy-runs",
    "version": 2,
    "windowEnd": "2026-08-01T00:00:00Z",
    "windowStart": "2026-07-31T00:00:00Z"
  }
]
```

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

## Invalid examples

##### usage/a-cohort-small-enough-to-identify-somebody

below the threshold the cohort IS the tenant, and the honest report is the
below-threshold bucket

Must produce: `cohort-below-anonymity-threshold`

```json
[
  {
    "cohort": "general-availability",
    "consumerClass": "third-party-integration",
    "count": 137,
    "distinctTenants": 2,
    "environment": "production",
    "surfaceId": "route:studio.isis.legacy-runs",
    "version": 2,
    "windowEnd": "2026-08-01T00:00:00Z",
    "windowStart": "2026-07-31T00:00:00Z"
  }
]
```

##### usage/a-cohort-that-names-a-tenant

a cohort naming a tenant is a tenant id with extra steps, and the record is read
by every dashboard the surface appears on

Must produce: `cohort-names-a-tenant`

```json
[
  {
    "cohort": "tenant:acme",
    "consumerClass": "third-party-integration",
    "count": 137,
    "distinctTenants": 42,
    "environment": "production",
    "surfaceId": "route:studio.isis.legacy-runs",
    "version": 2,
    "windowEnd": "2026-08-01T00:00:00Z",
    "windowStart": "2026-07-31T00:00:00Z"
  }
]
```

##### usage/a-counter-since-the-beginning-of-time

a window that only grows cannot be alerted on: the number goes up forever and
never crosses a threshold that means anything

Must produce: `usage-window-too-long`

```json
[
  {
    "cohort": "general-availability",
    "consumerClass": "third-party-integration",
    "count": 137,
    "distinctTenants": 42,
    "environment": "production",
    "surfaceId": "route:studio.isis.legacy-runs",
    "version": 2,
    "windowEnd": "2026-08-01T00:00:00Z",
    "windowStart": "2026-01-01T00:00:00Z"
  }
]
```

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

## Authorization and scope

| Symbol                        | Type     | Notes |
| ----------------------------- | -------- | ----- |
| `UsageRecord.distinctTenants` | `number` | —     |

## Idempotency and concurrency

Not applicable: nothing on this page is retried or applied twice: these are
declarations, not operations.

## Pagination

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

## State and failure

| Symbol                        | Type          | Notes |
| ----------------------------- | ------------- | ----- |
| `callerIndependenceViolation` | `function`    | —     |
| `DEPRECATION_VIOLATION_KINDS` | `enumeration` | —     |
| `DeprecationViolationKind`    | `type`        | —     |

## Compatibility

| Symbol                               | Type      | Notes                                                                    |
| ------------------------------------ | --------- | ------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `DeprecationNotice.removalVersion`   | `number   | null`                                                                    | The contract version it disappears in, or null while undecided. |
| `DeprecationNotice.supportedThrough` | `Instant` | The last date the surface is SUPPORTED — questions answered, bugs fixed. |
| `SurfaceAttachment.carrier`          | `string`  | Where the notice actually lives, in this repository.                     |
| `UsageRecord.version`                | `number`  | —                                                                        |

## Deprecation

| Symbol                              | Type          | Notes                                                                                                                                                                                                                     |
| ----------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `DEPRECATABLE_SURFACES`             | `enumeration` | The nine surfaces. `event` and `job` are separate rather than the ledger's "event/job", because they deprecate differently: an event has consumers the producer cannot enumerate, and a job has exactly one worker fleet. |
| `DeprecatableSurface`               | `type`        | —                                                                                                                                                                                                                         |
| `DEPRECATION_VIOLATION_KINDS`       | `enumeration` | —                                                                                                                                                                                                                         |
| `deprecationAlerts`                 | `function`    | Alert on usage that has passed a date somebody committed to.                                                                                                                                                              |
| `DeprecationNotice.deprecatedSince` | `Instant`     | —                                                                                                                                                                                                                         |
| `DeprecationNotice.removalVersion`  | `number       | null`                                                                                                                                                                                                                     | The contract version it disappears in, or null while undecided. |
| `DeprecationNotice.replacement`     | `Replacement` | —                                                                                                                                                                                                                         |
| `DeprecationNotice.sunsetOn`        | `Instant`     | The date it stops being served at all. Never before supportedThrough.                                                                                                                                                     |
| `DeprecationViolationKind`          | `type`        | —                                                                                                                                                                                                                         |
| `removalDecision`                   | `function`    | Decide whether a deprecated surface may be removed.                                                                                                                                                                       |
| `RemovalDecision`                   | `type`        | —                                                                                                                                                                                                                         |
| `Replacement`                       | `type`        | What replaces the deprecated thing.                                                                                                                                                                                       |

## Evidence

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