Taking Over the Record Layer: Provider

Provider is the abstract root of the storage hierarchy. Extend it directly — rather than ContainerProvider — only when your store already owns its encryption or record model and should keep owning it end to end: a database with column-level encryption, a secrets manager, a store that frames records its own way. In exchange for that control you implement the container session and the whole Record API yourself, including the crypto.

What you implement

Beyond the six storage primitives (_exist, _listItems, _read, _write, _remove, _ensureDir), a Provider subclass supplies the container session and the record API:

Provider also ships a default initialize() that writes the four root records (CONFIG, NETWORK, ASSET, LOG) from bundled templates via your writeRecord — idempotent, so existing records are left untouched. Override it only if your backend needs non-record setup (allocating a schema, say).

RecordType

The five record kinds a container holds:

type RecordType = "CONFIG" | "ACCOUNTS" | "NETWORK" | "ASSET" | "LOG";

CONFIG, NETWORK, ASSET and LOG are singletons (one record each); ACCOUNTS is a namespace of one record per account, addressed by slug (a branded string). The singletons ignore the slug argument.

Records and RecordInit

loadRecord hands back a Record<T> handle. You construct one with an optional RecordInit<T>; the fields you provide decide what the handle can do:

A Record<T> exposes readonly slug and readonly path, a get locked boolean, a get value (throws WativeError with code === "RECORD_LOCKED" while locked), an unlock(password): this credential check, and save(): Promise<void>.

Absent vs. unreadable — the load obligations

The account layer reads presence through your methods, so the difference between "not there" and "there but unreadable" is a contract, not a detail:

Name-collision hooks

Three members guard the account namespace against a second handle clobbering a record it cannot see. They have working defaults on Provider, so override them only when your store needs a more precise answer:

ContainerState and create-vs-open

Workspace.open() calls inspectContainer(): Promise<ContainerState> before unlocking to choose create-vs-open. Provider's default returns "workspace" — the never-refuse answer — so a minimal subclass always proceeds as open-or-create. Override it to return "empty" (safe to initialize) or "foreign" (non-empty, not a wative container — open() refuses) when your store can inspect itself cheaply.

type ContainerState = "empty" | "workspace" | "foreign";

A full custom backend

Example 07 in the release consumer suite implements a complete Provider against an in-memory Map, with its own cipher standing in for a store that brings its own encryption:

import { Workspace, Provider, Record, WativeError } from "wative-core";

class InMemoryProvider extends Provider {
  #store = new Map();
  #password = null;

  // …six storage primitives ( _exist / _read / _write / _remove /
  //    _ensureDir / _listItems ) over #store…

  async unlockContainer(password) {
    if (typeof password !== "string" || password.length === 0) return false;
    // verify against the CONFIG record, then:
    this.#password = password;
    return true;
  }
  async lockContainer() { this.#password = null; }
  isContainerUnlocked() { return this.#password !== null; }

  async loadRecord(type, slug) {
    if (this.#password === null) throw new WativeError("PROVIDER_IO", "container locked");
    const path = this.#pathFor(type, slug);
    if (!this.#store.has(path)) throw new WativeError("RECORD_NOT_FOUND", path);
    const encrypted = this.#store.get(path);
    const value = JSON.parse(new TextDecoder().decode(this.#decrypt(encrypted, this.#password)));
    return new Record(slug, path, {
      provider: this,
      recordType: type,
      encrypted,
      value,
      password: this.#password,
      decrypt: (ct, pwd) => this.#decrypt(ct, pwd),
      persist: async (val, pwd) => { this.#store.set(path, this.#encrypt(JSON.stringify(val), pwd)); },
    });
  }

  async writeRecord(type, slug, value) {
    if (this.#password === null) throw new WativeError("PROVIDER_IO", "container locked");
    this.#store.set(this.#pathFor(type, slug), this.#encrypt(JSON.stringify(value), this.#password));
  }
  async dropRecord(type, slug) { this.#store.delete(this.#pathFor(type, slug)); }
  async close() { this.#password = null; }
}

const provider = new InMemoryProvider("memory://desk-1");
const ws = await Workspace.open({ provider, password: "wsp-pwd" });