Eve library

Lifecycle and deprecation

Evidence

Revision 1

On this page

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#

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 required —
completed boolean required —

ClosureItem#

Field Type Required Notes
id 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 required —
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 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#

ts
(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#

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 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 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#

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