Skip to main content

Class: SpecArtifact

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:22

An artifact file within a spec directory or a change directory.

Holds the filename, raw file content, and an optional originalHash that acts as a version token for optimistic concurrency control.

Lifecycle of originalHash:

  • When a repository loads an artifact from storage, it computes sha256(content) and passes it as originalHash.
  • When a use case produces a derived artifact, it propagates the originalHash from the source artifact so the token survives the transformation.
  • When a repository saves a derived artifact, it re-hashes the current file on disk and compares against originalHash. If they differ, the file was modified between load and save — the write is rejected to prevent silently discarding concurrent changes (e.g. those made by an LLM agent writing to the same file).
  • originalHash is undefined for artifacts that were never read from storage (e.g. scaffolded for the first time). In that case the repository performs no conflict check.

Constructors​

Constructor​

new SpecArtifact(filename, content, originalHash?): SpecArtifact

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:37

Creates a new SpecArtifact.

Parameters​

filename​

string

The artifact filename (e.g. "spec.md", "proposal.md")

content​

string

The raw file content

originalHash?​

string

The sha256:<hex> hash of the content as it existed in storage when this artifact was loaded. Pass undefined for artifacts that have no prior storage representation (first write / scaffold).

Returns​

SpecArtifact

Accessors​

content​

Get Signature​

get content(): string

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:49

The raw file content of the artifact.

Returns​

string

filename​

Get Signature​

get filename(): string

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:44

The artifact filename (e.g. "spec.md").

Returns​

string

originalHash​

Get Signature​

get originalHash(): string | undefined

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:64

The sha256:<hex> hash of the content as it existed in storage when this artifact was loaded, or undefined if the artifact has no prior storage representation.

Used by repository implementations to detect concurrent modifications: before writing, the repository hashes the current file on disk and compares against this value. A mismatch means another writer (e.g. an LLM agent) modified the file after this artifact was loaded, and the save should be rejected to avoid a lost update.

Returns​

string | undefined

Methods​

section()​

section(name): string | null

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:132

Returns the body of a single section by name, or null if not present.

Parameters​

name​

string

The section heading text (without the ## prefix)

Returns​

string | null

The trimmed section body, or null if the section does not exist

sections()​

sections(): Map<string, string>

Defined in: packages/core/src/domain/value-objects/spec-artifact.ts:76

Parses the content into a map of ## Section Name → section body.

Only level-2 headings (##) are treated as section delimiters. The body of each section is trimmed of leading/trailing whitespace.

Returns​

Map<string, string>

A Map from section name to trimmed section content