Declarative residency policy so threads without application code shard correctly #980

Follow-up to #975 (dedicated replication worker pool), under #435. Proposal, not a committed design: the questions at the end decide the shape.

Problem

Residency rules are JavaScript functions an application installs per thread: Table.setResidency(record => …) and Table.setResidencyById(id => …) (core resources/Table.ts, the setResidency/setResidencyById statics). A thread that does not run the application's code has neither function. Two kinds of thread now run without application code:

• Replication pool workers (replication.threads > 0, Run replication on a dedicated worker pool (replication.threads) #975). The sender skips residency invalidations to non-resident peers only when table.getResidencyById is installed (replication/replicationConnection.ts, the table.getResidencyById test in the audit-send loop). On a pool worker it never is. An application that shards by id with setResidencyById therefore sends invalidation entries with indexed-field stubs (residency partials) to every non-resident peer, which stores them, where today it sends nothing. Run replication on a dedicated worker pool (replication.threads) #975 accepts this for 5.4 and documents "keep replication.threads: 0 if you use setResidencyById".
• The main thread (likely already today, unverified). Application plugins run handleApplication only on workers (components/componentLoader.ts, resources.isWorker && extensionModule.handleApplication), and operations-API writes execute on the main thread. If that holds, an upsert through the operations API computes no residency at all. verify: with an app that calls setResidency, then an upsert operation, then inspect the record's residencyId.

The root cause is that residency is a placement policy that every node and every thread must agree on, but it is defined as thread-local code. Residency lists themselves are already storage-backed: the writer stores a residencyId (dbis residency_by_id) and the list travels with the audit record, so receivers never re-evaluate it. Only the policy that produces it is thread-local.

Proposal

Make the common residency policies declarative table metadata, persisted with the table the way replicate already is (core resources/databases.ts, primaryAttribute.replicate), so every thread that opens the table materializes the same getResidency/getResidencyById without loading application code.

type Order @table @residency(byId: { shards: 8 }) {
	id: ID @primaryKey
	region: String
}

type Customer @table @residency(byAttribute: "region", shards: { us: 1, eu: 2 }, default: 1) {
	id: ID @primaryKey
	region: String
}

• byId: { shards: N } is hash sharding: shard = hash(encodedPrimaryKey) % N, mapped to nodes by the existing replication.shard membership (server.shards, replication/knownNodes.ts). It is installed as getResidencyById, so it drives all three places that function drives today: the sender's skip, full omission on write (no residency partial), and the read fast path that routes a miss to a resident node.
• byAttribute maps an attribute value to a shard and is installed as getResidency. Moving a record between shards uses the existing relocation path (_recordRelocate).
• Shard membership stays in config (replication.shard per node, replication.databases[].sharded), as it is now. Only the policy moves into table metadata, because the policy must be identical on every node while membership is per node.
• One source per table. A table with declarative residency refuses setResidency/setResidencyById from application code (a clear error at the call), so the function and the metadata cannot diverge between threads. A table without it keeps the function API unchanged.
• The hash is part of the storage format. It must be fixed and documented (for example FNV-1a 32-bit over the ordered-binary key encoding), never "whatever the runtime's hash is", since changing it relocates every record.

Alternatives

Where the code changes

• core resources/Table.ts: build getResidency/getResidencyById from table metadata at table open; refuse the function API on a declarative table.
• core resources/databases.ts + schema directive parsing: persist and replicate the residency metadata (same path as replicate).
• harper-pro replication/replicationConnection.ts: no change once getResidencyById exists on every thread.

Open questions

1. Schema directive only, or also a set_table_residency operation for tables defined without a schema?
2. Changing shards on an existing table: refuse, or define it as a relocation migration?
3. Is the main-thread gap real today (see verify: above)? If so it is a bug on its own, independent of the pool.

Size: real work (core schema + metadata + Table, small harper-pro follow-through). Not blocking #975, which ships with the documented limitation.

_{🤖 Generated by Claude (Opus 5.5); posted via @kriszyp.}