# Identity

The branded types every capability is addressed by, and the guard that refuses a
fixture value.

Generated from `libs/oshun/workbench-kit/src/identity.ts`,
`libs/oshun/workbench-kit/src/synthetic.ts` by
`node scripts/v1-workbenches/generate-workbench-kit-api-reference.mjs`. Ledger:
S1.4 / S1.13.d. Do not edit by hand.

## Summary

- `src/identity.ts`
- `src/synthetic.ts`

| Entry point                      | Runtime class | Authorized by |
| -------------------------------- | ------------- | ------------- |
| `@oshun/workbench-kit/identity`  | `contract`    | S1.4          |
| `@oshun/workbench-kit/synthetic` | `contract`    | S1.13.d       |

## Exports

| Symbol                                                            | Kind        | Summary                                                                                                                        |
| ----------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [ActorId](#actorid)                                               | type        | An actor. Opaque by construction — see .                                                                                       |
| [ActorKind](#actorkind)                                           | type        | —                                                                                                                              |
| [ActorRef](#actorref)                                             | type        | —                                                                                                                              |
| [ANCHOR_KINDS](#anchor_kinds)                                     | enumeration | —                                                                                                                              |
| [ANCHOR_ORPHAN_CAUSES](#anchor_orphan_causes)                     | enumeration | What happened to an anchor when it was resolved against a later revision.                                                      |
| [AnchorKind](#anchorkind)                                         | type        | —                                                                                                                              |
| [AnchorOrphanCause](#anchororphancause)                           | type        | —                                                                                                                              |
| [AnchorResolution](#anchorresolution)                             | type        | —                                                                                                                              |
| [ArtifactId](#artifactid)                                         | type        | A produced artifact, independent of any particular bytes.                                                                      |
| [ArtifactRef](#artifactref)                                       | type        | —                                                                                                                              |
| [asRecord](#asrecord)                                             | function    | —                                                                                                                              |
| [assertNoSyntheticValues](#assertnosyntheticvalues)               | function    | Refuse a value graph that contains anything a test builder made.                                                               |
| [authorityOf](#authorityof)                                       | function    | The actor whose authority a mutation used.                                                                                     |
| [BlockId](#blockid)                                               | type        | A structural block inside an entity's content.                                                                                 |
| [buildId](#buildid)                                               | function    | Build a canonical id from a bare segment, validating it.                                                                       |
| [ByteDigest](#bytedigest)                                         | interface   | —                                                                                                                              |
| [CapabilityId](#capabilityid)                                     | type        | One capability a deployment either has or honestly does not (S1.5.f).                                                          |
| [CorrelationId](#correlationid)                                   | type        | A business transaction, spanning services and surviving retries.                                                               |
| [EntityId](#entityid)                                             | type        | A domain entity inside a workbench (a run, a story, a lesson, a take).                                                         |
| [EnvelopeId](#envelopeid)                                         | type        | One message on the wire (S1.5).                                                                                                |
| [expectOk](#expectok)                                             | function    | Unwrap a result or throw. For tests and startup-time constants only.                                                           |
| [findSyntheticValues](#findsyntheticvalues)                       | function    | Every fixture value reachable from `root`.                                                                                     |
| [FloatingArtifactRef](#floatingartifactref)                       | interface   | A reference that names a MOVING TARGET.                                                                                        |
| [formatId](#formatid)                                             | function    | The serializer, which is the exact inverse of the parser.                                                                      |
| [GraphTarget](#graphtarget)                                       | interface   | —                                                                                                                              |
| [ID_CANONICAL_FORM](#id_canonical_form)                           | constant    | —                                                                                                                              |
| [ID_NAMESPACES](#id_namespaces)                                   | constant    | —                                                                                                                              |
| [ID_SEGMENT_MAX_LENGTH](#id_segment_max_length)                   | constant    | —                                                                                                                              |
| [idEquals](#idequals)                                             | function    | Byte equality, which is correct ONLY because is strict.                                                                        |
| [IdKind](#idkind)                                                 | type        | —                                                                                                                              |
| [ImplementationCandidate](#implementationcandidate)               | interface   | —                                                                                                                              |
| [Instant](#instant)                                               | type        | An instant, as UTC text.                                                                                                       |
| [isComparableAt](#iscomparableat)                                 | function    | Whether an anchor can even be asked about at a given revision.                                                                 |
| [isNonEmptyString](#isnonemptystring)                             | function    | —                                                                                                                              |
| [isPinned](#ispinned)                                             | function    | —                                                                                                                              |
| [isSyntheticId](#issyntheticid)                                   | function    | Whether a string is a reserved fixture identifier.                                                                             |
| [isSyntheticObject](#issyntheticobject)                           | function    | Whether an object carries the fixture mark.                                                                                    |
| [JobId](#jobid)                                                   | type        | One durable job (S1.5.e).                                                                                                      |
| [MediaProfile](#mediaprofile)                                     | interface   | —                                                                                                                              |
| [NormalizationReport](#normalizationreport)                       | interface   | —                                                                                                                              |
| [normalizeIdCandidate](#normalizeidcandidate)                     | function    | Fold an untrusted candidate towards canonical form and SAY WHAT CHANGED.                                                       |
| [parseActorId](#parseactorid)                                     | function    | —                                                                                                                              |
| [parseActorRef](#parseactorref)                                   | function    | —                                                                                                                              |
| [parseArtifactId](#parseartifactid)                               | function    | —                                                                                                                              |
| [parseArtifactRef](#parseartifactref)                             | function    | —                                                                                                                              |
| [parseBlockId](#parseblockid)                                     | function    | —                                                                                                                              |
| [parseCapabilityId](#parsecapabilityid)                           | function    | —                                                                                                                              |
| [parseCorrelationId](#parsecorrelationid)                         | function    | —                                                                                                                              |
| [parseEntityId](#parseentityid)                                   | function    | —                                                                                                                              |
| [parseEnvelopeId](#parseenvelopeid)                               | function    | —                                                                                                                              |
| [parseError](#parseerror)                                         | function    | —                                                                                                                              |
| [ParseErrorCode](#parseerrorcode)                                 | type        | —                                                                                                                              |
| [parseInstant](#parseinstant)                                     | function    | —                                                                                                                              |
| [parseJobId](#parsejobid)                                         | function    | —                                                                                                                              |
| [parseOk](#parseok)                                               | function    | The parsing primitives are EXPORTED, not private.                                                                              |
| [ParseResult](#parseresult)                                       | type        | —                                                                                                                              |
| [parseRevisionId](#parserevisionid)                               | function    | —                                                                                                                              |
| [parseRevisionRef](#parserevisionref)                             | function    | —                                                                                                                              |
| [parseSha256Hex](#parsesha256hex)                                 | function    | —                                                                                                                              |
| [parseStableAnchor](#parsestableanchor)                           | function    | —                                                                                                                              |
| [parseTenantId](#parsetenantid)                                   | function    | —                                                                                                                              |
| [parseTraceId](#parsetraceid)                                     | function    | —                                                                                                                              |
| [parseWorkbenchId](#parseworkbenchid)                             | function    | —                                                                                                                              |
| [PinnedArtifactRef](#pinnedartifactref)                           | interface   | A reference that names EXACT BYTES.                                                                                            |
| [ProductionSelection](#productionselection)                       | type        | —                                                                                                                              |
| [Rational](#rational)                                             | interface   | An exact rational, because frame rates are not numbers.                                                                        |
| [rationalEquals](#rationalequals)                                 | function    | —                                                                                                                              |
| [reduceRational](#reducerational)                                 | function    | —                                                                                                                              |
| [RefusedCandidate](#refusedcandidate)                             | interface   | —                                                                                                                              |
| [rejectExtraFields](#rejectextrafields)                           | function    | —                                                                                                                              |
| [resolutionContract](#resolutioncontract)                         | function    | What resolving a ref does and does not promise.                                                                                |
| [ResolutionContract](#resolutioncontract)                         | interface   | —                                                                                                                              |
| [RevisionId](#revisionid)                                         | type        | One revision of one entity.                                                                                                    |
| [RevisionRef](#revisionref)                                       | interface   | —                                                                                                                              |
| [sameEntity](#sameentity)                                         | function    | Two revision refs address the same entity in the same tenant and workbench.                                                    |
| [SelectionOptions](#selectionoptions)                             | interface   | —                                                                                                                              |
| [selectProductionImplementation](#selectproductionimplementation) | function    | Choose the implementation a production container should use.                                                                   |
| [Sha256Hex](#sha256hex)                                           | type        | —                                                                                                                              |
| [StableAnchor](#stableanchor)                                     | type        | —                                                                                                                              |
| [SYNTHETIC_FINDING_KINDS](#synthetic_finding_kinds)               | enumeration | —                                                                                                                              |
| [SYNTHETIC_MARK_KEY](#synthetic_mark_key)                         | constant    | The registry key behind the object mark.                                                                                       |
| [SYNTHETIC_NAMESPACE](#synthetic_namespace)                       | constant    | The reserved namespace for tokens that have no namespace of their own — idempotency keys, cursors, checkpoints, resume tokens. |
| [SYNTHETIC_SCAN_MAX_DEPTH](#synthetic_scan_max_depth)             | constant    | —                                                                                                                              |
| [SYNTHETIC_SCAN_MAX_NODES](#synthetic_scan_max_nodes)             | constant    | —                                                                                                                              |
| [SYNTHETIC_SEGMENT_PREFIX](#synthetic_segment_prefix)             | constant    | The reserved id segment prefix.                                                                                                |
| [SyntheticFinding](#syntheticfinding)                             | interface   | —                                                                                                                              |
| [SyntheticFindingKind](#syntheticfindingkind)                     | type        | —                                                                                                                              |
| [syntheticMark](#syntheticmark)                                   | function    | The mark itself, behind a function rather than a top-level `const`.                                                            |
| [syntheticProvenance](#syntheticprovenance)                       | function    | The provenance a marked value carries, or null when it carries none.                                                           |
| [SyntheticProvenance](#syntheticprovenance)                       | interface   | Why a value is synthetic and which factory made it that way.                                                                   |
| [SyntheticScanOptions](#syntheticscanoptions)                     | interface   | —                                                                                                                              |
| [SyntheticValueError](#syntheticvalueerror)                       | class       | —                                                                                                                              |
| [TenantId](#tenantid)                                             | type        | The tenant an entity belongs to. The isolation boundary; never optional.                                                       |
| [TimeBase](#timebase)                                             | type        | What a temporal position is counted in.                                                                                        |
| [TimeBaseKind](#timebasekind)                                     | type        | —                                                                                                                              |
| [TraceId](#traceid)                                               | type        | A W3C trace-context trace-id: 32 lowercase hex characters, not all zero.                                                       |
| [WorkbenchId](#workbenchid)                                       | type        | A workbench instance (an Isis generation workbench, a Veritas newsroom desk).                                                  |

## Shapes

#### ActorId

An actor. Opaque by construction — see .

```ts
Branded<'ActorId'>;
```

#### ActorKind

```ts
ActorRef['kind'];
```

#### ActorRef

```ts
| { readonly kind: 'human'; readonly actorId: ActorId; readonly tenant: TenantId; }
| { readonly kind: 'delegated'; readonly actorId: ActorId; readonly onBehalfOf: ActorId; readonly grant: string; readonly tenant: TenantId; }
| { readonly kind: 'service'; readonly actorId: ActorId; readonly service: string; readonly tenant: TenantId | null; }
| { readonly kind: 'system'; readonly actorId: ActorId; readonly reason: string; }
| { readonly kind: 'redacted'; readonly redactionId: ActorId; readonly cause: 'erasure-request' | 'retention-expiry' | 'legal-hold'; readonly redactedAt: string; }
```

#### ANCHOR_KINDS

Values: `entity`, `field`, `block`, `range`, `temporal`, `graph`, `canvas`,
`hierarchy`

#### ANCHOR_ORPHAN_CAUSES

What happened to an anchor when it was resolved against a later revision.

Values: `deleted`, `replaced`, `migrated`, `permission-hidden`, `ambiguous`,
`unsupported`

#### AnchorKind

```ts
StableAnchor['kind'];
```

#### AnchorOrphanCause

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

#### AnchorResolution

```ts
| { readonly status: 'resolved'; readonly at: RevisionRef }
| { readonly status: 'rebased'; readonly at: RevisionRef; readonly anchor: StableAnchor; readonly confidence: number; }
| { readonly status: 'orphaned'; readonly cause: AnchorOrphanCause; readonly at: RevisionRef; }
```

#### ArtifactId

A produced artifact, independent of any particular bytes.

```ts
Branded<'ArtifactId'>;
```

#### ArtifactRef

```ts
PinnedArtifactRef | FloatingArtifactRef;
```

#### asRecord

```ts
asRecord(input: unknown, what: string): ParseResult<Record<string, unknown>>
```

#### assertNoSyntheticValues

Refuse a value graph that contains anything a test builder made.

```ts
assertNoSyntheticValues(root: unknown, context: string, options?: SyntheticScanOptions): void
```

#### authorityOf

The actor whose authority a mutation used.

```ts
authorityOf(actor: ActorRef): ActorId | null
```

#### BlockId

A structural block inside an entity's content.

```ts
Branded<'BlockId'>;
```

#### buildId

Build a canonical id from a bare segment, validating it.

```ts
buildId(kind: TKind, segment: string): ParseResult<Branded<TKind>>
```

#### ByteDigest

| Field       | Type                    | Required | Notes |
| ----------- | ----------------------- | -------- | ----- |
| `algorithm` | `'sha256'`              | required | —     |
| `hex`       | [Sha256Hex](#sha256hex) | required | —     |

#### CapabilityId

One capability a deployment either has or honestly does not (S1.5.f).

```ts
Branded<'CapabilityId'>;
```

#### CorrelationId

A business transaction, spanning services and surviving retries.

```ts
Branded<'CorrelationId'>;
```

#### EntityId

A domain entity inside a workbench (a run, a story, a lesson, a take).

```ts
Branded<'EntityId'>;
```

#### EnvelopeId

One message on the wire (S1.5).

```ts
Branded<'EnvelopeId'>;
```

#### expectOk

Unwrap a result or throw. For tests and startup-time constants only.

```ts
expectOk(result: ParseResult<T>, context: string): T
```

#### findSyntheticValues

Every fixture value reachable from `root`.

```ts
findSyntheticValues(root: unknown, options: SyntheticScanOptions = {}): readonly SyntheticFinding[]
```

#### FloatingArtifactRef

A reference that names a MOVING TARGET.

| Field        | Type                                                   | Required | Notes |
| ------------ | ------------------------------------------------------ | -------- | ----- |
| `kind`       | `'floating'`                                           | required | —     |
| `artifactId` | [ArtifactId](#artifactid)                              | required | —     |
| `channel`    | `'latest' \| 'published' \| 'draft'`                   | required | —     |
| `media`      | `MediaProfile \| null` — [MediaProfile](#mediaprofile) | required | —     |

#### formatId

The serializer, which is the exact inverse of the parser.

```ts
formatId(id: Branded<IdKind>): string
```

#### GraphTarget

| Field     | Type                         | Required | Notes                                                                  |
| --------- | ---------------------------- | -------- | ---------------------------------------------------------------------- |
| `target`  | `'node' \| 'edge' \| 'port'` | required | —                                                                      |
| `id`      | `string`                     | required | —                                                                      |
| `ownerId` | `string \| null`             | required | For a port, the node it belongs to; a bare port id is not addressable. |

#### ID_CANONICAL_FORM

Value: `'<namespace>:<segment>'`

#### ID_NAMESPACES

#### ID_SEGMENT_MAX_LENGTH

Value: `63`

#### idEquals

Byte equality, which is correct ONLY because is strict.

```ts
idEquals(a: T, b: NoInfer<T>): boolean
```

#### IdKind

```ts
keyof typeof ID_NAMESPACES
```

#### ImplementationCandidate

| Field            | Type     | Required | Notes                                                                    |
| ---------------- | -------- | -------- | ------------------------------------------------------------------------ |
| `name`           | `string` | required | How the container knows it: a token, a package name, a registration key. |
| `implementation` | `T`      | required | —                                                                        |

#### Instant

An instant, as UTC text.

```ts
Branded<'Instant'>;
```

#### isComparableAt

Whether an anchor can even be asked about at a given revision.

```ts
isComparableAt(anchor: StableAnchor, at: RevisionRef): boolean
```

#### isNonEmptyString

```ts
isNonEmptyString(value: unknown): value is string
```

#### isPinned

```ts
isPinned(ref: ArtifactRef): ref is PinnedArtifactRef
```

#### isSyntheticId

Whether a string is a reserved fixture identifier.

```ts
isSyntheticId(value: unknown): boolean
```

#### isSyntheticObject

Whether an object carries the fixture mark.

```ts
isSyntheticObject(value: unknown): boolean
```

#### JobId

One durable job (S1.5.e).

```ts
Branded<'JobId'>;
```

#### MediaProfile

| Field       | Type             | Required | Notes                                                                                                                                                                                                 |
| ----------- | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mediaType` | `string`         | required | `type/subtype`, lowercase.                                                                                                                                                                            |
| `profile`   | `string \| null` | required | The variant WITHIN that media type: a codec profile, a colour space, a schema version. Nullable because most media types have exactly one, and a required field with one legal value teaches nothing. |

#### NormalizationReport

| Field        | Type                                                                          | Required | Notes                                                                 |
| ------------ | ----------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `candidate`  | `string`                                                                      | required | —                                                                     |
| `normalized` | `string`                                                                      | required | What a strict parser would accept, if anything.                       |
| `changes`    | `readonly ('trimmed-whitespace' \| 'lowercased' \| 'collapsed-separators')[]` | required | Every transformation applied, so an input boundary can log or reject. |

#### normalizeIdCandidate

Fold an untrusted candidate towards canonical form and SAY WHAT CHANGED.

```ts
normalizeIdCandidate(candidate: string): NormalizationReport
```

#### parseActorId

```ts
parseActorId(input: unknown): ParseResult<ActorId>
```

#### parseActorRef

```ts
parseActorRef(input: unknown): ParseResult<ActorRef>
```

#### parseArtifactId

```ts
parseArtifactId(input: unknown): ParseResult<ArtifactId>
```

#### parseArtifactRef

```ts
parseArtifactRef(input: unknown): ParseResult<ArtifactRef>
```

#### parseBlockId

```ts
parseBlockId(input: unknown): ParseResult<BlockId>
```

#### parseCapabilityId

```ts
parseCapabilityId(input: unknown): ParseResult<CapabilityId>
```

#### parseCorrelationId

```ts
parseCorrelationId(input: unknown): ParseResult<CorrelationId>
```

#### parseEntityId

```ts
parseEntityId(input: unknown): ParseResult<EntityId>
```

#### parseEnvelopeId

```ts
parseEnvelopeId(input: unknown): ParseResult<EnvelopeId>
```

#### parseError

```ts
parseError(code: ParseErrorCode, message: string): ParseResult<T>
```

#### ParseErrorCode

```ts
| 'not-a-string'
| 'empty'
| 'missing-namespace'
| 'wrong-namespace'
| 'not-canonical-case'
| 'invalid-segment'
| 'too-long'
| 'not-an-object'
| 'unknown-kind'
| 'unknown-field'
| 'display-data-in-identity'
| 'missing-field'
| 'invalid-field'
| 'invariant-violated'
```

#### parseInstant

```ts
parseInstant(input: unknown, field: string): ParseResult<Instant>
```

#### parseJobId

```ts
parseJobId(input: unknown): ParseResult<JobId>
```

#### parseOk

The parsing primitives are EXPORTED, not private.

```ts
parseOk(value: T): ParseResult<T>
```

#### ParseResult

```ts
| { readonly ok: true; readonly value: T }
| { readonly ok: false; readonly code: ParseErrorCode; readonly message: string }
```

#### parseRevisionId

```ts
parseRevisionId(input: unknown): ParseResult<RevisionId>
```

#### parseRevisionRef

```ts
parseRevisionRef(input: unknown): ParseResult<RevisionRef>
```

#### parseSha256Hex

```ts
parseSha256Hex(input: unknown): ParseResult<Sha256Hex>
```

#### parseStableAnchor

```ts
parseStableAnchor(input: unknown): ParseResult<StableAnchor>
```

#### parseTenantId

```ts
parseTenantId(input: unknown): ParseResult<TenantId>
```

#### parseTraceId

```ts
parseTraceId(input: unknown): ParseResult<TraceId>
```

#### parseWorkbenchId

```ts
parseWorkbenchId(input: unknown): ParseResult<WorkbenchId>
```

#### PinnedArtifactRef

A reference that names EXACT BYTES.

| Field        | Type                          | Required | Notes |
| ------------ | ----------------------------- | -------- | ----- |
| `kind`       | `'pinned'`                    | required | —     |
| `artifactId` | [ArtifactId](#artifactid)     | required | —     |
| `digest`     | [ByteDigest](#bytedigest)     | required | —     |
| `media`      | [MediaProfile](#mediaprofile) | required | —     |

#### ProductionSelection

```ts
| { readonly selected: true; readonly name: string; readonly implementation: T; readonly refused: readonly RefusedCandidate[]; }
| { readonly selected: false; readonly reason: 'no-candidate' | 'all-candidates-synthetic' | 'ambiguous'; readonly detail: string; readonly refused: readonly RefusedCandidate[]; }
```

#### Rational

An exact rational, because frame rates are not numbers.

| Field         | Type     | Required | Notes |
| ------------- | -------- | -------- | ----- |
| `numerator`   | `number` | required | —     |
| `denominator` | `number` | required | —     |

#### rationalEquals

```ts
rationalEquals(a: Rational, b: Rational): boolean
```

#### reduceRational

```ts
reduceRational(value: Rational): Rational
```

#### RefusedCandidate

| Field    | Type     | Required | Notes |
| -------- | -------- | -------- | ----- |
| `name`   | `string` | required | —     |
| `reason` | `string` | required | —     |

#### rejectExtraFields

```ts
rejectExtraFields(candidate: Record<string, unknown>, allowed: readonly string[], what: string): ParseResult<null>
```

#### resolutionContract

What resolving a ref does and does not promise.

```ts
resolutionContract(ref: ArtifactRef): ResolutionContract
```

#### ResolutionContract

| Field           | Type      | Required | Notes                                              |
| --------------- | --------- | -------- | -------------------------------------------------- |
| `deterministic` | `boolean` | required | Two resolutions of this ref return the same bytes. |
| `cacheable`     | `boolean` | required | The result may be cached without an expiry.        |
| `signable`      | `boolean` | required | A signature over this ref means something later.   |
| `rationale`     | `string`  | required | —                                                  |

#### RevisionId

One revision of one entity.

```ts
Branded<'RevisionId'>;
```

#### RevisionRef

| Field           | Type                                             | Required | Notes                                                                 |
| --------------- | ------------------------------------------------ | -------- | --------------------------------------------------------------------- |
| `tenant`        | [TenantId](#tenantid)                            | required | —                                                                     |
| `workbench`     | [WorkbenchId](#workbenchid)                      | required | —                                                                     |
| `entityId`      | [EntityId](#entityid)                            | required | —                                                                     |
| `revisionId`    | [RevisionId](#revisionid)                        | required | —                                                                     |
| `schemaVersion` | `number`                                         | required | The entity schema this revision's content conforms to. Integer, >= 1. |
| `parent`        | `RevisionId \| null` — [RevisionId](#revisionid) | required | LINEAGE: the revision this one was created from. Null for the first.  |
| `base`          | `RevisionId \| null` — [RevisionId](#revisionid) | required | COMPARISON: the revision a diff or merge is computed against.         |

#### sameEntity

Two revision refs address the same entity in the same tenant and workbench.

```ts
sameEntity(a: RevisionRef, b: RevisionRef): boolean
```

#### SelectionOptions

| Field    | Type                                          | Required | Notes                                                                      |
| -------- | --------------------------------------------- | -------- | -------------------------------------------------------------------------- |
| `prefer` | `string`                                      | optional | Which candidate wins when more than one real implementation is registered. |
| `scan`   | [SyntheticScanOptions](#syntheticscanoptions) | optional | —                                                                          |

#### selectProductionImplementation

Choose the implementation a production container should use.

```ts
selectProductionImplementation(candidates: readonly ImplementationCandidate<T>[], context: string, options: SelectionOptions = {}): ProductionSelection<T>
```

#### Sha256Hex

```ts
Branded<'Sha256Hex'>;
```

#### StableAnchor

```ts
| (AnchorBase & { readonly kind: 'entity' })
| (AnchorBase & { readonly kind: 'field'; readonly fieldPath: readonly string[] })
| (AnchorBase & { readonly kind: 'block'; readonly blockId: BlockId })
| (AnchorBase & { readonly kind: 'range'; readonly blockId: BlockId; readonly start: number; readonly end: number; })
| (AnchorBase & { readonly kind: 'temporal'; readonly timeBase: TimeBase; readonly position: number; })
| (AnchorBase & { readonly kind: 'graph'; readonly graph: GraphTarget })
| (AnchorBase & { readonly kind: 'canvas'; readonly objectId: string; readonly part: string | null; })
| (AnchorBase & { readonly kind: 'hierarchy'; readonly path: readonly string[] })
```

#### SYNTHETIC_FINDING_KINDS

Values: `marked-object`, `synthetic-id`, `scan-truncated`

#### SYNTHETIC_MARK_KEY

The registry key behind the object mark.

Value: `'@oshun/workbench-kit#synthetic'`

#### SYNTHETIC_NAMESPACE

The reserved namespace for tokens that have no namespace of their own —
idempotency keys, cursors, checkpoints, resume tokens.

Value: `'synthetic'`

#### SYNTHETIC_SCAN_MAX_DEPTH

Value: `12`

#### SYNTHETIC_SCAN_MAX_NODES

Value: `5_000`

#### SYNTHETIC_SEGMENT_PREFIX

The reserved id segment prefix.

Value: `'synthetic-'`

#### SyntheticFinding

| Field    | Type                                          | Required | Notes                                                                    |
| -------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------ |
| `kind`   | [SyntheticFindingKind](#syntheticfindingkind) | required | —                                                                        |
| `path`   | `string`                                      | required | A JSON-pointer-ish path, so a finding in a 200-field graph is locatable. |
| `detail` | `string`                                      | required | —                                                                        |

#### SyntheticFindingKind

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

#### syntheticMark

The mark itself, behind a function rather than a top-level `const`.

```ts
syntheticMark(): symbol
```

#### syntheticProvenance

The provenance a marked value carries, or null when it carries none.

```ts
syntheticProvenance(value: unknown): SyntheticProvenance | null
```

#### SyntheticProvenance

Why a value is synthetic and which factory made it that way.

| Field        | Type     | Required | Notes                                                                    |
| ------------ | -------- | -------- | ------------------------------------------------------------------------ |
| `builder`    | `string` | required | The builder that minted it, so a finding names a fix rather than a fact. |
| `ledgerItem` | `string` | required | The ledger cell that decided the marking rule.                           |

#### SyntheticScanOptions

| Field      | Type     | Required | Notes                                                                                                                                           |
| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `maxDepth` | `number` | optional | How deep to walk. Bounded because the guard runs on a request path and an adversarial or merely cyclic-through-arrays payload must not hang it. |
| `maxNodes` | `number` | optional | How many nodes to visit before stopping and SAYING it stopped.                                                                                  |

#### SyntheticValueError

#### TenantId

The tenant an entity belongs to. The isolation boundary; never optional.

```ts
Branded<'TenantId'>;
```

#### TimeBase

What a temporal position is counted in.

```ts
| { readonly base: 'seconds' }
| { readonly base: 'frames'; readonly rate: Rational }
| { readonly base: 'samples'; readonly sampleRate: number }
| { readonly base: 'musical'; readonly pulsesPerQuarter: number }
```

#### TimeBaseKind

```ts
TimeBase['base'];
```

#### TraceId

A W3C trace-context trace-id: 32 lowercase hex characters, not all zero.

```ts
Branded<'TraceId'>;
```

#### WorkbenchId

A workbench instance (an Isis generation workbench, a Veritas newsroom desk).

```ts
Branded<'WorkbenchId'>;
```

## Valid examples

No committed fixture corpus covers this page's accepted cases; they are
unit-level and live in the module's own spec.

## Invalid examples

No committed fixture corpus covers this page's refused cases; they are
unit-level and live in the module's own spec.

## Authorization and scope

| Symbol               | Type       | Notes                                                                    |
| -------------------- | ---------- | ------------------------------------------------------------------------ |
| `ActorId`            | `type`     | An actor. Opaque by construction — see .                                 |
| `ActorKind`          | `type`     | —                                                                        |
| `ActorRef`           | `type`     | —                                                                        |
| `parseActorId`       | `function` | —                                                                        |
| `parseActorRef`      | `function` | —                                                                        |
| `parseTenantId`      | `function` | —                                                                        |
| `RevisionRef.tenant` | `TenantId` | —                                                                        |
| `TenantId`           | `type`     | The tenant an entity belongs to. The isolation boundary; never optional. |

## Idempotency and concurrency

| Symbol                   | Type         | Notes                       |
| ------------------------ | ------------ | --------------------------- |
| `parseRevisionId`        | `function`   | —                           |
| `parseRevisionRef`       | `function`   | —                           |
| `RevisionId`             | `type`       | One revision of one entity. |
| `RevisionRef.revisionId` | `RevisionId` | —                           |

## Pagination

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

## State and failure

| Symbol                | Type       | Notes |
| --------------------- | ---------- | ----- |
| `parseError`          | `function` | —     |
| `ParseErrorCode`      | `type`     | —     |
| `SyntheticValueError` | `class`    | —     |

## Compatibility

| Symbol                      | Type     | Notes                                                                 |
| --------------------------- | -------- | --------------------------------------------------------------------- |
| `RevisionRef.schemaVersion` | `number` | The entity schema this revision's content conforms to. Integer, >= 1. |

## Deprecation

Not applicable: nothing on this page can be deprecated on its own; the package
version is its lifecycle.

## Evidence

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