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.tssrc/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 | type | An actor. Opaque by construction — see . |
| ActorKind | type | — |
| ActorRef | type | — |
| ANCHOR_KINDS | enumeration | — |
| ANCHOR_ORPHAN_CAUSES | enumeration | What happened to an anchor when it was resolved against a later revision. |
| AnchorKind | type | — |
| AnchorOrphanCause | type | — |
| AnchorResolution | type | — |
| ArtifactId | type | A produced artifact, independent of any particular bytes. |
| ArtifactRef | type | — |
| asRecord | function | — |
| assertNoSyntheticValues | function | Refuse a value graph that contains anything a test builder made. |
| authorityOf | function | The actor whose authority a mutation used. |
| BlockId | type | A structural block inside an entity's content. |
| buildId | function | Build a canonical id from a bare segment, validating it. |
| ByteDigest | interface | — |
| CapabilityId | type | One capability a deployment either has or honestly does not (S1.5.f). |
| CorrelationId | type | A business transaction, spanning services and surviving retries. |
| EntityId | type | A domain entity inside a workbench (a run, a story, a lesson, a take). |
| EnvelopeId | type | One message on the wire (S1.5). |
| expectOk | function | Unwrap a result or throw. For tests and startup-time constants only. |
| findSyntheticValues | function | Every fixture value reachable from root. |
| FloatingArtifactRef | interface | A reference that names a MOVING TARGET. |
| formatId | function | The serializer, which is the exact inverse of the parser. |
| GraphTarget | interface | — |
| ID_CANONICAL_FORM | constant | — |
| ID_NAMESPACES | constant | — |
| ID_SEGMENT_MAX_LENGTH | constant | — |
| idEquals | function | Byte equality, which is correct ONLY because is strict. |
| IdKind | type | — |
| ImplementationCandidate | interface | — |
| Instant | type | An instant, as UTC text. |
| isComparableAt | function | Whether an anchor can even be asked about at a given revision. |
| isNonEmptyString | function | — |
| isPinned | function | — |
| isSyntheticId | function | Whether a string is a reserved fixture identifier. |
| isSyntheticObject | function | Whether an object carries the fixture mark. |
| JobId | type | One durable job (S1.5.e). |
| MediaProfile | interface | — |
| NormalizationReport | interface | — |
| normalizeIdCandidate | function | Fold an untrusted candidate towards canonical form and SAY WHAT CHANGED. |
| parseActorId | function | — |
| parseActorRef | function | — |
| parseArtifactId | function | — |
| parseArtifactRef | function | — |
| parseBlockId | function | — |
| parseCapabilityId | function | — |
| parseCorrelationId | function | — |
| parseEntityId | function | — |
| parseEnvelopeId | function | — |
| parseError | function | — |
| ParseErrorCode | type | — |
| parseInstant | function | — |
| parseJobId | function | — |
| parseOk | function | The parsing primitives are EXPORTED, not private. |
| ParseResult | type | — |
| parseRevisionId | function | — |
| parseRevisionRef | function | — |
| parseSha256Hex | function | — |
| parseStableAnchor | function | — |
| parseTenantId | function | — |
| parseTraceId | function | — |
| parseWorkbenchId | function | — |
| PinnedArtifactRef | interface | A reference that names EXACT BYTES. |
| ProductionSelection | type | — |
| Rational | interface | An exact rational, because frame rates are not numbers. |
| rationalEquals | function | — |
| reduceRational | function | — |
| RefusedCandidate | interface | — |
| rejectExtraFields | function | — |
| resolutionContract | function | What resolving a ref does and does not promise. |
| ResolutionContract | interface | — |
| RevisionId | type | One revision of one entity. |
| RevisionRef | interface | — |
| sameEntity | function | Two revision refs address the same entity in the same tenant and workbench. |
| SelectionOptions | interface | — |
| selectProductionImplementation | function | Choose the implementation a production container should use. |
| Sha256Hex | type | — |
| StableAnchor | type | — |
| SYNTHETIC_FINDING_KINDS | enumeration | — |
| SYNTHETIC_MARK_KEY | constant | The registry key behind the object mark. |
| 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 | constant | — |
| SYNTHETIC_SCAN_MAX_NODES | constant | — |
| SYNTHETIC_SEGMENT_PREFIX | constant | The reserved id segment prefix. |
| SyntheticFinding | interface | — |
| SyntheticFindingKind | type | — |
| syntheticMark | function | The mark itself, behind a function rather than a top-level const. |
| syntheticProvenance | function | The provenance a marked value carries, or null when it carries none. |
| SyntheticProvenance | interface | Why a value is synthetic and which factory made it that way. |
| SyntheticScanOptions | interface | — |
| SyntheticValueError | class | — |
| TenantId | type | The tenant an entity belongs to. The isolation boundary; never optional. |
| TimeBase | type | What a temporal position is counted in. |
| TimeBaseKind | type | — |
| TraceId | type | A W3C trace-context trace-id: 32 lowercase hex characters, not all zero. |
| WorkbenchId | type | A workbench instance (an Isis generation workbench, a Veritas newsroom desk). |
Shapes#
ActorId#
An actor. Opaque by construction — see .
Branded<'ActorId'>;
ActorKind#
ActorRef['kind'];
ActorRef#
| { 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#
StableAnchor['kind'];
AnchorOrphanCause#
(typeof ANCHOR_ORPHAN_CAUSES)[number];
AnchorResolution#
| { 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.
Branded<'ArtifactId'>;
ArtifactRef#
PinnedArtifactRef | FloatingArtifactRef;
asRecord#
asRecord(input: unknown, what: string): ParseResult<Record<string, unknown>>
assertNoSyntheticValues#
Refuse a value graph that contains anything a test builder made.
assertNoSyntheticValues(root: unknown, context: string, options?: SyntheticScanOptions): void
authorityOf#
The actor whose authority a mutation used.
authorityOf(actor: ActorRef): ActorId | null
BlockId#
A structural block inside an entity's content.
Branded<'BlockId'>;
buildId#
Build a canonical id from a bare segment, validating it.
buildId(kind: TKind, segment: string): ParseResult<Branded<TKind>>
ByteDigest#
| Field | Type | Required | Notes |
|---|---|---|---|
algorithm |
'sha256' |
required | — |
hex |
Sha256Hex | required | — |
CapabilityId#
One capability a deployment either has or honestly does not (S1.5.f).
Branded<'CapabilityId'>;
CorrelationId#
A business transaction, spanning services and surviving retries.
Branded<'CorrelationId'>;
EntityId#
A domain entity inside a workbench (a run, a story, a lesson, a take).
Branded<'EntityId'>;
EnvelopeId#
One message on the wire (S1.5).
Branded<'EnvelopeId'>;
expectOk#
Unwrap a result or throw. For tests and startup-time constants only.
expectOk(result: ParseResult<T>, context: string): T
findSyntheticValues#
Every fixture value reachable from root.
findSyntheticValues(root: unknown, options: SyntheticScanOptions = {}): readonly SyntheticFinding[]
FloatingArtifactRef#
A reference that names a MOVING TARGET.
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'floating' |
required | — |
artifactId |
ArtifactId | required | — |
channel |
'latest' | 'published' | 'draft' |
required | — |
media |
MediaProfile | null — MediaProfile |
required | — |
formatId#
The serializer, which is the exact inverse of the parser.
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.
idEquals(a: T, b: NoInfer<T>): boolean
IdKind#
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.
Branded<'Instant'>;
isComparableAt#
Whether an anchor can even be asked about at a given revision.
isComparableAt(anchor: StableAnchor, at: RevisionRef): boolean
isNonEmptyString#
isNonEmptyString(value: unknown): value is string
isPinned#
isPinned(ref: ArtifactRef): ref is PinnedArtifactRef
isSyntheticId#
Whether a string is a reserved fixture identifier.
isSyntheticId(value: unknown): boolean
isSyntheticObject#
Whether an object carries the fixture mark.
isSyntheticObject(value: unknown): boolean
JobId#
One durable job (S1.5.e).
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.
normalizeIdCandidate(candidate: string): NormalizationReport
parseActorId#
parseActorId(input: unknown): ParseResult<ActorId>
parseActorRef#
parseActorRef(input: unknown): ParseResult<ActorRef>
parseArtifactId#
parseArtifactId(input: unknown): ParseResult<ArtifactId>
parseArtifactRef#
parseArtifactRef(input: unknown): ParseResult<ArtifactRef>
parseBlockId#
parseBlockId(input: unknown): ParseResult<BlockId>
parseCapabilityId#
parseCapabilityId(input: unknown): ParseResult<CapabilityId>
parseCorrelationId#
parseCorrelationId(input: unknown): ParseResult<CorrelationId>
parseEntityId#
parseEntityId(input: unknown): ParseResult<EntityId>
parseEnvelopeId#
parseEnvelopeId(input: unknown): ParseResult<EnvelopeId>
parseError#
parseError(code: ParseErrorCode, message: string): ParseResult<T>
ParseErrorCode#
| '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#
parseInstant(input: unknown, field: string): ParseResult<Instant>
parseJobId#
parseJobId(input: unknown): ParseResult<JobId>
parseOk#
The parsing primitives are EXPORTED, not private.
parseOk(value: T): ParseResult<T>
ParseResult#
| { readonly ok: true; readonly value: T }
| { readonly ok: false; readonly code: ParseErrorCode; readonly message: string }
parseRevisionId#
parseRevisionId(input: unknown): ParseResult<RevisionId>
parseRevisionRef#
parseRevisionRef(input: unknown): ParseResult<RevisionRef>
parseSha256Hex#
parseSha256Hex(input: unknown): ParseResult<Sha256Hex>
parseStableAnchor#
parseStableAnchor(input: unknown): ParseResult<StableAnchor>
parseTenantId#
parseTenantId(input: unknown): ParseResult<TenantId>
parseTraceId#
parseTraceId(input: unknown): ParseResult<TraceId>
parseWorkbenchId#
parseWorkbenchId(input: unknown): ParseResult<WorkbenchId>
PinnedArtifactRef#
A reference that names EXACT BYTES.
| Field | Type | Required | Notes |
|---|---|---|---|
kind |
'pinned' |
required | — |
artifactId |
ArtifactId | required | — |
digest |
ByteDigest | required | — |
media |
MediaProfile | required | — |
ProductionSelection#
| { 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#
rationalEquals(a: Rational, b: Rational): boolean
reduceRational#
reduceRational(value: Rational): Rational
RefusedCandidate#
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string |
required | — |
reason |
string |
required | — |
rejectExtraFields#
rejectExtraFields(candidate: Record<string, unknown>, allowed: readonly string[], what: string): ParseResult<null>
resolutionContract#
What resolving a ref does and does not promise.
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.
Branded<'RevisionId'>;
RevisionRef#
| Field | Type | Required | Notes |
|---|---|---|---|
tenant |
TenantId | required | — |
workbench |
WorkbenchId | required | — |
entityId |
EntityId | required | — |
revisionId |
RevisionId | required | — |
schemaVersion |
number |
required | The entity schema this revision's content conforms to. Integer, >= 1. |
parent |
RevisionId | null — RevisionId |
required | LINEAGE: the revision this one was created from. Null for the first. |
base |
RevisionId | null — 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.
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 | optional | — |
selectProductionImplementation#
Choose the implementation a production container should use.
selectProductionImplementation(candidates: readonly ImplementationCandidate<T>[], context: string, options: SelectionOptions = {}): ProductionSelection<T>
Sha256Hex#
Branded<'Sha256Hex'>;
StableAnchor#
| (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 | required | — |
path |
string |
required | A JSON-pointer-ish path, so a finding in a 200-field graph is locatable. |
detail |
string |
required | — |
SyntheticFindingKind#
(typeof SYNTHETIC_FINDING_KINDS)[number];
syntheticMark#
The mark itself, behind a function rather than a top-level const.
syntheticMark(): symbol
syntheticProvenance#
The provenance a marked value carries, or null when it carries none.
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.
Branded<'TenantId'>;
TimeBase#
What a temporal position is counted in.
| { readonly base: 'seconds' }
| { readonly base: 'frames'; readonly rate: Rational }
| { readonly base: 'samples'; readonly sampleRate: number }
| { readonly base: 'musical'; readonly pulsesPerQuarter: number }
TimeBaseKind#
TimeBase['base'];
TraceId#
A W3C trace-context trace-id: 32 lowercase hex characters, not all zero.
Branded<'TraceId'>;
WorkbenchId#
A workbench instance (an Isis generation workbench, a Veritas newsroom desk).
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.jsonlibs/oshun/workbench-kit/src/identity.tslibs/oshun/workbench-kit/src/synthetic.ts