@clossys/butler 0.1.1

package/src/validation.ts

@@ -0,0 +1,172 @@
+/**
+ * Shared, dependency-free validation primitives for `schema.ts`. This
+ * package hand-rolls its entity validation rather than depending on a
+ * schema library — see `schema.ts`'s top-level doc comment for why, and
+ * `@clossys/strategist`'s `validation.ts` for the precedent this
+ * file follows: plain type guards over `unknown`, accumulating findings
+ * into an array, never throwing.
+ *
+ * Every `require*` helper below takes the same three leading arguments —
+ * `value` (the candidate, still `unknown`), `path` (an absolute,
+ * human-readable location like `"instructions[2].currency.days"`), and
+ * `issues` (the caller's shared, mutated-in-place array) — and returns
+ * either the narrowed value or `undefined`. A caller never has to inspect
+ * the return value to know whether something went wrong: every failure is
+ * also recorded into `issues` at the moment it is discovered, so the
+ * standard pattern (used throughout `schema.ts`) is to snapshot
+ * `issues.length` before validating an object's fields and compare it
+ * after — if it grew, something in this object failed, regardless of which
+ * field.
+ */
+
+export interface ValidationIssue {
+  /** Absolute, dot/bracket-joined location, e.g. `"intents[0].confidence"`, or `"(root)"` for a whole-value shape problem. */
+  path: string;
+  message: string;
+}
+
+export type ValidationResult<T> = { ok: true; value: T } | { ok: false; issues: ValidationIssue[] };
+
+/** A hand-rolled validator: takes an unknown value, returns a `ValidationResult<T>`. Never throws. */
+export type Validator<T> = (value: unknown) => ValidationResult<T>;
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A closed-vocabulary check. Membership is decided by the caller's own literal list, never by a shape heuristic. */
+export function isOneOf<T extends string>(value: unknown, list: readonly T[]): value is T {
+  return typeof value === "string" && (list as readonly string[]).includes(value);
+}
+
+/** A short, readable description of an arbitrary value for an error message — never the value's full (potentially huge, potentially person-attributable) content. */
+export function describeValue(value: unknown): string {
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `an array (${value.length} item(s))`;
+  const t = typeof value;
+  if (t === "object") return "an object";
+  if (t === "string") return JSON.stringify(value);
+  return String(value);
+}
+
+export function pushIssue(issues: ValidationIssue[], path: string, message: string): void {
+  issues.push({ path, message });
+}
+
+export function requireString(
+  value: unknown,
+  path: string,
+  issues: ValidationIssue[],
+  opts?: { minLength?: number },
+): string | undefined {
+  if (typeof value !== "string") {
+    pushIssue(issues, path, `must be a string, got ${describeValue(value)}`);
+    return undefined;
+  }
+  const minLength = opts?.minLength ?? 0;
+  if (value.trim().length < minLength) {
+    pushIssue(issues, path, `must be at least ${minLength} non-whitespace character(s) long`);
+    return undefined;
+  }
+  return value;
+}
+
+/** Same as `requireString`, except `undefined` is valid (the field is optional) and produces no issue. */
+export function optionalString(
+  value: unknown,
+  path: string,
+  issues: ValidationIssue[],
+  opts?: { minLength?: number },
+): string | undefined {
+  if (value === undefined) return undefined;
+  return requireString(value, path, issues, opts);
+}
+
+/**
+ * A timestamp this package can actually order and subtract. A record whose
+ * time cannot be parsed is a validation failure, never a record silently
+ * treated as "now" — the currency gate's whole job is arithmetic on these
+ * values, and a fabricated one would make an expired instruction read as
+ * current.
+ */
+export function requireTimestamp(value: unknown, path: string, issues: ValidationIssue[]): string | undefined {
+  const asString = requireString(value, path, issues, { minLength: 1 });
+  if (asString === undefined) return undefined;
+  if (Number.isNaN(Date.parse(asString))) {
+    pushIssue(issues, path, `must be a parseable timestamp, got ${describeValue(value)}`);
+    return undefined;
+  }
+  return asString;
+}
+
+/** Same as `requireTimestamp`, except `undefined` is valid (the field is optional) and produces no issue. */
+export function optionalTimestamp(value: unknown, path: string, issues: ValidationIssue[]): string | undefined {
+  if (value === undefined) return undefined;
+  return requireTimestamp(value, path, issues);
+}
+
+export function requireNumber(
+  value: unknown,
+  path: string,
+  issues: ValidationIssue[],
+  opts?: { min?: number; max?: number; integer?: boolean },
+): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    pushIssue(issues, path, `must be a finite number, got ${describeValue(value)}`);
+    return undefined;
+  }
+  if (opts?.integer === true && !Number.isInteger(value)) {
+    pushIssue(issues, path, `must be a whole number, got ${describeValue(value)}`);
+    return undefined;
+  }
+  if (opts?.min !== undefined && value < opts.min) {
+    pushIssue(issues, path, `must be at least ${opts.min}, got ${describeValue(value)}`);
+    return undefined;
+  }
+  if (opts?.max !== undefined && value > opts.max) {
+    pushIssue(issues, path, `must be at most ${opts.max}, got ${describeValue(value)}`);
+    return undefined;
+  }
+  return value;
+}
+
+/** A real boolean, never a truthy string or number — the same discipline the donor's `isGpcSignal` applies to `present`. */
+export function requireBoolean(value: unknown, path: string, issues: ValidationIssue[]): boolean | undefined {
+  if (typeof value !== "boolean") {
+    pushIssue(issues, path, `must be a boolean, got ${describeValue(value)}`);
+    return undefined;
+  }
+  return value;
+}
+
+/**
+ * An array where each item is read by `itemReader` — the same
+ * `(value, path, issues) => T | undefined` shape every function in this
+ * file follows, so an entity's own per-object reader (e.g. `readIntent` in
+ * `schema.ts`) plugs directly into this without an adapter.
+ */
+export function requireArrayOf<T>(
+  value: unknown,
+  path: string,
+  issues: ValidationIssue[],
+  itemReader: (item: unknown, itemPath: string, issues: ValidationIssue[]) => T | undefined,
+): T[] | undefined {
+  if (!Array.isArray(value)) {
+    pushIssue(issues, path, `must be an array, got ${describeValue(value)}`);
+    return undefined;
+  }
+  const out: T[] = [];
+  let ok = true;
+  value.forEach((item, i) => {
+    const result = itemReader(item, `${path}[${i}]`, issues);
+    if (result === undefined) ok = false;
+    else out.push(result);
+  });
+  return ok ? out : undefined;
+}
+
+/** Joins `ValidationIssue[]` into one-line-per-issue text a CLI can print directly. */
+export function summarizeIssues(issues: readonly ValidationIssue[]): string {
+  return issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+}

package/src/web/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @clossys/butler/web — preference-surface state, built entirely on
+ * the root package's pure functions.
+ *
+ * `react`/`react-dom` are OPTIONAL peers of this subpath specifically (see
+ * package.json's `peerDependenciesMeta`) — importing
+ * `@clossys/butler` (the root) or `@clossys/butler/inbound`
+ * never pulls in React; only importing `@clossys/butler/web` does.
+ * This module asserts the installed `react` version against this package's
+ * declared range at import time, so an absent or incompatible React fails
+ * loudly here instead of crashing later inside a hook with no version named
+ * as the cause. See `internal/peer-version.ts` for the guard itself.
+ *
+ * This subpath ships no rendering and no copy. What a preference surface
+ * says to a person, and what it looks like, are the consumer's own values;
+ * what is offered here is the state machine underneath it, including the
+ * structural half of withdrawal parity — see `useStandingWants`.
+ */
+import { version as reactVersion } from "react";
+import { assertPeerVersion } from "./internal/peer-version.js";
+
+/** Must match package.json's `peerDependencies.react` exactly — `peer-guard.test.ts` asserts that directly. */
+export const REACT_DECLARED_RANGE = ">=18";
+assertPeerVersion({ peer: "react", declaredRange: REACT_DECLARED_RANGE, foundVersion: reactVersion });
+
+export { useStandingWants } from "./useStandingWants.js";
+export type { StandingWantsClient, UseStandingWantsOptions, UseStandingWantsResult } from "./useStandingWants.js";

package/src/web/internal/peer-version.ts

@@ -0,0 +1,159 @@
+/**
+ * `assertPeerVersion` — the runtime half of `./web`'s "optional peer, no
+ * install-time signal in either direction" problem. `react`/`react-dom` are
+ * declared `peerDependenciesMeta: { optional: true }` (see package.json) so
+ * a consumer can install `@clossys/butler` (the root, provider-
+ * neutral core) without ever installing React — only `./web` needs it. But
+ * an ABSENT or OUT-OF-RANGE `react` produces no signal of any kind without
+ * this guard: a consumer on an incompatible React version would otherwise
+ * learn about it from whatever `./web` happened to crash on deep inside
+ * React itself, with nothing naming a version range as the cause. See
+ * `web/index.ts`'s own guard call, evaluated once at import time via
+ * `react`'s own exported `version`, for where this is wired in.
+ *
+ * This is the same obligation this repository's own contribution guide
+ * states for every requirement this workspace takes on: requiring a
+ * prerequisite is legitimate; failing silently when it is unmet is not,
+ * because that turns a setup error into a debugging session inside
+ * somebody else's codebase.
+ *
+ * PORTED, NOT SHARED, from `packages/consent/src/web/internal/peer-version.ts`
+ * — identical algorithm, copied rather than imported across a package
+ * boundary for the structural reason that file's own header gives: that
+ * package does not expose this as part of its public API surface, and even
+ * if it did, `@clossys/butler` would gain nothing by taking a real
+ * runtime dependency on a sibling just to reach one shared utility, and its
+ * "zero runtime dependencies" claim would then be wrong. Keep the copies in
+ * sync by hand if the ported range algorithm ever changes.
+ *
+ * DELIBERATELY PURE — NO `node:*` IMPORTS IN THIS FILE. `./web`'s entry
+ * point is reachable from a browser bundle (a client component rendering
+ * a preference surface), not just a Node process, so the version check reads
+ * `react`'s own exported `version` directly rather than any Node-only
+ * fs-based resolver.
+ */
+
+// ------------------------------------------------------------- range parsing
+
+interface Bound {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/** Strict x.y.z only — same as scripts/check-workspace-links.mjs's parseVersion(). */
+function parseVersion(version: string): Bound | null {
+  const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version).trim());
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
+}
+
+function compareVersions(a: Bound, b: Bound): number {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+/**
+ * An exact pin, a caret range, or a tilde range against a plain x.y.z. For
+ * `0.y.z`, BOTH `^` and `~` are minor-locked; above `0.y.z`, `^` is
+ * major-locked and only `~` is minor-locked. Returns `null` —
+ * unparseable — for anything else, including the `>=`/`<` forms
+ * `parseGteForm` below understands instead.
+ */
+function parsePinCaretTilde(range: string): { lower: Bound; upper: Bound } | null {
+  const m = /^(\^|~)?(\d+)\.(\d+)\.(\d+)$/.exec(String(range).trim());
+  if (!m) return null;
+  const prefix = m[1] ?? "";
+  const major = Number(m[2]);
+  const minor = Number(m[3]);
+  const patch = Number(m[4]);
+  if (prefix === "") return { lower: { major, minor, patch }, upper: { major, minor, patch: patch + 1 } };
+  if (major === 0) return { lower: { major, minor, patch }, upper: { major, minor: minor + 1, patch: 0 } };
+  if (prefix === "^") return { lower: { major, minor, patch }, upper: { major: major + 1, minor: 0, patch: 0 } };
+  return { lower: { major, minor, patch }, upper: { major, minor: minor + 1, patch: 0 } }; // "~"
+}
+
+/**
+ * A bounded `>=x[.y[.z]] <a[.b[.c]]>` range or an unbounded `>=x[.y[.z]]`
+ * range — the shape this package's own `peerDependencies` uses for React
+ * (`">=18"`). A version segment omitted from either side defaults to its
+ * lowest value (`18` reads as `18.0.0`), matching ordinary semver range
+ * convention. Returns `null` — unparseable — for anything else.
+ */
+function parseGteForm(range: string): { lower: Bound; upper: Bound | null } | null {
+  const trimmed = String(range).trim();
+  const segment = "(\\d+)(?:\\.(\\d+))?(?:\\.(\\d+))?";
+  const bounded = new RegExp(`^>=\\s*${segment}\\s+<\\s*${segment}$`).exec(trimmed);
+  if (bounded) {
+    const [, lMaj, lMin, lPat, uMaj, uMin, uPat] = bounded;
+    return {
+      lower: { major: Number(lMaj), minor: Number(lMin ?? "0"), patch: Number(lPat ?? "0") },
+      upper: { major: Number(uMaj), minor: Number(uMin ?? "0"), patch: Number(uPat ?? "0") },
+    };
+  }
+  const unbounded = new RegExp(`^>=\\s*${segment}$`).exec(trimmed);
+  if (unbounded) {
+    const [, maj, min, pat] = unbounded;
+    return { lower: { major: Number(maj), minor: Number(min ?? "0"), patch: Number(pat ?? "0") }, upper: null };
+  }
+  return null;
+}
+
+type RangeSatisfaction = { evaluated: true; ok: boolean } | { evaluated: false; reason: string };
+
+/**
+ * Returns `{ evaluated: false, reason }` when either side could not be
+ * parsed — a finding, never assumed satisfied — or `{ evaluated: true, ok
+ * }` once both sides parsed cleanly.
+ */
+function satisfiesRange(versionStr: string, rangeStr: string): RangeSatisfaction {
+  const bound = parsePinCaretTilde(rangeStr) ?? parseGteForm(rangeStr);
+  if (!bound) {
+    return {
+      evaluated: false,
+      reason: `"${rangeStr}" is not a range form this guard parses (an exact pin, ^x.y.z, ~x.y.z, ">=x.y.z <a.b.c>", or ">=x.y.z" are supported)`,
+    };
+  }
+  const version = parseVersion(versionStr);
+  if (!version) {
+    return { evaluated: false, reason: `the installed version "${versionStr}" is not a plain x.y.z semver this guard can compare` };
+  }
+  const geLower = compareVersions(version, bound.lower) >= 0;
+  const ltUpper = bound.upper === null ? true : compareVersions(version, bound.upper) < 0;
+  return { evaluated: true, ok: geLower && ltUpper };
+}
+
+// ------------------------------------------------------------------ the guard
+
+export interface AssertPeerVersionInput {
+  /** The optional peer's package name, e.g. `"react"`. */
+  peer: string;
+  /** This package's own `peerDependencies` range for `peer`. */
+  declaredRange: string;
+  /** The peer's real installed version, or `undefined` if it could not be resolved at all. */
+  foundVersion: string | undefined;
+}
+
+/**
+ * Throws a named, actionable error naming the package, the declared range,
+ * and the version actually found. Never returns a boolean — a guard must
+ * state where control goes when it declines. A missing peer and an
+ * out-of-range peer throw genuinely DIFFERENT messages — "not installed"
+ * and "installed but incompatible" are different problems with different
+ * fixes. An unparseable declared range or installed version is a third,
+ * equally loud error, never an assumed pass.
+ */
+export function assertPeerVersion(input: AssertPeerVersionInput): void {
+  const { peer, declaredRange, foundVersion } = input;
+
+  if (foundVersion === undefined) {
+    throw new Error(`${peer} is required for this import but is not installed. Install ${peer}@"${declaredRange}" — see this package's README for its optional-peer setup.`);
+  }
+
+  const outcome = satisfiesRange(foundVersion, declaredRange);
+  if (!outcome.evaluated) {
+    throw new Error(`Could not verify ${peer}@${foundVersion} against this package's declared range "${declaredRange}": ${outcome.reason}. Refusing to assume this is compatible.`);
+  }
+  if (!outcome.ok) {
+    throw new Error(`${peer}@${foundVersion} is installed, but this package requires ${peer}@"${declaredRange}". Installed but incompatible — install a version of ${peer} that satisfies "${declaredRange}".`);
+  }
+}

package/src/web/useStandingWants.ts

@@ -0,0 +1,139 @@
+import { useCallback, useEffect, useState } from "react";
+import { evaluateStandingInstruction } from "../contract.js";
+import type {
+  CurrencyWindow,
+  PolicyVersion,
+  StandingAction,
+  StandingEvaluation,
+  StandingEvaluationPolicy,
+  StandingInstruction,
+  StandingTopic,
+} from "../schema.js";
+
+/**
+ * The client-side counterpart to `StandingInstructionStore`.
+ *
+ * `StandingInstructionStore` is `Promise`-based host-implemented I/O, most
+ * naturally implemented behind a server boundary — a database read, a
+ * server-side session — that a browser cannot call directly as a plain
+ * async function. A hook that genuinely reads and writes standing
+ * instructions needs a client-shaped port instead: something a browser
+ * really can call, typically a `fetch` to a host-owned route that itself
+ * runs `decideStandingChange` and writes both the instruction and the
+ * audit event server-side. This is that port — still host-implemented,
+ * still carrying no opinion about transport, but shaped for the side of
+ * the boundary that actually runs in a browser.
+ */
+export interface StandingWantsClient {
+  /** Reads every stored instruction for `subjectId`, however the host's own API/storage boundary is reached. */
+  read(subjectId: string): Promise<readonly StandingInstruction[]>;
+  /**
+   * Applies one decided action and returns the durably-stored instruction.
+   * The host is expected to run `decideStandingChange` (or equivalent) on
+   * its own server and write both the instruction and the audit event
+   * before resolving — this hook never computes or stores anything itself.
+   */
+  apply(subjectId: string, action: StandingAction): Promise<StandingInstruction>;
+}
+
+export interface UseStandingWantsOptions {
+  subjectId: string;
+  /** The topics this preference surface manages. Determines the keys of `evaluations`. */
+  topics: readonly StandingTopic[];
+  policyVersion: PolicyVersion;
+  /** The window written onto any instruction this surface decides. No default — see `CurrencyWindow`. */
+  currency: CurrencyWindow;
+  /** No default — see `StandingEvaluationPolicy`; the host must decide this explicitly. */
+  evaluationPolicy: StandingEvaluationPolicy;
+  /** The moment to evaluate currency against, as an ISO timestamp. Supplied by the caller so a surface renders the same answer on the server and on the client rather than drifting with an ambient clock. */
+  now: string;
+  client: StandingWantsClient;
+}
+
+export interface UseStandingWantsResult {
+  /** One evaluation per requested topic. A topic with no stored instruction evaluates to `absent`, never to a falsy value that could read as a denial or as permission. */
+  evaluations: Readonly<Record<StandingTopic, StandingEvaluation>>;
+  /** `true` while the initial `client.read` call is in flight. */
+  loading: boolean;
+  /** The error thrown by the most recent `client.read`/`client.apply` call, if any. Never thrown by this hook itself. */
+  error: unknown;
+  grant(topic: StandingTopic): Promise<void>;
+  deny(topic: StandingTopic): Promise<void>;
+  /**
+   * Withdraw is reachable through the SAME call shape as grant and deny —
+   * one topic, one promise, one function on the same object. That is
+   * withdrawal parity enforced structurally at the API surface, not
+   * asserted in prose: there is no separate, harder-to-reach function and
+   * no extra argument for revoking a want than for giving one. The
+   * `withdrawal-parity` gate measures the same property one layer out, in
+   * a consumer's real interface, where this hook cannot see.
+   */
+  withdraw(topic: StandingTopic): Promise<void>;
+}
+
+/**
+ * Manages a preference surface's standing wants: reads every stored
+ * instruction for `subjectId` once on mount, evaluates each of `topics`
+ * against `policyVersion` AND the supplied `now`, and exposes
+ * `grant`/`deny`/`withdraw` as identically-shaped async functions backed by
+ * the same `client.apply` call.
+ *
+ * The evaluation is currency-aware, which is the whole difference between
+ * this and a hook that reads a row: an instruction that exists, and was
+ * granted, and is a year past its own declared window comes back `stale`,
+ * not `granted`. Rendering a surface off `evaluations` therefore re-asks
+ * on its own rather than quietly continuing to act on an answer nobody has
+ * checked since it was written.
+ */
+export function useStandingWants(options: UseStandingWantsOptions): UseStandingWantsResult {
+  const { subjectId, topics, policyVersion, currency, evaluationPolicy, now, client } = options;
+  const [instructions, setInstructions] = useState<Readonly<Record<StandingTopic, StandingInstruction>>>({});
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<unknown>(undefined);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(undefined);
+    client
+      .read(subjectId)
+      .then((all) => {
+        if (cancelled) return;
+        const byTopic: Record<StandingTopic, StandingInstruction> = {};
+        for (const instruction of all) byTopic[instruction.topic] = instruction;
+        setInstructions(byTopic);
+      })
+      .catch((caught: unknown) => {
+        if (!cancelled) setError(caught);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [client, subjectId]);
+
+  const applyAction = useCallback(
+    async (action: StandingAction) => {
+      try {
+        const instruction = await client.apply(subjectId, action);
+        setInstructions((previous) => ({ ...previous, [instruction.topic]: instruction }));
+      } catch (caught: unknown) {
+        setError(caught);
+      }
+    },
+    [client, subjectId],
+  );
+
+  const grant = useCallback((topic: StandingTopic) => applyAction({ kind: "grant", topic, policyVersion, currency }), [applyAction, policyVersion, currency]);
+  const deny = useCallback((topic: StandingTopic) => applyAction({ kind: "deny", topic, policyVersion, currency }), [applyAction, policyVersion, currency]);
+  const withdraw = useCallback((topic: StandingTopic) => applyAction({ kind: "withdraw", topic, policyVersion, currency }), [applyAction, policyVersion, currency]);
+
+  const evaluations: Record<StandingTopic, StandingEvaluation> = {};
+  for (const topic of topics) {
+    evaluations[topic] = evaluateStandingInstruction(instructions[topic], policyVersion, evaluationPolicy, now);
+  }
+
+  return { evaluations, loading, error, grant, deny, withdraw };
+}