sealkeep 0.9.0 → 0.11.0

package/dist/src/vault.d.ts

@@ -1,23 +1,41 @@
-import { type Recipient } from "../packages/vaultline-crypto/src/index.js";
+import { type Recipient } from "../packages/sealkeep-crypto/src/index.js";
 import { type ArchiveRecord, type ArchiveRecordV2, type VaultConfig } from "./types.js";
 import type { ProviderConfig } from "./control-plane.js";
+export declare function withoutArchiveRecordWarnings<T>(operation: () => Promise<T>): Promise<T>;
 /** Bumped when the adapter's preservation behaviour changes, recorded in every envelope. */
+export type RecordWriteOperations = {
+    /** Test seam for proving the durability boundary; production uses fsync(2). */
+    syncFile?: (path: string) => Promise<void>;
+    rename?: (from: string, to: string) => Promise<void>;
+    syncDirectory?: (path: string) => Promise<void>;
+};
 /**
  * Writes one archive record atomically.
  *
- * Written to a temporary file beside the target and renamed into place, so a
- * crash never leaves a half-written record that would strand an archive. This
- * lived as three byte-identical private copies in upload, migrate and
- * retention; a fourth was about to be added for the managed push path.
+ * The complete temporary file is fsynced before rename, then the archive
+ * directory is fsynced after rename. Atomic visibility alone is not enough for
+ * source reclaim: the purge journal must never become more durable than the
+ * record saying where the recoverable archive lives.
+ */
+export declare function writeRecord(root: string, record: ArchiveRecord, operations?: RecordWriteOperations): Promise<void>;
+/**
+ * Serialize a read/modify/write of one archive record across the daemon, CLI,
+ * dashboard and hooks. Atomic rename prevents torn JSON, but by itself it
+ * still lets two valid stale documents overwrite one another (for example an
+ * upload adding a remote copy while retention marks the source reclaimed).
  */
-export declare function writeRecord(root: string, record: ArchiveRecord): Promise<void>;
+export declare function mutateArchiveRecord(root: string, archiveId: string, change: (current: ArchiveRecord) => ArchiveRecord | Promise<ArchiveRecord>, options?: {
+    initial?: ArchiveRecord;
+}): Promise<ArchiveRecord>;
 export declare const ADAPTER_VERSION = "1";
 export declare const CONFIG_VERSION = 1;
 /**
- * ~/.sealkeep for new vaults; an existing ~/.Sealkeep keeps working forever —
- * the rebrand must never strand a vault that predates it.
+ * ~/.sealkeep for new vaults; an existing ~/.vaultline keeps working forever.
+ * A unique initialized vault named by owned integrations is the same vault a
+ * bare CLI/UI/MCP process must use. Multiple initialized candidates are never
+ * guessed between: explicit `--data-dir` is then required.
  */
-export declare const defaultDataDir: () => string;
+export declare const defaultDataDir: (home?: string, environment?: NodeJS.ProcessEnv) => string;
 /**
  * Reads and version-gates the vault config. A config written by a newer build is
  * refused rather than silently reinterpreted; migrations attach here when v2 lands.
@@ -34,7 +52,14 @@ export declare function vaultStatus(dataDir: string): Promise<{
         region?: string;
     } | undefined;
     archiveCount: number;
+    sessionCount: number;
     archivedBytes: number;
+    sealedBytes: number;
+    cloudArchiveCount: number;
+    incompleteChainCount: number;
+    blockedUploadCount: number;
+    pendingUploadCount: number;
+    pendingUploadBytes: number;
 }>;
 export declare function configureRemoteStorage(dataDir: string, remoteStorage: ProviderConfig): Promise<VaultConfig>;
 export declare function initialize(dataDir: string, providedPhrase?: string, opts?: {
@@ -57,7 +82,7 @@ export declare function initialize(dataDir: string, providedPhrase?: string, opt
  * 3 MB reports the 3 MB archive. Nothing is returned when the file was
  * rewritten, truncated, or has never been archived.
  */
-export declare function provenAppendOffset(archives: readonly ArchiveRecord[], sourcePath: string, currentBytes: number): Promise<{
+export declare function provenAppendOffset(archives: readonly ArchiveRecord[], sourcePath: string, currentBytes: number, onActivity?: (bytesRead: number) => void, signal?: AbortSignal, onYield?: () => void | Promise<void>): Promise<{
     archiveId: string;
     bytes: number;
 } | null>;
@@ -75,6 +100,9 @@ export type ArchiveDelta = {
 export type DeltaArchiveRecord = ArchiveRecordV2 & {
     delta: ArchiveDelta;
 };
+/** Bound replay work for an agent that appends forever. The next snapshot
+ * after this many physical links is sealed whole and becomes a new base. */
+export declare const MAX_DELTA_CHAIN_LINKS = 16;
 /**
  * The delta pointer on a record, when the record is a delta archive.
  *
@@ -86,26 +114,47 @@ export declare function deltaOf(record: ArchiveRecord): ArchiveDelta | null;
 export type ArchiveResult = ArchiveRecord & {
     deduplicated: boolean;
 };
-/**
- * Seals one transcript, reading and writing a chunk at a time.
- *
- * An existing archive is returned unchanged when the same source bytes are
- * archived again, so a duplicate lifecycle event costs a hash rather than an
- * archive.
- *
- * `hooks.delta` opts in to incremental sealing: when the newest archive of
- * this path is a *proven* prefix of the live file, only the appended range is
- * sealed and the record carries a `delta` pointer to its base. Off by default
- * so every existing caller keeps writing complete, standalone archives; the
- * queue worker turns it on, because re-sealing a growing session whole on
- * every snapshot is exactly how 4 GB of transcript became 40 GB of storage.
- */
 export declare function archiveFile(dataDir: string, sourcePath: string, rawPhrase: string, agent?: string, hooks?: {
     onProgress?: (bytesRead: number) => void;
+    /** Internal liveness signal while validating a prior snapshot; unlike onProgress it does not describe bytes being sealed. */
+    onActivity?: (bytesRead: number) => void;
+    /** Cancels lock waiting, hashing, compression, and the unpublished partial. */
+    signal?: AbortSignal;
+    /** Internal cooperative scheduler used by unattended/background sealing. */
+    onYield?: () => void | Promise<void>;
     delta?: boolean;
     chunkBytes?: number;
     /** Which project this session belongs to — decides which members are wrapped in. */
     project?: string | null;
+    /** Stable identity for access decisions. When supplied, label fallback is forbidden. */
+    projectKey?: string | null;
+    teamRecipients?: Recipient[];
+    /**
+     * Whole-file zstd instead of per-chunk gzip: 59x rather than 2x on a
+     * transcript, because the duplicate screenshots this collapses sit megabytes
+     * apart and a 4 MB window never sees them.
+     *
+     * Not the default, and the reason is a real trade rather than caution. Chunk
+     * compression is what makes a chunk stand alone, and two shipped things
+     * depend on that: a cold search answers by ranged-reading the few chunks it
+     * needs instead of pulling the whole archive, and sealing streams at bounded
+     * memory. Whole-file compression gives up both. `squeeze` opts in because it
+     * exists to give a full disk back and its archives are read whole anyway;
+     * anything headed for a bucket it will later search should not.
+     */
+    compression?: "gzip-chunk" | "zstd" | "zstd-chunk";
+    /**
+     * Index this seal's tokens into the local content index as part of the seal
+     * (chunk-compressed full seals up to the whale threshold; a delta is indexed
+     * by the catch-up as one chain). The daemon, the CLI and the MCP server set
+     * it: a person's session is searchable the moment it is sealed, not after a
+     * background pass that on a real vault sits behind hours of multi-gigabyte
+     * snapshots. Off by default so callers that build the index themselves
+     * (tests, migrations) see exactly what they built. Advisory: a seal is
+     * durable before its index entry exists, and an entry that fails is named
+     * (`SealkeepIndexDeferred`, audit `index.merge`), never a failed seal.
+     */
+    indexInline?: boolean;
 }): Promise<ArchiveResult>;
 /**
  * The recovery phrase always gets a recipient, so a recovery kit alone can restore.
@@ -114,12 +163,94 @@ export declare function archiveFile(dataDir: string, sourcePath: string, rawPhra
 export declare function configuredRecipients(config: VaultConfig, rawPhrase: string, scope?: string | {
     group?: string;
     project?: string;
+    projectKey?: string;
 }): Recipient[];
+/** Accepted managed team members that should open future project archives. */
+export declare function teamRecipientsForProject(dataDir: string, project: string | null | undefined, projectKey?: string | null): Promise<Recipient[]>;
+/**
+ * Every archive this vault knows about.
+ *
+ * One unreadable record used to take the whole list with it: `JSON.parse`
+ * threw inside a `Promise.all`, so a single truncated file — a crash mid-write,
+ * a disk that filled between `open` and `close` — made `status`, `search`,
+ * `retention` and every other command that lists archives fail outright. A
+ * vault of two hundred good records became a vault of none, over one bad byte.
+ *
+ * A record that will not parse is skipped and NAMED, not swallowed: it may be
+ * the only trace of an archive, and quietly dropping it would turn a loud
+ * problem into a missing one. The archives that do parse still answer.
+ */
 export declare function listArchives(dataDir: string): Promise<ArchiveRecord[]>;
 /**
  * Registers an X25519 public key that may open future archives. Only the public
  * key is stored; the matching private key stays on its own device.
  */
+export declare function projectSharingOf(config: VaultConfig, project: string | undefined | null, projectKey?: string | null): "active" | "passive";
+export declare function setProjectSharing(dataDir: string, project: string, mode: "active" | "passive", projectKey?: string | null): Promise<VaultConfig>;
+export type TeamSpaceBinding = {
+    spaceKey: string;
+    role?: "owner" | "member";
+    keyVersion?: number;
+    realtimeKey?: string;
+    localConfirmed?: true;
+    /** Display-only label for a binding stored under an opaque project key. */
+    localProject?: string;
+};
+export type TeamSpaceBindingPatch = Partial<Omit<TeamSpaceBinding, "spaceKey">>;
+export type TeamProjectDraft = {
+    projectName: string;
+    projects: string[];
+    projectSelections?: ProjectSelection[];
+    createdAt: string;
+};
+export type ProjectSelection = {
+    projectKey: string;
+    project: string;
+};
+export declare function teamSpaceOf(config: VaultConfig, project: string | undefined | null, projectKey?: string | null): TeamSpaceBinding | null;
+/**
+ * Adds keyed aliases for old label-keyed bindings only when local discovery
+ * proves that label names exactly one stable project. The legacy entry stays
+ * in place for older Sealkeep builds; duplicate labels stay untouched and are
+ * therefore invisible to new exact-key access decisions.
+ */
+export declare function migrateLegacyTeamSpaceBindings(dataDir: string, identities: readonly {
+    project: string | null;
+    projectKey: string | null;
+}[]): Promise<VaultConfig>;
+/**
+ * Records the dashboard-visible choice that this checkout participates in a
+ * team space. It stores only the opaque space id; encryption keys never enter
+ * config.json. Binding also enables the automatic live lane for that project.
+ */
+export declare function bindTeamSpace(dataDir: string, project: string, binding: TeamSpaceBinding, projectKey?: string | null): Promise<VaultConfig>;
+/**
+ * Remember which detected local folders should become one logical project.
+ * No path or project label is sent to the hosted plane here. The account page
+ * creates the logical project, then normal daemon reconciliation consumes this
+ * local draft when the matching project appears.
+ */
+export declare function stageTeamProjectDraft(dataDir: string, projectName: string, projects: string[] | ProjectSelection[]): Promise<TeamProjectDraft>;
+export declare function removeTeamProjectDraft(dataDir: string, projectName: string): Promise<VaultConfig>;
+export declare function unbindTeamSpace(dataDir: string, project: string, projectKey?: string | null): Promise<VaultConfig>;
+/**
+ * Disconnect one hosted project from this machine without changing cloud
+ * membership. The tombstone is deliberate: daemon reconciliation must not
+ * silently recreate a binding the person just removed.
+ */
+export declare function disconnectTeamSpaceOnMachine(dataDir: string, spaceKey: string): Promise<VaultConfig>;
+/**
+ * Apply a hosted key/version/route update to every local checkout bound to one
+ * logical space. `undefined` patch members are ignored so an older hosted
+ * response cannot erase a newer route already learned by this machine.
+ */
+export declare function updateTeamSpaceBindings(dataDir: string, spaceKey: string, patch: TeamSpaceBindingPatch): Promise<VaultConfig>;
+/**
+ * Revoke every checkout bound to a removed hosted membership in one atomic
+ * config replacement. The logical space disappears and all affected projects
+ * become passive together; encrypted archives and project files are untouched.
+ */
+export declare function revokeTeamSpaceBindings(dataDir: string, spaceKey: string): Promise<VaultConfig>;
 export declare function addRecipient(dataDir: string, label: string, publicKeyBase64: string, group?: string, 
 /**
  * Tie this key to one project and it becomes a member of that project only:
@@ -127,12 +258,38 @@ export declare function addRecipient(dataDir: string, label: string, publicKeyBa
  * seals. A colleague on `checkout-rewrite` never receives the rest of your
  * work, which is the difference between sharing a folder and handing over a
  * drive.
- */
-project?: string): Promise<VaultConfig>;
+*/
+project?: string, projectKey?: string): Promise<VaultConfig>;
 /** Removes a recipient from future archives. Run `sealkeep rewrap` to revoke it on existing ones. */
 export declare function removeRecipient(dataDir: string, id: string): Promise<VaultConfig>;
-/** Persists a full config document after validation by the caller. */
+/**
+ * Persists a full config document after validation by the caller. Team state
+ * is deliberately retained from the lock-protected current file: bindings and
+ * revocations are changed only through their dedicated atomic helpers.
+ */
 export declare function writeConfig(dataDir: string, config: VaultConfig): Promise<void>;
+/**
+ * Installs a vault identity that was authenticated and decrypted by a transfer
+ * protocol before this call. Unlike `initialize`, this must not mint a new id
+ * or phrase; unlike `writeConfig`, it must work before config.json exists.
+ * The storage root is always local to this data directory, regardless of what
+ * the sending machine used, and the same cross-process lock/refusal protects
+ * against replacing a vault that appeared while approval was in flight.
+ */
+export declare function initializeTransferredVault(dataDir: string, transferred: VaultConfig): Promise<VaultConfig>;
+/** Merge a top-level patch into the latest lock-protected config document. */
+export declare function updateConfigFields(dataDir: string, patch: Partial<VaultConfig>): Promise<VaultConfig>;
+/**
+ * Compare and update top-level config fields while holding the same
+ * cross-process lock as every other supported config mutation. This is the
+ * config-file equivalent of compare-and-set: callers which obtained a value
+ * before an asynchronous network read can refuse to replace a newer local
+ * choice which landed while that read was in flight.
+ */
+export declare function updateConfigFieldsIf(dataDir: string, predicate: (current: VaultConfig) => boolean, patch: Partial<VaultConfig>): Promise<{
+    matched: boolean;
+    config: VaultConfig;
+}>;
 export type RetentionCandidate = {
     id: string;
     agent: string;
@@ -184,10 +341,21 @@ export declare function restoreRecordToFile(dataDir: string, record: ArchiveReco
  */
 rawPhrase: string | {
     privateKey: string;
-}, destination: string, 
+}, 
+/**
+ * A path, or a Writable to stream the plaintext into. The stream form exists
+ * so an archive can be PROVED to decrypt without spending its own size in
+ * free disk; the delta and plain-mode paths below still need a real file and
+ * say so rather than silently writing somewhere unexpected.
+ */
+destination: string | NodeJS.WritableStream, 
 /** Injectable so the offloaded-archive path can be proved without a bucket. */
 options?: {
     client?: import("./offload.js").FetchClient;
+    /** Historical indexing owns a cancellable child; cancellation must also
+     * withdraw a queued/materialising compatibility archive. */
+    signal?: AbortSignal;
+    scratchWaitMs?: number;
 }): Promise<{
     bytes: number;
 }>;
@@ -202,7 +370,15 @@ options?: {
  * base whose recorded length is not what the delta sealed from is refused
  * here, before any restore starts writing.
  */
-export declare function resolveDeltaChain(archives: readonly ArchiveRecord[], target: ArchiveRecord): ArchiveRecord[];
+export declare function resolveDeltaChain(archives: readonly ArchiveRecord[], target: ArchiveRecord, 
+/**
+ * Callers resolving many heads from one ledger may supply its shared index.
+ * Rebuilding the same thousands-entry map once per visible session turned a
+ * linear dashboard question into quadratic work. The optional argument does
+ * not change resolution semantics; it only lets that immutable lookup be
+ * built once for the batch.
+ */
+archiveIndex?: ReadonlyMap<string, ArchiveRecord>): ArchiveRecord[];
 /**
  * Restores a delta archive by reassembling its chain: the base archive first,
  * then each delta's appended range, concatenated in order into `destination`.
@@ -221,7 +397,27 @@ export declare function restoreDeltaChainToFile(dataDir: string, record: Archive
     bytes: number;
     chain: string[];
 }>;
-export declare function decryptRecord(dataDir: string, id: string, rawPhrase: string): Promise<{
+/**
+ * Verifies then decrypts one archive in memory. Ciphertext integrity is checked
+ * before the key touches it, and plaintext integrity after.
+ *
+ * This holds the whole transcript at once; `restoreRecordToFile` is the
+ * constant-memory path and is what restoring uses. Callers that genuinely need
+ * the bytes in hand — indexing, the v1 migration — still come through here.
+ */
+/**
+ * The sealed bytes of a record, wherever they live. A local blob reads
+ * straight from disk; an OFFLOADED archive — sealed copy in the cloud, local
+ * blob reclaimed — is fetched hash-checked and held only for the read. Found
+ * by the live value drill: `sealkeep index build` died with ENOENT on the
+ * first offloaded legacy archive it met, because this read assumed the blob.
+ */
+export type DecryptRecordOptions = {
+    client?: import("./offload.js").FetchClient;
+    signal?: AbortSignal;
+    scratchWaitMs?: number;
+};
+export declare function decryptRecord(dataDir: string, id: string, rawPhrase: string, options?: DecryptRecordOptions): Promise<{
     record: ArchiveRecord;
     plaintext: Buffer;
 }>;