Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.5 KB
Raw Blame
/**
 * `content_hash` as a resumable stream (Wave B, spec 1.4). `contentHash`
 * (utils.ts) is sha256 over
 *
 *   JSON.stringify({title, type, compiled_truth, timeline || '', frontmatter*, tags*})
 *
 * This module feeds the same bytes piece by piece:
 *
 *   '{"title":' J(title) ',"type":' J(type) ',"compiled_truth":"' E(truth 1) E(truth 2) ...
 *   '","timeline":"' E(timeline 1) ... '","frontmatter":' J(frontmatter*) ',"tags":' J(tags*) '}'
 *
 * with J = JSON.stringify and E(s) = JSON.stringify(s).slice(1, -1). E is exact
 * for any split on a code-point boundary (segments always end on one), so the
 * digest depends only on the logical page, never on where segments were cut.
 *
 * A manifest row stores `exportState()` after its own E(...) bytes
 * (`hash_state`). Resume rules:
 * - append to the last region: resume from the last row's state, push the appended text;
 * - append to the truth while the timeline is non-empty: resume from the last truth row,
 *   push the appended truth, then re-push every timeline row;
 * - frontmatter or tags change: resume from the last row and `finish` with the new values;
 * - title or type change: the prefix changed, start over with `begin`.
 */
import type { PageInput } from '../types.ts';
import { contentHashFrontmatterAndTags } from '../utils.ts';
import { ResumableSha256 } from './sha256-resumable.ts';

type Phase = 'truth' | 'timeline';
const PHASE_BYTE: Record<Phase, number> = { truth: 0, timeline: 1 };

/** Largest `ContentHashStream.exportState()` result in bytes (phase byte plus SHA-256 midstate). */
export const CONTENT_HASH_STATE_MAX_BYTES = 104;

/** Envelope member text: `"name":` + J(value), or '' when JSON.stringify omits the member. */
function member(name: string, value: unknown): string {
  const json = JSON.stringify(value);
  return json === undefined ? '' : `"${name}":${json}`;
}

export class ContentHashStream {
  private constructor(private readonly sha: ResumableSha256, private phase: Phase) {}

  /** Start a page: feeds the envelope through the opening quote of `compiled_truth`. */
  static begin(page: { title: unknown; type: unknown }): ContentHashStream {
    const stream = new ContentHashStream(new ResumableSha256(), 'truth');
    const head = [member('title', page.title), member('type', page.type)].filter(Boolean);
    head.push('"compiled_truth":"');
    stream.feed(`{${head.join(',')}`);
    return stream;
  }

  static fromState(state: Uint8Array): ContentHashStream {
    const phase = state[0] === PHASE_BYTE.timeline ? 'timeline' : state[0] === PHASE_BYTE.truth ? 'truth' : null;
    if (!phase) throw new Error(`content hash state has an unknown phase byte ${state[0]}`);
    return new ContentHashStream(ResumableSha256.fromState(state.subarray(1)), phase);
  }

  /** Append compiled_truth text (a whole number of code points). */
  pushTruth(text: string): this {
    if (this.phase !== 'truth') throw new Error('content hash stream: truth text after the timeline began');
    this.feed(JSON.stringify(text).slice(1, -1));
    return this;
  }

  /** Close compiled_truth and open the timeline string. Idempotent. */
  beginTimeline(): this {
    if (this.phase === 'truth') {
      this.feed('","timeline":"');
      this.phase = 'timeline';
    }
    return this;
  }

  /** Append timeline text (a whole number of code points); opens the timeline first if needed. */
  pushTimeline(text: string): this {
    this.beginTimeline();
    this.feed(JSON.stringify(text).slice(1, -1));
    return this;
  }

  /** The midstate after everything pushed so far (at most CONTENT_HASH_STATE_MAX_BYTES). */
  exportState(): Uint8Array {
    const sha = this.sha.exportState();
    const out = new Uint8Array(1 + sha.length);
    out[0] = PHASE_BYTE[this.phase];
    out.set(sha, 1);
    return out;
  }

  /** Hex content_hash with this frontmatter and tags. The stream itself is left unchanged. */
  finish(meta: Pick<PageInput, 'frontmatter' | 'tags'>): string {
    const tail = ContentHashStream.fromState(this.exportState()).beginTimeline();
    const { frontmatter, tags } = contentHashFrontmatterAndTags(meta);
    tail.feed(`",${member('frontmatter', frontmatter)},${member('tags', tags)}}`);
    return tail.sha.digest();
  }

  private feed(text: string): void {
    this.sha.update(Buffer.from(text, 'utf8'));
  }
}

/** `contentHash(page)` computed through the stream, one push per region (tests and small callers). */
export function streamingContentHash(page: PageInput): string {
  return ContentHashStream.begin(page).pushTruth(page.compiled_truth).pushTimeline(page.timeline || '').finish(page);
}