TypeGraph | Blog

Look Before You Write

Tue, 22 Sep 2026 00:00:00 GMT

Suppose you tighten the schema on an account directory so that email has to be a real address, plan has to be one of three values, and seats has to be positive. TypeGraph validates on write, so everything written from then on is checked, but rows stored before the change are never looked at again, and you have no idea how many of them fail the new rules. You’d like a background agent (or yourself, in a REPL) to find and fix them while sales reps carry on editing the same accounts.

To do that safely the agent needs a cheap overview of what’s in the graph, a way to find the rows that don’t validate without reading everything back into memory, and a write that won’t clobber a change a person made after the agent read the row.

0.54 added store.describe(), store.validateStore(), and compareAndSet() for those three jobs, plus planCandidateWriteSet() for reviewing a whole batch before it lands, and 0.64 lets the first two run inside a transaction. It’s the same loop runtime schema evolution uses when an agent proposes changes to the schema itself: the agent looks at the current state, proposes a change, and the change only applies if nothing has moved since it looked.

The graph here is 240 accounts and 90 people created through the store, 60 memberOf edges, and three legacy Account rows inserted through the backend directly, the way a writer running the old rules would have stored them. The outputs below come from running this code against it on SQLite.

const Account = defineNode("Account", {
  schema: z.object({
    name: z.string().min(1),
    email: z.email(),
    plan: z.enum(["free", "team", "enterprise"]),
    seats: z.number().int().positive(),
    ownerId: z.string().optional(),
  }),
});

What’s in the graph

const { statistics } = await store.describe();
for (const kind of [...statistics.nodes, ...statistics.edges]) {
  console.log(`${kind.entity} ${kind.kind}: ${kind.count}`);
  for (const property of kind.properties) {
    console.log(
      `  ${property.path}  present=${property.presentCount}  coverage=${property.coverage.toFixed(2)}`,
    );
  }
}

node Account: 243
  /email  present=243  coverage=1.00
  /name  present=243  coverage=1.00
  /ownerId  present=60  coverage=0.25
  /plan  present=243  coverage=1.00
  /seats  present=243  coverage=1.00
node Person: 90
  /name  present=90  coverage=1.00
  /title  present=30  coverage=0.33
edge memberOf: 60
  /role  present=30  coverage=0.50

Every declared kind gets a row count, and every declared property gets a presence count and a coverage figure. /ownerId at 0.25 says 60 of 243 accounts have an owner, which is enough for an agent to decide where to spend its attention before it reads a single row.

The counting happens in the database, and on this graph describe() runs two statements, one for all node kinds and one for all edge kinds. The result also records the schema version and hash it was computed under, and TypeGraph checks that they didn’t change mid-way, so you never get statistics that straddle a schema change.

What no longer fits

let cursor: string | undefined;
do {
  const page = await store.validateStore({
    entity: "node",
    kind: "Account",
    pageSize: 100,
    ...(cursor === undefined ? {} : { cursor }),
  });
  console.log(
    `scanned ${page.scannedCount}, ${page.violations.length} violation(s)`,
  );
  for (const failure of page.violations) {
    console.log(failure.id, failure.path, failure.reason);
  }
  cursor = page.nextCursor;
} while (cursor !== undefined);

scanned 100, 0 violation(s)
scanned 100, 0 violation(s)
scanned 43, 3 violation(s)
acct_legacy_1 /email Invalid email address
acct_legacy_2 /plan Invalid option: expected one of "free"|"team"|"enterprise"
acct_legacy_2 /seats Too small: expected number to be >0

There are three violations across two records, because acct_legacy_2 breaks two rules. Each failure carries the record id, a JSON pointer to the property, the Zod issue code, and the reason. Each page is one bounded statement, and the cursor is tied to the schema it started under. If the schema changes mid-sweep, the next page throws StoreAnalysisCursorStaleError instead of quietly checking the rest against different rules.

The third legacy row, acct_legacy_3, isn’t reported. It carries a salesforceId the schema doesn’t declare, and undeclared properties count as healthy extra data, so you can sweep a graph whose shape is changing at runtime without every extra field showing up as a defect.

Fix a row without racing anyone

The obvious repair is to call getById(), decide what to change, and call update(), but a sales rep’s edit that lands between the read and the write gets overwritten. compareAndSet() closes that gap by checking the expected values and applying the update in one statement.

const applied = await store.nodes.Account.compareAndSet(id, {
  expected: { name: "Northwind", plan: "team", seats: 12 },
  patch: { email: "ops@northwind.example" },
});

applied=true  email=ops@northwind.example  version 1 -> 2

The interesting case is when someone else gets there first. Say the agent read acct_legacy_2 and planned a repair, but before it applied, a person fixed the row by hand and changed the email along the way. The agent’s guard names the email it read:

const applied = await store.nodes.Account.compareAndSet(id, {
  expected: { name: "Contoso", email: "it@contoso.example" },
  patch: { plan: "team", seats: 5 },
});

applied=false  seats=20  version 2 -> 2  updatedAt changed=false

false means nothing was written, so the person’s seats=20 stands and the version didn’t move. It’s an ordinary return value rather than an exception, and the agent should re-read the row and plan again.

To require that a property is missing, use the exported compareAndSetAbsent marker (undefined is too easy to lose while an object is being built or serialized). Here are two agents trying to claim the same unowned account:

const claim = (ownerId: string) =>
  store.nodes.Account.compareAndSet("acct_1", {
    expected: { ownerId: compareAndSetAbsent },
    patch: { ownerId },
  });

console.log(await claim("rep-9"), await claim("rep-4"));

true false

The first agent gets the account and the second finds out immediately, without a lock or a retry loop.

Expected values are checked against the property’s current schema, so you can’t guard on a value that’s already invalid, which is why the repair above guards on name, plan and seats rather than the bad email. The row also has to be valid as a whole after the patch, so patching only plan on acct_legacy_2 fails on seats before anything is written.

Review a batch before it lands

A guard works for one row, but a partner feed offering a batch of accounts is more of a review problem, where you want to see what would change before anything does. planCandidateWriteSet() takes a serializable batch of nodes and edges, stages it on a throwaway copy, and hands back an ordinary merge plan without ever writing to the target.

const plan = unwrap(
  await planCandidateWriteSet({
    target: store,
    makeBackend,
    options, // two Accounts with the same email are the same account
    writeSet: {
      formatVersion: 1,
      sourceId: "partner-feed",
      target: await captureCandidateWriteSetTarget(store),
      nodes: [partnerAccount7, partnerGlobex],
      edges: [],
    },
  }),
);

upserts: 2  accounts still 243
acct_7 name: keep "Account 7", feed says "Account 7 Holdings"
acct_7 plan: keep "team", feed says "enterprise"
acct_7 seats: keep 12, feed says 40

The plan has one new account and one match on acct_7, where the feed disagrees on three properties. The existing values win by default and the disagreements go on the review, so “enterprise, 40 seats” becomes a line item for a person to look at instead of a silent overwrite.

If something unrelated writes to the graph before you apply, applying the original plan fails:

StaleMergePlanError: The target revision changed after this merge plan was created; the plan was not applied.  accounts 243

Re-planning and applying takes the count to 244. The plan is tied to the target’s revision rather than only the rows it touches, so any write makes it stale, which is cheap to recover from for a bounded batch. When a person’s approval has to sit between planning and applying, durable review handles it.

One consistent snapshot

At the root store, each describe() statement and each validateStore() page is its own read. TypeGraph catches schema changes between those reads but not data changes, so when a sweep needs one consistent view, 0.64 puts both methods on the transaction context:

const summary = await store.transaction(
  async (tx) => {
    const { statistics } = await tx.describe();
    // ...page through tx.validateStore() exactly as above
  },
  { isolationLevel: "repeatable_read", accessMode: "read_only" },
);

{ accounts: 244, scanned: 244, violations: [] }

The violations are gone because both repairs landed earlier in the run. Use repeatable_read or serializable and consume every page inside the callback.

Limits

describe() covers directly addressable declared properties. It doesn’t guess through $ref, unions, arrays, or conditionals. validateStore() is the authority for those.
Both are current-state only. There’s no “what did the data look like last month” analysis.
A guard can only protect what it can name. You can’t guard on an invalid value, so if a person and an agent both repair the same bad field, a guard on its neighbors won’t tell them apart. The revision-fenced plan is the alternative there.
Planning copies the whole target, so its cost scales with the graph. It’s for bounded review workflows, not a hot path.

Upgrading

Writing this post turned up two bugs in 0.68.0 and earlier. planCandidateWriteSet() fails on a target that holds a row with undeclared properties, like acct_legacy_3 above (#733), and compareAndSet() throws a raw Zod error on a kind whose schema has an object-level .refine() (#734). Both are fixed in 0.68.1 (#735, #737), which the examples here assume.

BulkOperationHookContext["operation"] now includes "compareAndSet", so an exhaustive switch over it needs the new case. If you run mixed versions during a rollout, upgrade every process that writes schema versions to 0.54 before using graph-scoped annotations (also new in 0.54: metadata on the graph itself, carried through extensions and returned by describe()). Older writers drop fields they don’t recognize.

Try it

describe() and validateStore()
compareAndSet() and compareAndSetAbsent
planCandidateWriteSet()
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Merges That Wait

Mon, 21 Sep 2026 00:00:00 GMT

Graph Merge plans before it applies: you fork a working copy with branch(), stage changes on it, and planMerge() shows you the exact write set before anything touches the target. That works well as long as staging, planning and applying all happen in one run of one process.

The workflows that most want a review step don’t look like that. Say a nightly job proposes loyalty-point adjustments that a person approves the next morning, a deploy lands in between, and the thing feeding the branch is a queue that occasionally delivers the same message twice. An in-memory branch handle and a plan that goes stale as soon as anything is written can’t cope with any of that.

It took three releases to fix, and I think the result is one of the more unusual things TypeGraph can do. 0.56 made the review itself durable by storing it as graph data, 0.67 made the working copy durable so a branch can be closed in one process and reopened in another, and 0.68 made it safe to feed that branch from an at-least-once queue.

The review lives in the graph

A merge plan is tied to the target’s revision, so if the target changes after planning, applying the plan fails. That rule is what keeps a stale plan from clobbering newer data, but it gets in the way if you want the review (the proposal, the decision, who approved it) stored as graph data next to the record it concerns, because writing the review down is itself a write to the target, and by the time anyone approves the plan it’s stale.

0.56 resolves this by separating what was reviewed from the plan you eventually apply. planCandidateWriteSetReview() captures the candidate changes, the plan, the policy, and a baseline of the target as one immutable, content-digested artifact:

const review = unwrap(
  await planCandidateWriteSetReview({
    target: store,
    makeBackend,
    policy: {
      id: "manual-acceptance-v1",
      context: { requiredApprovals: 1, authorizedReviewers: ["reviewer:maya"] },
    },
    writeSet: {
      formatVersion: 1,
      sourceId: "catalog-review",
      target: await captureCandidateWriteSetTarget(store),
      nodes: [
        {
          kind: "Item",
          id: proposal.id,
          properties: { label: proposal.label, status: "accepted" },
        },
      ],
      edges: [],
    },
  }),
);

You store it as ordinary graph data, keyed by its own digest, along with the reviewer’s decision. Artifact, Decision and evidence here are ordinary kinds the example defines itself, so this needs no special schema support:

const artifact = await store.nodes.Artifact.create(
  { content: JSON.stringify(review) },
  { id: review.digest.value },
);
await store.edges.evidence.create(proposal, artifact, { note: "review" });

const decision = await store.nodes.Decision.create({
  approved: true,
  reviewDigest: review.digest.value,
  reviewer: "reviewer:maya",
});
await store.edges.evidence.create(decision, artifact, { note: "approval" });

Applying the original plan at this point fails:

const stale = await applyMergePlan(store, review.plan);
// stale.error is a StaleMergePlanError

Recording the review and the approval moved the target, so the plan is stale. This is the part I like: durable review doesn’t get an exemption from the staleness check, because if recording an approval could quietly un-stale a plan, the check would mean nothing.

Instead of reusing the plan, you call revalidateCandidateWriteSetReview(), which reads the stored artifact, re-plans the retained candidate against the current target, and tells you what it found:

`checked.status`	What it means
`compatible`	Nothing that matters moved. You get a fresh `plan` and the original `reviewDigest`.
`changed`	Policy, options, baseline entities, or plan fields differ from what was reviewed. Get a new review and approval.
`incompatible`	Graph id, schema identity, or revision origin don’t match. This approval can’t be used against this target at all.

In the example only the review and approval records were added, so the result is compatible. I was careful to keep compatible meaning only that nothing relevant moved; it says nothing about whether the caller is allowed to act, so the example checks both before spending the plan:

if (checked.status !== "compatible") {
  throw new Error("A new review and approval are required");
}
if (checked.reviewDigest.value !== approval.reviewDigest) {
  throw new Error("Approval does not identify the validated review");
}

const report = unwrap(await applyMergePlan(store, checked.plan));

Authenticating the stored decision and enforcing authorizedReviewers are still your job. TypeGraph tells you whether the plan is safe to apply and leaves the question of who may apply it to you.

A working copy that outlives its process

The branch itself was still tied to one process, because a branch() result holds its store and close handle in memory and disposing it deletes the fork. 0.67 adds branchDurable(), which forks a working copy that persists and hands back a small JSON descriptor you can put on a queue. Here’s the loyalty ledger’s nightly job:

const created = unwrap(await branchDurable(base, host));
const staged = created.branch.store;

await staged.nodes.Account.update(ada.id, { points: 160 });
await staged.nodes.Account.create({ name: "Grace", points: 40 });

// Releases this process's connection and writer lease. The working copy stays.
await created.branch.close();
await queue.put(JSON.stringify(created.descriptor));

The descriptor is the only thing that leaves the process:

{
  "kind": "sqlite-file-host",
  "version": 1,
  "graphId": "loyalty",
  "definitionHash": "ec9dd68d2fbf14e3",
  "branchId": "gluQHM58QmB1LFjZIJEdA",
  "base": "ec9dd68d2fbf14e3#s1\u0000revision:kHeqC6EE55ENVL3a_np2R:r1:0000000000000001:2026-09-20T19:16:21.492Z",
  "store": { "id": "35da40a3-1820-4b9f-b9b4-2117e653ded8" },
  "schemaAnchor": { "version": 1, "hash": "ec9dd68d2fbf14e3" }
}

TypeGraph doesn’t ship a durable host. It defines the contract (a DurableWorkingCopyStrategy with create, seal, reopen, abort and destroy), and your host decides where a working copy lives, whether that’s a directory, a database, or a provider’s branch API. The descriptor’s store field is the host’s opaque locator, and everything else in it belongs to TypeGraph. The examples here ran against a small file-backed SQLite host, across separate node processes.

The next day a different process reads the descriptor and reopens the branch, and what comes back is an ordinary GraphBranch, so everything after that is the merge API you already know:

const descriptor = JSON.parse(await queue.get());

const branch = unwrap(await reopenDurableBranch(graph, descriptor, host));
const plan = unwrap(await planMerge(base, [branch]));

const report = unwrap(
  await applyDurableMergePlan({
    target: base,
    branch,
    descriptor,
    strategy: host,
    plan,
  }),
);
await branch.close();
unwrap(await destroyDurableBranch(descriptor, host));

plan: 2 node upserts, 0 conflicts
merged: {"nodes":2,"edges":0,"identity":{"asserted":0,"retracted":0}}
base now: Grace=40, Ada=160
reopen after destroy refused: true

applyDurableMergePlan() applies the approved plan through the target Store transaction. The former optional host-native merge hook was retired because a database merge that commits internally can cross the transaction boundary that checked the target revision. A host may still use native database branches for its durable working copies.

A descriptor is a document your application stored and handed back later, so TypeGraph treats it as untrusted input. At fork time the host seals the true origin, and every reopen and destroy is checked against it, so relabeling the branch id makes the reopen fail:

Durable branch descriptor does not match the working copy the host attested for
its store locator: the descriptor's TypeGraph fences disagree with the origin
recorded at fork. This is a tampered, relabeled, or wrong-branch descriptor.

The same check stops you from destroying branch B with branch A’s descriptor, or reopening with a graph that reuses the id "loyalty" but defines Account differently.

The message that arrives twice

Suppose the branch is fed from a queue where “award Ada 25 points” can arrive twice. The award has to apply exactly once, and whoever is downstream (a notification, an audit log) has to hear about every applied award eventually, even if the worker dies right after committing.

What that calls for is a transactional outbox scoped to the working copy, and 0.68 builds one into the durable-branch contract. You hand operateDurableBranch() an idempotency key, a mutation describing the change, and metadata to keep as evidence:

const outcome = unwrap(
  await operateDurableBranch(descriptor, host, {
    idempotencyKey: "award-7731",
    metadata: { source: "orders-queue", messageId: 7731 },
    mutation: { op: "award", account: adaId, points: 25 },
  }),
);

TypeGraph never interprets mutation; it digests it together with metadata, hands the host the request, and validates what comes back. The host applies the change and writes an evidence row in one database transaction, which in this host is a single SQLite transaction on one connection. To check the rollback, I made it throw after the graph write and before the evidence insert:

DurableOperationError | GRAPH_MERGE_OPERATION | Durable operation failed: injected failure after the graph write
evidence: undefined
accounts: Grace=40, Ada=160

There’s no evidence row, and Ada is still at the staged 160.

In the real run, the worker commits the award (Ada goes from 160 to 185) and then dies before telling anyone. A fresh process picks up the descriptor, and the queue redelivers the same message:

recover pid 76873 | Ada on branch: 185
redelivered: replayed | Ada on branch: 185

replayed returns the evidence from the first run and applies nothing, so Ada stays at 185 instead of 210. If you reuse the key with a different payload, even just different metadata, the host rejects it without writing:

changed payload: DurableOperationConflictError | GRAPH_MERGE_OPERATION_CONFLICT
Ada on branch: 185

The evidence rows act as the outbox. Each one starts with delivered: false, and you can’t destroy the branch while any are undelivered:

destroy: DurableEvidenceUndeliveredError | GRAPH_MERGE_OPERATION_UNDELIVERED |
  refusing to destroy "60367e1c-…": undelivered operation evidence remains

To deliver them, you scan for undelivered rows and mark each one after publishing it:

const page = unwrap(
  await scanDurableOperations(descriptor, host, { limit: 100 }),
);
for (const evidence of page.operations) {
  if (evidence.delivered) continue;
  await publishDownstream(evidence); // your outbox consumer
  unwrap(
    await markDurableOperationDelivered(
      descriptor,
      host,
      evidence.idempotencyKey,
    ),
  );
}
unwrap(await destroyDurableBranch(descriptor, host));

A crash at any point in that sequence means, at worst, that a downstream consumer hears about an award twice; the award itself is never applied twice or silently dropped.

Limits

There’s no first-party host and no queue. Whether your host’s transaction is atomic is up to your database. TypeGraph validates what the host reports back but can’t check your storage.
Exclusion is the host’s job. The example host’s writer lease is a lock file. When I left one behind, as a killed process would, reopening failed until it was cleared. A real host wants a lease that expires.
Plan against a quiet branch. Feeding operations into a branch while a reviewer plans against it means planning against a moving target.
Delivery is at-least-once. Make downstream writes idempotent on the key.
You probably don’t need this for a one-shot job. If you stage, plan and apply in one run, branch() is unchanged and simpler.

Try it

Durable candidate review
Durable host-native branches and atomic operations and evidence
Example 27: the durable review, end to end
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Schema Changes That Roll Back With Everything Else

Sat, 19 Sep 2026 00:00:00 GMT

Runtime Schema Evolution ended with an agent adding a kind for retraction notices to a live graph. This post uses a cut-down version of that: a Retraction kind added to a graph of publications.

store.evolve() commits a change like that in a transaction of its own and hands back a new Store. That’s fine when the schema change is the whole job, but not when your service keeps its own bookkeeping next to the graph, say a schema_audit table recording which schema version each import ran under.

If you do it in the obvious order, evolve() commits first, then a second transaction writes the retraction row and the audit row. When something downstream throws in that second transaction, this is what’s left:

evolve(), then a failed import:
  active schema version  2
  schema_audit rows      0
  Retraction node rows   0

The schema is at version 2 but nothing else moved, so there’s a Retraction kind that no ledger entry mentions and no row uses. Nothing is corrupt, but your bookkeeping and the database now disagree about which schema exists, because the schema change was the one step that couldn’t join the transaction. As of 0.62 it can join, and the rest of this post shows how.

Plan outside, apply inside

The setup is a graph with one kind, the extension the agent proposed, and a Drizzle table for the audit ledger in the same database.

const Publication = defineNode("Publication", {
  schema: z.object({ doi: z.string(), title: z.string() }),
});

const graph = defineGraph({
  id: "trials",
  nodes: { Publication: { type: Publication } },
  edges: {},
});

const retractions = defineGraphExtension({
  nodes: {
    Retraction: {
      properties: {
        doi: { type: "string", minLength: 1 },
        reason: { type: "string" },
      },
    },
  },
});

const schemaAudit = sqliteTable("schema_audit", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  schemaVersion: integer("schema_version").notNull(),
  recordedAt: text("recorded_at"),
});

The change is split into planning and applying. planEvolution() runs before any transaction opens, validates the extension against the active schema without writing anything, and returns an immutable plan that names the schema it starts from and the one it produces:

const plan = await store.planEvolution(retractions);

{
  "status": "change",
  "graphId": "trials",
  "baseline": { "version": 1, "hash": "89654f9e5c1debfb" },
  "result": { "version": 2, "hash": "aec6b8d50bf21bf8" },
  "requirements": [
    { "kind": "new-kind", "entity": "node", "kindName": "Retraction" }
  ]
}

Doing the planning outside means the slow, fallible part (validation, diffing) never holds a lock. For ordinary additions like a new kind or an optional scalar field, applying the plan needs no entity scans and no DDL.

Applying takes your transaction. better-sqlite3 is synchronous, so Drizzle’s db.transaction() can’t take an async callback, and a small helper drives BEGIN/COMMIT/ROLLBACK on the one connection. With node-postgres or libSQL you’d pass the nativeTx from db.transaction(async (nativeTx) => …) instead; the cross-store transactions recipe covers both.

async function inTransaction<T>(
  db: BetterSQLite3Database,
  run: () => Promise<T>,
): Promise<T> {
  db.run(sql`BEGIN`);
  try {
    const result = await run();
    db.run(sql`COMMIT`);
    return result;
  } catch (error) {
    db.run(sql`ROLLBACK`);
    throw error;
  }
}

const outcome = await inTransaction(db, async () => {
  const applied = await store.withEvolvedTransaction(db, plan, async (tx) => {
    const notices = tx.getNodeCollection("Retraction");
    if (notices === undefined) throw new Error("Retraction kind missing");
    await notices.create({ doi: "10.1/a", reason: "fabricated" });
  });

  db.insert(schemaAudit)
    .values({
      schemaVersion: applied.receipt.schema.version,
      recordedAt: String(applied.receipt.recorded),
    })
    .run();
  return applied;
});

const current = await store.refreshSchema({
  minVersion: outcome.receipt.schema.version,
});

Inside the callback, tx already sees the new schema: Retraction is writable even though the committed schema doesn’t have it yet. The receipt carries the exact schema version and hash the transaction produced (and, on a history-enabled store, the recorded-time anchor), so the audit row stores what the import actually ran under instead of what the code assumed. Treat the receipt as provisional until your outer COMMIT succeeds; after that, refreshSchema() hands the new schema to the Store you keep around.

To check the rollback, I threw an error after the ledger insert and ran the same plan twice, once failing and once clean:

attempt 1 (fails after the callback):
  receipt: schema v2, recorded r1:0000000000000002:2026-09-20T19:12:56.201Z
after rollback:
  active schema version  1
  schema_audit rows      0
  Retraction node rows   0
attempt 2 (same plan):
  receipt: schema v2, recorded r1:0000000000000002:2026-09-20T19:12:56.202Z
after commit:
  active schema version  2
  schema_audit rows      1
  Retraction node rows   1

The failed attempt got as far as a receipt and a ledger row visible inside the transaction, and none of it survived; when I checked the recorded-history table directly it had no Retraction rows either. The retry reused the same plan, got the same recorded revision, and committed, so the schema, the rows, the history, and your own table commit or roll back together.

If another writer evolves the graph between planning and applying, the apply throws StaleVersionError and the transaction is yours to roll back and replan.

No-ops, and schema-only checkpoints

A pipeline that runs the same wiring on every deploy will mostly produce no-op plans. Plan an extension the Store already has and you get status: "noop", which doesn’t need the exclusive schema lock, so an ordinary withRecordedTransaction() is enough:

const again = await current.planEvolution(retractions);
if (again.status === "noop") {
  await inTransaction(db, () =>
    current.withRecordedTransaction(db, async (tx) => {
      const notices = tx.getNodeCollection("Retraction");
      if (notices === undefined) throw new Error("Retraction kind missing");
      await notices.create({ doi: "10.1/b", reason: "duplicate publication" });
    }),
  );
}

The opposite case is a schema change that is itself the event worth recording. On a history-enabled store, tx.requestRecordedRevision() puts the change on the recorded timeline even when no entities change: the receipt reports zero writes, schema version 2, and a recorded anchor.

Merges and reviewed writes that bring their own kinds

0.61 added applyMergePlanInTransaction() for applying an approved merge plan next to your own SQL. But a merge plan is built against a specific schema, so a merge that introduces a kind the target doesn’t have yet couldn’t share a commit with the evolution that adds it. 0.62 closes that gap: branchForEvolution() forks a branch that already has the planned kinds, and planMergeForEvolution() plans against the resulting schema.

const evolutionPlan = await target.planEvolution(retractions);
const futureBranch = unwrap(
  await branchForEvolution(target, evolutionPlan, makeIsolatedBackend),
);
try {
  await futureBranch.store
    .getNodeCollectionOrThrow("Retraction")
    .create({ doi: "10.1/a", reason: "fabricated" });

  const mergePlan = unwrap(
    await planMergeForEvolution(target, evolutionPlan, [futureBranch]),
  );

  await inTransaction(db, () =>
    target.withEvolvedTransaction(db, evolutionPlan, (tx) =>
      applyMergePlanInTransaction(target, tx, mergePlan),
    ),
  );
} finally {
  await futureBranch.close();
}

A plan built the ordinary way, against the old schema, is rejected inside the evolved transaction with MergePlanSchemaMismatchError before anything is written.

0.65 does the same for candidate write sets, the branch-free way to propose changes as a JSON document a reviewer can read. planCandidateWriteSetForEvolution() plans the agent’s proposed Retraction records against the schema the pending evolution will produce, and nothing is written until the reviewed plan is applied inside withEvolvedTransaction().

Because review takes time and the target can move in the meantime, there are two different stale outcomes. If a write lands while the plan is being built, planning returns a MergePlanningStaleError, and you recapture the target and replan. If the target changes after you already hold a finished plan, applying throws StaleMergePlanError inside the outer transaction, and the schema change rolls back with it. I injected a write after planning to check this, and the active schema was still at version 1 afterwards.

Limits

Plans stay in one process. A plan is an in-memory token that can’t be serialized or reconstructed, so plan and apply in the same process.
The default adapter only does DML. A plan that needs new storage (a vector slot, identity work) is rejected before the callback runs, unless you use a privileged adapter configured with schemaProvisioning: "transactional". Indexes stay outside too: call materializeIndexes() after commit.
Only your database’s writes are atomic. The ledger row is atomic with the schema change because they share a connection. A message you publish to a queue from inside the callback is not.
Driver support varies. SQLite adoption needs a native connection with an observable transaction state (better-sqlite3 has one); HTTP-only drivers can’t adopt schema transactions at all.

Custom StoreEvolution implementations need planEvolution() and refreshSchema(), and custom adapters must now declare schemaProvisioning explicitly.

Try it

Plan outside and apply inside a caller-owned transaction
Merge after schema evolution in one caller transaction and candidate write sets for a planned schema
Adopted schema transactions: per-driver requirements
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Replacing the N+1 Loop With One Statement

Fri, 18 Sep 2026 00:00:00 GMT

Most apps have a page like this one: a workspace lists its published documents, and each row shows the title, how many versions the document has, the note on the newest version, and the three most recent comments. Every piece of that is a one-hop read from the document, so the first version anyone writes is a loop:

const documents = await store
  .query()
  .from("Document", "document")
  .whereNode("document", (document) => document.status.eq("published"))
  .orderBy("document", "title")
  .select((ctx) => ctx.document)
  .execute();

const rows = await Promise.all(
  documents.map(async (document) => {
    const versionEdges = await store.edges.hasVersion.findFrom(document);
    const versions = await store.nodes.Version.getByIds(
      versionEdges.map((edge) => edge.toId),
    );
    const commentEdges = await store.edges.hasComment.findFrom(document);
    const comments = await store.nodes.Comment.getByIds(
      commentEdges.map((edge) => edge.toId),
    );
    // Sort in JavaScript: newest version, version count, three latest comments.
    return summarize(document, versions, comments);
  }),
);

Counted at the driver, that loop issues 33 statements for eight documents, one for the list and four per document. On in-memory SQLite you’d never notice, but with the database across a network every one of those is a round trip, the count grows with the length of the list, and you’re loading every comment to keep three and every version to keep one.

This is the N+1, the oldest performance bug in the book, and over releases 0.58 to 0.65 I went after it properly. The same page now costs one SQL statement, and when TypeGraph can’t do a batch in one statement it throws before running anything instead of quietly issuing more.

(Every number here is a statement count, measured by wrapping better-sqlite3’s Statement and exec in the script that ran the code. None of them are wall-clock times. What a round trip costs on your network is yours to multiply in.)

Step one: reads that say what they want

store.neighbors() joins each edge to the node on its far end in a single statement, and applies ordering and the limit before hydrating anything, so “the newest version” fetches one row. store.countNeighbors() is the matching count and hydrates nothing at all.

const [latest] = await store.neighbors(document, {
  edges: ["hasVersion"],
  orderBy: { by: "node", field: "sequence", direction: "desc" },
  limit: 1,
});
const versions = await store.countNeighbors(document, {
  edges: ["hasVersion"],
});

Two calls per document is 16 statements for the page, which is better than 33 but still grows with the length of the list.

Step two: `batchOnce()`

store.batchOnce() is the part I’m happiest with. It takes any number of independent reads and runs them as exactly one SQL statement: each read becomes a CTE, and a single JSON envelope carries every result set back, in input order. The callback can return a runtime-sized array, which means the loop above translates almost literally:

const results = await store.batchOnce((read) =>
  documents.flatMap((document) => [
    read.neighbors(document, {
      edges: ["hasVersion"],
      orderBy: { by: "node", field: "sequence", direction: "desc" },
      limit: 1,
    }),
    read.countNeighbors(document, { edges: ["hasVersion"] }),
  ]),
);
// results[2 * i] is document i's newest version, results[2 * i + 1] its count.

That takes the page from sixteen statements to one. Inside a transaction, tx.batchOnce() binds to the open connection, so the batch sees writes made earlier in the same callback and is still one statement.

It won’t quietly fall back

A lot of “batch” APIs are really a for loop, and you only find out they issued N queries when a latency graph shows it a month later. batchOnce() has no fallback path, so if it can’t do the job in one statement it throws before executing anything:

await store.batchOnce((read) =>
  Array.from({ length: 501 }, () =>
    read.countNeighbors(document, { edges: ["hasVersion"] }),
  ),
);
// ConfigurationError: store.batchOnce() accepts at most 500 reads in one statement.

Five hundred reads run as one statement, and 501 throws without issuing any. It won’t chunk to fit the backend’s bind-parameter limit either, and reads that can’t be embedded (edge-collection batchFind* calls, for example) are rejected instead of being run on the side. Since the name promises one statement, I’d rather it fail loudly than break that promise.

The older store.batch(), by contrast, runs its queries one after another. It always did, and the docs now say so plainly because people were putting it in hot paths expecting a single round trip.

Step three: shape it in SQL

A batch of neighbors() calls still has one read per parent, so eight documents means sixteen reads inside the statement, and the 500-read ceiling works out to 250 documents. When the question is “for every document in this result”, a relation answers it with a fixed number of reads however long the list is. 0.61 added project(), derived relations, and aggregates; 0.63 added topPerPartition():

const published = () =>
  store
    .query()
    .from("Document", "document")
    .whereNode("document", (document) => document.status.eq("published"));

const versions = published()
  .traverse("hasVersion", "link")
  .to("Version", "version")
  .project((fields) => ({
    documentId: fields.document.id,
    versionId: fields.version.id,
    sequence: fields.version.sequence,
    note: fields.version.note,
  }))
  .asRelation();

const versionCounts = versions
  .groupBy((columns) => [columns.documentId])
  .aggregate((columns) => ({
    documentId: columns.documentId,
    versions: expr.count(columns.versionId),
  }));

const latestVersions = versions.topPerPartition({
  partitionBy: (columns) => [columns.documentId],
  orderBy: (columns) => [
    { expression: columns.sequence, direction: "desc" },
    { expression: columns.versionId },
  ],
  limit: 1,
});

topPerPartition() uses ROW_NUMBER(), so ties don’t widen the limit. Both orderings end in an id because the API can’t know your ordering is unique, and a repeatable winner needs a tiebreaker. The comments are the same shape with a limit of three, plus an ordered collection that folds the winners into one array per document:

const recentComments = published()
  .traverse("hasComment", "link")
  .to("Comment", "comment")
  .project((fields) => ({
    documentId: fields.document.id,
    commentId: fields.comment.id,
    body: fields.comment.body,
    postedAt: fields.comment.postedAt,
  }))
  .asRelation()
  .topPerPartition({
    partitionBy: (columns) => [columns.documentId],
    orderBy: (columns) => [
      { expression: columns.postedAt, direction: "desc", nulls: "last" },
      { expression: columns.commentId },
    ],
    limit: 3,
  })
  .groupBy((columns) => [columns.documentId])
  .aggregate((columns) => ({
    documentId: columns.documentId,
    recent: expr.collect(columns.body, {
      orderBy: [
        { expression: columns.postedAt, direction: "desc", nulls: "last" },
        { expression: columns.commentId },
      ],
    }),
  }));

Relations are batch members like any other read, so the whole page, titles included, is one statement:

const titles = published()
  .orderBy("document", "title")
  .select((ctx) => ({ id: ctx.document.id, title: ctx.document.title }));

const [documents, counts, latest, comments] = await store.batchOnce(
  () => [titles, versionCounts, latestVersions, recentComments] as const,
);

Joined on documentId, a row comes out as:

{ id: "1BMs3-6PEJYXtjB9BcrsU", versionCount: 3, latest: "v3 of doc 2",
  recent: ["comment 5 on doc 2", "comment 4 on doc 2", "comment 3 on doc 2"] }

The script asserts that these eight rows are identical to what the loop produced. Here’s how the versions of the page compare:

Page for eight documents	Statements
Loop of `findFrom()` and `getByIds()`	33
Loop of `neighbors()` and `countNeighbors()`	16
`batchOnce()` of the `neighbors()` reads	1
`batchOnce()` of four relations	1

neighbors() fits when you already hold a handful of sources, and relations fit when you want “every parent in this result”. topPerPartition() needs window functions and ordered expr.collect() needs ordered aggregates; a backend without them throws a typed error before executing.

The rest of the set-shaped toolkit

A few smaller pieces from the same stretch, all aimed at the same habit of doing one thing per row:

bulkFindFrom() / bulkFindTo() are findFrom() / findTo() for a whole page of endpoints. Index i of the result holds the edges of input i, an endpoint with no edges gets an empty array, and limitPerInput caps each endpoint’s fan-out. Fifty people’s jobs cost one statement per endpoint kind (split only when the bind-parameter budget requires it) instead of fifty.
```
const people = await store.nodes.Person.find({ limit: 50 });
const jobsPerPerson = await store.edges.worksAt.bulkFindFrom(people);
```
store.bulkFindEdgesTo() does the inbound direction across several node and edge kinds at once. Twelve documents and two edge kinds was one statement; calling findTo() per kind per document was 24.

updateWhere() is a set-based, transactional update that returns how many rows changed. The selector is mandatory (where, exists, a candidate query, or an explicit all: true), so you can’t wipe out a whole kind by forgetting a filter:

const result = await store.nodes.Person.updateWhere({
  patch: { active: false },
  where: (person) => person.lastSeen.lt(cutoff),
  exists: [
    {
      edgeKind: "worksAt",
      direction: "out",
      relatedKind: "Company",
      whereRelated: (company) =>
        company.field("status").string().eq("closed"),
    },
  ],
});
// { affectedCount: number }

in() / notIn() take list parameters, so field.in(param("ids")) binds a runtime-sized list in a prepared query instead of forcing you to rebuild the query per call.
Subgraphs got per-edge-kind windows (keep only the newest N edges of a noisy kind), and subgraph() works inside batchOnce(). Five roots awaited in a loop cost 10 statements on SQLite; batched, one.
Mixed-kind cursor pages: a query can start from several kinds (.from(["Person", "Team"], "entity")), and a .page() can sit in a batch next to unrelated reads, so a directory of people and teams can be read as one ordered stream at one statement per page.
executeChecked(version) folds the “has another isolate changed the schema?” probe into the read itself, for serverless deployments that cache the schema per isolate. Probing and then reading took 2 statements, and the checked read takes 1. A moved schema throws SchemaChangedError, even when the query would have matched no rows.

What one statement doesn’t buy you

It saves round trips, but the database does the same work. Every member of a batch still runs its own plan. For one large closure on Postgres, the direct subgraph() can beat the batched form, and topPerPartition() bounds the rows returned, not necessarily the rows scanned.
Results are materialized. batchOnce() returns JSON envelopes, doesn’t stream, and has no byte cap. Bound your reads with limits and projections.
The counts are SQLite driver counts. They show the shape of the improvement, and your actual latency depends on your network.

Try it

store.batchOnce(): the full contract, including what can and can’t be embedded
Top-N per parent and Ordered collections
updateWhere() and bulkFindEdgesTo()
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Tracking Which Records Are the Same Person

Sat, 12 Sep 2026 00:00:00 GMT

Say a bank’s KYC onboarding writes a Person node for each customer, keyed by the bank’s customer id, and its fraud pipeline writes a CaseSubject for everyone named in an investigation. When the person under investigation is a walk-in customer, the case system reuses the bank’s id, so one human being ends up as two nodes of different kinds, and nothing in the graph says they’re the same person.

Most graph libraries handle “these are the same thing” at the type level, and TypeGraph used to as well. The sameAs and differentFrom ontology factories related kinds rather than rows, and differentFrom never checked anything about actual data, which is of no use when a compliance team needs to say that this particular customer is that particular case subject. Both factories are deprecated now.

Their replacement, store.identity, is one of my favorite things in the library. It’s a ledger of claims about individual nodes, either that two of them are the same entity or that they’re provably not. You can query it at any point in time and retract a claim without deleting it, the claims carry through traversals and merges, and the database itself won’t commit a set of claims that contradicts itself.

Folding on a shared id

Identity is opt-in per graph. Turning it on also decides what happens when nodes of different kinds share an id:

const graph = defineGraph({
  id: "compliance",
  nodes: {
    Person: { type: Person },
    CaseSubject: { type: CaseSubject },
    Organization: { type: Organization },
  },
  edges: {},
  ontology: [disjointWith(Person, Organization)],
  identity: { sameIdAcrossKinds: "fold" },
});

With "fold", live nodes of different kinds that share an id are the same entity automatically. ("ignore" gives you the ledger without that implicit join, for graphs where a shared id is a coincidence.) The two systems above never have to coordinate:

const person = await store.nodes.Person.create(
  { name: "Alex Rivera" },
  { id: "cust-8842" },
);
const subject = await store.nodes.CaseSubject.create(
  { note: "Named in fraud case FC-2201" },
  { id: "cust-8842" },
);

await store.identity.membersOf(person);
// [{ kind: "CaseSubject", id: "cust-8842" },
//  { kind: "Person", id: "cust-8842" }]

A fold starts when the node actually exists, not at its validFrom. A node created today with a backdated validity window shows up in historical reads, but it doesn’t retroactively fold anything in the past.

Saying it explicitly

Most matches don’t come with a shared id. Here an investigator links a walk-in customer to an actor in an unrelated case, under two ids that have nothing in common:

const walkIn = await store.nodes.Person.create(
  { name: "J. Alvarez" },
  { id: "person-119" },
);
const caseActor = await store.nodes.CaseSubject.create(
  { note: "Signed the wire authorization in case FC-2214" },
  { id: "case-77" },
);

const linked = await store.identity.assertSame(walkIn, caseActor);
// { action: "created", assertion: { id, relation: "same", a, b, validFrom } }

await store.identity.assertSame(walkIn, caseActor);
// { action: "existing", assertion: <same assertion> } — idempotent

Asserting the same thing twice gives you the existing assertion back, so a job that re-runs after a crash doesn’t need to know whether it got that far last time. There are bulk forms (bulkAssertSame, bulkAssertDifferent) that return one result per input pair, in order.

Claims are also checked against the ontology before anything is stored. Since Person is disjointWith Organization, folding the walk-in onto a company fails:

await store.identity.assertSame(walkIn, acmeFreight);
// throws IdentityContradictionError
// details: { operation: "assertSame", reason: "disjoint-kinds", a, b }

Claims can also be bounded in time. A merged account that was later split, or a case subject that was only correct for the window an investigation covered, gets a half-open validity window:

await store.identity.assertSame(alice, legacyAlice, {
  validFrom: "2020-01-01T00:00:00.000Z",
  validTo: "2022-01-01T00:00:00.000Z",
});

Both endpoints have to exist for the whole window, and contradictions are checked across every overlapping stretch of time, including through chains of same claims.

Changing your mind

Suppose forensic review later shows that person-119 and case-77 are two different people who happened to share a wire-authorization signature. You want to record that, but the ledger currently says they’re the same entity, and it won’t hold both claims at once:

await store.identity.assertDifferent(walkIn, caseActor);
// throws IdentityContradictionError
// details: { operation: "assertDifferent", reason: "same-class", a, b }

You retract the old claim first, explicitly:

const ended = await store.identity.retractAssertion(linked.assertion.id);
// ended.validTo: "2026-08-21T18:03:11.442Z" — the fold ends, timestamped

await store.identity.assertDifferent(walkIn, caseActor);
// { action: "created", ... } — now recorded as provably different

await store.identity.areSame(walkIn, caseActor); // false
await store.identity.areDifferent(walkIn, caseActor); // true

Nothing was deleted: the retracted assertion and its validTo are still readable, and a query at a time before the retraction still sees one entity, so if an auditor asks why these two records were treated as one customer in August, you can answer them.

Soft-deleting a node ends its current assertions too, and records the node as the reason (endedBy), so a later reader can tell why a claim ended.

A backstop in the database

Everything so far is application code deciding whether a write is allowed, and application code can be wrong. assertSame checks against state it just read, so a bug somewhere else that writes identity rows directly could still commit the contradiction the API rejects.

So identity also keeps a table of which identity classes are held apart by a different claim, with a database CHECK constraint on it. When a transaction merges two classes, it rewrites those rows in the same batch. If two classes that are supposed to be separate get merged anyway, the rewrite violates the constraint and the database aborts the transaction:

// IdentitySeparationViolationError
// details: { graphId, enforcedBy: "database", classKey,
//            assertionId, a, b }

The API catches contradictions first and gives you a useful error, and the constraint is there for the case where the API has a bug.

Traversals that understand it

Queries can expand through identity classes, per hop, and it’s off by default:

const results = await store
  .query()
  .from("Person", "person")
  .traverse("authored", "edge", { includeIdentityMembers: true })
  .to("Document", "document")
  .select((ctx) => ({ edge: ctx.edge, document: ctx.document }))
  .execute();

That hop follows authored edges from the person and from every other node in their identity class, and returns the real edge and target rows with duplicates removed.

At the current time, each hop looks classes up through an index on the maintained closure, so the cost tracks the rows you start from and the size of their classes, not how many classes the graph holds. Measured on SQLite, with each Person folded to a Company and an Alias sharing its id, before and after the closure became index-seekable:

source rows	fan-out	matching edges	before	after
250	1	250	67 ms	6 ms
1000	1	1000	1077 ms	9 ms
2000	1	2000	4616 ms	19 ms
1000	8	8000	8611 ms	13 ms
500	200	100,000	51,602 ms	77 ms

That closure only describes the present, which is worth planning around. A hop at a historical time has to rebuild classes from the assertion ledger for the whole graph, once per statement, even if you only asked about one node, so queries about the present are much cheaper than queries about the past.

Identity claims also carry through interchange and graph merge. Exports carry assertions (current ones by default, ended ones too if you ask for an archival export), and graph merge treats identity as part of what it diffs. Two branches that make opposing claims about the same pair, or that contradict each other through a chain of same claims neither wrote alone, fail at plan time with IdentityMergeConflictError, and the merge checks again inside its own transaction before committing.

Staging the duplicate you came to resolve

Ingestion is where identity gets messiest. Say a provider feed arrives with a patient carrying MRN MRN-4471 and the graph already has a Patient with that MRN. That’s expected, since deciding whether the two are the same person is why the ingestion pass exists, but Patient declares unique("mrn"), so the second row can’t be written. If you stage it on an ordinary branch(), staging fails at the duplicate before entity resolution has seen anything.

ingestionBranch() makes a working copy that defers node uniqueness and nothing else, so schema validation, endpoint checks, disjointness and edge cardinality all still apply while staging. The usual answer to this problem is a “skip validation” flag on the import, which I didn’t want, because it lets every other kind of bad row in alongside the duplicates you meant to allow.

const incoming = unwrap(
  await ingestionBranch(base, makeBackend, { id: asBranchId("provider-a") }),
);

const imported = await importGraph(incoming, providerDocument, {
  onConflict: "error",
  onUnknownProperty: "error",
});
if (!imported.success) throw new Error("Provider import was rejected");

const alias = await incoming.nodes.Patient.getById(
  asNodeId("incoming-patient"),
);
if (alias === undefined) throw new Error("Imported patient was not found");

// `canonicalPatient` was read from the base before forking.
await incoming.identity.assertSame(canonicalPatient, alias);

The duplicate MRN and the claim that explains it now sit on the same branch and reach merge planning together. The handle only exposes the assertion methods, without identity reads, retractions, transactions, or access to the underlying store, so it can’t be used to get around the deferred constraint.

At merge time the original uniqueness rule applies again. applyMergePlan() checks uniqueness against the entire resolved write set inside the target transaction, so a valid key handoff or swap goes through as one set (a row-by-row check would see two owners in the middle and reject it). If resolution still leaves two live owners of one MRN, the merge fails with MergeConstraintConflictError and writes nothing, so the deferral only gives you room to review the duplicate before merging.

What it costs

A graph without identity enabled pays nothing: no identity SQL, locks, or closure work. With it on:

One writer per graph for identity-affecting writes on Postgres. They serialize on a per-graph advisory lock. Other graphs and all reads are unaffected.
First-time enablement is heavy. It briefly takes a SHARE lock on the shared nodes table, which blocks writes for every graph in that database, and loads the whole graph to build the initial closure. Do it in a quiet window.
Switching fold and ignore is a breaking schema change, because it changes every areSame answer on existing data. It needs an explicit migration.
It needs real transactions. The bundled SQLite and Postgres drivers have them. Cloudflare D1 and drizzle-orm/neon-http don’t, and reject an identity-enabled graph at construction.

store.identity records and propagates the identity claims you make, so deciding that two records are the same person is still up to you or your entity-resolution pass. What it adds is a durable record of those decisions, including when each was made and when it stopped being true.

Try it

Operational Identity: the full guide, including migrating off sameAs/differentFrom
Constraint-aware ingestion branches
Graph Merge: branch, resolve, and merge identity back
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Bring Your Own Database

Fri, 11 Sep 2026 00:00:00 GMT

The first versions of TypeGraph depended on Drizzle and assumed the database underneath was either a pg pool or better-sqlite3. That held up until people started running it on Cloudflare D1, inside Durable Objects, over Neon’s HTTP driver, in PGlite, and on engines that speak the Postgres wire protocol but handle locking very differently from Postgres.

Each of those broke an assumption somewhere, usually as a SQL error from deep inside a query the engine couldn’t run, and over three releases (0.38, 0.51, and 0.57) I’ve been removing those assumptions. This post covers all three: how Drizzle became optional, how a backend can now declare what it can’t do before a query fails, and how an engine that locks differently can describe that to TypeGraph.

Drizzle is an adapter now

Before 0.38, every Store<G> carried Drizzle’s types whether your code touched them or not. A strict TypeScript project that only ever called store.nodes.Person.create(...) still had to resolve Drizzle’s dialect declarations to typecheck, which is a lot of ORM to pull into your type checking just to create a node.

Now the portable Store<G> has no Drizzle in it. The managed factories own the connection and hand you a complete store:

import { createLocalSqliteStore } from "@nicia-ai/typegraph/sqlite/local";

const store = await createLocalSqliteStore(graph, { path: "./graph.db" });
const alice = await store.nodes.Person.create({ name: "Alice" });

created: LBPSjEoGPqI0P3C6kaJ5M Alice
capabilities.execution.interactiveTransactions: true

createLocalPgliteStore does the same for Postgres-in-WASM. The full graph API is there, store.transaction(...) included.

When you do want to write your own tables on the same connection, you opt in with createAdapterStore, and tx.sql hands you the native transaction:

await store.transaction(async (tx) => {
  await tx.nodes.Document.update(documentId, props);
  if (tx.sqlAvailability !== "available") {
    throw new Error(`Native transaction unavailable: ${tx.sqlAvailability}`);
  }
  await tx.sql.insert(documentVersions).values(versionRow);
});

sqlAvailability is a discriminant because raw SQL is sometimes off on purpose: on a history-enabled store, writing around TypeGraph would skip recorded-time capture, so tx.sql isn’t available there.

Drizzle is now an optional dependency

In 0.51 drizzle-orm became an optional peer dependency, and ten entrypoints don’t need it installed at all: the root, backend, core, schema, indexes, graph-extension, interchange, profiler, graph-merge, and provenance.

That list is enforced by tests: a fixture imports all ten with drizzle-orm missing from node_modules, and source and build-output checks fail if an import ever drags it back in. The last three routes to Drizzle (recorded-time migration DDL, a claim comparison, and some removal-statement builders) moved to portable code with golden tests pinning byte-identical SQL on both dialects.

If you use a managed store or a /adapters/drizzle/... entrypoint you still need Drizzle, and if your package manager skips optional peers you’ll need to install it yourself. The managed factories tell you so with a typed error that includes the npm install command, instead of a module-resolution stack trace.

Backends say what they can’t do

Removing the dependency was the easier part. The harder problem is that TypeGraph emits SQL some engines can’t run, and it used to find that out in production, halfway through a query.

Recursive CTEs are the clearest case, since variable-length traversals, subgraph extraction, and a few identity reads depend on them. An engine without them can now say so:

const capabilities: Partial<BackendCapabilities> = {
  recursiveTraversal: {
    supported: false,
    reason: "engine has no WITH RECURSIVE / equivalent",
  },
};

With that declared, the operations that need recursion throw a ConfigurationError naming the operation, instead of sending the engine SQL it can’t parse. weightedShortestPath falls back to walking the path one hop at a time, which returns the same answer in more round trips. Leaving the capability out means it’s supported, so every existing custom backend keeps working as it did.

How your engine keeps writers apart

Some writes (Operational Identity, and the recorded-time clock behind history and revisionTracking) need exactly one writer per graph at a time. TypeGraph used to pick the lock by checking which dialect it was talking to, which went badly if your engine said “postgres” but had no advisory locks.

Now the backend declares how it keeps writers apart, which for the two bundled engines is one line each:

// PostgreSQL
writeFence: { mechanism: "advisory", drain: "table-lock" }
// SQLite
writeFence: { mechanism: "engine-serialized" }

A custom backend that hosts identity or recorded history without declaring one is rejected at construction, and the error message prints the line to add for your dialect.

0.57 added two more mechanisms. caller-serialized is your promise that nothing else writes to the database; TypeGraph enforces the in-process half and trusts you with the rest. row is for engines with no advisory locks at all: TypeGraph takes the lock by upserting a row in its own typegraph_fences table. If your engine settles write conflicts at commit time rather than blocking, declare conflict: "commit-time" and TypeGraph retries its own transactions as a whole unit when they lose, up to three attempts.

Engine profiles

The piece I’m happiest about is that 0.57 made the two bundled backends data. createPostgresBackend and createSqliteBackend are now the same function, createSqlBackend, applied to an engine profile: the dialect, how it executes, how it provisions, and what it declares. That means you can take a bundled profile, change what’s different about your engine, and get a real backend:

import {
  buildSqliteEngineProfile,
  createSqlBackend,
  deriveEngineProfile,
} from "@nicia-ai/typegraph/adapters/drizzle/engine";
import { createLocalSqliteBackend } from "@nicia-ai/typegraph/adapters/drizzle/sqlite/local";

const { db } = createLocalSqliteBackend();
const base = buildSqliteEngineProfile(db);

const derived = deriveEngineProfile(base, {
  declaredCapabilities: {
    ...base.declaredCapabilities,
    writeFence: {
      mechanism: "row",
      drain: "quiescent",
      conflict: "commit-time",
    },
  },
});
const backend = createSqlBackend(derived);

console.log(backend.capabilities.execution?.unitOfWork);
// "optimistic-retry"

(It’s SQLite here only because that’s what runs on a laptop.) You never set unitOfWork yourself; TypeGraph works it out from what the engine declared rather than guessing from the engine’s name.

Derivation is narrow on purpose. You can override declared capabilities, the lock SQL, and a handful of runtime hooks, but not dialect or execution, because the bundled builders capture those in more than one place, and I’d rather throw at construction than hand you a backend that’s half one engine and half another.

One error for “you lost the race”

A Postgres serialization failure or deadlock used to surface as whatever the driver felt like throwing. Now every conflict comes back as TransactionConflictError, with the driver error as cause, and store.transaction() can retry for you:

// SQLite never raises 40001; this stands in for what PostgreSQL would.
function serializationFailure(): Error {
  return Object.assign(new Error("could not serialize access"), {
    code: "40001",
  });
}

let attempts = 0;
await store.transaction(
  async (tx) => {
    attempts += 1;
    await tx.nodes.Account.create({ owner: "ada", balance: 100 });
    if (attempts < 3) throw serializationFailure();
  },
  { retry: { attempts: 3 } },
);
console.log(attempts, (await store.nodes.Account.find()).length);
// 3 1 — two rolled-back attempts left nothing behind

The callback reruns from the top, so it has to be safe to run more than once: read inside it, don’t reuse values from outside it, and don’t cause side effects that escape the transaction.

Branches your host can copy

branch() normally copies a graph by streaming it into a fresh database. 0.57 also adds forkedWorkingCopyStrategy, which hands the copy to whatever your host is good at, such as a file copy, CREATE DATABASE ... TEMPLATE, or a provider’s branch API. Because the fork is a physical copy of the database, it keeps things a streamed copy can’t, including recorded history, so a forked branch can answer asOfRecorded queries from before the fork was taken.

What isn’t there yet

You can’t build an engine from scratch yet. deriveEngineProfile adapts one of the two bundled profiles, and building a profile from nothing needs pieces that aren’t exported. No third engine has been run through this in production yet either: the commit-time retry path is tested by injecting conflicts into real SQLite and PGlite transactions rather than against an engine that produces them on its own. If you have one, I’d like to hear how it goes.

Upgrading

From 0.37, the Drizzle-specific entrypoints moved under /adapters/drizzle and the old paths are gone rather than aliased:

0.37	0.38 and later
`/sqlite`	`/adapters/drizzle/sqlite`
`/sqlite/local`	`/adapters/drizzle/sqlite/local`
`/sqlite/libsql`	`/adapters/drizzle/sqlite/libsql`
`/postgres`	`/adapters/drizzle/postgres`
`/postgres/pglite`	`/adapters/drizzle/postgres/pglite`

/sqlite/local and /postgres/pglite now mean the managed store factories. If you read tx.sql, switch to createAdapterStore / createAdapterStoreWithSchema; if you don’t, nothing changes.

Custom backend authors: capabilities.pessimisticLocks is now capabilities.writeFence, and conflicts should be matched as TransactionConflictError rather than by SQLSTATE. The 0.57.0 changelog has the full list.

Try it

Backend Setup: entrypoints, capabilities, and the parity matrix
Write fence declaration: every mechanism and what each error means
Authoring an engine profile: the derivable fields and worked examples
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Letting an Edge's Targets Depend on Its Source

Fri, 04 Sep 2026 00:00:00 GMT

This schema looks reasonable, but it allows more than you probably meant:

const assignedTo = defineEdge("assignedTo", {
  from: [Employee, Student],
  to: [Department, Course],
});

You want employees assigned to departments and students assigned to courses, but array-valued from and to declare the Cartesian product, so every source may point at every target and both store.edges.assignedTo.create(student, department) and create(employee, course) succeed. Until 0.55 the only way to rule those two combinations out was to split the edge into two kinds and query them separately.

Say which source gets which targets

to can now be a map from source kind to its own allowed targets:

const assignedTo = defineEdge("assignedTo", {
  from: [Employee, Student],
  to: {
    Employee: [Department],
    Student: [Course],
  },
});

const graph = defineGraph({
  id: "assignments",
  nodes: {
    Employee: { type: Employee },
    Student: { type: Student },
    Department: { type: Department },
    Course: { type: Course },
  },
  edges: { assignedTo },
});

create(employee, department) and create(student, course) still work, and the other two combinations fail before anything is written:

EndpointPairError: assignedTo: undeclared endpoint pair
  { edgeKind: "assignedTo", endpoint: "pair",
    fromKind: "Employee", toKind: "Course",
    allowedPairs: [
      { from: "Employee", to: "Department" },
      { from: "Student", to: "Course" },
    ] }

In typed code you won’t get that far, because the collection’s create() signature narrows per source and handing it an employee and a course is a compile error. The runtime check covers the paths a type checker can’t see, such as dynamic collections, bulk writes, and imports. An endpoint kind that isn’t in from at all still throws the existing EndpointError; EndpointPairError is specifically for two kinds that are each valid but were never declared together.

The map itself is checked when you call defineEdge(): every kind in from needs an entry, extra keys aren’t allowed, and no entry may be empty. A mistake throws ConfigurationError at that point rather than turning up later as a confusing write failure.

Narrowing, never widening

An edge’s map is its outer bound, and a graph or a runtime graph extension can register a narrower version:

edges: {
  assignedTo: {
    type: assignedTo,
    from: [Employee],
    to: { Employee: [Department] }, // this graph has no students
  },
}

A registration can’t add a pair the edge never declared. That includes the easy mistake of registering the old array form, to: [Department, Course], against an edge whose map only allows the correlated pairs, which would quietly re-admit the cross-pairs the map is there to forbid, so it’s rejected.

Subclasses are checked against the declared pairs. With SubTask subClassOf Task and an edge that allows Task: [Task], every mix of Task and SubTask works, but a SubTask can’t borrow a target that only some other source kind is allowed.

Bulk writes are all or nothing

await store.edges.assignedTo.bulkCreate([
  { from: employeeA, to: departmentA }, // valid
  { from: employeeB, to: courseA }, // undeclared pair
]);
// throws EndpointPairError; store.edges.assignedTo.count() is still 0

A single undeclared pair rejects the whole batch, because committing the valid half and quietly dropping the rest would leave you guessing which rows made it.

Pairs are stored in the schema

The pairs are stored in the serialized schema, and declaring them in a different key order doesn’t change the schema hash. Replacing an array to with a map removes pairs even though it removes no kinds, so it counts as a breaking change and follows the same migration rules as any other breaking edge change. See endpoint pair changes.

Try it

Source-Dependent Targets: the full reference
EndpointPairError
Endpoint pair changes
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

One Round Trip Per Write

Tue, 01 Sep 2026 00:00:00 GMT

I turned on statement logging, turned off prepared statements, and created one node. This is what went over the wire:

begin
SELECT ... schema-version fence probe
SELECT ... duplicate/endpoint check
INSERT ... (the write)
commit

That’s five round trips to write one row. On a pooled connection sitting next to the database you’d never notice, but a lot of people run TypeGraph from edge functions against managed Postgres, where a round trip is more like 45ms and each of those statements pays it in full, so the row takes roughly a quarter of a second to exist.

When I captured a first-run provisioning flow for one graph, it issued 97 statements, and about 40 of them, spread across just seven writes, were schema-version probes, duplicate checks, and begin/commit rather than actual writes.

That was issue #533, and closing it took two releases. The short version: an eligible write and every check it depends on now go to the database together, as one request.

A note on the numbers: everything below is a count of requests crossing the transport, which is what I measured. Latency figures are that count times an assumed 45ms round trip, not wall-clock benchmarks.

Checks and write, in one statement

The old path was a sequence of reads, each deciding whether the write could proceed: whether the schema version still matched, whether the row was a duplicate, whether the edge’s endpoints existed, and whether the cardinality constraint held. Each of those was another round trip, and the whole sequence was wrapped in a transaction so nothing could change between the checks and the insert.

In 0.52, for the common shape on Postgres (schema-managed, generated ID, no history or identity tracking), all of those checks and the insert compile into a single statement, and the database evaluates the conditions and performs the write atomically.

That takes five or six sequential requests down to one, which at 45ms removes roughly 180–225ms of waiting from every such write. On Neon’s WebSocket driver, a typical get-or-create that misses drops from five requests to one.

When a write needs something a single statement can’t carry (history capture, a caller-owned transaction, call-level matchOn), it takes the ordinary transactional path, which is still there underneath for everything the fast path doesn’t cover.

Batches on drivers without transactions

The bigger win is on Neon HTTP, Cloudflare D1, and libSQL, which don’t give you an interactive transaction at all, only one-shot atomic batches. Before 0.52, a bulk write on one of them ran statement by statement, so it was slow and a partial failure left partial data behind.

Now TypeGraph compiles eligible bulk writes into a precompiled program that those drivers execute as a single atomic batch. nodes.bulkInsert() becomes one request, edge batches validate their endpoints inside the write instead of reading candidate endpoints first, and batches with a cardinality constraint (one, unique, oneActive) carry the constraint checks in the same batch. Counting actual execute() / batch() calls on libSQL:

Bulk edge write	Before	After
Unconstrained	1	1
With a durable match identity	6	1
With a cardinality constraint	8	1

Since it’s all one batch, a conflict anywhere rolls the whole thing back. I wanted proof that the conflict check actually did something, so I wrote its regression test by deleting the conflict clause, watching duplicates land, and then putting the clause back and watching the same input get rejected.

0.53: the writes that have to look first

0.52 fused the writes that create things, which left the ones that need to know what’s already there: updates, upserts, and deletes that have to release the uniqueness claims their row held. 0.53 moved those onto the same programs.

Single-row update() and delete() are one read plus one guarded write, rather than a transaction around both: 60–67% fewer requests.
bulkUpsertById() is two requests: one batched read, one atomic write.
bulkReplaceById() is new. Each item is a complete document, so there’s nothing to read first. Creates, replacements, resurrections of deleted rows, uniqueness claims, and fulltext and vector index updates all go in one request.
Large D1 upserts stay atomic. D1 allows 100 bind parameters per statement, so the program splits into many statements inside one atomic batch. That raised the ceiling from 17 nodes and 6 edges to 512 nodes and 187 edges per call. Anything bigger falls back to the regular path instead of building an unbounded request.
Postgres transaction sessions run the same programs through a savepoint, so a rejected program doesn’t poison the transaction around it.

There’s one trade-off to know about: the fused update() is optimistic. It doesn’t hold a lock between its read and its write, so if the row moved underneath it, it re-reads and tries again, up to four times, and then throws DatabaseOperationError. Under sustained contention on the same row, that can fail a write that a transaction-capable backend used to serialize for you. I think that’s the right trade for most workloads, but not for something like a hot counter.

Letting the database decide: match identities

Fusing an edge get-or-create needed something the database could arbitrate on its own, without a lock or an in-process cache: a real unique constraint. So 0.52 also added durable edge match identities. An edge can declare a named set of fields that identify it:

const worksAt = defineEdge("worksAt", {
  schema: z.object({ role: z.string() }),
});

edges: {
  worksAt: {
    type: worksAt,
    from: [Person],
    to: [Company],
    cardinality: "many",
    matchIdentity: { name: "employment", fields: ["role"] },
  },
},

TypeGraph stores that key on every edge row and backs it with a unique index, on both SQLite and Postgres. Once that exists, getOrCreateByEndpoints no longer has to read, decide, write, and hope nothing raced, because it’s a single conditional insert the database resolves atomically, which is what makes the one-request path safe on a stateless edge worker with nothing in memory to lean on.

Changing a match identity is a breaking schema change and is rejected while the edge kind has rows. Call-level matchOn still works for matching you don’t want in the schema, through the regular transactional path.

Upgrading

If you use a bundled backend (createLocalSqliteBackend, createPostgresBackend, or one of the serverless factories), you don’t need to change any code.

There are two things to know. An existing or externally provisioned database has to be opened once through createStoreWithSchema() (or get TypeGraph’s generated base-schema migration) before the zero-DDL verified-store paths will run; until then they fail early with BaseSchemaMigrationError. And store.transaction() now throws on a backend without interactive transactions instead of quietly running your callback without one.

If you maintain a custom backend, GraphBackend.commands is now required and a few capability flags changed shape. The authoritative command sessions section has the migration.

Try it

Batch write patterns and remote edge convergence: which writes are eligible, and the measured counts
Upgrading deployment-wide base storage
Changelog for 0.53.0, and 0.52.0
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Five Bugs That Didn't Crash

Fri, 14 Aug 2026 00:00:00 GMT

A bug that crashes is the easy kind, because it tells you where it is. The ones I worry about in a database library are the ones that return a reasonable-looking answer (zero rows, a successful write, a clean startup) while the data is wrong, so you find out weeks later or not at all.

Over the last stretch of releases (0.44 through 0.50, plus one older fix) I’ve fixed five of those in TypeGraph. None of them warrants a post of its own, but together they show how I want the library to behave, and one of them you could hit just by doing what TypeGraph’s own error message told you to do.

Rows that exist at no point in time

A valid-time window is half-open, so asOf(t) returns a row when valid_from <= t < valid_to. If you backfilled a record you knew had already ended, you’d pass a validTo in the past and no validFrom, and the write stamped its own instant as validFrom, which put the start after the end. A window that runs backwards contains no t at all, so the row was stored, counted, and exported, but no temporal read could ever return it.

Since 0.48, a write that creates a row (or resets its window) with a validTo at or before its own instant and no validFrom stores no lower bound instead, so the row reads as “ended at T, start unknown”, which is what you meant. A future validTo behaves as before. Custom backends can call the same helper the built-in ones use, resolveStampedValidityLowerBound, so the rule lives in one place.

While I was in there, 0.47 added the thing people were faking with delete-and-recreate: clearValidTo: true reopens a window you closed too early, on the same row, with oneActive edges rechecked because reopening can create a second active edge.

await store.nodes.Employment.updateById(employmentId, {
  patch: { department: "Research" },
  clearValidTo: true,
});

Upgrading doesn’t repair old rows, on purpose

Older versions could store inverted windows, and upgrading leaves them alone. I think that’s the right call: an upgrade that made invisible rows start appearing in historical queries would change your reports and replays without telling you which rows had moved, which is its own quiet bug.

So the repair is an explicit operator action, with a dry run:

import { repairInvertedValidityWindows } from "@nicia-ai/typegraph";

const report = await repairInvertedValidityWindows({
  backend: anyBackend,
  relations: "live-and-recorded",
  mode: "report",
});
// report.counts.recordedNodes === undefined means NOT SCANNED, never "clean"

mode: "apply" rewrites what report counted. Stop writers first, pass the raw backend on a history-enabled store, and repair "live-and-recorded" unless you have a reason not to, because fixing only the live rows leaves the recorded history carrying the same backwards window and asOfRecorded will keep serving it. The runbook has the details.

Constraints that `importGraph` walked straight past

TypeGraph lets you declare hierarchy-wide uniqueness (scope: "kindWithSubClasses"), disjointWith(Person, Organization), and edge cardinality (one, unique, oneActive). Plain per-kind uniqueness was always backed by a real database key, but these three were enforced by a writer that took the per-graph write lock, checked, and then wrote.

That works only as long as every writer takes the lock, and importGraph didn’t. It also skipped the disjointness and cardinality checks entirely, so an import could commit a Person and an Organization with the same id, or three edges on a cardinality: "one" relationship, and report success. Import is also the path most likely to be carrying data you didn’t write yourself.

As of 0.50, each of those constraints is also backed by a reservation row whose primary key admits exactly one owner. Taking the constraint means winning that insert, so a writer holding no lock still loses the race it should lose. Import now enforces all three and reports rejected rows in its errors like any other violation. Every store and import write also goes through a single write pipeline now. Import had drifted because it had its own hand-built write path, and nobody noticed which rules it was missing.

There are two caveats. This only covers writes that go through TypeGraph, so raw SQL inserting into the node or edge tables skips the reservation. And databases created before 0.50 need the new edge-claims table, which the normal bootstrap or the generated migration SQL provides.

As with validity windows, the fix prevents new violations and leaves old ones where they are. To find those:

for (const violation of await store.verifyConstraintFences()) {
  console.warn(violation.family, violation.target.axis, violation.target.key);
}

The audit reads the nodes and edges themselves rather than the new reservation tables, because a database written before those tables existed has no reservations in it, and an audit that only looked there would report zero violations on exactly the data you’re worried about. It writes and repairs nothing, since picking which of two conflicting rows survives destroys data either way, and that decision should be yours.

A search index that said it was fine

Fulltext and vector search need their own tables. TypeGraph creates them on first use and writes a marker row saying so, and from then on it trusted the marker without checking that the tables were still there.

When one went missing out of band (a partial restore, a migration that recreated a schema, or an edge runtime that lost a file), the store opened cleanly and then failed on the first search with a raw driver error about a missing relation. This mostly showed up on Cloudflare Durable Objects, where one SQLite database per tenant means thousands of small databases that nobody is watching individually.

That error is now a ContributionUnavailableError with state: "physical-storage-missing" and rebuild guidance. The check only runs on the error path, so healthy stores don’t pay for it. There’s also a three-step ladder for when search is broken, from cheapest to most drastic:

Step	Call	Writes
Probe	`store.probeContributions()`	Nothing. Safe on a replica
Repair	`store.repairContributions()`	Marker rows, `IF NOT EXISTS`
Rebuild	`store.rebuildContribution("fulltext")`	Deletes and refills this graph’s rows

Start at the top and stop when the probe says ready. Rebuild is the only fix when the table exists in a shape the current code no longer produces, and it needs a maintenance window. Vector storage can’t be rebuilt, because the embeddings exist only in the table a rebuild would drop, so TypeGraph won’t drop it. The troubleshooting guide walks through each state.

A migration that deleted your runtime kinds

This one stings. Runtime schema evolution lets an agent add node and edge kinds with store.evolve(), and those kinds live in the stored schema rather than in your TypeScript graph definition.

migrateSchema() committed whatever graph you passed it, so if you migrated with your compile-time graph, every kind added at runtime disappeared from the schema while its rows stayed in the tables where nothing could reach them. The usual way you’d end up calling migrateSchema() was the library’s own error message telling you to review the changes and run it, so following my advice hid your data.

0.44 folds the stored runtime additions in before committing, the same way store creation already did. It also throws if a migration would drop a kind that still holds rows, unless you pass { discardDroppedKindRows: true }.

Two races in the same area got fixed alongside it:

A schema commit could land while another writer was mid-write against the version being replaced. Managed writes now recheck their schema version while holding a lock the commit also needs, so a stale write fails instead of landing against a schema that no longer accepts it.
Removing a kind and adding it back before its cleanup ran made the old rows reappear next to the new ones, and the cleanup then skipped them because the kind was live again. evolve() now won’t re-add a kind while its cleanup is pending, and cleanup rechecks the schema under the same lock.

An `implies()` that folded nonsense rows

This is the older one, from 0.35. implies(edgeA, edgeB) means “a traversal of edgeB can include edgeA edges”, which only makes sense if edgeA’s endpoints could stand in for edgeB’s. Nothing checked that, so this was accepted:

edges: {
  authored: { type: authored, from: [Author], to: [Paper] },
  covers: { type: covers, from: [Paper], to: [Topic] },
},
ontology: [implies(authored, covers)],

and a covers traversal with expand: "implying" would fold in rows that start at an Author. Now it fails when the graph is built or loaded:

ConfigurationError: implies("authored", "covers") is endpoint-incompatible:
from kind(s) [Author] declared on "authored" cannot be assigned to any of
"covers"'s from kind(s) [Paper].

The check also runs on schemas loaded from the database, so a bad relation saved by an older version fails on first load after upgrading. The same release made projected ids keep their NodeId<N> brand through .select() and gave every fixed-shape error class a typed details, so fewer mistakes make it to runtime in the first place.

What they have in common

All five fixes follow the rules I now hold the whole library to. If TypeGraph can’t do what you asked, it throws and tells you why rather than returning an empty result that looks like a clean one, and it doesn’t rewrite your data behind your back, even to fix it. You get a report first and decide what to do.

Try it

Repairing inverted validity windows
Claim relations, and what they do not promise
Contribution health: probe, repair, rebuild
Schema Management: migrations and kind removal

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

An Infinite Supply of Graph Databases

Fri, 24 Jul 2026 00:00:00 GMT

TypeGraph turns a SQLite (or PGlite, or Postgres) connection into a typed property graph. If you point that connection at a Cloudflare Durable Object’s own storage, you no longer have to provision the database at all. Every user, agent conversation, or workspace can have its own graph database without anyone ever creating it, and I think that’s a lot of fun.

I built a companion repo to show it off, cf-do-typegraph. It wires TypeGraph into a single Durable Object class and runs three real apps on top, entirely on your laptop under wrangler dev. It’s MIT-licensed.

Naming is the provisioning step

Here’s the whole multi-tenant boundary:

// the whole multi-tenant boundary, trimmed from src/worker.ts
const stub = env.GRAPH_DO.get(env.GRAPH_DO.idFromName(`${example}:${tenant}`));
return stub.fetch(request); // that tenant's graph, and nothing else, lives here

idFromName is effectively the provisioning API. The Durable Object it names, and the private SQLite database inside it, comes into existence on the first request and hibernates as soon as nothing is using it, so there’s no CREATE DATABASE, no row to add to a tenants table, and no migration to run against a database that didn’t exist five minutes ago. Giving every user, agent, or document its own graph stops being a capacity-planning question, because each one is just a name.

Minting a lot of them is just a loop:

curl -X POST "localhost:8787/api/spawn/notes?count=25&prefix=demo"

{ "example": "notes", "seeded": ["demo-1", "demo-2", "...", "demo-25"] }

curl "localhost:8787/api/notes/demo-7/search?q=hibernation"   # its own private graph

That endpoint forwards 25 /seed requests to 25 different names and lets each Durable Object materialize when its request arrives. There’s nothing more to it than that.

Isolation and shared transactions

Making each tenant a Durable Object has two consequences that matter more than the provisioning trick.

Isolation is physical. Each tenant’s SQLite file is its own ctx.storage rather than a slice of a shared table. The usual SaaS approach is a tenant_id column plus a promise that every query remembers its WHERE tenant_id = ?, but here there’s no shared table to put that column in, so a bad join or a missing filter can only ever see one tenant’s data.

The graph and the app’s data live in the same file and the same transaction. The Durable Object boots its store the same way on every request:

src/do/graph-do.ts

createSqliteBackend(drizzle(this.ctx.storage));

ctx.storage is the same SQLite the application would use for its regular tables, and TypeGraph doesn’t need a separate connection or service, so writing an app row and the graph edge that describes it can be one store.transaction(...). There’s no sync job between your data and your graph, and nothing for them to drift apart on.

Three apps, one Durable Object class

The repo runs the same GraphDO class three ways, distinguished only by what you name the tenant. I picked each example because it needs a query that’s painful to hand-write in SQL.

`authz`: a graph per workspace

Zanzibar-style permission checks are reachability questions, and TypeGraph’s ontology does the reasoning you’d otherwise hand-roll in a WITH RECURSIVE:

src/examples/authz/graph.ts

ontology: [
  implies(owner, editor), // owner ⇒ editor ⇒ viewer
  implies(editor, viewer),
  inverseOf(memberOf, hasMember), // group membership, read backwards, zero stored reverse edges
],

A permission check is one shortestPath call over the edge kinds the requested relation implies:

curl "localhost:8787/api/authz/acme/check?user=alice&relation=editor&doc=roadmap"

{
  "allowed": true,
  "relation": "editor",
  "subject": "user:alice",
  "via": {
    "grantSubject": "group:staff",
    "grantRelation": "editor",
    "grantTarget": "folder:engineering"
  },
  "pathNodeIds": [
    "user:alice",
    "group:eng",
    "group:staff",
    "folder:engineering",
    "folder:specs",
    "doc:roadmap"
  ],
  "pathEdgeKinds": ["memberOf", "memberOf", "editor", "parentOf", "parentOf"]
}

Alice never got a direct grant on that doc, and the answer comes with the path that proves she has access anyway: nested group membership (alice → eng → staff), one group-level editor grant, and two levels of folder inheritance, all inferred at query time from five stored edges without a permissions table.

`notes`: a graph per user

This one is a personal wiki with [[wiki-links]], and the fun part is that FTS5 runs inside the Durable Object’s own SQLite, so there’s no search service to keep warm:

curl "localhost:8787/api/notes/me/search?q=reachability"

{
  "hits": [
    {
      "id": "note:reachability",
      "title": "Reachability",
      "score": "...",
      "snippet": "<mark>Reachability</mark> asks whether you can get from one node to another..."
    }
  ]
}

Backlinks don’t need any stored rows. The graph only writes a forward linksTo edge when a note contains [[Some Target]], and one ontology declaration lets a linkedFrom traversal read those same edges backwards:

src/examples/notes/graph.ts

ontology: [inverseOf(linksTo, linkedFrom)],

There’s no second edge to keep in sync, so backlinks can’t drift from the links that produced them.

`agent-memory`: a graph per conversation

Each session is its own graph, seeded by replaying a hand-written conversation one message at a time:

"I'm Ada, and I'm PMing the Halo launch."
"Grace is my lead engineer — we've shipped three products together."
...
"New development: we're partnering with Northwind, and Grace is their main contact."

That eighth message is my favorite part of the repo. Organization isn’t a node kind in the compile-time schema, so it arrives at runtime, gets validated the same way an LLM’s proposed schema change would be, and is applied live:

src/examples/agent-memory/replay.ts

const validation = validateGraphExtension(evolution.extension, {
  strict: true,
});
current = await current.evolve(validation.data);

The graph grows a new node kind and a new worksAt edge kind in the middle of a conversation, while the Durable Object is running. The change is persisted, so it’s still there the next time the object wakes from hibernation. And because the store boots with { history: true }, the same graph can answer “what did the agent believe after message 4?”, before Northwind existed, by reading at a recorded point in time instead of the live state.

The same pattern without Cloudflare

The underlying idea, a small, typed graph database per tenant, addressed by name, works well whenever tenants are numerous, mostly idle, and shouldn’t share a query surface. Durable Objects make it especially easy (SQLite at the edge, isolated per object, and hibernating for free), but TypeGraph doesn’t know or care that one is underneath, and the same pattern works with:

A directory of SQLite files. One file per tenant, opened through createLocalSqliteStore. Provisioning is choosing a file path.
A pool of PGlite files. Postgres-in-WASM via createLocalPgliteStore, one file per tenant, no server process.
A database per Neon branch. Real network Postgres, with the standard createPostgresBackend pointed at a different connection string per tenant, provisioned through Neon’s API instead of idFromName.

I built the demo on Durable Objects because they need the least infrastructure to try: there’s no server to run, and you don’t need an account to develop against them.

Tested against the real thing

Every example runs its tests against real Durable Objects via @cloudflare/vitest-pool-workers, not mocks, including a cross-tenant isolation test that seeds one tenant and checks that a same-shaped, differently named tenant reads back empty. pnpm dev runs the whole thing (landing page, live force-directed graph view, all three APIs) locally for free. Workers AI, the one billable piece, is only used for optional semantic search and entity extraction, and ships commented out.

Try it

cf-do-typegraph: pnpm install && pnpm dev, then open localhost:8787
Bring Your Own Database: the backend abstraction that lets the same store run on a different SQLite underneath
Agent Memory That Knows Why It Believes Things: the bitemporal history behind the agent-memory replay
An Agent That Grows Its Own Schema: store.evolve(), the mechanism behind the live Organization extension
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

TypeGraph vs. Neo4j, LadybugDB and pgGraph: Who Wins What

Thu, 23 Jul 2026 00:00:00 GMT

My first pass at benchmarking TypeGraph against real graph databases ran the seven LDBC “short read” queries (IS1–IS7) against Neo4j and LadybugDB. TypeGraph on SQLite won every one of them, which should have made me suspicious rather than happy: IS1–IS7 are point lookups and one-hop walks, and an in-process engine doing direct index seeks can’t lose that race to anything that pays a network round trip.

So I rebuilt the harness around the queries a graph database is supposed to win (shortest paths, bounded neighborhood walks, complex multi-hop reads, and whole-graph algorithms) and ran 17 queries against five engines at two scales. The short version:

TypeGraph on SQLite still wins every point read, usually by 10–100x.
The engines that keep an in-memory graph index win whole-graph algorithms by three to four orders of magnitude, and the gap gets wider as the data grows.

I’m publishing both results rather than only the flattering one.

The setup

All five engines run through one shared harness (packages/benchmarks/src/real/):

Engine	Version
SQLite	3.53.2 (via `better-sqlite3` 12.11.1)
PostgreSQL (TypeGraph backend)	18.1 (`pgvector/pgvector:pg18` image)
Neo4j	`neo4j:2026.05.0` server image, `neo4j-driver` 6.2.0, GDS plugin
LadybugDB	`@ladybugdb/core` 0.18.0
pgGraph	Evokoa pgGraph 0.1.8 (`ghcr.io/evokoa/pggraph:0.1.8`, bundles PostgreSQL 17)

pgGraph is the new entrant, and I think it’s clever. Rather than being a separate database, it’s a Postgres extension that builds a derived CSR (compressed sparse row) index over ordinary normalized tables and exposes traversal and pathfinding as SQL functions. Its point reads are tuned Postgres, and the CSR index only comes into play once a query traverses.

The 17 queries are the original IS1–IS7; IC13 (shortest path) and IC14 (weighted shortest path); BFS3, a bounded neighborhood walk; three complex reads (IC2, IC8, IC9); and four graph-algorithm queries: GA_DEGREE, GA_WCC (weakly connected components), and GA_BFS / GA_SSSP (whole-component reachability and shortest-path depth from a seed).

I held the comparison to two rules. Every result is checked with a value-level digest, per row, across every engine that runs the query, and every run below passed, since a fast wrong answer shouldn’t count. And nothing is skipped silently: an engine without a comparable primitive for a query reports a typed gap, so a gap cell means the engine can’t run that query in a comparable form, not that I didn’t get around to it.

Scales are SF1 (9,892 persons, 361K directed knows edges) and SF10 (65,645 persons, 3.88M knows, 21.9M comments). Each is one run on an EC2 host with shared vCPUs, so treat sub-millisecond cells and anything flagged noisy as order-of-magnitude.

SF1

p50 latency in milliseconds unless noted. Fastest engine per row in bold.

Query	typegraph-sqlite	typegraph-postgres	neo4j	ladybugdb	pggraph
IS1	0.03	0.76	4.84	1.11	0.93
IS2	1.85	21.5	39.9	76.0	19.9
IS3	0.24	1.82	4.07	4.5	1.47
IS4	0.02	0.98	3.01	0.39	0.91
IS5	0.03	1.08	3.1	1.61	0.94
IS6	0.07	1.97	3.23	3.93	1.89
IS7	0.07	2.15	5.74	7.83	1.76
IC13 (shortest path)	3.88	22.3	3.24	9.91	2.18
IC14 (weighted SP)	5586	4860	gap	gap	gap
BFS3	220	1139	468	1539	357
IC2	51.8	523	36.2	89.1	347
IC8	3.06	17.3	3.73	24.2	8
IC9	2236	15069	3388	775	3498
GA_DEGREE	0.03	1.09	2.97	1.8	0.72
GA_WCC	7269	24237	18.7	gap	9.53
GA_BFS	221	1828	24.5	gap	288
GA_SSSP	220	1742	23.6	gap	284

Point reads

TypeGraph on SQLite takes every IS row, often by one to two orders of magnitude, because it’s the only engine here that pays no network round trip and no per-call query planning overhead. GA_DEGREE and IC8 go the same way, because underneath the “algorithm” and “complex read” labels they’re point lookups too.

This is the case for an embedded graph. Most of what an application asks its graph all day looks like IS1–IS7 (fetch this person, their recent posts, who they know), and on IS1 Neo4j takes 4.84ms where SQLite takes 0.03ms.

Graph algorithms

GA_WCC, GA_BFS, GA_SSSP, and IC13 are what a graph engine’s specialized index exists for, and here the CSR engines are in a different league:

pgGraph wins GA_WCC (9.53ms) and IC13 (2.18ms), running union-find and shortest path directly over its CSR index.
Neo4j with the GDS plugin wins GA_BFS (24.5ms) and GA_SSSP (23.6ms). Without GDS, Neo4j answers these with Cypher path enumeration, which works but is slow. With GDS it projects the graph into memory once and runs the same kind of set-based traversal pgGraph does.
TypeGraph is three to four orders of magnitude slower on GA_WCC (7,269ms on SQLite, 24,237ms on Postgres, against pgGraph’s 9.53ms).

That last gap isn’t a bug I can fix. TypeGraph’s algorithms run as rounds of SQL, one window or aggregate query per round, however well indexed, while pgGraph and GDS hold the graph in an in-memory structure built for this access pattern, and query tuning won’t make SQL iteration behave like a CSR traversal.

SF10

The SF10 run happened before I added the GDS plugin to the Neo4j setup, so Neo4j’s graph-algorithm rows show gap here even though Neo4j can run them. For Neo4j on those queries, the SF1 table above is the current picture.

s = seconds; otherwise milliseconds.

Query	typegraph-sqlite	typegraph-postgres	neo4j	ladybugdb	pggraph
IS1	0.03	1.06	5.22	1.12	0.93
IS2	2.35	77.2	133	104	22.6
IS3	0.42	6.23	53.8	15.7	1.87
IS4	0.03	0.91	3.33	0.90	0.96
IS5	0.04	8.67	5.52	2.68	0.96
IS6	0.07	3.69	8.09	5.50	2.02
IS7	0.07	7.29	8.23	8.38	1.80
IC13 (shortest path)	35.0	339	82.2	161	2.25
IC14 (weighted SP)	74.6s	57.3s	gap	gap	gap
BFS3	1.7s	7.2s	3.9s	9.3s	2.2s
IC2	141	724	138	296	843
IC8	5.24	220	92.1	47.6	15.3
IC9	11.9s	76.7s	15.5s	3.1s	25.4s
GA_DEGREE	0.06	1.05	3.02	2.07	0.82
GA_WCC	119.9s	506.0s	gap	gap	69.0
GA_BFS	2.8s	22.3s	gap	gap	2.0s
GA_SSSP	2.8s	22.3s	gap	gap	1.9s

Point reads barely move at 10x the data, as you’d expect from an indexed seek. The more interesting number is how GA_WCC grows:

Engine	SF1	SF10	Growth
pggraph	9.53ms	69.0ms	~7x
typegraph-sqlite	7269ms	119.9s	~16x
typegraph-postgres	24237ms	506.0s	~21x

pgGraph grows a bit less than linearly with the data, while TypeGraph’s round-by-round algorithm grows faster than linearly because more edges also means more rounds, so the gap gets bigger as the data grows. If you need whole-graph analytics over millions of edges on a schedule, use a specialized engine for that job.

SQLite beats Postgres, even inside TypeGraph

Both TypeGraph backends run the same logical algorithms, and SQLite is 4–8x faster on the heavy ones at SF10 (GA_WCC 119.9s vs 506.0s, GA_BFS 2.8s vs 22.3s, IC9 11.9s vs 76.7s). My first guess was network round trips, but that doesn’t hold up: GA_BFS already issues one INSERT ... RETURNING per round, Postgres is on loopback, and the ratio stays about 8x at both scales, whereas a fixed per-call cost would shrink as a share of a longer run. That points at a per-row cost in how Postgres executes these queries, which I haven’t tracked down yet.

The one exception is IC14, the weighted shortest path, where Postgres wins. Its set-based frontier expansion handles a large, unbounded Dijkstra better than SQLite’s row-at-a-time version.

IC14: the one only TypeGraph ran

IC14 asks for the lowest-cost path between two people rather than the fewest hops. In this lineup, nothing else could run it in a comparable form: Neo4j’s GDS has no stored knows weight to project, pgGraph’s shortest path counts hops only, and LadybugDB’s weighted shortest path isn’t wired into the harness yet. TypeGraph answers it on both backends with store.algorithms.weightedShortestPath, at real LDBC scale (5.6s / 4.9s at SF1, 75s / 57s at SF10), with byte-identical results across the two.

Those times aren’t fast, and the benchmark makes them look worse than real use would, because it picks random pairs near the graph’s diameter, which is the worst case for single-source Dijkstra. Real weighted-path questions tend to be between related, nearby entities, where the same algorithm stops early.

Loading

Loading is where TypeGraph still trails. It improved a lot between my first run and this one, because in the meantime 0.37 shipped a trusted initial import, and the benchmark loader now uses it.

importGraph validates every row it writes: schema shape, edge endpoints, cardinality, conflicts. That’s the right default, since most imports come from somewhere you don’t fully trust. But when you’re filling a brand-new database from an export you produced and already validated, every one of those checks is wasted work. trustedImportGraph and trustedImportGraphStream skip them. They bypass the normal write pipeline, drop secondary indexes, insert straight into the tables, then rebuild the indexes and refresh statistics, all in one transaction.

Loading the same 200,000 nodes and 200,000 edges into a fresh SQLite database both ways:

run 1 — importGraph: 6783ms   trustedImportGraphStream: 2455ms
run 2 — importGraph: 7253ms   trustedImportGraphStream: 2206ms
run 3 — importGraph: 5048ms   trustedImportGraphStream: 2116ms

Trusted import was 2.5–3x faster on every run. The streaming form takes a header, then node chunks, then edge chunks, so the loader here reads the LDBC CSVs in two bounded passes instead of holding a multi-million-row graph in memory.

Skipping validation needs a narrow contract. The node and edge tables must be completely empty, and TypeGraph only checks stream order and kind names. Property shapes, endpoints, and duplicate-free IDs are on you. Features whose extra writes it would otherwise skip (history, uniqueness constraints, searchable() and embedding() fields) are rejected outright. Point it at a database with rows in it and it throws before touching anything:

TrustedImportError: Trusted import requires globally empty TypeGraph node and edge tables.
  details: { tables: ["typegraph_nodes", "typegraph_edges"], reason: "database_not_empty" }

For anything that isn’t a one-time load of a fresh, dedicated database, use importGraph (untrusted data, conflicts, history, search fields) or collection bulkInsert (trusted data going into a database that isn’t empty).

Here’s what it did to the benchmark:

Engine	SF1 load	Earlier run	SF10 load
ladybugdb	46s	41.6s	373s
neo4j	66s	71.4s	409s
pggraph	120s	—	1,119s
typegraph-sqlite	164s	587.1s	2,199s
typegraph-postgres	344s	669.3s	3,278s

TypeGraph on SQLite went from 587s to 164s (~3.6x) and on Postgres from 669s to 344s (~1.9x). SQLite is now within about 1.4x of pgGraph, while Postgres is still about 3x slower than pgGraph at both scales, because pgGraph loads through batched INSERTs tuned for its own schema and TypeGraph’s Postgres path still uses prepared statements instead of COPY. Switching to COPY is next, and unlike most of what this benchmark turned up, it would help every Postgres user.

pgGraph as an accelerator

pgGraph is the most interesting result here, less for the rows it wins than for how it works. It indexes tables that already look a lot like the ones TypeGraph’s Postgres backend writes (normalized nodes and edges in Postgres, queryable over the same connection), which is why its point reads look like tuned Postgres while its traversal numbers look like a graph engine’s.

None of this is built yet. The pgGraph driver in this benchmark loads its own copy of the data into its own schema. It doesn’t sit on top of a TypeGraph-managed database. But the numbers suggest the shape of a pairing: use TypeGraph for the point reads and everyday writes it already wins, and when profiling finds a real whole-graph workload (components, centrality, unweighted shortest path at scale), build a pgGraph index over the same tables and send just that query through it. I’m excited about that direction, because it keeps everything in one database without giving up anything on the queries applications run most.

What the slow rows actually mean

It’s tempting to read every slow cell as a TypeGraph bug. Mostly they aren’t:

IC9 is a modeling artifact. LDBC models a message’s creator as an edge, so ranking a feed means fetching a sort key for every candidate first: 1.2M of them at SF1 to return the top 20. A real feed would put the owner on the item and index (owner, created_at), which defineNodeIndex already supports, so the fix belongs in the schema rather than the engine.
The whole-graph algorithms are architectural. Tuning has helped (a delta-frontier rewrite of connected components nearly halved the Postgres GA_WCC time during this work), but it won’t close a 1,000x gap. Pairing with something like pgGraph for those queries is the realistic answer.
IC14 is benchmark-amplified, as above.

And the caveats: one run per scale on a shared-vCPU host, so several cells are noisy and should be read as order-of-magnitude. What I’m confident in regardless: every query passes value-level parity across every engine that runs it, and the direction of every finding is far larger than run-to-run noise.

Try it

The harness: all five engine drivers and the EC2 runner
Full results and investigation notes: sf1-results.md, sf10-results.md
Trusted initial import: the full contract
TypeGraph 0.35: Faster Almost Everywhere: the fixes an earlier run of this benchmark turned up

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Agent Memory That Knows Why It Believes Things

Wed, 22 Jul 2026 00:00:00 GMT

Say a vuln-feed agent in your overnight security pipeline flags 60 services as shipping a vulnerable library, blocks their deploys, opens fix PRs, and pages the owning teams. In the morning someone notices that the feed had a bad package-name mapping, which pinned a real CVE to the wrong package across a whole class of entries. What should happen to those 60 flags?

Deleting all of them is wrong, because some were independently confirmed by a SAST run or an SBOM check and those services really are vulnerable. Leaving them is also wrong, because most were only ever the feed talking, and they’re blocking shipments and paging people for nothing. What you need is the blast radius: which of the 60 flags depend only on the feed, and which have other evidence behind them.

Most agent memory can’t answer that, because “memory” today usually means retrieval: embed everything, fetch the nearest neighbors, and let the model sort it out. That works for recall, but a vector store only keeps what was said. It has no record of why something was concluded, or of what should happen to a conclusion when one of its sources turns out to be wrong. You could live with that when an agent was a single chat transcript, but not once a fleet of agents writes into shared memory and acts on it.

Over the last few releases I built the layer that answers the question: a second temporal axis (0.33), provenance-backed retraction on top of it (0.34), and the hardening that makes both hold up under real load (0.39 and 0.40). I’m really happy with how this one came out.

The blast radius, as a query

With the provenance layer, the support structure is right there in the graph:

VulnFeed ──▶ Vulnerable(svc-14) ──▶ BlockDeploy(svc-14)
SASTRun  ──▶ Vulnerable(svc-14)          two sources, survives

VulnFeed ──▶ Vulnerable(svc-22) ──▶ BlockDeploy(svc-22)
                                         feed only, dies

Retract the feed and Vulnerable(svc-22) loses its only source, so it goes non-current. That takes away the premise of BlockDeploy(svc-22), which goes non-current too, and the deploy unblocks. Vulnerable(svc-14) survives because the SAST run still backs it, so that block stands.

const report = await provenance.retract({
  kind: "VulnFeed",
  id: badMappingSnapshotId,
});

// report.died:
//   flags and deploy blocks that had only the feed behind them
//
// report.survivedVia:
//   flags still confirmed by SAST or the SBOM check

Run that across all 60 services and report is your cleanup list: died tells you which deploys to unblock and which PRs to close, and survivedVia tells you which flags are still real. I wouldn’t trust anyone to work that out by hand at 7am.

The source doesn’t have to be a feed; it can be another agent’s run. If a triage agent combined an overnight feed-ingest run, a SAST scan, and an SBOM rebuild into block-and-page decisions, and the feed-ingest run turns out to have trusted bad data, you retract that run, not the whole fleet’s memory:

const report = await provenance.retract({
  kind: "AgentRun",
  id: overnightFeedRunId,
});

Flags raised only by that run go non-current, while flags another run also supports survive, so one agent’s mistake gets cleaned up without disturbing what the others established.

How retraction works

The @nicia-ai/typegraph/provenance subpath maps your existing graph kinds onto four roles (sources, justifications, facts, and the edges between them) and gives you a retract that recomputes support instead of deleting blindly:

import { createRetractionCapability } from "@nicia-ai/typegraph/provenance";

const provenance = createRetractionCapability(store, {
  source: { kinds: ["ScannerSource", "VendorSource"] },
  justification: { kind: "Justification" },
  fact: { kinds: ["Vulnerability", "DeployDecision"] },
  premiseOf: { kind: "premiseOf" },
  derives: { kind: "derives" },
});

A fact stays believed while at least one of its justifications has all its premises still supported. Premises bottom out at sources. Retract a source and every justification that leaned on it stops counting; a fact loses currency only when it runs out of surviving justifications.

Two properties make this safe to use. Retraction is scoped, touching only facts reachable from the sources that flipped, and it’s reversible: it changes whether a fact is believed without deleting anything, and the fact’s edges stay put, so unRetract is an exact inverse of retract.

None of this is new theory. The storage follows the JTMS shape from Doyle’s 1979 A Truth Maintenance System: AND-justifications over premises, sources as the base case, a fact believed only if some justification has all its premises supported. The question retract answers (which facts keep support after a source drops out) is the ATMS question from de Kleer’s 1986 work, and all of it runs on ordinary SQL. It covers the well-founded, monotonic part of classic truth maintenance rather than all of it. The new part is where it lives: your agent keeps writing ordinary graph data and gets retraction semantics without moving to a dedicated reasoning engine.

Replaying what the agent believed

Retraction is much more useful with history. You want “why did the agent block svc-22 at 2am, and why doesn’t it anymore?” to be a query rather than a dig through logs, and recorded time is what makes that possible.

TypeGraph already had valid time: when a fact was true in the world, set with validFrom / validTo and read with store.asOf(T). 0.33 adds the second axis, recorded time: when TypeGraph captured a fact, what the system knew as of a commit. It’s the SQL:2011 FOR SYSTEM_TIME axis, or Datomic’s system time. Turn it on per store:

const store = createStore(graph, backend, { history: true });

Writes through that store are captured with a per-graph, monotonic commit anchor. store.asOfRecorded(T) gives you a read-only view of the graph as of that anchor, and store.recordedNow() hands you the current one. The two axes compose:

store.asOf(validTime).asOfRecorded(recordedTime);

Retraction is a normal write under history: true, so the whole before and after replays:

const before = await store.recordedNow();

await provenance.retract({
  kind: "VulnFeed",
  id: badMappingSnapshotId,
});

const after = await store.recordedNow();

await store.asOfRecorded(before).nodes.BlockDeploy.getById("svc-22"); // current
await store.asOfRecorded(after).nodes.BlockDeploy.getById("svc-22"); // non-current

One naming note, since it trips up people coming from other systems: TypeGraph’s asOf is valid time, the reverse of SQL:2011’s FOR SYSTEM_TIME AS OF and Datomic’s d/as-of, where a bare “as of” means system time. Valid-time reads are the common case here, so they got the short name.

Why plain SQL, and what it costs

There’s no portable, engine-native system versioning across Postgres and SQLite. Postgres needs an extension or an application-level pattern, and SQLite has nothing. So TypeGraph stores history in its own tables and reconstructs point-in-time views in the query compiler. One implementation runs on both backends, so the same memory model works from a solo agent’s local SQLite file up to a fleet writing into shared Postgres.

That isn’t free:

Only TypeGraph-managed writes are captured. Raw tx.sql is disabled on a history store, since it would bypass capture. This is an audit layer for graph writes, not database-level CDC.
No backfill. Enable history on a fresh graph. An entity that already existed is first recorded the next time it’s written.
Recorded reads are an audit and replay tool, not a hot path. They reconstruct from history, so they’re slower than current-state reads, and broad reads like find, search, and vector predicates aren’t available at a past anchor because those indexes only reflect the present.
Writes cost more. Roughly 2.5–6× an uncaptured write when each write is its own transaction, dropping to about 1–1.5× when writes are batched.

Hardening it: 0.39 and 0.40

Once real consumers started reading this axis, two gaps showed up.

Commits in the same millisecond. 0.33 ordered commits by wall-clock timestamp alone, which breaks exactly when writes get fast. Five back-to-back writes:

commit 0 anchor: r1:0000000000000001:2026-07-21T17:59:03.914Z
commit 1 anchor: r1:0000000000000002:2026-07-21T17:59:03.914Z
commit 2 anchor: r1:0000000000000003:2026-07-21T17:59:03.915Z
commit 3 anchor: r1:0000000000000004:2026-07-21T17:59:03.915Z
commit 4 anchor: r1:0000000000000005:2026-07-21T17:59:03.915Z

Commits 0 and 1 share 17:59:03.914Z. With a timestamp-only anchor, “the graph right after commit 0 but before commit 1” doesn’t have an answer. 0.40 anchors are r1:<revision>:<timestamp>: the revision is a strict per-graph counter, so every commit gets its own position no matter how many share a millisecond. The timestamp is still there for display, and it never moves backwards, even if the system clock does. A raw ISO string no longer type-checks as an anchor, on purpose; get anchors from recordedNow(). Deployments that adopted the earlier format run migrateLegacyRecordedTime() once before opening the upgraded store.

Walking a whole snapshot. 0.39 adds scan() to recorded collections: bounded, deterministic pages (up to 1,000 per call) ordered by id, with a cursor bound to the exact view it came from:

const view = store.asOfRecorded(anchor);
const page1 = await view.nodes.Item.scan({ limit: 2 });
const page2 = await view.nodes.Item.scan({ limit: 2, after: page1.nextCursor });

Together those make “every row as of commit N, in order, one page at a time” a supported operation for a replication tap, an audit export, or a search index rebuild pinned to a point in history.

Why agent memory needs this

A fact stored without provenance is organizational hearsay: the memory can’t tell you why it believes something or what should change when a source goes bad. A single chat agent can get away with that because a lot of inconsistency hides inside one transcript, but agents that share memory will read stale feeds, trust bad mappings, and inherit each other’s wrong assumptions.

Memory that gates deploys, or maintains any long-lived model of a company, needs to answer three questions: what do we believe, why do we believe it, and what changes if this source turns out to be wrong. This layer is built to answer those, and it runs on the SQL database you already have.

Try it

Provenance and Retraction and the Provenance Retraction example
Bitemporal Time Travel example
Logical revision and physical time: the anchor format and diagonal bitemporal reads
Migrating preview recorded time
GitHub

If you’ve mapped JTMS/ATMS-style truth maintenance onto relational storage elsewhere, or know of prior art that does, I’d like to hear about it. There’s plenty written on truth maintenance systems and not much on doing it directly on ordinary SQL tables.

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

The Cheapest Citation Lineage Isn't the Shortest One

Tue, 21 Jul 2026 00:00:00 GMT

When I introduced TypeGraph I said there was no PageRank and no community detection, and that if you needed those you wanted a real graph database. That’s still partly true (more on that at the end), but as of 0.38 the list is a lot shorter.

Until now, store.algorithms answered questions about two nodes at a time, like how to get from A to B or what’s within three hops of A. Some questions need the whole graph at once: whether a dataset is one connected body or several islands, which nodes matter most structurally rather than by raw count, or whether communities emerge from the topology on their own.

Answering those means running an algorithm round after round over the entire graph, from one consistent snapshot, until it converges. That needs more machinery than a single traversal, including a pinned transaction, a temporary working table, and a clear rule for what happens when the rounds don’t settle. 0.37 added weaklyConnectedComponents and weightedShortestPath. 0.38 added global and personalized pageRank and deterministic labelPropagation, the same algorithm the LDBC Graphalytics benchmark uses for community detection. All five run as SQL against the store, so you don’t export the graph to a separate analytics engine and keep a second copy in sync.

They’re also a lot of fun to play with, so the rest of this post runs them on a small citation graph.

The corpus

This is the same citation graph as the research-copilot example: 18 landmark ML papers, 55 authors, 14 topics, and 37 real citation edges, from Rumelhart, Hinton & Williams’ 1986 backprop paper through LLaMA in 2023. That example runs point queries; here I run the whole-graph algorithms over the same data.

const backend = createExampleBackend();
const [store] = await createStoreWithSchema(graph, backend);
// Ingested 18 papers, 55 authors, 14 topics, 37 citation edges.

One body of work, or islands?

Treat cites as undirected and partition by connectivity:

const components = await store.algorithms.weaklyConnectedComponents({
  edges: ["cites"],
  nodeKinds: ["Paper"],
});

18 papers partition into 1 component(s):
  • component of 18 paper(s), rooted at "Adam: A Method for Stochastic Optimization"

Every paper reaches every other through some chain of citations. On a real, messy dataset this is the sanity check to run first. nodeKinds: ["Paper"] keeps authors and topics out of it, so more than one component would mean a separate sub-literature rather than a lightly cited author hanging off the edge.

The cheapest lineage isn’t the shortest one

This is my favorite result in the post, and getting to it took one false start.

Citations always point from a newer paper to an older one, so the obvious edge weight is yearGap, the number of years a citation reaches back. The trouble is that every hop steps strictly backward in time, so the gaps along any route from A to B telescope to exactly A.year - B.year. Every path ties, and weighting by yearGap is just shortestPath with extra arithmetic.

Squaring the gap breaks the tie. yearGapCost = yearGap² is convex, so one 27-year leap costs 27² = 729 while the same span covered in several small steps costs much less. The question becomes “what’s the smoothest chain of ideas between these two papers,” and that’s where weightedShortestPath starts disagreeing with shortestPath:

const hopPath = await store.algorithms.shortestPath(from.id, to.id, {
  edges: ["cites"],
  maxHops: 10,
});
const byConvexCost = await store.algorithms.weightedShortestPath(
  from.id,
  to.id,
  { edges: ["cites"], weightProperty: "yearGapCost" },
);

transformer → backprop:
  shortestPath (fewest hop):   2 hops   transformer(2017) → adam(2014) → backprop(1986)
  weighted by yearGapCost:     4 hops   totalWeight=353   transformer(2017) → dropout(2014) → alexnet(2012) → lenet(1998) → backprop(1986)   ◀── more hops, lower convex cost

clip → backprop:
  shortestPath (fewest hop):   3 hops   clip(2021) → simclr(2020) → dropout(2014) → backprop(1986)
  weighted by yearGapCost:     7 hops   totalWeight=359   clip(2021) → gpt2(2019) → bert(2018) → transformer(2017) → dropout(2014) → alexnet(2012) → lenet(1998) → backprop(1986)   ◀── more hops, lower convex cost

The fewest-hops route from the Transformer paper to backprop makes a 28-year jump through Adam. The convex-cost route takes four smaller steps (Dropout, AlexNet, LeNet) and comes in at less than half the cost. From CLIP it walks seven hops, almost straight down the history of deep learning. Both are legitimate answers to “what’s the best path” between the same two papers, and I like that the convex-cost one reads like a syllabus.

Weights are checked before any traversal round runs, so a negative or non-numeric yearGapCost anywhere in the selected edges throws InvalidEdgeWeightError up front instead of producing a wrong answer.

PageRank vs. counting citations

A citation count tells you how many papers cite this one. PageRank tells you how much a paper matters given who cites it: a citation from an important paper is worth more, and that carries through the graph.

const pageRankScores = await store.algorithms.pageRank({
  edges: ["cites"],
  nodeKinds: ["Paper"],
  direction: "out", // random surfer follows citations forward, toward the classics
});

 PR-rank  score     cites  raw-rank  Δ  title
 ────────────────────────────────────────────────────────────────
     1    0.24209      6       1    ·  Learning representations by back-propagating errors
     2    0.09060      3       7   +5  ImageNet Classification with Deep Convolutional N...
     3    0.07559      3       6   +3  Efficient Estimation of Word Representations in V...
     4    0.07424      4       2   -2  Attention Is All You Need
     5    0.05868      4       3   -2  BERT: Pre-training of Deep Bidirectional Transfor...
     6    0.05827      1      13   +7  Gradient-Based Learning Applied to Document Recog...
     7    0.05818      3       5   -2  Dropout: A Simple Way to Prevent Neural Networks ...
     8    0.05592      3       4   -4  Deep Residual Learning for Image Recognition

Backprop wins both rankings, which is no surprise since it’s the root of the whole corpus. The row I find interesting is 6th place. LeNet has exactly one citation in this corpus, which puts it 13th by count, but PageRank moves it up seven places because that one citation comes from AlexNet, which is heavily cited itself. A plain count would treat it like any other citation.

What matters to CLIP, specifically

Personalized PageRank runs the same iteration, but instead of jumping to a random node it keeps jumping back to a seed you choose. The question changes from “important globally” to “important from where CLIP is standing”:

const personalized = await store.algorithms.personalizedPageRank({
  edges: ["cites"],
  nodeKinds: ["Paper"],
  direction: "out",
  seeds: [{ id: clip.id, kind: "Paper" }],
});

 PPR-rank  score     global-rank  Δ    title
 ──────────────────────────────────────────────────────────────────
      1    0.25884           17  +16  Learning Transferable Visual Models From Natural ...
      2    0.12804            1   -1  Learning representations by back-propagating errors
      3    0.09396            5   +2  BERT: Pre-training of Deep Bidirectional Transfor...
      4    0.07889            4    ·  Attention Is All You Need
      5    0.06382            3   -2  Efficient Estimation of Word Representations in V...
      6    0.05500            9   +3  Language Models are Unsupervised Multitask Learners
      7    0.05500           15   +8  A Simple Framework for Contrastive Learning of Vi...
      8    0.05500           16   +8  An Image is Worth 16x16 Words: Transformers for I...

CLIP itself jumps from 17th to 1st, since every jump lands back on it, and SimCLR and ViT, both cited directly by CLIP and both well outside the global top 10, climb eight places each. Changing only the seed gives you a ranking for a different question, and it’s the one I’d reach for in a “related work” or recommendation feature.

Do research communities fall out?

Label propagation finds communities by having every node adopt the most common label among its neighbors, round after round, over the undirected version of cites. Run it strictly first:

const converged = await store.algorithms.labelPropagation({
  edges: ["cites"],
  nodeKinds: ["Paper"],
  onMaxIterations: "throw", // default
});

onMaxIterations: "throw" raised GraphAlgorithmConvergenceError —
the undirected citation graph oscillates (tree / even-cycle structure
that mirrors labels back and forth).

That error is expected. In synchronous label propagation a node doesn’t vote for itself, so a tree-shaped neighborhood (common once you flatten a citation DAG into an undirected graph) can flip two labelings back and forth forever, and more iterations won’t fix it. The default throws rather than handing you whatever labels the last round happened to land on. If you want that fixed-round answer, which is what the LDBC Graphalytics benchmark specifies, ask for it:

const fixedRound = await store.algorithms.labelPropagation({
  edges: ["cites"],
  nodeKinds: ["Paper"],
  onMaxIterations: "return",
});

3 communities:

── community of 7 ──
   Adam: A Method for Stochastic Optimization            [Optimization]
   Learning representations by back-propagating errors   [Optimization, DeepLearning]
   Dropout: A Simple Way to Prevent Neural Networks ...   [DeepLearning, Optimization]
   Gradient-Based Learning Applied to Document Recog...   [CNN, ComputerVision]
   Sequence to Sequence Learning with Neural Networks     [RNN, NLP, DeepLearning]
   Very Deep Convolutional Networks for Large-Scale ...   [CNN, ComputerVision]
   Efficient Estimation of Word Representations in V...   [Embeddings, NLP]
── community of 7 ──
   BERT: Pre-training of Deep Bidirectional Transfor...   [Transformer, NLP, SelfSupervised]
   Learning Transferable Visual Models From Natural ...   [Contrastive, MultiModal, ComputerVision]
   Chain-of-Thought Prompting Elicits Reasoning in L...   [LanguageModel, Reasoning, NLP]
   Language Models are Unsupervised Multitask Learners    [Transformer, NLP, LanguageModel]
   LLaMA: Open and Efficient Foundation Language Models   [Transformer, LanguageModel, NLP]
   Attention Is All You Need                              [Transformer, Attention, NLP]
   An Image is Worth 16x16 Words: Transformers for I...   [Transformer, ComputerVision, DeepLearning]
── community of 4 ──
   ImageNet Classification with Deep Convolutional N...   [CNN, ComputerVision, DeepLearning]
   Momentum Contrast for Unsupervised Visual Represe...   [Contrastive, SelfSupervised, ComputerVision]
   Deep Residual Learning for Image Recognition           [CNN, ComputerVision, DeepLearning]
   A Simple Framework for Contrastive Learning of Vi...   [Contrastive, SelfSupervised, ComputerVision]

The algorithm only saw undirected cites edges (the topic tags are printed for you and were never fed to it), yet it separated the optimization and classic-vision foundations, the transformer and language-model era, and the contrastive self-supervised vision cluster purely from who cites whom.

What’s still missing

Shortest path (weighted and unweighted), reachability, neighborhoods, degree, connected components, label propagation, and global and personalized PageRank cover a lot of ground, but strongly connected components, topological sort, betweenness/closeness/eigenvector centrality, and Louvain/Leiden community detection aren’t in store.algorithms. For those, pull the edge list out with .query().traverse() or store.subgraph() and hand it to an in-memory library like graphology.

Scale matters too. These run as rounds of SQL, which keeps everything in one database and is fine for graphs the size most applications have, but on millions of edges the engines that hold the graph in a specialized in-memory index are orders of magnitude faster at whole-graph work. The benchmark post has the numbers, including the unflattering ones.

Try it

Graph Algorithms: every algorithm, shared options, temporal behavior, and PageRank tolerance notes across backends
Research Copilot: the same corpus, run through the point-query algorithms
Example 32: the runnable source behind this post
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Turning Two Agents' Event Streams Into One Canonical Graph

Thu, 16 Jul 2026 00:00:00 GMT

Imagine a sales bot and a support bot that both talk to the same person without knowing it. The sales bot knows her as “Jane Doe”, VP Engineering, at jane@acme.com, while the support bot has “J. Doe”, VP Eng, at the same email, along with two companies the sales bot has never heard of, one of which the support bot retracts a day later. Both bots emit durable, at-least-once event streams of what they’ve seen.

Event logs are great at delivery, ordering, and replay, but they don’t resolve entities, and you can’t ask a Kafka topic what an agent believed last Tuesday. That work happens in a layer between the log and whatever reads it, which is what Materializing Event Logs describes. @nicia-ai/agent-stream-graph is the reference implementation, built on 0.35’s store.transactionWithReceipt() and a couple of 0.36 additions. It pulls together three things I’d built separately (bitemporal history, idempotent writes, and graph merge), and seeing them click into one pipeline was a lot of fun.

Projecting events idempotently

Streams redeliver changes after a crash, a reconnect, or a replay, so the second delivery of a change has to land on the same row as the first. In practice that means upsertById for nodes and getOrCreateByEndpoints for edges, and a bare create only when the source event carries its own unique id that you pass through as the TypeGraph id.

const project: Projector<typeof intelGraph> = async (belief, change) => {
  switch (change.shape) {
    case "person": {
      if (change.operation === "delete") {
        await belief.nodes.Person.delete(asNodeId(change.key));
        return;
      }
      await belief.nodes.Person.upsertById(change.key, {
        name: change.value.name,
        email: change.value.email,
        title: change.value.title,
      });
      return;
    }
    case "employment": {
      await belief.edges.worksAt.getOrCreateByEndpoints(
        { kind: "Person", id: change.value.person },
        { kind: "Company", id: change.value.company },
        {},
      );
      return;
    }
  }
};

Resuming after a crash

consume() checkpoints the last processed offset and a recorded-time anchor after every change, and uses store.transactionWithReceipt() to know whether the projector actually wrote anything. The demo runs the sales bot’s stream, stops it after two of its four changes, then simulates the nastiest crash window there is: a change gets projected, and the process dies before the checkpoint lands.

(b) Durable consumer — resume from checkpoint, replay safely after crash

  consumer ran, then crashed after 2 messages
    durable cursor: last offset = 002
    sales-bot belief so far: 1 person, 1 company

  crash window: projected 003, then died before checkpoint
    uncheckpointed anchor existed: 2026-07-14T16:32:30.397Z
    durable cursor is still:       002
    belief already has worksAt edges: 1

  restarted — replayed 003, then processed 004 (2 messages)
    sales-bot belief now: 1 person, 1 company — Jane Doe (VP Eng & Product)
    worksAt edges after replay: 1 (no duplicate edge)

  re-run (at-least-once): 0 messages processed; belief unchanged: 1 person, 1 company

The cursor still says 002 even though 003 was already projected, which is the crash window the demo sets up deliberately. On restart 003 replays, getOrCreateByEndpoints finds the edge it already wrote, and processing carries on. Running the whole stream a third time processes nothing because the cursor is already at the end.

Rebuilding from offset zero

A full rebuild is a different case: replay every event from the beginning into a fresh belief graph, for recovery or a schema migration. Before 0.36, that rewrote every row even when the replayed value matched what was already there, so each rebuild cost a wasted write per event and grew recorded history by the length of the log.

createStore(graph, backend, { coalesceUnchangedUpserts: true }) makes a value-identical redelivery a true no-op that writes nothing, adds no history row, and doesn’t advance the revision. A stream that actually changes a value and later changes it back still writes both times, since those changes really happened. 0.36 also adds tx.measure(), which scopes a receipt to the writes made by one callback, so a materializer’s own cursor bookkeeping in the same transaction can’t be mistaken for projector output.

What did each bot believe, and when?

Each bot’s belief graph has history enabled, so book.anchorFor(stream, offset) gives you a recorded-time coordinate for any processed offset. That means you can read exactly what this bot believed at that point in its own stream:

(c) What did each agent believe, at which offset?

  sales-bot's own belief graph:
    @offset 001: people: Jane Doe (VP Engineering) | companies: —
    @offset 004: people: Jane Doe (VP Eng & Product) | companies: Acme Corp (Series A)  (title corrected)

  support-bot's own belief graph (same person, different surface form):
    @offset 004: people: J. Doe (VP Eng) | companies: Umbrella (unverified), Acme (Series B), Globex (Series C)
    @offset 005: people: J. Doe (VP Eng) | companies: Acme (Series B), Globex (Series C)  (Umbrella retracted)

  → Same email, but neither agent alone knows 'Jane Doe' and 'J. Doe'
    are one person. The retracted company also remains visible in past belief.

The support bot’s belief at offset 4 still shows “Umbrella (unverified)”, even though it was deleted at offset 5, because a read at a past offset reconstructs the belief as it was then.

One canonical graph

Each bot’s belief exports through streaming interchange into a graph merge branch, and mergeIncremental() folds it into a canonical graph. It’s the same entity resolution as in the graph merge post, run once per stream as it arrives:

await importGraphStream(
  agentBranch.store,
  exportGraphStream(belief, { includeTemporal: true }),
  { onConflict: "update" },
);

const result = await mergeIncremental({
  forkPoint,
  target: canonical,
  branches: [agentBranch],
  options: {
    resolve: {
      Person: {
        similarity: { kind: "fulltext", fields: ["name"] },
        threshold: 0.9,
      },
      Company: {
        similarity: { kind: "fulltext", fields: ["name"] },
        threshold: 0.9,
      },
    },
    onPropertyConflict: "flag",
    onBasePropertyConflict: "flag",
    branchOrder: [branchId],
    persistProvenance: true,
  },
});

The sales bot merges first, as a clean append. The support bot merges second, and that’s where the same-person, different-spelling problem gets resolved:

[wave 1] merged sales-bot  — conflicts: 0
[wave 2] merged support-bot — conflicts: 4
  conflict: Company.name on c1: support-bot="Acme"; kept "Acme Corp"
  conflict: Company.stage on c1: support-bot="Series B"; kept "Series A"
  conflict: Person.name on p1: support-bot="J. Doe"; kept "Jane Doe"
  conflict: Person.title on p1: support-bot="VP Eng"; kept "VP Eng & Product"

canonical now: 1 person, 2 companies — Jane Doe (VP Eng & Product)
  provenance — sales-bot contributed to 3 canonical entities
  provenance — support-bot contributed to 3 canonical entities

“Jane Doe” and “J. Doe” collapse into one canonical person, and every disagreement is flagged instead of silently overwritten. Globex, which only the support bot ever saw, joins as a new company. Umbrella, which the support bot retracted before the merge, never shows up at all. And the canonical graph has history too, so it time-travels across merge waves:

canonical, time-travelled:
  asOfRecorded(after wave 1): 1 person, 1 company
  asOfRecorded(after wave 2): 1 person, 2 companies

So from two unreliable streams you end up with one canonical graph, and you can still ask any of the three graphs what it believed at any point along the way.

A bigger example

The demo above is small on purpose: one person, two bots, five offsets. The repo’s main demo (pnpm demo) runs the same mechanics against a set of wiki entries that mention overlapping concepts under different names, and converges them into one canonical concept graph with source attribution for every mention.

Try it

Materializing Event Logs: idempotent projectors, cursor bookkeeping, transaction receipts, and mapping event time onto the two temporal axes
Graph Merge: the entity resolution this builds on
agent-stream-graph: pnpm demo and pnpm demo:mechanics
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

TypeGraph 0.35: Faster Almost Everywhere

Wed, 15 Jul 2026 00:00:00 GMT

A 2M-row bulk load into SQLite was still running after 4.5 hours with no sign of finishing, and the cause turned out to be a statistics refresh. After a large batch, bulkCreate and bulkInsert automatically run SQLite’s ANALYZE so the query planner has fresh numbers, but that ANALYZE was bare and unscoped: it scanned every table in the database file (not just TypeGraph’s), with no limit, after every big batch. If you stream a load through repeated bulkInsert() calls, each refresh costs more than the last and the total goes quadratic.

It’s now scoped to TypeGraph’s own tables and bounded with PRAGMA analysis_limit, the way the Postgres version already behaved. A 100k-row reproduction of the same shape finishes in about 8 seconds, and the last batch costs only about twice what the first one did.

0.35 has about 35 fixes like that one, and below are the ones that matter most, with numbers.

Bulk writes

These four changes stack on top of each other for anything that writes a lot of rows:

SQLite pragmas at open. createLocalSqliteBackend now turns on journal_mode=WAL, synchronous=NORMAL, and a busy timeout by default. better-sqlite3’s own defaults pay a full fsync per write in rollback-journal mode. Single-operation writes on file-backed databases are roughly 5x faster.
Real bind-parameter limits. The backend used to assume SQLite’s old 999-parameter limit on every driver. It now asks the driver (32,766 for better-sqlite3, 100 for Cloudflare D1), so batches on better-sqlite3 use ~33x fewer statements: 111-row chunks became 3,640-row chunks.
bulkCreate / bulkInsert batched end to end. Existence checks, uniqueness checks, and fulltext/embedding writes each happen once per batch instead of once per row: ~1,600 → ~4,100 rows/s (~2.6x).
importGraph batched the same way: ~26k → ~96k entities/s (~4x). The default batchSize also went from 100 to 1,000, and now actually applies. A schema-parsing gap meant the old default was silently ignored. That change alone took a 20k-node, 5k-edge Postgres import from 1,515ms to 781ms.

There’s also a new walAutocheckpointPages option for tuning WAL checkpoints during heavy loads. On its own it cut a 2M-row load’s time by more than half at the largest scale tested.

The regression, and fixing it properly

This one’s on me. 0.34 fixed a real correctness bug where “current” reads compared against the database’s clock instead of the application’s, so when the two clocks drifted (app and database on separate hosts, which is normal), a row you’d just created could be invisible to the very next read. The fix was to bind the read instant fresh every time a query compiled, which was correct but had two problems I didn’t catch until this release.

It was slow. Every execute() recompiled the query from scratch, including the .prepare()-once, .execute()-many pattern that exists specifically to avoid that. A repeated point query cost about 47µs.

It was also, briefly, worse than the bug it fixed. The query builders cached their compiled SQL text across calls, so a prepared query froze “now” at the moment it first compiled. Every row created after that had a later valid_from than the frozen instant, and stayed invisible to that query forever. It reproduced in a single process on the very next insert after preparing a query, whereas the clock-skew bug at least needed two hosts.

0.35 fixes both the same way: the SQL text is cached, and only the “now” instant is re-bound as a parameter on each call. The repeated point query went from 47µs to 2.4µs (~20x), and a row created after .prepare() shows up on the next .execute().

I’m not going to bury that in a changelog line. If you’re on 0.34 and use .prepare(), upgrade.

Point operations and traversals

CRUD statements reuse the prepared-statement cache. On synchronous drivers, Drizzle’s db.all() / db.run() re-prepared every statement. They now go through the same cached path the query engine uses. Single creates: ~18.3k → ~28.8k ops/s (~1.6x).
Cascade deletes remove edges in batches instead of one statement per edge. A 50-edge cascade on local Postgres: 24.4ms → 3.6ms.
degree() can use the index again. The direction filter compiled to a shape neither edge index could seek. Now it matches the index prefix: 0.30ms → 0.06ms on Postgres 18, and on Postgres 17 and earlier it no longer falls back to scanning the whole partition.
Subgraph extraction is ~4x faster on Postgres (322ms → 82ms on a depth-3 stress shape). The recursive traversal runs once instead of twice, and the resulting ids go in as a single array parameter.

Search

Hybrid search is one SQL statement instead of two searches plus fusion in JavaScript, with the candidate filter computed once and shared. Filtered hybrid search at 5k documents: 26.5ms → 17.1ms.
Postgres fulltext can use its GIN index. The query referenced the language from a per-row column, which kept the planner off the index. It’s now a constant: 12.9ms → 2.3ms at 5,000 documents.
Exact .similarTo() on SQLite uses sqlite-vec’s KNN. It’s brute force in C, so results are identical, just faster: 489ms → 124ms for top-10 over 50k 384-dimension embeddings.
Approximate vector search on Postgres uses the ANN index now. A stray DISTINCT kept the planner off the ordered index scan, and the inline path wasn’t applying the same pgvector tuning as the search API. Together: 174ms → 2.1ms, at 0.995 recall.

That last area also had a correctness bug. Exact .similarTo() was quietly approximate whenever a matching ANN index existed, because pgvector will happily answer an exact-looking ORDER BY ... LIMIT k from an HNSW or IVFFlat index. Under a selective filter at 50k documents, measured recall dropped as low as 0.000, which means the results were simply wrong. The exact path now forces a true scan regardless of which indexes exist.

Found by benchmarking against real graph databases

Two of these fixes came from running the LDBC Social Network Benchmark against Neo4j and LadybugDB, not from profiling TypeGraph on its own. Edge bulkCreate / bulkInsert had an N+1 endpoint check that made each batch slower as the graph grew (~90ms → ~630ms per batch). And the default edge traversal indexes were missing columns a join needed to stay index-only, which didn’t show up until the table outgrew the page cache and then hit a multi-second latency cliff. The full benchmark writeup covers where TypeGraph wins and where it doesn’t.

If you’re upgrading an existing database, note that the wider edge indexes only appear on fresh databases. CREATE INDEX IF NOT EXISTS does nothing when an index with that name exists, even with a different column list, so an upgraded deployment keeps the narrow index until you rebuild it. Performance → Indexes has the exact DROP / CREATE INDEX CONCURRENTLY steps for both backends.

Also in 0.35

.aggregate({...}).orderBy(key, direction?), so “top N groups by count” no longer means fetching every group and sorting in JavaScript.
Breaking, ontology: implies(edgeA, edgeB) now checks that the two edges’ endpoint kinds are compatible. This also runs when a persisted schema loads, so check saved schemas before rolling out, not just source.

Try it

Performance overview and Indexes
Changelog: the full 0.35.0 entry
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Merging Two Feeds That Disagree About the Same Patient

Tue, 09 Jun 2026 00:00:00 GMT

Point two ingestion agents at overlapping data (an EHR export and a claims feed, say) and tell them to “just write everything to the graph”, and you end up with two patient nodes for one person, each holding half the care history and neither aware of the other. Most pipelines then add a nightly dedupe job and hope nothing reads the graph in between.

I think append is the wrong default for graphs, which is why 0.31 ships @nicia-ai/typegraph/graph-merge. It’s the feature I’ve been most eager to get into people’s hands. You branch a store, let each writer work on its own copy, and then fold the branches back in: entities are resolved, edges are repointed onto the surviving nodes, disagreements are reported instead of silently overwritten, and the merge records who contributed what.

Branch, write, merge

branch() records the base store’s current state and hands back an isolated working copy. Writers use the ordinary store API against it. merge() diffs every branch against the base and runs one pipeline to fold them back in:

stage (diff every branch)
  → generate candidates (exact unique · blocking key · similarity)
    → cluster (group nodes that are the same entity)
      → canonicalize (pick a survivor, union properties, resolve conflicts)
        → repoint + dedupe edges onto survivors
          → reconcile delete/modify and types
            → commit transactionally + build the report

The whole thing is deterministic: clusters resolve by stable keys and conflicts are decided by an explicit branchOrder rather than by which branch happened to arrive first, so merging the same branches in any order commits the same graph.

Two ways to be the same patient

Example 18 runs this on a small FHIR-flavored care graph. An EHR branch and a claims branch each record the same two patients, and each gets both identities wrong in a different way:

Anna Rivera (EHR) and Ana Rivera (claims) share MRN-001, and because mrn is declared unique, they’re matched regardless of how the name is spelled, without any similarity threshold.
Mohammed Ali (EHR, MRN-204) and Mohamed Ali (claims, MRN-205) have different MRNs, so nothing forces them together. They share a birth date, which puts them in the same blocking bucket, and they collapse because their fulltext name similarity clears the configured 0.78 threshold.

Landing in the same bucket only means two records get compared. The test suite also covers the other side of the threshold with Zoe Adams and Quinn Webb, who share a birth date and land in the same bucket but score near zero on name similarity, so they stay two separate patients.

const mergeOptions: MergeOptions<CareGraph> = {
  resolve: {
    Patient: {
      block: (node) => node.birthDate,
      similarity: { kind: "fulltext", fields: ["name"] },
      threshold: 0.78,
    },
  },
  onPropertyConflict: "flag",
  branchOrder: [EHR_BRANCH, CLAIMS_BRANCH],
  provenance: true,
};

const result = await merge(base, [ehr, claims], mergeOptions);

Both pairs collapse to one canonical patient each:

merged nodes: 9
merged edges: 10
entity resolutions: 2

That’s six nodes staged on the EHR branch plus five on claims, minus the two patients that folded into their counterparts, and all ten edges survive without duplicates.

Disagreements get flagged, not hidden

Merge doesn’t quietly pick a value when branches disagree. The properties that don’t agree are flagged, and the flags also show which identity mechanism was in play:

conflicts:
  - Patient.fhirId on patient-ana: claims-agent="Patient/claims-ana", ehr-agent="Patient/ehr-anna"
  - Patient.name on patient-ana: claims-agent="Ana Rivera", ehr-agent="Anna Rivera"
  - Patient.fhirId on patient-mohamed: claims-agent="Patient/claims-mohamed", ehr-agent="Patient/ehr-mohammed"
  - Patient.mrn on patient-mohamed: claims-agent="MRN-205", ehr-agent="MRN-204"
  - Patient.name on patient-mohamed: claims-agent="Mohamed Ali", ehr-agent="Mohammed Ali"

There’s no mrn conflict for patient-ana, because Anna and Ana share MRN-001 exactly. The Mohammed/Mohamed pair does flag mrn, since their merge was based on name similarity and never required the MRNs to agree.

Every edge lands on the survivor

This is the part I like best: everything attached to either duplicate ends up on the one canonical patient. Here it is read back through each survivor’s forPatient edges rather than a table scan:

Ana Rivera (MRN-001, 1974-03-09)
  - Encounter: Hypertension follow-up (2026-04-11T09:30:00-07:00)
  - Encounter: Kidney function review (2026-04-14T10:00:00-07:00)
  - MedicationRequest: Lisinopril 10 MG Oral Tablet - Take one tablet by mouth daily
  - Observation: Blood pressure panel = 152/96 mmHg (high)
  - Observation: Estimated glomerular filtration rate = 54 mL/min/1.73m2 (low)
Mohamed Ali (MRN-205, 1990-08-21)
  - Encounter: Cardiology consult (2026-05-02T13:00:00-07:00)
  - Observation: LDL cholesterol = 168 mg/dL (high)

Ana Rivera’s five resources came from both branches (the EHR encounter and medication, the claims encounter and lab result), and they now hang off a single patient node that neither branch created on its own, so anyone reading this record sees the full history. If an edge had been repointed wrongly, it would be missing from the list.

Who contributed what

With provenance: true, the merge reports which branch contributed each committed node and edge:

provenance:
  - ehr-agent: 6 node(s), 6 edge(s)
  - claims-agent: 5 node(s), 4 edge(s)

That report lives only as long as the call. Pass persistProvenance: true and each contribution is also written as a durable {branch, sourceId} → canonical row in a separate provenance graph on the same backend, so “what did this provider ever contribute?” is a query you can run next month, without adding anything to your domain schema.

Merging into a graph that kept moving

merge() is a snapshot operation: every branch must fork from the target’s current state, or it fails with BaseVersionMismatchError rather than risk clobbering newer data. That works when you fork, write, and merge in one round, but real ingestion keeps going, and Example 19 covers folding new batches into a target that has already moved on.

In that example a company knowledge base already has Acme Corp (acme.com), and a provider batch reports the same company under another spelling along with one company that’s new:

Target before: [ 'Acme Corp (acme.com)' ]
Target after:  [ 'Acme Corp (acme.com)', 'Globex (globex.io)' ]

No duplicate was created: the provider's "ACME Corporation" merged onto the
committed "Acme Corp" via the shared domain.

mergeIncremental() finds the already-committed row by its unique domain and merges onto it instead of creating a duplicate. It’s the same mechanism as the shared-MRN case, matched against live data instead of another branch:

const result = await mergeIncremental({
  forkPoint, // the frozen ancestor the branch forked from
  target, // the live committed graph, which may have advanced
  branches: [provider],
  options: {
    resolve: {
      Company: {
        similarity: { kind: "fulltext", fields: ["name"] },
        threshold: 0.9,
      },
    },
    onPropertyConflict: "flag",
    onBasePropertyConflict: "flag", // required: never let a stale branch value win
    persistProvenance: true,
  },
});

onBasePropertyConflict: "flag" is required so that a stale branch can’t overwrite something newer than the point it forked from. If the live target changed the same row after the fork, the target’s value wins and the disagreement is reported.

Try it

Graph Merge: entity resolution, blocking, similarity strategies, conflicts, scaling guards, and determinism
FHIR Graph Merge and Incremental Graph Merge: the docs walkthroughs
Example 18 and Example 19: the runnable source behind this post
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

An Agent That Grows Its Own Schema

Tue, 12 May 2026 00:00:00 GMT

If you follow a clinical trial through the literature, you see it registered first, then published as a paper, and occasionally, years later, retracted. A retraction notice is a kind of record that wasn’t in anyone’s schema when the trial was registered, and usually wasn’t there when the paper was indexed either.

TypeGraph’s schema normally lives in code: you declare defineNode and defineEdge in TypeScript, you get full type inference, and adding a new kind of thing means a code change and a deploy. I think that’s the right default and I’m keeping it, but it doesn’t fit an ingestion pipeline pulling from an API you don’t control, a multi-tenant app where each tenant brings its own shape, or an agent that discovers a new kind of record halfway through a corpus.

0.25 adds graph extensions for those cases. A schema change can be proposed at runtime, validated as strictly as the compile-time path, and committed atomically without a redeploy.

Proposing a change

An extension is a plain JSON document (new node and edge kinds, their property types, unique constraints, indexes) built with defineGraphExtension and committed with store.evolve():

const proposal = defineGraphExtension({
  nodes: {
    Paper: {
      properties: {
        title: { type: "string", minLength: 1 },
        doi: { type: "string", minLength: 1 },
        year: { type: "number", int: true, min: 1900, max: 2100 },
      },
      unique: [{ name: "paper_doi_unique", fields: ["doi"] }],
    },
  },
});

const evolved = await store.evolve(proposal);

The type vocabulary is small on purpose: strings, numbers, booleans, enums, and one level of array/object nesting. An LLM-written schema stays readable, and it can’t smuggle in a Zod refinement or a function. A malformed proposal throws GraphExtensionValidationError with per-field issues before anything touches the database. The commit is checked against the active schema version, so two writers racing to extend the same graph get a StaleVersionError to retry on, not a silent overwrite.

Reads get the same care. TypeScript can’t see a kind that didn’t exist at compile time, so runtime kinds go through string-keyed versions of the query builder, which check kind names against the live schema:

const rows = await store
  .query()
  .fromDynamic("Paper", "p")
  .traverseDynamic("authoredBy", "a")
  .toDynamic("Author", "u")
  .select((ctx) => ({ paper: ctx.p, author: ctx.u }))
  .execute();

A typo in a kind name throws KindNotFoundError, where a schemaless store would quietly return zero rows and leave you to find out later.

Letting an agent drive

A toy example is fine for the API, but I wanted to know whether the loop holds up against messy, real, multi-stage data. So I built typegraph-clinical-demo: the same machinery end to end, over real trial registrations from ClinicalTrials.gov, their publications from PubMed, and retractions and corrections from CrossRef. It’s all public bibliographic metadata, with no patient data.

An LLM agent watches the corpus arrive in three stages and proposes an extension after each one. The proposals are blind: the agent sees sample records and the names of kinds already in the graph, and I didn’t give it any hints about types, searchable fields, or which identifier should be unique. Property types, optionality, searchability, and constraints are all inferred from the samples.

Stage 1, registration. The agent sees about 1,100 ClinicalTrials.gov records and proposes ClinicalTrial.
Stage 2, publication. PubMed records referencing those trials arrive, and the agent proposes Publication with a referencesTrial edge back to stage 1.
Stage 3, retraction. Retraction notices and corrections arrive. Nobody designs for these up front, because most trials never get one. The agent proposes PublicationEvent with a correctsPublication edge back to stage 2.

Each stage is a real store.evolve() against a real store, followed by a bulk ingest under the new schema.

When the proposal is valid but wrong

Validation catches malformed proposals, but it can’t catch one that’s internally consistent and still wrong for the data, like a field the agent marked required because the three samples it saw all happened to have it. So after each accepted proposal the demo runs a smoke test: ingest the full sample into a scratch store seeded with every earlier extension. Failures go back to the agent in the same structured {path, code, message} form validation uses.

Stage 3 is where it fires, on a real run:

STAGE 3: post-publication discourse
  agent  attempt=1
  validator  ACCEPTED  +nodes=[PublicationEvent]  +edges=[correctsPublication]
  smoke test  FAILED  2 issue(s) — proposal validates but doesn't fit the data:
    [INGEST_INVALID_TYPE] artifactDoi: expected string, received undefined
    [INGEST_INVALID_TYPE] date: expected string, received undefined
  agent  attempt=2
  validator  ACCEPTED  +nodes=[PublicationEvent]  +edges=[correctsPublication]
  smoke test  PASSED  schema fits the sample
  PublicationEvent nodes: 922/922 ingested  (0 skipped)

The first proposal saw three samples, all correction events with artifactDoi and date filled in, and made both required. The full-sample ingest hit comment events without them and failed. On attempt 2 the agent made both optional, the smoke test passed, and the graph committed. The whole stage, repair included, takes about 16 seconds and one extra model call.

I love watching this loop work. Nobody explained the mistake to the model in prose; it got the same machine-readable errors a developer would have seen and fixed its own schema. Because the smoke test runs against a scratch store, a failed attempt leaves no stray rows or half-claimed unique keys for the next attempt to trip over. Only a proposal that survives gets committed to the real store.

The payoff

After stage 3 the graph has three kinds and two edges that didn’t exist when the demo started, and one query walks all of them:

const rows = await store
  .query()
  .fromDynamic("PublicationEvent", "event")
  .traverseDynamic("correctsPublication", "correction")
  .toDynamic("Publication", "pub")
  .traverseDynamic("referencesTrial", "reference")
  .toDynamic("ClinicalTrial", "trial")
  .select((ctx) => ({
    event: ctx.event,
    publication: ctx.pub,
    trial: ctx.trial,
  }))
  .execute();

On the real corpus it surfaces four documented retraction chains, including SCIPIO (cardiac stem cells, Lancet 2011, retracted 2019) and a 2018 nilotinib trial outcome, plus three more the corpus turned up on its own: the Anil Potti genomic-predictor case and the Mehra et al. hydroxychloroquine retraction that halted multiple registered trials in 2020 among them. Getting there took no migrations, just three store.evolve() calls and a query written against kind names that were plain strings until the agent defined them.

You don’t need a frontier model for this

The demo includes an eval harness (pnpm eval) that runs the same blind three-stage pipeline across a lineup of models and scores whether each first proposal survives validation and the smoke test. The cheapest model that cleared all three stages on the first try was a 26B-parameter open-weight MoE with 4B active parameters. It came in 4x cheaper than Gemini 3.1 Flash Lite (which also went three for three) and 5x cheaper than GPT 5.4 nano (which needed one repair).

The full three-stage run, repair included, takes under 30 seconds and costs about $0.003 in API calls. The loop needs a structured error channel and a model that can read a JSON Schema error and try again, and when the schema layer does its job, a small model handles that fine.

Try it

Graph Extensions: the full reference
Agent-Driven Schema: a minimal, in-repo version of the same loop
pdlug/typegraph-clinical-demo: clone it, pnpm demo, and watch the schema grow
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Embeddings Can't Find a SKU

Thu, 30 Apr 2026 00:00:00 GMT

Type PROD-1005-E into a search box and you expect one result: the product with that SKU. Vector search is bad at this in a way tuning won’t fix: a rare alphanumeric code barely moves an embedding, so cosine similarity ranks on everything else in the query, and the product whose exact code you typed ends up under a pile of vaguely similar ones.

BM25 handles it easily, because it counts terms and a token that appears in exactly one document wins however odd it looks. Rather than trying to make embeddings better at exact matches, I wanted both signals fused in one place, so 0.21 added native fulltext search and hybrid retrieval that combines it with vector search, and 0.24 finished the job on SQLite.

Fulltext is a field modifier

Mark a field searchable() and TypeGraph keeps a BM25 index in sync on every write. On Postgres that’s tsvector + GIN; on SQLite it’s FTS5. You don’t need an Elasticsearch cluster for this, or a sync job to feed one.

const Product = defineNode("Product", {
  schema: z.object({
    name: searchable({ language: "english" }),
    description: searchable({ language: "english" }),
    sku: searchable({ language: "english" }),
    category: z.enum(["outerwear", "footwear", "accessories", "climbing"]),
    embedding: embedding(16).optional(),
  }),
});

Query it with store.search.fulltext(), or use $fulltext.matches() as a predicate inside an ordinary query, where it combines with metadata filters and traversals in the same SQL statement:

const activeOuterwear = await store
  .query()
  .from("Product", "p")
  .whereNode("p", (p) =>
    p.$fulltext
      .matches("lightweight", 10)
      .and(p.status.eq("active"))
      .and(p.category.eq("outerwear")),
  )
  .select((ctx) => ({ sku: ctx.p.sku, name: ctx.p.name }))
  .execute();

Hybrid, fused with RRF

store.search.hybrid() runs the vector search and the fulltext search and merges them with Reciprocal Rank Fusion. RRF only looks at rank positions, so it doesn’t care that a cosine score and a BM25 score live on completely different scales, which makes it the least fiddly fusion method I know of.

const hybridHits = await store.search.hybrid("Product", {
  limit: 5,
  vector: { fieldPath: "embedding", queryEmbedding, metric: "cosine", k: 20 },
  fulltext: { query: "waterproof shell", k: 20, includeSnippets: true },
  fusion: { method: "rrf", k: 60, weights: { vector: 1, fulltext: 1.25 } },
});

Fulltext worked on both backends from 0.21, but hybrid needs the backend to run a vector search, which SQLite couldn’t do yet, so on SQLite the hybrid call threw ConfigurationError. 0.24 gives SQLite a real vector search on top of sqlite-vec, built to the same shape as the Postgres version, and the hybrid call now takes the same options and returns the same results on both.

SQLite also turned out to be the faster of the two. On the project’s search benchmark (500 documents, 384 dimensions), SQLite hybrid runs in 0.8ms against Postgres’s 2.5ms, partly because SQLite runs in-process and doesn’t pay for a round trip.

Running it

Example 15 seeds nine outdoor-gear products (parkas, shells, a climbing harness, ski goggles), each with a searchable name, description, and SKU, plus a small embedding. A BM25 query for "waterproof jacket" finds the Expedition Parka, and the snippet shows why:

Heavily insulated <mark>jacket</mark> for alpine expeditions and extreme
cold. <mark>Waterproof</mark> outer shell with down fill.

Then the SKU:

Query: "PROD-1005-E" (looking up an exact SKU)
   1. [PROD-1005-E] Climbing Harness Pro     score=1.6328

It comes back as the only result, where a pure vector search on that string ranks unrelated products higher because the SKU barely registers in the embedding.

Hybrid is where it gets interesting. Here’s "waterproof shell" with k=20 on each side, RRF k=60, and fulltext weighted at 1.25:

   1. [PROD-1001-A] Expedition Parka         score=0.0357 (v#3, f#3)
   2. [PROD-1002-B] Arctic Shell             score=0.0356 (v#6, f#1)
   3. [PROD-9901-Z] Legacy Rain Shell        score=0.0355 (v#5, f#2)
   4. [PROD-1007-G] Compression Socks        score=0.0164 (v#1, f—)
   5. [PROD-1008-H] Hiking Daypack 25L       score=0.0161 (v#2, f—)

The (v#, f#) tags are each hit’s rank on each side. Arctic Shell was fulltext’s top pick but only sixth by vector, so pure vector search would have buried it, and RRF lifts it to second because doing well on either side counts. Compression Socks went the other way: they were the vector side’s top hit, but with no fulltext match at all they end up at the bottom of the list.

It composes with everything else

The same fusion is on the query builder as .fuseWith(), so a hybrid search can carry ordinary predicates. Filtering to status = "active" drops the discontinued Legacy Rain Shell in the same query, without a post-filter:

const builderHybrid = await store
  .query()
  .from("Product", "p")
  .whereNode("p", (p) =>
    p.$fulltext
      .matches("waterproof shell", 20)
      .and(p.embedding.similarTo(queryEmbedding, 20))
      .and(p.status.eq("active")),
  )
  .fuseWith({ k: 60, weights: { vector: 1, fulltext: 1.25 } })
  .select((ctx) => ({ sku: ctx.p.sku, name: ctx.p.name }))
  .limit(5)
  .execute();

// → Arctic Shell, Expedition Parka, Hiking Daypack 25L, Ski Goggles UV400,
//   Compression Socks

There are four query modes for what a search box actually receives: websearch for Google-style syntax ("ski goggles" -compression), phrase for exact adjacency, plain for all-terms-must-match, and raw when you want the engine’s native tsquery or FTS5 MATCH syntax.

And if the index falls behind (you added a searchable() field, or a bulk write went around the store), store.search.rebuildFulltext() backfills it page by page:

Before rebuild: "waterproof" → 0 hits (fulltext rows cleared).
Rebuilt: kinds=Product processed=9 upserted=9 cleared=0 skipped=0
After rebuild: "waterproof" → 3 hits restored.

Try it

Fulltext Search: RRF tuning, adding fulltext to existing data, and alternate Postgres strategies (pg_trgm, ParadeDB, pgroonga)
Semantic Search: the vector half
Example 15: the runnable source behind this post
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

Introducing TypeGraph

Sat, 21 Feb 2026 00:00:00 GMT

Every project I’ve worked on that needed real structure (a knowledge base, an org chart, memory for an agent) ended up with the same stack: an ORM for the actual data, a vector store added when someone wanted semantic search, and eventually, once the relationships got interesting, a graph database off to the side with a sync job keeping it roughly in line with the other two.

Each of those systems has its own idea of what a Person is and its own consistency model, so the schema drifts between them. Meanwhile TypeScript already has Zod, a schema language good enough to describe all of it, and none of those systems treats it as the source of truth.

TypeGraph is the other option: keep the graph inside the application, as a library, and store it in the database you already run.

It runs in your process

TypeGraph writes through your existing SQLite or Postgres connection and commits in the same transaction as the rest of your data. You don’t deploy a graph server or keep one running, and your app doesn’t make a network hop to reach its own graph.

One schema

You describe your data once, in Zod:

const Person = defineNode("Person", {
  schema: z.object({ name: z.string(), role: z.string() }),
});

const worksOn = defineEdge("worksOn", {
  schema: z.object({ since: z.string() }),
});

const graph = defineGraph({
  id: "org",
  nodes: { Person: { type: Person } },
  edges: { worksOn: { type: worksOn, from: [Person], to: [Person] } },
});

From that one definition TypeGraph derives runtime validation, the TypeScript types, the storage layout, and what the query builder will let you write. If you’ve ever kept an ORM schema, a folder of hand-written interfaces, and a Cypher cheat sheet in sync by hand, you know why I wanted this.

Relationships that mean something

A foreign key tells you two rows are related, but it can’t tell you that a Podcast is a kind of Media, that marriedTo implies knows, or that a Person and an Organization can never be the same thing. In most codebases those rules live in a comment, or in the head of whoever wrote the migration.

In TypeGraph, edges are first-class and typed, and they carry their own properties. The ontology layer (subClassOf, implies, disjointWith, equivalentTo) does real work: a query for Media can include podcasts, a knows traversal can pick up spouses, and a write that would make a person and an organization share an identity fails. Traversals compile to SQL, so a three-hop walk is one query rather than a loop of lookups.

Vectors are just another field

Embeddings are a field type. When you declare one, TypeGraph stores and indexes it on whichever backend you’re running:

const Document = defineNode("Document", {
  schema: z.object({ title: z.string(), embedding: embedding(1536) }),
});

const similar = await store
  .query()
  .from("Document", "d")
  .whereNode("d", (d) => d.embedding.similarTo(queryVector, 10))
  .select((ctx) => ctx.d)
  .execute();

.similarTo() is a predicate like any other, so it composes with filters and traversals in the same query. You don’t ask a vector database for a list of IDs and then run a second query to find out what those IDs are.

What it isn’t

TypeGraph isn’t trying to be Neo4j. There’s no PageRank, no community detection, no distributed storage, and at this stage no traversal algorithms beyond the queries you write yourself. It’s built for thousands to millions of nodes living next to the rest of your data. If your graph is the product and it has billions of edges, you want a dedicated graph database.

Where it stands

It’s early, a handful of releases in. The DSL, the ontology layer, vector search, and both backends are solid. What comes next depends on what people build with it, so if you try it and hit a wall, open an issue.

Try it

What is TypeGraph? and the Quick Start
Ontology & Reasoning: subClassOf, implies, disjointWith, equivalentTo
Semantic Search
GitHub

Stay in the loop

Occasional updates on new features, guides, and releases. No spam.

TypeGraph | Blog

Look Before You Write

What’s in the graph

What no longer fits

Fix a row without racing anyone

Review a batch before it lands

One consistent snapshot

Limits

Upgrading

Try it

Stay in the loop

Merges That Wait

The review lives in the graph

A working copy that outlives its process

The message that arrives twice

Limits

Try it

Stay in the loop

Schema Changes That Roll Back With Everything Else

Plan outside, apply inside

No-ops, and schema-only checkpoints

Merges and reviewed writes that bring their own kinds

Limits

Try it

Stay in the loop

Replacing the N+1 Loop With One Statement

Step one: reads that say what they want

Step two: batchOnce()

It won’t quietly fall back

Step three: shape it in SQL

The rest of the set-shaped toolkit

What one statement doesn’t buy you

Try it

Stay in the loop

Tracking Which Records Are the Same Person

Folding on a shared id

Saying it explicitly

Changing your mind

A backstop in the database

Traversals that understand it

Staging the duplicate you came to resolve

What it costs

Try it

Stay in the loop

Bring Your Own Database

Drizzle is an adapter now

Drizzle is now an optional dependency

Backends say what they can’t do

How your engine keeps writers apart

Engine profiles

One error for “you lost the race”

Branches your host can copy

What isn’t there yet

Upgrading

Try it

Stay in the loop

Letting an Edge's Targets Depend on Its Source

Say which source gets which targets

Narrowing, never widening

Bulk writes are all or nothing

Pairs are stored in the schema

Try it

Stay in the loop

One Round Trip Per Write

Checks and write, in one statement

Batches on drivers without transactions

0.53: the writes that have to look first

Letting the database decide: match identities

Upgrading

Try it

Stay in the loop

Five Bugs That Didn't Crash

Rows that exist at no point in time

Upgrading doesn’t repair old rows, on purpose

Constraints that importGraph walked straight past

A search index that said it was fine

A migration that deleted your runtime kinds

An implies() that folded nonsense rows

What they have in common

Try it

Step two: `batchOnce()`

Constraints that `importGraph` walked straight past

An `implies()` that folded nonsense rows

`authz`: a graph per workspace

`notes`: a graph per user

`agent-memory`: a graph per conversation