feat(documents): contract parties, roles, optional parties and dual roles

[QSchlegel]

Replaces the closed #385, after both open questions came back maximal: one human may hold two roles, and optional / non-signing parties are a launch requirement.

They turn out to be the same change — both need the capacity in the signed bytes — so doing them together costs far less than either alone.

No SIGNOFF_DOMAIN bump, contrary to what I told you

partyId is an optional payload field, and canonicalize filters undefined keys. So a threshold signature produces bytes byte-identical to before this field existed, and every proof already issued keeps verifying. A domain bump is only needed to rename or re-mean a field, not to add one.

Proven by a test: threshold bytes contain no partyId, and partyId: null canonicalizes identically to omitting it.

It has to be in the signed bytes rather than beside them. A contract's claim is "the Buyer signed as Buyer", and once one human can hold two roles, two signatures from one address are otherwise indistinguishable. The verifier binds it, so a relabelled capacity fails verification instead of quietly re-attributing a signature.

A party-aware outcome rule

evaluateThreshold counts approvals anonymously, which cannot decide a contract: an optional Witness in the snapshot lets one be Approved over a required party's explicit rejection, and leaving the Witness out denies them at submission instead.

evaluateContractOutcome decides on which parties acted — every required party approved, any required party rejected, optional parties recorded and never counted. A test asserts the two rules genuinely diverge on identical facts.

It also refuses to decide a party set with nothing required: "every required party approved" is vacuously true over an empty set, and approving a contract nobody had to sign is the worst possible default.

The cost of dual roles, paid explicitly

Allowing one address two capacities means dropping DocumentReview_versionId_signerAddress_key. That would silently weaken threshold mode, where one signer acting twice is still wrong and the in-transaction check reads rows fetched before the write.

A partial unique index restores exactly the old guarantee exactly where it still applies (WHERE "partyId" IS NULL). Prisma can't express a WHERE on @@unique, so it's raw SQL, with a note on how migrations are generated here and why that keeps it safe.

Verified against a throwaway Postgres

check	result
one human on two parties with one address	allowed
that human signs one version twice, once per capacity	allowed
twice as the same party	refused
threshold mode, one signer twice	still refused
RLS on both new tables	on, in this migration

1174 unit tests, 85 integration tests, tsc clean, next build exit 0.

Still required before parties mode works

Unchanged from #385, and none of it is here: the access layer (a named party cannot reach any document procedure today), the startReview parties branch, the ordering gate and row lock in submitSignerAction, and rendering ContractField values into the body before hashing.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
multisig	Ready	Preview	Aug 23, 2026 6:34pm