pi-mega-compact 0.19.2 → 0.20.0

package/dist/src/vector-cortex/migrations/router-generation-v2.js

@@ -0,0 +1,252 @@
+/**
+ * vector-cortex/migrations/router-generation-v2.ts — M6 copy/validate/switch
+ * migration (VC3C).
+ *
+ * M6 versions the tiered router's query set: the predecessor routed on ad-hoc
+ * per-session keys (no generation identity); VC3C routes on the structured,
+ * length-delimited `RouterKeyV2`. M6 copies the old per-session query set into
+ * v2 `RouterGenV2Row`s BESIDE the legacy state, validates, and only then
+ * atomically switches the active version pointer — the same copy/validate/
+ * switch + resume contract as M4.
+ *
+ *   - copy: resumable per (session, old key) — an interrupted run resumes
+ *     without duplicate rows or active-pointer drift.
+ *   - validate: every old query key has exactly one v2 row, every row's key is
+ *     canonical + re-hashes, and — the VC3C-specific invariant — the new query
+ *     set is partition-preserving: a row derived from an old key of session S
+ *     MUST carry session S. A row whose session differs is rejected as
+ *     cross-session eviction (`M6_CROSS_SESSION_EVICTION`): one session may
+ *     never lose or steal another session's query identity.
+ *   - switch: atomically flips the ACTIVE VERSION pointer from 1 (legacy) to 2
+ *     (router-generation-v2) only after a verified copy; interruption keeps the
+ *     old active pointer.
+ *
+ * Pure logic over an injected M6Host (deterministic + testable; no console).
+ * PREVENT-002/011/PI-004 honored.
+ */
+import { createHash } from "node:crypto";
+import { encodeRouterKeyV2, decodeRouterKeyV2, } from "../topology/query.js";
+/** The active-version value the v2 router generation pointer is switched to. */
+export const ROUTER_GEN_V2_VERSION = 2;
+/** The legacy (predecessor) active-version value before any verified switch. */
+export const ROUTER_GEN_LEGACY_VERSION = 1;
+/** M6 failure codes. */
+export const M6_FAIL = {
+    VERSION_MISMATCH: "M6_VERSION_MISMATCH",
+    COPY_PARTIAL: "M6_COPY_PARTIAL",
+    COUNT_MISMATCH: "M6_COUNT_MISMATCH",
+    DIGEST_MISMATCH: "M6_DIGEST_MISMATCH",
+    BAD_OLD_KEY: "M6_BAD_OLD_KEY",
+    CROSS_SESSION_EVICTION: "M6_CROSS_SESSION_EVICTION",
+    SWITCH_PRECONDITION: "M6_SWITCH_PRECONDITION",
+};
+/** Derive one v2 row from an old key (authoritative bytes). */
+export function deriveRouterGenRow(host, session, oldKey) {
+    const parsed = host.parseOldKey(session, oldKey);
+    if (!parsed.ok)
+        return { ok: false, session, oldKey };
+    const key = parsed.key;
+    // Cross-session guard at COPY time: the structured key's session must equal
+    // the slot session. A key that claims a different session is never copied.
+    if (key.session !== session)
+        return { ok: false, session, oldKey };
+    const encoded = encodeRouterKeyV2(key);
+    return {
+        ok: true,
+        row: {
+            session,
+            generation: key.generation,
+            sourceStart: key.sourceStart,
+            sourceEnd: key.sourceEnd,
+            algorithm: key.algorithm,
+            key: encoded,
+            digest: sha256Hex(Buffer.from(encoded.slice(4), "hex")),
+        },
+    };
+}
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * Copy the full old query set into v2 rows (resumable): rows already persisted
+ * with a matching canonical key + digest are left untouched (no duplicates);
+ * absent or corrupt (wrong session / wrong key / stale digest / bad old key)
+ * slots are (re)written from the authoritative derivation. Returns the delta
+ * written this call. The active pointer stays at the legacy version until a
+ * verified switch.
+ */
+export function m6Copy(host) {
+    const existing = new Map(host.existingV2().map((r) => [`${r.session}::${r.key}`, r]));
+    const wanted = [];
+    for (const session of host.sessions()) {
+        for (const oldKey of host.oldKeysOf(session)) {
+            const derived = deriveRouterGenRow(host, session, oldKey);
+            if (!derived.ok)
+                continue; // bad old key surfaced by verify, not lost silently
+            const stored = existing.get(`${session}::${derived.row.key}`);
+            if (stored !== undefined && rowMatches(stored, derived.row))
+                continue; // healthy
+            wanted.push(derived.row);
+        }
+    }
+    if (wanted.length > 0)
+        host.putV2(wanted);
+    return { written: wanted, all: [...host.existingV2()] };
+}
+/** True when a persisted row already matches the authoritative derivation. */
+function rowMatches(stored, fresh) {
+    return (stored.session === fresh.session &&
+        stored.generation === fresh.generation &&
+        stored.sourceStart === fresh.sourceStart &&
+        stored.sourceEnd === fresh.sourceEnd &&
+        stored.algorithm === fresh.algorithm &&
+        stored.key === fresh.key &&
+        stored.digest === fresh.digest);
+}
+/**
+ * Verify the migrated query set: every old query key across every session has a
+ * v2 row (exact-once), every row's key is canonical + re-hashes, and the new set
+ * is partition-preserving — every row's session is exactly the session of the
+ * old key it was derived from (rejects cross-session eviction). Never mutates.
+ *
+ * Comparison of old/new query sets is exact-by-identity (structured key bytes),
+ * never by string prefix.
+ */
+export function m6Verify(host) {
+    const codes = [];
+    const stored = host.existingV2();
+    // Expected slot inventory: (session, canonical key) for every derivable old key.
+    const expectedSlots = [];
+    const badOldKeys = [];
+    for (const session of host.sessions()) {
+        for (const oldKey of host.oldKeysOf(session)) {
+            const parsed = host.parseOldKey(session, oldKey);
+            if (!parsed.ok) {
+                badOldKeys.push({ session, oldKey });
+                continue;
+            }
+            if (parsed.key.session !== session) {
+                // A structured key that claims a different session is a cross-session
+                // eviction attempt — never migrated, never evicted.
+                codes.push(M6_FAIL.CROSS_SESSION_EVICTION);
+                continue;
+            }
+            expectedSlots.push({ session, oldKey });
+        }
+    }
+    if (badOldKeys.length > 0)
+        codes.push(M6_FAIL.BAD_OLD_KEY);
+    // Map stored rows by their (session,key) identity.
+    const byIdentity = new Map();
+    const duplicateCheck = new Map();
+    for (const r of stored) {
+        const ident = `${r.session}::${r.key}`;
+        byIdentity.set(ident, r);
+        duplicateCheck.set(ident, (duplicateCheck.get(ident) ?? 0) + 1);
+    }
+    // Each expected slot must be present exactly once, with a healthy row.
+    for (const slot of expectedSlots) {
+        const parsed = host.parseOldKey(slot.session, slot.oldKey);
+        if (!parsed.ok)
+            continue;
+        const expectedKey = encodeRouterKeyV2(parsed.key);
+        const ident = `${slot.session}::${expectedKey}`;
+        const count = duplicateCheck.get(ident) ?? 0;
+        if (count === 0)
+            codes.push(M6_FAIL.COPY_PARTIAL);
+        if (count > 1)
+            codes.push(M6_FAIL.COUNT_MISMATCH);
+    }
+    // Row health: digest re-hashes + session partition-preserving.
+    for (const r of stored) {
+        if (!r.key.startsWith("rk2:"))
+            codes.push(M6_FAIL.DIGEST_MISMATCH);
+        const expectedDigest = sha256Hex(Buffer.from(r.key.slice(4), "hex"));
+        if (r.digest !== expectedDigest)
+            codes.push(M6_FAIL.DIGEST_MISMATCH);
+        // The row's own structured key must decode and agree with its declared fields.
+        const dec = decodeRow(r);
+        if (!dec)
+            codes.push(M6_FAIL.DIGEST_MISMATCH);
+    }
+    // No stored row may be an orphan (no corresponding old key anywhere).
+    const expectedIdentities = new Set();
+    for (const slot of expectedSlots) {
+        const parsed = host.parseOldKey(slot.session, slot.oldKey);
+        if (!parsed.ok)
+            continue;
+        expectedIdentities.add(`${slot.session}::${encodeRouterKeyV2(parsed.key)}`);
+    }
+    for (const ident of byIdentity.keys()) {
+        if (!expectedIdentities.has(ident))
+            codes.push(M6_FAIL.COUNT_MISMATCH);
+    }
+    const ok = codes.length === 0;
+    return { ok, codes: dedupe(codes) };
+}
+/**
+ * Self-consistent decode of a stored row: its canonical key decodes to a
+ * RouterKeyV2 whose five fields equal the row's declared fields. A row whose key
+ * doesn't round-trip against its own declared session/generation/range/algorithm
+ * is corrupt (cannot be trusted as the query set's identity).
+ */
+function decodeRow(r) {
+    if (!r.key.startsWith("rk2:"))
+        return false;
+    const hex = r.key.slice(4);
+    if (!/^[0-9a-f]+$/.test(hex) || hex.length % 2 !== 0)
+        return false;
+    const dec = decodeRouterKeyV2(r.key);
+    if (!dec.ok)
+        return false;
+    return (dec.key.session === r.session &&
+        dec.key.generation === r.generation &&
+        dec.key.sourceStart === r.sourceStart &&
+        dec.key.sourceEnd === r.sourceEnd &&
+        dec.key.algorithm === r.algorithm);
+}
+/**
+ * Switch the active version to 2. Only call after `m6Verify` reports ok; a
+ * crash/return before switch leaves the legacy pointer active (interruption
+ * keeps old authority, resumable idempotently).
+ */
+export function m6Switch(host) {
+    if (host.activeVersion() !== ROUTER_GEN_LEGACY_VERSION)
+        return;
+    host.switchToV2();
+}
+/** Full M6 lifecycle: copy -> verify -> switch; returns the verify result. */
+export function migrateRouterGenerationV2(host) {
+    m6Copy(host);
+    const v = m6Verify(host);
+    if (v.ok)
+        m6Switch(host);
+    return v;
+}
+/** Registered M6 conformance ID range (M6-001..012). */
+export const M6_IDS = [
+    "M6-001",
+    "M6-002",
+    "M6-003",
+    "M6-004",
+    "M6-005",
+    "M6-006",
+    "M6-007",
+    "M6-008",
+    "M6-009",
+    "M6-010",
+    "M6-011",
+    "M6-012",
+];
+/** Registered named M6 conformance IDs. */
+export const M6_NAMED_IDS = [
+    "M6-KEY-001",
+    "M6-STALE-002",
+];
+function dedupe(codes) {
+    const out = [];
+    for (const c of codes)
+        if (!out.includes(c))
+            out.push(c);
+    return out;
+}

package/dist/src/vector-cortex/shards/exact.js

@@ -0,0 +1,134 @@
+/**
+ * vector-cortex/shards/exact.ts — exact tier partition (VC4A).
+ *
+ * Carves the session's PROTECTED spans — every tool call/result pair, every
+ * anchor, every invalid UTF-8 event — into `ExactShardV1` payloads of the
+ * ORIGINAL bytes, verbatim and never normalized (SHD-UTF8-002: invalid bytes
+ * are exact-only and preserved unchanged — the codec's strict-fatal classifier
+ * means an invalid event has no lossy text to re-encode; we copy `originalBytes`
+ * directly). Each protected span is ATOMIC: a tool call/result pair is one
+ * `ProtectedSpan`, so no exact shard EVER splits a pair, even when the pair
+ * straddles the target-size boundary (SHD-PAIR-001).
+ *
+ * The partition walks the protected spans in canonical stream order (ascending
+ * first-seq), accrues each span's bytes, and closes an exact shard the moment
+ * adding the next atomic span would exceed `targetSize`. A single span over the
+ * budget still occupies exactly one shard — the pair case never splits.
+ *
+ * Triad: A = used with the semantic tier; B = the same exact spans preserved
+ * alongside extractive-derived semantic content; C = exact anchors/current
+ * transcript ONLY (this partition alone, with zero semantic shards).
+ *
+ * Pure/deterministic: hashes + array walking only, no storage, no console, no
+ * network (PREVENT-PI-004 / PREVENT-011).
+ */
+import { createHash } from "node:crypto";
+import { cumulativeOffsets } from "./semantic.js";
+/** Deterministic exact-shard digest over the verbatim original bytes. */
+function sealExactDigest(sessionId, bytes) {
+    const h = createHash("sha256");
+    h.update(`exact-shard-v1|${sessionId}|`);
+    h.update(bytes);
+    return `sha256:${h.digest("hex")}`;
+}
+/** Combine per-span cases into one shard case (invalid dominates, then tool-pair). */
+function combineCase(span, acc) {
+    if (span.case === "invalid-utf8" || acc === "invalid-utf8")
+        return "invalid-utf8";
+    if (span.case === "tool-pair" || acc === "tool-pair")
+        return "tool-pair";
+    return "anchor";
+}
+/** Concatenate an ordered group of events' original bytes, verbatim. */
+function concatBytes(events) {
+    let len = 0;
+    for (const e of events)
+        len += e.originalBytes.length;
+    const out = new Uint8Array(len);
+    let off = 0;
+    for (const e of events) {
+        out.set(e.originalBytes, off);
+        off += e.originalBytes.length;
+    }
+    return out;
+}
+/**
+ * Partition the exact tier (task 3). Returns `ok:true` with a list of
+ * `ExactShardV1` whose (sorted) ranges are contiguous, non-overlapping and
+ * jointly cover every protected span exactly once, each preserving the original
+ * bytes verbatim. Defensive failures mirror the semantic tier: a bad target size
+ * rejects with `SHD_INVALID_TARGET_SIZE`; a protected span referencing an event
+ * outside the session's stream, or a mixed-session span, rejects with
+ * `SHD_CROSS_SESSION`.
+ */
+export function partitionExact(input) {
+    const { sessionId, events, protectedSpans, targetSize } = input;
+    if (!Number.isFinite(targetSize) || targetSize <= 0) {
+        return { ok: false, code: "SHD_INVALID_TARGET_SIZE" };
+    }
+    const stream = new Set(events.map((e) => e.seq.toString()));
+    for (const span of protectedSpans) {
+        if (span.events.some((e) => e.sessionId !== sessionId || !stream.has(e.seq.toString()))) {
+            return { ok: false, code: "SHD_CROSS_SESSION" };
+        }
+    }
+    const offsets = cumulativeOffsets(events);
+    if (protectedSpans.length === 0)
+        return { ok: true, shards: [] };
+    // Process protected spans in canonical stream order (ascending first-seq;
+    // equal first-seq preserves input order for determinism).
+    const ordered = [...protectedSpans].sort((a, b) => {
+        const as = a.events.length ? a.events[0].seq : 0n;
+        const bs = b.events.length ? b.events[0].seq : 0n;
+        return as < bs ? -1 : as > bs ? 1 : 0;
+    });
+    const shards = [];
+    let batch = [];
+    let batchBytes = 0;
+    let batchCase = "anchor";
+    const spanBytes = (s) => s.events.reduce((n, e) => n + e.originalBytes.length, 0);
+    const flush = () => {
+        if (batch.length === 0)
+            return;
+        const first = batch[0];
+        const last = batch[batch.length - 1];
+        const firstEv = first.events[0];
+        const lastEv = last.events[last.events.length - 1];
+        const start = offsets.of(firstEv.seq);
+        const end = offsets.of(lastEv.seq);
+        const byteStart = start ? start.byteStart : 0;
+        const byteEnd = end ? end.byteEnd : byteStart;
+        const bytes = concatBytes(batch.flatMap((s) => s.events));
+        shards.push({
+            schema: "exact-shard-v1",
+            sessionId,
+            range: {
+                sessionId,
+                seqStart: firstEv.seq,
+                seqEnd: lastEv.seq,
+                byteStart,
+                byteEnd,
+            },
+            kind: "exact",
+            originalBytes: bytes,
+            digest: sealExactDigest(sessionId, bytes),
+            byteCount: batchBytes,
+            case: batchCase,
+        });
+        batch = [];
+        batchBytes = 0;
+        batchCase = "anchor";
+    };
+    for (const span of ordered) {
+        const sz = spanBytes(span);
+        // Close at a complete-span boundary when adding this atomic span would
+        // exceed the budget and we already hold at least one complete span.
+        if (batch.length > 0 && batchBytes + sz > targetSize)
+            flush();
+        batch.push(span);
+        batchBytes += sz;
+        batchCase = combineCase(span, batchCase);
+    }
+    flush();
+    return { ok: true, shards };
+}

package/dist/src/vector-cortex/shards/manifest.js

@@ -0,0 +1,237 @@
+/**
+ * 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";
+/** A manifest shard's range, normalized for sorting / digest purposes. */
+function rangeKey(r) {
+    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) {
+    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 = [];
+    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, cover) {
+    const ordered = cover
+        .slice()
+        .sort((a, b) => (a.start !== b.start ? a.start - b.start : a.end - b.end));
+    const gaps = [];
+    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) {
+    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) {
+    // 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, sourceHighWater, semantic, exact) {
+    const rows = [
+        ...semantic.map((s) => ["semantic", s.range, s.digest]),
+        ...exact.map((s) => ["exact", s.range, s.digest]),
+    ].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")}`;
+}
+/**
+ * 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) {
+    const cmp = (a, b) => {
+        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, emit) {
+    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) {
+    const key = (r) => `${r.seqStart.toString()},${r.byteStart}`;
+    const sorted = (rows) => 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) {
+    const fire = (event, fields) => {
+        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 };