Skip to main content

Abstract Class: ArchiveRepository

Defined in: packages/core/src/application/ports/archive-repository.ts:18

Port for archiving and querying archived changes within a single workspace.

Extends Repository — workspace(), ownership(), and isExternal() are set at construction time. The archive is append-only: once a change is archived it is never mutated. An index.jsonl file at the archive root provides O(1) appends and fast lookup without scanning the filesystem.

Implementations receive both the changes path and the archive path in their configuration so they can physically move the change directory during archive().

Extends​

Constructors​

Constructor​

new ArchiveRepository(config): ArchiveRepository

Defined in: packages/core/src/application/ports/archive-repository.ts:24

Creates a new ArchiveRepository instance.

Parameters​

config​

RepositoryConfig

Workspace, ownership, and locality configuration

Returns​

ArchiveRepository

Overrides​

Repository.constructor

Methods​

archive()​

abstract archive(change, options?): Promise<{ archivedChange: ArchivedChange; archiveDirPath: string; }>

Defined in: packages/core/src/application/ports/archive-repository.ts:52

Moves the change directory to the archive, creates the ArchivedChange record, persists its manifest, and appends an entry to index.jsonl.

As a safety guard, the repository verifies that the change is in archivable state before proceeding. This check is intentionally redundant — the ArchiveChange use case performs the same validation first. The guard exists to prevent accidental archival if the repository is called directly without going through the use case.

Pass { force: true } to bypass the state check (e.g. for recovery or administrative operations).

The destination path is computed from the archive pattern configured at construction time (e.g. {{year}}/{{change.archivedName}}). The source path is resolved from the change name using the changes path configuration.

Parameters​

change​

Change

The change to archive

options?​

Archive options

actor?​

ActorIdentity

Git identity of the actor performing the archive, recorded in the manifest

force?​

boolean

When true, skip the state check and archive unconditionally

Returns​

Promise<{ archivedChange: ArchivedChange; archiveDirPath: string; }>

The created ArchivedChange record

Throws​

When the change is not in archivable state and force is not set

archivePath()​

abstract archivePath(archivedChange): string

Defined in: packages/core/src/application/ports/archive-repository.ts:97

Returns the absolute filesystem path for an archived change's directory.

Mirrors ChangeRepository.changePath for active changes.

Parameters​

archivedChange​

ArchivedChange

The archived change to resolve the path for

Returns​

string

The absolute path to the archived change's directory

get()​

abstract get(name): Promise<ArchivedChange | null>

Defined in: packages/core/src/application/ports/archive-repository.ts:77

Returns the archived change with the given name, or null if not found.

Searches index.jsonl from the end (most recent entries first). If not found in the index, falls back to a glob scan of the archive directory and appends the recovered entry to index.jsonl for future lookups.

Parameters​

name​

string

The change name to look up (e.g. "add-oauth-login")

Returns​

Promise<ArchivedChange | null>

The archived change, or null if not found

isExternal()​

isExternal(): boolean

Defined in: packages/core/src/application/ports/repository.ts:71

Returns whether this repository points to data outside the current git repository.

Returns​

boolean

true if this repository is external to the current git root

Inherited from​

Repository.isExternal

list()​

abstract list(): Promise<ArchivedChange[]>

Defined in: packages/core/src/application/ports/archive-repository.ts:65

Lists all archived changes in this workspace in chronological order (oldest first).

Streams index.jsonl from the start, deduplicating by name so that the last entry wins in case of duplicates introduced by manual recovery.

Returns​

Promise<ArchivedChange[]>

All archived changes, oldest first

ownership()​

ownership(): "owned" | "shared" | "readOnly"

Defined in: packages/core/src/application/ports/repository.ts:62

Returns the ownership level of this repository, as declared in specd.yaml.

Returns​

"owned" | "shared" | "readOnly"

The ownership level

Inherited from​

Repository.ownership

reindex()​

abstract reindex(): Promise<void>

Defined in: packages/core/src/application/ports/archive-repository.ts:87

Rebuilds index.jsonl by scanning the archive directory for all manifest.json files, sorting by archivedAt, and writing a clean index in chronological order.

Use this to recover from a corrupted or missing index. The resulting git diff shows only missing or spurious lines — no reorderings.

Returns​

Promise<void>

workspace()​

workspace(): string

Defined in: packages/core/src/application/ports/repository.ts:53

Returns the workspace name this repository is bound to.

Returns​

string

The workspace name (e.g. "billing", "default")

Inherited from​

Repository.workspace