@substrat-run/engine-protocol 0.3.6 → 0.4.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { dataSubjectId, entityRef, moduleManifest, permissionKey, } from '@substrat-run/contracts';
+import { dataSubjectId, entityRef, instant, moduleManifest, permissionKey, principalId, } from '@substrat-run/contracts';
 import { assertAllowed, ulid, } from '@substrat-run/kernel';
 // ============================================================================
 // The protocol engine (docs/design/engine-protocol.md, extracted at milestone
@@ -9,25 +9,88 @@ import { assertAllowed, ulid, } from '@substrat-run/kernel';
 // invariants; template CONTENT (which protocols exist, what they contain)
 // is 100% vertical-owned:
 //
-//   1. sign freezes     — any write to a signed instance's responses fails
-//   2. content_hash     — SHA-256 over template content + latest responses at
-//                         sign time; verifiable against replayed state
-//   3. counter-sign     — an ADDITIONAL signature row on the same frozen
-//                         content (hash re-verified, never new content);
-//                         exactly one primary signature per instance
-//   4. append-only      — a response edit is a NEW row; history is audit
-//                         material ("4.2 → 5.1 before signing")
-//   5. version-pinned   — templates version immutably; an instance pins
-//                         (key, version) at instantiation forever
-//   6. void, not delete — a protocol is superseded, never mutated or removed
+//   1. freeze freezes    — any write to a frozen instance's content fails
+//   2. content_hash      — SHA-256 over template content + the frozen content;
+//                          verifiable against replayed state
+//   3. counter-sign      — an ADDITIONAL signature row on the same frozen
+//                          content (hash re-verified, never new content)
+//   4. append-only       — a response edit is a NEW row; history is audit
+//                          material ("4.2 → 5.1 before signing")
+//   5. version-pinned    — templates version immutably; an instance pins
+//                          (key, version) at instantiation forever
+//   6. void, not delete  — a protocol is superseded, never mutated or removed
 //
 // Entity-agnostic: an instance binds to any EntityRef ('workorder' today,
 // anything tomorrow). The vertical declares the `protocol → <parent>` entity
 // relation in ITS manifest — the engine cannot know the vertical's vocabulary.
+//
+// ---------------------------------------------------------------------------
+// TWO CONTENT KINDS (milestone D). The engine's attestation half — hash,
+// freeze, signatures, the guards — was always content-agnostic; only `fill`
+// and the template shape were checklist-specific. That seam is now exposed:
+//
+//   kind: 'checklist' — sections/items, filled response-by-response. The
+//     original shape; templates that predate this carry no `kind` and parse as
+//     checklist, and their stored content_json is NEVER rewritten (the hash
+//     covers it verbatim — a migration that touched it would invalidate every
+//     signature ever made).
+//
+//   kind: 'document' — content the ENGINE NEVER SEES. A priced avtal, a
+//     styrelserapport, a PDF: the vertical owns the rows and computes their
+//     hash, and binds (contentRef, contentHash) to the instance. The engine
+//     attests that a signature was made over exactly that hash at that time,
+//     and says so honestly rather than pretending its recipe covered content
+//     it never read. Recomputation is the VERTICAL's obligation — the engine
+//     cannot verify what it cannot see, and claiming otherwise would be the
+//     false audit trail a degenerate one-item checklist produces.
+//
+// ---------------------------------------------------------------------------
+// FREEZE IS SEPARATE FROM SIGNING (milestone D). Signing used to freeze as a
+// side effect, which was sound only because `signProtocol` is synchronous:
+// the authenticated principal taps sign and the window between "what we showed
+// them" and "what we hashed" is microseconds.
+//
+// An external signing flow (BankID via Scrive) is not synchronous, and the
+// signatory is not a principal at all:
+//
+//   we dispatch a signing request  →  days pass  →  a customer signatory with
+//   no account in the system signs  →  a webhook reports party X signed at
+//   time T with evidence Y
+//
+// With freeze welded to signing, that instance stays `open` — and therefore
+// writable — for the entire days-long window, so the document the customer
+// saw and the content the hash is computed over can differ with no detection.
+// That is a hole in the freeze invariant for ANY asynchronous signature,
+// checklist or document alike.
+//
+// So freezing is now its own transition, and the missing noun is the
+// SIGNATURE REQUEST:
+//
+//   open  --requestSignatures-->  pending_signature  --all resolved-->  signed
+//     \                                  |
+//      \--signProtocol (in-app)----------+-------------------------->  signed
+//                                        |
+//                          cancelSignatureRequests --> open (renegotiate)
+//
+// `pending_signature` is frozen: no fill, no rebind. The requests table also
+// makes MULTI-PARTY expressible — "every requested party has signed" is
+// `requireAllSigned`, which primary/counter alone could never say.
+//
+// What the engine deliberately does NOT do: talk to Scrive. Module code makes
+// no network calls (boundary-lint R3). `requestSignatures` emits a fat
+// `protocol.signatures-requested`; a connector/executor outside the scope
+// effects it. The return path — webhook ingress and an inbound authority seam
+// that lets a callback invoke `recordSignature` — does not exist in the kernel
+// yet (see the issues filed alongside this change). `recordSignature` is
+// shaped to be callable by that ingress when it lands, and is permissioned as
+// its own key so nothing else can reach it in the meantime.
 // ============================================================================
 export const PROTOCOL_PERM = {
     create: permissionKey.parse('protocol:create'),
     fill: permissionKey.parse('protocol:fill'),
+    bind: permissionKey.parse('protocol:bind'),
+    requestSignature: permissionKey.parse('protocol:request-signature'),
+    recordSignature: permissionKey.parse('protocol:record-signature'),
     sign: permissionKey.parse('protocol:sign'),
     countersign: permissionKey.parse('protocol:countersign'),
     read: permissionKey.parse('protocol:read'),
@@ -35,20 +98,27 @@ export const PROTOCOL_PERM = {
 };
 export const protocolManifest = moduleManifest.parse({
     id: '@substrat-run/engine-protocol',
-    version: '0.0.1',
+    version: '0.0.2',
     kernelContract: '^0.0.1',
     permissions: [
         { key: 'protocol:create', description: 'Define protocol templates and start protocol instances on entities' },
-        { key: 'protocol:fill', description: 'Record responses on an open protocol (append-only)' },
-        { key: 'protocol:sign', description: 'Sign a protocol — freezes it forever (separate from fill: the technician fills, the arbetsledare signs)' },
+        { key: 'protocol:fill', description: 'Record responses on an open checklist protocol (append-only)' },
+        { key: 'protocol:bind', description: 'Bind vertical-owned document content (ref + hash) to an open document protocol' },
+        { key: 'protocol:request-signature', description: 'Freeze a protocol and request signatures from named parties (external signing flows); also cancels a pending request set' },
+        { key: 'protocol:record-signature', description: 'Record a signature reported by an external signing provider — held by connector ingress, never by a human role' },
+        { key: 'protocol:sign', description: 'Sign a protocol in-app — freezes it forever (separate from fill: the technician fills, the arbetsledare signs)' },
         { key: 'protocol:countersign', description: 'Counter-sign an already-signed protocol — a second signature on the same frozen content (customer at pickup)' },
-        { key: 'protocol:read', description: 'Read protocol templates, instances, responses and signatures' },
+        { key: 'protocol:read', description: 'Read protocol templates, instances, responses, signature requests and signatures' },
         { key: 'protocol:void', description: 'Void (supersede) a protocol — never deletes' },
     ],
     events: {
         emits: [
             { type: 'protocol.instantiated', schemaVersion: 1 },
             { type: 'protocol.response-recorded', schemaVersion: 1 },
+            { type: 'protocol.content-bound', schemaVersion: 1 },
+            { type: 'protocol.signatures-requested', schemaVersion: 1 },
+            { type: 'protocol.signature-declined', schemaVersion: 1 },
+            { type: 'protocol.signatures-cancelled', schemaVersion: 1 },
             { type: 'protocol.signed', schemaVersion: 1 },
             { type: 'protocol.countersigned', schemaVersion: 1 },
             { type: 'protocol.voided', schemaVersion: 1 },
@@ -109,12 +179,143 @@ export const protocolMigrations = [
       );
     `,
     },
+    // 0002 — MILESTONE D. Asynchronous, non-principal signatures and the
+    // document content kind. Three shape changes:
+    //
+    //   1. `protocol_instances.status` gains 'pending_signature'. SQLite cannot
+    //      ALTER a CHECK constraint, so this is the standard table rebuild.
+    //   2. `protocol_instances` gains the frozen hash and the document binding.
+    //      `frozen_hash` is BACKFILLED from each instance's earliest signature,
+    //      so already-signed instances carry the hash they were frozen at.
+    //   3. `protocol_signature_requests` — the new noun.
+    //
+    // The rebuild covers all three data tables rather than just `instances`,
+    // because `responses`/`signatures` carry `REFERENCES protocol_instances(id)`
+    // clauses: renaming out from under them leaves those clauses pointing at a
+    // dropped table. The FK clauses are dropped rather than re-pointed —
+    // neither adapter enables `PRAGMA foreign_keys` (and DO SQLite restricts
+    // PRAGMA entirely), so they were never enforced; the engine is the only
+    // writer and enforces the relationships in code.
+    //
+    // `protocol_templates` is untouched, and NO stored `content_json` is
+    // rewritten: the content hash covers that string verbatim, so adding an
+    // explicit `"kind":"checklist"` would invalidate every signature ever made.
+    // Legacy content parses as checklist by normalisation at read time instead.
+    //
+    // Column names and order are preserved for every pre-existing column so that
+    // Callout's `0003-protocols-to-engine` extraction handoff — which INSERTs
+    // into these tables by explicit column list and runs after this migration —
+    // keeps working untouched.
+    {
+        version: '0002-signature-requests',
+        sql: `
+      CREATE TABLE protocol_instances_v2 (
+        id               TEXT PRIMARY KEY,
+        template_key     TEXT NOT NULL,
+        template_version INTEGER NOT NULL,
+        entity_type      TEXT NOT NULL,
+        entity_id        TEXT NOT NULL,
+        status           TEXT NOT NULL
+                         CHECK (status IN ('open','pending_signature','signed','voided')),
+        created_by       TEXT NOT NULL,
+        created_at       TEXT NOT NULL,
+        voided_by        TEXT,
+        voided_reason    TEXT,
+        voided_at        TEXT,
+        content_ref_type TEXT,
+        content_ref_id   TEXT,
+        bound_hash       TEXT,
+        frozen_hash      TEXT,
+        frozen_at        TEXT
+      );
+      INSERT INTO protocol_instances_v2
+        (id, template_key, template_version, entity_type, entity_id, status,
+         created_by, created_at, voided_by, voided_reason, voided_at,
+         content_ref_type, content_ref_id, bound_hash, frozen_hash, frozen_at)
+        SELECT i.id, i.template_key, i.template_version, i.entity_type, i.entity_id, i.status,
+               i.created_by, i.created_at, i.voided_by, i.voided_reason, i.voided_at,
+               NULL, NULL, NULL,
+               (SELECT s.content_hash FROM protocol_signatures s
+                 WHERE s.instance_id = i.id ORDER BY s.rowid LIMIT 1),
+               (SELECT s.signed_at FROM protocol_signatures s
+                 WHERE s.instance_id = i.id ORDER BY s.rowid LIMIT 1)
+        FROM protocol_instances i;
+
+      CREATE TABLE protocol_responses_v2 (
+        id           TEXT PRIMARY KEY,
+        instance_id  TEXT NOT NULL,
+        item_key     TEXT NOT NULL,
+        value_json   TEXT NOT NULL,
+        note         TEXT,
+        responded_by TEXT NOT NULL,
+        responded_at TEXT NOT NULL
+      );
+      INSERT INTO protocol_responses_v2
+        (id, instance_id, item_key, value_json, note, responded_by, responded_at)
+        SELECT id, instance_id, item_key, value_json, note, responded_by, responded_at
+        FROM protocol_responses;
+
+      CREATE TABLE protocol_signatures_v2 (
+        id              TEXT PRIMARY KEY,
+        instance_id     TEXT NOT NULL,
+        signed_by       TEXT NOT NULL,
+        kind            TEXT NOT NULL CHECK (kind IN ('primary','counter')),
+        method          TEXT NOT NULL,
+        content_hash    TEXT NOT NULL,
+        evidence_ref    TEXT,
+        signed_at       TEXT NOT NULL,
+        request_id      TEXT,
+        signatory_kind  TEXT NOT NULL DEFAULT 'principal'
+                        CHECK (signatory_kind IN ('principal','external')),
+        signatory_label TEXT
+      );
+      INSERT INTO protocol_signatures_v2
+        (id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at,
+         request_id, signatory_kind, signatory_label)
+        SELECT id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at,
+               NULL, 'principal', NULL
+        FROM protocol_signatures;
+
+      DROP TABLE protocol_signatures;
+      DROP TABLE protocol_responses;
+      DROP TABLE protocol_instances;
+      ALTER TABLE protocol_instances_v2 RENAME TO protocol_instances;
+      ALTER TABLE protocol_responses_v2 RENAME TO protocol_responses;
+      ALTER TABLE protocol_signatures_v2 RENAME TO protocol_signatures;
+
+      CREATE TABLE protocol_signature_requests (
+        id            TEXT PRIMARY KEY,
+        instance_id   TEXT NOT NULL,
+        party_label   TEXT NOT NULL,
+        party_kind    TEXT NOT NULL CHECK (party_kind IN ('principal','external')),
+        party_ref     TEXT,
+        signature_kind TEXT NOT NULL CHECK (signature_kind IN ('primary','counter')),
+        method        TEXT NOT NULL,
+        status        TEXT NOT NULL
+                      CHECK (status IN ('pending','signed','declined','expired','cancelled')),
+        content_hash  TEXT NOT NULL,
+        external_ref  TEXT,
+        resolved_note TEXT,
+        requested_by  TEXT NOT NULL,
+        requested_at  TEXT NOT NULL,
+        resolved_at   TEXT
+      );
+      CREATE INDEX protocol_signature_requests_by_instance
+        ON protocol_signature_requests (instance_id, status);
+      CREATE INDEX protocol_instances_by_entity
+        ON protocol_instances (entity_type, entity_id, template_key, status);
+    `,
+    },
 ];
 // ---------------------------------------------------------------------------
 // Template content SHAPE — engine-owned so fills can be validated against the
 // pinned template. The content VALUES (sections, items, vocabulary,
-// branschprotokoll packs) are written by verticals. v0 item types:
-// check | value (measurement, decimal string) | text.
+// branschprotokoll packs) are written by verticals.
+//
+// Two kinds, discriminated on `kind`. Content stored before the discriminant
+// existed carries no `kind` and is normalised to 'checklist' at PARSE time
+// only — never rewritten in the database, because the hash covers the stored
+// string byte-for-byte.
 // ---------------------------------------------------------------------------
 export const protocolItem = z.object({
     key: z.string().min(1),
@@ -122,13 +323,78 @@ export const protocolItem = z.object({
     type: z.enum(['check', 'value', 'text']),
     unit: z.string().optional(), // 'MΩ' on measurements
 });
-export const protocolTemplateContent = z.object({
+/** The original shape: sections of items, filled response-by-response. */
+export const checklistContent = z.object({
+    kind: z.literal('checklist'),
     sections: z
         .array(z.object({ title: z.string().min(1), items: z.array(protocolItem).min(1) }))
         .min(1),
 });
+/**
+ * Content the engine never sees. The template says what KIND of document this
+ * is and how to render it; the instance carries the vertical's `EntityRef` and
+ * the hash the vertical computed over its own rows.
+ *
+ * `hashRecipe` is free text, and it is the load-bearing honesty of this kind:
+ * a document signature attests to a hash the engine did not compute, so the
+ * recipe for reproducing it must be written down where an auditor reading the
+ * template finds it. The engine cannot enforce that the text is true — but a
+ * signature over an unreproducible hash is worth nothing, and a required field
+ * is what makes the vertical say out loud how to reproduce it.
+ */
+export const documentContent = z.object({
+    kind: z.literal('document'),
+    /** Vertical vocabulary for what this is — 'avtal', 'styrelserapport'. */
+    documentType: z.string().min(1),
+    /** How to recompute `boundHash` from the vertical's own rows. */
+    hashRecipe: z.string().min(1),
+    description: z.string().optional(),
+});
+const contentUnion = z.discriminatedUnion('kind', [checklistContent, documentContent]);
+/**
+ * Parses either kind, defaulting a missing discriminant to 'checklist' so
+ * every template defined before milestone D still parses. Note this is a
+ * READ-time normalisation: `defineTemplate` stores what it is given after
+ * parsing, so new templates carry an explicit `kind`, and old rows keep their
+ * bytes (and therefore their hashes) exactly as signed.
+ */
+export const protocolTemplateContent = z.preprocess((value) => value && typeof value === 'object' && !Array.isArray(value) && !('kind' in value)
+    ? { ...value, kind: 'checklist' }
+    : value, contentUnion);
 /** Booleans for checks; strings for measurements/text (decimals stay strings, K-14). */
 const responseValue = z.union([z.boolean(), z.string()]);
+/**
+ * Who signed. Two kinds, and the difference is the whole point of milestone D:
+ *
+ * - `principal` — an authenticated principal in this scope. `ref` is their
+ *   `PrincipalId`. Every in-app signature.
+ * - `external` — a human with no account, identified by an external provider
+ *   (BankID via Scrive). `ref` is an OPAQUE `DataSubjectId` the vertical minted
+ *   for that person.
+ *
+ * A personnummer, an email or a name must NEVER land in `ref`. It is `direct`
+ * PII, and `subjectId` on the emitted event is what crypto-shredding keys the
+ * erasure on (§5.3) — a `DataSubjectId` is shreddable, a personnummer written
+ * into a signature row is a GDPR liability that immutability makes permanent.
+ * The provider's own party identifier belongs in `evidenceRef`, which is where
+ * the sealed PDF and the provider audit log are reachable from.
+ *
+ * This follows `engines/booking`'s `partyRef`: a participant is a person with
+ * no principal, and it names them with a `DataSubjectId` for exactly this
+ * reason.
+ */
+export const signatory = z.discriminatedUnion('kind', [
+    z.object({
+        kind: z.literal('principal'),
+        ref: principalId,
+        label: z.string().min(1).optional(),
+    }),
+    z.object({
+        kind: z.literal('external'),
+        ref: dataSubjectId,
+        label: z.string().min(1).optional(),
+    }),
+]);
 const protocolRef = (id) => ({ entityType: 'protocol', entityId: id });
 function getInstanceRow(ctx, instanceId) {
     const row = ctx.sql.query('SELECT * FROM protocol_instances WHERE id = ?', [instanceId])[0];
@@ -142,6 +408,7 @@ function getTemplateRow(ctx, key, version) {
         throw new Error(`protocol template not found: ${key}@${version}`);
     return row;
 }
+const templateContentOf = (template) => protocolTemplateContent.parse(JSON.parse(template.content_json));
 /** Append order is authoritative for "latest wins" — rowid, not ULID (same-ms safe). */
 function getResponseRows(ctx, instanceId) {
     return ctx.sql.query('SELECT * FROM protocol_responses WHERE instance_id = ? ORDER BY rowid', [instanceId]);
@@ -149,6 +416,9 @@ function getResponseRows(ctx, instanceId) {
 function getSignatureRows(ctx, instanceId) {
     return ctx.sql.query('SELECT * FROM protocol_signatures WHERE instance_id = ? ORDER BY rowid', [instanceId]);
 }
+function getRequestRows(ctx, instanceId) {
+    return ctx.sql.query('SELECT * FROM protocol_signature_requests WHERE instance_id = ? ORDER BY rowid', [instanceId]);
+}
 function latestPerItem(responses) {
     const latest = {};
     for (const r of responses)
@@ -156,17 +426,53 @@ function latestPerItem(responses) {
     return latest;
 }
 const frozenAnswers = (latest) => Object.fromEntries(Object.entries(latest).map(([k, r]) => [k, JSON.parse(r.value_json)]));
-export async function protocolContentHash(template, latest) {
+const signatoryOf = (row) => ({
+    kind: row.signatory_kind,
+    ref: row.signed_by,
+    ...(row.signatory_label ? { label: row.signatory_label } : {}),
+});
+async function sha256Hex(input) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+export async function protocolContentHash(template, latest, boundHash) {
+    const head = `${template.key}@${template.version}\n${template.content_json}\n`;
+    if (boundHash)
+        return sha256Hex(`${head}document:${boundHash}\n`);
     const lines = Object.keys(latest)
         .sort()
         .map((k) => `${k}=${latest[k].value_json}\n`)
         .join('');
-    const input = `${template.key}@${template.version}\n${template.content_json}\n${lines}`;
-    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(input));
-    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+    return sha256Hex(`${head}${lines}`);
+}
+/** The hash an instance's content currently produces, whatever kind it is. */
+async function currentHash(ctx, instance) {
+    const template = getTemplateRow(ctx, instance.template_key, instance.template_version);
+    const content = templateContentOf(template);
+    if (content.kind === 'document') {
+        if (!instance.bound_hash) {
+            throw new Error(`document protocol ${instance.id} has no bound content — bind it before freezing`);
+        }
+        return protocolContentHash(template, {}, instance.bound_hash);
+    }
+    return protocolContentHash(template, latestPerItem(getResponseRows(ctx, instance.id)));
+}
+/**
+ * Re-derive the frozen hash and refuse if it moved. Fail closed: a signature
+ * binds to VERIFIED frozen content, never to a trusted column.
+ */
+async function verifyFrozen(ctx, instance) {
+    if (!instance.frozen_hash) {
+        throw new Error(`protocol ${instance.id} is not frozen: nothing to sign against`);
+    }
+    const replayed = await currentHash(ctx, instance);
+    if (replayed !== instance.frozen_hash) {
+        throw new Error(`content hash mismatch: frozen ${instance.frozen_hash}, replayed ${replayed}`);
+    }
+    return instance.frozen_hash;
 }
 // ---------------------------------------------------------------------------
-// THE GUARD (engine-protocol.md §6, kernel-design open question 11). ONE
+// THE GUARDS (engine-protocol.md §6, kernel-design open question 11). One
 // predicate body, TWO ways to reach it — that is the whole open question:
 //
 //  pole 1 — VERTICAL-COMPOSED (milestone A): the vertical calls requireSigned()
@@ -197,7 +503,7 @@ export function requireSigned(ctx, entity, templateKey) {
 }
 /**
  * The stronger form: signed AND counter-signed — the frozen content was
- * ACCEPTED by a second principal (the customer at pickup). Invariant 3 already
+ * ACCEPTED by a second signatory (the customer at pickup). Invariant 3 already
  * guarantees a counter-signature can only exist on verified frozen content, so
  * the existence of the row is the whole check.
  */
@@ -213,6 +519,14 @@ export function requireCountersigned(ctx, entity, templateKey) {
             `(${entity.entityType} ${entity.entityId})`);
     }
 }
+/**
+ * NOTE on multi-party: there is deliberately no `requireAllSigned`. In the
+ * request-driven path an instance reaches `signed` only once EVERY requested
+ * party has signed (see `recordSignature`), so "all parties signed" IS
+ * `requireSigned` — a separate guard would read as though it checked something
+ * stronger while checking the same thing. The multi-party question is answered
+ * by the state machine, not by a second predicate.
+ */
 /**
  * Config for the `protocol/all-signed` predicate — parsed by the PREDICATE, not
  * by the kernel (the kernel keeps `config` opaque). `entityIdFrom` names the
@@ -224,7 +538,7 @@ export const allSignedGuardConfig = z.object({
     templateKey: z.string().min(1), // vertical content: 'tillstandsrapport'
     entityType: z.string().min(1), // what the protocol hangs on: 'workorder'
     entityIdFrom: z.string().min(1), // input field holding the id: 'orderId'
-    countersigned: z.boolean().default(false), // require the customer's acceptance too
+    countersigned: z.boolean().default(false), // require a second signatory's acceptance too
 });
 /** The named predicate the kernel resolves for `predicate: 'protocol/all-signed'`. */
 export const allSignedPredicate = (ctx, rawConfig, input) => {
@@ -284,8 +598,11 @@ export function instantiateProtocol(ctx, rawInput) {
     const template = ctx.sql.query('SELECT * FROM protocol_templates WHERE key = ? ORDER BY version DESC LIMIT 1', [input.templateKey])[0];
     if (!template)
         throw new Error(`protocol template not found: ${input.templateKey}`);
+    // An instance being signed is still "in play": a second one would race the
+    // first for the same (template, entity) slot.
     const dup = ctx.sql.query(`SELECT id FROM protocol_instances
-     WHERE entity_type = ? AND entity_id = ? AND template_key = ? AND status = 'open' LIMIT 1`, [input.entity.entityType, input.entity.entityId, input.templateKey])[0];
+     WHERE entity_type = ? AND entity_id = ? AND template_key = ?
+       AND status IN ('open','pending_signature') LIMIT 1`, [input.entity.entityType, input.entity.entityId, input.templateKey])[0];
     if (dup) {
         throw new Error(`protocol '${input.templateKey}' already open on this ${input.entity.entityType}`);
     }
@@ -314,11 +631,23 @@ export function instantiateProtocol(ctx, rawInput) {
             templateKey: template.key,
             templateVersion: template.version,
             title: template.title,
+            contentKind: templateContentOf(template).kind,
             entity: input.entity,
         },
     });
     return getInstanceRow(ctx, id);
 }
+/** The one place that decides whether content may still change. */
+function assertUnfrozen(instance, what) {
+    if (instance.status === 'open')
+        return;
+    if (instance.status === 'pending_signature') {
+        throw new Error(`protocol is out for signature: content is frozen until the requests resolve ` +
+            `or are cancelled (instance ${instance.id})`);
+    }
+    throw new Error(`protocol is ${instance.status}: content is frozen, ${what} can no longer change ` +
+        `(append-only history kept)`);
+}
 export const fillProtocolInput = z.object({
     instanceId: z.string().min(1),
     itemKey: z.string().min(1),
@@ -328,12 +657,14 @@ export const fillProtocolInput = z.object({
 export function fillProtocol(ctx, rawInput) {
     const input = fillProtocolInput.parse(rawInput);
     const instance = getInstanceRow(ctx, input.instanceId);
-    // Invariant 1+4: responses bind to an OPEN instance only, and always append.
-    if (instance.status !== 'open') {
-        throw new Error(`protocol is ${instance.status}: responses are frozen (append-only history kept)`);
-    }
+    // Invariant 1+4: responses bind to an UNFROZEN instance only, and always append.
+    assertUnfrozen(instance, 'responses');
     const template = getTemplateRow(ctx, instance.template_key, instance.template_version);
-    const content = protocolTemplateContent.parse(JSON.parse(template.content_json));
+    const content = templateContentOf(template);
+    if (content.kind !== 'checklist') {
+        throw new Error(`template ${instance.template_key}@${instance.template_version} is a '${content.kind}' ` +
+            `protocol: it carries no items — bind its content instead of filling it`);
+    }
     const item = content.sections.flatMap((s) => s.items).find((i) => i.key === input.itemKey);
     if (!item) {
         throw new Error(`unknown item '${input.itemKey}' in template ${instance.template_key}@${instance.template_version}`);
@@ -374,55 +705,455 @@ export function fillProtocol(ctx, rawInput) {
         id,
     ])[0];
 }
+export const bindDocumentInput = z.object({
+    instanceId: z.string().min(1),
+    /** The vertical entity that holds the real content — an avtal, a report. */
+    contentRef: entityRef,
+    /** The hash the VERTICAL computed over its own rows, per `hashRecipe`. */
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/, 'contentHash must be lowercase hex SHA-256'),
+});
 /**
- * In-app sign (engine-protocol.md §5): the authenticated principal signs;
- * integrity comes from the hash + immutability + the spine event. Connector
- * methods (bankid/scrive) arrive later through the SAME operation shape with
- * upgraded evidence. Exactly ONE primary signature per instance — enforced by
- * the open → signed transition.
+ * Bind (or re-bind) a document protocol's content while it is still open —
+ * the document-kind counterpart of `fillProtocol`. Re-binding is the whole
+ * point during negotiation: an avtal's price changes until it is sent out, and
+ * each rebind moves the hash the signature will be taken over.
+ *
+ * Once frozen, this fails like any other write to frozen content.
  */
-export async function signProtocol(ctx, input) {
-    const instance = getInstanceRow(ctx, z.string().min(1).parse(input.instanceId));
+export function bindDocument(ctx, rawInput) {
+    const input = bindDocumentInput.parse(rawInput);
+    const instance = getInstanceRow(ctx, input.instanceId);
+    assertUnfrozen(instance, 'the binding');
+    const template = getTemplateRow(ctx, instance.template_key, instance.template_version);
+    const content = templateContentOf(template);
+    if (content.kind !== 'document') {
+        throw new Error(`template ${instance.template_key}@${instance.template_version} is a '${content.kind}' ` +
+            `protocol: fill its items instead of binding content`);
+    }
+    ctx.sql.exec(`UPDATE protocol_instances
+     SET content_ref_type = ?, content_ref_id = ?, bound_hash = ? WHERE id = ?`, [input.contentRef.entityType, input.contentRef.entityId, input.contentHash, instance.id]);
+    ctx.emit({
+        type: 'protocol.content-bound',
+        schemaVersion: 1,
+        entity: protocolRef(instance.id),
+        piiClass: 'none',
+        payload: {
+            instanceId: instance.id,
+            templateKey: instance.template_key,
+            templateVersion: instance.template_version,
+            documentType: content.documentType,
+            contentRef: input.contentRef,
+            boundHash: input.contentHash,
+            entity: { entityType: instance.entity_type, entityId: instance.entity_id },
+        },
+    });
+    return getInstanceRow(ctx, instance.id);
+}
+// ---------------------------------------------------------------------------
+// Asynchronous signing — freeze first, collect signatures over days.
+// ---------------------------------------------------------------------------
+export const signatureRequestParty = z.object({
+    /** Display name for the role, never PII: 'Beställare', 'Leverantör'. */
+    label: z.string().min(1),
+    kind: z.enum(['principal', 'external']),
+    /**
+     * Who is expected to sign, when that is known up front. A `PrincipalId` for
+     * `principal`, an opaque `DataSubjectId` for `external`.
+     *
+     * Optional because it often is NOT known: a BankID flow addressed to a
+     * company mailbox is signed by whichever firmatecknare opens it, and their
+     * identity only becomes known when the provider reports it. Left unset, the
+     * signatory is whoever `recordSignature` reports; set, it is a constraint
+     * the recorded signatory must match.
+     */
+    ref: z.string().min(1).optional(),
+    /**
+     * 'primary' for the issuing party, 'counter' for accepting parties.
+     *
+     * Optional, and resolved so that a request set ALWAYS has exactly one
+     * primary: declare one explicitly, or the first party becomes it. A set with
+     * no primary would leave a signed instance whose issuing signature is null —
+     * `requireCountersigned` would then pass on a document nobody issued.
+     */
+    signatureKind: z.enum(['primary', 'counter']).optional(),
+});
+export const requestSignaturesInput = z.object({
+    instanceId: z.string().min(1),
+    /** 'scrive', 'bankid' — the provider a connector will dispatch to. */
+    method: z.string().min(1),
+    parties: z.array(signatureRequestParty).min(1),
+});
+/**
+ * Freeze the content and ask named parties to sign it — the asynchronous
+ * counterpart of `signProtocol`.
+ *
+ * This is the transition that closes the drift window: the instance leaves
+ * `open` immediately, so nothing can fill or rebind it while it sits at the
+ * provider. The hash is computed ONCE, here, and every signature that comes
+ * back must match it.
+ *
+ * The engine dispatches nothing. It emits `protocol.signatures-requested` with
+ * everything a connector needs (the hash, the parties, the method) and an
+ * executor outside the scope makes the call — module code never touches the
+ * network (boundary-lint R3).
+ */
+export async function requestSignatures(ctx, rawInput) {
+    const input = requestSignaturesInput.parse(rawInput);
+    const instance = getInstanceRow(ctx, input.instanceId);
     if (instance.status !== 'open') {
-        throw new Error(`protocol is ${instance.status}: only an open protocol can be signed`);
+        throw new Error(`protocol is ${instance.status}: only an open protocol can be sent for signature`);
     }
-    const template = getTemplateRow(ctx, instance.template_key, instance.template_version);
-    const latest = latestPerItem(getResponseRows(ctx, instance.id));
-    const contentHash = await protocolContentHash(template, latest);
-    const id = ulid();
-    ctx.sql.exec(`INSERT INTO protocol_signatures
-       (id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at)
-     VALUES (?, ?, ?, 'primary', 'in-app', ?, NULL, ?)`, [id, instance.id, ctx.principal, contentHash, new Date().toISOString()]);
-    ctx.sql.exec(`UPDATE protocol_instances SET status = 'signed' WHERE id = ?`, [instance.id]);
+    const primaries = input.parties.filter((p) => p.signatureKind === 'primary');
+    if (primaries.length > 1) {
+        throw new Error('at most one party may sign as primary — the rest counter-sign');
+    }
+    // Exactly one primary, always: the declared one, else the first party.
+    const primaryIndex = primaries.length === 1
+        ? input.parties.findIndex((p) => p.signatureKind === 'primary')
+        : 0;
+    // Validate the refs that were supplied, so a personnummer cannot be smuggled
+    // into a request row and land in a signature by way of the matching check.
+    for (const party of input.parties) {
+        if (party.ref === undefined)
+            continue;
+        signatory.parse({ kind: party.kind, ref: party.ref, label: party.label });
+    }
+    const contentHash = await currentHash(ctx, instance);
+    const now = new Date().toISOString();
+    ctx.sql.exec(`UPDATE protocol_instances
+     SET status = 'pending_signature', frozen_hash = ?, frozen_at = ? WHERE id = ?`, [contentHash, now, instance.id]);
+    const created = [];
+    for (const [index, party] of input.parties.entries()) {
+        const id = ulid();
+        created.push(id);
+        ctx.sql.exec(`INSERT INTO protocol_signature_requests
+         (id, instance_id, party_label, party_kind, party_ref, signature_kind, method,
+          status, content_hash, external_ref, resolved_note, requested_by, requested_at, resolved_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', ?, NULL, NULL, ?, ?, NULL)`, [
+            id,
+            instance.id,
+            party.label,
+            party.kind,
+            party.ref ?? null,
+            index === primaryIndex ? 'primary' : 'counter',
+            input.method,
+            contentHash,
+            ctx.principal,
+            now,
+        ]);
+    }
+    const requests = getRequestRows(ctx, instance.id).filter((r) => created.includes(r.id));
     ctx.emit({
-        type: 'protocol.signed',
+        type: 'protocol.signatures-requested',
         schemaVersion: 1,
         entity: protocolRef(instance.id),
-        piiClass: 'pseudonymous',
-        subjectId: dataSubjectId.parse(ctx.principal),
+        piiClass: 'none', // party refs are opaque ids; labels are role names, never PII
         payload: {
             instanceId: instance.id,
             templateKey: instance.template_key,
             templateVersion: instance.template_version,
             entity: { entityType: instance.entity_type, entityId: instance.entity_id },
-            signedBy: ctx.principal,
-            method: 'in-app',
+            method: input.method,
             contentHash,
-            // fat payload: the frozen answers travel with the event
-            responses: frozenAnswers(latest),
+            // Fat: a connector must never need a cross-module read to dispatch.
+            contentRef: instance.content_ref_type && instance.content_ref_id
+                ? { entityType: instance.content_ref_type, entityId: instance.content_ref_id }
+                : null,
+            boundHash: instance.bound_hash,
+            parties: requests.map((r) => ({
+                requestId: r.id,
+                label: r.party_label,
+                kind: r.party_kind,
+                ref: r.party_ref,
+                signatureKind: r.signature_kind,
+            })),
         },
     });
-    return {
+    return { instance: getInstanceRow(ctx, instance.id), contentHash, requests };
+}
+export const recordSignatureInput = z.object({
+    requestId: z.string().min(1),
+    signatory,
+    /** When the party actually signed, per the provider — NOT when we heard. */
+    signedAt: instant,
+    /**
+     * The hash the provider signed over, as the provider reports it. Checked
+     * against the frozen hash: a mismatch means the document that was signed is
+     * not the document we froze, and that must fail closed rather than record a
+     * signature over unknown content.
+     */
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    /** Sealed PDF, provider transaction id, audit log — where the proof lives. */
+    evidenceRef: z.string().min(1).optional(),
+});
+/**
+ * Record a signature that happened OUTSIDE this system — the webhook's half.
+ *
+ * Everything `signProtocol` takes from ambient context, this takes as data:
+ * the signatory is supplied (and may be an external person with no account),
+ * the timestamp is the provider's, the method is the request's, and the
+ * evidence reference points at the provider's sealed artifact.
+ *
+ * The last pending request resolving is what transitions the instance to
+ * `signed` — which is the multi-party rule stated in code: an avtal is signed
+ * when every requested party has signed it, not when the first one has.
+ *
+ * NOTE ON THE CALLER: there is no webhook ingress in the kernel yet, and no
+ * inbound authority seam that would let a provider callback invoke a scope
+ * operation (`ScopeHost.getScope` demands a `PrincipalId`; `ExecutorHandler`
+ * has no return path into a scope). Until those land this is reachable only by
+ * a principal holding `protocol:record-signature` — a key deliberately held by
+ * no human role in any demo.
+ */
+export async function recordSignature(ctx, rawInput) {
+    const input = recordSignatureInput.parse(rawInput);
+    const request = ctx.sql.query('SELECT * FROM protocol_signature_requests WHERE id = ?', [input.requestId])[0];
+    if (!request)
+        throw new Error(`signature request not found: ${input.requestId}`);
+    if (request.status !== 'pending') {
+        throw new Error(`signature request is already ${request.status}: ${request.id}`);
+    }
+    const instance = getInstanceRow(ctx, request.instance_id);
+    if (instance.status !== 'pending_signature') {
+        throw new Error(`protocol is ${instance.status}: signatures are only recorded while out for signature`);
+    }
+    // Re-derive rather than trust the column, then check the provider agrees.
+    const frozen = await verifyFrozen(ctx, instance);
+    if (input.contentHash !== frozen) {
+        throw new Error(`signed content does not match the frozen protocol: provider reported ` +
+            `${input.contentHash}, frozen ${frozen}`);
+    }
+    if (request.party_kind !== input.signatory.kind) {
+        throw new Error(`signature request ${request.id} expects a ${request.party_kind} signatory, ` +
+            `got ${input.signatory.kind}`);
+    }
+    if (request.party_ref && request.party_ref !== input.signatory.ref) {
+        throw new Error(`signature request ${request.id} was addressed to a different party than the one who signed`);
+    }
+    if (getSignatureRows(ctx, instance.id).some((s) => s.signed_by === input.signatory.ref)) {
+        throw new Error('this signatory has already signed this protocol');
+    }
+    const id = ulid();
+    ctx.sql.exec(`INSERT INTO protocol_signatures
+       (id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at,
+        request_id, signatory_kind, signatory_label)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+        id,
+        instance.id,
+        input.signatory.ref,
+        request.signature_kind,
+        request.method,
+        frozen,
+        input.evidenceRef ?? null,
+        input.signedAt,
+        request.id,
+        input.signatory.kind,
+        input.signatory.label ?? request.party_label,
+    ]);
+    ctx.sql.exec(`UPDATE protocol_signature_requests
+     SET status = 'signed', resolved_at = ?, external_ref = COALESCE(?, external_ref)
+     WHERE id = ?`, [input.signedAt, input.evidenceRef ?? null, request.id]);
+    // The instance is signed only when EVERY requested party signed — not merely
+    // when nothing is left pending. A declined or expired request is not pending
+    // either, and treating that as completion would mark an avtal fully executed
+    // that one party refused. An unresolved refusal holds the instance frozen
+    // until someone explicitly withdraws the request set.
+    const unsigned = ctx.sql.query(`SELECT COUNT(*) AS n FROM protocol_signature_requests
+     WHERE instance_id = ? AND status <> 'signed'`, [instance.id])[0].n;
+    const complete = unsigned === 0;
+    if (complete) {
+        ctx.sql.exec(`UPDATE protocol_instances SET status = 'signed' WHERE id = ?`, [instance.id]);
+    }
+    const signature = getSignatureRows(ctx, instance.id).find((s) => s.id === id);
+    emitSignatureEvent(ctx, {
         instance: getInstanceRow(ctx, instance.id),
-        signature: getSignatureRows(ctx, instance.id).find((s) => s.id === id),
+        signature,
+        contentHash: frozen,
+        complete,
+    });
+    return { instance: getInstanceRow(ctx, instance.id), signature };
+}
+export const declineSignatureInput = z.object({
+    requestId: z.string().min(1),
+    reason: z.string().min(1),
+    /** 'declined' when a party refused; 'expired' when the provider timed out. */
+    outcome: z.enum(['declined', 'expired']).default('declined'),
+});
+/**
+ * A party refused, or the provider's window expired. The instance stays
+ * `pending_signature` and therefore frozen — a refusal is not permission to
+ * edit. Renegotiating means cancelling the request set explicitly, which is a
+ * separate, permissioned, audited act.
+ */
+export function declineSignature(ctx, rawInput) {
+    const input = declineSignatureInput.parse(rawInput);
+    const request = ctx.sql.query('SELECT * FROM protocol_signature_requests WHERE id = ?', [input.requestId])[0];
+    if (!request)
+        throw new Error(`signature request not found: ${input.requestId}`);
+    if (request.status !== 'pending') {
+        throw new Error(`signature request is already ${request.status}: ${request.id}`);
+    }
+    const instance = getInstanceRow(ctx, request.instance_id);
+    ctx.sql.exec(`UPDATE protocol_signature_requests
+     SET status = ?, resolved_at = ?, resolved_note = ? WHERE id = ?`, [input.outcome ?? 'declined', new Date().toISOString(), input.reason, request.id]);
+    ctx.emit({
+        type: 'protocol.signature-declined',
+        schemaVersion: 1,
+        entity: protocolRef(instance.id),
+        piiClass: 'none',
+        payload: {
+            instanceId: instance.id,
+            requestId: request.id,
+            templateKey: instance.template_key,
+            entity: { entityType: instance.entity_type, entityId: instance.entity_id },
+            partyLabel: request.party_label,
+            outcome: input.outcome ?? 'declined',
+            reason: input.reason,
+        },
+    });
+    return ctx.sql.query('SELECT * FROM protocol_signature_requests WHERE id = ?', [request.id])[0];
+}
+export const cancelSignatureRequestsInput = z.object({
+    instanceId: z.string().min(1),
+    reason: z.string().min(1),
+});
+/**
+ * Withdraw an outstanding request set and thaw the instance — the
+ * renegotiation path an avtal needs when a party declines or the price moves.
+ *
+ * Cancelling THAWS: status returns to `open` and the frozen hash is cleared,
+ * so the next `requestSignatures` freezes fresh content at a fresh hash.
+ * Signatures already collected are NOT removed — they are append-only history
+ * attesting to content that really was frozen at the time — but they were
+ * taken over the OLD hash, so they can never satisfy the new one. That is the
+ * intended reading: a party who signed v1 has not signed v2.
+ */
+export function cancelSignatureRequests(ctx, rawInput) {
+    const input = cancelSignatureRequestsInput.parse(rawInput);
+    const instance = getInstanceRow(ctx, input.instanceId);
+    if (instance.status !== 'pending_signature') {
+        throw new Error(`protocol is ${instance.status}: only a protocol out for signature can be withdrawn`);
+    }
+    const now = new Date().toISOString();
+    const cancelled = ctx.sql.exec(`UPDATE protocol_signature_requests
+     SET status = 'cancelled', resolved_at = ?, resolved_note = ?
+     WHERE instance_id = ? AND status = 'pending'`, [now, input.reason, instance.id]);
+    ctx.sql.exec(`UPDATE protocol_instances
+     SET status = 'open', frozen_hash = NULL, frozen_at = NULL WHERE id = ?`, [instance.id]);
+    ctx.emit({
+        type: 'protocol.signatures-cancelled',
+        schemaVersion: 1,
+        entity: protocolRef(instance.id),
+        piiClass: 'none',
+        payload: {
+            instanceId: instance.id,
+            templateKey: instance.template_key,
+            entity: { entityType: instance.entity_type, entityId: instance.entity_id },
+            cancelled: cancelled.changes,
+            reason: input.reason,
+        },
+    });
+    return getInstanceRow(ctx, instance.id);
+}
+// ---------------------------------------------------------------------------
+// In-app signing — the everyday field case, unchanged in shape and behaviour.
+// ---------------------------------------------------------------------------
+/** Both signing paths emit the same pair of events, so they agree by construction. */
+function emitSignatureEvent(ctx, args) {
+    const { instance, signature, contentHash, complete } = args;
+    const signatories = getSignatureRows(ctx, instance.id).map(signatoryOf);
+    const base = {
+        instanceId: instance.id,
+        templateKey: instance.template_key,
+        templateVersion: instance.template_version,
+        entity: { entityType: instance.entity_type, entityId: instance.entity_id },
+        method: signature.method,
+        contentHash,
+        // Document kind: what was signed lives in the vertical, so the event
+        // carries the pointer and the hash rather than the content.
+        contentRef: instance.content_ref_type && instance.content_ref_id
+            ? { entityType: instance.content_ref_type, entityId: instance.content_ref_id }
+            : null,
+        boundHash: instance.bound_hash,
+        // fat payload: the frozen answers travel with the event (checklist kind)
+        responses: args.responses ?? {},
+        signatory: signatoryOf(signature),
+        // Retained for consumers that read the flat field: the signatory's ref.
+        signedBy: signature.signed_by,
+        evidenceRef: signature.evidence_ref,
+        signedAt: signature.signed_at,
+        /** False while other requested parties are still outstanding. */
+        complete,
+        signatories,
     };
+    if (signature.kind === 'primary') {
+        ctx.emit({
+            type: 'protocol.signed',
+            schemaVersion: 1,
+            entity: protocolRef(instance.id),
+            piiClass: 'pseudonymous',
+            subjectId: dataSubjectId.parse(signature.signed_by),
+            payload: base,
+        });
+        return;
+    }
+    const primary = getSignatureRows(ctx, instance.id).find((s) => s.kind === 'primary');
+    ctx.emit({
+        type: 'protocol.countersigned',
+        schemaVersion: 1,
+        entity: protocolRef(instance.id),
+        piiClass: 'pseudonymous',
+        subjectId: dataSubjectId.parse(signature.signed_by),
+        payload: {
+            ...base,
+            signedBy: primary?.signed_by ?? null,
+            countersignedBy: signature.signed_by,
+            countersignatory: signatoryOf(signature),
+        },
+    });
+}
+/**
+ * In-app sign (engine-protocol.md §5): the authenticated principal signs, now;
+ * integrity comes from the hash + immutability + the spine event. Freezing and
+ * signing coincide here, which is sound precisely BECAUSE it is synchronous —
+ * there is no window between what the signer saw and what was hashed.
+ *
+ * For an external provider flow (BankID via Scrive) use `requestSignatures` +
+ * `recordSignature` instead: the signatory is not `ctx.principal`, the moment
+ * is not now, and freezing must happen at dispatch rather than at signature.
+ * Exactly ONE primary signature per instance — enforced by the open → signed
+ * transition.
+ */
+export async function signProtocol(ctx, input) {
+    const instance = getInstanceRow(ctx, z.string().min(1).parse(input.instanceId));
+    if (instance.status !== 'open') {
+        throw new Error(`protocol is ${instance.status}: only an open protocol can be signed`);
+    }
+    const latest = latestPerItem(getResponseRows(ctx, instance.id));
+    const contentHash = await currentHash(ctx, instance);
+    const now = new Date().toISOString();
+    const id = ulid();
+    ctx.sql.exec(`INSERT INTO protocol_signatures
+       (id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at,
+        request_id, signatory_kind, signatory_label)
+     VALUES (?, ?, ?, 'primary', 'in-app', ?, NULL, ?, NULL, 'principal', NULL)`, [id, instance.id, ctx.principal, contentHash, now]);
+    ctx.sql.exec(`UPDATE protocol_instances SET status = 'signed', frozen_hash = ?, frozen_at = ? WHERE id = ?`, [contentHash, now, instance.id]);
+    const signature = getSignatureRows(ctx, instance.id).find((s) => s.id === id);
+    emitSignatureEvent(ctx, {
+        instance: getInstanceRow(ctx, instance.id),
+        signature,
+        contentHash,
+        complete: true,
+        responses: frozenAnswers(latest),
+    });
+    return { instance: getInstanceRow(ctx, instance.id), signature };
 }
 /**
  * Counter-sign (invariant 3): a SECOND signature on the SAME frozen content —
  * the customer at pickup. Requires a signed instance; the content hash is
- * recomputed and must equal the primary signature's hash (frozen content,
- * verified, never assumed). One counter-signature per principal; a principal
- * never counter-signs what they primary-signed.
+ * recomputed and must equal the frozen hash (frozen content, verified, never
+ * assumed). One counter-signature per signatory; a signatory never
+ * counter-signs what they primary-signed.
  */
 export async function countersignProtocol(ctx, input) {
     const instance = getInstanceRow(ctx, z.string().min(1).parse(input.instanceId));
@@ -433,46 +1164,27 @@ export async function countersignProtocol(ctx, input) {
     const primary = signatures.find((s) => s.kind === 'primary');
     if (!primary)
         throw new Error(`signed protocol has no primary signature: ${instance.id}`); // corrupt state, fail closed
-    if (primary.signed_by === ctx.principal) {
-        throw new Error('counter-signature must come from a different principal than the signer');
-    }
-    if (signatures.some((s) => s.kind === 'counter' && s.signed_by === ctx.principal)) {
-        throw new Error('already counter-signed by this principal');
+    if (signatures.some((s) => s.signed_by === ctx.principal)) {
+        throw new Error('counter-signature must come from a signatory who has not already signed');
     }
-    // Re-run the hash recipe against stored state: the counter-signature binds
-    // to verified frozen content, not to a trusted column.
-    const template = getTemplateRow(ctx, instance.template_key, instance.template_version);
+    // Re-run the recipe against stored state: the counter-signature binds to
+    // verified frozen content, not to a trusted column.
+    const contentHash = await verifyFrozen(ctx, instance);
     const latest = latestPerItem(getResponseRows(ctx, instance.id));
-    const contentHash = await protocolContentHash(template, latest);
-    if (contentHash !== primary.content_hash) {
-        throw new Error(`content hash mismatch on counter-sign: stored ${primary.content_hash}, replayed ${contentHash}`);
-    }
     const id = ulid();
     ctx.sql.exec(`INSERT INTO protocol_signatures
-       (id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at)
-     VALUES (?, ?, ?, 'counter', 'in-app', ?, NULL, ?)`, [id, instance.id, ctx.principal, contentHash, new Date().toISOString()]);
-    ctx.emit({
-        type: 'protocol.countersigned',
-        schemaVersion: 1,
-        entity: protocolRef(instance.id),
-        piiClass: 'pseudonymous',
-        subjectId: dataSubjectId.parse(ctx.principal),
-        payload: {
-            instanceId: instance.id,
-            templateKey: instance.template_key,
-            templateVersion: instance.template_version,
-            entity: { entityType: instance.entity_type, entityId: instance.entity_id },
-            signedBy: primary.signed_by,
-            countersignedBy: ctx.principal,
-            method: 'in-app',
-            contentHash,
-            responses: frozenAnswers(latest),
-        },
+       (id, instance_id, signed_by, kind, method, content_hash, evidence_ref, signed_at,
+        request_id, signatory_kind, signatory_label)
+     VALUES (?, ?, ?, 'counter', 'in-app', ?, NULL, ?, NULL, 'principal', NULL)`, [id, instance.id, ctx.principal, contentHash, new Date().toISOString()]);
+    const signature = getSignatureRows(ctx, instance.id).find((s) => s.id === id);
+    emitSignatureEvent(ctx, {
+        instance,
+        signature,
+        contentHash,
+        complete: true,
+        responses: frozenAnswers(latest),
     });
-    return {
-        instance: getInstanceRow(ctx, instance.id),
-        signature: getSignatureRows(ctx, instance.id).find((s) => s.id === id),
-    };
+    return { instance: getInstanceRow(ctx, instance.id), signature };
 }
 /** Voiding, not deleting: a superseded protocol keeps its rows forever. */
 export function voidProtocol(ctx, input) {
@@ -480,8 +1192,15 @@ export function voidProtocol(ctx, input) {
     const instance = getInstanceRow(ctx, z.string().min(1).parse(input.instanceId));
     if (instance.status === 'voided')
         throw new Error('protocol is already voided');
+    const now = new Date().toISOString();
+    // An outstanding request set dies with the protocol — leaving rows `pending`
+    // on a voided instance would keep `requireAllSigned` reading a live gate on
+    // a document that is out of play.
+    ctx.sql.exec(`UPDATE protocol_signature_requests
+     SET status = 'cancelled', resolved_at = ?, resolved_note = ?
+     WHERE instance_id = ? AND status = 'pending'`, [now, `protocol voided: ${reason}`, instance.id]);
     ctx.sql.exec(`UPDATE protocol_instances
-     SET status = 'voided', voided_by = ?, voided_reason = ?, voided_at = ? WHERE id = ?`, [ctx.principal, reason, new Date().toISOString(), instance.id]);
+     SET status = 'voided', voided_by = ?, voided_reason = ?, voided_at = ? WHERE id = ?`, [ctx.principal, reason, now, instance.id]);
     ctx.emit({
         type: 'protocol.voided',
         schemaVersion: 1,
@@ -508,12 +1227,13 @@ export function getProtocol(ctx, instanceId) {
             key: template.key,
             version: template.version,
             title: template.title,
-            content: protocolTemplateContent.parse(JSON.parse(template.content_json)),
+            content: templateContentOf(template),
         },
         responses,
         latest: latestPerItem(responses),
         signature: signatures.find((s) => s.kind === 'primary') ?? null,
         signatures,
+        requests: getRequestRows(ctx, instance.id),
     };
 }
 export function listProtocolsForEntity(ctx, entity) {
@@ -521,21 +1241,33 @@ export function listProtocolsForEntity(ctx, entity) {
      WHERE entity_type = ? AND entity_id = ? ORDER BY rowid`, [entity.entityType, entity.entityId]);
     return instances.map((instance) => {
         const template = getTemplateRow(ctx, instance.template_key, instance.template_version);
-        const content = protocolTemplateContent.parse(JSON.parse(template.content_json));
-        const total = content.sections.reduce((n, s) => n + s.items.length, 0);
-        const answered = Object.keys(latestPerItem(getResponseRows(ctx, instance.id))).length;
+        const content = templateContentOf(template);
+        // A document has one thing to settle — its bound content — so it reads as
+        // 0/1 or 1/1 rather than pretending to a checklist's item count.
+        const total = content.kind === 'checklist'
+            ? content.sections.reduce((n, s) => n + s.items.length, 0)
+            : 1;
+        const answered = content.kind === 'checklist'
+            ? Object.keys(latestPerItem(getResponseRows(ctx, instance.id))).length
+            : instance.bound_hash
+                ? 1
+                : 0;
         const signatures = getSignatureRows(ctx, instance.id);
         const primary = signatures.find((s) => s.kind === 'primary');
         const counter = signatures.filter((s) => s.kind === 'counter').at(-1);
+        const pendingSignatures = ctx.sql.query(`SELECT COUNT(*) AS n FROM protocol_signature_requests
+       WHERE instance_id = ? AND status = 'pending'`, [instance.id])[0].n;
         return {
             instance,
             title: template.title,
+            contentKind: content.kind,
             answered,
             total,
             signedBy: primary?.signed_by ?? null,
             signedAt: primary?.signed_at ?? null,
             countersignedBy: counter?.signed_by ?? null,
             countersignedAt: counter?.signed_at ?? null,
+            pendingSignatures,
         };
     });
 }
@@ -564,6 +1296,32 @@ const fillOp = async (ctx, input) => {
     assertAllowed(await ctx.check(PROTOCOL_PERM.fill, protocolRef(input.instanceId)));
     return fillProtocol(ctx, input);
 };
+const bindOp = async (ctx, input) => {
+    assertAllowed(await ctx.check(PROTOCOL_PERM.bind, protocolRef(input.instanceId)));
+    return bindDocument(ctx, input);
+};
+const requestSignaturesOp = async (ctx, input) => {
+    assertAllowed(await ctx.check(PROTOCOL_PERM.requestSignature, protocolRef(input.instanceId)));
+    return requestSignatures(ctx, input);
+};
+const cancelSignaturesOp = async (ctx, input) => {
+    assertAllowed(await ctx.check(PROTOCOL_PERM.requestSignature, protocolRef(input.instanceId)));
+    return cancelSignatureRequests(ctx, input);
+};
+/**
+ * The ingress-facing pair. Both check `protocol:record-signature`, which is a
+ * connector's key rather than a person's — the permission diff is where a
+ * deployment declares that it trusts something to speak for an external
+ * signing provider.
+ */
+const recordSignatureOp = async (ctx, input) => {
+    assertAllowed(await ctx.check(PROTOCOL_PERM.recordSignature));
+    return recordSignature(ctx, input);
+};
+const declineSignatureOp = async (ctx, input) => {
+    assertAllowed(await ctx.check(PROTOCOL_PERM.recordSignature));
+    return declineSignature(ctx, input);
+};
 const signOp = async (ctx, input) => {
     assertAllowed(await ctx.check(PROTOCOL_PERM.sign, protocolRef(input.instanceId)));
     return signProtocol(ctx, input);
@@ -599,6 +1357,11 @@ export const protocolModule = {
         'protocol/list-templates': listTemplatesOp,
         'protocol/instantiate': instantiateOp,
         'protocol/fill': fillOp,
+        'protocol/bind-document': bindOp,
+        'protocol/request-signatures': requestSignaturesOp,
+        'protocol/cancel-signatures': cancelSignaturesOp,
+        'protocol/record-signature': recordSignatureOp,
+        'protocol/decline-signature': declineSignatureOp,
         'protocol/sign': signOp,
         'protocol/countersign': countersignOp,
         'protocol/void': voidOp,