Eve library

Identity

Evidence

Revision 1

On this page

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

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 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 required —
channel 'latest' | 'published' | 'draft' required —
media MediaProfile | null — 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 required —
digest ByteDigest required —
media 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 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.

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