Skip to main content

Class: Change

Defined in: packages/core/src/domain/entities/change.ts:171

The central domain entity representing an in-progress spec change.

Lifecycle state is derived entirely from the history — the to field of the most recent transitioned event. No state snapshot is stored.

Every significant operation appends one or more events to history. Events are never modified or removed.

Constructors​

Constructor​

new Change(props): Change

Defined in: packages/core/src/domain/entities/change.ts:185

Creates a new Change from the given properties.

Parameters​

props​

ChangeProps

Change construction properties

Returns​

Change

Accessors​

activeSignoff​

Get Signature​

get activeSignoff(): SignedOffEvent | undefined

Defined in: packages/core/src/domain/entities/change.ts:293

The active signoff — the most recent signed-off event that has not been superseded by a subsequent invalidated event, or undefined.

Returns​

SignedOffEvent | undefined

activeSpecApproval​

Get Signature​

get activeSpecApproval(): SpecApprovedEvent | undefined

Defined in: packages/core/src/domain/entities/change.ts:280

The active spec approval — the most recent spec-approved event that has not been superseded by a subsequent invalidated event, or undefined.

Returns​

SpecApprovedEvent | undefined

artifacts​

Get Signature​

get artifacts(): ReadonlyMap<string, ChangeArtifact>

Defined in: packages/core/src/domain/entities/change.ts:303

All artifacts currently attached to this change, keyed by type.

Returns​

ReadonlyMap<string, ChangeArtifact>

createdAt​

Get Signature​

get createdAt(): Date

Defined in: packages/core/src/domain/entities/change.ts:212

Timestamp when the change was created.

Returns​

Date

description​

Get Signature​

get description(): string | undefined

Defined in: packages/core/src/domain/entities/change.ts:217

Optional free-text description of the change's purpose.

Returns​

string | undefined

history​

Get Signature​

get history(): readonly ChangeEvent[]

Defined in: packages/core/src/domain/entities/change.ts:246

Read-only view of the append-only event history.

Returns​

readonly ChangeEvent[]

isArchivable​

Get Signature​

get isArchivable(): boolean

Defined in: packages/core/src/domain/entities/change.ts:340

Whether this change is in archivable or archiving state and may be archived.

Returns​

boolean

isDrafted​

Get Signature​

get isDrafted(): boolean

Defined in: packages/core/src/domain/entities/change.ts:266

Whether the change is currently shelved in drafts/. Derived from the most recent drafted or restored event.

Returns​

boolean

name​

Get Signature​

get name(): string

Defined in: packages/core/src/domain/entities/change.ts:207

Unique slug name identifying this change.

Returns​

string

schemaName​

Get Signature​

get schemaName(): string

Defined in: packages/core/src/domain/entities/change.ts:222

Schema name recorded at creation time, derived from the created history event.

Returns​

string

schemaVersion​

Get Signature​

get schemaVersion(): number

Defined in: packages/core/src/domain/entities/change.ts:227

Schema version recorded at creation time, derived from the created history event.

Returns​

number

specDependsOn​

Get Signature​

get specDependsOn(): ReadonlyMap<string, readonly string[]>

Defined in: packages/core/src/domain/entities/change.ts:313

Per-spec declared dependencies, keyed by spec ID.

Used by CompileContext as the highest-priority source for dependsOn resolution. Not subject to approval invalidation.

Returns​

ReadonlyMap<string, readonly string[]>

specIds​

Get Signature​

get specIds(): readonly string[]

Defined in: packages/core/src/domain/entities/change.ts:241

Current snapshot of spec paths being created or modified.

Returns​

readonly string[]

state​

Get Signature​

get state(): ChangeState

Defined in: packages/core/src/domain/entities/change.ts:254

The current lifecycle state, derived from the most recent transitioned event's to field. Returns 'drafting' if no transitioned event exists.

Returns​

ChangeState

workspaces​

Get Signature​

get workspaces(): readonly string[]

Defined in: packages/core/src/domain/entities/change.ts:232

Workspace IDs derived from specIds at runtime.

Returns​

readonly string[]

Methods​

assertArchivable()​

assertArchivable(): void

Defined in: packages/core/src/domain/entities/change.ts:564

Asserts that this change is in archivable state.

Returns​

void

Throws​

If the change is not in archivable state

discard()​

discard(reason, actor, supersededBy?): void

Defined in: packages/core/src/domain/entities/change.ts:525

Permanently abandons the change, appending a discarded event.

Parameters​

reason​

string

Mandatory explanation for discarding

actor​

ActorIdentity

Identity of the person discarding the change

supersededBy?​

readonly string[]

Optional list of change names that replace this one

Returns​

void

draft()​

draft(actor, reason?): void

Defined in: packages/core/src/domain/entities/change.ts:501

Shelves this change to drafts/, appending a drafted event.

Parameters​

actor​

ActorIdentity

Identity of the person shelving the change

reason?​

string

Optional explanation for shelving

Returns​

void

effectiveStatus()​

effectiveStatus(type): ArtifactStatus

Defined in: packages/core/src/domain/entities/change.ts:358

Computes the effective artifact status for type, cascading through the dependency graph to reflect blocking dependencies.

An artifact whose own hash matches its validatedHash is still reported as in-progress if any artifact in its requires chain is neither complete nor skipped.

Includes cycle detection to prevent infinite recursion on circular artifact dependencies.

Parameters​

type​

string

The artifact type ID to evaluate

Returns​

ArtifactStatus

The effective ArtifactStatus after dependency resolution

getArtifact()​

getArtifact(type): ChangeArtifact | null

Defined in: packages/core/src/domain/entities/change.ts:703

Returns the artifact of the given type, or null if not present.

Parameters​

type​

string

The artifact type ID to look up

Returns​

ChangeArtifact | null

The artifact, or null if not found

invalidate()​

invalidate(cause, actor, message?, affectedArtifacts?): void

Defined in: packages/core/src/domain/entities/change.ts:415

Records an invalidation, appending an invalidated event followed by a transitioned event rolling back to designing.

Called when specIds or artifact content changes and supersedes any active spec approval or signoff.

Parameters​

cause​

"spec-change" | "artifact-drift" | "artifact-review-required"

The reason for invalidation

actor​

ActorIdentity

Identity of the actor triggering the change

message?​

string = 'Invalidated because artifacts require review.'

Human-readable invalidation summary

affectedArtifacts?​

readonly InvalidatedArtifactEntry[] = ...

Artifact/file payload that triggered the invalidation

Returns​

void

recordArtifactSkipped()​

recordArtifactSkipped(artifactId, actor, reason?): void

Defined in: packages/core/src/domain/entities/change.ts:487

Records that an optional artifact was explicitly skipped.

Parameters​

artifactId​

string

The artifact type ID that was skipped

actor​

ActorIdentity

Identity of the actor skipping the artifact

reason?​

string

Optional explanation for skipping

Returns​

void

recordSignoff()​

recordSignoff(reason, artifactHashes, actor): void

Defined in: packages/core/src/domain/entities/change.ts:472

Records that the signoff gate has been passed.

Parameters​

reason​

string

Free-text rationale for the sign-off

artifactHashes​

Record<string, string>

Hashes of the artifacts reviewed during sign-off

actor​

ActorIdentity

Identity of the approver

Returns​

void

recordSpecApproval()​

recordSpecApproval(reason, artifactHashes, actor): void

Defined in: packages/core/src/domain/entities/change.ts:457

Records that the spec approval gate has been passed.

Parameters​

reason​

string

Free-text rationale for the approval

artifactHashes​

Record<string, string>

Hashes of the artifacts reviewed during approval

actor​

ActorIdentity

Identity of the approver

Returns​

void

removeSpecDependsOn()​

removeSpecDependsOn(specId): void

Defined in: packages/core/src/domain/entities/change.ts:335

Removes the declared dependencies entry for a single spec.

Parameters​

specId​

string

The spec whose dependencies to remove

Returns​

void

restore()​

restore(actor): void

Defined in: packages/core/src/domain/entities/change.ts:514

Recovers a drafted change back to changes/, appending a restored event.

Parameters​

actor​

ActorIdentity

Identity of the person restoring the change

Returns​

void

setArtifact()​

setArtifact(artifact): void

Defined in: packages/core/src/domain/entities/change.ts:693

Adds or replaces an artifact on this change, keyed by its type.

Parameters​

artifact​

ChangeArtifact

The artifact to attach

Returns​

void

setSpecDependsOn()​

setSpecDependsOn(specId, deps): void

Defined in: packages/core/src/domain/entities/change.ts:326

Sets (replaces) the declared dependencies for a single spec.

Does not trigger invalidation — specDependsOn is advisory, not spec content.

Parameters​

specId​

string

The spec whose dependencies to set

deps​

readonly string[]

The new dependency list

Returns​

void

syncArtifacts()​

syncArtifacts(artifactTypes): boolean

Defined in: packages/core/src/domain/entities/change.ts:593

Synchronises the artifact map against the current schema artifact types and spec IDs.

For each artifact type:

  • Creates the ChangeArtifact if missing
  • For scope: 'change': ensures one ArtifactFile keyed by the type id, filename = basename from artifactType.output
  • For scope: 'spec': ensures one ArtifactFile per specId, filename = basename from artifactType.output
  • Removes files for specIds no longer in the change
  • Removes artifacts for types no longer in the schema
  • Preserves existing validatedHash and state for surviving entries

If the sync produces any changes, an artifacts-synced event is appended to the history.

Pure method with no I/O. Called by the repository layer on every get() and save() to keep the artifact map in sync with schema x specIds.

Parameters​

artifactTypes​

readonly ArtifactType[]

The resolved artifact types from the active schema

Returns​

boolean

true if any changes were made, false if the artifact map was already in sync

transition()​

transition(to, actor): void

Defined in: packages/core/src/domain/entities/change.ts:395

Attempts a lifecycle state transition, appending a transitioned event.

Parameters​

to​

ChangeState

The target state

actor​

ActorIdentity

Identity of the actor performing the transition

Returns​

void

Throws​

If the transition is not permitted

updateSpecIds()​

updateSpecIds(specIds, actor): void

Defined in: packages/core/src/domain/entities/change.ts:542

Updates the spec ID list and appends an invalidation.

Any modification to specIds always appends an invalidated event followed by a transitioned event rolling back to designing.

Parameters​

specIds​

readonly string[]

The new spec paths

actor​

ActorIdentity

Identity of the actor making the change

Returns​

void