What causes "SHMR requires a beam with conn or db" in can1357/oh-my-pi?

Ensure the beam object has a valid `conn` or `db` SQLite handle before calling SHMR functions

can1357/oh-my-pi · error · TypeError

SHMR requires a beam with conn or db

Error message

SHMR requires a beam with conn or db

What it means

SHMR helper dbOf extracts the SQLite database from a BeamLike object via `beam.conn ?? beam.db`; if the beam carries neither, a TypeError is thrown because every SHMR operation needs a database handle to run queries.

Source

Thrown at packages/mnemopi/src/core/shmr.ts:354

				belief.target_fact_id,
			]);
		const beliefId = createHash("sha256")
			.update(`${clusterId}:${belief.subject}:${belief.predicate}:${belief.object.slice(0, 50)}`)
			.digest("hex")
			.slice(0, 24);
		const provenance = JSON.stringify(
			cluster.map(item => item.fact_id).filter((id): id is string => typeof id === "string"),
		);
		db.run(
			`INSERT OR REPLACE INTO harmonic_beliefs (belief_id, subject, predicate, object, confidence, provenance, cluster_id, iteration, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
			[beliefId, belief.subject, belief.predicate, belief.object, confidence, provenance, clusterId, 0, now],
		);
	}
}

function dbOf(beam: BeamLike): Database {
	const db = beam.conn ?? beam.db;
	if (db === undefined) throw new TypeError("SHMR requires a beam with conn or db");
	return db;
}

function tableExists(db: Database, table: string): boolean {
	return db.query("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?").get(table) !== null;
}

function parseEmbeddingJson(raw: unknown): Vector | null {
	if (typeof raw !== "string") return null;
	try {
		const parsed = JSON.parse(raw) as unknown;
		if (!Array.isArray(parsed) || parsed.length === 0) return null;
		const out = new Float32Array(parsed.length);
		for (let i = 0; i < parsed.length; i++) {
			const value = Number(parsed[i]);
			if (!Number.isFinite(value)) return null;
			out[i] = value;
		}

View on GitHub (pinned to 9690622007)

Solutions

Ensure the beam object has a valid `conn` or `db` SQLite handle before calling SHMR functions
Fix the field name so it matches BeamLike (`conn` or `db`)
Attach the database when constructing the beam: `{ ...beam, db: database }`

Example fix

// before
const beam = { table: "memories" };
shmrQuery(beam); // TypeError
// after
const beam = { table: "memories", db: database };

Defensive patterns

Strategy: validation

Validate before calling

if (beam.conn === undefined && beam.db === undefined) {
  throw new Error("beam must carry a conn or db handle before SHMR use");
}
shmrQuery(beam);

Type guard

function hasBeamDb(beam: Partial<BeamLike>): beam is BeamLike {
  return beam.conn !== undefined || beam.db !== undefined;
}

Try / catch

try {
  shmrQuery(beam);
} catch (err) {
  if (err instanceof TypeError && err.message.includes("beam with conn or db")) {
    logger.error("SHMR beam missing database handle", { beamKeys: Object.keys(beam) });
  }
  throw err;
}

Prevention

Always attach conn or db when constructing beams
Validate beam shape at construction time, not at query time
Beware field renames that break the BeamLike contract

When it happens

Trigger: Passing a beam object constructed without conn or db fields (both undefined) into SHMR functions; a partial/configured-later beam object used before its DB handle was attached.

Common situations: Building beams programmatically and forgetting to attach the database; refactoring renamed the field (e.g. `database` instead of `db`); deserialized beams from storage that omit connection handles.

Related errors

AI-assisted analysis of can1357/oh-my-pi@9690622007 (2026-08-31). Data as JSON: /api/errors/49059fe9b9d1db67. Report an issue: GitHub.