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 | enumeration | — |
| AlertSeverity | type | — |
| ATTACHMENT_KINDS | enumeration | — |
| AttachmentKind | type | — |
| callerIndependenceViolation | function | — |
| CLOSURE_ITEMS | enumeration | What has to go WITH the surface. |
| closureChecklist | function | A fresh checklist, with every item open. |
| ClosureChecklist | interface | — |
| ClosureItem | interface | — |
| ClosureItemId | type | — |
| Cohort | type | — |
| COHORT_ANONYMITY_THRESHOLD | constant | Fewer distinct tenants than this and a cohort identifies somebody. |
| COHORTS | enumeration | Tenant-safe cohorts: buckets, never identities. |
| CONSUMER_CLASSES | enumeration | — |
| ConsumerClass | type | — |
| 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 | — |
| DeprecationAlert | interface | — |
| deprecationAlerts | function | Alert on usage that has passed a date somebody committed to. |
| DeprecationNotice | interface | — |
| DeprecationViolation | interface | — |
| DeprecationViolationKind | type | — |
| DeprecationWarning | interface | — |
| Environment | type | — |
| ENVIRONMENTS | enumeration | — |
| MAX_USAGE_WINDOW_HOURS | constant | A window longer than this is a counter nobody can alert on. |
| removalDecision | function | Decide whether a deprecated surface may be removed. |
| RemovalDecision | type | — |
| RemovalException | interface | An approved extension past the sunset. Expires by itself. |
| Replacement | type | What replaces the deprecated thing. |
| SURFACE_ATTACHMENTS | constant | Where a deprecation notice can be attached today, per surface. |
| SurfaceAttachment | interface | — |
| UsageRecord | interface | — |
| validateAttachments | function | — |
| validateClosure | function | — |
| validateNotice | function | — |
| validateUsage | function | — |
| WARNING_PROTOCOLS | enumeration | — |
| warningFor | function | — |
| WarningProtocol | type | — |
| warningsAreCallerIndependent | function | Prove a warning is caller-independent by comparing two of them. |
Shapes#
ALERT_SEVERITIES#
Values: warning, critical
AlertSeverity#
(typeof ALERT_SEVERITIES)[number];
ATTACHMENT_KINDS#
Values: descriptor-field, version-range, sidecar-register
AttachmentKind#
(typeof ATTACHMENT_KINDS)[number];
callerIndependenceViolation#
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.
closureChecklist(notice: DeprecationNotice): ClosureChecklist
ClosureChecklist#
| Field | Type | Required | Notes |
|---|---|---|---|
surfaceId |
string |
required | — |
items |
readonly ClosureItem[] — ClosureItem |
required | — |
completed |
boolean |
required | — |
ClosureItem#
| Field | Type | Required | Notes |
|---|---|---|---|
id |
ClosureItemId | required | — |
done |
boolean |
required | — |
ClosureItemId#
(typeof CLOSURE_ITEMS)[number];
Cohort#
(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#
(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#
(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 | required | — |
consumerClass |
ConsumerClass | required | — |
count |
number |
required | — |
detail |
string |
required | — |
deprecationAlerts#
Alert on usage that has passed a date somebody committed to.
deprecationAlerts(notice: DeprecationNotice, usage: readonly UsageRecord[], now: Instant): readonly DeprecationAlert[]
DeprecationNotice#
| Field | Type | Required | Notes |
|---|---|---|---|
surface |
DeprecatableSurface | required | — |
surfaceId |
string |
required | — |
deprecatedSince |
Instant | required | — |
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 | required | The last date the surface is SUPPORTED — questions answered, bugs fixed. |
sunsetOn |
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 |
required | — |
DeprecationViolation#
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
DeprecationViolationKind | required | — |
subject |
string |
required | — |
detail |
string |
required | — |
DeprecationViolationKind#
(typeof DEPRECATION_VIOLATION_KINDS)[number];
DeprecationWarning#
| Field | Type | Required | Notes |
|---|---|---|---|
protocol |
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#
(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.
removalDecision(notice: DeprecationNotice, usage: readonly UsageRecord[], now: Instant): RemovalDecision
RemovalDecision#
| { 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 | required | — |
Replacement#
What replaces the deprecated thing.
| { 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 | required | — |
attachment |
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 | required | — |
environment |
Environment | required | — |
cohort |
Cohort | required | — |
distinctTenants |
number |
required | — |
count |
number |
required | — |
windowStart |
Instant | required | — |
windowEnd |
Instant | required | — |
validateAttachments#
validateAttachments(attachments: readonly SurfaceAttachment[]): readonly DeprecationViolation[]
validateClosure#
validateClosure(checklist: ClosureChecklist): readonly DeprecationViolation[]
validateNotice#
validateNotice(notice: DeprecationNotice): readonly DeprecationViolation[]
validateUsage#
validateUsage(usage: readonly UsageRecord[], knownSurfaceIds: readonly string[]): readonly DeprecationViolation[]
WARNING_PROTOCOLS#
Values: http, event, job, bridge, cli
warningFor#
warningFor(notice: DeprecationNotice, protocol: WarningProtocol): DeprecationWarning
WarningProtocol#
(typeof WARNING_PROTOCOLS)[number];
warningsAreCallerIndependent#
Prove a warning is caller-independent by comparing two of them.
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
[
{
"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
[
{
"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
[
{
"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
[
{
"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
[
{
"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
[
{
"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.jsonevidence/v1-workbenches/workbench-kit-export-map.jsonlibs/oshun/workbench-kit/src/deprecation.ts