pi-mega-compact 0.19.2 → 0.20.0

package/src/vector-cortex/shards/manifest.ts

@@ -0,0 +1,276 @@
+/**
+ * vector-cortex/shards/manifest.ts — shard manifest assembly + validation (VC4A).
+ *
+ * Owns `assembleShardManifest` (the deterministic build) and
+ * `validateShardManifest` (task 4). The builder takes the already-partitioned
+ * semantic + exact tiers plus the protected spans and emits a `ShardManifestV1`
+ * whose ranges are disjoint and sorted by `(seqStart, byteStart)`. The validator
+ * enforces the two structural rules the sprint acceptance pins:
+ *
+ *   - SHD_RANGE_OVERLAP — any two manifest shard ranges (semantic or exact)
+ *     overlap in the session byte stream;
+ *   - SHD_PROTECTED_GAP  — the exact shards do not cover every protected byte
+ *     exactly once (a protected span is unterminated by an exact shard, or an
+ *     exact shard covers a byte no protected span claims).
+ *
+ * Emits `vector_cortex_shard_manifest_built` on a successful assembly and
+ * `vector_cortex_protected_span_rejected` when validation fails, via the same
+ * flag-gated reporter pattern VC3A/VC3B/VC3C use (`MEGACOMPACT_VC4A=0` emits
+ * nothing — byte-identical predecessor).
+ *
+ * Pure/deterministic: hashes + range math only, no storage, no console, no
+ * network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+import { VC4A_ENABLED } from "../../config/vector-cortex.js";
+import type {
+  ExactShardV1,
+  SemanticShardV1,
+  ShardEmitter,
+  ShardManifestFailureCode,
+  ShardManifestV1,
+  ShardManifestValidation,
+  ShardRange,
+  ShardReporter,
+} from "./types.js";
+
+/** A bare byte interval (used for the range math below). */
+interface Interval {
+  readonly start: number;
+  readonly end: number;
+}
+
+/** A manifest shard's range, normalized for sorting / digest purposes. */
+function rangeKey(r: ShardRange): string {
+  return `${r.seqStart.toString()},${r.byteStart}`;
+}
+
+/**
+ * Merge byte intervals into disjoint, sorted intervals (half-open). Overlapping
+ * AND touching intervals merge into one — this produces the "union" used for
+ * coverage math, never used to hide an overlap (overlap is checked separately in
+ * `hasOverlap` before any merging).
+ */
+function mergeIntervals(ranges: readonly ShardRange[]): Interval[] {
+  const sorted = [...ranges]
+    .map((r) => ({ start: r.byteStart, end: r.byteEnd }))
+    .sort((a, b) => (a.start !== b.start ? a.start - b.start : a.end - b.end));
+  const out: Interval[] = [];
+  for (const iv of sorted) {
+    const last = out[out.length - 1];
+    if (last !== undefined && iv.start <= last.end) {
+      out[out.length - 1] = { start: last.start, end: Math.max(last.end, iv.end) };
+      continue;
+    }
+    out.push(iv);
+  }
+  return out;
+}
+
+/** Difference: the bytes of `base` intervals NOT covered by `cover` intervals. */
+function subtractCover(base: Interval[], cover: Interval[]): Interval[] {
+  const ordered = cover
+    .slice()
+    .sort((a, b) => (a.start !== b.start ? a.start - b.start : a.end - b.end));
+  const gaps: Interval[] = [];
+  for (const iv of base) {
+    let cursor = iv.start;
+    for (const c of ordered) {
+      if (c.end <= cursor) continue;
+      if (c.start > cursor) {
+        gaps.push({ start: cursor, end: Math.min(c.start, iv.end) });
+        if (c.start >= iv.end) break;
+      }
+      cursor = Math.max(cursor, c.end);
+      if (cursor >= iv.end) break;
+    }
+    if (cursor < iv.end) gaps.push({ start: cursor, end: iv.end });
+  }
+  return gaps;
+}
+
+/** True when any two ranges overlap (share at least one byte). */
+function hasOverlap(ranges: readonly ShardRange[]): boolean {
+  const sorted = [...ranges].sort((a, b) => (a.byteStart !== b.byteStart ? a.byteStart - b.byteStart : a.byteEnd - b.byteEnd));
+  for (let i = 1; i < sorted.length; i++) {
+    const prev = sorted[i - 1];
+    const cur = sorted[i];
+    if (cur.byteStart < prev.byteEnd) return true;
+  }
+  return false;
+}
+
+/**
+ * Validate a manifest (task 4). Disjointness is a PER-TIER property: semantic
+ * shard ranges must be pairwise disjoint among themselves, and exact shard
+ * ranges pairwise disjoint among themselves (else `SHD_RANGE_OVERLAP`). The two
+ * tiers are NOT disjoint from each other — exact shards are a verbatim SUBSET of
+ * the semantic stream's bytes (a protected tool-pair's bytes are part of the
+ * semantic content), so a semantic range and an exact range overlapping is
+ * expected and correct. The cross-tier property is complete protected-span
+ * coverage: the exact shards must tile every protected span byte exactly once,
+ * no gap and no extra coverage (else `SHD_PROTECTED_GAP`). A manifest missing
+ * protected spans is malformed (`SHD_PROTECTED_GAP`). `generationDigest` is NOT
+ * verified here (it is a deterministic projection; the caller verifies it
+ * against the rebuilt digest).
+ */
+export function validateShardManifest(manifest: ShardManifestV1): ShardManifestValidation {
+  // Disjointness is enforced within each tier separately. An exact shard sitting
+  // inside a semantic shard is legitimate (exact ⊂ semantic).
+  if (hasOverlap(manifest.semantic.map((s) => s.range))) {
+    return { ok: false, code: "SHD_RANGE_OVERLAP" };
+  }
+  if (hasOverlap(manifest.exact.map((s) => s.range))) {
+    return { ok: false, code: "SHD_RANGE_OVERLAP" };
+  }
+
+  const protectedUnion = mergeIntervals(manifest.protectedSpans);
+  const exactUnion = mergeIntervals(manifest.exact.map((s) => s.range));
+
+  // Every protected byte must be covered by at least one exact shard (no gap),
+  // and no exact byte may fall outside the protected union (no extra coverage).
+  const gaps = subtractCover(protectedUnion, exactUnion);
+  const extras = subtractCover(exactUnion, protectedUnion);
+  if (gaps.length > 0 || extras.length > 0) {
+    return { ok: false, code: "SHD_PROTECTED_GAP" };
+  }
+  return { ok: true };
+}
+
+/**
+ * Deterministic manifest digest over a shard set — order-independent because it
+ * hashes the shards sorted by `(kind, seqStart, byteStart, digest)` (never input
+ * order). One SHA-256 over the canonical parts; the caller compares it against
+ * the stored `generationDigest`.
+ */
+export function shardManifestDigest(
+  sessionId: string,
+  sourceHighWater: bigint,
+  semantic: readonly { range: ShardRange; digest: string }[],
+  exact: readonly { range: ShardRange; digest: string }[],
+): string {
+  const rows: Array<[string, ShardRange, string]> = [
+    ...semantic.map((s) => ["semantic", s.range, s.digest] as [string, ShardRange, string]),
+    ...exact.map((s) => ["exact", s.range, s.digest] as [string, ShardRange, string]),
+  ].sort((a, b) => {
+    if (a[0] !== b[0]) return a[0] < b[0] ? -1 : 1;
+    const rk = rangeKey(a[1]);
+    const rk2 = rangeKey(b[1]);
+    return rk !== rk2 ? (rk < rk2 ? -1 : 1) : a[2] < b[2] ? -1 : a[2] > b[2] ? 1 : 0;
+  });
+  const h = createHash("sha256");
+  h.update(`shard-manifest-v1|${sessionId}|${sourceHighWater.toString()}|`);
+  for (const [kind, r, digest] of rows) {
+    h.update(`${kind}|${r.seqStart.toString()}|${r.seqEnd.toString()}|${r.byteStart}|${r.byteEnd}|${digest}~`);
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+/** Inputs to assemble a manifest. */
+export interface AssembleManifestInput {
+  readonly sessionId: string;
+  readonly sourceHighWater: bigint;
+  readonly semantic: readonly SemanticShardV1[];
+  readonly exact: readonly ExactShardV1[];
+  readonly protectedSpans: readonly ShardRange[];
+}
+
+/**
+ * Assemble a `ShardManifestV1` from already-partitioned tiers (deterministic).
+ * Shards are sorted by `(seqStart, byteStart)`; `generationDigest`, `byteTotal`
+ * and `shardCount` are computed from the sorted set. The caller typically runs
+ * this through `assembleAndValidate` so the structural rules are enforced too.
+ */
+export function buildShardManifest(input: AssembleManifestInput): ShardManifestV1 {
+  const cmp = (a: SemanticShardV1 | ExactShardV1, b: SemanticShardV1 | ExactShardV1): number => {
+    if (a.range.seqStart !== b.range.seqStart) {
+      return a.range.seqStart < b.range.seqStart ? -1 : 1;
+    }
+    return a.range.byteStart !== b.range.byteStart
+      ? a.range.byteStart < b.range.byteStart ? -1 : 1
+      : 0;
+  };
+  const semantic = [...input.semantic].sort(cmp);
+  const exact = [...input.exact].sort(cmp);
+  const byteTotal =
+    semantic.reduce((n, s) => n + s.byteCount, 0) +
+    exact.reduce((n, s) => n + s.byteCount, 0);
+  const generationDigest = shardManifestDigest(input.sessionId, input.sourceHighWater, semantic, exact);
+  return {
+    schema: "shard-manifest-v1",
+    sessionId: input.sessionId,
+    sourceHighWater: input.sourceHighWater,
+    semantic,
+    exact,
+    protectedSpans: [...input.protectedSpans],
+    byteTotal,
+    shardCount: semantic.length + exact.length,
+    generationDigest,
+  };
+}
+
+/**
+ * Assembly + validation seam (task 5). Builds the manifest, validates it, and
+ * emits `vector_cortex_shard_manifest_built` on success or
+ * `vector_cortex_protected_span_rejected` on failure (flag-gated). Non-fatal:
+ * a validation failure returns `{ok:false, code}` and NEVER throws into the host.
+ */
+export function assembleAndValidate(
+  input: AssembleManifestInput,
+  emit?: ShardEmitter,
+): { ok: true; manifest: ShardManifestV1 } | { ok: false; code: ShardManifestFailureCode } {
+  const manifest = buildShardManifest(input);
+  const validation = validateShardManifest(manifest);
+  const reporter = createShardReporter(emit);
+  if (!validation.ok) {
+    reporter.protectedSpanRejected({
+      sessionId: input.sessionId,
+      code: validation.code,
+    });
+    return { ok: false, code: validation.code };
+  }
+  reporter.manifestBuilt({
+    sessionId: input.sessionId,
+    sourceHighWater: input.sourceHighWater.toString(),
+    shardCount: manifest.shardCount,
+    byteTotal: manifest.byteTotal,
+    generationDigest: manifest.generationDigest,
+  });
+  return { ok: true, manifest };
+}
+
+/**
+ * Whether each tier's ranges are internally sorted by (seqStart, byteStart).
+ * The two tiers are NOT globally ordered against each other (exact shards are a
+ * subset of the semantic stream, so an exact range always sits inside some
+ * semantic range); the guarantee the builder provides is per-tier ordering.
+ */
+export function manifestSorted(m: ShardManifestV1): boolean {
+  const key = (r: ShardRange): string => `${r.seqStart.toString()},${r.byteStart}`;
+  const sorted = (rows: readonly { range: ShardRange }[]): boolean =>
+    rows.every((r, i) => i === 0 || key(rows[i - 1]!.range) <= key(r.range));
+  return sorted(m.semantic) && sorted(m.exact);
+}
+
+/** Build the flag-gated typed reporter (mirrors ledger/topology reporters). */
+function createShardReporter(emit?: ShardEmitter): ShardReporter {
+  const fire = (event: Parameters<ShardEmitter>[0], fields: Record<string, unknown>): void => {
+    if (!VC4A_ENABLED()) return;
+    if (!emit) return;
+    try {
+      emit(event, fields);
+    } catch {
+      /* non-fatal observability — never break the agent loop */
+    }
+  };
+  return {
+    manifestBuilt(fields) {
+      fire("vector_cortex_shard_manifest_built", fields);
+    },
+    protectedSpanRejected(fields) {
+      fire("vector_cortex_protected_span_rejected", fields);
+    },
+  };
+}
+
+export { createShardReporter };

package/src/vector-cortex/shards/semantic.ts

@@ -0,0 +1,156 @@
+/**
+ * vector-cortex/shards/semantic.ts — semantic tier partition (VC4A, mode A/B).
+ *
+ * Partitions a session's canonical EventV2 stream into `SemanticShardV1`
+ * chunks, cutting ONLY at complete record boundaries. Every shard's `range`
+ * names the exact inclusive seq span and the half-open source byte window it
+ * covers in canonical stream order; a shard NEVER splits a record (or a tool
+ * call/result pair). Semantic shards carry DERIVED aggregate content (a
+ * deterministic digest + token estimate + byte/event counts) and never
+ * reproduce exact text — exact bytes are the exact tier's job.
+ *
+ * The partition is deterministic and size-bounded: it walks the sorted events,
+ * accrues each record's bytes, and closes a shard the moment adding the next
+ * complete record would exceed `targetSize`. A single record that is already
+ * over the budget gets its own shard (a shard is always at least one complete
+ * record, so over-budget records are never split).
+ *
+ * Triad: A = this semantic tier plus exact shards; B = the same range shape
+ * derived from extractive heads with the semantic encoder disabled (the caller
+ * may substitute the derived payload, since the range+digest contract is
+ * identical); C = exact anchors/current transcript only (no semantic shards at
+ * all, handled by the exact tier alone).
+ *
+ * Pure/deterministic: hashes + array walking only, no storage, no console, no
+ * network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+import type { EventV2 } from "../ledger/types.js";
+import type { SemanticPartitionInput, SemanticPartitionResult, SemanticShardV1 } from "./types.js";
+
+/** A full-stream byte offset map: cumulative end offset per ascending seq. */
+export interface ByteOffsets {
+  /** For an EventV2 at `seq`, its half-open [byteStart, byteEnd) in stream order. */
+  readonly of: (seq: bigint) => { byteStart: number; byteEnd: number } | undefined;
+  /** Total canonical stream length (sum of every record's bytes). */
+  readonly total: number;
+}
+
+/**
+ * Compute the canonical per-record byte offsets for a session's sorted events.
+ * Events are sorted by seq (ascending) defensively; the byte stream is the
+ * concatenation of each event's `originalBytes` in that order. A shared pure
+ * helper so semantic + exact tiers agree on source ranges (the two partitioning
+ * algorithms remain otherwise independent). Returns `undefined`-guarding lookup
+ * plus the total length; empty input yields an empty map with total 0.
+ */
+export function cumulativeOffsets(events: readonly EventV2[]): ByteOffsets {
+  const map = new Map<string, { byteStart: number; byteEnd: number }>();
+  let off = 0;
+  const sorted = [...events].sort((a, b) => (a.seq < b.seq ? -1 : a.seq > b.seq ? 1 : 0));
+  for (const e of sorted) {
+    const len = e.originalBytes.length;
+    map.set(e.seq.toString(), { byteStart: off, byteEnd: off + len });
+    off += len;
+  }
+  return {
+    of: (seq: bigint) => map.get(seq.toString()),
+    total: off,
+  };
+}
+
+/** Approximate token count for a valid UTF-8 text (whitespace-separated runs). */
+function approxTokens(text: string): number {
+  if (text.length === 0) return 0;
+  const runs = text.match(/\S+/g);
+  return runs ? runs.length : 0;
+}
+
+/** Deterministic SHARD digest over a semantic shard's derived payload. */
+function sealedSemanticDigest(
+  sessionId: string,
+  events: readonly EventV2[],
+  range: { byteStart: number; byteEnd: number; seqStart: bigint; seqEnd: bigint },
+  tokenEstimate: number,
+): string {
+  const h = createHash("sha256");
+  h.update(`semantic-shard-v1|${sessionId}|`);
+  h.update(`${range.seqStart.toString()}|${range.seqEnd.toString()}|`);
+  h.update(`${range.byteStart}|${range.byteEnd}|`);
+  h.update(`${tokenEstimate}|`);
+  // One `~`-joined run of the covered records' authoritative byte digests in
+  // seq order, so the shard digest depends on exactly which records it covers.
+  for (const e of [...events].sort((a, b) => (a.seq < b.seq ? -1 : a.seq > b.seq ? 1 : 0))) {
+    h.update(`${e.seq.toString()}:${e.bytesDigest}~`);
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+/**
+ * Partition the semantic tier (task 2). Returns `ok:true` with a list of
+ * `SemanticShardV1` whose (sorted) ranges are contiguous, non-overlapping and
+ * jointly cover every event exactly once. Failures are defensive: a non-positive
+ * or non-finite `targetSize` rejects with `SHD_INVALID_TARGET_SIZE`; mixed-session
+ * events reject with `SHD_CROSS_SESSION`.
+ */
+export function partitionSemantic(input: SemanticPartitionInput): SemanticPartitionResult {
+  const { sessionId, events, targetSize } = input;
+  if (!Number.isFinite(targetSize) || targetSize <= 0) {
+    return { ok: false, code: "SHD_INVALID_TARGET_SIZE" };
+  }
+  if (events.some((e) => e.sessionId !== sessionId)) {
+    return { ok: false, code: "SHD_CROSS_SESSION" };
+  }
+  const offsets = cumulativeOffsets(events);
+  const sorted = [...events].sort((a, b) => (a.seq < b.seq ? -1 : a.seq > b.seq ? 1 : 0));
+  if (sorted.length === 0) return { ok: true, shards: [] };
+
+  const shards: SemanticShardV1[] = [];
+  let batch: EventV2[] = [];
+  let batchBytes = 0;
+  let batchTokens = 0;
+
+  const flush = (): void => {
+    if (batch.length === 0) return;
+    const first = batch[0];
+    const last = batch[batch.length - 1];
+    const start = offsets.of(first.seq);
+    const end = offsets.of(last.seq);
+    const byteStart = start ? start.byteStart : 0;
+    const byteEnd = end ? end.byteEnd : byteStart;
+    const tokenEstimate = batchTokens;
+    shards.push({
+      schema: "semantic-shard-v1",
+      sessionId,
+      range: {
+        sessionId,
+        seqStart: first.seq,
+        seqEnd: last.seq,
+        byteStart,
+        byteEnd,
+      },
+      kind: "semantic",
+      digest: sealedSemanticDigest(sessionId, batch, { seqStart: first.seq, seqEnd: last.seq, byteStart, byteEnd }, tokenEstimate),
+      byteCount: batchBytes,
+      eventCount: batch.length,
+      tokenEstimate,
+    });
+    batch = [];
+    batchBytes = 0;
+    batchTokens = 0;
+  };
+
+  for (const e of sorted) {
+    const len = e.originalBytes.length;
+    const tokens = e.utf8.valid ? approxTokens(e.utf8.text) : Math.ceil(len / 4);
+    // A batch that already has a complete record and would exceed the budget
+    // (and the next record itself fits, or it doesn't) closes at a boundary.
+    if (batch.length > 0 && batchBytes + len > targetSize) flush();
+    batch.push(e);
+    batchBytes += len;
+    batchTokens += tokens;
+  }
+  flush();
+
+  return { ok: true, shards };
+}

package/src/vector-cortex/shards/types.ts

@@ -0,0 +1,212 @@
+/**
+ * vector-cortex/shards/types.ts — dual-tier shard contract (VC4A).
+ *
+ * Owns `SemanticShardV1` / `ExactShardV1` / `ShardManifestV1` — the shared
+ * partition contract of the sprint failure triad:
+ *
+ *   A = semantic + exact shards (normal path);
+ *   B = extractive + exact shards with the semantic encoder disabled;
+ *   C = exact anchors/current transcript only.
+ *
+ * A session's canonical byte stream is partitioned ONLY at complete EventV2
+ * record boundaries (VC1A byte authority — an EventV2's `originalBytes` + its
+ * SHA-256 `bytesDigest` are authoritative, invalid UTF-8 is never normalized).
+ * A `ShardRange` names a contiguous run of complete records by inclusive
+ * seq `[seqStart..seqEnd]` and by the half-open source byte range
+ * `[byteStart, byteEnd)` they occupy in canonical stream order (record `seq`
+ * carries every byte from `offset(seq)` to `offset(seq)+len(seq)`).
+ *
+ * Semantic shards carry derived aggregate vectors/token estimates and NEVER
+ * reproduce exact text (the RESIDUAL_CODEC / exact-payload shards own exact
+ * bytes). Exact shards carry the EXACT original bytes, unchanged, for the
+ * protected spans: every tool call/result pair, every anchor, and every invalid
+ * UTF-8 event (SHD-UTF8-002 — invalid bytes are exact-only and never
+ * normalized/re-encoded). A tool call/result pair that straddles a target-size
+ * boundary stays in ONE exact shard (SHD-PAIR-001).
+ *
+ * Consumes only reviewer-accepted predecessor contracts (VC1A EventV2) and the
+ * [common contracts](../../../../docs/vector-cortex/CONTRACTS.md). Pure
+ * types/schema + small predicates: no storage, no console, no network
+ * (PREVENT-PI-004 / PREVENT-011). The acceptance contract and the conformance
+ * IDs (SHD-001..020 + named SHD-PAIR-001 / SHD-UTF8-002 / SHD-RANGE-003) live
+ * here.
+ */
+
+import type { EventV2 } from "../ledger/types.js";
+
+/**
+ * A contiguous covered byte+seq window over ONE session's canonical EventV2
+ * stream. `seqStart`/`seqEnd` are inclusive record sequence bounds; `byteStart`/
+ * `byteEnd` are half-open byte offsets in canonical stream order. Every recorded
+ * boundary is a COMPLETE EventV2 record boundary — a shard never splits a record
+ * or a tool call/result pair.
+ */
+export interface ShardRange {
+  readonly sessionId: string;
+  readonly seqStart: bigint;
+  readonly seqEnd: bigint;
+  readonly byteStart: number;
+  readonly byteEnd: number;
+}
+
+/** What an exact shard protects (why its bytes must survive verbatim). */
+export type ExactShardCase =
+  | "tool-pair"
+  | "anchor"
+  | "invalid-utf8"
+  | "anchor+invalid";
+
+/**
+ * A semantic shard — a deterministic partition of complete, valid EventV2
+ * records into sub-target-size chunks. It carries DERIVED aggregate content
+ * (head vectors + token estimate + a deterministic content digest) and
+ * explicitly not the raw record bytes; exact restoration of those bytes is the
+ * exact tier's job (RESIDUAL_CODEC / exact payload shards).
+ */
+export interface SemanticShardV1 {
+  readonly schema: "semantic-shard-v1";
+  readonly sessionId: string;
+  /** Source metadata: which complete records and byte span this shard covers. */
+  readonly range: ShardRange;
+  readonly kind: "semantic";
+  /** Deterministic SHA-256 over the shard's derived payload bytes. */
+  readonly digest: string;
+  /** Sum of the covered records' original byte lengths. */
+  readonly byteCount: number;
+  /** Number of complete events covered. */
+  readonly eventCount: number;
+  /** Deterministic token estimate for the covered text (aggregate). */
+  readonly tokenEstimate: number;
+}
+
+/**
+ * An exact shard — the ORIGINAL bytes of a protected span, preserved verbatim
+ * including invalid UTF-8 (never normalized/re-encoded). `originalBytes` is the
+ * concatenation, in seq order, of every covered record's `originalBytes`; the
+ * byte range equals that concatenation exactly. `case` records why the span is
+ * protected. No semantic loss is ever claimed for exact bytes.
+ */
+export interface ExactShardV1 {
+  readonly schema: "exact-shard-v1";
+  readonly sessionId: string;
+  readonly range: ShardRange;
+  readonly kind: "exact";
+  /** Exact original bytes, unchanged (authoritative). */
+  readonly originalBytes: Uint8Array;
+  /** SHA-256 of `originalBytes`. */
+  readonly digest: string;
+  readonly byteCount: number;
+  readonly case: ExactShardCase;
+}
+
+/**
+ * The assembled shard manifest. `changes` mirror the sprint failure triad:
+ *   A / B — semantic + exact tiers both present (B may derive the semantic tier
+ *           from extractive heads when the semantic encoder is disabled);
+ *   C     — exact anchors/current transcript ONLY (zero semantic shards).
+ * `generationDigest` is ONE deterministic SHA-256 over the canonical
+ * serialization of every shard's range + kind + digest. `protectedSpans`
+ * enumerate every span that must exist as exact bytes; the validator requires
+ * the exact shards to cover them exactly once (no gap, no overlap).
+ */
+export interface ShardManifestV1 {
+  readonly schema: "shard-manifest-v1";
+  readonly sessionId: string;
+  /** Contiguous durable authority high-water the manifest is built AT. */
+  readonly sourceHighWater: bigint;
+  readonly semantic: readonly SemanticShardV1[];
+  readonly exact: readonly ExactShardV1[];
+  /** Deterministic manifest digest (order-independent over the shard set). */
+  readonly generationDigest: string;
+  /** The protected spans that must be exactly covered (tools/anchors/invalid). */
+  readonly protectedSpans: readonly ShardRange[];
+  /** Sum of every semantic + exact shard's covered bytes. */
+  readonly byteTotal: number;
+  /** Total number of shards (semantic + exact). */
+  readonly shardCount: number;
+}
+
+/** Input to a semantic partition: the sorted events + a target max byte size. */
+export interface SemanticPartitionInput {
+  readonly sessionId: string;
+  /** Complete EventV2 records in ascending seq order (source of truth). */
+  readonly events: readonly EventV2[];
+  /** Per-shard byte budget; a single over-budget record gets its own shard. */
+  readonly targetSize: number;
+}
+
+/** Result of partitioning the semantic tier (A/B). */
+export type SemanticPartitionResult =
+  | { ok: true; shards: readonly SemanticShardV1[] }
+  | { ok: false; code: string };
+
+/** One protected input span to carve into exact shards. */
+export interface ProtectedSpan {
+  /** The events to preserve verbatim, in ascending seq order. */
+  readonly events: readonly EventV2[];
+  /** Why this span is protected (used for the exact shard `case`). */
+  readonly case: ExactShardCase;
+}
+
+/**
+ * Input to an exact partition. `events` is the FULL canonical session stream
+ * (used to derive the true stream byte offsets); `protectedSpans` are the atomic
+ * groups to preserve verbatim (a tool call+result pair is ONE span so it can
+ * never be split across exact shards — SHD-PAIR-001); `targetSize` is the
+ * per-shard byte budget (a single over-budget pair still occupies one shard).
+ */
+export interface ExactPartitionInput {
+  readonly sessionId: string;
+  readonly events: readonly EventV2[];
+  readonly protectedSpans: readonly ProtectedSpan[];
+  readonly targetSize: number;
+}
+
+/** Result of partitioning the exact tier. */
+export type ExactPartitionResult =
+  | { ok: true; shards: readonly ExactShardV1[] }
+  | { ok: false; code: string };
+
+/** Manifest validation failure codes. */
+export type ShardManifestFailureCode = "SHD_RANGE_OVERLAP" | "SHD_PROTECTED_GAP";
+
+/** Validation of a manifest vs the pairwise-disjoint + protected-span rules. */
+export type ShardManifestValidation =
+  | { ok: true }
+  | { ok: false; code: ShardManifestFailureCode };
+
+/** The two structured events the VC4A reporter emits. */
+export type ShardEventName =
+  | "vector_cortex_shard_manifest_built"
+  | "vector_cortex_protected_span_rejected";
+
+/** Injected emit callback — same (event, fields) shape as the other VC seams. */
+export type ShardEmitter = (event: ShardEventName, fields: Record<string, unknown>) => void;
+
+/** Typed, best-effort reporter bound to the two shard event names. */
+export interface ShardReporter {
+  readonly manifestBuilt: (fields: Record<string, unknown>) => void;
+  readonly protectedSpanRejected: (fields: Record<string, unknown>) => void;
+}
+
+/**
+ * Registered SHD conformance ID range (SHD-001..020). The acceptance test reads
+ * these rows from the v2 manifest and asserts each returns its manifest
+ * `ok`/`code`. The named assertions (SHD-PAIR-001 / SHD-UTF8-002 /
+ * SHD-RANGE-003) live in the acceptance test.
+ */
+export const SHD_IDS = [
+  "SHD-001", "SHD-002", "SHD-003", "SHD-004", "SHD-005",
+  "SHD-006", "SHD-007", "SHD-008", "SHD-009", "SHD-010",
+  "SHD-011", "SHD-012", "SHD-013", "SHD-014", "SHD-015",
+  "SHD-016", "SHD-017", "SHD-018", "SHD-019", "SHD-020",
+] as const;
+
+/** Named SHD conformance assertions. */
+export const SHD_NAMED_IDS = [
+  "SHD-PAIR-001",
+  "SHD-UTF8-002",
+  "SHD-RANGE-003",
+] as const;
+
+export type { EventV2 };