@zanii/decisions 0.1.2 → 0.1.3

package/README.md

@@ -43,6 +43,8 @@ ruleConsistency(payloads); // rulebook windows + the interleaving red flag
 Reference kinds: `dispatch`, `rank`, `payout` — any string works.
 
 ## Changelog
+
+- **0.1.3** — `adverseActionNotice` (principal reasons), `disparityReport` (selection rates and impact ratios; groups stay off the ledger), human-review requests with `reviewStatus`, `payBreakdown` that must add up, `appealPack`, `counterfactuals`, rule-change notices with `noticeCompliance`, `collectiveAudit`, and `creditDecision` / `tenantScreeningDecision` with notices when declined. Metrics flag where to look; they do not rule on fairness.
 - **0.1.2** — now depends on `@zanii/core` 0.5 (protocol 1.2), so it shares one core with `@zanii/sdk` 0.5 instead of pulling in a second, older copy. No API change.
 - **0.1.0** — initial release: `buildDecisionReceipt`, `verifyDecision`, `ruleConsistency`.
 

package/dist/fairness.d.ts

@@ -0,0 +1,176 @@
+import { type DecisionInput } from './index.js';
+type Payload = Record<string, unknown>;
+/** An adverse-action notice: the decision, its rulebook and the principal reasons (at most four, most important first). */
+export declare function adverseActionNotice(decision: Payload, input: {
+    reasons: string[];
+    decidedBy: string;
+    rights: string;
+}): {
+    decision: string;
+    kind: unknown;
+    rulebook: unknown;
+    decided_by: string;
+    principal_reasons: string[];
+    rights: string;
+    ts: unknown;
+};
+/**
+ * Selection rate per group and the impact ratio against the most-selected group. Groups
+ * are supplied by the auditor (they never go on the ledger). A ratio under 0.8 is flagged,
+ * the threshold bias audits commonly use.
+ */
+export declare function disparityReport(outcomes: Array<{
+    group: string;
+    selected: boolean;
+}>, threshold?: number): {
+    impactRatio: number | null;
+    flagged: boolean;
+    group: string;
+    n: number;
+    rate: number;
+}[];
+/** A person asks for a human to review an automated decision. */
+export declare function humanReviewRequest(input: {
+    decision: string;
+    subjectTag: string;
+    reason: string;
+    ts: string;
+    slaDays: number;
+}): {
+    target: string;
+    subjectTag: string;
+    payload: {
+        _zr_kind: string;
+        v: number;
+        decision: string;
+        reason: string;
+        ts: string;
+        due: string;
+    };
+};
+/** Which review requests are answered, pending or overdue. */
+export declare function reviewStatus(requests: Payload[], resolutions: Array<{
+    decision: string;
+    ts: string;
+    outcome: 'upheld' | 'changed';
+}>, now: string): {
+    decision: unknown;
+    status: string;
+    outcome: "upheld" | "changed" | null;
+}[];
+/** How a worker's pay for a period was computed, line by line, and whether it adds up to what was paid. Integer minor units. */
+export declare function payBreakdown(lines: Array<{
+    task: string;
+    base_minor: number;
+    adjustments: Array<{
+        reason: string;
+        amount_minor: number;
+    }>;
+}>, paid_minor: number): {
+    items: {
+        task: string;
+        base_minor: number;
+        adjustments: {
+            reason: string;
+            amount_minor: number;
+        }[];
+        total_minor: number;
+    }[];
+    computed_minor: number;
+    paid_minor: number;
+    matches: boolean;
+    difference_minor: number;
+};
+/** Everything a worker needs to contest a deactivation or a sanction. */
+export declare function appealPack(decision: Payload, statement: string, factors?: {
+    nonce: string;
+    disclosed?: Record<string, unknown>;
+}): {
+    decision: string;
+    kind: unknown;
+    outcome: unknown;
+    rulebook: unknown;
+    ts: unknown;
+    factors_commitment: {} | null;
+    factors: Record<string, unknown> | null;
+    factors_nonce: string | null;
+    statement: string;
+};
+/**
+ * Which single-factor changes would have flipped the outcome, using the (committed) model
+ * you supply. Each candidate value is tried on its own.
+ */
+export declare function counterfactuals<F extends Record<string, unknown>>(model: (factors: F) => boolean, factors: F, candidates: Partial<Record<keyof F, unknown[]>>): {
+    outcome: boolean;
+    flips: {
+        factor: keyof F;
+        from: unknown;
+        to: unknown;
+    }[];
+};
+/** Advance notice that a rulebook will change. */
+export declare function ruleChangeNotice(input: {
+    from: string;
+    to: string;
+    effectiveFrom: string;
+    summary: string;
+    ts: string;
+}): {
+    target: string;
+    payload: {
+        from: string;
+        to: string;
+        effectiveFrom: string;
+        summary: string;
+        ts: string;
+        _zr_kind: string;
+        v: number;
+    };
+};
+/** Did the platform give at least `minDays` notice, and did the new rulebook only appear after it took effect? */
+export declare function noticeCompliance(notice: Payload, decisions: Payload[], minDays: number): {
+    ok: boolean;
+    noticeDays: number;
+    usedEarly: number;
+};
+/** A union or advocate pools members' decision records: rule consistency plus outcomes per kind. */
+export declare function collectiveAudit(memberDecisions: Payload[][]): {
+    members: number;
+    decisions: number;
+    consistency: import("./index.js").ConsistencyReport;
+    byKind: Record<string, number>;
+};
+/** A credit decision: rulebook, committed factors and principal reasons. */
+export declare function creditDecision(input: Omit<DecisionInput, 'kind'> & {
+    approved: boolean;
+    reasons?: string[];
+}): {
+    receipt: import("./index.js").DecisionReceipt;
+    notice: {
+        decision: string;
+        kind: unknown;
+        rulebook: unknown;
+        decided_by: string;
+        principal_reasons: string[];
+        rights: string;
+        ts: unknown;
+    } | null;
+};
+/** A tenant-screening decision, recorded the same way. */
+export declare function tenantScreeningDecision(input: Omit<DecisionInput, 'kind'> & {
+    accepted: boolean;
+    reasons?: string[];
+}): {
+    receipt: import("./index.js").DecisionReceipt;
+    notice: {
+        decision: string;
+        kind: unknown;
+        rulebook: unknown;
+        decided_by: string;
+        principal_reasons: string[];
+        rights: string;
+        ts: unknown;
+    } | null;
+};
+export {};
+//# sourceMappingURL=fairness.d.ts.map

package/dist/fairness.d.ts.map

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

package/dist/fairness.js

@@ -0,0 +1,107 @@
+/**
+ * What people and auditors need around algorithmic decisions: adverse-action notices,
+ * selection-rate disparity (the impact ratio bias audits use), human-review requests with
+ * deadlines, pay breakdowns, appeal packs, counterfactuals, advance notice of rule changes,
+ * collective audits, and credit and tenant-screening decisions.
+ *
+ * Fairness metrics here are arithmetic on outcomes. They flag where to look; they do not
+ * decide whether a system is lawful or fair.
+ */
+import { jcsHash } from '@zanii/core';
+import { buildDecisionReceipt, ruleConsistency } from './index.js';
+/** An adverse-action notice: the decision, its rulebook and the principal reasons (at most four, most important first). */
+export function adverseActionNotice(decision, input) {
+    if (!input.reasons.length)
+        throw new Error('decisions: an adverse action needs at least one principal reason');
+    return {
+        decision: jcsHash(decision), kind: decision.kind, rulebook: decision.manifest_hash, decided_by: input.decidedBy,
+        principal_reasons: input.reasons.slice(0, 4), rights: input.rights, ts: decision.ts,
+    };
+}
+/**
+ * Selection rate per group and the impact ratio against the most-selected group. Groups
+ * are supplied by the auditor (they never go on the ledger). A ratio under 0.8 is flagged,
+ * the threshold bias audits commonly use.
+ */
+export function disparityReport(outcomes, threshold = 0.8) {
+    const groups = new Map();
+    for (const o of outcomes) {
+        const g = groups.get(o.group) ?? { n: 0, selected: 0 };
+        g.n++;
+        if (o.selected)
+            g.selected++;
+        groups.set(o.group, g);
+    }
+    const rates = [...groups].map(([group, g]) => ({ group, n: g.n, rate: g.n ? g.selected / g.n : 0 }));
+    const best = Math.max(...rates.map((r) => r.rate), 0);
+    return rates.map((r) => ({ ...r, impactRatio: best ? Math.round((r.rate / best) * 1000) / 1000 : null, flagged: best > 0 && r.rate / best < threshold }));
+}
+/** A person asks for a human to review an automated decision. */
+export function humanReviewRequest(input) {
+    return { target: 'decision.review.request', subjectTag: input.subjectTag, payload: { _zr_kind: 'decision.review', v: 1, decision: input.decision, reason: input.reason, ts: input.ts, due: new Date(Date.parse(input.ts) + input.slaDays * 86_400_000).toISOString() } };
+}
+/** Which review requests are answered, pending or overdue. */
+export function reviewStatus(requests, resolutions, now) {
+    return requests.map((r) => {
+        const done = resolutions.find((x) => x.decision === r.decision && x.ts >= String(r.ts));
+        return { decision: r.decision, status: done ? (done.ts <= String(r.due) ? 'answered' : 'answered-late') : now > String(r.due) ? 'overdue' : 'pending', outcome: done?.outcome ?? null };
+    });
+}
+/** How a worker's pay for a period was computed, line by line, and whether it adds up to what was paid. Integer minor units. */
+export function payBreakdown(lines, paid_minor) {
+    const items = lines.map((l) => ({ task: l.task, base_minor: l.base_minor, adjustments: l.adjustments, total_minor: l.base_minor + l.adjustments.reduce((s, a) => s + a.amount_minor, 0) }));
+    const computed = items.reduce((s, i) => s + i.total_minor, 0);
+    return { items, computed_minor: computed, paid_minor, matches: computed === paid_minor, difference_minor: paid_minor - computed };
+}
+/** Everything a worker needs to contest a deactivation or a sanction. */
+export function appealPack(decision, statement, factors) {
+    return {
+        decision: jcsHash(decision), kind: decision.kind, outcome: decision.outcome, rulebook: decision.manifest_hash, ts: decision.ts,
+        factors_commitment: decision.factors_commitment ?? null, factors: factors?.disclosed ?? null, factors_nonce: factors?.nonce ?? null, statement,
+    };
+}
+/**
+ * Which single-factor changes would have flipped the outcome, using the (committed) model
+ * you supply. Each candidate value is tried on its own.
+ */
+export function counterfactuals(model, factors, candidates) {
+    const base = model(factors);
+    const flips = [];
+    for (const [k, values] of Object.entries(candidates)) {
+        for (const v of values)
+            if (model({ ...factors, [k]: v }) !== base)
+                flips.push({ factor: k, from: factors[k], to: v });
+    }
+    return { outcome: base, flips };
+}
+/** Advance notice that a rulebook will change. */
+export function ruleChangeNotice(input) {
+    return { target: 'decision.rulebook.notice', payload: { _zr_kind: 'decision.notice', v: 1, ...input } };
+}
+/** Did the platform give at least `minDays` notice, and did the new rulebook only appear after it took effect? */
+export function noticeCompliance(notice, decisions, minDays) {
+    const gap = (Date.parse(String(notice.effectiveFrom)) - Date.parse(String(notice.ts))) / 86_400_000;
+    const early = decisions.filter((d) => d.manifest_hash === notice.to && String(d.ts) < String(notice.effectiveFrom));
+    return { ok: gap >= minDays && early.length === 0, noticeDays: Math.floor(gap), usedEarly: early.length };
+}
+/** A union or advocate pools members' decision records: rule consistency plus outcomes per kind. */
+export function collectiveAudit(memberDecisions) {
+    const all = memberDecisions.flat();
+    const outcomes = {};
+    for (const d of all)
+        outcomes[String(d.kind)] = (outcomes[String(d.kind)] ?? 0) + 1;
+    return { members: memberDecisions.length, decisions: all.length, consistency: ruleConsistency(all), byKind: outcomes };
+}
+/** A credit decision: rulebook, committed factors and principal reasons. */
+export function creditDecision(input) {
+    const { approved, reasons, ...rest } = input;
+    const receipt = buildDecisionReceipt({ ...rest, kind: 'credit', outcome: { approved, ...(input.outcome ?? {}) } });
+    return { receipt, notice: approved ? null : adverseActionNotice(receipt.payload, { reasons: reasons ?? ['(state the principal reasons)'], decidedBy: 'automated system', rights: 'You may request the reasons and a human review.' }) };
+}
+/** A tenant-screening decision, recorded the same way. */
+export function tenantScreeningDecision(input) {
+    const { accepted, reasons, ...rest } = input;
+    const receipt = buildDecisionReceipt({ ...rest, kind: 'tenant-screening', outcome: { accepted, ...(input.outcome ?? {}) } });
+    return { receipt, notice: accepted ? null : adverseActionNotice(receipt.payload, { reasons: reasons ?? ['(state the principal reasons)'], decidedBy: 'automated system', rights: 'You may request a copy of the report used.' }) };
+}
+//# sourceMappingURL=fairness.js.map

package/dist/fairness.js.map

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

package/dist/index.d.ts

@@ -53,4 +53,5 @@ export interface ConsistencyReport {
  * interleaved window is the red flag a regulator looks for.
  */
 export declare function ruleConsistency(payloads: Array<Record<string, unknown>>): ConsistencyReport;
+export * from './fairness.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CAkB1E;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,aAAa,CAQ1F;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,iGAAiG;IACjG,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,iBAAiB,CA2B3F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,yCAAyC;AACzC,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,kFAAkF;IAClF,YAAY,EAAE,MAAM,CAAC;IACrB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;CACf;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,eAAe,CAkB1E;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,aAAa,CAQ1F;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,iGAAiG;IACjG,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,iBAAiB,CA2B3F;AACD,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -93,4 +93,5 @@ export function ruleConsistency(payloads) {
     }
     return { rulebooks, consistent: reasons.length === 0, reasons };
 }
+export * from './fairness.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zanii/decisions",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Gig/creator algorithmic fairness: decision receipts a worker can audit — completeness (every decision about me, tamper-evident), rule-consistency (the same rulebook decided everyone, via manifest_hash), and committed factors (no post-hoc rationalization). Never claims 'the algorithm is fair'.",
   "license": "Apache-2.0",
   "homepage": "https://ledger.zanii.agency",
@@ -31,8 +31,8 @@
     "vitest": "^3.0.9"
   },
   "dependencies": {
-    "@zanii/subject": "^0.1.2",
-    "@zanii/core": "^0.5.2"
+    "@zanii/core": "^0.5.4",
+    "@zanii/subject": "^0.1.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/src/fairness.ts

@@ -0,0 +1,115 @@
+/**
+ * What people and auditors need around algorithmic decisions: adverse-action notices,
+ * selection-rate disparity (the impact ratio bias audits use), human-review requests with
+ * deadlines, pay breakdowns, appeal packs, counterfactuals, advance notice of rule changes,
+ * collective audits, and credit and tenant-screening decisions.
+ *
+ * Fairness metrics here are arithmetic on outcomes. They flag where to look; they do not
+ * decide whether a system is lawful or fair.
+ */
+import { jcsHash } from '@zanii/core';
+import { buildDecisionReceipt, ruleConsistency, type DecisionInput } from './index.js';
+
+type Payload = Record<string, unknown>;
+
+/** An adverse-action notice: the decision, its rulebook and the principal reasons (at most four, most important first). */
+export function adverseActionNotice(decision: Payload, input: { reasons: string[]; decidedBy: string; rights: string }) {
+  if (!input.reasons.length) throw new Error('decisions: an adverse action needs at least one principal reason');
+  return {
+    decision: jcsHash(decision), kind: decision.kind, rulebook: decision.manifest_hash, decided_by: input.decidedBy,
+    principal_reasons: input.reasons.slice(0, 4), rights: input.rights, ts: decision.ts,
+  };
+}
+
+/**
+ * Selection rate per group and the impact ratio against the most-selected group. Groups
+ * are supplied by the auditor (they never go on the ledger). A ratio under 0.8 is flagged,
+ * the threshold bias audits commonly use.
+ */
+export function disparityReport(outcomes: Array<{ group: string; selected: boolean }>, threshold = 0.8) {
+  const groups = new Map<string, { n: number; selected: number }>();
+  for (const o of outcomes) {
+    const g = groups.get(o.group) ?? { n: 0, selected: 0 };
+    g.n++;
+    if (o.selected) g.selected++;
+    groups.set(o.group, g);
+  }
+  const rates = [...groups].map(([group, g]) => ({ group, n: g.n, rate: g.n ? g.selected / g.n : 0 }));
+  const best = Math.max(...rates.map((r) => r.rate), 0);
+  return rates.map((r) => ({ ...r, impactRatio: best ? Math.round((r.rate / best) * 1000) / 1000 : null, flagged: best > 0 && r.rate / best < threshold }));
+}
+
+/** A person asks for a human to review an automated decision. */
+export function humanReviewRequest(input: { decision: string; subjectTag: string; reason: string; ts: string; slaDays: number }) {
+  return { target: 'decision.review.request', subjectTag: input.subjectTag, payload: { _zr_kind: 'decision.review', v: 1, decision: input.decision, reason: input.reason, ts: input.ts, due: new Date(Date.parse(input.ts) + input.slaDays * 86_400_000).toISOString() } };
+}
+
+/** Which review requests are answered, pending or overdue. */
+export function reviewStatus(requests: Payload[], resolutions: Array<{ decision: string; ts: string; outcome: 'upheld' | 'changed' }>, now: string) {
+  return requests.map((r) => {
+    const done = resolutions.find((x) => x.decision === r.decision && x.ts >= String(r.ts));
+    return { decision: r.decision, status: done ? (done.ts <= String(r.due) ? 'answered' : 'answered-late') : now > String(r.due) ? 'overdue' : 'pending', outcome: done?.outcome ?? null };
+  });
+}
+
+/** How a worker's pay for a period was computed, line by line, and whether it adds up to what was paid. Integer minor units. */
+export function payBreakdown(lines: Array<{ task: string; base_minor: number; adjustments: Array<{ reason: string; amount_minor: number }> }>, paid_minor: number) {
+  const items = lines.map((l) => ({ task: l.task, base_minor: l.base_minor, adjustments: l.adjustments, total_minor: l.base_minor + l.adjustments.reduce((s, a) => s + a.amount_minor, 0) }));
+  const computed = items.reduce((s, i) => s + i.total_minor, 0);
+  return { items, computed_minor: computed, paid_minor, matches: computed === paid_minor, difference_minor: paid_minor - computed };
+}
+
+/** Everything a worker needs to contest a deactivation or a sanction. */
+export function appealPack(decision: Payload, statement: string, factors?: { nonce: string; disclosed?: Record<string, unknown> }) {
+  return {
+    decision: jcsHash(decision), kind: decision.kind, outcome: decision.outcome, rulebook: decision.manifest_hash, ts: decision.ts,
+    factors_commitment: decision.factors_commitment ?? null, factors: factors?.disclosed ?? null, factors_nonce: factors?.nonce ?? null, statement,
+  };
+}
+
+/**
+ * Which single-factor changes would have flipped the outcome, using the (committed) model
+ * you supply. Each candidate value is tried on its own.
+ */
+export function counterfactuals<F extends Record<string, unknown>>(model: (factors: F) => boolean, factors: F, candidates: Partial<Record<keyof F, unknown[]>>) {
+  const base = model(factors);
+  const flips: Array<{ factor: keyof F; from: unknown; to: unknown }> = [];
+  for (const [k, values] of Object.entries(candidates) as Array<[keyof F, unknown[]]>) {
+    for (const v of values) if (model({ ...factors, [k]: v }) !== base) flips.push({ factor: k, from: factors[k], to: v });
+  }
+  return { outcome: base, flips };
+}
+
+/** Advance notice that a rulebook will change. */
+export function ruleChangeNotice(input: { from: string; to: string; effectiveFrom: string; summary: string; ts: string }) {
+  return { target: 'decision.rulebook.notice', payload: { _zr_kind: 'decision.notice', v: 1, ...input } };
+}
+
+/** Did the platform give at least `minDays` notice, and did the new rulebook only appear after it took effect? */
+export function noticeCompliance(notice: Payload, decisions: Payload[], minDays: number) {
+  const gap = (Date.parse(String(notice.effectiveFrom)) - Date.parse(String(notice.ts))) / 86_400_000;
+  const early = decisions.filter((d) => d.manifest_hash === notice.to && String(d.ts) < String(notice.effectiveFrom));
+  return { ok: gap >= minDays && early.length === 0, noticeDays: Math.floor(gap), usedEarly: early.length };
+}
+
+/** A union or advocate pools members' decision records: rule consistency plus outcomes per kind. */
+export function collectiveAudit(memberDecisions: Payload[][]) {
+  const all = memberDecisions.flat();
+  const outcomes: Record<string, number> = {};
+  for (const d of all) outcomes[String(d.kind)] = (outcomes[String(d.kind)] ?? 0) + 1;
+  return { members: memberDecisions.length, decisions: all.length, consistency: ruleConsistency(all), byKind: outcomes };
+}
+
+/** A credit decision: rulebook, committed factors and principal reasons. */
+export function creditDecision(input: Omit<DecisionInput, 'kind'> & { approved: boolean; reasons?: string[] }) {
+  const { approved, reasons, ...rest } = input;
+  const receipt = buildDecisionReceipt({ ...rest, kind: 'credit', outcome: { approved, ...(input.outcome ?? {}) } });
+  return { receipt, notice: approved ? null : adverseActionNotice(receipt.payload, { reasons: reasons ?? ['(state the principal reasons)'], decidedBy: 'automated system', rights: 'You may request the reasons and a human review.' }) };
+}
+
+/** A tenant-screening decision, recorded the same way. */
+export function tenantScreeningDecision(input: Omit<DecisionInput, 'kind'> & { accepted: boolean; reasons?: string[] }) {
+  const { accepted, reasons, ...rest } = input;
+  const receipt = buildDecisionReceipt({ ...rest, kind: 'tenant-screening', outcome: { accepted, ...(input.outcome ?? {}) } });
+  return { receipt, notice: accepted ? null : adverseActionNotice(receipt.payload, { reasons: reasons ?? ['(state the principal reasons)'], decidedBy: 'automated system', rights: 'You may request a copy of the report used.' }) };
+}

package/src/index.ts

@@ -139,3 +139,4 @@ export function ruleConsistency(payloads: Array<Record<string, unknown>>): Consi
   }
   return { rulebooks, consistent: reasons.length === 0, reasons };
 }
+export * from './fairness.js';