overview.md

@specd/core — Overview

@specd/core is the domain library for SpecD. It contains all business logic — entities, use cases, ports, and errors — with zero I/O dependencies. The CLI, MCP server, and plugins are adapters that translate between their delivery mechanism and the core.

Who this documentation is for

docs/core/ is the plugin and @specd/core package reference — domain model, ports, composition factories, and use-case semantics.

Delivery hosts (CLI, MCP, API) should use @specd/sdk as the single import; see the SDK docs for bootstrap and orchestration.

If you are using the specd CLI or MCP server as an end user, you do not need to read these documents — the configuration reference and schema format reference are the right starting points.

Architecture

@specd/core is organized in three layers. The dependency flow is strictly one-way: domain has no dependencies, application depends on domain, infrastructure depends on application and domain.

┌──────────────────────────────────────────┐
│               domain/                    │
│  Entities · Value objects · Errors       │
│  No I/O. No external dependencies.       │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│             application/                 │
│  Use cases · Ports (interfaces)          │
│  Depends on domain only.                 │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│           infrastructure/                │
│  Fs adapters · Git · Hooks               │
│  Internal. Never imported directly.      │
└──────────────────┬───────────────────────┘
                   │
┌──────────────────▼───────────────────────┐
│            composition/                  │
│  Factory functions for adapter creation  │
│  Exported. Returns abstract port types.  │
└──────────────────────────────────────────┘

The infrastructure/ layer is internal — never import from it directly. Infrastructure adapters are created exclusively through the factory functions in composition/, which is the only layer permitted to instantiate them. Public use-case factories accept either explicit dependencies (createX(deps)) or a resolved SpecdConfig plus optional additive registrations (createX(config, options?)), while lower-level repository factories still accept adapter-specific configuration.

Public exports

@specd/core exports from a single entry point:

import { ... } from '@specd/core'       // domain + application + composition

Everything exported is a domain type (entity, value object, error, service), an application type (use case, port interface, error, config type), or a composition factory / adapter class.

What is exported

From the domain layer — entities:

Export	Kind	Description
Change	class	The central entity representing an in-progress spec change.
Spec	class	Metadata for a spec directory.
ChangeArtifact	class	A single artifact file tracked within a change.
ArchivedChange	class	An immutable historical record of a completed change.
Delta	class	A delta file record.
SYSTEM_ACTOR	const	The built-in system actor identity used by automated operations.

From the domain layer — value objects:

Export	Kind	Description
SpecPath	class	Validated, immutable spec path value object.
ArtifactType	class	Describes a single artifact type as declared in the schema.
Schema	class	A fully-constructed schema with artifacts, workflow, and extraction.
ArtifactFile	class	A spec-scoped artifact file record.
SpecArtifact	class	A spec-scoped artifact record with metadata.
HookResult	class	The outcome of a run: hook execution.
ChangeState	type	Union of all valid lifecycle state strings.
ArtifactStatus	type	'missing' | 'in-progress' | 'complete' | 'skipped'
ArtifactScope	type	'spec' | 'change' — whether an artifact lives on the spec or change.
ArtifactFormat	type	'markdown' | 'json' | 'yaml' | 'plaintext'
ActorIdentity	interface	{ name: string; email: string } — actor identity.
ChangeEvent	type	Discriminated union of all change history event types.
WorkflowStep	type	A single step entry in the schema workflow. Includes requiresTaskCompletion.
HookEntry	type	A single hook declaration within a workflow step.
ValidationRule	type	A structural validation rule from the schema.
PreHashCleanup	type	A pre-hash substitution rule from the schema.
TaskCompletionCheck	type	Pattern-based task completion check from the schema.
Selector	type	An AST node selector used in validations and extractors.
Extractor	type	An extraction configuration for metadata derivation.
MetadataExtraction	type	The full metadata extraction block from a schema.
VALID_TRANSITIONS	const	Map of valid transitions per lifecycle state.
isValidTransition	function	Returns whether a state transition is permitted.

From the domain layer — errors:

Export	Code
SpecdError	abstract base class
InvalidStateTransitionError	INVALID_STATE_TRANSITION
ApprovalRequiredError	APPROVAL_REQUIRED
HookFailedError	HOOK_FAILED
ArtifactConflictError	ARTIFACT_CONFLICT
DeltaApplicationError	DELTA_APPLICATION
InvalidSpecPathError	INVALID_SPEC_PATH
InvalidChangeError	INVALID_CHANGE
ArtifactNotOptionalError	ARTIFACT_NOT_OPTIONAL
SchemaValidationError	SCHEMA_VALIDATION_ERROR
ConfigValidationError	CONFIG_VALIDATION_ERROR
CorruptedManifestError	CORRUPTED_MANIFEST
MetadataValidationError	METADATA_VALIDATION_ERROR
DependsOnOverwriteError	DEPENDS_ON_OVERWRITE
HookNotFoundError	HOOK_NOT_FOUND
StepNotValidError	STEP_NOT_VALID
PathTraversalError	PATH_TRAVERSAL
UnsupportedPatternError	UNSUPPORTED_PATTERN_ERROR
MissingDefaultWorkspaceError	MISSING_DEFAULT_WORKSPACE
ArtifactParseError	ARTIFACT_PARSE_ERROR

From the domain layer — services:

Export	Kind	Description
hashFiles	function	Applies a hash function to each entry in a file-content map.
applyPreHashCleanup	function	Applies schema-declared pre-hash substitutions to artifact content.
buildSchema	function	Constructs a typed Schema from validated YAML data and templates.
buildSelector	function	Converts a raw selector shape into the domain Selector type.
mergeSchemaLayers	function	Applies ordered customisation layers to a base schema's intermediate data.
parseSpecId	function	Splits a spec ID into workspace and capability path.
extractSpecSummary	function	Extracts a short summary from spec.md content.
extractMetadata	function	Async metadata extraction orchestration across multiple artifact ASTs.
extractContent	function	Async extractor runtime for one AST root (supports promise transforms).
evaluateRules	function	Evaluates validation rules against an AST, returning failures/warnings.
findNodes	function	Finds all nodes matching a selector in an AST.
nodeMatches	function	Tests whether a single AST node matches a selector.
selectBySelector	function	Selects nodes using a selector with parent-scope and index support.
collectAllNodes	function	Recursively collects all nodes in an AST.
safeRegex	function	Compiles a user-supplied pattern, returning null if invalid or unsafe.
inferFormat	function	Infers artifact format from a filename extension.
shiftHeadings	function	Shifts Markdown heading levels by a given delta.
selectByJsonPath	function	Navigates an AST using a simplified JSONPath expression.
tokenizeJsonPath	function	Tokenises a JSONPath expression into segments.
specMetadataSchema	const	Lenient Zod schema for reading metadata.json.
strictSpecMetadataSchema	const	Strict Zod schema for writing metadata.json.

From the application layer — ports:

Export	Kind	Description
Repository	abstract class	Base class for all repository ports.
SpecRepository	abstract class	Port for reading and writing specs.
ChangeRepository	abstract class	Port for snapshot reads and serialized persisted change mutations.
ArchiveRepository	abstract class	Port for archiving and querying archived changes.
ContentHasher	abstract class	Port for computing content hashes.
YamlSerializer	abstract class	Port for serialising and deserialising YAML.
SchemaRegistry	interface	Port for discovering and resolving schemas.
HookRunner	interface	Port for executing built-in run: hook commands.
ExternalHookRunner	interface	Port for dispatching explicit external: workflow hooks by type.
ActorResolver	interface	Port for resolving the current actor identity.
VcsAdapter	interface	Port for querying version control system state.
FileReader	interface	Port for reading files by absolute path.
ArtifactParser	interface	Port for parsing, applying deltas, and serialising artifacts.
ArtifactParserRegistry	type	ReadonlyMap<string, ArtifactParser>
SchemaProvider	interface	Port for lazily resolving the active schema.
ConfigLoader	interface	Port for loading and resolving specd.yaml.
ConfigWriter	interface	Port for writing project configuration.

From the application layer — use cases:

Export	Kind	Description
CreateChange	type	Creates a new change.
GetStatus	type	Reports change state and artifact statuses.
TransitionChange	type	Advances the change lifecycle and serializes the final manifest mutation.
DraftChange	type	Shelves a change to drafts/ via serialized persistence.
RestoreChange	type	Recovers a drafted change via serialized persistence.
DiscardChange	type	Permanently abandons a change via serialized persistence.
ApproveSpec	type	Records a spec approval through a serialized change mutation.
ApproveSignoff	type	Records a sign-off through a serialized change mutation.
ArchiveChange	type	Finalises and archives a completed change after serializing archiving.
ValidateArtifacts	type	Validates artifact files and serializes completion/invalidation.
CompileContext	type	Assembles the AI instruction block for a lifecycle step.
ListChanges	type	Lists all active changes.
ListDrafts	type	Lists all drafted changes.
ListDiscarded	type	Lists all discarded changes.
ListArchived	type	Lists all archived changes.
GetArchivedChange	type	Retrieves a single archived change.
EditChange	type	Edits change scope while serializing the persisted specIds update.
SkipArtifact	type	Explicitly skips an optional artifact on a change.
UpdateSpecDeps	type	Updates declared spec dependencies within a change.
ListSpecs	type	Lists all specs across all configured workspaces.
GetSpec	type	Loads a spec and its artifact files.
SaveSpecMetadata	type	Writes validated metadata for a spec.
InvalidateSpecMetadata	type	Removes content hashes from a spec's metadata.
GetActiveSchema	type	Resolves and returns the active schema.
ValidateSchema	type	Validates a schema against structural rules.
ValidateSpecs	type	Validates spec artifacts against schema structural rules.
GenerateSpecMetadata	type	Generates deterministic metadata from schema extraction rules.
GetSpecContext	type	Builds structured context entries for a spec.
RunStepHooks	type	Executes built-in run: hooks and explicit external: hooks for a workflow step and phase.
GetHookInstructions	type	Returns instruction: hook text for a workflow step and phase.
GetArtifactInstruction	type	Returns artifact-specific instructions, rules, and delta guidance.
GetProjectContext	type	Compiles project-level context without a specific change or step.
GetProjectSummary	type	Returns consolidated project-level change and spec counts without loading entities.

From the application layer — config types:

Export	Kind	Description
SpecdConfig	type	The fully-resolved project configuration structure.
SpecdWorkspaceConfig	type	Per-workspace configuration within SpecdConfig.
SpecdStorageConfig	type	Storage (paths) configuration within SpecdConfig.
SpecdContextEntry	type	A single entry in the project context block.
isSpecdConfig	function	Type guard for SpecdConfig.
TemplateExpander	class	Expands template variables in hook commands and instructions.

From the application layer — errors:

Export	Code
ChangeNotFoundError	CHANGE_NOT_FOUND
ChangeAlreadyExistsError	CHANGE_ALREADY_EXISTS
ApprovalGateDisabledError	APPROVAL_GATE_DISABLED
SchemaNotFoundError	SCHEMA_NOT_FOUND
AlreadyInitialisedError	ALREADY_INITIALISED
ArtifactNotFoundError	ARTIFACT_NOT_FOUND
ParserNotRegisteredError	PARSER_NOT_REGISTERED
SpecNotInChangeError	SPEC_NOT_IN_CHANGE
SchemaMismatchError	SCHEMA_MISMATCH
SpecNotFoundError	SPEC_NOT_FOUND
WorkspaceNotFoundError	WORKSPACE_NOT_FOUND

From the composition layer — kernel:

Export	Kind	Description
createKernel	function	Constructs all use cases from a SpecdConfig and returns them as a grouped Kernel.
Kernel	interface	The fully-wired set of use cases, grouped as kernel.changes.*, kernel.specs.*, kernel.project.*.
KernelOptions	interface	Options for createKernel, including extra node_modules paths for schema discovery.

createKernelBuilder and KernelBuilder are exported from @specd/core/extensions, not from the root @specd/core barrel.

From the composition layer — repository and schema factories:

Export	Kind	Description
createSchemaRegistry	function	Constructs a SchemaRegistry for the given adapter type ('fs').
createSchemaRepository	function	Constructs a SchemaRepository for the given adapter type.
createConfigLoader	function	Creates a filesystem-backed ConfigLoader that discovers and parses specd.yaml.
SpecStorageFactory	interface	Named storage factory for workspace specs repositories.
SchemaStorageFactory	interface	Named storage factory for workspace schema repositories.
ChangeStorageFactory	interface	Named storage factory for active and shelved changes.
ArchiveStorageFactory	interface	Named storage factory for archived changes.
VcsProvider	interface	External-first VCS detection provider used by the composition registry layer.
ActorProvider	interface	External-first actor detection provider used by the composition registry layer.

From the composition layer — VCS and actor adapters:

Export	Kind	Description
createVcsAdapter	function	Auto-detects the active VCS (git/hg/svn/null) and returns a VcsAdapter.
createVcsActorResolver	function	Auto-detects the active VCS and returns an ActorResolver.
NodeContentHasher	class	ContentHasher implementation using Node.js crypto (SHA-256).

From the composition layer — use case creator functions:

These functions expose the canonical standalone composition contract:

• createX(deps) for fully explicit dependency injection
• createX(config, options?) for convenience bootstrap through the shared composition resolver

Use them when you need only one or two use cases without constructing a full Kernel.

Export	Description
createCreateChange	Wires CreateChange from explicit deps or from SpecdConfig.
createGetStatus	Wires GetStatus from explicit deps or from SpecdConfig.
createTransitionChange	Wires TransitionChange from explicit deps or from SpecdConfig.
createDraftChange	Wires DraftChange from explicit deps or from SpecdConfig.
createRestoreChange	Wires RestoreChange from explicit deps or from SpecdConfig.
createDiscardChange	Wires DiscardChange from explicit deps or from SpecdConfig.
createApproveSpec	Wires ApproveSpec from explicit deps or from SpecdConfig.
createApproveSignoff	Wires ApproveSignoff from explicit deps or from SpecdConfig.
createArchiveChange	Wires ArchiveChange from explicit deps or from SpecdConfig.
createValidateArtifacts	Wires ValidateArtifacts from explicit deps or from SpecdConfig.
createCompileContext	Wires CompileContext from explicit deps or from SpecdConfig.
createListChanges	Wires ListChanges from explicit deps or from SpecdConfig.
createListDrafts	Wires ListDrafts from explicit deps or from SpecdConfig.
createListDiscarded	Wires ListDiscarded from explicit deps or from SpecdConfig.
createListArchived	Wires ListArchived from explicit deps or from SpecdConfig.
createGetArchivedChange	Wires GetArchivedChange from explicit deps or from SpecdConfig.
createEditChange	Wires EditChange from explicit deps or from SpecdConfig.
createSkipArtifact	Wires SkipArtifact from explicit deps or from SpecdConfig.
createListSpecs	Wires ListSpecs from explicit deps or from SpecdConfig.
createGetSpec	Wires GetSpec from explicit deps or from SpecdConfig.
createSaveSpecMetadata	Wires SaveSpecMetadata from explicit deps or from SpecdConfig.
createInvalidateSpecMetadata	Wires InvalidateSpecMetadata from explicit deps or from SpecdConfig.
createGetActiveSchema	Wires GetActiveSchema from explicit deps or from SpecdConfig.
createValidateSpecs	Wires ValidateSpecs to the fs.
createGetSpecContext	Wires GetSpecContext to the fs.
createConfigWriter	Filesystem-backed ConfigWriter for yaml mutations.
createGetProjectContext	Wires GetProjectContext to the fs.
createGetProjectSummary	Wires GetProjectSummary to the fs.

Where to go next

Document	Read when you need to…
domain-model.md	Understand the entities and value objects you receive as return values.
ports.md	Implement a repository, schema registry, or other port.
use-cases.md	Wire and call use cases from your adapter.
errors.md	Handle errors from use cases and ports in your delivery layer.
services.md	Use domain service functions such as hashFiles and buildSchema.
examples/implementing-a-port.md	See a full port implementation from scratch.