@secondlayer/shared 7.7.0 → 7.8.0

package/dist/src/archive/key-registry.d.ts

@@ -0,0 +1,52 @@
+/**\\n* Trust root for the canonical archive.\\n*\\n* Day-to-day signing uses an ONLINE key that lives on the publishing host, so\\n* it is exposed to every risk that host is. The archive's actual trust anchor\\n* is an OFFLINE ROOT key that never touches a server: it signs a registry of\\n* online keys, and nothing else. A consumer pins the root public key, verifies\\n* the registry against it, and only then decides whether a manifest's signature\\n* means anything.\\n*\\n* The distinction that makes rotation survivable:\\n*\\n*   retired / rotated → the key stops signing NEW objects, but everything it\\n*                       signed while valid stays valid. Without this, every\\n*                       rotation would invalidate the entire published history.\\n*   compromised       → every signature by that key is suspect, including\\n*                       historical ones, because an attacker holding the key\\n*                       could have backdated anything.\\n*\\n* Those two cases look identical in a naive "is this key current?" check, and\\n* conflating them either destroys your history on every rotation or accepts\\n* forgeries after a leak.\\n*/
+declare const KEY_REGISTRY_SCHEMA_VERSION = 1;
+type KeyStatus = "active" | "retired" | "compromised";
+type RegisteredKey = {
+	key_id: string
+	public_key_pem: string
+	status: KeyStatus
+	/** ISO timestamp this key became valid for signing. */
+	valid_from: string
+	/** ISO timestamp it stopped signing. Null while active. */
+	valid_until: string | null
+	/** For `compromised`: the moment trust is withdrawn. Everything this key
+	*  signed is suspect regardless of when, so this is provenance, not a
+	*  validity bound. */
+	compromised_at?: string
+};
+type KeyRegistry = {
+	schema_version: typeof KEY_REGISTRY_SCHEMA_VERSION
+	network: string
+	keys: RegisteredKey[]
+	updated_at: string
+	/** Root signature over the registry minus this envelope. */
+	signature?: string
+	root_key_id?: string
+};
+type KeyTrustResult = {
+	trusted: boolean
+	/** Machine-readable so callers can map to exit codes and messages. */
+	reason: "trusted" | "registry-unsigned" | "registry-signature-invalid" | "unknown-key" | "key-compromised" | "signed-outside-validity"
+	detail: string
+};
+/** The exact bytes the root signature covers: the registry minus its envelope. */
+declare function canonicalRegistryPayload(registry: KeyRegistry): string;
+/**
+* Verify the registry itself against the pinned root public key. Everything
+* downstream is meaningless if this fails — an attacker who can serve a
+* registry can otherwise nominate their own signing key.
+*/
+declare function verifyRegistry(registry: KeyRegistry, rootPublicKeyPem: string): KeyTrustResult;
+/**
+* Decide whether an object signed by `keyId` at `signedAt` should be trusted.
+*
+* `signedAt` is the object's own generation time, NOT now — that is what lets a
+* rotated key keep vouching for what it signed while it was valid.
+*/
+declare function checkKeyTrust(registry: KeyRegistry, keyId: string, signedAt: string): KeyTrustResult;
+/** Look up a key's public PEM for signature verification. */
+declare function publicKeyFor(registry: KeyRegistry, keyId: string): string | undefined;
+/** Derive the registry entry id for a public key, so operators cannot mislabel
+*  a key by hand-editing the registry. */
+declare function keyIdFor(publicKeyPem: string): string;
+export { verifyRegistry, publicKeyFor, keyIdFor, checkKeyTrust, canonicalRegistryPayload, RegisteredKey, KeyTrustResult, KeyStatus, KeyRegistry, KEY_REGISTRY_SCHEMA_VERSION };

package/dist/src/archive/key-registry.js

@@ -0,0 +1,168 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/crypto/ed25519.ts
+var exports_ed25519 = {};
+__export(exports_ed25519, {
+  verifyEd25519: () => verifyEd25519,
+  signEd25519: () => signEd25519,
+  publicKeyPemFromPrivate: () => publicKeyPemFromPrivate,
+  loadEd25519PublicKey: () => loadEd25519PublicKey,
+  loadEd25519PrivateKey: () => loadEd25519PrivateKey,
+  generateEd25519KeyPair: () => generateEd25519KeyPair,
+  ed25519KeyId: () => ed25519KeyId
+});
+import {
+  createHash,
+  createPrivateKey,
+  createPublicKey,
+  generateKeyPairSync,
+  sign as nodeSign,
+  verify as nodeVerify
+} from "node:crypto";
+function generateEd25519KeyPair() {
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  return {
+    privateKeyPem: privateKey.export({ format: "pem", type: "pkcs8" }).toString(),
+    publicKeyPem: publicKey.export({ format: "pem", type: "spki" }).toString()
+  };
+}
+function loadEd25519PrivateKey(pem) {
+  return createPrivateKey(pem);
+}
+function loadEd25519PublicKey(pem) {
+  return createPublicKey(pem);
+}
+function publicKeyPemFromPrivate(privateKeyPem) {
+  return createPublicKey(createPrivateKey(privateKeyPem)).export({ format: "pem", type: "spki" }).toString();
+}
+function ed25519KeyId(publicKeyPem) {
+  const der = createPublicKey(publicKeyPem).export({
+    format: "der",
+    type: "spki"
+  });
+  return createHash("sha256").update(der).digest("base64url").slice(0, 16);
+}
+function signEd25519(payload, privateKey) {
+  return nodeSign(null, Buffer.from(payload, "utf8"), privateKey).toString("base64");
+}
+function verifyEd25519(payload, signatureBase64, publicKey) {
+  try {
+    return nodeVerify(null, Buffer.from(payload, "utf8"), publicKey, Buffer.from(signatureBase64, "base64"));
+  } catch {
+    return false;
+  }
+}
+
+// src/archive/key-registry.ts
+var KEY_REGISTRY_SCHEMA_VERSION = 1;
+function canonicalRegistryPayload(registry) {
+  const { signature: _s, root_key_id: _r, ...rest } = registry;
+  return JSON.stringify(rest);
+}
+function verifyRegistry(registry, rootPublicKeyPem) {
+  if (!registry.signature) {
+    return {
+      trusted: false,
+      reason: "registry-unsigned",
+      detail: "key registry carries no root signature"
+    };
+  }
+  let valid = false;
+  try {
+    valid = verifyEd25519(canonicalRegistryPayload(registry), registry.signature, loadEd25519PublicKey(rootPublicKeyPem));
+  } catch (err) {
+    return {
+      trusted: false,
+      reason: "registry-signature-invalid",
+      detail: err instanceof Error ? err.message : "root verification failed"
+    };
+  }
+  return valid ? {
+    trusted: true,
+    reason: "trusted",
+    detail: "registry verified against root"
+  } : {
+    trusted: false,
+    reason: "registry-signature-invalid",
+    detail: "registry signature does not match the pinned root key"
+  };
+}
+function checkKeyTrust(registry, keyId, signedAt) {
+  const key = registry.keys.find((k) => k.key_id === keyId);
+  if (!key) {
+    return {
+      trusted: false,
+      reason: "unknown-key",
+      detail: `key ${keyId} is not in the registry`
+    };
+  }
+  if (key.status === "compromised") {
+    return {
+      trusted: false,
+      reason: "key-compromised",
+      detail: `key ${keyId} was compromised${key.compromised_at ? ` (${key.compromised_at})` : ""}; every signature it made is suspect`
+    };
+  }
+  const signedTime = Date.parse(signedAt);
+  const from = Date.parse(key.valid_from);
+  if (Number.isNaN(signedTime) || Number.isNaN(from)) {
+    return {
+      trusted: false,
+      reason: "signed-outside-validity",
+      detail: "unparseable timestamp on the object or the key"
+    };
+  }
+  if (signedTime < from) {
+    return {
+      trusted: false,
+      reason: "signed-outside-validity",
+      detail: `object predates key validity (${signedAt} < ${key.valid_from})`
+    };
+  }
+  if (key.valid_until !== null) {
+    const until = Date.parse(key.valid_until);
+    if (!Number.isNaN(until) && signedTime > until) {
+      return {
+        trusted: false,
+        reason: "signed-outside-validity",
+        detail: `object postdates key retirement (${signedAt} > ${key.valid_until})`
+      };
+    }
+  }
+  return {
+    trusted: true,
+    reason: "trusted",
+    detail: key.status === "active" ? `signed by active key ${keyId}` : `signed by ${keyId} while it was valid (now ${key.status})`
+  };
+}
+function publicKeyFor(registry, keyId) {
+  return registry.keys.find((k) => k.key_id === keyId)?.public_key_pem;
+}
+function keyIdFor(publicKeyPem) {
+  return ed25519KeyId(publicKeyPem);
+}
+export {
+  verifyRegistry,
+  publicKeyFor,
+  keyIdFor,
+  checkKeyTrust,
+  canonicalRegistryPayload,
+  KEY_REGISTRY_SCHEMA_VERSION
+};
+
+//# debugId=06FAC7E08C33616364756E2164756E21
+//# sourceMappingURL=key-registry.js.map

package/dist/src/archive/key-registry.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/crypto/ed25519.ts", "../src/archive/key-registry.ts"],
+  "sourcesContent": [
+    "import {\n\ttype KeyObject,\n\tcreateHash,\n\tcreatePrivateKey,\n\tcreatePublicKey,\n\tgenerateKeyPairSync,\n\tsign as nodeSign,\n\tverify as nodeVerify,\n} from \"node:crypto\";\n\n/**\n * Asymmetric ed25519 signing for Streams response proofs.\n *\n * Asymmetric (not HMAC) so the proof is real: only the server holds the private\n * key, and any consumer verifies with the published public key — no shared\n * secret to leak. ed25519 uses node's `sign`/`verify` with a `null` algorithm.\n * Keys are PEM (PKCS8 private / SPKI public) for env transport; load once and\n * reuse the KeyObject on hot paths.\n */\n\nexport function generateEd25519KeyPair(): {\n\tprivateKeyPem: string;\n\tpublicKeyPem: string;\n} {\n\tconst { privateKey, publicKey } = generateKeyPairSync(\"ed25519\");\n\treturn {\n\t\tprivateKeyPem: privateKey\n\t\t\t.export({ format: \"pem\", type: \"pkcs8\" })\n\t\t\t.toString(),\n\t\tpublicKeyPem: publicKey.export({ format: \"pem\", type: \"spki\" }).toString(),\n\t};\n}\n\nexport function loadEd25519PrivateKey(pem: string): KeyObject {\n\treturn createPrivateKey(pem);\n}\n\nexport function loadEd25519PublicKey(pem: string): KeyObject {\n\treturn createPublicKey(pem);\n}\n\nexport function publicKeyPemFromPrivate(privateKeyPem: string): string {\n\treturn createPublicKey(createPrivateKey(privateKeyPem))\n\t\t.export({ format: \"pem\", type: \"spki\" })\n\t\t.toString();\n}\n\n/** Stable short id for a public key (rotation hint via X-Signature-KeyId). */\nexport function ed25519KeyId(publicKeyPem: string): string {\n\tconst der = createPublicKey(publicKeyPem).export({\n\t\tformat: \"der\",\n\t\ttype: \"spki\",\n\t});\n\treturn createHash(\"sha256\").update(der).digest(\"base64url\").slice(0, 16);\n}\n\nexport function signEd25519(payload: string, privateKey: KeyObject): string {\n\treturn nodeSign(null, Buffer.from(payload, \"utf8\"), privateKey).toString(\n\t\t\"base64\",\n\t);\n}\n\nexport function verifyEd25519(\n\tpayload: string,\n\tsignatureBase64: string,\n\tpublicKey: KeyObject,\n): boolean {\n\ttry {\n\t\treturn nodeVerify(\n\t\t\tnull,\n\t\t\tBuffer.from(payload, \"utf8\"),\n\t\t\tpublicKey,\n\t\t\tBuffer.from(signatureBase64, \"base64\"),\n\t\t);\n\t} catch {\n\t\treturn false;\n\t}\n}\n",
+    "import {\n\ted25519KeyId,\n\tloadEd25519PublicKey,\n\tverifyEd25519,\n} from \"../crypto/ed25519.ts\";\n\n/**\n * Trust root for the canonical archive.\n *\n * Day-to-day signing uses an ONLINE key that lives on the publishing host, so\n * it is exposed to every risk that host is. The archive's actual trust anchor\n * is an OFFLINE ROOT key that never touches a server: it signs a registry of\n * online keys, and nothing else. A consumer pins the root public key, verifies\n * the registry against it, and only then decides whether a manifest's signature\n * means anything.\n *\n * The distinction that makes rotation survivable:\n *\n *   retired / rotated → the key stops signing NEW objects, but everything it\n *                       signed while valid stays valid. Without this, every\n *                       rotation would invalidate the entire published history.\n *   compromised       → every signature by that key is suspect, including\n *                       historical ones, because an attacker holding the key\n *                       could have backdated anything.\n *\n * Those two cases look identical in a naive \"is this key current?\" check, and\n * conflating them either destroys your history on every rotation or accepts\n * forgeries after a leak.\n */\n\nexport const KEY_REGISTRY_SCHEMA_VERSION = 1;\n\nexport type KeyStatus = \"active\" | \"retired\" | \"compromised\";\n\nexport type RegisteredKey = {\n\tkey_id: string;\n\tpublic_key_pem: string;\n\tstatus: KeyStatus;\n\t/** ISO timestamp this key became valid for signing. */\n\tvalid_from: string;\n\t/** ISO timestamp it stopped signing. Null while active. */\n\tvalid_until: string | null;\n\t/** For `compromised`: the moment trust is withdrawn. Everything this key\n\t *  signed is suspect regardless of when, so this is provenance, not a\n\t *  validity bound. */\n\tcompromised_at?: string;\n};\n\nexport type KeyRegistry = {\n\tschema_version: typeof KEY_REGISTRY_SCHEMA_VERSION;\n\tnetwork: string;\n\tkeys: RegisteredKey[];\n\tupdated_at: string;\n\t/** Root signature over the registry minus this envelope. */\n\tsignature?: string;\n\troot_key_id?: string;\n};\n\nexport type KeyTrustResult = {\n\ttrusted: boolean;\n\t/** Machine-readable so callers can map to exit codes and messages. */\n\treason:\n\t\t| \"trusted\"\n\t\t| \"registry-unsigned\"\n\t\t| \"registry-signature-invalid\"\n\t\t| \"unknown-key\"\n\t\t| \"key-compromised\"\n\t\t| \"signed-outside-validity\";\n\tdetail: string;\n};\n\n/** The exact bytes the root signature covers: the registry minus its envelope. */\nexport function canonicalRegistryPayload(registry: KeyRegistry): string {\n\tconst { signature: _s, root_key_id: _r, ...rest } = registry;\n\treturn JSON.stringify(rest);\n}\n\n/**\n * Verify the registry itself against the pinned root public key. Everything\n * downstream is meaningless if this fails — an attacker who can serve a\n * registry can otherwise nominate their own signing key.\n */\nexport function verifyRegistry(\n\tregistry: KeyRegistry,\n\trootPublicKeyPem: string,\n): KeyTrustResult {\n\tif (!registry.signature) {\n\t\treturn {\n\t\t\ttrusted: false,\n\t\t\treason: \"registry-unsigned\",\n\t\t\tdetail: \"key registry carries no root signature\",\n\t\t};\n\t}\n\tlet valid = false;\n\ttry {\n\t\tvalid = verifyEd25519(\n\t\t\tcanonicalRegistryPayload(registry),\n\t\t\tregistry.signature,\n\t\t\tloadEd25519PublicKey(rootPublicKeyPem),\n\t\t);\n\t} catch (err) {\n\t\treturn {\n\t\t\ttrusted: false,\n\t\t\treason: \"registry-signature-invalid\",\n\t\t\tdetail: err instanceof Error ? err.message : \"root verification failed\",\n\t\t};\n\t}\n\treturn valid\n\t\t? {\n\t\t\t\ttrusted: true,\n\t\t\t\treason: \"trusted\",\n\t\t\t\tdetail: \"registry verified against root\",\n\t\t\t}\n\t\t: {\n\t\t\t\ttrusted: false,\n\t\t\t\treason: \"registry-signature-invalid\",\n\t\t\t\tdetail: \"registry signature does not match the pinned root key\",\n\t\t\t};\n}\n\n/**\n * Decide whether an object signed by `keyId` at `signedAt` should be trusted.\n *\n * `signedAt` is the object's own generation time, NOT now — that is what lets a\n * rotated key keep vouching for what it signed while it was valid.\n */\nexport function checkKeyTrust(\n\tregistry: KeyRegistry,\n\tkeyId: string,\n\tsignedAt: string,\n): KeyTrustResult {\n\tconst key = registry.keys.find((k) => k.key_id === keyId);\n\tif (!key) {\n\t\treturn {\n\t\t\ttrusted: false,\n\t\t\treason: \"unknown-key\",\n\t\t\tdetail: `key ${keyId} is not in the registry`,\n\t\t};\n\t}\n\tif (key.status === \"compromised\") {\n\t\treturn {\n\t\t\ttrusted: false,\n\t\t\treason: \"key-compromised\",\n\t\t\tdetail: `key ${keyId} was compromised${key.compromised_at ? ` (${key.compromised_at})` : \"\"}; every signature it made is suspect`,\n\t\t};\n\t}\n\n\tconst signedTime = Date.parse(signedAt);\n\tconst from = Date.parse(key.valid_from);\n\tif (Number.isNaN(signedTime) || Number.isNaN(from)) {\n\t\treturn {\n\t\t\ttrusted: false,\n\t\t\treason: \"signed-outside-validity\",\n\t\t\tdetail: \"unparseable timestamp on the object or the key\",\n\t\t};\n\t}\n\tif (signedTime < from) {\n\t\treturn {\n\t\t\ttrusted: false,\n\t\t\treason: \"signed-outside-validity\",\n\t\t\tdetail: `object predates key validity (${signedAt} < ${key.valid_from})`,\n\t\t};\n\t}\n\tif (key.valid_until !== null) {\n\t\tconst until = Date.parse(key.valid_until);\n\t\tif (!Number.isNaN(until) && signedTime > until) {\n\t\t\treturn {\n\t\t\t\ttrusted: false,\n\t\t\t\treason: \"signed-outside-validity\",\n\t\t\t\tdetail: `object postdates key retirement (${signedAt} > ${key.valid_until})`,\n\t\t\t};\n\t\t}\n\t}\n\n\t// A retired key that was valid at signing time is fine — that is the whole\n\t// point of recording a validity window rather than a boolean.\n\treturn {\n\t\ttrusted: true,\n\t\treason: \"trusted\",\n\t\tdetail:\n\t\t\tkey.status === \"active\"\n\t\t\t\t? `signed by active key ${keyId}`\n\t\t\t\t: `signed by ${keyId} while it was valid (now ${key.status})`,\n\t};\n}\n\n/** Look up a key's public PEM for signature verification. */\nexport function publicKeyFor(\n\tregistry: KeyRegistry,\n\tkeyId: string,\n): string | undefined {\n\treturn registry.keys.find((k) => k.key_id === keyId)?.public_key_pem;\n}\n\n/** Derive the registry entry id for a public key, so operators cannot mislabel\n *  a key by hand-editing the registry. */\nexport function keyIdFor(publicKeyPem: string): string {\n\treturn ed25519KeyId(publicKeyPem);\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "06FAC7E08C33616364756E2164756E21",
+  "names": []
+}

package/dist/src/archive/progress.d.ts

@@ -0,0 +1,36 @@
+/**
+* Progress reporting for multi-hour archive jobs.
+*
+* A job that prints nothing until it finishes is indistinguishable from a hung
+* one. That is not a cosmetic problem: on 2026-08-12 an ran silently for
+* 2.5 hours and progress had to be inferred by listing partition filenames on
+* disk, and a killed upload left a log whose single line could not distinguish
+* "died immediately" from "died at 90%".
+*
+* Two rules make the output trustworthy:
+*
+*  - **Time-based, not count-based.** Reporting every N items goes quiet for
+*    an hour when items are large and floods when they are small. Reporting
+*    every N seconds behaves the same for a sparse range and a dense one, so
+*    silence always means the same thing: something is wrong.
+*  - **stderr only.** Progress is chrome. Putting it on stdout would corrupt
+*    `--json` output for every caller that pipes it.
+*/
+type ProgressReporter = {
+	/** Record cumulative progress. Emits at most once per interval. */
+	tick: (completed: number, detail?: string) => void
+	/** Emit a final line regardless of interval. */
+	finish: (detail?: string) => void
+};
+type ProgressOptions = {
+	label: string
+	/** Total units, when known. Enables percentage and ETA. */
+	total?: number
+	intervalMs?: number
+	/** Defaults to stderr. Injectable so tests capture without spying. */
+	write?: (line: string) => void
+	now?: () => number
+};
+declare function formatDuration(seconds: number): string;
+declare function createProgressReporter(options: ProgressOptions): ProgressReporter;
+export { formatDuration, createProgressReporter, ProgressReporter, ProgressOptions };

package/dist/src/archive/progress.js

@@ -0,0 +1,75 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/archive/progress.ts
+var DEFAULT_INTERVAL_MS = 30000;
+function formatDuration(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0)
+    return "unknown";
+  if (seconds < 90)
+    return `${Math.round(seconds)}s`;
+  if (seconds < 5400)
+    return `${Math.round(seconds / 60)}m`;
+  if (seconds < 172800)
+    return `${(seconds / 3600).toFixed(1)}h`;
+  return `${(seconds / 86400).toFixed(1)}d`;
+}
+function createProgressReporter(options) {
+  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const now = options.now ?? (() => Date.now());
+  const write = options.write ?? ((line2) => process.stderr.write(`${line2}
+`));
+  const startedAt = now();
+  let lastEmit = startedAt;
+  function line(completed, detail) {
+    const elapsed = (now() - startedAt) / 1000;
+    const parts = [`${options.label}:`];
+    if (options.total !== undefined && options.total > 0) {
+      const pct = Math.floor(completed / options.total * 100);
+      parts.push(`${completed}/${options.total} (${pct}%)`);
+      if (completed > 0 && elapsed > 0) {
+        const remaining = (options.total - completed) / completed * elapsed;
+        parts.push(`eta ${formatDuration(remaining)}`);
+      }
+    } else {
+      parts.push(String(completed));
+    }
+    parts.push(`elapsed ${formatDuration(elapsed)}`);
+    if (detail)
+      parts.push(`· ${detail}`);
+    return `  ${parts.join(" ")}`;
+  }
+  return {
+    tick(completed, detail) {
+      const current = now();
+      if (current - lastEmit < intervalMs)
+        return;
+      lastEmit = current;
+      write(line(completed, detail));
+    },
+    finish(detail) {
+      lastEmit = now();
+      write(line(options.total ?? 0, detail));
+    }
+  };
+}
+export {
+  formatDuration,
+  createProgressReporter
+};
+
+//# debugId=C1E6E800BC29361764756E2164756E21
+//# sourceMappingURL=progress.js.map

package/dist/src/archive/progress.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/archive/progress.ts"],
+  "sourcesContent": [
+    "/**\n * Progress reporting for multi-hour archive jobs.\n *\n * A job that prints nothing until it finishes is indistinguishable from a hung\n * one. That is not a cosmetic problem: on 2026-08-12 an export ran silently for\n * 2.5 hours and progress had to be inferred by listing partition filenames on\n * disk, and a killed upload left a log whose single line could not distinguish\n * \"died immediately\" from \"died at 90%\".\n *\n * Two rules make the output trustworthy:\n *\n *  - **Time-based, not count-based.** Reporting every N items goes quiet for\n *    an hour when items are large and floods when they are small. Reporting\n *    every N seconds behaves the same for a sparse range and a dense one, so\n *    silence always means the same thing: something is wrong.\n *  - **stderr only.** Progress is chrome. Putting it on stdout would corrupt\n *    `--json` output for every caller that pipes it.\n */\n\nexport type ProgressReporter = {\n\t/** Record cumulative progress. Emits at most once per interval. */\n\ttick: (completed: number, detail?: string) => void;\n\t/** Emit a final line regardless of interval. */\n\tfinish: (detail?: string) => void;\n};\n\nexport type ProgressOptions = {\n\tlabel: string;\n\t/** Total units, when known. Enables percentage and ETA. */\n\ttotal?: number;\n\tintervalMs?: number;\n\t/** Defaults to stderr. Injectable so tests capture without spying. */\n\twrite?: (line: string) => void;\n\tnow?: () => number;\n};\n\nconst DEFAULT_INTERVAL_MS = 30_000;\n\nexport function formatDuration(seconds: number): string {\n\tif (!Number.isFinite(seconds) || seconds < 0) return \"unknown\";\n\tif (seconds < 90) return `${Math.round(seconds)}s`;\n\tif (seconds < 5_400) return `${Math.round(seconds / 60)}m`;\n\tif (seconds < 172_800) return `${(seconds / 3_600).toFixed(1)}h`;\n\treturn `${(seconds / 86_400).toFixed(1)}d`;\n}\n\nexport function createProgressReporter(\n\toptions: ProgressOptions,\n): ProgressReporter {\n\tconst intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;\n\tconst now = options.now ?? (() => Date.now());\n\tconst write =\n\t\toptions.write ?? ((line: string) => process.stderr.write(`${line}\\n`));\n\n\tconst startedAt = now();\n\tlet lastEmit = startedAt;\n\n\tfunction line(completed: number, detail?: string): string {\n\t\tconst elapsed = (now() - startedAt) / 1000;\n\t\tconst parts = [`${options.label}:`];\n\n\t\tif (options.total !== undefined && options.total > 0) {\n\t\t\tconst pct = Math.floor((completed / options.total) * 100);\n\t\t\tparts.push(`${completed}/${options.total} (${pct}%)`);\n\t\t\t// ETA only once there is a rate to extrapolate from; a prediction made\n\t\t\t// from zero progress is noise dressed as information.\n\t\t\tif (completed > 0 && elapsed > 0) {\n\t\t\t\tconst remaining = ((options.total - completed) / completed) * elapsed;\n\t\t\t\tparts.push(`eta ${formatDuration(remaining)}`);\n\t\t\t}\n\t\t} else {\n\t\t\tparts.push(String(completed));\n\t\t}\n\n\t\tparts.push(`elapsed ${formatDuration(elapsed)}`);\n\t\tif (detail) parts.push(`· ${detail}`);\n\t\treturn `  ${parts.join(\" \")}`;\n\t}\n\n\treturn {\n\t\ttick(completed, detail) {\n\t\t\tconst current = now();\n\t\t\tif (current - lastEmit < intervalMs) return;\n\t\t\tlastEmit = current;\n\t\t\twrite(line(completed, detail));\n\t\t},\n\t\tfinish(detail) {\n\t\t\tlastEmit = now();\n\t\t\twrite(line(options.total ?? 0, detail));\n\t\t},\n\t};\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AAoCA,IAAM,sBAAsB;AAErB,SAAS,cAAc,CAAC,SAAyB;AAAA,EACvD,IAAI,CAAC,OAAO,SAAS,OAAO,KAAK,UAAU;AAAA,IAAG,OAAO;AAAA,EACrD,IAAI,UAAU;AAAA,IAAI,OAAO,GAAG,KAAK,MAAM,OAAO;AAAA,EAC9C,IAAI,UAAU;AAAA,IAAO,OAAO,GAAG,KAAK,MAAM,UAAU,EAAE;AAAA,EACtD,IAAI,UAAU;AAAA,IAAS,OAAO,IAAI,UAAU,MAAO,QAAQ,CAAC;AAAA,EAC5D,OAAO,IAAI,UAAU,OAAQ,QAAQ,CAAC;AAAA;AAGhC,SAAS,sBAAsB,CACrC,SACmB;AAAA,EACnB,MAAM,aAAa,QAAQ,cAAc;AAAA,EACzC,MAAM,MAAM,QAAQ,QAAQ,MAAM,KAAK,IAAI;AAAA,EAC3C,MAAM,QACL,QAAQ,UAAU,CAAC,UAAiB,QAAQ,OAAO,MAAM,GAAG;AAAA,CAAQ;AAAA,EAErE,MAAM,YAAY,IAAI;AAAA,EACtB,IAAI,WAAW;AAAA,EAEf,SAAS,IAAI,CAAC,WAAmB,QAAyB;AAAA,IACzD,MAAM,WAAW,IAAI,IAAI,aAAa;AAAA,IACtC,MAAM,QAAQ,CAAC,GAAG,QAAQ,QAAQ;AAAA,IAElC,IAAI,QAAQ,UAAU,aAAa,QAAQ,QAAQ,GAAG;AAAA,MACrD,MAAM,MAAM,KAAK,MAAO,YAAY,QAAQ,QAAS,GAAG;AAAA,MACxD,MAAM,KAAK,GAAG,aAAa,QAAQ,UAAU,OAAO;AAAA,MAGpD,IAAI,YAAY,KAAK,UAAU,GAAG;AAAA,QACjC,MAAM,aAAc,QAAQ,QAAQ,aAAa,YAAa;AAAA,QAC9D,MAAM,KAAK,OAAO,eAAe,SAAS,GAAG;AAAA,MAC9C;AAAA,IACD,EAAO;AAAA,MACN,MAAM,KAAK,OAAO,SAAS,CAAC;AAAA;AAAA,IAG7B,MAAM,KAAK,WAAW,eAAe,OAAO,GAAG;AAAA,IAC/C,IAAI;AAAA,MAAQ,MAAM,KAAK,KAAI,QAAQ;AAAA,IACnC,OAAO,KAAK,MAAM,KAAK,GAAG;AAAA;AAAA,EAG3B,OAAO;AAAA,IACN,IAAI,CAAC,WAAW,QAAQ;AAAA,MACvB,MAAM,UAAU,IAAI;AAAA,MACpB,IAAI,UAAU,WAAW;AAAA,QAAY;AAAA,MACrC,WAAW;AAAA,MACX,MAAM,KAAK,WAAW,MAAM,CAAC;AAAA;AAAA,IAE9B,MAAM,CAAC,QAAQ;AAAA,MACd,WAAW,IAAI;AAAA,MACf,MAAM,KAAK,QAAQ,SAAS,GAAG,MAAM,CAAC;AAAA;AAAA,EAExC;AAAA;",
+  "debugId": "C1E6E800BC29361764756E2164756E21",
+  "names": []
+}

package/dist/src/archive/status.d.ts

@@ -0,0 +1,92 @@
+/**
+* `status.json` — the archive's operational truth, published short-cache from
+* verified state only.
+*
+* Everything else in the tree is immutable and signed, which makes it durable
+* but silent: a consumer holding a valid manifest cannot tell whether it is
+* current, three days behind, or the last thing published before an incident.
+* This object answers that, and it is the only object allowed to say something
+* unflattering.
+*
+* The distinction this file exists to protect:
+*
+*   lagging → the archive trails the chain tip because it only publishes below
+*             the finality boundary. This is CORRECT and permanent. An archive
+*             that reported `stale` for its own finality lag would be crying
+*             wolf forever, and consumers would learn to ignore it.
+*   stale   → publishing stopped. The lag exceeds what the finality rule can
+*             explain, so something is broken.
+*
+* `state` is derived from measurements, never asserted by the publisher, and
+* every unhealthy state is reachable — an archive that can only report health
+* is decoration.
+*/
+declare const ARCHIVE_STATUS_SCHEMA_VERSION = 1;
+type ArchiveState = "fresh" | "lagging" | "stale" | "gap" | "failed-audit" | "source-unavailable";
+type ArchiveStatus = {
+	schema_version: typeof ARCHIVE_STATUS_SCHEMA_VERSION
+	network: string
+	state: ArchiveState
+	/** Human-facing one-liner explaining the state, including WHY. */
+	detail: string
+	generated_at: string
+	archive: {
+		snapshot_digest: string | null
+		coverage_to_block: number | null
+		promoted_at: string | null
+		signing_key_id: string | null
+	}
+	source: {
+		/** Chain tip as the publisher last observed it. Null when unreachable. */
+		tip_height: number | null
+		/** Highest height eligible to publish under the finality rule. */
+		finalized_height: number | null
+	}
+	lag: {
+		/** Behind the FINALIZED height — the number that indicates a problem. */
+		blocks_behind_finalized: number | null
+		/** Behind the raw chain tip — expected to be non-zero forever. */
+		blocks_behind_tip: number | null
+		seconds_since_promotion: number | null
+	}
+	audit: {
+		complete: boolean
+		checked_at: string
+	} | null
+	signature?: string
+	key_id?: string
+};
+type StatusInputs = {
+	network: string
+	snapshotDigest: string | null
+	coverageToBlock: number | null
+	promotedAt: string | null
+	signingKeyId: string | null
+	/** Null when the source could not be reached. */
+	sourceTipHeight: number | null
+	finalizedHeight: number | null
+	audit: {
+		complete: boolean
+		checkedAt: string
+	} | null
+	now: Date
+	/**
+	* How far behind the FINALIZED height the archive may fall before it is
+	* stale rather than merely lagging. Publishing one partition covers 50k
+	* blocks, so a healthy archive sits well inside this.
+	*/
+	maxBlocksBehindFinalized?: number
+	/** How long since the last promotion before staleness, regardless of height. */
+	maxSecondsSincePromotion?: number
+};
+/**
+* Derive status from measurements. Pure, so every state below is reachable in
+* a test rather than only in production at 3am.
+*
+* Order matters: a failing audit outranks freshness, because an archive that
+* is current and wrong is worse than one that is behind and correct.
+*/
+declare function deriveArchiveStatus(inputs: StatusInputs): ArchiveStatus;
+/** States a consumer should refuse to restore from. */
+declare function isRestorable(state: ArchiveState): boolean;
+export { isRestorable, deriveArchiveStatus, StatusInputs, ArchiveStatus, ArchiveState, ARCHIVE_STATUS_SCHEMA_VERSION };

package/dist/src/archive/status.js

@@ -0,0 +1,106 @@
+import { createRequire } from "node:module";
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+
+// src/archive/status.ts
+var ARCHIVE_STATUS_SCHEMA_VERSION = 1;
+var DEFAULT_MAX_BLOCKS_BEHIND_FINALIZED = 60000;
+var DEFAULT_MAX_SECONDS_SINCE_PROMOTION = 48 * 3600;
+function deriveArchiveStatus(inputs) {
+  const maxBehind = inputs.maxBlocksBehindFinalized ?? DEFAULT_MAX_BLOCKS_BEHIND_FINALIZED;
+  const maxAge = inputs.maxSecondsSincePromotion ?? DEFAULT_MAX_SECONDS_SINCE_PROMOTION;
+  const secondsSincePromotion = inputs.promotedAt ? Math.max(0, Math.round((inputs.now.getTime() - Date.parse(inputs.promotedAt)) / 1000)) : null;
+  const behindFinalized = inputs.finalizedHeight !== null && inputs.coverageToBlock !== null ? Math.max(0, inputs.finalizedHeight - inputs.coverageToBlock) : null;
+  const behindTip = inputs.sourceTipHeight !== null && inputs.coverageToBlock !== null ? Math.max(0, inputs.sourceTipHeight - inputs.coverageToBlock) : null;
+  const base = {
+    schema_version: ARCHIVE_STATUS_SCHEMA_VERSION,
+    network: inputs.network,
+    generated_at: inputs.now.toISOString(),
+    archive: {
+      snapshot_digest: inputs.snapshotDigest,
+      coverage_to_block: inputs.coverageToBlock,
+      promoted_at: inputs.promotedAt,
+      signing_key_id: inputs.signingKeyId
+    },
+    source: {
+      tip_height: inputs.sourceTipHeight,
+      finalized_height: inputs.finalizedHeight
+    },
+    lag: {
+      blocks_behind_finalized: behindFinalized,
+      blocks_behind_tip: behindTip,
+      seconds_since_promotion: secondsSincePromotion
+    },
+    audit: inputs.audit ? { complete: inputs.audit.complete, checked_at: inputs.audit.checkedAt } : null
+  };
+  if (inputs.audit && !inputs.audit.complete) {
+    return {
+      ...base,
+      state: "failed-audit",
+      detail: `the canonical audit did not pass at ${inputs.audit.checkedAt}; this archive is not safe to restore from`
+    };
+  }
+  if (!inputs.snapshotDigest || inputs.coverageToBlock === null) {
+    return {
+      ...base,
+      state: "gap",
+      detail: "no snapshot is currently promoted"
+    };
+  }
+  if (inputs.sourceTipHeight === null || inputs.finalizedHeight === null) {
+    return {
+      ...base,
+      state: "source-unavailable",
+      detail: "the chain source could not be reached, so freshness cannot be determined"
+    };
+  }
+  if (secondsSincePromotion !== null && secondsSincePromotion > maxAge) {
+    return {
+      ...base,
+      state: "stale",
+      detail: `last promotion was ${Math.round(secondsSincePromotion / 3600)}h ago, beyond the ${Math.round(maxAge / 3600)}h freshness objective`
+    };
+  }
+  if (behindFinalized !== null && behindFinalized > maxBehind) {
+    return {
+      ...base,
+      state: "stale",
+      detail: `${behindFinalized} blocks behind the finalized height, beyond the ${maxBehind} threshold`
+    };
+  }
+  if (behindTip !== null && behindTip > 0) {
+    return {
+      ...base,
+      state: "lagging",
+      detail: `${behindTip} blocks behind the chain tip, which is expected: only heights below the finality boundary are published`
+    };
+  }
+  return {
+    ...base,
+    state: "fresh",
+    detail: "published through the finalized height"
+  };
+}
+function isRestorable(state) {
+  return state === "fresh" || state === "lagging";
+}
+export {
+  isRestorable,
+  deriveArchiveStatus,
+  ARCHIVE_STATUS_SCHEMA_VERSION
+};
+
+//# debugId=D9102A12541A66EA64756E2164756E21
+//# sourceMappingURL=status.js.map

package/dist/src/archive/status.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/archive/status.ts"],
+  "sourcesContent": [
+    "/**\n * `status.json` — the archive's operational truth, published short-cache from\n * verified state only.\n *\n * Everything else in the tree is immutable and signed, which makes it durable\n * but silent: a consumer holding a valid manifest cannot tell whether it is\n * current, three days behind, or the last thing published before an incident.\n * This object answers that, and it is the only object allowed to say something\n * unflattering.\n *\n * The distinction this file exists to protect:\n *\n *   lagging → the archive trails the chain tip because it only publishes below\n *             the finality boundary. This is CORRECT and permanent. An archive\n *             that reported `stale` for its own finality lag would be crying\n *             wolf forever, and consumers would learn to ignore it.\n *   stale   → publishing stopped. The lag exceeds what the finality rule can\n *             explain, so something is broken.\n *\n * `state` is derived from measurements, never asserted by the publisher, and\n * every unhealthy state is reachable — an archive that can only report health\n * is decoration.\n */\n\nexport const ARCHIVE_STATUS_SCHEMA_VERSION = 1;\n\nexport type ArchiveState =\n\t| \"fresh\"\n\t| \"lagging\"\n\t| \"stale\"\n\t| \"gap\"\n\t| \"failed-audit\"\n\t| \"source-unavailable\";\n\nexport type ArchiveStatus = {\n\tschema_version: typeof ARCHIVE_STATUS_SCHEMA_VERSION;\n\tnetwork: string;\n\tstate: ArchiveState;\n\t/** Human-facing one-liner explaining the state, including WHY. */\n\tdetail: string;\n\tgenerated_at: string;\n\tarchive: {\n\t\tsnapshot_digest: string | null;\n\t\tcoverage_to_block: number | null;\n\t\tpromoted_at: string | null;\n\t\tsigning_key_id: string | null;\n\t};\n\tsource: {\n\t\t/** Chain tip as the publisher last observed it. Null when unreachable. */\n\t\ttip_height: number | null;\n\t\t/** Highest height eligible to publish under the finality rule. */\n\t\tfinalized_height: number | null;\n\t};\n\tlag: {\n\t\t/** Behind the FINALIZED height — the number that indicates a problem. */\n\t\tblocks_behind_finalized: number | null;\n\t\t/** Behind the raw chain tip — expected to be non-zero forever. */\n\t\tblocks_behind_tip: number | null;\n\t\tseconds_since_promotion: number | null;\n\t};\n\taudit: {\n\t\tcomplete: boolean;\n\t\tchecked_at: string;\n\t} | null;\n\tsignature?: string;\n\tkey_id?: string;\n};\n\nexport type StatusInputs = {\n\tnetwork: string;\n\tsnapshotDigest: string | null;\n\tcoverageToBlock: number | null;\n\tpromotedAt: string | null;\n\tsigningKeyId: string | null;\n\t/** Null when the source could not be reached. */\n\tsourceTipHeight: number | null;\n\tfinalizedHeight: number | null;\n\taudit: { complete: boolean; checkedAt: string } | null;\n\tnow: Date;\n\t/**\n\t * How far behind the FINALIZED height the archive may fall before it is\n\t * stale rather than merely lagging. Publishing one partition covers 50k\n\t * blocks, so a healthy archive sits well inside this.\n\t */\n\tmaxBlocksBehindFinalized?: number;\n\t/** How long since the last promotion before staleness, regardless of height. */\n\tmaxSecondsSincePromotion?: number;\n};\n\nconst DEFAULT_MAX_BLOCKS_BEHIND_FINALIZED = 60_000;\nconst DEFAULT_MAX_SECONDS_SINCE_PROMOTION = 48 * 3_600;\n\n/**\n * Derive status from measurements. Pure, so every state below is reachable in\n * a test rather than only in production at 3am.\n *\n * Order matters: a failing audit outranks freshness, because an archive that\n * is current and wrong is worse than one that is behind and correct.\n */\nexport function deriveArchiveStatus(inputs: StatusInputs): ArchiveStatus {\n\tconst maxBehind =\n\t\tinputs.maxBlocksBehindFinalized ?? DEFAULT_MAX_BLOCKS_BEHIND_FINALIZED;\n\tconst maxAge =\n\t\tinputs.maxSecondsSincePromotion ?? DEFAULT_MAX_SECONDS_SINCE_PROMOTION;\n\n\tconst secondsSincePromotion = inputs.promotedAt\n\t\t? Math.max(\n\t\t\t\t0,\n\t\t\t\tMath.round(\n\t\t\t\t\t(inputs.now.getTime() - Date.parse(inputs.promotedAt)) / 1000,\n\t\t\t\t),\n\t\t\t)\n\t\t: null;\n\n\tconst behindFinalized =\n\t\tinputs.finalizedHeight !== null && inputs.coverageToBlock !== null\n\t\t\t? Math.max(0, inputs.finalizedHeight - inputs.coverageToBlock)\n\t\t\t: null;\n\tconst behindTip =\n\t\tinputs.sourceTipHeight !== null && inputs.coverageToBlock !== null\n\t\t\t? Math.max(0, inputs.sourceTipHeight - inputs.coverageToBlock)\n\t\t\t: null;\n\n\tconst base = {\n\t\tschema_version:\n\t\t\tARCHIVE_STATUS_SCHEMA_VERSION as typeof ARCHIVE_STATUS_SCHEMA_VERSION,\n\t\tnetwork: inputs.network,\n\t\tgenerated_at: inputs.now.toISOString(),\n\t\tarchive: {\n\t\t\tsnapshot_digest: inputs.snapshotDigest,\n\t\t\tcoverage_to_block: inputs.coverageToBlock,\n\t\t\tpromoted_at: inputs.promotedAt,\n\t\t\tsigning_key_id: inputs.signingKeyId,\n\t\t},\n\t\tsource: {\n\t\t\ttip_height: inputs.sourceTipHeight,\n\t\t\tfinalized_height: inputs.finalizedHeight,\n\t\t},\n\t\tlag: {\n\t\t\tblocks_behind_finalized: behindFinalized,\n\t\t\tblocks_behind_tip: behindTip,\n\t\t\tseconds_since_promotion: secondsSincePromotion,\n\t\t},\n\t\taudit: inputs.audit\n\t\t\t? { complete: inputs.audit.complete, checked_at: inputs.audit.checkedAt }\n\t\t\t: null,\n\t};\n\n\t// A failed audit is the loudest signal: current-and-wrong beats behind-and-right.\n\tif (inputs.audit && !inputs.audit.complete) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tstate: \"failed-audit\",\n\t\t\tdetail: `the canonical audit did not pass at ${inputs.audit.checkedAt}; this archive is not safe to restore from`,\n\t\t};\n\t}\n\n\tif (!inputs.snapshotDigest || inputs.coverageToBlock === null) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tstate: \"gap\",\n\t\t\tdetail: \"no snapshot is currently promoted\",\n\t\t};\n\t}\n\n\t// Source unreachable: report the gap in KNOWLEDGE rather than guessing. The\n\t// archive may be perfectly healthy; we cannot currently say so.\n\tif (inputs.sourceTipHeight === null || inputs.finalizedHeight === null) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tstate: \"source-unavailable\",\n\t\t\tdetail:\n\t\t\t\t\"the chain source could not be reached, so freshness cannot be determined\",\n\t\t};\n\t}\n\n\tif (secondsSincePromotion !== null && secondsSincePromotion > maxAge) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tstate: \"stale\",\n\t\t\tdetail: `last promotion was ${Math.round(secondsSincePromotion / 3_600)}h ago, beyond the ${Math.round(maxAge / 3_600)}h freshness objective`,\n\t\t};\n\t}\n\n\tif (behindFinalized !== null && behindFinalized > maxBehind) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tstate: \"stale\",\n\t\t\tdetail: `${behindFinalized} blocks behind the finalized height, beyond the ${maxBehind} threshold`,\n\t\t};\n\t}\n\n\t// Behind the tip but within the finality boundary — correct, permanent, and\n\t// explicitly NOT staleness.\n\tif (behindTip !== null && behindTip > 0) {\n\t\treturn {\n\t\t\t...base,\n\t\t\tstate: \"lagging\",\n\t\t\tdetail: `${behindTip} blocks behind the chain tip, which is expected: only heights below the finality boundary are published`,\n\t\t};\n\t}\n\n\treturn {\n\t\t...base,\n\t\tstate: \"fresh\",\n\t\tdetail: \"published through the finalized height\",\n\t};\n}\n\n/** States a consumer should refuse to restore from. */\nexport function isRestorable(state: ArchiveState): boolean {\n\treturn state === \"fresh\" || state === \"lagging\";\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;AAwBO,IAAM,gCAAgC;AAiE7C,IAAM,sCAAsC;AAC5C,IAAM,sCAAsC,KAAK;AAS1C,SAAS,mBAAmB,CAAC,QAAqC;AAAA,EACxE,MAAM,YACL,OAAO,4BAA4B;AAAA,EACpC,MAAM,SACL,OAAO,4BAA4B;AAAA,EAEpC,MAAM,wBAAwB,OAAO,aAClC,KAAK,IACL,GACA,KAAK,OACH,OAAO,IAAI,QAAQ,IAAI,KAAK,MAAM,OAAO,UAAU,KAAK,IAC1D,CACD,IACC;AAAA,EAEH,MAAM,kBACL,OAAO,oBAAoB,QAAQ,OAAO,oBAAoB,OAC3D,KAAK,IAAI,GAAG,OAAO,kBAAkB,OAAO,eAAe,IAC3D;AAAA,EACJ,MAAM,YACL,OAAO,oBAAoB,QAAQ,OAAO,oBAAoB,OAC3D,KAAK,IAAI,GAAG,OAAO,kBAAkB,OAAO,eAAe,IAC3D;AAAA,EAEJ,MAAM,OAAO;AAAA,IACZ,gBACC;AAAA,IACD,SAAS,OAAO;AAAA,IAChB,cAAc,OAAO,IAAI,YAAY;AAAA,IACrC,SAAS;AAAA,MACR,iBAAiB,OAAO;AAAA,MACxB,mBAAmB,OAAO;AAAA,MAC1B,aAAa,OAAO;AAAA,MACpB,gBAAgB,OAAO;AAAA,IACxB;AAAA,IACA,QAAQ;AAAA,MACP,YAAY,OAAO;AAAA,MACnB,kBAAkB,OAAO;AAAA,IAC1B;AAAA,IACA,KAAK;AAAA,MACJ,yBAAyB;AAAA,MACzB,mBAAmB;AAAA,MACnB,yBAAyB;AAAA,IAC1B;AAAA,IACA,OAAO,OAAO,QACX,EAAE,UAAU,OAAO,MAAM,UAAU,YAAY,OAAO,MAAM,UAAU,IACtE;AAAA,EACJ;AAAA,EAGA,IAAI,OAAO,SAAS,CAAC,OAAO,MAAM,UAAU;AAAA,IAC3C,OAAO;AAAA,SACH;AAAA,MACH,OAAO;AAAA,MACP,QAAQ,uCAAuC,OAAO,MAAM;AAAA,IAC7D;AAAA,EACD;AAAA,EAEA,IAAI,CAAC,OAAO,kBAAkB,OAAO,oBAAoB,MAAM;AAAA,IAC9D,OAAO;AAAA,SACH;AAAA,MACH,OAAO;AAAA,MACP,QAAQ;AAAA,IACT;AAAA,EACD;AAAA,EAIA,IAAI,OAAO,oBAAoB,QAAQ,OAAO,oBAAoB,MAAM;AAAA,IACvE,OAAO;AAAA,SACH;AAAA,MACH,OAAO;AAAA,MACP,QACC;AAAA,IACF;AAAA,EACD;AAAA,EAEA,IAAI,0BAA0B,QAAQ,wBAAwB,QAAQ;AAAA,IACrE,OAAO;AAAA,SACH;AAAA,MACH,OAAO;AAAA,MACP,QAAQ,sBAAsB,KAAK,MAAM,wBAAwB,IAAK,sBAAsB,KAAK,MAAM,SAAS,IAAK;AAAA,IACtH;AAAA,EACD;AAAA,EAEA,IAAI,oBAAoB,QAAQ,kBAAkB,WAAW;AAAA,IAC5D,OAAO;AAAA,SACH;AAAA,MACH,OAAO;AAAA,MACP,QAAQ,GAAG,kEAAkE;AAAA,IAC9E;AAAA,EACD;AAAA,EAIA,IAAI,cAAc,QAAQ,YAAY,GAAG;AAAA,IACxC,OAAO;AAAA,SACH;AAAA,MACH,OAAO;AAAA,MACP,QAAQ,GAAG;AAAA,IACZ;AAAA,EACD;AAAA,EAEA,OAAO;AAAA,OACH;AAAA,IACH,OAAO;AAAA,IACP,QAAQ;AAAA,EACT;AAAA;AAIM,SAAS,YAAY,CAAC,OAA8B;AAAA,EAC1D,OAAO,UAAU,WAAW,UAAU;AAAA;",
+  "debugId": "D9102A12541A66EA64756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/shared",
-	"version": "7.7.0",
+	"version": "7.8.0",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
@@ -108,6 +108,18 @@
 			"types": "./dist/src/streams-bulk-manifest.d.ts",
 			"import": "./dist/src/streams-bulk-manifest.js"
 		},
+		"./archive/progress": {
+			"types": "./dist/src/archive/progress.d.ts",
+			"import": "./dist/src/archive/progress.js"
+		},
+		"./archive/status": {
+			"types": "./dist/src/archive/status.d.ts",
+			"import": "./dist/src/archive/status.js"
+		},
+		"./archive/key-registry": {
+			"types": "./dist/src/archive/key-registry.d.ts",
+			"import": "./dist/src/archive/key-registry.js"
+		},
 		"./archive/copy-loader": {
 			"types": "./dist/src/archive/copy-loader.d.ts",
 			"import": "./dist/src/archive/copy-loader.js"
@@ -172,7 +184,7 @@
 		"prepublishOnly": "bun run build"
 	},
 	"dependencies": {
-		"@secondlayer/stacks": "^3.0.0",
+		"@secondlayer/stacks": "^3.3.1",
 		"kysely": "0.28.17",
 		"kysely-postgres-js": "3.0.0",
 		"postgres": "^3.4.6",