@taasky/protocol 0.0.0-stage → 0.1.1

package/dist/envelope.d.ts

@@ -0,0 +1,32 @@
+export declare const PROTOCOL_VERSION = 1;
+export declare const VERDICTS: readonly ["offer", "counter", "need_more_detail", "approve", "reject", "cancel"];
+export type Verdict = (typeof VERDICTS)[number];
+/** Moves that pass the turn back to the other side without ending the room. */
+export declare const CONTINUING: ReadonlySet<Verdict>;
+/** Moves only a human can release; the agent's request for one waits for them (§8). */
+export declare const HUMAN_GATED: readonly ["approve", "reject", "cancel"];
+export type HumanGatedVerdict = (typeof HUMAN_GATED)[number];
+export declare function isHumanGated(v: Verdict): v is HumanGatedVerdict;
+/** Moves that carry terms, and therefore must carry a subject hash. */
+export declare const CARRIES_TERMS: ReadonlySet<Verdict>;
+export interface Envelope {
+    v: number;
+    room: string;
+    msg: string;
+    from: string;
+    round: number;
+    verdict: Verdict;
+    in_reply_to: string | null;
+    subject_hash: string | null;
+    deadline: string | null;
+    ts: string;
+    subject: Record<string, unknown> | null;
+}
+export declare function isVerdict(x: unknown): x is Verdict;
+/**
+ * Deterministic serialisation for hashing: keys sorted at every level, so two
+ * sides hash identical terms identically. Without this `subject_hash` cannot
+ * be compared across parties and "we agreed" stays an agent's claim (§3).
+ */
+export declare function canonicalize(value: unknown): string;
+export declare function subjectHash(subject: unknown): Promise<string>;

package/dist/envelope.js

@@ -0,0 +1,48 @@
+// The typed half of the protocol (SPEC.md §3). Closed on purpose:
+// the state machine hangs off `verdict`, so it does not grow. `subject` does.
+export const PROTOCOL_VERSION = 1;
+export const VERDICTS = [
+    "offer",
+    "counter",
+    "need_more_detail",
+    "approve",
+    "reject",
+    "cancel",
+];
+/** Moves that pass the turn back to the other side without ending the room. */
+export const CONTINUING = new Set([
+    "offer",
+    "counter",
+    "need_more_detail",
+]);
+/** Moves only a human can release; the agent's request for one waits for them (§8). */
+export const HUMAN_GATED = ["approve", "reject", "cancel"];
+export function isHumanGated(v) {
+    return HUMAN_GATED.includes(v);
+}
+/** Moves that carry terms, and therefore must carry a subject hash. */
+export const CARRIES_TERMS = new Set(["offer", "counter"]);
+export function isVerdict(x) {
+    return typeof x === "string" && VERDICTS.includes(x);
+}
+/**
+ * Deterministic serialisation for hashing: keys sorted at every level, so two
+ * sides hash identical terms identically. Without this `subject_hash` cannot
+ * be compared across parties and "we agreed" stays an agent's claim (§3).
+ */
+export function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalize(v)}`).join(",")}}`;
+}
+export async function subjectHash(subject) {
+    const bytes = new TextEncoder().encode(canonicalize(subject));
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    const hex = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+    return `sha256:${hex}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./envelope.js";
+export * from "./limits.js";
+export * from "./move.js";
+export * from "./state.js";
+export * from "./subject.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// The reference implementation of the Taasky Negotiation Protocol (SPEC.md).
+// Pure functions over plain data: no storage, no transport, no clock of its
+// own. A relay loads a room, asks what a move does, and stores the answer.
+export * from "./envelope.js";
+export * from "./limits.js";
+export * from "./move.js";
+export * from "./state.js";
+export * from "./subject.js";

package/dist/limits.d.ts

@@ -0,0 +1,38 @@
+import { type SubjectSchema } from "./subject.js";
+export interface FieldLimit {
+    /** int: integer; money: {amount, currency}; date: YYYY-MM-DD; timerange: RFC3339, no start before it. */
+    min?: unknown;
+    /** As min; timerange: no end after it. */
+    max?: unknown;
+    /** enum: the values that are acceptable. */
+    one_of?: string[];
+    /** bool: the only acceptable value. */
+    equals?: boolean;
+}
+export type Limits = Record<string, FieldLimit>;
+/** One way a value falls outside a limit. `bound` is shaped like the field's values. */
+export interface Breach {
+    field: string;
+    rule: "below_min" | "above_max" | "not_allowed" | "not_equal" | "other_currency";
+    bound: unknown;
+}
+/** Validates limits against the party's own schema. Unknown fields and loose shapes are refused. */
+export declare function parseLimits(schema: SubjectSchema, raw: unknown): Limits | null;
+/**
+ * Where `subject` falls outside `limits`. `subject` may be in the other
+ * party's shape: a field is checked only where both declare it with the same
+ * type, since that is the only case where "the same field" means anything.
+ */
+export declare function checkLimits(schema: SubjectSchema, limits: Limits | null, subject: Record<string, unknown>, subjectSchema?: SubjectSchema): Breach[];
+/**
+ * The fields on which two parties' limits cannot both be met — empty when
+ * they can, or when nobody limited the same field. Answers yes or no per
+ * field and never says by how much: that is all either side learns.
+ */
+export declare function cannotMeet(a: {
+    schema: SubjectSchema;
+    limits: Limits | null;
+}, b: {
+    schema: SubjectSchema;
+    limits: Limits | null;
+}): string[];

package/dist/limits.js

@@ -0,0 +1,214 @@
+// Private limits (SPEC.md §7): the bounds a party's human set — the most
+// they pay, the earliest they can meet. Only the relay sees them; the other
+// side never does. They do three things the agents cannot be trusted with,
+// because an agent tuned to be agreeable drifts toward any deal:
+//
+//  - an agent's own offer outside its limits is refused before it is sent;
+//  - terms outside them are flagged on the human's confirmation card;
+//  - when both sides set limits on the same field and they cannot meet, both
+//    are told so — without either number — instead of circling forever.
+//
+// Limits are set once, on open or join, and never change: a party that could
+// move its limit and ask again could find the other's number one bit at a time.
+import { minorDigits, SubjectError, } from "./subject.js";
+function fail(path, why) {
+    throw new SubjectError(`${path}: ${why}`);
+}
+const isDate = (v) => typeof v === "string" &&
+    /^\d{4}-\d{2}-\d{2}$/.test(v) &&
+    new Date(`${v}T00:00:00Z`).toISOString().startsWith(v);
+/** A money amount as an integer count of thousandths, so no float decides a comparison. */
+function milli(amount) {
+    const [whole, frac = ""] = amount.split(".");
+    return BigInt(whole + frac.padEnd(3, "0"));
+}
+function parseBound(decl, value, at) {
+    switch (decl.type) {
+        case "int":
+            if (typeof value !== "number" || !Number.isSafeInteger(value))
+                fail(at, "expected integer");
+            return value;
+        case "date":
+            if (!isDate(value))
+                fail(at, "expected a date, YYYY-MM-DD");
+            return value;
+        case "timerange":
+            if (typeof value !== "string" || Number.isNaN(Date.parse(value))) {
+                fail(at, "expected an RFC3339 time");
+            }
+            return value;
+        case "money": {
+            const m = value;
+            if (!m || typeof m !== "object" || typeof m.currency !== "string") {
+                fail(at, "expected {amount, currency}");
+            }
+            if (!/^[A-Z]{3}$/.test(m.currency))
+                fail(at, "currency must be ISO 4217");
+            if (decl.currency && m.currency !== decl.currency)
+                fail(at, `currency must be ${decl.currency}`);
+            const digits = minorDigits(m.currency);
+            const shape = digits ? `^\\d{1,15}(\\.\\d{1,${digits}})?$` : "^\\d{1,15}$";
+            if (typeof m.amount !== "string" || !new RegExp(shape).test(m.amount)) {
+                fail(at, "amount must be a decimal string");
+            }
+            return { amount: m.amount, currency: m.currency };
+        }
+        default:
+            fail(at, `min and max do not apply to ${decl.type} fields`);
+    }
+}
+/** -1, 0 or 1. Money bounds of different currencies never get here. */
+function compare(type, a, b) {
+    let d;
+    if (type === "money") {
+        d = milli(a.amount) - milli(b.amount);
+    }
+    else if (type === "timerange")
+        d = Date.parse(a) - Date.parse(b);
+    else if (type === "int")
+        d = a - b;
+    else
+        d = a < b ? -1 : a > b ? 1 : 0;
+    return d > 0 ? 1 : d < 0 ? -1 : 0;
+}
+const currencyOf = (v) => v?.currency;
+/** Validates limits against the party's own schema. Unknown fields and loose shapes are refused. */
+export function parseLimits(schema, raw) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        fail("limits", "must be an object by field");
+    const limits = {};
+    for (const [field, value] of Object.entries(raw)) {
+        const at = `limits.${field}`;
+        const decl = schema[field];
+        if (!decl)
+            fail(at, "not a field of your subject_schema");
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            fail(at, "must be an object");
+        }
+        const v = value;
+        const keys = Object.keys(v);
+        const allowed = decl.type === "enum" ? ["one_of"] : decl.type === "bool" ? ["equals"] : ["min", "max"];
+        if (decl.type === "string")
+            fail(at, "string fields take no limits");
+        if (keys.length === 0 || !keys.every((k) => allowed.includes(k))) {
+            fail(at, `${decl.type} fields take ${allowed.join(" and/or ")}`);
+        }
+        const limit = {};
+        if (decl.type === "enum") {
+            const one = v.one_of;
+            if (!Array.isArray(one) || one.length === 0 || !one.every((x) => decl.values.includes(x))) {
+                fail(at, "one_of must list values of the field");
+            }
+            limit.one_of = [...new Set(one)];
+        }
+        else if (decl.type === "bool") {
+            if (typeof v.equals !== "boolean")
+                fail(at, "equals must be true or false");
+            limit.equals = v.equals;
+        }
+        else {
+            if ("min" in v)
+                limit.min = parseBound(decl, v.min, `${at}.min`);
+            if ("max" in v)
+                limit.max = parseBound(decl, v.max, `${at}.max`);
+            if (limit.min !== undefined && limit.max !== undefined) {
+                if (decl.type === "money" && currencyOf(limit.min) !== currencyOf(limit.max)) {
+                    fail(at, "min and max must be in the same currency");
+                }
+                if (compare(decl.type, limit.min, limit.max) > 0)
+                    fail(at, "min is above max");
+            }
+        }
+        limits[field] = limit;
+    }
+    return Object.keys(limits).length ? limits : null;
+}
+function breachesOf(type, field, limit, value) {
+    if (Array.isArray(value))
+        return value.flatMap((v) => breachesOf(type, field, limit, v));
+    if (type === "enum") {
+        return limit.one_of && !limit.one_of.includes(value)
+            ? [{ field, rule: "not_allowed", bound: limit.one_of }]
+            : [];
+    }
+    if (type === "bool") {
+        return limit.equals !== undefined && value !== limit.equals
+            ? [{ field, rule: "not_equal", bound: limit.equals }]
+            : [];
+    }
+    const out = [];
+    const bound = limit.min ?? limit.max;
+    if (type === "money" && bound !== undefined && currencyOf(bound) !== currencyOf(value)) {
+        return [{ field, rule: "other_currency", bound }];
+    }
+    // A meeting must lie inside the window: its start no earlier than min,
+    // its end no later than max.
+    const low = type === "timerange" ? value.start : value;
+    const high = type === "timerange" ? value.end : value;
+    if (limit.min !== undefined && compare(type, low, limit.min) < 0) {
+        out.push({ field, rule: "below_min", bound: limit.min });
+    }
+    if (limit.max !== undefined && compare(type, high, limit.max) > 0) {
+        out.push({ field, rule: "above_max", bound: limit.max });
+    }
+    return out;
+}
+/**
+ * Where `subject` falls outside `limits`. `subject` may be in the other
+ * party's shape: a field is checked only where both declare it with the same
+ * type, since that is the only case where "the same field" means anything.
+ */
+export function checkLimits(schema, limits, subject, subjectSchema = schema) {
+    if (!limits)
+        return [];
+    return Object.entries(limits).flatMap(([field, limit]) => {
+        const value = subject[field];
+        const type = schema[field]?.type;
+        if (value === undefined || value === null || !type || subjectSchema[field]?.type !== type) {
+            return [];
+        }
+        return breachesOf(type, field, limit, value);
+    });
+}
+/**
+ * The fields on which two parties' limits cannot both be met — empty when
+ * they can, or when nobody limited the same field. Answers yes or no per
+ * field and never says by how much: that is all either side learns.
+ */
+export function cannotMeet(a, b) {
+    if (!a.limits || !b.limits)
+        return [];
+    const fields = [];
+    for (const [field, la] of Object.entries(a.limits)) {
+        const lb = b.limits[field];
+        const type = a.schema[field]?.type;
+        if (!lb || !type || b.schema[field]?.type !== type)
+            continue;
+        let apart = false;
+        if (type === "enum") {
+            apart = !!la.one_of && !!lb.one_of && !la.one_of.some((v) => lb.one_of.includes(v));
+        }
+        else if (type === "bool") {
+            apart = la.equals !== undefined && lb.equals !== undefined && la.equals !== lb.equals;
+        }
+        else {
+            const bounds = [la.min, la.max, lb.min, lb.max].filter((x) => x !== undefined);
+            // Amounts in two currencies are not comparable; say nothing rather than guess.
+            if (type === "money" && new Set(bounds.map(currencyOf)).size > 1)
+                continue;
+            const pick = (x, y, sign) => x === undefined ? y : y === undefined ? x : compare(type, x, y) * sign >= 0 ? x : y;
+            const low = pick(la.min, lb.min, 1);
+            const high = pick(la.max, lb.max, -1);
+            if (low !== undefined && high !== undefined) {
+                const c = compare(type, low, high);
+                // A meeting needs time between start and end, so an exact touch is no window.
+                apart = type === "timerange" ? c >= 0 : c > 0;
+            }
+        }
+        if (apart)
+            fields.push(field);
+    }
+    return fields;
+}

package/dist/move.d.ts

@@ -0,0 +1,47 @@
+import { type Verdict } from "./envelope.js";
+import { type RoomView } from "./state.js";
+import { type SubjectSchema } from "./subject.js";
+export interface MoveParty {
+    id: string;
+    subject_schema: SubjectSchema;
+}
+export interface MoveHistoryItem {
+    id: string;
+    seq: number;
+    from_id: string;
+    verdict: string;
+    subject_hash: string | null;
+}
+export interface MoveRequest {
+    actor: string;
+    verdict: Verdict;
+    /** offer / counter only. */
+    subject?: unknown;
+    /** approve only: the hash of the terms being approved, as the actor read them. */
+    subject_hash?: string;
+    deadline?: string | null;
+}
+export interface MovePlan {
+    message: {
+        verdict: Verdict;
+        in_reply_to: string | null;
+        subject_hash: string | null;
+        subject: Record<string, unknown> | null;
+        deadline: string | null;
+    };
+    next: Omit<RoomView, "id">;
+}
+/** How many moves in a row without new terms count as going in circles. */
+export declare const CIRCLE_WINDOW = 4;
+/**
+ * The room is going in circles: the last CIRCLE_WINDOW moves were all
+ * counters or requests for detail, and none of them tabled terms that were
+ * not on the table before — two sides restating their positions, or asking
+ * each other the same thing. Two agents whose humans' bounds never meet do
+ * this forever, and neither can say so without giving its bound away.
+ * Tiny concessions (100 → 99.99) are new terms and do not count.
+ */
+export declare function isCircling<T extends MoveHistoryItem>(history: readonly T[]): boolean;
+/** The last move that put terms on the table, if any. */
+export declare function termsOnTable<T extends MoveHistoryItem>(history: readonly T[]): T | null;
+export declare function planMove(room: RoomView, parties: readonly MoveParty[], history: readonly MoveHistoryItem[], req: MoveRequest, now: Date): Promise<MovePlan>;

package/dist/move.js

@@ -0,0 +1,118 @@
+// What a move does to a room (SPEC.md §3, §5), decided without touching
+// storage. The caller loads the room, asks for a plan, and writes it only if
+// the room has not changed in between.
+import { CARRIES_TERMS, subjectHash } from "./envelope.js";
+import { assertMoveAllowed, MoveError, nextState } from "./state.js";
+import { validateSubject } from "./subject.js";
+/** How many moves in a row without new terms count as going in circles. */
+export const CIRCLE_WINDOW = 4;
+/**
+ * The room is going in circles: the last CIRCLE_WINDOW moves were all
+ * counters or requests for detail, and none of them tabled terms that were
+ * not on the table before — two sides restating their positions, or asking
+ * each other the same thing. Two agents whose humans' bounds never meet do
+ * this forever, and neither can say so without giving its bound away.
+ * Tiny concessions (100 → 99.99) are new terms and do not count.
+ */
+export function isCircling(history) {
+    const recent = history.slice(-CIRCLE_WINDOW);
+    if (recent.length < CIRCLE_WINDOW)
+        return false;
+    if (!recent.every((m) => m.verdict === "counter" || m.verdict === "need_more_detail")) {
+        return false;
+    }
+    const seen = new Set(history.slice(0, -CIRCLE_WINDOW).map((m) => m.subject_hash));
+    return recent.every((m) => !m.subject_hash || seen.has(m.subject_hash));
+}
+/** The last move that put terms on the table, if any. */
+export function termsOnTable(history) {
+    for (let i = history.length - 1; i >= 0; i--) {
+        if (CARRIES_TERMS.has(history[i].verdict))
+            return history[i];
+    }
+    return null;
+}
+export async function planMove(room, parties, history, req, now) {
+    const actor = parties.find((p) => p.id === req.actor);
+    if (!actor)
+        throw new MoveError("you do not take part in this room");
+    assertMoveAllowed(room, req.actor, req.verdict, now);
+    const deadline = req.deadline ?? null;
+    if (deadline !== null) {
+        const at = Date.parse(deadline);
+        if (Number.isNaN(at))
+            throw new MoveError("deadline must be RFC3339");
+        if (at <= now.getTime())
+            throw new MoveError("deadline must be in the future");
+    }
+    const terms = termsOnTable(history);
+    const last = history.at(-1) ?? null;
+    const carriesTerms = CARRIES_TERMS.has(req.verdict);
+    if (!carriesTerms && req.subject !== undefined) {
+        throw new MoveError(`${req.verdict} carries no terms; leave subject out`);
+    }
+    if (req.verdict !== "approve" && req.subject_hash !== undefined) {
+        throw new MoveError("subject_hash is only given with approve");
+    }
+    let subject = null;
+    let hash = null;
+    let inReplyTo = last?.id ?? null;
+    let bothApproved = false;
+    switch (req.verdict) {
+        case "offer":
+        case "counter":
+            if (req.verdict === "offer" && terms) {
+                throw new MoveError("terms are already on the table; answer them with counter");
+            }
+            if (req.verdict === "counter" && !terms) {
+                throw new MoveError("nothing to counter yet; open with offer");
+            }
+            if (req.subject === undefined)
+                throw new MoveError(`${req.verdict} needs a subject`);
+            // A party's terms conform to the shape that party declared (§4).
+            subject = validateSubject(actor.subject_schema, req.subject);
+            hash = await subjectHash(subject);
+            break;
+        case "need_more_detail":
+            if (!terms)
+                throw new MoveError("nothing to ask about yet; open with offer");
+            break;
+        case "approve": {
+            if (!terms)
+                throw new MoveError("no terms on the table to approve");
+            if (req.subject_hash === undefined) {
+                throw new MoveError("approve must name the subject_hash of the terms it accepts");
+            }
+            if (req.subject_hash !== terms.subject_hash) {
+                throw new MoveError("subject_hash does not match the terms on the table; re-read the room");
+            }
+            hash = terms.subject_hash;
+            inReplyTo = terms.id;
+            // Agreement is two approvals of the same terms (§5). Only approvals made
+            // after those terms were tabled count — an approval of an earlier,
+            // identical offer was answered by a counter in between.
+            bothApproved = history.some((m) => m.seq > terms.seq &&
+                m.verdict === "approve" &&
+                m.subject_hash === hash &&
+                m.from_id !== req.actor);
+            break;
+        }
+        case "reject":
+        case "cancel":
+            break;
+    }
+    return {
+        message: {
+            verdict: req.verdict,
+            in_reply_to: inReplyTo,
+            subject_hash: hash,
+            subject,
+            deadline,
+        },
+        next: nextState(room, req.verdict, {
+            bothApproved,
+            participants: parties.map((p) => p.id),
+            deadline,
+        }),
+    };
+}

package/dist/state.d.ts

@@ -0,0 +1,35 @@
+import { type Verdict } from "./envelope.js";
+export type RoomState = "draft" | "awaiting" | "agreed" | "closed" | "expired";
+export declare class MoveError extends Error {
+}
+export interface RoomView {
+    id: string;
+    state: RoomState;
+    round: number;
+    turn: string | null;
+    deadline: string | null;
+}
+export declare function isTerminal(state: RoomState): boolean;
+/** A live room whose deadline has passed is expired, whether or not it is stored as such yet (§6). */
+export declare function isOverdue(room: RoomView, now: Date): boolean;
+/** The room as it stands at `now`: an overdue room reads as expired (§6). */
+export declare function asOf<R extends RoomView>(room: R, now: Date): R;
+/**
+ * Whether `actor` may play `verdict` right now. Rejects rather than repairs —
+ * the caller surfaces the reason to the agent, which surfaces it to its human.
+ */
+export declare function assertMoveAllowed(room: RoomView, actor: string, verdict: Verdict, now: Date): void;
+/**
+ * The room after a move. `approve` alone is not agreement: both sides must
+ * approve the same terms, which the caller checks by subject_hash (§3).
+ *
+ * `participants` holds both parties' ids. RoomView does not carry them, so the
+ * caller supplies them — without that the turn cannot be passed on.
+ *
+ * `deadline` is the mover's; a live room takes it over, replacing the last one.
+ */
+export declare function nextState(room: RoomView, verdict: Verdict, opts: {
+    bothApproved: boolean;
+    participants: readonly string[];
+    deadline: string | null;
+}): Omit<RoomView, "id">;

package/dist/state.js

@@ -0,0 +1,76 @@
+// SPEC.md §5. Terminal states are terminal; a new negotiation is a new room.
+import { CONTINUING } from "./envelope.js";
+export class MoveError extends Error {
+}
+export function isTerminal(state) {
+    return state === "agreed" || state === "closed" || state === "expired";
+}
+/** A live room whose deadline has passed is expired, whether or not it is stored as such yet (§6). */
+export function isOverdue(room, now) {
+    return (!isTerminal(room.state) && room.deadline !== null && Date.parse(room.deadline) <= now.getTime());
+}
+/** The room as it stands at `now`: an overdue room reads as expired (§6). */
+export function asOf(room, now) {
+    return isOverdue(room, now) ? { ...room, state: "expired", turn: null } : room;
+}
+/**
+ * Whether `actor` may play `verdict` right now. Rejects rather than repairs —
+ * the caller surfaces the reason to the agent, which surfaces it to its human.
+ */
+export function assertMoveAllowed(room, actor, verdict, now) {
+    if (isTerminal(room.state)) {
+        throw new MoveError(`room is ${room.state} and accepts no further moves`);
+    }
+    if (room.state === "draft") {
+        throw new MoveError("peer has not joined yet");
+    }
+    if (room.turn !== actor && verdict !== "cancel") {
+        throw new MoveError("not your turn");
+    }
+    if (isOverdue(room, now)) {
+        throw new MoveError("deadline has passed; the room is expired");
+    }
+}
+/**
+ * The room after a move. `approve` alone is not agreement: both sides must
+ * approve the same terms, which the caller checks by subject_hash (§3).
+ *
+ * `participants` holds both parties' ids. RoomView does not carry them, so the
+ * caller supplies them — without that the turn cannot be passed on.
+ *
+ * `deadline` is the mover's; a live room takes it over, replacing the last one.
+ */
+export function nextState(room, verdict, opts) {
+    if (verdict === "reject" || verdict === "cancel") {
+        return { state: "closed", round: room.round, turn: null, deadline: room.deadline };
+    }
+    const { deadline } = opts;
+    if (verdict === "approve") {
+        return opts.bothApproved
+            ? { state: "agreed", round: room.round, turn: null, deadline }
+            : {
+                state: "awaiting",
+                round: room.round,
+                turn: otherThan(opts.participants, room.turn),
+                deadline,
+            };
+    }
+    if (CONTINUING.has(verdict)) {
+        return {
+            state: "awaiting",
+            round: room.round + 1,
+            turn: otherThan(opts.participants, room.turn),
+            deadline,
+        };
+    }
+    throw new MoveError(`unhandled verdict ${verdict}`);
+}
+// Two parties per room in v1 (SPEC.md §1 non-goals), so "the other one"
+// is well defined. A live room with a null turn is one nobody can move in, so
+// refuse the move rather than write that state.
+function otherThan(participants, current) {
+    if (participants.length !== 2 || current === null || !participants.includes(current)) {
+        throw new MoveError("room does not have two parties with a defined turn");
+    }
+    return participants.find((p) => p !== current);
+}

package/dist/subject.d.ts

@@ -0,0 +1,23 @@
+export type FieldType = "string" | "int" | "bool" | "timerange" | "enum" | "money" | "date";
+export interface FieldDecl {
+    type: FieldType;
+    /** Shown to a human. Written by the counterparty — render as untrusted (§4.3). */
+    label: string;
+    optional?: boolean;
+    /** `enum` only. */
+    values?: string[];
+    /** `money` only: fixes the currency (ISO 4217) when the field has one. */
+    currency?: string;
+    /** `string` only; hard cap regardless. */
+    max_len?: number;
+    /** Wrap the declared type in an array. */
+    repeated?: boolean;
+}
+export type SubjectSchema = Record<string, FieldDecl>;
+export declare class SubjectError extends Error {
+}
+export declare function parseSchema(raw: unknown): SubjectSchema;
+/** Digits after the point for a currency: 2 for EUR, 0 for JPY, 3 for KWD. */
+export declare function minorDigits(currency: string): number;
+/** Validates a subject against a declared schema. Throws on the first problem. */
+export declare function validateSubject(schema: SubjectSchema, subject: unknown): Record<string, unknown>;