Glossary

This page defines the terms used across the current API docs and the longer-term implementation plan. The plan includes future concepts; the definitions here distinguish the current meaning from planned extensions.

Catalog : An on-disk collection of catalog configuration, repository state, managed artifacts, and records. Today this is a local directory backed by TinyDB.

Record : The catalog entry describing one catalogued item. In the current API this is a CatalogRecord with top-level fields, a locator, user metadata, derived metadata, and naming metadata.

Artifact : The file, directory, URI, or opaque external reference being catalogued. The current data model stores one primary locator per record; the long-term plan discusses multiple artifact descriptors per record.

Locator : A serialisable description of where an artifact lives. Current locator kinds include path-backed, URI-backed, and opaque references.

Managed file : A local artifact copied or moved into the catalog-managed files area by Catalog.add_file.

Reference record : A record added with Catalog.add_artifact whose artifact may be external, already materialised, written by an artifact writer, or represented by an opaque locator.

Metadata : JSON-compatible descriptive data attached to records. user_metadata comes from callers, derived_metadata comes from hooks or writers, and naming_metadata is used for storage template rendering.

Schema : A RecordSchema describing expected metadata fields and optional storage naming templates for a record type. Schema validation is intentionally permissive unless fields are marked required or strict validation is used.

Hook : A structural protocol method implemented by a plugin object and dispatched by HookManager during catalog operations.

Plugin : A group of hooks or related extension objects registered with a catalog, usually through PluginRegistry.

Operation context : The mutable OperationContext object passed to hooks and artifact writers. It carries source information, planned locators, metadata, warnings, and the rollback registrar for the active operation.

Artifact writer : Any object satisfying the ArtifactWriter protocol. Writers materialise artifact data from an OperationSource into a target ArtifactLocator.

Operation source : The OperationSource description passed to artifact writers. It can carry a local path, non-path descriptor, source metadata, or in-memory payload.

Unit of work : The current best-effort transaction helper. It stages catalog changes, registers rollback actions, commits on success, and runs cleanup callbacks on failure. It is not an ACID database transaction.

Journal : A planned durable record of operation state transitions. The current implementation has rollback actions, but not yet a durable operation journal.

Event log : A planned catalog-level structured log for operation debugging and audit trails. This is distinct from the future journal, which tracks recoverable operation state.

Storage profile : A planned named configuration for resolving non-local storage adapters and credentials without storing secrets in records.