Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Segmented page storage (Wave B, spec 7.3): one segment's read projection,
* the text whole-body sanitization (page-window/document.ts projectPageText)
* gives for that stretch of the body, computed from the segment alone.
*
* Whole segments are projected, never a bare slice: the stored protected
* regions remove takes runs, a truncated tail, materialized markers and the
* pem guard, replace each private key with the projection token plus its
* newlines, and leave each facts region as a slot rendered here (world rows
* only, minus rows the text marks forgotten, through renderFactsRegion; a
* region crossing the segment's bounds is omitted). The caller hands in the
* segment text after the withdrawal overlay; this applies the fence overlay
* (held and purged rows out, rows below the page tier moved to the low-tier
* block). When either changed the text, or the stored metadata is stale, the
* regions are recomputed by segmenting the text from the segment's carried
* entry state; with no usable entry state the read refuses with
* `page_projection_stale`, never raw text.
*
* Each piece maps back to the stored bytes it stands for, so a stored-space
* range selects pieces: text is cut byte for byte where the mapping is
* linear; a token, a rendered facts table or text a transform rewrote is
* emitted whole or not at all.
*/
import { opError } from '../ops/contract.ts';
import { renderFactsRegion } from '../remote-body.ts';
import { credentialSafeProjection } from '../credential-projection.ts';
import { fenceLowTierRows, splitFenceOverlay, type FenceChunkOverlay, type FenceLowTierRow } from '../eligibility/fence-overlay.ts';
import { readEntryState } from './entry-state.ts';
import { utf8Len } from './region-scan.ts';
import { segmentProjectionParts, segmentString, type StoredRegion } from './segmenter.ts';
import type { BodyRegion } from './types.ts';
const utf8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
/** The stored parts of one segment the projection reads (a manifest row and its text). */
export interface ProjectableSegment {
region: BodyRegion;
bytes: Uint8Array;
/** Stored-stream offset and 0-based raw line of the segment's first byte. */
byteStart: number;
lineStart: number;
/** The stored entry state (JSON); only read when the regions are recomputed. */
entryState: unknown;
protectedRegions: readonly StoredRegion[];
/** The region's fence trust (body_flags), the trust stored regions were computed under. */
fenceTrust: 'trusted' | 'void';
}
export interface SegmentProjectionInput {
/** The segment text after the withdrawal overlay; defaults to the stored text. */
text?: string;
fenceOverlay?: FenceChunkOverlay;
/** The stored regions cannot be trusted (segmenter version or sha mismatch): recompute from the entry state. */
stale?: boolean;
}
/** A run of the projection: `text`, standing for stored bytes [rawStart, rawEnd) of the segment (segment-relative). */
export interface ProjectedPiece {
text: string;
rawStart: number;
rawEnd: number;
/** Projected text equals the stored bytes, so a stored range may cut it; otherwise it is emitted whole or not at all. */
linear: boolean;
}
export interface SegmentProjection {
pieces: ProjectedPiece[];
/** Rendered facts regions in slot order (bytes), for the outline's static-to-projected offsets. */
factsBytes: number[];
/** Rows the fence overlay moved to the page's low-tier block. */
lowTier: FenceLowTierRow[];
/** The regions were recomputed (a transform changed the text, or the metadata was stale). */
recomputed: boolean;
}
/** `page_projection_stale`: the segment's stored projection metadata is unusable and cannot be recomputed. */
export function projectionStaleError(byteStart: number, why: string) {
return opError('page_projection_stale',
`The segment at stored byte ${byteStart} cannot be projected: ${why}. Nothing was returned for it.`,
'Rewrite the page body (import or sync its file again) so it is segmented by this gbrain version, then read it again.');
}
export function projectSegment(segment: ProjectableSegment, input: SegmentProjectionInput = {}): SegmentProjection {
const raw = utf8.decode(segment.bytes);
const overlaid = input.text ?? raw;
const split = splitFenceOverlay(overlaid, input.fenceOverlay);
const lowTier = fenceLowTierRows(overlaid, input.fenceOverlay);
const text = split.main;
const recompute = input.stale === true || text !== raw;
const parts = recompute ? recomputedParts(segment, text) : segmentProjectionParts(raw, segment.protectedRegions, segment.byteStart);
const map = recompute ? diffMap(raw, text) : null;
const pieces: ProjectedPiece[] = [];
const factsBytes: number[] = [];
for (const part of parts) {
let out = '';
if (part.kind === 'text' || part.kind === 'pem') out = part.text;
else if (part.kind === 'facts') {
out = part.region!.open_start === undefined ? credentialSafeProjection(renderFactsRegion(part.text)) : '';
factsBytes.push(utf8Len(out));
}
if (!out) continue;
const at = map ? map(part.start, part.end) : { start: part.start, end: part.end, linear: true };
pieces.push({ text: out, rawStart: at.start, rawEnd: at.end, linear: part.kind === 'text' && at.linear });
}
return { pieces, factsBytes, lowTier, recomputed: recompute };
}
/**
* The trusted body view of a segment (its stored text after the withdrawal overlay) as pieces: one linear piece when
* the overlay changed nothing, else the unchanged prefix and suffix linear and the rewritten middle whole.
*/
export function overlaidPieces(raw: string, text: string): ProjectedPiece[] {
if (text === raw) return raw ? [{ text: raw, rawStart: 0, rawEnd: utf8Len(raw), linear: true }] : [];
const map = diffMap(raw, text);
const bytes = Buffer.from(text, 'utf8');
const cuts = [...new Set([0, map.head, map.textTail, bytes.length])].filter(b => b >= 0 && b <= bytes.length).sort((a, b) => a - b);
const pieces: ProjectedPiece[] = [];
for (let i = 0; i + 1 < cuts.length; i++) {
const at = map(cuts[i]!, cuts[i + 1]!);
pieces.push({ text: bytes.subarray(cuts[i]!, cuts[i + 1]!).toString('utf8'), rawStart: at.start, rawEnd: at.end, linear: at.linear });
}
return pieces;
}
/** The projection parts of `text` (the segment's text after a transform), segmented from the stored entry state. */
function recomputedParts(segment: ProjectableSegment, text: string) {
const entry = readEntryState(segment.entryState);
if (!entry || entry.region !== segment.region) throw projectionStaleError(segment.byteStart, 'its entry state is missing or of another version');
const segments = segmentString(text, entry, { byteStart: segment.byteStart, lineStart: segment.lineStart, fenceTrust: segment.fenceTrust, end: 'eof' });
return segments.flatMap(out => {
const shift = out.byteStart - segment.byteStart;
return segmentProjectionParts(utf8.decode(out.bytes), out.protectedRegions, out.byteStart)
.map(part => ({ ...part, start: part.start + shift, end: part.end + shift }));
});
}
/**
* Stored bytes of a transformed text's byte range: the common prefix and suffix of the stored and transformed texts map
* exactly, the rewritten middle maps to its whole stored extent.
*/
interface DiffMap {
(start: number, end: number): { start: number; end: number; linear: boolean };
/** Transformed-text bytes of the common prefix, and where the common suffix starts. */
head: number;
textTail: number;
}
function diffMap(raw: string, text: string): DiffMap {
const high = (c: number) => c >= 0xd800 && c <= 0xdbff;
let p = 0;
while (p < raw.length && p < text.length && raw.charCodeAt(p) === text.charCodeAt(p)) p++;
if (p > 0 && high(raw.charCodeAt(p - 1))) p--;
let q = 0;
while (q < raw.length - p && q < text.length - p && raw.charCodeAt(raw.length - 1 - q) === text.charCodeAt(text.length - 1 - q)) q++;
if (q > 0 && high(raw.charCodeAt(raw.length - 1 - q))) q--;
const head = utf8Len(raw, 0, p);
const rawTail = utf8Len(raw) - utf8Len(raw, raw.length - q);
const textTail = utf8Len(text) - utf8Len(text, text.length - q);
const at = (b: number, end: boolean) => b <= head ? b : b >= textTail ? b - textTail + rawTail : end ? rawTail : head;
return Object.assign((start: number, end: number) => ({ start: at(start, false), end: at(end, true), linear: end <= head || start >= textTail }),
{ head, textTail });
}