@zanii/subprocessor 0.1.0

package/LICENSE

@@ -0,0 +1,159 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or agreed
+      to in writing, Licensor provides the Work (and each Contributor
+      provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
+      OR CONDITIONS OF ANY KIND, either express or implied, including,
+      without limitation, any warranties or conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Zanii
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,38 @@
+# @zanii/subprocessor
+
+**Which third parties actually touched it?** The fear behind every AI DPA — *"you sent my
+data to OpenAI, who sent it where?"* This makes the onward-transfer chain a **first-class
+provable graph**: which downstream processors saw the data, under which agreement, tied to
+the junction. The exact GDPR Art. 28 answer.
+
+```sh
+npm install @zanii/subprocessor @zanii/core
+```
+
+```ts
+import { buildTransfer, verifyTransfers, subprocessorGraph } from '@zanii/subprocessor';
+
+await zanii.record(buildTransfer({ from: 'controller', to: 'openai',
+  agreement: { type: 'zero-retention' }, ts: now, ref: dataRef }));
+
+// verify the recorded onward chain against your DECLARED subprocessor list:
+const r = verifyTransfers(transfers, ['openai', 'anthropic', 'stripe']);
+r.ok;   // false if data reached any party NOT on the declared list — a provable Art. 28 violation
+
+subprocessorGraph(transfers, declared);   // { parties, edges, undeclared, missing_agreement_id }
+```
+
+Python: `from zanii.subprocessor import build_transfer, verify_transfers, subprocessor_graph`
+
+## The load-bearing check
+
+Every `to` must be in the declared subprocessor list. A transfer to an **undeclared** party
+is surfaced (`undeclared`) as a provable violation — discovered by the check, not after a
+breach. dpa/scc transfers with no agreement id are flagged too. Composes
+`@zanii/data-custody`'s `junction` and `@zanii/x402`'s settlement.
+
+## The limit, stated up front
+
+Proves the transfers that were **recorded**. It cannot prove an off-record leak — a
+processor that received plaintext and emitted nothing (that's the enclave/broker problem).
+An agreement id is a reference, not a guarantee the counterparty honored it.

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+export interface Agreement {
+    /** e.g. `zero-retention`, `dpa`, `scc` (standard contractual clauses). */
+    type: 'zero-retention' | 'dpa' | 'scc' | 'other';
+    /** The agreement identifier/reference. */
+    id?: string;
+}
+export interface Transfer {
+    v: 1;
+    type: 'subprocessor.transfer';
+    /** Optional data-object ref (`@zanii/data-custody`) this transfer moved. */
+    ref?: string;
+    /** The party disclosing (a DID, a processor name). */
+    from: string;
+    /** The party receiving — must be in the declared subprocessor list. */
+    to: string;
+    agreement: Agreement;
+    /** Optional destination region (compose with `@zanii/residency`). */
+    region?: string;
+    /** Optional settlement/junction reference (`@zanii/x402` tx, an API-call id). */
+    junction?: string;
+    ts: string;
+}
+export interface TransferInput {
+    from: string;
+    to: string;
+    agreement: Agreement;
+    ts: string;
+    ref?: string;
+    region?: string;
+    junction?: string;
+}
+/** Build one onward-transfer record. Record it; the `to` is checked against your declared list. */
+export declare function buildTransfer(input: TransferInput): {
+    target: string;
+    payload: Record<string, unknown>;
+};
+export declare function transferHash(t: Transfer): string;
+export interface SubprocessorGraph {
+    /** Every party that appears (as sender or receiver). */
+    parties: string[];
+    /** The recorded hops. */
+    edges: Array<{
+        from: string;
+        to: string;
+        agreement: Agreement;
+        ts: string;
+    }>;
+    /** Receivers NOT in the declared subprocessor list — the violations. */
+    undeclared: string[];
+    /** Transfers with no agreement id where one is required (dpa/scc). */
+    missing_agreement_id: Array<{
+        to: string;
+        ts: string;
+    }>;
+}
+/**
+ * Build the onward-transfer graph and check it against the **declared** subprocessor
+ * allow-list. `undeclared` is the load-bearing output: any receiver not on the list is a
+ * provable Art. 28 violation. `missing_agreement_id` flags dpa/scc transfers with no id.
+ * Pure — pass the transfers you recorded (from the ledger).
+ */
+export declare function subprocessorGraph(transfers: Transfer[], declared: string[]): SubprocessorGraph;
+export interface TransferCheck {
+    ok: boolean;
+    reasons: string[];
+}
+/**
+ * The compliance verdict for one data object's transfers: every receiver is declared, and
+ * every dpa/scc transfer carries an agreement id. `ok` means the recorded onward chain is
+ * clean; it does not assert no off-record transfer happened (see the limit).
+ */
+export declare function verifyTransfers(transfers: Transfer[], declared: string[]): TransferCheck;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,IAAI,EAAE,gBAAgB,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAC;IACjD,0CAA0C;IAC1C,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,CAAC,CAAC;IACL,IAAI,EAAE,uBAAuB,CAAC;IAC9B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,CAAC;IACrB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,SAAS,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,mGAAmG;AACnG,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAiBxG;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEhD;AAED,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yBAAyB;IACzB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,SAAS,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC7E,wEAAwE;IACxE,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sEAAsE;IACtE,oBAAoB,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAoB9F;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,aAAa,CAMxF"}

package/dist/index.js

@@ -0,0 +1,94 @@
+/**
+ * @zanii/subprocessor — which third parties actually touched it?
+ *
+ * The fear behind every AI DPA: "you sent my data to OpenAI, who sent it where?" This
+ * makes the onward-transfer chain a **first-class provable graph** — which downstream
+ * processors saw the data, under which agreement (zero-retention, a DPA id), tied to the
+ * junction. It extends `@zanii/data-custody`'s `junction` field and `@zanii/x402`'s
+ * settlement into the exact GDPR Art. 28 answer buyers want.
+ *
+ * A **transfer** is one hop: `from → to`, under an `agreement`, at a time. Transfers form
+ * a graph (a controller → OpenAI → OpenAI's own subprocessors). The load-bearing check:
+ * every `to` must appear in the **declared subprocessor list**; a transfer to an
+ * undeclared party is a provable, flagged violation — not discovered after a breach.
+ *
+ * ## The limit, stated up front
+ *
+ * This proves the transfers that were **recorded**. It cannot prove an off-record leak —
+ * a processor that received plaintext and emitted no transfer receipt. That residual is
+ * the credential-custody / enclave problem (`@zanii/broker`, `@zanii/attest`), unchanged.
+ * And an agreement id is a reference, not a guarantee the counterparty honored it.
+ */
+import { jcsHash } from '@zanii/core';
+/** Build one onward-transfer record. Record it; the `to` is checked against your declared list. */
+export function buildTransfer(input) {
+    if (!input.from || !input.to)
+        throw new Error('from and to are required');
+    if (input.from === input.to)
+        throw new Error('a transfer must cross parties (from != to)');
+    if (!input.agreement?.type)
+        throw new Error('agreement.type is required');
+    if (Number.isNaN(Date.parse(input.ts)))
+        throw new Error('ts must be an ISO timestamp');
+    const t = {
+        v: 1,
+        type: 'subprocessor.transfer',
+        from: input.from,
+        to: input.to,
+        agreement: input.agreement,
+        ts: input.ts,
+    };
+    if (input.ref !== undefined)
+        t.ref = input.ref;
+    if (input.region !== undefined)
+        t.region = input.region;
+    if (input.junction !== undefined)
+        t.junction = input.junction;
+    return { target: `subprocessor.transfer.${input.agreement.type}`, payload: t };
+}
+export function transferHash(t) {
+    return jcsHash(t);
+}
+/**
+ * Build the onward-transfer graph and check it against the **declared** subprocessor
+ * allow-list. `undeclared` is the load-bearing output: any receiver not on the list is a
+ * provable Art. 28 violation. `missing_agreement_id` flags dpa/scc transfers with no id.
+ * Pure — pass the transfers you recorded (from the ledger).
+ */
+export function subprocessorGraph(transfers, declared) {
+    const parties = new Set();
+    const edges = [];
+    const undeclared = new Set();
+    const missing = [];
+    for (const t of transfers) {
+        parties.add(t.from);
+        parties.add(t.to);
+        edges.push({ from: t.from, to: t.to, agreement: t.agreement, ts: t.ts });
+        if (!declared.includes(t.to))
+            undeclared.add(t.to);
+        if ((t.agreement.type === 'dpa' || t.agreement.type === 'scc') && !t.agreement.id) {
+            missing.push({ to: t.to, ts: t.ts });
+        }
+    }
+    return {
+        parties: [...parties].sort(),
+        edges: edges.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts)),
+        undeclared: [...undeclared].sort(),
+        missing_agreement_id: missing,
+    };
+}
+/**
+ * The compliance verdict for one data object's transfers: every receiver is declared, and
+ * every dpa/scc transfer carries an agreement id. `ok` means the recorded onward chain is
+ * clean; it does not assert no off-record transfer happened (see the limit).
+ */
+export function verifyTransfers(transfers, declared) {
+    const g = subprocessorGraph(transfers, declared);
+    const reasons = [];
+    for (const u of g.undeclared)
+        reasons.push(`data reached '${u}', which is NOT a declared subprocessor`);
+    for (const m of g.missing_agreement_id)
+        reasons.push(`transfer to '${m.to}' at ${m.ts} has no agreement id (dpa/scc requires one)`);
+    return { ok: reasons.length === 0, reasons };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zanii/subprocessor",
+  "version": "0.1.0",
+  "description": "Prove the onward-transfer chain - which downstream processors actually saw the data, under which agreement (zero-retention, DPA id), tied to the junction/settlement. Answers the exact GDPR Art. 28 question every AI DPA raises: 'you sent my data to OpenAI, who sent it where?' A transfer to a party not in the declared subprocessor list is a provable, flagged violation. Proves recorded transfers; an off-record leak needs an attested enclave.",
+  "license": "Apache-2.0",
+  "homepage": "https://ledger.zanii.agency",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.0.9"
+  },
+  "dependencies": {
+    "@zanii/core": "0.4.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+/**
+ * @zanii/subprocessor — which third parties actually touched it?
+ *
+ * The fear behind every AI DPA: "you sent my data to OpenAI, who sent it where?" This
+ * makes the onward-transfer chain a **first-class provable graph** — which downstream
+ * processors saw the data, under which agreement (zero-retention, a DPA id), tied to the
+ * junction. It extends `@zanii/data-custody`'s `junction` field and `@zanii/x402`'s
+ * settlement into the exact GDPR Art. 28 answer buyers want.
+ *
+ * A **transfer** is one hop: `from → to`, under an `agreement`, at a time. Transfers form
+ * a graph (a controller → OpenAI → OpenAI's own subprocessors). The load-bearing check:
+ * every `to` must appear in the **declared subprocessor list**; a transfer to an
+ * undeclared party is a provable, flagged violation — not discovered after a breach.
+ *
+ * ## The limit, stated up front
+ *
+ * This proves the transfers that were **recorded**. It cannot prove an off-record leak —
+ * a processor that received plaintext and emitted no transfer receipt. That residual is
+ * the credential-custody / enclave problem (`@zanii/broker`, `@zanii/attest`), unchanged.
+ * And an agreement id is a reference, not a guarantee the counterparty honored it.
+ */
+import { jcsHash } from '@zanii/core';
+
+export interface Agreement {
+  /** e.g. `zero-retention`, `dpa`, `scc` (standard contractual clauses). */
+  type: 'zero-retention' | 'dpa' | 'scc' | 'other';
+  /** The agreement identifier/reference. */
+  id?: string;
+}
+
+export interface Transfer {
+  v: 1;
+  type: 'subprocessor.transfer';
+  /** Optional data-object ref (`@zanii/data-custody`) this transfer moved. */
+  ref?: string;
+  /** The party disclosing (a DID, a processor name). */
+  from: string;
+  /** The party receiving — must be in the declared subprocessor list. */
+  to: string;
+  agreement: Agreement;
+  /** Optional destination region (compose with `@zanii/residency`). */
+  region?: string;
+  /** Optional settlement/junction reference (`@zanii/x402` tx, an API-call id). */
+  junction?: string;
+  ts: string;
+}
+
+export interface TransferInput {
+  from: string;
+  to: string;
+  agreement: Agreement;
+  ts: string;
+  ref?: string;
+  region?: string;
+  junction?: string;
+}
+
+/** Build one onward-transfer record. Record it; the `to` is checked against your declared list. */
+export function buildTransfer(input: TransferInput): { target: string; payload: Record<string, unknown> } {
+  if (!input.from || !input.to) throw new Error('from and to are required');
+  if (input.from === input.to) throw new Error('a transfer must cross parties (from != to)');
+  if (!input.agreement?.type) throw new Error('agreement.type is required');
+  if (Number.isNaN(Date.parse(input.ts))) throw new Error('ts must be an ISO timestamp');
+  const t: Transfer = {
+    v: 1,
+    type: 'subprocessor.transfer',
+    from: input.from,
+    to: input.to,
+    agreement: input.agreement,
+    ts: input.ts,
+  };
+  if (input.ref !== undefined) t.ref = input.ref;
+  if (input.region !== undefined) t.region = input.region;
+  if (input.junction !== undefined) t.junction = input.junction;
+  return { target: `subprocessor.transfer.${input.agreement.type}`, payload: t as unknown as Record<string, unknown> };
+}
+
+export function transferHash(t: Transfer): string {
+  return jcsHash(t as unknown as Record<string, unknown>);
+}
+
+export interface SubprocessorGraph {
+  /** Every party that appears (as sender or receiver). */
+  parties: string[];
+  /** The recorded hops. */
+  edges: Array<{ from: string; to: string; agreement: Agreement; ts: string }>;
+  /** Receivers NOT in the declared subprocessor list — the violations. */
+  undeclared: string[];
+  /** Transfers with no agreement id where one is required (dpa/scc). */
+  missing_agreement_id: Array<{ to: string; ts: string }>;
+}
+
+/**
+ * Build the onward-transfer graph and check it against the **declared** subprocessor
+ * allow-list. `undeclared` is the load-bearing output: any receiver not on the list is a
+ * provable Art. 28 violation. `missing_agreement_id` flags dpa/scc transfers with no id.
+ * Pure — pass the transfers you recorded (from the ledger).
+ */
+export function subprocessorGraph(transfers: Transfer[], declared: string[]): SubprocessorGraph {
+  const parties = new Set<string>();
+  const edges: SubprocessorGraph['edges'] = [];
+  const undeclared = new Set<string>();
+  const missing: SubprocessorGraph['missing_agreement_id'] = [];
+  for (const t of transfers) {
+    parties.add(t.from);
+    parties.add(t.to);
+    edges.push({ from: t.from, to: t.to, agreement: t.agreement, ts: t.ts });
+    if (!declared.includes(t.to)) undeclared.add(t.to);
+    if ((t.agreement.type === 'dpa' || t.agreement.type === 'scc') && !t.agreement.id) {
+      missing.push({ to: t.to, ts: t.ts });
+    }
+  }
+  return {
+    parties: [...parties].sort(),
+    edges: edges.sort((a, b) => Date.parse(a.ts) - Date.parse(b.ts)),
+    undeclared: [...undeclared].sort(),
+    missing_agreement_id: missing,
+  };
+}
+
+export interface TransferCheck {
+  ok: boolean;
+  reasons: string[];
+}
+
+/**
+ * The compliance verdict for one data object's transfers: every receiver is declared, and
+ * every dpa/scc transfer carries an agreement id. `ok` means the recorded onward chain is
+ * clean; it does not assert no off-record transfer happened (see the limit).
+ */
+export function verifyTransfers(transfers: Transfer[], declared: string[]): TransferCheck {
+  const g = subprocessorGraph(transfers, declared);
+  const reasons: string[] = [];
+  for (const u of g.undeclared) reasons.push(`data reached '${u}', which is NOT a declared subprocessor`);
+  for (const m of g.missing_agreement_id) reasons.push(`transfer to '${m.to}' at ${m.ts} has no agreement id (dpa/scc requires one)`);
+  return { ok: reasons.length === 0, reasons };
+}