@secondlayer/shared 11.2.0 → 11.3.0

package/dist/src/archive/instance-diagnosis.d.ts

@@ -0,0 +1,101 @@
+/**
+* One reading of `/status` (or `/public/status`), shared by the CLI
+* (`status`, `doctor`, `context`) and the SDK (`sl.instance.diagnose`).
+*
+* These surfaces used to each interpret the same payload on their own and
+* disagreed in the most common first-run state: on a freshly self-hosted
+* instance with no chain data, `status` printed DEGRADED while `doctor` printed
+* "All checks passed", and neither named the cause or a next command. An
+* operator (or an agent) reading both had no way to tell whether it was safe to
+* proceed. The verdict now lives here so the surfaces cannot drift apart, and
+* every issue carries the exact command that resolves it.
+*/
+interface PublicStatusDecoder {
+	decoder: string;
+	status: string;
+}
+interface PublicStatusService {
+	name: string;
+	status: string;
+}
+/** The subset of `/status` a diagnosis reads. Everything is optional:
+*  an older instance may not send a field, and a missing field must never be
+*  read as a failure. */
+interface PublicStatus {
+	status?: string;
+	chainTip?: number | null;
+	chainIntegrity?: {
+		ok?: boolean
+		maxHeight?: number
+		reason?: string | null
+	};
+	streams?: {
+		status?: string
+		tip?: {
+			lag_seconds?: number
+			block_height?: number
+		} | null
+	};
+	index?: {
+		status?: string
+		decoders?: PublicStatusDecoder[]
+	};
+	services?: PublicStatusService[];
+	timestamp?: string;
+	[key: string]: unknown;
+}
+interface InstanceIssue {
+	/** What is wrong, in one line. */
+	title: string;
+	/** Why — assembled only from what the payload actually reports. */
+	detail?: string;
+	/** What to run next, most useful first. */
+	nextSteps: string[];
+}
+type InstanceState = "healthy" | "empty-index" | "degraded";
+interface InstanceDiagnosis {
+	state: InstanceState;
+	/** The API's own top-level verdict, passed through unmodified. */
+	overall: string;
+	issues: InstanceIssue[];
+}
+declare const BOOTSTRAP_STEP = "Restore verified history: secondlayer bootstrap --against <manifest>";
+declare const OBSERVER_STEP = "Confirm your node streams into this instance — secondlayer observer --mode indexer --endpoint secondlayer:3700 prints the stanza its config needs";
+declare const SELF_HOST_DOCS_STEP = "Docs: https://www.secondlayer.tools/docs/self-host";
+/** `true` when the instance is reachable but has never indexed a block. */
+declare function hasNoChainData(status: PublicStatus): boolean;
+/**
+* Turn a `/status` payload into a verdict plus zero or more issues.
+* Only facts present in the payload become issues — when the API says degraded
+* and names no failing surface, the issue says exactly that rather than
+* guessing a cause.
+*/
+declare function diagnoseInstanceStatus(status: PublicStatus): InstanceDiagnosis;
+interface ContextProbe {
+	/** The endpoint the snapshot was read from. */
+	apiUrl: string;
+	/** `false` only for the metered archive deployment, which has accounts. */
+	selfHosted: boolean;
+	/** `true` when INSTANCE_TOKEN / SL_API_KEY resolved to a value. */
+	hasCredential: boolean;
+	/** `/public/status` when it answered, `null` when the probe failed. */
+	status: PublicStatus | null;
+	/** Why the probe failed, when it did. */
+	statusError?: string;
+}
+interface ContextExplanation {
+	/** One line naming the likeliest cause of the nulls below. */
+	summary: string;
+	/** Per-null-field reason. Fields that carry a value are absent. */
+	nulls: Record<string, string>;
+}
+/**
+* Explain every null in a `context` snapshot.
+*
+* The SDK degrades each read to `null` on failure, so an all-null snapshot is
+* indistinguishable from "not bootstrapped", "unauthorized", and "broken" —
+* which is exactly what a caller needs to tell apart. Each reason here is
+* derived from a live probe of the same instance, never assumed.
+*/
+declare function explainContextNulls(snapshot: Record<string, unknown>, probe: ContextProbe): ContextExplanation;
+export { hasNoChainData, explainContextNulls, diagnoseInstanceStatus, SELF_HOST_DOCS_STEP, PublicStatusService, PublicStatusDecoder, PublicStatus, OBSERVER_STEP, InstanceState, InstanceIssue, InstanceDiagnosis, ContextProbe, ContextExplanation, BOOTSTRAP_STEP };

package/dist/src/archive/instance-diagnosis.js

@@ -0,0 +1,134 @@
+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/instance-diagnosis.ts
+var BOOTSTRAP_STEP = "Restore verified history: secondlayer bootstrap --against <manifest>";
+var OBSERVER_STEP = "Confirm your node streams into this instance — secondlayer observer --mode indexer --endpoint secondlayer:3700 prints the stanza its config needs";
+var SELF_HOST_DOCS_STEP = "Docs: https://www.secondlayer.tools/docs/self-host";
+function hasNoChainData(status) {
+  const integrity = status.chainIntegrity;
+  if (!integrity || integrity.reason === "check_failed")
+    return false;
+  if (integrity.maxHeight !== 0)
+    return false;
+  return (status.chainTip ?? null) === null;
+}
+function emptyIndexIssue(status) {
+  const decoders = status.index?.decoders ?? [];
+  const stalled = decoders.filter((d) => d.status !== "ok").length;
+  const decoderClause = stalled > 0 ? ` and ${stalled} decoder${stalled === 1 ? "" : "s"} report unavailable because there is nothing to decode` : "";
+  return {
+    title: "No blocks indexed yet — this instance holds 0 blocks.",
+    detail: `Streams has no tip${decoderClause}, which is what makes the overall status DEGRADED. This is the expected state for a fresh instance: nothing is broken, but no read returns data until history lands.`,
+    nextSteps: [BOOTSTRAP_STEP, OBSERVER_STEP, SELF_HOST_DOCS_STEP]
+  };
+}
+var SERVICE_STEPS = [
+  "See the raw per-service report: secondlayer status --json",
+  "Check the containers from docker/oss: docker compose ps, then docker compose logs --tail=50 secondlayer"
+];
+function diagnoseInstanceStatus(status) {
+  const overall = String(status.status ?? "unknown");
+  if (hasNoChainData(status)) {
+    return { state: "empty-index", overall, issues: [emptyIndexIssue(status)] };
+  }
+  const issues = [];
+  for (const service of status.services ?? []) {
+    if (service.status === "ok")
+      continue;
+    issues.push({
+      title: `Service ${service.name} reports ${service.status}.`,
+      nextSteps: SERVICE_STEPS
+    });
+  }
+  const integrity = status.chainIntegrity;
+  if (integrity && integrity.ok === false) {
+    issues.push({
+      title: "Chain-data integrity check failed.",
+      detail: integrity.reason ?? "The tip the instance serves is not backed by the history it implies.",
+      nextSteps: [
+        "Verify against the archive: secondlayer verify all --against <manifest>",
+        "Repair what diverged: secondlayer repair --against <manifest> --apply"
+      ]
+    });
+  }
+  if (issues.length === 0 && overall !== "healthy") {
+    issues.push({
+      title: `The API reports status=${overall} but names no failing service.`,
+      detail: "Every service in the report is ok, so the degradation is in a surface this command does not summarize.",
+      nextSteps: SERVICE_STEPS
+    });
+  }
+  return {
+    state: issues.length > 0 ? "degraded" : "healthy",
+    overall,
+    issues
+  };
+}
+var CONTEXT_FIELDS = [
+  "account",
+  "streamsTip",
+  "indexTip",
+  "subgraphs",
+  "subscriptions",
+  "activeOperations"
+];
+function explainContextNulls(snapshot, probe) {
+  const nullFields = CONTEXT_FIELDS.filter((field) => (snapshot[field] ?? null) === null);
+  if (nullFields.length === 0) {
+    return { summary: "Every field resolved.", nulls: {} };
+  }
+  if (!probe.status) {
+    const reason = `No instance answered at ${probe.apiUrl} (${probe.statusError ?? "unreachable"}), so this read never reached an API.`;
+    return {
+      summary: `${reason} Start it from docker/oss with: docker compose up -d — or point SL_API_URL at the instance you meant.`,
+      nulls: Object.fromEntries(nullFields.map((field) => [field, reason]))
+    };
+  }
+  const emptyIndex = hasNoChainData(probe.status);
+  const blocks = probe.status.chainIntegrity?.maxHeight ?? null;
+  const accountReason = probe.selfHosted ? "Expected: a self-hosted instance has no account system. Accounts exist only on the metered archive deployment at api.secondlayer.tools, so null here is normal and not a failure." : "Not authenticated — run `secondlayer login`, or export INSTANCE_TOKEN.";
+  const listReason = unresolvedReadReason(probe, blocks);
+  const chainReason = emptyIndex ? `No blocks indexed yet — this instance holds 0 blocks, so there is no tip to report. ${BOOTSTRAP_STEP}` : listReason;
+  const nulls = {};
+  for (const field of nullFields) {
+    if (field === "account")
+      nulls[field] = accountReason;
+    else if (field === "streamsTip" || field === "indexTip")
+      nulls[field] = chainReason;
+    else if (field === "activeOperations")
+      nulls[field] = (snapshot.subgraphs ?? null) === null ? "Not probed: in-flight operations are read per subgraph, and the subgraph list did not resolve." : listReason;
+    else
+      nulls[field] = listReason;
+  }
+  const summary = emptyIndex ? `Instance at ${probe.apiUrl} is reachable but holds 0 blocks — the chain fields are null because nothing has been indexed yet. ${BOOTSTRAP_STEP}` : nullFields.length === 1 && nullFields[0] === "account" ? `Instance at ${probe.apiUrl} is reachable and indexed to block ${blocks ?? "unknown"}; only \`account\` is null, which is normal when self-hosting.` : `Instance at ${probe.apiUrl} is reachable, but ${nullFields.length} field${nullFields.length === 1 ? "" : "s"} did not resolve — see \`nulls\` below for each one.`;
+  return { summary, nulls };
+}
+function unresolvedReadReason(probe, blocks) {
+  const where = `The instance at ${probe.apiUrl} is reachable${blocks !== null ? ` and indexed to block ${blocks}` : ""}, but this read returned nothing.`;
+  return probe.hasCredential ? `${where} Check the surface directly: secondlayer status --json` : `${where} No credential resolved: export INSTANCE_TOKEN — an instance published past loopback requires it on every /v1 read.`;
+}
+export {
+  hasNoChainData,
+  explainContextNulls,
+  diagnoseInstanceStatus,
+  SELF_HOST_DOCS_STEP,
+  OBSERVER_STEP,
+  BOOTSTRAP_STEP
+};
+
+//# debugId=C2B46C6D2D1CDDE564756E2164756E21
+//# sourceMappingURL=instance-diagnosis.js.map

package/dist/src/archive/instance-diagnosis.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/archive/instance-diagnosis.ts"],
+  "sourcesContent": [
+    "/**\n * One reading of `/status` (or `/public/status`), shared by the CLI\n * (`status`, `doctor`, `context`) and the SDK (`sl.instance.diagnose`).\n *\n * These surfaces used to each interpret the same payload on their own and\n * disagreed in the most common first-run state: on a freshly self-hosted\n * instance with no chain data, `status` printed DEGRADED while `doctor` printed\n * \"All checks passed\", and neither named the cause or a next command. An\n * operator (or an agent) reading both had no way to tell whether it was safe to\n * proceed. The verdict now lives here so the surfaces cannot drift apart, and\n * every issue carries the exact command that resolves it.\n */\n\nexport interface PublicStatusDecoder {\n\tdecoder: string;\n\tstatus: string;\n}\n\nexport interface PublicStatusService {\n\tname: string;\n\tstatus: string;\n}\n\n/** The subset of `/status` a diagnosis reads. Everything is optional:\n *  an older instance may not send a field, and a missing field must never be\n *  read as a failure. */\nexport interface PublicStatus {\n\tstatus?: string;\n\tchainTip?: number | null;\n\tchainIntegrity?: {\n\t\tok?: boolean;\n\t\tmaxHeight?: number;\n\t\treason?: string | null;\n\t};\n\tstreams?: {\n\t\tstatus?: string;\n\t\ttip?: { lag_seconds?: number; block_height?: number } | null;\n\t};\n\tindex?: { status?: string; decoders?: PublicStatusDecoder[] };\n\tservices?: PublicStatusService[];\n\ttimestamp?: string;\n\t[key: string]: unknown;\n}\n\nexport interface InstanceIssue {\n\t/** What is wrong, in one line. */\n\ttitle: string;\n\t/** Why — assembled only from what the payload actually reports. */\n\tdetail?: string;\n\t/** What to run next, most useful first. */\n\tnextSteps: string[];\n}\n\nexport type InstanceState = \"healthy\" | \"empty-index\" | \"degraded\";\n\nexport interface InstanceDiagnosis {\n\tstate: InstanceState;\n\t/** The API's own top-level verdict, passed through unmodified. */\n\toverall: string;\n\tissues: InstanceIssue[];\n}\n\nexport const BOOTSTRAP_STEP =\n\t\"Restore verified history: secondlayer bootstrap --against <manifest>\";\nexport const OBSERVER_STEP =\n\t\"Confirm your node streams into this instance — secondlayer observer --mode indexer --endpoint secondlayer:3700 prints the stanza its config needs\";\nexport const SELF_HOST_DOCS_STEP =\n\t\"Docs: https://www.secondlayer.tools/docs/self-host\";\n\n/** `true` when the instance is reachable but has never indexed a block. */\nexport function hasNoChainData(status: PublicStatus): boolean {\n\tconst integrity = status.chainIntegrity;\n\t// `check_failed` is the API's placeholder when the integrity query itself\n\t// errored — its maxHeight of 0 means \"unknown\", not \"empty\".\n\tif (!integrity || integrity.reason === \"check_failed\") return false;\n\tif (integrity.maxHeight !== 0) return false;\n\treturn (status.chainTip ?? null) === null;\n}\n\nfunction emptyIndexIssue(status: PublicStatus): InstanceIssue {\n\tconst decoders = status.index?.decoders ?? [];\n\tconst stalled = decoders.filter((d) => d.status !== \"ok\").length;\n\tconst decoderClause =\n\t\tstalled > 0\n\t\t\t? ` and ${stalled} decoder${stalled === 1 ? \"\" : \"s\"} report unavailable because there is nothing to decode`\n\t\t\t: \"\";\n\treturn {\n\t\ttitle: \"No blocks indexed yet — this instance holds 0 blocks.\",\n\t\tdetail: `Streams has no tip${decoderClause}, which is what makes the overall status DEGRADED. This is the expected state for a fresh instance: nothing is broken, but no read returns data until history lands.`,\n\t\tnextSteps: [BOOTSTRAP_STEP, OBSERVER_STEP, SELF_HOST_DOCS_STEP],\n\t};\n}\n\nconst SERVICE_STEPS = [\n\t\"See the raw per-service report: secondlayer status --json\",\n\t\"Check the containers from docker/oss: docker compose ps, then docker compose logs --tail=50 secondlayer\",\n];\n\n/**\n * Turn a `/status` payload into a verdict plus zero or more issues.\n * Only facts present in the payload become issues — when the API says degraded\n * and names no failing surface, the issue says exactly that rather than\n * guessing a cause.\n */\nexport function diagnoseInstanceStatus(\n\tstatus: PublicStatus,\n): InstanceDiagnosis {\n\tconst overall = String(status.status ?? \"unknown\");\n\n\tif (hasNoChainData(status)) {\n\t\treturn { state: \"empty-index\", overall, issues: [emptyIndexIssue(status)] };\n\t}\n\n\tconst issues: InstanceIssue[] = [];\n\tfor (const service of status.services ?? []) {\n\t\tif (service.status === \"ok\") continue;\n\t\tissues.push({\n\t\t\ttitle: `Service ${service.name} reports ${service.status}.`,\n\t\t\tnextSteps: SERVICE_STEPS,\n\t\t});\n\t}\n\n\tconst integrity = status.chainIntegrity;\n\tif (integrity && integrity.ok === false) {\n\t\tissues.push({\n\t\t\ttitle: \"Chain-data integrity check failed.\",\n\t\t\tdetail:\n\t\t\t\tintegrity.reason ??\n\t\t\t\t\"The tip the instance serves is not backed by the history it implies.\",\n\t\t\tnextSteps: [\n\t\t\t\t\"Verify against the archive: secondlayer verify all --against <manifest>\",\n\t\t\t\t\"Repair what diverged: secondlayer repair --against <manifest> --apply\",\n\t\t\t],\n\t\t});\n\t}\n\n\tif (issues.length === 0 && overall !== \"healthy\") {\n\t\t// Do not invent a cause: report the contradiction and where to look.\n\t\tissues.push({\n\t\t\ttitle: `The API reports status=${overall} but names no failing service.`,\n\t\t\tdetail:\n\t\t\t\t\"Every service in the report is ok, so the degradation is in a surface this command does not summarize.\",\n\t\t\tnextSteps: SERVICE_STEPS,\n\t\t});\n\t}\n\n\treturn {\n\t\tstate: issues.length > 0 ? \"degraded\" : \"healthy\",\n\t\toverall,\n\t\tissues,\n\t};\n}\n\n// ── context ────────────────────────────────────────────────────────────\n\nexport interface ContextProbe {\n\t/** The endpoint the snapshot was read from. */\n\tapiUrl: string;\n\t/** `false` only for the metered archive deployment, which has accounts. */\n\tselfHosted: boolean;\n\t/** `true` when INSTANCE_TOKEN / SL_API_KEY resolved to a value. */\n\thasCredential: boolean;\n\t/** `/public/status` when it answered, `null` when the probe failed. */\n\tstatus: PublicStatus | null;\n\t/** Why the probe failed, when it did. */\n\tstatusError?: string;\n}\n\nexport interface ContextExplanation {\n\t/** One line naming the likeliest cause of the nulls below. */\n\tsummary: string;\n\t/** Per-null-field reason. Fields that carry a value are absent. */\n\tnulls: Record<string, string>;\n}\n\nconst CONTEXT_FIELDS = [\n\t\"account\",\n\t\"streamsTip\",\n\t\"indexTip\",\n\t\"subgraphs\",\n\t\"subscriptions\",\n\t\"activeOperations\",\n] as const;\n\n/**\n * Explain every null in a `context` snapshot.\n *\n * The SDK degrades each read to `null` on failure, so an all-null snapshot is\n * indistinguishable from \"not bootstrapped\", \"unauthorized\", and \"broken\" —\n * which is exactly what a caller needs to tell apart. Each reason here is\n * derived from a live probe of the same instance, never assumed.\n */\nexport function explainContextNulls(\n\tsnapshot: Record<string, unknown>,\n\tprobe: ContextProbe,\n): ContextExplanation {\n\tconst nullFields = CONTEXT_FIELDS.filter(\n\t\t(field) => (snapshot[field] ?? null) === null,\n\t);\n\n\tif (nullFields.length === 0) {\n\t\treturn { summary: \"Every field resolved.\", nulls: {} };\n\t}\n\n\tif (!probe.status) {\n\t\tconst reason = `No instance answered at ${probe.apiUrl} (${probe.statusError ?? \"unreachable\"}), so this read never reached an API.`;\n\t\treturn {\n\t\t\tsummary: `${reason} Start it from docker/oss with: docker compose up -d — or point SL_API_URL at the instance you meant.`,\n\t\t\tnulls: Object.fromEntries(nullFields.map((field) => [field, reason])),\n\t\t};\n\t}\n\n\tconst emptyIndex = hasNoChainData(probe.status);\n\tconst blocks = probe.status.chainIntegrity?.maxHeight ?? null;\n\tconst accountReason = probe.selfHosted\n\t\t? \"Expected: a self-hosted instance has no account system. Accounts exist only on the metered archive deployment at api.secondlayer.tools, so null here is normal and not a failure.\"\n\t\t: \"Not authenticated — run `secondlayer login`, or export INSTANCE_TOKEN.\";\n\n\t// An empty index explains the chain tips and nothing else: the subgraph and\n\t// subscription lists are control-plane reads that answer on a bare instance.\n\tconst listReason = unresolvedReadReason(probe, blocks);\n\tconst chainReason = emptyIndex\n\t\t? `No blocks indexed yet — this instance holds 0 blocks, so there is no tip to report. ${BOOTSTRAP_STEP}`\n\t\t: listReason;\n\n\tconst nulls: Record<string, string> = {};\n\tfor (const field of nullFields) {\n\t\tif (field === \"account\") nulls[field] = accountReason;\n\t\telse if (field === \"streamsTip\" || field === \"indexTip\")\n\t\t\tnulls[field] = chainReason;\n\t\telse if (field === \"activeOperations\")\n\t\t\tnulls[field] =\n\t\t\t\t(snapshot.subgraphs ?? null) === null\n\t\t\t\t\t? \"Not probed: in-flight operations are read per subgraph, and the subgraph list did not resolve.\"\n\t\t\t\t\t: listReason;\n\t\telse nulls[field] = listReason;\n\t}\n\n\tconst summary = emptyIndex\n\t\t? `Instance at ${probe.apiUrl} is reachable but holds 0 blocks — the chain fields are null because nothing has been indexed yet. ${BOOTSTRAP_STEP}`\n\t\t: nullFields.length === 1 && nullFields[0] === \"account\"\n\t\t\t? `Instance at ${probe.apiUrl} is reachable and indexed to block ${blocks ?? \"unknown\"}; only \\`account\\` is null, which is normal when self-hosting.`\n\t\t\t: `Instance at ${probe.apiUrl} is reachable, but ${nullFields.length} field${nullFields.length === 1 ? \"\" : \"s\"} did not resolve — see \\`nulls\\` below for each one.`;\n\n\treturn { summary, nulls };\n}\n\nfunction unresolvedReadReason(\n\tprobe: ContextProbe,\n\tblocks: number | null,\n): string {\n\tconst where = `The instance at ${probe.apiUrl} is reachable${blocks !== null ? ` and indexed to block ${blocks}` : \"\"}, but this read returned nothing.`;\n\treturn probe.hasCredential\n\t\t? `${where} Check the surface directly: secondlayer status --json`\n\t\t: `${where} No credential resolved: export INSTANCE_TOKEN — an instance published past loopback requires it on every /v1 read.`;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "C2B46C6D2D1CDDE564756E2164756E21",
+  "names": []
+}

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

@@ -0,0 +1,170 @@
+/**
+* Cheap, SQL-computed digests over a height range — the basis of a verify that
+* runs in seconds instead of hours.
+*
+* The archive's per-object `sha256:parquet-object` digests can only be checked
+* by regenerating the Parquet locally, which costs a full export. That is a
+* reasonable paranoid check and a terrible first-run experience: nobody will
+* spend two hours to discover whether they are broken. These digests are
+* computed by the database itself, over the columns that actually carry chain
+* identity, so an operator gets an answer before they lose interest.
+*
+* What this catches is not a subset chosen for convenience — it is precisely
+* the defect class seen in production: missing heights, a canonical child whose
+* `parent_hash` names a block we no longer hold, duplicate canonical rows at one
+* height, and any altered block/transaction identity. What it deliberately does
+* NOT catch is a difference in bulky payload columns (`raw_tx`, event `data`)
+* that leaves identity intact; `--deep` re-exists for that.
+*
+* Determinism rules, so two independent databases agree:
+*  - Aggregate over an explicit ORDER BY, never table order.
+*  - Hash each row to a fixed-width digest FIRST, then aggregate those, so the
+*    intermediate string is 32 bytes/row rather than the whole row.
+*  - Normalize NULL to a sentinel that cannot collide with a real value.
+*  - Never include a column whose representation is environment-dependent
+*    (timestamps with timezone rendering, generated ids, `created_at`).
+*/
+declare const RANGE_DIGEST_SPEC: "md5:sql-identity-v1";
+type RangeDigestDataset = "blocks" | "transactions" | "events";
+type RangeDigest = {
+	dataset: RangeDigestDataset
+	from_block: number
+	to_block: number
+	row_count: number
+	/** null when the range holds no rows — an empty range has no digest, and
+	*  that is materially different from "a digest that happens to be of zero
+	*  rows", which would compare equal across datasets. */
+	digest: string | null
+	digest_spec: typeof RANGE_DIGEST_SPEC
+};
+/**
+* v1 canonical byte encoding for chain identity — the shape that lets
+* independently-run runtimes agree on the same block.
+*
+* The exact-body digest (`sha256:parquet-object`) proves capture fidelity to one
+* source: replay the same bytes, get the same rows. It cannot prove two nodes
+* observed the same chain, because their Parquet encoders legally differ in
+* column padding, compression, JSON key order, and null placement — two
+* operators processing the same block can ship byte-different Parquets that
+* carry identical content.
+*
+* The semantic digest is the shape that lets independent runtimes agree. Every
+* value on a block/transaction/event is normalized into a canonical byte string
+* by rules that MUST NOT change without a version bump. Two v1 computations
+* over the same range agree, or one is wrong about the chain — never about
+* formatting.
+*
+* Encoding rules (v1):
+*   - Fields join with `\x1f` (ASCII US, unit separator — cannot legally
+*     appear in any chain value; a printable delimiter risks collision with
+*     contract-emitted strings).
+*   - Null encodes as `\x00` (single NUL). Distinct from empty string `""`.
+*   - Integers encode as their base-10 string. bigint → decimal string.
+*   - JSON payload columns (function_args, event data) encode as canonical
+*     JSON: object keys sorted lexicographically, no whitespace, bigint →
+*     quoted decimal string, non-finite numbers rejected.
+*   - Field order per record type is fixed and never reordered.
+*   - Digest = sha256(bytes), lowercase hex.
+*
+* Rollup rules (v1) — order MUST match the archive's stream order or an
+* honest re-will disagree with the manifest:
+*   - blocks:       (height asc)
+*   - transactions: (block_height asc, tx_index asc, tx_id asc)
+*   - events:       (block_height asc, event_index asc, tx_id asc)
+* Per-partition rollup is `sha256(concat(row_digest_bytes))` in stream order.
+*
+* Test vectors under `packages/shared/src/archive/__fixtures__/semantic-digest/`
+* pin the encoding. Any change to bytes must bump the spec version.
+*/
+declare const SEMANTIC_DIGEST_SPEC_V1: "sha256:semantic-v1";
+type SemanticDigestSpec = typeof SEMANTIC_DIGEST_SPEC_V1;
+/**
+* Per-partition digest record — the shape that lands in the snapshot manifest.
+* Complements the existing `sha256:parquet-object` per-partition digest by
+* proving semantic identity independent of file encoding.
+*/
+interface PartitionSemanticDigest {
+	dataset: "blocks" | "transactions" | "events";
+	from_block: number;
+	to_block: number;
+	row_count: number;
+	digest: string | null;
+	digest_spec: SemanticDigestSpec;
+}
+/**
+* Loading and trusting an archive reference — shared by the CLI and the SDK
+* so the two cannot disagree about what "the archive says".
+*
+* A reference is either an https URL or a local path to a snapshot manifest.
+* The SDK only passes `http(s)://` sources; local paths stay CLI. Partition
+* objects live beside the snapshot at `<root>/<dataset>/<name>.parquet`,
+* where the root is two levels above the manifest
+* (`<root>/snapshots/<digest>.json`).
+*/
+type ArchivePartition = {
+	dataset: string
+	from_block: number
+	to_block: number
+	path: string
+	row_count: number
+	byte_size: number
+	sha256: string
+};
+type ArchiveManifest = {
+	network?: string
+	coverage?: {
+		from_block: number
+		to_block: number
+	}
+	partition_size_blocks?: number
+	range_digests?: RangeDigest[]
+	partition_semantic_digests?: PartitionSemanticDigest[]
+	partitions?: ArchivePartition[]
+	signature?: string
+	key_id?: string
+	[key: string]: unknown
+};
+type LoadedReference = {
+	manifest: ArchiveManifest
+	origin: string
+	/** Base for resolving partition paths; a URL prefix or a directory. */
+	root: string
+	isRemote: boolean
+};
+type LoadReferenceOptions = {
+	/** Key used to verify a signed `latest.json` pointer. The pointer names
+	*  which snapshot is current, so without this an attacker holding only
+	*  bucket write access could roll every reader back to an older, still
+	*  validly signed, snapshot. */
+	publicKeyPem?: string
+	/** Test/SDK seam; production CLI leaves this unset and uses global fetch. */
+	fetchImpl?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+};
+declare function loadReference(source: string, options?: LoadReferenceOptions): Promise<LoadedReference>;
+type SignatureResult = {
+	verified: boolean
+	reason?: string
+};
+/**
+* An unsigned or unverifiable reference is worthless as a source of truth:
+* comparing against it yields a confident answer with nothing behind it, and
+* repairing from it would write unverified data into a live database.
+*/
+declare function checkSignature(manifest: ArchiveManifest, publicKeyPem: string | undefined, insecure: boolean): SignatureResult;
+/**
+* Which key a manifest is checked against, in trust order: an explicit
+* `--public-key`, then `ARCHIVE_SIGNING_PUBLIC_KEY` / `STREAMS_SIGNING_PUBLIC_KEY`
+* from the environment, then the hosted key endpoint over https (never in OSS
+* mode, which must work with no path to api.secondlayer.tools), and finally the
+* key compiled into this release. The compiled key means a fresh self-hosted
+* instance can bootstrap offline; the tradeoff is that rotating it is a CLI
+* release. Plaintext `http://` key sources are never consulted.
+*/
+declare function resolveArchivePublicKey(input: {
+	explicitPem?: string
+	envPem?: string
+	allowHostedApi?: boolean
+	/** Test seam for the hosted endpoint; production callers leave it unset. */
+	hostedKeyUrl?: string
+}): Promise<string>;
+export { resolveArchivePublicKey, loadReference, checkSignature, SignatureResult, LoadedReference, LoadReferenceOptions, ArchivePartition, ArchiveManifest };

package/dist/src/archive/reference.js

@@ -0,0 +1,231 @@
+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/streams-bulk-manifest.ts
+function canonicalStreamsBulkManifestPayload(manifest) {
+  const { signature: _signature, key_id: _keyId, ...rest } = manifest;
+  return JSON.stringify(rest);
+}
+function normalizePem(pem) {
+  return pem.includes("\\n") ? pem.replace(/\\n/g, `
+`) : pem;
+}
+function signStreamsBulkManifest(manifest, privateKeyPem) {
+  const pem = normalizePem(privateKeyPem);
+  const privateKey = loadEd25519PrivateKey(pem);
+  const keyId = ed25519KeyId(publicKeyPemFromPrivate(pem));
+  const { signature: _signature, key_id: _keyId, ...base } = manifest;
+  const payload = JSON.stringify(base);
+  return {
+    ...base,
+    signature: signEd25519(payload, privateKey),
+    key_id: keyId
+  };
+}
+function verifyStreamsBulkManifestSignature(manifest, publicKeyPem) {
+  if (!manifest.signature)
+    return false;
+  const payload = canonicalStreamsBulkManifestPayload(manifest);
+  return verifyEd25519(payload, manifest.signature, loadEd25519PublicKey(publicKeyPem));
+}
+
+// src/archive/root-key.ts
+var ARCHIVE_ROOT_PUBLIC_KEY_PEM = [
+  "-----BEGIN PUBLIC KEY-----",
+  "MCowBQYDK2VwAyEAq7wXm235JkFbElDmTVdNtmTKqRLx4PzjBgZhyREUFis=",
+  "-----END PUBLIC KEY-----",
+  ""
+].join(`
+`);
+var ARCHIVE_ROOT_KEY_ID = "fHQWzs9ML2WIYakf";
+
+// src/archive/reference.ts
+import { createHash as createHash2 } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+function isLatestPointer(value) {
+  const pointer = value;
+  return typeof pointer.snapshot_path === "string" && (value.partitions === undefined || value.partitions.length === 0);
+}
+var SNAPSHOT_PATH_PATTERN = /^snapshots\/[0-9a-f]{64}\.json$/;
+async function fetchJson(url, fetchImpl) {
+  const response = await fetchImpl(url, {
+    signal: AbortSignal.timeout(30000)
+  });
+  if (!response.ok) {
+    throw new Error(`could not fetch manifest (${response.status} ${response.statusText})`);
+  }
+  return response.json();
+}
+async function loadReference(source, options = {}) {
+  const isRemote = /^https?:\/\//.test(source);
+  const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+  let manifest;
+  let root;
+  if (isRemote) {
+    manifest = await fetchJson(source, fetchImpl);
+    const url = new URL(source);
+    url.pathname = url.pathname.replace(/\/snapshots\/[^/]+$/, "").replace(/\/[^/]+\.json$/, "");
+    root = url.toString();
+  } else {
+    const path = resolve(source);
+    manifest = JSON.parse(await readFile(path, "utf8"));
+    root = isLatestPointer(manifest) ? dirname(path) : dirname(dirname(path));
+  }
+  if (!isLatestPointer(manifest)) {
+    return { manifest, origin: source, root, isRemote };
+  }
+  const pointer = manifest;
+  const snapshotPath = pointer.snapshot_path;
+  if (!SNAPSHOT_PATH_PATTERN.test(snapshotPath)) {
+    throw new Error(`pointer names an invalid snapshot path: ${snapshotPath} (expected snapshots/<sha256>.json)`);
+  }
+  if (typeof pointer.snapshot_digest !== "string" || !/^[0-9a-f]{64}$/.test(pointer.snapshot_digest)) {
+    throw new Error("pointer carries no snapshot_digest, so it cannot prove which snapshot is current");
+  }
+  if (pointer.signature !== undefined) {
+    if (!options.publicKeyPem) {
+      throw new Error("pointer is signed but no public key is available to verify it");
+    }
+    let verified = false;
+    try {
+      verified = verifyStreamsBulkManifestSignature(pointer, options.publicKeyPem);
+    } catch {
+      verified = false;
+    }
+    if (!verified) {
+      throw new Error("pointer signature did not verify against the archive key");
+    }
+  }
+  const resolved = isRemote ? await fetchJson(`${root.replace(/\/$/, "")}/${snapshotPath}`, fetchImpl) : JSON.parse(await readFile(join(root, snapshotPath), "utf8"));
+  const digest = createHash2("sha256").update(JSON.stringify((({ signature: _s, key_id: _k, ...rest }) => rest)(resolved))).digest("hex");
+  if (digest !== pointer.snapshot_digest) {
+    throw new Error(`pointer/snapshot mismatch: latest.json names ${pointer.snapshot_digest}, resolved manifest hashes to ${digest}`);
+  }
+  return { manifest: resolved, origin: source, root, isRemote };
+}
+function checkSignature(manifest, publicKeyPem, insecure) {
+  if (insecure)
+    return { verified: false, reason: "signature check skipped" };
+  if (!manifest.signature) {
+    return { verified: false, reason: "manifest carries no signature" };
+  }
+  if (!publicKeyPem) {
+    return {
+      verified: false,
+      reason: "no public key available to verify with"
+    };
+  }
+  try {
+    const verified = verifyStreamsBulkManifestSignature(manifest, publicKeyPem);
+    return {
+      verified,
+      reason: verified ? undefined : "signature did not verify"
+    };
+  } catch (err) {
+    return {
+      verified: false,
+      reason: err instanceof Error ? err.message : "signature check failed"
+    };
+  }
+}
+var HOSTED_SIGNING_KEY_URL = "https://api.secondlayer.tools/public/streams/signing-key";
+async function fetchHostedKey(url) {
+  if (!url.startsWith("https://"))
+    return;
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(1e4) });
+    if (!response.ok)
+      return;
+    const body = await response.json();
+    return typeof body.public_key_pem === "string" ? body.public_key_pem : undefined;
+  } catch {
+    return;
+  }
+}
+async function resolveArchivePublicKey(input) {
+  if (input.explicitPem)
+    return input.explicitPem;
+  if (input.envPem)
+    return input.envPem;
+  if (input.allowHostedApi) {
+    const hosted = await fetchHostedKey(input.hostedKeyUrl ?? HOSTED_SIGNING_KEY_URL);
+    if (hosted)
+      return hosted;
+  }
+  return ARCHIVE_ROOT_PUBLIC_KEY_PEM;
+}
+export {
+  resolveArchivePublicKey,
+  loadReference,
+  checkSignature
+};
+
+//# debugId=C1F257F42AE1841A64756E2164756E21
+//# sourceMappingURL=reference.js.map

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

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/crypto/ed25519.ts", "../src/streams-bulk-manifest.ts", "../src/archive/root-key.ts", "../src/archive/reference.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\tloadEd25519PrivateKey,\n\tloadEd25519PublicKey,\n\tpublicKeyPemFromPrivate,\n\tsignEd25519,\n\tverifyEd25519,\n} from \"./crypto/ed25519.ts\";\n\n/**\n * ed25519 signing for the Streams cold-bulk parquet manifest.\n *\n * The live Streams lane is ed25519-signed; the bulk manifest was plain JSON with\n * only per-file sha256, so a tampered manifest+file pair verified cleanly. This\n * signs the manifest itself with the same platform key, so a consumer can trust\n * the file hashes only after the manifest signature checks out — making the two\n * availability lanes symmetric.\n *\n * The signed bytes are the manifest's canonical JSON with the signature envelope\n * fields removed, so signer and verifier agree without a separate canonical\n * form: `signature`/`key_id` are appended last, so stripping them and\n * re-serializing reproduces the exact pre-sign bytes.\n */\ntype SignatureEnvelope = { signature?: string; key_id?: string };\n\n/** The exact bytes a manifest signature covers: the manifest JSON minus the\n *  signature envelope fields. */\nexport function canonicalStreamsBulkManifestPayload(\n\tmanifest: Record<string, unknown> & SignatureEnvelope,\n): string {\n\tconst { signature: _signature, key_id: _keyId, ...rest } = manifest;\n\treturn JSON.stringify(rest);\n}\n\nfunction normalizePem(pem: string): string {\n\t// Env transport often escapes newlines; restore real PEM line breaks.\n\treturn pem.includes(\"\\\\n\") ? pem.replace(/\\\\n/g, \"\\n\") : pem;\n}\n\n/**\n * Attach an ed25519 `signature` + `key_id` over the manifest's canonical bytes.\n * Returns a new manifest; re-signing one that already carries a signature signs\n * over its un-enveloped form (idempotent shape).\n */\nexport function signStreamsBulkManifest<\n\tT extends Record<string, unknown> & SignatureEnvelope,\n>(\n\tmanifest: T,\n\tprivateKeyPem: string,\n): T & { signature: string; key_id: string } {\n\tconst pem = normalizePem(privateKeyPem);\n\tconst privateKey = loadEd25519PrivateKey(pem);\n\tconst keyId = ed25519KeyId(publicKeyPemFromPrivate(pem));\n\tconst { signature: _signature, key_id: _keyId, ...base } = manifest;\n\tconst payload = JSON.stringify(base);\n\treturn {\n\t\t...(base as T),\n\t\tsignature: signEd25519(payload, privateKey),\n\t\tkey_id: keyId,\n\t};\n}\n\n/** Verify a manifest's ed25519 signature against the published public key. */\nexport function verifyStreamsBulkManifestSignature(\n\tmanifest: Record<string, unknown> & SignatureEnvelope,\n\tpublicKeyPem: string,\n): boolean {\n\tif (!manifest.signature) return false;\n\tconst payload = canonicalStreamsBulkManifestPayload(manifest);\n\treturn verifyEd25519(\n\t\tpayload,\n\t\tmanifest.signature,\n\t\tloadEd25519PublicKey(publicKeyPem),\n\t);\n}\n",
+    "/**\n * The archive signing key, compiled into every release.\n *\n * `secondlayer bootstrap`, `verify`, and `repair` refuse a manifest they\n * cannot verify, so a self-hosted instance with no network path to the hosted\n * API still needs a key it can trust. Shipping it here means the trust root\n * travels with the CLI rather than with whichever host answers\n * `/public/streams/signing-key`.\n *\n * Tradeoff: rotating this key is a CLI release until a root-signed key\n * ceremony lands. Operators who want a different root pin one with\n * `ARCHIVE_SIGNING_PUBLIC_KEY` or `--public-key`, which win over this value.\n *\n * Value: `GET https://api.secondlayer.tools/public/streams/signing-key`,\n * key_id `fHQWzs9ML2WIYakf`, ed25519, fetched 2026-08-27.\n */\nexport const ARCHIVE_ROOT_PUBLIC_KEY_PEM: string = [\n\t\"-----BEGIN PUBLIC KEY-----\",\n\t\"MCowBQYDK2VwAyEAq7wXm235JkFbElDmTVdNtmTKqRLx4PzjBgZhyREUFis=\",\n\t\"-----END PUBLIC KEY-----\",\n\t\"\",\n].join(\"\\n\");\n\nexport const ARCHIVE_ROOT_KEY_ID: string = \"fHQWzs9ML2WIYakf\";\n",
+    "import { createHash } from \"node:crypto\";\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join, resolve } from \"node:path\";\nimport { verifyStreamsBulkManifestSignature } from \"../streams-bulk-manifest.ts\";\nimport type { RangeDigest } from \"./range-digest.ts\";\nimport { ARCHIVE_ROOT_PUBLIC_KEY_PEM } from \"./root-key.ts\";\nimport type { PartitionSemanticDigest } from \"./semantic-digest.ts\";\n\n/**\n * Loading and trusting an archive reference — shared by the CLI and the SDK\n * so the two cannot disagree about what \"the archive says\".\n *\n * A reference is either an https URL or a local path to a snapshot manifest.\n * The SDK only passes `http(s)://` sources; local paths stay CLI. Partition\n * objects live beside the snapshot at `<root>/<dataset>/<name>.parquet`,\n * where the root is two levels above the manifest\n * (`<root>/snapshots/<digest>.json`).\n */\n\nexport type ArchivePartition = {\n\tdataset: string;\n\tfrom_block: number;\n\tto_block: number;\n\tpath: string;\n\trow_count: number;\n\tbyte_size: number;\n\tsha256: string;\n};\n\nexport type ArchiveManifest = {\n\tnetwork?: string;\n\tcoverage?: { from_block: number; to_block: number };\n\tpartition_size_blocks?: number;\n\trange_digests?: RangeDigest[];\n\tpartition_semantic_digests?: PartitionSemanticDigest[];\n\tpartitions?: ArchivePartition[];\n\tsignature?: string;\n\tkey_id?: string;\n\t[key: string]: unknown;\n};\n\nexport type LoadedReference = {\n\tmanifest: ArchiveManifest;\n\torigin: string;\n\t/** Base for resolving partition paths; a URL prefix or a directory. */\n\troot: string;\n\tisRemote: boolean;\n};\n\n/**\n * The archive root, `latest.json`, is a signed POINTER at a snapshot manifest,\n * not a manifest itself. It is also the only URL a user can be expected to\n * know, so every command accepts it and follows it — anything else makes the\n * obvious command fail with an error about digests, which reads as \"this tool\n * is broken\" rather than \"you passed the wrong file\".\n */\ntype LatestPointer = {\n\tsnapshot_path?: string;\n\tsnapshot_digest?: string;\n\tsignature?: string;\n\tkey_id?: string;\n};\n\nfunction isLatestPointer(value: ArchiveManifest): boolean {\n\tconst pointer = value as LatestPointer;\n\treturn (\n\t\ttypeof pointer.snapshot_path === \"string\" &&\n\t\t(value.partitions === undefined || value.partitions.length === 0)\n\t);\n}\n\n/** The publisher names snapshots by their content digest and nothing else\n *  (`packages/indexer/src/archive/promote-snapshot.ts`). Anything looser is\n *  a pointer someone rewrote, and it must not steer a fetch. */\nconst SNAPSHOT_PATH_PATTERN = /^snapshots\\/[0-9a-f]{64}\\.json$/;\n\nasync function fetchJson(\n\turl: string,\n\tfetchImpl: (\n\t\tinput: string | URL | Request,\n\t\tinit?: RequestInit,\n\t) => Promise<Response>,\n): Promise<unknown> {\n\tconst response = await fetchImpl(url, {\n\t\tsignal: AbortSignal.timeout(30_000),\n\t});\n\tif (!response.ok) {\n\t\tthrow new Error(\n\t\t\t`could not fetch manifest (${response.status} ${response.statusText})`,\n\t\t);\n\t}\n\treturn response.json();\n}\n\nexport type LoadReferenceOptions = {\n\t/** Key used to verify a signed `latest.json` pointer. The pointer names\n\t *  which snapshot is current, so without this an attacker holding only\n\t *  bucket write access could roll every reader back to an older, still\n\t *  validly signed, snapshot. */\n\tpublicKeyPem?: string;\n\t/** Test/SDK seam; production CLI leaves this unset and uses global fetch. */\n\tfetchImpl?: (\n\t\tinput: string | URL | Request,\n\t\tinit?: RequestInit,\n\t) => Promise<Response>;\n};\n\nexport async function loadReference(\n\tsource: string,\n\toptions: LoadReferenceOptions = {},\n): Promise<LoadedReference> {\n\tconst isRemote = /^https?:\\/\\//.test(source);\n\tconst fetchImpl = options.fetchImpl ?? globalThis.fetch;\n\tlet manifest: ArchiveManifest;\n\tlet root: string;\n\n\tif (isRemote) {\n\t\tmanifest = (await fetchJson(source, fetchImpl)) as ArchiveManifest;\n\t\tconst url = new URL(source);\n\t\t// Both `<root>/latest.json` and `<root>/snapshots/<digest>.json` resolve\n\t\t// their partition paths against `<root>`.\n\t\turl.pathname = url.pathname\n\t\t\t.replace(/\\/snapshots\\/[^/]+$/, \"\")\n\t\t\t.replace(/\\/[^/]+\\.json$/, \"\");\n\t\troot = url.toString();\n\t} else {\n\t\tconst path = resolve(source);\n\t\tmanifest = JSON.parse(await readFile(path, \"utf8\")) as ArchiveManifest;\n\t\troot = isLatestPointer(manifest) ? dirname(path) : dirname(dirname(path));\n\t}\n\n\tif (!isLatestPointer(manifest)) {\n\t\treturn { manifest, origin: source, root, isRemote };\n\t}\n\n\t// Follow the pointer, then prove it led where it claimed. A tampered\n\t// pointer could otherwise redirect to a different — and still validly\n\t// signed — snapshot, which is a downgrade attack rather than a forgery.\n\tconst pointer = manifest as ArchiveManifest & LatestPointer;\n\tconst snapshotPath = pointer.snapshot_path as string;\n\tif (!SNAPSHOT_PATH_PATTERN.test(snapshotPath)) {\n\t\tthrow new Error(\n\t\t\t`pointer names an invalid snapshot path: ${snapshotPath} (expected snapshots/<sha256>.json)`,\n\t\t);\n\t}\n\tif (\n\t\ttypeof pointer.snapshot_digest !== \"string\" ||\n\t\t!/^[0-9a-f]{64}$/.test(pointer.snapshot_digest)\n\t) {\n\t\tthrow new Error(\n\t\t\t\"pointer carries no snapshot_digest, so it cannot prove which snapshot is current\",\n\t\t);\n\t}\n\tif (pointer.signature !== undefined) {\n\t\tif (!options.publicKeyPem) {\n\t\t\tthrow new Error(\n\t\t\t\t\"pointer is signed but no public key is available to verify it\",\n\t\t\t);\n\t\t}\n\t\tlet verified = false;\n\t\ttry {\n\t\t\tverified = verifyStreamsBulkManifestSignature(\n\t\t\t\tpointer as Record<string, unknown>,\n\t\t\t\toptions.publicKeyPem,\n\t\t\t);\n\t\t} catch {\n\t\t\tverified = false;\n\t\t}\n\t\tif (!verified) {\n\t\t\tthrow new Error(\n\t\t\t\t\"pointer signature did not verify against the archive key\",\n\t\t\t);\n\t\t}\n\t}\n\n\tconst resolved = isRemote\n\t\t? ((await fetchJson(\n\t\t\t\t`${root.replace(/\\/$/, \"\")}/${snapshotPath}`,\n\t\t\t\tfetchImpl,\n\t\t\t)) as ArchiveManifest)\n\t\t: (JSON.parse(\n\t\t\t\tawait readFile(join(root, snapshotPath), \"utf8\"),\n\t\t\t) as ArchiveManifest);\n\n\tconst digest = createHash(\"sha256\")\n\t\t.update(\n\t\t\tJSON.stringify(\n\t\t\t\t(({ signature: _s, key_id: _k, ...rest }) => rest)(\n\t\t\t\t\tresolved as Record<string, unknown>,\n\t\t\t\t),\n\t\t\t),\n\t\t)\n\t\t.digest(\"hex\");\n\tif (digest !== pointer.snapshot_digest) {\n\t\tthrow new Error(\n\t\t\t`pointer/snapshot mismatch: latest.json names ${pointer.snapshot_digest}, resolved manifest hashes to ${digest}`,\n\t\t);\n\t}\n\n\treturn { manifest: resolved, origin: source, root, isRemote };\n}\n\nexport type SignatureResult = { verified: boolean; reason?: string };\n\n/**\n * An unsigned or unverifiable reference is worthless as a source of truth:\n * comparing against it yields a confident answer with nothing behind it, and\n * repairing from it would write unverified data into a live database.\n */\nexport function checkSignature(\n\tmanifest: ArchiveManifest,\n\tpublicKeyPem: string | undefined,\n\tinsecure: boolean,\n): SignatureResult {\n\tif (insecure) return { verified: false, reason: \"signature check skipped\" };\n\tif (!manifest.signature) {\n\t\treturn { verified: false, reason: \"manifest carries no signature\" };\n\t}\n\tif (!publicKeyPem) {\n\t\treturn {\n\t\t\tverified: false,\n\t\t\treason: \"no public key available to verify with\",\n\t\t};\n\t}\n\ttry {\n\t\tconst verified = verifyStreamsBulkManifestSignature(\n\t\t\tmanifest as Record<string, unknown>,\n\t\t\tpublicKeyPem,\n\t\t);\n\t\treturn {\n\t\t\tverified,\n\t\t\treason: verified ? undefined : \"signature did not verify\",\n\t\t};\n\t} catch (err) {\n\t\treturn {\n\t\t\tverified: false,\n\t\t\treason: err instanceof Error ? err.message : \"signature check failed\",\n\t\t};\n\t}\n}\n\nconst HOSTED_SIGNING_KEY_URL =\n\t\"https://api.secondlayer.tools/public/streams/signing-key\";\n\nasync function fetchHostedKey(url: string): Promise<string | undefined> {\n\t// A key fetched over plaintext is whoever sits on the wire, not a key.\n\tif (!url.startsWith(\"https://\")) return undefined;\n\ttry {\n\t\tconst response = await fetch(url, { signal: AbortSignal.timeout(10_000) });\n\t\tif (!response.ok) return undefined;\n\t\tconst body = (await response.json()) as { public_key_pem?: string };\n\t\treturn typeof body.public_key_pem === \"string\"\n\t\t\t? body.public_key_pem\n\t\t\t: undefined;\n\t} catch {\n\t\t// Offline is a legitimate state; the compiled root key still applies.\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Which key a manifest is checked against, in trust order: an explicit\n * `--public-key`, then `ARCHIVE_SIGNING_PUBLIC_KEY` / `STREAMS_SIGNING_PUBLIC_KEY`\n * from the environment, then the hosted key endpoint over https (never in OSS\n * mode, which must work with no path to api.secondlayer.tools), and finally the\n * key compiled into this release. The compiled key means a fresh self-hosted\n * instance can bootstrap offline; the tradeoff is that rotating it is a CLI\n * release. Plaintext `http://` key sources are never consulted.\n */\nexport async function resolveArchivePublicKey(input: {\n\texplicitPem?: string;\n\tenvPem?: string;\n\tallowHostedApi?: boolean;\n\t/** Test seam for the hosted endpoint; production callers leave it unset. */\n\thostedKeyUrl?: string;\n}): Promise<string> {\n\tif (input.explicitPem) return input.explicitPem;\n\tif (input.envPem) return input.envPem;\n\tif (input.allowHostedApi) {\n\t\tconst hosted = await fetchHostedKey(\n\t\t\tinput.hostedKeyUrl ?? HOSTED_SIGNING_KEY_URL,\n\t\t);\n\t\tif (hosted) return hosted;\n\t}\n\treturn ARCHIVE_ROOT_PUBLIC_KEY_PEM;\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "C1F257F42AE1841A64756E2164756E21",
+  "names": []
+}

package/dist/src/index-http.js

@@ -19,6 +19,7 @@ var INDEX_INTERNAL_TENANT_ID = "tenant_index_internal";
 var INTERNAL_STREAMS_TENANT_ID = "tenant_streams_decode_internal";
 var DEFAULT_INTERNAL_INDEX_BASE_URL = "http://api:3800";
 var MISSING_INTERNAL_STREAMS_API_KEY = "Set STREAMS_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Empty env no longer falls back to a committed secret.";
+var MISSING_INTERNAL_INDEX_API_KEY = "Set INDEX_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Without one, Index reads go out anonymously and are capped at the last 24h, so any seek into older history 402s.";
 function defaultInternalIndexApiKey(env = process.env) {
   const internal = env.INDEX_INTERNAL_API_KEY?.trim();
   if (internal)
@@ -37,6 +38,12 @@ function defaultInternalStreamsApiKey(env = process.env) {
     return instance;
   return;
 }
+function requireInternalIndexApiKey(env = process.env) {
+  const key = defaultInternalIndexApiKey(env);
+  if (!key)
+    throw new Error(MISSING_INTERNAL_INDEX_API_KEY);
+  return key;
+}
 function requireInternalStreamsApiKey(env = process.env) {
   const key = defaultInternalStreamsApiKey(env);
   if (!key)
@@ -179,5 +186,5 @@ export {
   IndexHttpClient
 };
 
-//# debugId=F69B8DFD070B8FFC64756E2164756E21
+//# debugId=1D8416E6B0F3E28D64756E2164756E21
 //# sourceMappingURL=index-http.js.map

package/dist/src/index-http.js.map

@@ -2,10 +2,10 @@
   "version": 3,
   "sources": ["../src/index-internal-auth.ts", "../src/index-http.ts"],
   "sourcesContent": [
-    "// Internal service credentials for first-party consumers of /v1/index and\n// /v1/streams over HTTP (decoder, subgraph processor PublicApiBlockSource).\n// Seeded as internal tenants with NO account_id, so these reads are\n// unmetered (metering gates on account_id). Lives in shared so the API (seed)\n// and the consumers import it without a cycle.\n//\n// Resolution: STREAMS_INTERNAL_API_KEY / INDEX_INTERNAL_API_KEY, then\n// INSTANCE_TOKEN (OSS). No committed fallback. Empty-string env values fall\n// through (`trim()`, then empty): compose interpolates\n// `${STREAMS_INTERNAL_API_KEY:-}` which is \"\" when unset.\n//\n// Archive keys must not use the `sk-sl_` prefix; generate with `sl-int_`.\n// OSS compose should omit the internal env and send INSTANCE_TOKEN.\nexport const INDEX_INTERNAL_TENANT_ID = \"tenant_index_internal\";\nexport const INTERNAL_STREAMS_TENANT_ID = \"tenant_streams_decode_internal\";\n\nconst DEFAULT_INTERNAL_INDEX_BASE_URL = \"http://api:3800\";\n\nconst MISSING_INTERNAL_STREAMS_API_KEY =\n\t\"Set STREAMS_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Empty env no longer falls back to a committed secret.\";\n\nexport function defaultInternalIndexApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.INDEX_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\nexport function defaultInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.STREAMS_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\n/** Decoder startup: refuse to run with neither credential. */\nexport function requireInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string {\n\tconst key = defaultInternalStreamsApiKey(env);\n\tif (!key) throw new Error(MISSING_INTERNAL_STREAMS_API_KEY);\n\treturn key;\n}\n\n/** Shared env contract for decoder + subgraph HTTP dogfood. */\nexport function defaultInternalIndexBaseUrl(): string {\n\treturn (\n\t\tprocess.env.SUBGRAPH_INDEX_API_URL ||\n\t\tprocess.env.STREAMS_API_URL ||\n\t\tDEFAULT_INTERNAL_INDEX_BASE_URL\n\t);\n}\n",
+    "// Internal service credentials for first-party consumers of /v1/index and\n// /v1/streams over HTTP (decoder, subgraph processor PublicApiBlockSource).\n// Seeded as internal tenants with NO account_id, so these reads are\n// unmetered (metering gates on account_id). Lives in shared so the API (seed)\n// and the consumers import it without a cycle.\n//\n// Resolution: STREAMS_INTERNAL_API_KEY / INDEX_INTERNAL_API_KEY, then\n// INSTANCE_TOKEN (OSS). No committed fallback. Empty-string env values fall\n// through (`trim()`, then empty): compose interpolates\n// `${STREAMS_INTERNAL_API_KEY:-}` which is \"\" when unset.\n//\n// Archive keys must not use the `sk-sl_` prefix; generate with `sl-int_`.\n// OSS compose should omit the internal env and send INSTANCE_TOKEN.\nexport const INDEX_INTERNAL_TENANT_ID = \"tenant_index_internal\";\nexport const INTERNAL_STREAMS_TENANT_ID = \"tenant_streams_decode_internal\";\n\nconst DEFAULT_INTERNAL_INDEX_BASE_URL = \"http://api:3800\";\n\nconst MISSING_INTERNAL_STREAMS_API_KEY =\n\t\"Set STREAMS_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Empty env no longer falls back to a committed secret.\";\n\nconst MISSING_INTERNAL_INDEX_API_KEY =\n\t\"Set INDEX_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Without one, Index reads go out anonymously and are capped at the last 24h, so any seek into older history 402s.\";\n\nexport function defaultInternalIndexApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.INDEX_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\nexport function defaultInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.STREAMS_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\n/**\n * Platform-mode Index consumer: refuse to run with neither credential.\n *\n * A keyless Index read is not an error — it is an anonymous read, and the API\n * serves it for the last 24h (`api/src/index/free-window.ts`). That makes a\n * missing key invisible right up until a consumer's cursor falls out of the\n * window, at which point every read 402s and the container goes unhealthy,\n * possibly weeks after the misconfiguration. Callers that seek older history\n * on a platform-mode instance should fail here at startup instead.\n *\n * Self-hosted (oss/dedicated) instances are not gated, so they must NOT call\n * this — `defaultInternalIndexApiKey()` returning undefined is correct there.\n */\nexport function requireInternalIndexApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string {\n\tconst key = defaultInternalIndexApiKey(env);\n\tif (!key) throw new Error(MISSING_INTERNAL_INDEX_API_KEY);\n\treturn key;\n}\n\n/** Decoder startup: refuse to run with neither credential. */\nexport function requireInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string {\n\tconst key = defaultInternalStreamsApiKey(env);\n\tif (!key) throw new Error(MISSING_INTERNAL_STREAMS_API_KEY);\n\treturn key;\n}\n\n/** Shared env contract for decoder + subgraph HTTP dogfood. */\nexport function defaultInternalIndexBaseUrl(): string {\n\treturn (\n\t\tprocess.env.SUBGRAPH_INDEX_API_URL ||\n\t\tprocess.env.STREAMS_API_URL ||\n\t\tDEFAULT_INTERNAL_INDEX_BASE_URL\n\t);\n}\n",
     "import {\n\tdefaultInternalIndexApiKey,\n\tdefaultInternalIndexBaseUrl,\n\tdefaultInternalStreamsApiKey,\n} from \"./index-internal-auth.ts\";\n\n/**\n * Low-level transport for the public Index (`/v1/index`) + Streams clock\n * (`/v1/streams`) HTTP APIs: cursor-paginated reads, tip, reorgs. Lives in\n * `shared` (a leaf both the SDK and the subgraph runtime depend on) so the wire\n * format has one home and no package cycle. The SDK's ergonomic client should\n * eventually consume these row types too (see the plan's convergence task).\n *\n * This is intentionally minimal — just the GETs the subgraph runtime's\n * PublicApiBlockSource needs. It is NOT the SDK's full client (walk/consume/\n * retries/auth resolution).\n */\n\nconst PAGE_LIMIT = 1000;\n\n// Transport resilience for the streams-index data plane. The api runs N>1\n// replicas behind Caddy; during a rolling deploy one replica is briefly\n// unreachable, surfacing as a thrown fetch (connection refused/reset) or a\n// Caddy 502/503/504 while it fails over. Retrying a few times with backoff\n// makes a single-replica recreate transparent to the subgraph-processor /\n// decoder — closing the processors-depend-on-api coupling.\nconst MAX_ATTEMPTS = 4;\nconst RETRY_BASE_MS = 150;\nconst RETRYABLE_STATUS = new Set([502, 503, 504]);\n\nconst delay = (ms: number): Promise<void> =>\n\tnew Promise((resolve) => setTimeout(resolve, ms));\n\ntype Envelope<K extends string, T> = {\n\t[P in K]: T[];\n} & { next_cursor: string | null };\n\n// ── Index API wire shapes (single source of truth) ─────────────────────────\nexport type IndexBlockRow = {\n\tblock_height: number;\n\tblock_hash: string;\n\tparent_hash: string;\n\tburn_block_height: number;\n\tburn_block_hash: string | null;\n\t/** Nakamoto StacksBlockId. Absent from pre-2026-07 API deployments. */\n\tindex_block_hash?: string | null;\n\tblock_time: string | null;\n};\n\ntype IndexEventCommon = {\n\tblock_height: number;\n\ttx_id: string;\n\ttx_index?: number;\n\tevent_index: number;\n\tcontract_id: string | null;\n\t/** Submitting-tx context — present only when the read passed `tx_context=true`.\n\t *  Lets a consumer build the tx for `ctx.tx` without a separate\n\t *  walkTransactions (the ~37x reindex over-fetch; see indexing-speed plan). */\n\ttx_sender?: string | null;\n\ttx_type?: string | null;\n\ttx_status?: string | null;\n\ttx_contract_id?: string | null;\n\ttx_function_name?: string | null;\n};\n\nexport type IndexEventRow = IndexEventCommon &\n\t(\n\t\t| {\n\t\t\t\tevent_type: \"ft_transfer\" | \"ft_mint\" | \"ft_burn\";\n\t\t\t\tasset_identifier: string;\n\t\t\t\tsender?: string;\n\t\t\t\trecipient?: string;\n\t\t\t\tamount: string;\n\t\t  }\n\t\t| {\n\t\t\t\tevent_type: \"nft_transfer\" | \"nft_mint\" | \"nft_burn\";\n\t\t\t\tasset_identifier: string;\n\t\t\t\tsender?: string;\n\t\t\t\trecipient?: string;\n\t\t\t\tvalue: string;\n\t\t  }\n\t\t| {\n\t\t\t\tevent_type: \"stx_transfer\" | \"stx_mint\" | \"stx_burn\";\n\t\t\t\tsender?: string;\n\t\t\t\trecipient?: string;\n\t\t\t\tamount: string;\n\t\t\t\tmemo?: string | null;\n\t\t  }\n\t\t| {\n\t\t\t\tevent_type: \"stx_lock\";\n\t\t\t\tsender: string;\n\t\t\t\tamount: string;\n\t\t\t\tpayload: { unlock_height: string | null };\n\t\t  }\n\t\t| {\n\t\t\t\tevent_type: \"print\";\n\t\t\t\tpayload: {\n\t\t\t\t\ttopic: string | null;\n\t\t\t\t\tvalue: unknown;\n\t\t\t\t\traw_value: string | null;\n\t\t\t\t};\n\t\t  }\n\t);\n\nexport type IndexTransactionRow = {\n\ttx_id: string;\n\tblock_height: number;\n\tblock_time?: string | null;\n\tburn_block_height?: number | null;\n\ttx_index: number;\n\ttx_type: string;\n\tsender: string;\n\tstatus: string;\n\tcontract_call?: {\n\t\tcontract_id: string;\n\t\tfunction_name: string;\n\t\tfunction_args_hex?: string[] | null;\n\t\tresult_hex?: string | null;\n\t} | null;\n\tsmart_contract?: { contract_id: string | null } | null;\n};\n\nexport type StreamsReorgRow = {\n\tid: string;\n\tdetected_at: string;\n\tfork_point_height: number;\n\torphaned_range: { from: string; to: string };\n\tnew_canonical_tip: string;\n};\n\nexport type IndexHttpOptions = {\n\t/** Base URL for /v1/index (the decoded data plane). */\n\tindexBaseUrl: string;\n\t/** Bearer for /v1/index. Empty/unset omits the header. */\n\tindexApiKey?: string;\n\t/** Base URL for /v1/streams (the canonical clock). */\n\tstreamsBaseUrl: string;\n\t/** Bearer for /v1/streams. Empty/unset omits the header. */\n\tstreamsApiKey?: string;\n};\n\nexport class IndexHttpClient {\n\tprivate readonly indexBaseUrl: string;\n\tprivate readonly indexApiKey: string | undefined;\n\tprivate readonly streamsBaseUrl: string;\n\tprivate readonly streamsApiKey: string | undefined;\n\n\tconstructor(opts: IndexHttpOptions) {\n\t\tthis.indexBaseUrl = opts.indexBaseUrl.replace(/\\/+$/, \"\");\n\t\tthis.indexApiKey = opts.indexApiKey ?? defaultInternalIndexApiKey();\n\t\tthis.streamsBaseUrl = opts.streamsBaseUrl.replace(/\\/+$/, \"\");\n\t\tthis.streamsApiKey = opts.streamsApiKey;\n\t}\n\n\tprivate async get<T>(url: string, apiKey: string | undefined): Promise<T> {\n\t\t// Index reads are anon — omit the header entirely when no key is set, so\n\t\t// an empty key reads anonymously rather than 401-ing as an invalid bearer.\n\t\tconst headers: Record<string, string> = apiKey\n\t\t\t? { authorization: `Bearer ${apiKey}` }\n\t\t\t: {};\n\t\tlet lastErr: unknown;\n\t\tfor (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {\n\t\t\tlet res: Response;\n\t\t\ttry {\n\t\t\t\tres = await fetch(url, { headers });\n\t\t\t} catch (err) {\n\t\t\t\t// An explicit abort/cancel is intentional — surface it immediately\n\t\t\t\t// rather than burning the retry budget masking it as transient.\n\t\t\t\tif (err instanceof Error && err.name === \"AbortError\") throw err;\n\t\t\t\t// Otherwise a transport-level failure (connection refused/reset) —\n\t\t\t\t// e.g. an api replica mid-recreate. Retry; the next attempt\n\t\t\t\t// round-robins to a healthy replica.\n\t\t\t\tlastErr = err;\n\t\t\t\tif (attempt >= MAX_ATTEMPTS) break;\n\t\t\t\tawait delay(RETRY_BASE_MS * 2 ** (attempt - 1));\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (!res.ok) {\n\t\t\t\tif (RETRYABLE_STATUS.has(res.status) && attempt < MAX_ATTEMPTS) {\n\t\t\t\t\t// Drain the body so the connection can be reused, then back off.\n\t\t\t\t\tawait res.text().catch(() => {});\n\t\t\t\t\tawait delay(RETRY_BASE_MS * 2 ** (attempt - 1));\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t\tthrow new Error(`GET ${url} → ${res.status} ${await res.text()}`);\n\t\t\t}\n\t\t\treturn (await res.json()) as T;\n\t\t}\n\t\tthrow (\n\t\t\tlastErr ?? new Error(`GET ${url} failed after ${MAX_ATTEMPTS} attempts`)\n\t\t);\n\t}\n\n\t/** Fetch a single cursor page of an Index collection. */\n\tprivate async getPage<K extends string, T>(\n\t\tpath: string,\n\t\tkey: K,\n\t\tparams: URLSearchParams,\n\t): Promise<{ items: T[]; next_cursor: string | null }> {\n\t\tconst env: Envelope<K, T> = await this.get(\n\t\t\t`${this.indexBaseUrl}${path}?${params}`,\n\t\t\tthis.indexApiKey,\n\t\t);\n\t\treturn { items: env[key], next_cursor: env.next_cursor };\n\t}\n\n\t/** Drain a cursor-paginated Index collection over [fromHeight, toHeight]. */\n\tprivate async walk<K extends string, T>(\n\t\tpath: string,\n\t\tkey: K,\n\t\tfromHeight: number,\n\t\ttoHeight: number,\n\t\textraParams: Record<string, string> = {},\n\t): Promise<T[]> {\n\t\tconst out: T[] = [];\n\t\tlet cursor: string | null = null;\n\t\tdo {\n\t\t\tconst params = new URLSearchParams({\n\t\t\t\tto_height: String(toHeight),\n\t\t\t\tlimit: String(PAGE_LIMIT),\n\t\t\t\t...extraParams,\n\t\t\t});\n\t\t\t// from_height and cursor are mutually exclusive — anchor the first page\n\t\t\t// by height, then page forward by cursor only.\n\t\t\tif (cursor) params.set(\"cursor\", cursor);\n\t\t\telse params.set(\"from_height\", String(fromHeight));\n\t\t\tconst { items, next_cursor } = await this.getPage<K, T>(\n\t\t\t\tpath,\n\t\t\t\tkey,\n\t\t\t\tparams,\n\t\t\t);\n\t\t\tout.push(...items);\n\t\t\tcursor = next_cursor;\n\t\t} while (cursor);\n\t\treturn out;\n\t}\n\n\t/**\n\t * Fetch ONE page of contract-call transactions filtered to `contractId`.\n\t * Unlike walk(), this does NOT drain — the caller pages by feeding back\n\t * next_cursor — so a sparse high-volume filter (e.g. a single contract over\n\t * all history) costs one request per batch, not O(all-history) per tick.\n\t * `cursor` is exclusive (rows strictly after it); on the first call pass\n\t * `fromHeight` to anchor the backfill start instead.\n\t */\n\tasync fetchContractCalls(\n\t\tcontractId: string,\n\t\topts: {\n\t\t\ttoHeight: number;\n\t\t\tcursor?: string | null;\n\t\t\tfromHeight?: number;\n\t\t\tlimit?: number;\n\t\t},\n\t): Promise<{\n\t\ttransactions: IndexTransactionRow[];\n\t\tnext_cursor: string | null;\n\t}> {\n\t\tconst params = new URLSearchParams({\n\t\t\tto_height: String(opts.toHeight),\n\t\t\tlimit: String(opts.limit ?? PAGE_LIMIT),\n\t\t\tcontract_id: contractId,\n\t\t});\n\t\tif (opts.cursor) params.set(\"cursor\", opts.cursor);\n\t\telse params.set(\"from_height\", String(opts.fromHeight ?? 0));\n\t\tconst { items, next_cursor } = await this.getPage<\n\t\t\t\"transactions\",\n\t\t\tIndexTransactionRow\n\t\t>(\"/v1/index/transactions\", \"transactions\", params);\n\t\treturn { transactions: items, next_cursor };\n\t}\n\n\twalkBlocks(fromHeight: number, toHeight: number): Promise<IndexBlockRow[]> {\n\t\treturn this.walk<\"blocks\", IndexBlockRow>(\n\t\t\t\"/v1/index/blocks\",\n\t\t\t\"blocks\",\n\t\t\tfromHeight,\n\t\t\ttoHeight,\n\t\t);\n\t}\n\n\t/** Lowest block height in [fromHeight, toHeight] with a matching event, or\n\t *  null. One page, limit 1 — built for sparse-scan probes. */\n\tasync firstEventHeight(\n\t\teventType: string,\n\t\tfromHeight: number,\n\t\ttoHeight: number,\n\t\tcontractId?: string,\n\t): Promise<number | null> {\n\t\tconst params = new URLSearchParams({\n\t\t\tevent_type: eventType,\n\t\t\tfrom_height: String(fromHeight),\n\t\t\tto_height: String(toHeight),\n\t\t\tlimit: \"1\",\n\t\t\t...(contractId ? { contract_id: contractId } : {}),\n\t\t});\n\t\tconst { items } = await this.getPage<\"events\", IndexEventRow>(\n\t\t\t\"/v1/index/events\",\n\t\t\t\"events\",\n\t\t\tparams,\n\t\t);\n\t\treturn items[0]?.block_height ?? null;\n\t}\n\n\twalkEvents(\n\t\teventType: string,\n\t\tfromHeight: number,\n\t\ttoHeight: number,\n\t\t/** Join the submitting tx so each row carries `tx_*` — lets an event-only\n\t\t *  subgraph skip walkTransactions and build `ctx.tx` from the event. */\n\t\twithTx = false,\n\t): Promise<IndexEventRow[]> {\n\t\treturn this.walk<\"events\", IndexEventRow>(\n\t\t\t\"/v1/index/events\",\n\t\t\t\"events\",\n\t\t\tfromHeight,\n\t\t\ttoHeight,\n\t\t\t{\n\t\t\t\tevent_type: eventType,\n\t\t\t\t...(withTx ? { tx_context: \"true\" } : {}),\n\t\t\t},\n\t\t);\n\t}\n\n\twalkTransactions(\n\t\tfromHeight: number,\n\t\ttoHeight: number,\n\t): Promise<IndexTransactionRow[]> {\n\t\treturn this.walk<\"transactions\", IndexTransactionRow>(\n\t\t\t\"/v1/index/transactions\",\n\t\t\t\"transactions\",\n\t\t\tfromHeight,\n\t\t\ttoHeight,\n\t\t);\n\t}\n\n\t/** Canonical tip height from the Streams clock. */\n\tasync getStreamsTip(): Promise<number> {\n\t\tconst tip = await this.get<{ block_height: number }>(\n\t\t\t`${this.streamsBaseUrl}/v1/streams/tip`,\n\t\t\tthis.streamsApiKey,\n\t\t);\n\t\treturn Number(tip.block_height) || 0;\n\t}\n\n\t/**\n\t * Highest block height the Index data plane can serve (tip is inline in every\n\t * envelope). This is the data-availability bound — a consumer must not\n\t * process past it, even if the Streams clock is ahead.\n\t */\n\tasync getIndexTip(): Promise<number> {\n\t\tconst env = await this.get<{ tip: { block_height: number } }>(\n\t\t\t`${this.indexBaseUrl}/v1/index/blocks?limit=1`,\n\t\t\tthis.indexApiKey,\n\t\t);\n\t\treturn Number(env.tip?.block_height) || 0;\n\t}\n\n\t/** Reorgs since a resume token (wall-clock `detected_at`-keyed). */\n\tasync listReorgs(\n\t\tsince: string,\n\t): Promise<{ reorgs: StreamsReorgRow[]; next_since: string | null }> {\n\t\tconst params = new URLSearchParams({ since });\n\t\treturn this.get(\n\t\t\t`${this.streamsBaseUrl}/v1/streams/reorgs?${params}`,\n\t\t\tthis.streamsApiKey,\n\t\t);\n\t}\n}\n\n/** Decoder + subgraph processor client. One env contract; omits bearer when no key. */\nexport function createInternalIndexHttpClient(): IndexHttpClient {\n\tconst baseUrl = defaultInternalIndexBaseUrl();\n\treturn new IndexHttpClient({\n\t\tindexBaseUrl: baseUrl,\n\t\tstreamsBaseUrl: baseUrl,\n\t\tindexApiKey: defaultInternalIndexApiKey(),\n\t\tstreamsApiKey: defaultInternalStreamsApiKey(),\n\t});\n}\n"
   ],
-  "mappings": "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",
-  "debugId": "F69B8DFD070B8FFC64756E2164756E21",
+  "mappings": "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",
+  "debugId": "1D8416E6B0F3E28D64756E2164756E21",
   "names": []
 }

package/dist/src/index-internal-auth.d.ts

@@ -2,8 +2,22 @@ declare const INDEX_INTERNAL_TENANT_ID = "tenant_index_internal";
 declare const INTERNAL_STREAMS_TENANT_ID = "tenant_streams_decode_internal";
 declare function defaultInternalIndexApiKey(env?: NodeJS.ProcessEnv): string | undefined;
 declare function defaultInternalStreamsApiKey(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+* Platform-mode Index consumer: refuse to run with neither credential.
+*
+* A keyless Index read is not an error — it is an anonymous read, and the API
+* serves it for the last 24h (`api/src/index/free-window.ts`). That makes a
+* missing key invisible right up until a consumer's cursor falls out of the
+* window, at which point every read 402s and the container goes unhealthy,
+* possibly weeks after the misconfiguration. Callers that seek older history
+* on a platform-mode instance should fail here at startup instead.
+*
+* Self-hosted (oss/dedicated) instances are not gated, so they must NOT call
+* this — `defaultInternalIndexApiKey()` returning undefined is correct there.
+*/
+declare function requireInternalIndexApiKey(env?: NodeJS.ProcessEnv): string;
 /** Decoder startup: refuse to run with neither credential. */
 declare function requireInternalStreamsApiKey(env?: NodeJS.ProcessEnv): string;
 /** Shared env contract for decoder + subgraph HTTP dogfood. */
 declare function defaultInternalIndexBaseUrl(): string;
-export { requireInternalStreamsApiKey, defaultInternalStreamsApiKey, defaultInternalIndexBaseUrl, defaultInternalIndexApiKey, INTERNAL_STREAMS_TENANT_ID, INDEX_INTERNAL_TENANT_ID };
+export { requireInternalStreamsApiKey, requireInternalIndexApiKey, defaultInternalStreamsApiKey, defaultInternalIndexBaseUrl, defaultInternalIndexApiKey, INTERNAL_STREAMS_TENANT_ID, INDEX_INTERNAL_TENANT_ID };

package/dist/src/index-internal-auth.js

@@ -19,6 +19,7 @@ var INDEX_INTERNAL_TENANT_ID = "tenant_index_internal";
 var INTERNAL_STREAMS_TENANT_ID = "tenant_streams_decode_internal";
 var DEFAULT_INTERNAL_INDEX_BASE_URL = "http://api:3800";
 var MISSING_INTERNAL_STREAMS_API_KEY = "Set STREAMS_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Empty env no longer falls back to a committed secret.";
+var MISSING_INTERNAL_INDEX_API_KEY = "Set INDEX_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Without one, Index reads go out anonymously and are capped at the last 24h, so any seek into older history 402s.";
 function defaultInternalIndexApiKey(env = process.env) {
   const internal = env.INDEX_INTERNAL_API_KEY?.trim();
   if (internal)
@@ -37,6 +38,12 @@ function defaultInternalStreamsApiKey(env = process.env) {
     return instance;
   return;
 }
+function requireInternalIndexApiKey(env = process.env) {
+  const key = defaultInternalIndexApiKey(env);
+  if (!key)
+    throw new Error(MISSING_INTERNAL_INDEX_API_KEY);
+  return key;
+}
 function requireInternalStreamsApiKey(env = process.env) {
   const key = defaultInternalStreamsApiKey(env);
   if (!key)
@@ -48,6 +55,7 @@ function defaultInternalIndexBaseUrl() {
 }
 export {
   requireInternalStreamsApiKey,
+  requireInternalIndexApiKey,
   defaultInternalStreamsApiKey,
   defaultInternalIndexBaseUrl,
   defaultInternalIndexApiKey,
@@ -55,5 +63,5 @@ export {
   INDEX_INTERNAL_TENANT_ID
 };
 
-//# debugId=CD1CACB1473B873D64756E2164756E21
+//# debugId=D4294FDC89E3160364756E2164756E21
 //# sourceMappingURL=index-internal-auth.js.map

package/dist/src/index-internal-auth.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["../src/index-internal-auth.ts"],
   "sourcesContent": [
-    "// Internal service credentials for first-party consumers of /v1/index and\n// /v1/streams over HTTP (decoder, subgraph processor PublicApiBlockSource).\n// Seeded as internal tenants with NO account_id, so these reads are\n// unmetered (metering gates on account_id). Lives in shared so the API (seed)\n// and the consumers import it without a cycle.\n//\n// Resolution: STREAMS_INTERNAL_API_KEY / INDEX_INTERNAL_API_KEY, then\n// INSTANCE_TOKEN (OSS). No committed fallback. Empty-string env values fall\n// through (`trim()`, then empty): compose interpolates\n// `${STREAMS_INTERNAL_API_KEY:-}` which is \"\" when unset.\n//\n// Archive keys must not use the `sk-sl_` prefix; generate with `sl-int_`.\n// OSS compose should omit the internal env and send INSTANCE_TOKEN.\nexport const INDEX_INTERNAL_TENANT_ID = \"tenant_index_internal\";\nexport const INTERNAL_STREAMS_TENANT_ID = \"tenant_streams_decode_internal\";\n\nconst DEFAULT_INTERNAL_INDEX_BASE_URL = \"http://api:3800\";\n\nconst MISSING_INTERNAL_STREAMS_API_KEY =\n\t\"Set STREAMS_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Empty env no longer falls back to a committed secret.\";\n\nexport function defaultInternalIndexApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.INDEX_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\nexport function defaultInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.STREAMS_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\n/** Decoder startup: refuse to run with neither credential. */\nexport function requireInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string {\n\tconst key = defaultInternalStreamsApiKey(env);\n\tif (!key) throw new Error(MISSING_INTERNAL_STREAMS_API_KEY);\n\treturn key;\n}\n\n/** Shared env contract for decoder + subgraph HTTP dogfood. */\nexport function defaultInternalIndexBaseUrl(): string {\n\treturn (\n\t\tprocess.env.SUBGRAPH_INDEX_API_URL ||\n\t\tprocess.env.STREAMS_API_URL ||\n\t\tDEFAULT_INTERNAL_INDEX_BASE_URL\n\t);\n}\n"
+    "// Internal service credentials for first-party consumers of /v1/index and\n// /v1/streams over HTTP (decoder, subgraph processor PublicApiBlockSource).\n// Seeded as internal tenants with NO account_id, so these reads are\n// unmetered (metering gates on account_id). Lives in shared so the API (seed)\n// and the consumers import it without a cycle.\n//\n// Resolution: STREAMS_INTERNAL_API_KEY / INDEX_INTERNAL_API_KEY, then\n// INSTANCE_TOKEN (OSS). No committed fallback. Empty-string env values fall\n// through (`trim()`, then empty): compose interpolates\n// `${STREAMS_INTERNAL_API_KEY:-}` which is \"\" when unset.\n//\n// Archive keys must not use the `sk-sl_` prefix; generate with `sl-int_`.\n// OSS compose should omit the internal env and send INSTANCE_TOKEN.\nexport const INDEX_INTERNAL_TENANT_ID = \"tenant_index_internal\";\nexport const INTERNAL_STREAMS_TENANT_ID = \"tenant_streams_decode_internal\";\n\nconst DEFAULT_INTERNAL_INDEX_BASE_URL = \"http://api:3800\";\n\nconst MISSING_INTERNAL_STREAMS_API_KEY =\n\t\"Set STREAMS_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Empty env no longer falls back to a committed secret.\";\n\nconst MISSING_INTERNAL_INDEX_API_KEY =\n\t\"Set INDEX_INTERNAL_API_KEY (archive; prefix sl-int_) or INSTANCE_TOKEN (OSS). Without one, Index reads go out anonymously and are capped at the last 24h, so any seek into older history 402s.\";\n\nexport function defaultInternalIndexApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.INDEX_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\nexport function defaultInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string | undefined {\n\tconst internal = env.STREAMS_INTERNAL_API_KEY?.trim();\n\tif (internal) return internal;\n\tconst instance = env.INSTANCE_TOKEN?.trim();\n\tif (instance) return instance;\n\treturn undefined;\n}\n\n/**\n * Platform-mode Index consumer: refuse to run with neither credential.\n *\n * A keyless Index read is not an error — it is an anonymous read, and the API\n * serves it for the last 24h (`api/src/index/free-window.ts`). That makes a\n * missing key invisible right up until a consumer's cursor falls out of the\n * window, at which point every read 402s and the container goes unhealthy,\n * possibly weeks after the misconfiguration. Callers that seek older history\n * on a platform-mode instance should fail here at startup instead.\n *\n * Self-hosted (oss/dedicated) instances are not gated, so they must NOT call\n * this — `defaultInternalIndexApiKey()` returning undefined is correct there.\n */\nexport function requireInternalIndexApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string {\n\tconst key = defaultInternalIndexApiKey(env);\n\tif (!key) throw new Error(MISSING_INTERNAL_INDEX_API_KEY);\n\treturn key;\n}\n\n/** Decoder startup: refuse to run with neither credential. */\nexport function requireInternalStreamsApiKey(\n\tenv: NodeJS.ProcessEnv = process.env,\n): string {\n\tconst key = defaultInternalStreamsApiKey(env);\n\tif (!key) throw new Error(MISSING_INTERNAL_STREAMS_API_KEY);\n\treturn key;\n}\n\n/** Shared env contract for decoder + subgraph HTTP dogfood. */\nexport function defaultInternalIndexBaseUrl(): string {\n\treturn (\n\t\tprocess.env.SUBGRAPH_INDEX_API_URL ||\n\t\tprocess.env.STREAMS_API_URL ||\n\t\tDEFAULT_INTERNAL_INDEX_BASE_URL\n\t);\n}\n"
   ],
-  "mappings": ";;;;;;;;;;;;;;;;;AAaO,IAAM,2BAA2B;AACjC,IAAM,6BAA6B;AAE1C,IAAM,kCAAkC;AAExC,IAAM,mCACL;AAEM,SAAS,0BAA0B,CACzC,MAAyB,QAAQ,KACZ;AAAA,EACrB,MAAM,WAAW,IAAI,wBAAwB,KAAK;AAAA,EAClD,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB,MAAM,WAAW,IAAI,gBAAgB,KAAK;AAAA,EAC1C,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB;AAAA;AAGM,SAAS,4BAA4B,CAC3C,MAAyB,QAAQ,KACZ;AAAA,EACrB,MAAM,WAAW,IAAI,0BAA0B,KAAK;AAAA,EACpD,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB,MAAM,WAAW,IAAI,gBAAgB,KAAK;AAAA,EAC1C,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB;AAAA;AAIM,SAAS,4BAA4B,CAC3C,MAAyB,QAAQ,KACxB;AAAA,EACT,MAAM,MAAM,6BAA6B,GAAG;AAAA,EAC5C,IAAI,CAAC;AAAA,IAAK,MAAM,IAAI,MAAM,gCAAgC;AAAA,EAC1D,OAAO;AAAA;AAID,SAAS,2BAA2B,GAAW;AAAA,EACrD,OACC,QAAQ,IAAI,0BACZ,QAAQ,IAAI,mBACZ;AAAA;",
-  "debugId": "CD1CACB1473B873D64756E2164756E21",
+  "mappings": ";;;;;;;;;;;;;;;;;AAaO,IAAM,2BAA2B;AACjC,IAAM,6BAA6B;AAE1C,IAAM,kCAAkC;AAExC,IAAM,mCACL;AAED,IAAM,iCACL;AAEM,SAAS,0BAA0B,CACzC,MAAyB,QAAQ,KACZ;AAAA,EACrB,MAAM,WAAW,IAAI,wBAAwB,KAAK;AAAA,EAClD,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB,MAAM,WAAW,IAAI,gBAAgB,KAAK;AAAA,EAC1C,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB;AAAA;AAGM,SAAS,4BAA4B,CAC3C,MAAyB,QAAQ,KACZ;AAAA,EACrB,MAAM,WAAW,IAAI,0BAA0B,KAAK;AAAA,EACpD,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB,MAAM,WAAW,IAAI,gBAAgB,KAAK;AAAA,EAC1C,IAAI;AAAA,IAAU,OAAO;AAAA,EACrB;AAAA;AAgBM,SAAS,0BAA0B,CACzC,MAAyB,QAAQ,KACxB;AAAA,EACT,MAAM,MAAM,2BAA2B,GAAG;AAAA,EAC1C,IAAI,CAAC;AAAA,IAAK,MAAM,IAAI,MAAM,8BAA8B;AAAA,EACxD,OAAO;AAAA;AAID,SAAS,4BAA4B,CAC3C,MAAyB,QAAQ,KACxB;AAAA,EACT,MAAM,MAAM,6BAA6B,GAAG;AAAA,EAC5C,IAAI,CAAC;AAAA,IAAK,MAAM,IAAI,MAAM,gCAAgC;AAAA,EAC1D,OAAO;AAAA;AAID,SAAS,2BAA2B,GAAW;AAAA,EACrD,OACC,QAAQ,IAAI,0BACZ,QAAQ,IAAI,mBACZ;AAAA;",
+  "debugId": "D4294FDC89E3160364756E2164756E21",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@secondlayer/shared",
-	"version": "11.2.0",
+	"version": "11.3.0",
 	"description": "Internal building blocks shared across Secondlayer packages.",
 	"license": "MIT",
 	"repository": {
@@ -141,6 +141,10 @@
 			"types": "./dist/src/archive/key-registry.d.ts",
 			"import": "./dist/src/archive/key-registry.js"
 		},
+		"./archive/reference": {
+			"types": "./dist/src/archive/reference.d.ts",
+			"import": "./dist/src/archive/reference.js"
+		},
 		"./archive/copy-loader": {
 			"types": "./dist/src/archive/copy-loader.d.ts",
 			"import": "./dist/src/archive/copy-loader.js"
@@ -165,6 +169,10 @@
 			"types": "./dist/src/archive/derived-stage-report.d.ts",
 			"import": "./dist/src/archive/derived-stage-report.js"
 		},
+		"./archive/instance-diagnosis": {
+			"types": "./dist/src/archive/instance-diagnosis.d.ts",
+			"import": "./dist/src/archive/instance-diagnosis.js"
+		},
 		"./coverage": {
 			"types": "./dist/src/coverage/index.d.ts",
 			"import": "./dist/src/coverage/index.js"