agl 40.6.0 → 41.0.1

package/ts/functions.flexprivatesnapshot.ts

@@ -0,0 +1,601 @@
+import * as plugins from './plugins.js';
+import {
+  type IFlexPrivateCandidateDocument,
+  type IFlexPrivateChunkDocument,
+  type TFlexDomainKind,
+  assertFlexPrivateCandidateDocument,
+  assertFlexPrivateChunkDocument,
+  flexPrivateChunkBytes,
+} from './classes.flexmodels.private.js';
+
+/*
+ * A private snapshot is stored as the JSON of the snapshot cut into content-addressed chunks
+ * (`IFlexPrivateChunkDocument`), listed in order by a candidate (`IFlexPrivateCandidateDocument`)
+ * that names the SHA-256 of the whole JSON. The JSON is cut in runs, and a chunk never spans two
+ * runs:
+ *
+ * - a growing list of a projection (`packedLists`) is its own run, packed entry by entry from the
+ *   list's start into chunks of up to 64 KiB (an entry over the chunk size is cut in slices), so a
+ *   chunk's end depends only on the entries before it;
+ * - everything else, and the whole snapshot of the other domains, is cut into slices of
+ *   `flexPrivateChunkBytes` from the run's start.
+ *
+ * A save rebuilds only what its change touches: it keeps the layout of the candidate it replaces
+ * (`IFlexPrivateLayout`: each chunk with its bytes and where each list entry lies in them), takes
+ * every chunk whose bytes the change leaves in place, and serializes, hashes and encodes only the
+ * entries and chunks from the change on. The whole-snapshot SHA-256 is one pass over the chunks'
+ * bytes in order. A build without a previous layout is the full path: it serializes every entry.
+ * Both produce the bytes AGL 40.5.0 wrote; `test/test.flexprivatesnapshot.node.ts` proves it
+ * against that serializer.
+ */
+
+/** The lists of a domain snapshot that grow entry by entry, each packed in its own run. */
+const packedLists: Partial<Record<TFlexDomainKind, readonly string[]>> = {
+  projection: ['messages', 'reversionSegments'],
+};
+
+/**
+ * The list a domain snapshot stores as the last member of its one run. Its entries' bytes stay
+ * where they are when the snapshot's other members keep their length, so a save that changes the
+ * list's newest entries rebuilds the run's first slice and the slices from the change on.
+ */
+const streamedLists: Partial<Record<TFlexDomainKind, string>> = {
+  agentEvents: 'events',
+};
+
+/** A chunk of a growing list stays under this size, so a change rewrites little of the list. */
+const privateListChunkBytes = 64 * 1024;
+
+const sha256 = (valueArg: Uint8Array | string): string =>
+  plugins.crypto.createHash('sha256').update(valueArg).digest('hex');
+
+/** The domain incarnation whose snapshot a layout stores: its chunks are addressed within it. */
+export interface IFlexPrivateSnapshotOwner {
+  controllerId: string;
+  storageKey: string;
+  domain: TFlexDomainKind;
+  sessionId?: string;
+  archiveId?: string;
+  incarnationId: string;
+}
+
+export const privateCandidateDocumentId = (candidateIdArg: string): string =>
+  `flex-private-candidate:${candidateIdArg}`;
+
+/**
+ * Private chunks are addressed by their content within one domain incarnation, so a save stores
+ * only the chunks it changed and shares the others with the snapshot it replaces.
+ */
+export const privateChunkDocumentId = (
+  ownerArg: IFlexPrivateSnapshotOwner,
+  chunkDigestArg: string,
+): string => `flex-private-chunk:${sha256(JSON.stringify([
+  ownerArg.controllerId,
+  ownerArg.storageKey,
+  ownerArg.domain,
+  ownerArg.sessionId ?? null,
+  ownerArg.archiveId ?? null,
+  ownerArg.incarnationId,
+  chunkDigestArg,
+]))}`;
+
+const ownerKey = (ownerArg: IFlexPrivateSnapshotOwner): string => JSON.stringify([
+  ownerArg.controllerId,
+  ownerArg.storageKey,
+  ownerArg.domain,
+  ownerArg.sessionId ?? null,
+  ownerArg.archiveId ?? null,
+  ownerArg.incarnationId,
+]);
+
+/** A stored chunk and its bytes, which stay valid while a cached layout holds the chunk. */
+export interface IFlexPrivateChunk {
+  readonly id: string;
+  readonly sha256: string;
+  readonly bytes: number;
+  /** The chunk's own memory, zeroed once no cached layout holds it. */
+  readonly data: Buffer;
+  /** How many cached layouts hold the chunk. */
+  holders: number;
+}
+
+/** The list a sliced run streams between its head and tail, and where each entry's piece ends. */
+interface IFlexSlicedList {
+  readonly key: string;
+  readonly entries: readonly unknown[];
+  /** The offset in the run where each entry's piece (its JSON, after a comma but the first) ends. */
+  readonly ends: readonly number[];
+}
+
+/** A run cut into slices of `flexPrivateChunkBytes` from its start. */
+interface IFlexSlicedRun {
+  readonly kind: 'sliced';
+  readonly head: Buffer;
+  readonly list?: IFlexSlicedList;
+  readonly tail: Buffer;
+  readonly bytes: number;
+  readonly chunks: readonly IFlexPrivateChunk[];
+}
+
+/** A chunk of a packed run: whole pieces `first` to `end`, or one slice of the piece `first`. */
+interface IFlexPackedChunk {
+  readonly chunk: IFlexPrivateChunk;
+  readonly first: number;
+  readonly end: number;
+  readonly sliced: boolean;
+}
+
+/** A list's run of entry pieces, packed into chunks from the list's start. */
+interface IFlexPackedRun {
+  readonly kind: 'packed';
+  readonly key: string;
+  readonly entries: readonly unknown[];
+  /** The bytes of each entry's piece, the separating comma included. */
+  readonly pieceBytes: readonly number[];
+  readonly chunks: readonly IFlexPackedChunk[];
+}
+
+type TFlexPrivateRun = IFlexSlicedRun | IFlexPackedRun;
+
+/** How a stored private snapshot lies in its chunks, kept while this writer holds its lease. */
+export interface IFlexPrivateLayout {
+  readonly owner: string;
+  readonly runs: readonly TFlexPrivateRun[];
+  /** Every chunk, in candidate order. */
+  readonly chunks: readonly IFlexPrivateChunk[];
+  readonly bytes: number;
+  readonly sha256: string;
+}
+
+type TFlexRunSource =
+  | {
+    kind: 'sliced';
+    head: string;
+    list?: { key: string; entries: readonly unknown[] };
+    tail: string;
+  }
+  | { kind: 'packed'; key: string; entries: readonly unknown[] };
+
+/** A snapshot that streams `keyArg` when it is the last member and a list; else its JSON whole. */
+const streamedRun = (snapshotArg: object, keyArg: string | undefined): TFlexRunSource => {
+  const keys = Object.keys(snapshotArg);
+  const value = keyArg === undefined ? undefined : Reflect.get(snapshotArg, keyArg);
+  if (keyArg === undefined || keys.at(-1) !== keyArg || !Array.isArray(value)) {
+    return { kind: 'sliced', head: JSON.stringify(snapshotArg), tail: '' };
+  }
+  const rest = JSON.stringify(Object.fromEntries(
+    keys.slice(0, -1).map((key) => [key, Reflect.get(snapshotArg, key)]),
+  ));
+  return {
+    kind: 'sliced',
+    head: `${rest.slice(0, -1)}${rest === '{}' ? '' : ','}${JSON.stringify(keyArg)}:[`,
+    list: { key: keyArg, entries: value },
+    tail: ']}',
+  };
+};
+
+/** The runs of a snapshot's JSON, in order. */
+const describeRuns = (snapshotArg: unknown, domainArg: TFlexDomainKind): TFlexRunSource[] => {
+  if (snapshotArg === null || typeof snapshotArg !== 'object' || Array.isArray(snapshotArg)) {
+    return [{ kind: 'sliced', head: JSON.stringify(snapshotArg), tail: '' }];
+  }
+  const listKeys = packedLists[domainArg] ?? [];
+  if (listKeys.length === 0) return [streamedRun(snapshotArg, streamedLists[domainArg])];
+  const runs: TFlexRunSource[] = [];
+  let frame = '{';
+  let first = true;
+  for (const [key, value] of Object.entries(snapshotArg)) {
+    if (value === undefined) continue;
+    frame += `${first ? '' : ','}${JSON.stringify(key)}:`;
+    first = false;
+    if (listKeys.includes(key) && Array.isArray(value) && value.length > 0) {
+      runs.push({ kind: 'sliced', head: `${frame}[`, tail: '' });
+      runs.push({ kind: 'packed', key, entries: value });
+      frame = ']';
+    } else {
+      frame += JSON.stringify(value);
+    }
+  }
+  runs.push({ kind: 'sliced', head: `${frame}}`, tail: '' });
+  return runs;
+};
+
+/** How many entries two lists share from their start, by identity. */
+const sharedPrefix = (leftArg: readonly unknown[], rightArg: readonly unknown[]): number => {
+  const limit = Math.min(leftArg.length, rightArg.length);
+  let index = 0;
+  while (index < limit && leftArg[index] === rightArg[index]) index++;
+  return index;
+};
+
+type TMint = (dataArg: Buffer) => IFlexPrivateChunk;
+
+/** A piece of a run's new bytes: its length and how to copy a range of it. */
+interface IFlexRunSegment {
+  readonly bytes: number;
+  copy(targetArg: Buffer, targetOffsetArg: number, fromArg: number, toArg: number): void;
+}
+
+const bufferSegment = (bufferArg: Buffer): IFlexRunSegment => ({
+  bytes: bufferArg.byteLength,
+  copy: (targetArg, targetOffsetArg, fromArg, toArg) => {
+    bufferArg.copy(targetArg, targetOffsetArg, fromArg, toArg);
+  },
+});
+
+/** The bytes `fromArg` to `toArg` of a sliced run, read from its chunks. */
+const previousSegment = (runArg: IFlexSlicedRun, fromArg: number, toArg: number): IFlexRunSegment => ({
+  bytes: toArg - fromArg,
+  copy: (targetArg, targetOffsetArg, startArg, endArg) => {
+    let offset = fromArg + startArg;
+    let target = targetOffsetArg;
+    while (offset < fromArg + endArg) {
+      const index = Math.floor(offset / flexPrivateChunkBytes);
+      const within = offset - index * flexPrivateChunkBytes;
+      const length = Math.min(fromArg + endArg - offset, flexPrivateChunkBytes - within);
+      runArg.chunks[index]!.data.copy(targetArg, target, within, within + length);
+      offset += length;
+      target += length;
+    }
+  },
+});
+
+/**
+ * Fills the chunks `rangesArg` names (sorted, disjoint, in run offsets) from the run's segments in
+ * one pass.
+ */
+const fillRanges = (
+  segmentsArg: readonly IFlexRunSegment[],
+  rangesArg: ReadonlyArray<{ start: number; end: number; data: Buffer }>,
+): void => {
+  let rangeIndex = 0;
+  let position = 0;
+  for (const segment of segmentsArg) {
+    const segmentEnd = position + segment.bytes;
+    while (rangeIndex < rangesArg.length && rangesArg[rangeIndex]!.end <= position) rangeIndex++;
+    for (let index = rangeIndex; index < rangesArg.length && rangesArg[index]!.start < segmentEnd; index++) {
+      const range = rangesArg[index]!;
+      const from = Math.max(range.start, position);
+      const to = Math.min(range.end, segmentEnd);
+      if (from < to) segment.copy(range.data, from - range.start, from - position, to - position);
+    }
+    position = segmentEnd;
+  }
+};
+
+/** `textArg` as UTF-8 in memory of its own, never a slice of Node's shared buffer pool. */
+const ownBytes = (textArg: string): Buffer => {
+  const data = Buffer.alloc(Buffer.byteLength(textArg, 'utf8'));
+  data.write(textArg, 'utf8');
+  return data;
+};
+
+const updateSlicedRun = (
+  previousArg: IFlexSlicedRun | undefined,
+  sourceArg: Extract<TFlexRunSource, { kind: 'sliced' }>,
+  mintArg: TMint,
+): IFlexSlicedRun => {
+  const head = ownBytes(sourceArg.head);
+  const tail = ownBytes(sourceArg.tail);
+  const entries = sourceArg.list?.entries ?? [];
+  const previousList = previousArg?.list !== undefined && previousArg.list.key === sourceArg.list?.key
+    ? previousArg.list
+    : undefined;
+  const kept = previousList ? sharedPrefix(entries, previousList.entries) : 0;
+  // The pieces of the kept entries are taken from the previous run's bytes, never serialized again.
+  const previousListStart = previousArg?.head.byteLength ?? 0;
+  const keptEnd = kept > 0 ? previousList!.ends[kept - 1]! : previousListStart;
+  const fresh: Buffer[] = [];
+  for (let index = kept; index < entries.length; index++) {
+    fresh.push(Buffer.from(`${index === 0 ? '' : ','}${JSON.stringify(entries[index]) ?? 'null'}`, 'utf8'));
+  }
+  const shift = head.byteLength - previousListStart;
+  const ends: number[] = [];
+  for (let index = 0; index < kept; index++) ends.push(previousList!.ends[index]! + shift);
+  let offset = head.byteLength + keptEnd - previousListStart;
+  for (const piece of fresh) {
+    offset += piece.byteLength;
+    ends.push(offset);
+  }
+  const bytes = offset + tail.byteLength;
+
+  // The bytes from `cleanFrom` to `cleanTo` are the previous run's bytes at the same offsets.
+  let cleanFrom = Number.POSITIVE_INFINITY;
+  let cleanTo = 0;
+  if (previousArg && head.byteLength === previousArg.head.byteLength) {
+    cleanFrom = head.equals(previousArg.head) ? 0 : head.byteLength;
+    const listUnchanged = previousList
+      ? kept === entries.length && kept === previousList.entries.length
+      : sourceArg.list === undefined && previousArg.list === undefined;
+    cleanTo = listUnchanged && tail.equals(previousArg.tail) ? bytes : keptEnd;
+  }
+  const count = Math.max(1, Math.ceil(bytes / flexPrivateChunkBytes));
+  const chunks: Array<IFlexPrivateChunk | undefined> = [];
+  const ranges: Array<{ index: number; start: number; end: number; data: Buffer }> = [];
+  for (let index = 0; index < count; index++) {
+    const start = index * flexPrivateChunkBytes;
+    const end = Math.min(start + flexPrivateChunkBytes, bytes);
+    const previousChunk = previousArg?.chunks[index];
+    if (
+      previousChunk
+      && start >= cleanFrom
+      && end <= cleanTo
+      && Math.min(start + flexPrivateChunkBytes, previousArg!.bytes) === end
+    ) {
+      chunks.push(previousChunk);
+    } else {
+      chunks.push(undefined);
+      ranges.push({ index, start, end, data: Buffer.alloc(end - start) });
+    }
+  }
+  if (ranges.length > 0) {
+    fillRanges([
+      bufferSegment(head),
+      ...(kept > 0 ? [previousSegment(previousArg!, previousListStart, keptEnd)] : []),
+      ...fresh.map(bufferSegment),
+      bufferSegment(tail),
+    ], ranges);
+    for (const range of ranges) chunks[range.index] = mintArg(range.data);
+  }
+  for (const piece of fresh) piece.fill(0);
+  return {
+    kind: 'sliced',
+    head,
+    ...(sourceArg.list ? { list: { key: sourceArg.list.key, entries, ends } } : {}),
+    tail,
+    bytes,
+    chunks: chunks as IFlexPrivateChunk[],
+  };
+};
+
+/** The index of the last chunk that starts at or before piece `pieceArg`: the chunk holding it. */
+const chunkHolding = (chunksArg: readonly IFlexPackedChunk[], pieceArg: number): number => {
+  let low = 0;
+  let high = chunksArg.length - 1;
+  while (low < high) {
+    const middle = (low + high + 1) >>> 1;
+    if (chunksArg[middle]!.first <= pieceArg) low = middle;
+    else high = middle - 1;
+  }
+  return low;
+};
+
+const copyOf = (partsArg: readonly Buffer[], bytesArg: number): Buffer => {
+  const data = Buffer.alloc(bytesArg);
+  let offset = 0;
+  for (const part of partsArg) offset += part.copy(data, offset);
+  return data;
+};
+
+const updatePackedRun = (
+  previousArg: IFlexPackedRun | undefined,
+  sourceArg: Extract<TFlexRunSource, { kind: 'packed' }>,
+  mintArg: TMint,
+): IFlexPackedRun => {
+  const entries = sourceArg.entries;
+  const kept = previousArg ? sharedPrefix(entries, previousArg.entries) : 0;
+  if (previousArg && kept === entries.length && kept === previousArg.entries.length) {
+    return { ...previousArg, entries };
+  }
+  // Chunks end where the packing from the list's start ends them, so every chunk before the one
+  // holding the last kept piece stays; packing resumes at that chunk's start, where it began
+  // empty. A kept piece cut in slices ends its own chunks, so packing resumes after it.
+  const chunks: IFlexPackedChunk[] = [];
+  let restart = 0;
+  let restartChunk: IFlexPackedChunk | undefined;
+  if (previousArg && kept > 0) {
+    const holding = chunkHolding(previousArg.chunks, kept - 1);
+    const chunk = previousArg.chunks[holding]!;
+    if (chunk.sliced) {
+      chunks.push(...previousArg.chunks.slice(0, holding + 1));
+      restart = kept;
+    } else {
+      chunks.push(...previousArg.chunks.slice(0, holding));
+      restart = chunk.first;
+      restartChunk = chunk;
+    }
+  }
+  const pieceBytes = previousArg ? previousArg.pieceBytes.slice(0, kept) : [];
+  let pending: Buffer[] = [];
+  let pendingBytes = 0;
+  let pendingFirst = restart;
+  const fresh: Buffer[] = [];
+  const flush = (endArg: number): void => {
+    if (pending.length === 0) return;
+    chunks.push({
+      chunk: mintArg(copyOf(pending, pendingBytes)),
+      first: pendingFirst,
+      end: endArg,
+      sliced: false,
+    });
+    pending = [];
+    pendingBytes = 0;
+  };
+  let keptOffset = 0;
+  for (let index = restart; index < entries.length; index++) {
+    let piece: Buffer;
+    if (index < kept) {
+      const length = previousArg!.pieceBytes[index]!;
+      piece = restartChunk!.chunk.data.subarray(keptOffset, keptOffset + length);
+      keptOffset += length;
+    } else {
+      piece = Buffer.from(`${index === 0 ? '' : ','}${JSON.stringify(entries[index])}`, 'utf8');
+      pieceBytes.push(piece.byteLength);
+      fresh.push(piece);
+    }
+    if (pendingBytes > 0 && pendingBytes + piece.byteLength > privateListChunkBytes) flush(index);
+    if (piece.byteLength <= flexPrivateChunkBytes - pendingBytes) {
+      if (pending.length === 0) pendingFirst = index;
+      pending.push(piece);
+      pendingBytes += piece.byteLength;
+      continue;
+    }
+    flush(index);
+    for (let offset = 0; offset < piece.byteLength; offset += flexPrivateChunkBytes) {
+      chunks.push({
+        chunk: mintArg(copyOf(
+          [piece.subarray(offset, Math.min(offset + flexPrivateChunkBytes, piece.byteLength))],
+          Math.min(flexPrivateChunkBytes, piece.byteLength - offset),
+        )),
+        first: index,
+        end: index + 1,
+        sliced: true,
+      });
+    }
+  }
+  flush(entries.length);
+  for (const piece of fresh) piece.fill(0);
+  return { kind: 'packed', key: sourceArg.key, entries, pieceBytes, chunks };
+};
+
+export interface IFlexPrivateSnapshotBuildOptions {
+  owner: IFlexPrivateSnapshotOwner;
+  candidateId: string;
+  revision: number;
+  createdAt: string;
+  snapshot: unknown;
+  /**
+   * The layout of the candidate the domain head names now. Its unchanged chunks are taken as
+   * they are; without it every entry is serialized (the full path).
+   */
+  previous?: IFlexPrivateLayout;
+  /** The ids of the chunks the current candidate stores, which a save never writes again. */
+  sharedChunkIds: ReadonlySet<string>;
+}
+
+export interface IFlexPrivateSnapshotBuild {
+  readonly layout: IFlexPrivateLayout;
+  readonly candidate: IFlexPrivateCandidateDocument;
+  /** The documents of the chunks this build made that `sharedChunkIds` does not name, in order. */
+  readonly chunks: IFlexPrivateChunkDocument[];
+  /** The chunks this build made; zero those no cached layout holds once the save ends. */
+  readonly minted: readonly IFlexPrivateChunk[];
+}
+
+/** The candidate and chunk documents that store `snapshot`, and the layout they leave. */
+export const buildFlexPrivateSnapshot = (
+  optionsArg: IFlexPrivateSnapshotBuildOptions,
+): IFlexPrivateSnapshotBuild => {
+  const owner = optionsArg.owner;
+  const key = ownerKey(owner);
+  const previous = optionsArg.previous?.owner === key ? optionsArg.previous : undefined;
+  const minted: IFlexPrivateChunk[] = [];
+  const mint: TMint = (dataArg) => {
+    const digest = sha256(dataArg);
+    const chunk: IFlexPrivateChunk = {
+      id: privateChunkDocumentId(owner, digest),
+      sha256: digest,
+      bytes: dataArg.byteLength,
+      data: dataArg,
+      holders: 0,
+    };
+    minted.push(chunk);
+    return chunk;
+  };
+  try {
+    const previousPacked = new Map<string, IFlexPackedRun>();
+    const previousSliced: IFlexSlicedRun[] = [];
+    for (const run of previous?.runs ?? []) {
+      if (run.kind === 'packed') previousPacked.set(run.key, run);
+      else previousSliced.push(run);
+    }
+    let slicedIndex = 0;
+    const runs = describeRuns(optionsArg.snapshot, owner.domain).map((source): TFlexPrivateRun => (
+      source.kind === 'packed'
+        ? updatePackedRun(previousPacked.get(source.key), source, mint)
+        : updateSlicedRun(previousSliced[slicedIndex++], source, mint)
+    ));
+    const chunks = runs.flatMap((run) => (
+      run.kind === 'packed' ? run.chunks.map((entry) => entry.chunk) : run.chunks
+    ));
+    if (chunks.length === 0) chunks.push(mint(Buffer.alloc(0)));
+    // The whole-snapshot digest: one pass over the chunks' bytes, never joined into one buffer.
+    const hash = plugins.crypto.createHash('sha256');
+    let bytes = 0;
+    for (const chunk of chunks) {
+      hash.update(chunk.data);
+      bytes += chunk.bytes;
+    }
+    const digest = hash.digest('hex');
+    const identity = {
+      domain: owner.domain,
+      incarnationId: owner.incarnationId,
+      ...(owner.sessionId !== undefined ? { sessionId: owner.sessionId } : {}),
+      ...(owner.archiveId !== undefined ? { archiveId: owner.archiveId } : {}),
+    };
+    const made = new Set(minted);
+    const documents: IFlexPrivateChunkDocument[] = [];
+    chunks.forEach((chunk, index) => {
+      if (!made.has(chunk) || optionsArg.sharedChunkIds.has(chunk.id)) return;
+      documents.push({
+        id: chunk.id,
+        controllerId: owner.controllerId,
+        scopeId: owner.storageKey,
+        candidateId: optionsArg.candidateId,
+        revision: optionsArg.revision,
+        index,
+        sha256: chunk.sha256,
+        bytes: chunk.bytes,
+        data: chunk.data.toString('base64'),
+        createdAt: optionsArg.createdAt,
+        ...identity,
+      });
+    });
+    const candidate: IFlexPrivateCandidateDocument = {
+      id: privateCandidateDocumentId(optionsArg.candidateId),
+      controllerId: owner.controllerId,
+      scopeId: owner.storageKey,
+      candidateId: optionsArg.candidateId,
+      revision: optionsArg.revision,
+      sha256: digest,
+      bytes,
+      chunks: chunks.map(({ id, sha256: chunkDigest, bytes: chunkBytes }, index) => ({
+        id, index, sha256: chunkDigest, bytes: chunkBytes,
+      })),
+      createdAt: optionsArg.createdAt,
+      ...identity,
+    };
+    assertFlexPrivateCandidateDocument(candidate);
+    for (const document of documents) assertFlexPrivateChunkDocument(document);
+    return {
+      layout: { owner: key, runs, chunks, bytes, sha256: digest },
+      candidate,
+      chunks: documents,
+      minted,
+    };
+  } catch (errorArg) {
+    for (const chunk of minted) chunk.data.fill(0);
+    throw errorArg;
+  }
+};
+
+/** Marks the layout's chunks as held by one more cached snapshot. */
+export const holdFlexPrivateLayout = (layoutArg: IFlexPrivateLayout): void => {
+  for (const chunk of new Set(layoutArg.chunks)) chunk.holders += 1;
+};
+
+/**
+ * Ends one cached snapshot's hold on the layout: zeroes its own run frames and the chunks no
+ * layout holds now.
+ */
+export const releaseFlexPrivateLayout = (layoutArg: IFlexPrivateLayout): void => {
+  for (const chunk of new Set(layoutArg.chunks)) {
+    chunk.holders -= 1;
+    if (chunk.holders <= 0) {
+      chunk.holders = 0;
+      chunk.data.fill(0);
+    }
+  }
+  for (const run of layoutArg.runs) {
+    if (run.kind !== 'sliced') continue;
+    run.head.fill(0);
+    run.tail.fill(0);
+  }
+};
+
+/** Zeroes the chunks no cached layout holds, such as those of a build that was not cached. */
+export const discardFlexPrivateChunks = (chunksArg: readonly IFlexPrivateChunk[]): void => {
+  for (const chunk of chunksArg) {
+    if (chunk.holders === 0) chunk.data.fill(0);
+  }
+};

package/ts/functions.mcptickettools.ts

@@ -4,7 +4,7 @@ import type { TTicketOperation } from '../ts_interfaces/tickets.js';
 const workflow = ' Caller identity comes from AGL, never a supplied name. Unidentified callers may list/get tickets with empty mine; every mutation requires a verified caller. Workers create in backlog and may update/move only their assigned tickets within ready, in_progress, needs_input and review. Link a branch with a full sha before Review. Only the driver or owner assigns, lands or releases tickets.';
 export const ticketToolDefinitions = [
   { name: 'tickets_list', operation: 'list', description: 'Read the shared board across all projects. Filter by mine, project, status, label or text. mine uses your verified session. label also matches AutoLabels, which AGL computes and nobody sets: openQuestion marks a ticket with an unanswered question.' },
-  { name: 'ticket_get', operation: 'get', description: 'Read a ticket by its AGL-<n> key, with markdown comments, source, links, its questions and their answers, and the complete activity log.' },
+  { name: 'ticket_get', operation: 'get', description: 'Read a ticket by its AGL-<n> key: source, links, all its questions and their answers, and the newest page of its history, oldest first: up to limit entries (default 50, at most 500), fewer when the entries and their comments would pass 256 KiB. activity is the page; comments are the markdown comments it names, and a commented entry names its comment by id. historyBefore is present while older history exists: pass it as before for the next older page. commentId instead reads the one comment an activity entry or fleet event names (without before or limit).' },
   { name: 'ticket_create', operation: 'create', description: 'Capture discussed work as a ticket. Include project, title, description and sourceText (the original words); optional attachments are named URLs. Worker-created tickets start in backlog for driver triage.' },
   { name: 'ticket_update', operation: 'update', description: 'Update the title, markdown description, priority, labels, project or parent of your assigned ticket. Supply expectedRevision from the ticket you read; stale edits return TICKET_REVISION_CONFLICT with currentRevision. Reload before editing again. Status is changed only with ticket_move; assignment is driver/owner-only.' },
   { name: 'ticket_move', operation: 'move', description: 'Atomically move/reorder your assigned ticket. Omit beforeTicketId to append. Returns every record whose column or order changed. Review requires a linked branch and sha. Use needs_input to report a blocker.' },

package/ts/functions.ticketcli.ts

@@ -8,7 +8,10 @@ import type { ITicketChanges, ITicketPerson, TTicketOperation, TTicketRequest, T
 export const ticketCliHelp = `Usage: agl ticket <list|get|create|update|move|comment|link|assign|ask|answer> [AGL-<n>] [options]
   list    [--mine] [--project ID] [--status COLUMN] [--label LABEL] [--text TEXT]
           --label also matches AutoLabels, which AGL computes: openQuestion (an unanswered question)
-  get     AGL-<n>
+  get     AGL-<n> [--limit N] [--before HISTORY-ID] [--comment COMMENT-ID]
+          The ticket, its questions and the newest N history entries (default 50, at most 500, within 256 KiB);
+          historyBefore names the next older page: pass it as --before.
+          --comment reads the one comment an activity entry names instead (not with --limit or --before)
   create  --project ID --title TEXT [--description MARKDOWN] [--kind epic|task|subtask]
           [--parent AGL-<n>] [--priority none|low|normal|high|urgent] [--labels a,b]
           [--source TEXT] [--attachments JSON] [--column COLUMN]
@@ -38,7 +41,7 @@ export interface ITicketCliArguments {
 }
 const common = ['port', 'json'];
 const actionOptions: Record<string, string[]> = {
-  list: ['mine', 'project', 'status', 'label', 'text'], get: [],
+  list: ['mine', 'project', 'status', 'label', 'text'], get: ['limit', 'before', 'comment'],
   create: ['project', 'title', 'description', 'kind', 'parent', 'priority', 'labels', 'source', 'attachments', 'column'],
   update: ['expected-revision', 'changes', 'title', 'description', 'priority', 'project', 'labels', 'parent', 'clear-parent'],
   move: ['column', 'before'], comment: ['body'], link: ['repo', 'branch', 'sha', 'package', 'version'],
@@ -78,7 +81,8 @@ export const parseTicketCliArguments = (argumentsArg: string[]): ITicketCliArgum
   const operation = action === 'assign' ? 'update' : action as TTicketOperation;
   if (action === 'list') request = { ...(options.has('mine') ? { mine: true } : {}), ...optional('project'),
     ...optional('status'), ...optional('label'), ...optional('text') };
-  else if (action === 'get') request = { ticketId };
+  else if (action === 'get') request = { ticketId, ...optional('before'), ...optional('comment', 'commentId'),
+    ...(options.has('limit') ? { limit: Number(required('limit')) } : {}) };
   else if (action === 'create') request = { project: required('project'), title: required('title'), ...optional('description'),
     ...optional('kind'), ...optional('parent', 'parentId'), ...optional('priority'), ...labels(), ...optional('source', 'sourceText'),
     ...optional('column', 'columnId'), ...(options.has('attachments') ? { attachments: JSON.parse(required('attachments')) } : {}) };

package/ts/functions.ticketvalidation.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import { ticketAutoLabels, ticketColumns, type TTicketOperation, type TTicketRequest } from '../ts_interfaces/tickets.js';
+import { ticketAutoLabels, ticketColumns, ticketHistoryPage, type TTicketOperation, type TTicketRequest } from '../ts_interfaces/tickets.js';
 
 const text = (maximumArg: number) => plugins.z.string().max(maximumArg);
 const identifier = text(1024).min(1).refine((valueArg) => !/[\x00-\x1f\x7f]/u.test(valueArg));
@@ -38,7 +38,11 @@ const changes = plugins.z.object({
 export const ticketInputSchemas = {
   list: filters, board: filters,
   search: plugins.z.object({ query: text(1024), label: text(100).min(1).optional() }).strict(),
-  get: plugins.z.object({ ticketId }).strict(), comments: plugins.z.object({ ticketId }).strict(),
+  get: plugins.z.object({ ticketId, before: identifier.optional(),
+    limit: plugins.z.number().int().min(1).max(ticketHistoryPage.maximum).optional(), commentId: identifier.optional() }).strict()
+    .refine((valueArg) => valueArg.commentId === undefined || (valueArg.before === undefined && valueArg.limit === undefined),
+      'commentId reads one comment and excludes before and limit.'),
+  comments: plugins.z.object({ ticketId }).strict(),
   create: plugins.z.object({ project: identifier, kind: kind.optional(), title: text(200).trim().min(1),
     description: text(64 * 1024).optional(), columnId: plugins.z.enum(ticketColumns).optional(), parentId: ticketId.optional(),
     priority: priority.optional(), assignee: person.optional(), labels: labels.optional(), sourceText: text(64 * 1024).optional(),
@@ -117,7 +121,7 @@ export const assertTicketResponse = (methodArg: string, valueArg: unknown): void
       id: plugins.z.enum(ticketColumns), title: plugins.z.string(), done: plugins.z.boolean().optional() }).strict()), tickets: plugins.z.array(ticket),
       viewer: person }).strict(),
     get: plugins.z.object({ ticket, comments: plugins.z.array(ticketCommentSchema), activity: plugins.z.array(ticketActivitySchema),
-      questions: plugins.z.array(ticketQuestionSchema) }).strict(),
+      questions: plugins.z.array(ticketQuestionSchema), historyBefore: identifier.optional() }).strict(),
     comments: plugins.z.object({ comments: plugins.z.array(ticketCommentSchema) }).strict(),
     create: plugins.z.object({ ticket }).strict(), update: plugins.z.object({ ticket }).strict(),
     link: plugins.z.object({ ticket }).strict(), move: plugins.z.object({ tickets: plugins.z.array(ticket) }).strict(),