@namzu/sdk 59.0.0 → 60.0.0

package/src/sandbox/file-walk.ts

@@ -1,4 +1,4 @@
-import { isAbsolute, posix } from 'node:path'
+import { isAbsolute, join, posix } from 'node:path'
 import braceExpansion from 'brace-expansion'
 import { GLOBSTAR, Minimatch } from 'minimatch'
 import type {
@@ -6,9 +6,14 @@ import type {
 	SandboxExecResult,
 	SandboxFileEntry,
 	SandboxWalkFilesOptions,
+	SandboxWalkSummary,
 } from '../types/sandbox/index.js'
 import { subscribeToAbort } from '../utils/abort.js'
 import { FILE_WALK_PROGRAM } from './file-walk-program.js'
+import { VCS_NAMES, createIgnoreStack } from './ignore-matcher.js'
+
+/** Entries a walk examines before it stops with what it has: a safety valve, not a budget. */
+export const DEFAULT_MAX_VISITED_ENTRIES = 500_000
 
 interface WalkPlan {
 	root: string
@@ -18,6 +23,8 @@ interface WalkPlan {
 	maxEntries: number
 	maxVisitedEntries: number
 	includeHidden: boolean
+	respectIgnore: boolean
+	failOnLimit: boolean
 	patterns: (string | { source: string; flags: string } | null)[][]
 }
 
@@ -103,8 +110,13 @@ function planWalk(root: string, options: SandboxWalkFilesOptions): WalkPlan {
 		expressions,
 		maxDepth: Number.isFinite(maxDepth) ? maxDepth : null,
 		maxEntries: positiveInteger(options.maxEntries, 'maxEntries'),
-		maxVisitedEntries: positiveInteger(options.maxVisitedEntries ?? 20_000, 'maxVisitedEntries'),
+		maxVisitedEntries: positiveInteger(
+			options.maxVisitedEntries ?? DEFAULT_MAX_VISITED_ENTRIES,
+			'maxVisitedEntries',
+		),
 		includeHidden: options.includeHidden ?? false,
+		respectIgnore: options.respectIgnore ?? true,
+		failOnLimit: options.failOnLimit ?? false,
 		patterns: sets.map((set) =>
 			set.map((segment) =>
 				segment === GLOBSTAR
@@ -151,13 +163,25 @@ function directoryMatcher(plan: WalkPlan): (relative: string) => boolean {
 async function* executeWalk(
 	plan: WalkPlan,
 	signal?: AbortSignal,
+	onSummary?: (summary: SandboxWalkSummary) => void,
 ): AsyncGenerator<SandboxFileEntry> {
 	const fs = await import('node:fs/promises')
 	const path = await import('node:path')
 	const { EventEmitter } = await import('node:events')
-	const open: { dir: import('node:fs').Dir; relative: string; depth: number }[] = []
+	const open: {
+		dir: import('node:fs').Dir
+		relative: string
+		depth: number
+		/** Whether leaving this directory also drops its ignore layer. */
+		layered: boolean
+	}[] = []
 	let visited = 0
 	let emitted = 0
+	let ignoredDirectories = 0
+	let stopped: SandboxWalkSummary['stopped']
+	const ignore = plan.respectIgnore
+		? createIgnoreStack({ fs, path, extraFiles: globalIgnoreFiles() })
+		: undefined
 	const matchers = plan.expressions.map(({ source, flags }) => new RegExp(source, `${flags}s`))
 	const canDescend = directoryMatcher(plan)
 	const maxDepth = plan.maxDepth ?? Number.POSITIVE_INFINITY
@@ -204,9 +228,11 @@ async function* executeWalk(
 			dispose?.()
 		}
 	}
+	/** False once the safety valve trips; the walk then ends with what it has. */
 	const noteVisit = () => {
 		visited += 1
-		if (visited > plan.maxVisitedEntries) {
+		if (visited <= plan.maxVisitedEntries) return true
+		if (plan.failOnLimit) {
 			throw Object.assign(
 				new Error(
 					`File search stopped after examining ${plan.maxVisitedEntries} entries; narrow its root or pattern.`,
@@ -214,6 +240,8 @@ async function* executeWalk(
 				{ code: 'ERR_FILE_WALK_LIMIT' },
 			)
 		}
+		stopped = 'entry-limit'
+		return false
 	}
 	try {
 		check()
@@ -231,11 +259,14 @@ async function* executeWalk(
 		const rootInfo = await wait(fs.lstat(plan.root))
 		check()
 		if (rootInfo.isFile()) {
-			noteVisit()
+			if (!noteVisit()) return
 			if (matchers.some((matcher) => matcher.test(path.basename(plan.root))))
 				yield { path: plan.root, size: rootInfo.size }
 			return
 		}
+		// An explicit root is never itself ignored: only what is below it is tested.
+		await ignore?.init(plan.root)
+		await ignore?.enter(plan.root)
 		let start = plan.root
 		// Never follow a static-prefix symlink to speed up a pattern: traversal
 		// and its optimized starting point must have the same link policy.
@@ -249,22 +280,29 @@ async function* executeWalk(
 				if (missing(error)) return
 				throw error
 			}
-			noteVisit()
+			if (!noteVisit()) return
 			if (!info.isDirectory()) return
+			await ignore?.enter(start)
 		}
 		if (plan.prefix.length >= maxDepth) return
-		const openDirectory = async (absolute: string, relative: string, depth: number) => {
+		const openDirectory = async (
+			absolute: string,
+			relative: string,
+			depth: number,
+			layered: boolean,
+		) => {
 			check()
 			try {
 				const dir = await wait(fs.opendir(absolute), (late) => {
 					void close(late).catch(() => {})
 				})
-				open.push({ dir, relative, depth })
+				if (layered) await ignore?.enter(absolute)
+				open.push({ dir, relative, depth, layered })
 			} catch (error) {
 				if (!missing(error)) throw error
 			}
 		}
-		await openDirectory(start, plan.prefix.join('/'), plan.prefix.length)
+		await openDirectory(start, plan.prefix.join('/'), plan.prefix.length, false)
 		while (open.length > 0) {
 			check()
 			const frame = open[open.length - 1] as (typeof open)[number]
@@ -272,18 +310,26 @@ async function* executeWalk(
 			check()
 			if (!entry) {
 				open.pop()
+				if (frame.layered) ignore?.leave()
 				await close(frame.dir)
 				continue
 			}
-			noteVisit()
+			if (!noteVisit()) return
+			if (VCS_NAMES.has(entry.name)) continue
 			const relative = frame.relative ? `${frame.relative}/${entry.name}` : entry.name
 			const absolute = path.join(plan.root, relative)
 			const depth = frame.depth + 1
 			if (entry.isDirectory()) {
-				if (depth < maxDepth && canDescend(relative)) await openDirectory(absolute, relative, depth)
+				if (depth >= maxDepth || !canDescend(relative)) continue
+				if (ignore?.isIgnored(absolute, true)) {
+					ignoredDirectories += 1
+					continue
+				}
+				await openDirectory(absolute, relative, depth, true)
 				continue
 			}
 			if (!entry.isFile() || !matchers.some((matcher) => matcher.test(relative))) continue
+			if (ignore?.isIgnored(absolute, false)) continue
 			let info: import('node:fs').Stats
 			try {
 				info = await wait(fs.lstat(absolute))
@@ -303,16 +349,24 @@ async function* executeWalk(
 				void close(dir).catch(() => {})
 			} else await close(dir)
 		}
+		onSummary?.({ visited, ignoredDirectories, ...(stopped ? { stopped } : {}) })
 	}
 }
 
+/** Global exclude files, lowest precedence. Only the host has them. */
+function globalIgnoreFiles(): string[] {
+	const home = process.env.HOME ?? process.env.USERPROFILE
+	const base = process.env.XDG_CONFIG_HOME || (home ? join(home, '.config') : undefined)
+	return base ? [join(base, 'git', 'ignore')] : []
+}
+
 /** Internal host path; the caller first resolves its authorized filesystem root. */
 export async function* walkFilesLocally(
 	rootPath: string,
 	options: SandboxWalkFilesOptions,
 ): AsyncGenerator<SandboxFileEntry> {
 	options.signal?.throwIfAborted()
-	yield* executeWalk(planWalk(rootPath, options), options.signal)
+	yield* executeWalk(planWalk(rootPath, options), options.signal, options.onSummary)
 }
 
 /** The existing sandbox execution seam; no separate worker protocol is needed. */
@@ -346,6 +400,7 @@ export async function* walkFilesViaExec(
 	let terminal = false
 	let received = 0
 	let failure: unknown
+	const outcome: { summary?: SandboxWalkSummary } = {}
 	const reject = (error: unknown) => {
 		failure ??= error instanceof Error ? error : new Error(String(error))
 		controller.abort(error)
@@ -358,6 +413,13 @@ export async function* walkFilesViaExec(
 		const record = value as Record<string, unknown>
 		if (record.type === 'done') {
 			terminal = true
+			const count = (value: unknown) =>
+				typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : 0
+			outcome.summary = {
+				visited: count(record.visited),
+				ignoredDirectories: count(record.ignoredDirs),
+				...(record.stopped === 'entry-limit' ? { stopped: 'entry-limit' as const } : {}),
+			}
 			return
 		}
 		if (record.type === 'error' && typeof record.message === 'string') {
@@ -462,6 +524,7 @@ export async function* walkFilesViaExec(
 		}
 	} finally {
 		dispose?.()
+		if (outcome.summary) options.onSummary?.(outcome.summary)
 		if (!settled) controller.abort(new Error('File walk consumer stopped'))
 		await pending
 		// A rejected cancellation can mean remote work is still alive. Preserve

package/src/sandbox/ignore-matcher.ts

@@ -0,0 +1,46 @@
+import { IGNORE_SOURCE } from './ignore-source.js'
+
+/** One compiled ignore rule. */
+export interface IgnoreRule {
+	readonly negate: boolean
+	readonly dirOnly: boolean
+	readonly re: RegExp
+}
+
+/** Layered ignore rules for one depth-first walk; see `ignore-source.ts`. */
+export interface IgnoreStack {
+	/** Find the enclosing repository and load the layers above the walk root. */
+	init(root: string): Promise<void>
+	/** Load a directory's rule files; call before reading it. */
+	enter(directory: string): Promise<void>
+	/** Drop the layer of the directory most recently entered. */
+	leave(): void
+	isIgnored(absolute: string, isDirectory: boolean): boolean
+}
+
+export interface IgnoreDeps {
+	readonly fs: unknown
+	readonly path: unknown
+	/** Global exclude files, lowest precedence. The guest has none. */
+	readonly extraFiles?: readonly string[]
+}
+
+interface IgnoreModule {
+	parse(text: string): IgnoreRule[]
+	decide(rules: readonly IgnoreRule[], relative: string, isDirectory: boolean): 0 | 1 | 2
+	create(deps: IgnoreDeps): IgnoreStack
+	vcs: readonly string[]
+}
+
+// The same text is embedded in the guest program, so both walks share it.
+const module_ = new Function(
+	`${IGNORE_SOURCE}\nreturn { parse: ignParse, decide: ignDecide, create: ignCreate, vcs: IGN_VCS }`,
+)() as IgnoreModule
+
+/** Parse the text of one ignore file into rules; a line it cannot read is dropped. */
+export const parseIgnoreRules = module_.parse
+/** 0: no rule matches, 1: ignored, 2: re-included. The last matching rule wins. */
+export const decideIgnore = module_.decide
+export const createIgnoreStack = module_.create
+/** Version-control directories that no walk ever descends into. */
+export const VCS_NAMES: ReadonlySet<string> = new Set(module_.vcs)

package/src/sandbox/ignore-source.ts

@@ -0,0 +1,220 @@
+/**
+ * The ignore-file matcher, as plain JavaScript source text.
+ *
+ * One implementation serves two runtimes. The host walker evaluates this text
+ * once (see `ignore-matcher.ts`); the guest program (`file-walk-program.ts`)
+ * embeds the same text, because that program travels as a single `node -e`
+ * argument with stdin closed and cannot import a package. Keeping it as
+ * source text, not a serialised function, means a host bundler cannot rewrite
+ * it, and the two walks cannot drift apart.
+ *
+ * Rules follow the gitignore format: `#` comments, `\#` and `\!` escapes,
+ * unescaped trailing spaces dropped, `!` negation, a leading or inner `/`
+ * anchors a rule to the file that holds it, a trailing `/` matches
+ * directories only, and `*`, `?`, `[...]`, `**` as git defines them. A deeper
+ * file beats a shallower one, `.ignore` beats `.gitignore` in the same
+ * directory, and the last matching line of a file wins. A rule this matcher
+ * does not understand is dropped (an unclosed `[`, or more than three
+ * separate `*` in one rule, which could backtrack for seconds), so a visible
+ * file is never hidden by one.
+ *
+ * Nothing here is allowed to contain a backtick or a `${`: it lives inside a
+ * template literal. Every helper is prefixed `ign` so that, inlined into the
+ * guest program, it cannot collide with that program's own names.
+ */
+export const IGNORE_SOURCE = String.raw`
+const IGN_MAX_BYTES = 262144;
+const IGN_MAX_RULES = 10000;
+const IGN_MAX_PATTERN = 1024;
+const IGN_MAX_STARS = 3;
+const IGN_VCS = ['.git', '.svn', '.hg', '.bzr', '.jj', '.sl'];
+const IGN_POSIX_CLASSES = {
+  alpha: 'a-zA-Z', digit: '0-9', alnum: 'a-zA-Z0-9', upper: 'A-Z', lower: 'a-z',
+  space: ' \\t\\n\\r\\f\\v', punct: '!-\\/:-@\\[-\`{-~', xdigit: '0-9A-Fa-f',
+};
+function ignEscape(c) { return /[\\^$.*+?()[\]{}|\/-]/.test(c) ? '\\' + c : c; }
+function ignClass(body) {
+  let negate = false;
+  if (body[0] === '!' || body[0] === '^') { negate = true; body = body.slice(1); }
+  let out = '';
+  for (let i = 0; i < body.length; i++) {
+    const c = body[i];
+    if (c === '[' && body[i + 1] === ':') {
+      const end = body.indexOf(':]', i + 2);
+      const name = end < 0 ? '' : body.slice(i + 2, end);
+      if (IGN_POSIX_CLASSES[name]) { out += IGN_POSIX_CLASSES[name]; i = end + 1; continue; }
+    }
+    if (c === '\\') { i++; if (i < body.length) out += ignEscape(body[i]); continue; }
+    if (c === '-') { out += (out === '' || i === body.length - 1) ? '\\-' : '-'; continue; }
+    out += (c === '[' || c === ']' || c === '^') ? '\\' + c : c;
+  }
+  if (out === '') return null;
+  return '[' + (negate ? '^/' : '') + out + ']';
+}
+function ignTranslate(p) {
+  let out = '';
+  let i = 0;
+  let stars = 0;
+  while (i < p.length) {
+    const c = p[i];
+    if (c === '\\') {
+      if (i + 1 >= p.length) return null;
+      out += ignEscape(p[i + 1]); i += 2; continue;
+    }
+    if (c === '*') {
+      let j = i;
+      while (p[j] === '*') j++;
+      if (j - i >= 2 && (i === 0 || p[i - 1] === '/') && (j === p.length || p[j] === '/')) {
+        if (j === p.length) out += '.*';
+        else { out += '(?:.*/)?'; j++; }
+        i = j; continue;
+      }
+      stars++;
+      out += '[^/]*'; i = j; continue;
+    }
+    if (c === '?') { out += '[^/]'; i++; continue; }
+    if (c === '[') {
+      let j = i + 1;
+      if (p[j] === '!' || p[j] === '^') j++;
+      if (p[j] === ']') j++;
+      while (j < p.length && p[j] !== ']') { if (p[j] === '\\') j++; j++; }
+      if (j >= p.length) return null;
+      const cls = ignClass(p.slice(i + 1, j));
+      if (cls === null) return null;
+      out += cls; i = j + 1; continue;
+    }
+    out += ignEscape(c); i++;
+  }
+  // Each separate star can backtrack against the others: a rule with many of
+  // them takes time exponential in their number on one long name. Real rules
+  // use one or two; a rule past the cap is dropped, like any rule not understood.
+  if (stars > IGN_MAX_STARS) return null;
+  return out;
+}
+/** One line to one rule, or null when the line holds none. */
+function ignRule(raw) {
+  let line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+  while (line.endsWith(' ') && !line.endsWith('\\ ')) line = line.slice(0, -1);
+  if (line === '' || line[0] === '#' || line.length > IGN_MAX_PATTERN) return null;
+  let negate = false;
+  if (line[0] === '!') { negate = true; line = line.slice(1); }
+  let dirOnly = false;
+  while (line.length > 1 && line.endsWith('/')) { dirOnly = true; line = line.slice(0, -1); }
+  if (line === '/' || line === '') return null;
+  const anchored = line.indexOf('/') >= 0;
+  if (line[0] === '/') line = line.slice(1);
+  line = line.replace(/(\*\*\/)+/g, '**/');
+  if ((line.match(/\*\*/g) || []).length > 4) return null;
+  let body;
+  try { body = ignTranslate(line); } catch (error) { return null; }
+  if (body === null) return null;
+  try {
+    return { negate, dirOnly, re: new RegExp((anchored ? '^' : '^(?:.*/)?') + body + '$') };
+  } catch (error) { return null; }
+}
+function ignParse(text) {
+  if (text.charCodeAt(0) === 0xFEFF) text = text.slice(1);
+  if (text.length > IGN_MAX_BYTES) text = text.slice(0, text.lastIndexOf('\n', IGN_MAX_BYTES) + 1);
+  const rules = [];
+  for (const line of text.split('\n')) {
+    const rule = ignRule(line);
+    if (rule) rules.push(rule);
+    if (rules.length >= IGN_MAX_RULES) break;
+  }
+  return rules;
+}
+/** 0: no rule matches. 1: ignored. 2: re-included. The last matching rule wins. */
+function ignDecide(rules, relative, isDirectory) {
+  for (let i = rules.length - 1; i >= 0; i--) {
+    const rule = rules[i];
+    if (rule.dirOnly && !isDirectory) continue;
+    if (rule.re.test(relative)) return rule.negate ? 2 : 1;
+  }
+  return 0;
+}
+/**
+ * The layered rules for one walk. The caller enters a directory before it
+ * reads it and leaves it after, so the layers follow the depth-first stack.
+ * deps: fs (promises), path, extraFiles (global exclude files, host only).
+ */
+function ignCreate(deps) {
+  const fs = deps.fs;
+  const path = deps.path;
+  const layers = [];
+  const frames = [];
+  let ancestorsInRepo = false;
+  const posix = value => path.sep === '/' ? value : value.split(path.sep).join('/');
+  const lstat = async file => { try { return await fs.lstat(file); } catch (error) { return null; } };
+  const load = async file => {
+    const info = await lstat(file);
+    if (!info || !info.isFile() || info.size > IGN_MAX_BYTES * 4) return [];
+    try { return ignParse(await fs.readFile(file, 'utf8')); } catch (error) { return []; }
+  };
+  const loadDirectory = async (directory, inRepo) => {
+    const rules = [];
+    if (inRepo) rules.push(...await load(path.join(directory, '.gitignore')));
+    rules.push(...await load(path.join(directory, '.ignore')));
+    return rules;
+  };
+  const push = (directory, rules) => {
+    layers.push({ base: posix(directory).replace(/\/$/, ''), rules });
+  };
+  return {
+    /** Find the enclosing repository and load the layers above the root. */
+    async init(root) {
+      let directory = root;
+      let repo = null;
+      for (;;) {
+        const info = await lstat(path.join(directory, '.git'));
+        if (info) { repo = { directory, isDirectory: info.isDirectory() }; break; }
+        const parent = path.dirname(directory);
+        if (parent === directory) break;
+        directory = parent;
+      }
+      if (!repo || repo.directory === root) return;
+      ancestorsInRepo = true;
+      const chain = [];
+      for (let up = path.dirname(root); ; up = path.dirname(up)) {
+        chain.unshift(up);
+        if (up === repo.directory || path.dirname(up) === up) break;
+      }
+      for (const [index, directory] of chain.entries()) {
+        const rules = [];
+        if (index === 0) {
+          for (const file of deps.extraFiles || []) rules.push(...await load(file));
+          if (repo.isDirectory) rules.push(...await load(path.join(directory, '.git', 'info', 'exclude')));
+        }
+        rules.push(...await loadDirectory(directory, true));
+        push(directory, rules);
+      }
+    },
+    async enter(directory) {
+      const parentInRepo = frames.length ? frames[frames.length - 1] : ancestorsInRepo;
+      let inRepo = parentInRepo;
+      const rules = [];
+      if (!parentInRepo) {
+        const info = await lstat(path.join(directory, '.git'));
+        if (info) {
+          inRepo = true;
+          for (const file of deps.extraFiles || []) rules.push(...await load(file));
+          if (info.isDirectory()) rules.push(...await load(path.join(directory, '.git', 'info', 'exclude')));
+        }
+      }
+      rules.push(...await loadDirectory(directory, inRepo));
+      frames.push(inRepo);
+      push(directory, rules);
+    },
+    leave() { frames.pop(); layers.pop(); },
+    isIgnored(absolute, isDirectory) {
+      const target = posix(absolute);
+      for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        if (layer.rules.length === 0 || !target.startsWith(layer.base + '/')) continue;
+        const decision = ignDecide(layer.rules, target.slice(layer.base.length + 1), isDirectory);
+        if (decision) return decision === 1;
+      }
+      return false;
+    },
+  };
+}
+`

package/src/sandbox/provider/local.ts

@@ -14,6 +14,7 @@ import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join, parse, resolve } from 'node:path'
 import { NAMZU } from '../../constants/telemetry/index.js'
 import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { attributeSandboxFailure } from '../denial.js'
 
 import {
 	SANDBOX_DEFAULT_TIMEOUT_MS,
@@ -1084,8 +1085,16 @@ class LocalSandbox implements Sandbox {
 					terminate('SIGKILL')
 				}
 				const timedOut = cancellation === 'deadline'
+				const exitCode = code ?? (timedOut ? 124 : 1)
+				const attribution = attributeSandboxFailure({
+					environment: this.environment,
+					exitCode,
+					stderr: stderr.text,
+					timedOut,
+					allowedRoots: [...this.roots, tmpdir(), '/tmp', '/var/tmp', '/dev'],
+				})
 				resolvePromise({
-					exitCode: code ?? (timedOut ? 124 : 1),
+					exitCode,
 					stdout: stdout.text,
 					stderr: stderr.text,
 					signal: signal ?? undefined,
@@ -1096,6 +1105,7 @@ class LocalSandbox implements Sandbox {
 					// gone. The tool layer already renders the flag.
 					stdoutTruncated: stdout.truncated,
 					stderrTruncated: stderr.truncated,
+					...(attribution !== undefined ? { attribution } : {}),
 				})
 			})
 

package/src/scheduler/completion-inbox.ts

@@ -789,6 +789,7 @@ export function formatCompletionNotification(handles: readonly TaskHandle[]): st
 				: []),
 			...(handle.result?.stopReason ? [`stop_reason: ${handle.result.stopReason}`] : []),
 			...(durationMs !== undefined ? [`duration_ms: ${durationMs}`] : []),
+			...(handle.completedAt ? [`finished_at: ${new Date(handle.completedAt).toISOString()}`] : []),
 			'',
 			body,
 			// Outside the envelope, deliberately: this sentence is an

package/src/session/log-hash.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto'
 import {
+	IgnorableRecordSchema,
 	SESSION_RECORD_MAX_BYTES,
 	type SessionRecord,
 	SessionRecordSchema,
@@ -99,6 +100,18 @@ export function parseSessionLogLine(line: string | Uint8Array): ParsedSessionLog
 		)
 	}
 	const parsed = SessionRecordSchema.safeParse(value)
+	if (!parsed.success && isFlaggedIgnorable(value)) {
+		const ignorable = IgnorableRecordSchema.safeParse(value)
+		if (ignorable.success) {
+			// Typed as a record so the chain can carry it; its `type` is one no
+			// consumer matches, so it never moves a fold.
+			return {
+				record: ignorable.data as unknown as SessionRecord,
+				length: bytes.byteLength,
+				sha256: recordSha256(bytes),
+			}
+		}
+	}
 	if (!parsed.success) {
 		throw new SessionLogLineError(
 			'not-a-record',
@@ -113,3 +126,11 @@ export function parseSessionLogLine(line: string | Uint8Array): ParsedSessionLog
 		sha256: recordSha256(bytes),
 	}
 }
+
+function isFlaggedIgnorable(value: unknown): boolean {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		(value as { ignorable?: unknown }).ignorable === true
+	)
+}