@clossys/butler 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this package are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.1] - 2026-08-30
+
+### Changed
+
+- Updated the package's public repository, issue-tracker, and homepage metadata to the canonical Foundry repository. This change is not a publication or qualification claim.
+
+## [0.1.0] - 2026-08-21
+
+First release. This package is the butler role: everything about what a
+person wants, now and standing.
+
+This changelog starts here rather than carrying either donor's history,
+which cites decisions and issues that would mean nothing — or the wrong
+thing — to a reader who arrives at this package first.
+
+### Added
+
+- A want schema in three states, not two: `absent`, `denied`, and
+  `granted`, plus a `stale` evaluation status that is computed and never
+  stored. Absence is a value, so it can never be read as permission.
+- `evaluateStandingInstruction`, which compares one stored answer against
+  the policy version in force **and** the clock. A row that exists, says
+  `granted`, and is a year past its own declared window comes back `stale`.
+- `decideStandingChange` plus `recordReopened` and `recordStaleness`: the
+  pure decision core and the audit-event builders. Actor and subject are
+  separate parameters and separate fields, always, and
+  `src/audit-shape.check.ts` fails the build if the audit event ever gains
+  a personal-data-shaped key or loses that separation.
+- Three gates, all reachable from the single `butler-check` bin:
+  `confirmation-completeness`, `currency`, and `withdrawal-parity`. Each
+  dispatches on `argv[0]` matching exactly — never on
+  `basename(process.argv[1])`, which would see `cli.js` and silently run
+  the wrong command wherever a gate is invoked by compiled path.
+- The `0` / `1` / `2` exit contract, with `2` reachable on every gate by
+  more than one route — an unreadable or invalid record store, an empty
+  record set, a required declared value that was not supplied, and no gate
+  selected at all — and each route tested. A bare `butler-check` exits `2`:
+  nothing was selected, so nothing was checked. Only an explicitly
+  requested `--help` exits `0`.
+- An `./inbound` subpath: admission on any channel as a pure function of
+  the caller's own signature verification and a host ledger's dedupe
+  answer. An unreachable ledger rejects rather than acknowledging, because
+  acking an event whose dedupe never ran would silently discard it.
+- A `./web` subpath: `useStandingWants`, a currency-aware preference-surface
+  hook whose `withdraw` shares `grant`'s and `deny`'s exact call shape.
+  React is an optional peer, asserted at import time by `assertPeerVersion`
+  so an absent or incompatible version fails loudly and by name.
+- **The published tarball carries this changelog.** `files` includes
+  `CHANGELOG.md`: a consumer reading the installed package should not have
+  to leave it to find out what changed.
+
+### Design notes
+
+- **Confidence is a first-class value with a declared floor.** An intent
+  carries its confidence on the record, and the floor is supplied by the
+  caller with no default anywhere in this package. A reading below the
+  floor may be confirmed or handed off; what it may never be is acted on
+  silently, and `handed-off` is a first-class disposition precisely so
+  declining to act is representable as a decision rather than as an
+  absence of one.
+- **An inferred standing instruction is not binding until confirmed.** It
+  evaluates to `absent`, with its own reason, so relying on it is a
+  finding rather than a pass.
+- **The currency window has no default.** A window this package invented
+  would be this package authoring one of the consumer's own values, and a
+  missing window silently read as "forever" is the open loop the currency
+  gate exists to close.
+- **`invalidateDenialOnPolicyBump` has no default in either direction.**
+  Whether a policy bump invalidates a prior refusal is a jurisdiction
+  judgment, and this package answers no jurisdiction questions.
+
+### Not included
+
+- No topic vocabulary, no jurisdiction logic, no obligations, and no
+  values of any kind. Storage and audit are host-supplied ports and no
+  implementation of either ships here. No claim of legal compliance is
+  made anywhere.
+- No person-attributable record is written into this repository. `subjectId`
+  and `actorId` are opaque host-owned references carrying no email, name,
+  phone number, address, or IP.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calvin Hung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,260 @@
+# @clossys/butler
+
+**Everything about what a person wants — now, and standing.**
+
+The question this role answers, and no other role does:
+
+> Do we have what this person wants — this request in their own
+> confirmation, and their standing instructions, still current?
+
+Ships the schema and the checkers; every consumer authors its own values.
+
+## The loop this closes
+
+A stated want is the setpoint. Acting on it is the act. Reading the
+interpretation back, and asking whether the standing answer is still
+current, is the observation. Unconfirmed intents and expired instructions
+are the comparison. Re-asking is the correction.
+
+A preference written to a row and never re-checked has no observation and
+no comparison. It is an open loop, and closing it is the reason this
+package exists.
+
+## The defect this exists to prevent
+
+A weaker tool checks that a consent row **exists**. It passes on a row
+three policy versions old, and on a row a year past the window its own
+author declared, because a boolean read of "granted" cannot see age.
+Presence is not currency.
+
+Two rules follow, and both are structural here rather than advisory:
+
+1. **Consent is three states, never two.** `absent` (never asked) is a
+   distinct value from `denied` (asked, refused), and neither is a boolean.
+   Absence can therefore never be read as permission — including when the
+   record store is unreachable, when the subject was never asked, and when
+   the only thing on file is an inference nobody confirmed.
+2. **A gate that cannot run must say so.** `butler-check` exits `2` when
+   the record store cannot be read or there was nothing to scan, and `2` is
+   never collapsed into `0` or `1`.
+
+## Install
+
+```bash
+npm install @clossys/butler
+```
+
+Installing from this registry needs a GitHub personal access token with
+`read:packages` — see the repository root README.
+
+```ts
+import { checkCurrency, evaluateStandingInstruction } from "@clossys/butler";
+```
+
+## The three gates
+
+All three are reachable from one installed bin, `butler-check`, dispatched
+on the first argument matching a gate name exactly.
+
+```bash
+butler-check confirmation-completeness ./intents.json ./confirmations.json --floor 0.8
+butler-check currency ./instructions.json ./usages.json --invalidate-denial-on-policy-bump false
+butler-check withdrawal-parity ./paths.json
+```
+
+### `confirmation-completeness`
+
+Every acted-on intent has the subject's own confirmation record, or an
+explicit below-floor hand-off. It fails on an intent dispositioned `acted`
+with no confirmation at all, on one acted against a `misread` or `unclear`
+read-back, on a reading below the declared floor acted on with neither a
+hand-off nor a confirmation, and on a read-back answering an intent outside
+the set being checked.
+
+`--floor` is required and has no default. The number below which a reading
+is too weak to act on is one of the consumer's own values.
+
+### `currency`
+
+No standing instruction is used past its declared window. It reads
+**usages**, not instructions alone: a set of instructions nobody relies on
+proves nothing, while a usage record is the loop actually being closed or
+not. Each usage carries the policy version in force at the moment it
+happened, so the gate replays a real decision rather than re-deriving one
+against today's policy. It fails on a usage past the window, on a usage
+after the answered policy version was superseded, on a usage of an
+instruction with no answer on record — including an unconfirmed inference —
+and on a usage naming an instruction outside the set being checked.
+
+`--invalidate-denial-on-policy-bump` is required and has no default in
+either direction. Whether a policy bump also invalidates a prior refusal is
+a jurisdiction judgment this package does not make.
+
+### `withdrawal-parity`
+
+Withdrawing is no harder than granting. It compares the grant route and the
+withdraw route a consumer measured itself, using three coarse countable
+facts rather than a score, and fails when withdrawing takes more steps,
+demands contacting a human that granting did not, demands an account that
+granting did not, or is not offered at all.
+
+Reopening is not a degraded path, and this gate is only the measurement
+half of that. The API half is structural and lives in `./web`.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Ran against a non-empty record set and found nothing. |
+| `1` | Ran and found at least one real violation. |
+| `2` | Could not run: a missing, unreadable, unparseable or schema-invalid record store; an empty record set; a required declared value that was not supplied; or no gate selected at all. |
+
+`2` is not a variant of failure. "I checked and it is fine" and "I never
+checked" are different answers, and a gate that reports the second as the
+first is worse than no gate.
+
+A bare `butler-check` with no subcommand exits `2`, not `0`. Nothing was
+selected, so nothing was checked, and a CI step with a dropped argument
+must go red rather than green on the strength of having examined nothing.
+An explicitly requested `--help` is the one exception, and exits `0`,
+because asking for help is a run that did exactly what was asked.
+
+## API
+
+Everything below is exported from the package root.
+
+### Evaluating and deciding
+
+| Export | What it does |
+| --- | --- |
+| `evaluateStandingInstruction` | Compares one stored answer against the policy version in force and the clock. Returns `granted`, `denied`, `absent`, or `stale`. |
+| `decideStandingChange` | The pure decision core for one change: returns the new instruction and its audit event. Takes the actor and the subject as separate arguments. |
+| `recordReopened` | Builds the audit event for a subject reopening their preference surface, independent of any decision made inside it. |
+| `recordStaleness` | Builds the audit event for an answer found stale, with the reason as the event type. |
+
+### The gates, as pure functions
+
+| Export | What it does |
+| --- | --- |
+| `checkConfirmationCompleteness` | Gate 1, over intents, confirmations, and a declared floor. |
+| `checkCurrency` | Gate 2, over instructions, usages, and the caller's denial-invalidation decision. |
+| `checkWithdrawalParity` | Gate 3, over measured preference paths. |
+
+### Validators and guards
+
+| Export | What it does |
+| --- | --- |
+| `validateStandingInstruction` | Validates one untyped standing instruction. |
+| `validateStandingInstructions` | Validates an untyped array of them. |
+| `validateIntentRecord` | Validates one untyped intent. |
+| `validateIntentRecords` | Validates an untyped array of them. |
+| `validateConfirmationRecord` | Validates one untyped read-back answer. |
+| `validateConfirmationRecords` | Validates an untyped array of them. |
+| `validateInstructionUsages` | Validates an untyped array of usage records. |
+| `validatePreferencePaths` | Validates an untyped array of measured preference paths. |
+| `validateConfidenceFloor` | Validates a declared confidence floor. |
+| `validatePolicyVersion` | Validates a policy-version reference. |
+| `isStandingInstruction` | Boolean guard over `validateStandingInstruction`. |
+| `isIntentRecord` | Boolean guard over `validateIntentRecord`. |
+| `isConfirmationRecord` | Boolean guard over `validateConfirmationRecord`. |
+
+### Vocabularies
+
+`STANDING_PROVENANCES`, `INTENT_DISPOSITIONS`, `CONFIRMATION_VERDICTS`, and
+`STANDING_AUDIT_EVENT_TYPES` are the closed lists a caller validating
+untyped input needs.
+
+### Types
+
+The record types are `StandingInstruction`, `StandingState`,
+`StandingTopic`, `StandingProvenance`, `CurrencyWindow`, `PolicyVersion`,
+`IntentRecord`, `IntentDisposition`, `ConfirmationRecord`,
+`ConfirmationVerdict`, `ConfidenceFloor`, `InstructionUsage`,
+`PreferencePath` and `PathCost`.
+
+The evaluation and decision types are `StandingEvaluation`,
+`StandingEvaluationPolicy`, `StandingAction`, `StandingAuditEvent` and
+`StandingAuditEventType`.
+
+The host-implemented ports are `StandingInstructionStore` and
+`StandingAuditLedger`. No implementation of either ships here.
+
+Each gate returns its own result type — `ConfirmationCompletenessResult`,
+`CurrencyResult`, `WithdrawalParityResult` — carrying findings typed as
+`ConfirmationFinding`, `CurrencyFinding` and `WithdrawalParityFinding`,
+whose kinds are `ConfirmationFindingKind`, `CurrencyFindingKind` and
+`WithdrawalParityFindingKind`, and whose non-clean outcomes are named by
+`ConfirmationFailureReason`, `CurrencyFailureReason` and
+`WithdrawalParityFailureReason`.
+
+Validation surfaces `ValidationIssue`, `ValidationResult` and `Validator`.
+
+## The `./inbound` subpath
+
+Admission on any channel, and deliberately not an HTTP handler. The
+consumer owns the route, the raw body, and signature verification —
+signature schemes are provider-specific and this package must not pretend
+to verify what it cannot exercise. This package owns the admission
+decision: dedupe, ack/reject doctrine, replay tolerance, and ordering
+tolerance, as a pure function of the caller's own verification result plus
+a host ledger's dedupe answer.
+
+```ts
+import { admitInboundEvent } from "@clossys/butler/inbound";
+```
+
+The decision is never a bare boolean: acknowledging and processing are two
+separate questions. A replay is an acknowledgement with `action: "ignore"`,
+never an error. A rejection is reserved for a failed signature, so a
+provider is never told to keep retrying data that will never become
+processable. And a throwing ledger rejects the promise rather than
+acknowledging — if durable dedupe could not run, nothing was durably
+accepted, and saying otherwise would silently discard an event.
+
+## The `./web` subpath
+
+`useStandingWants` is a currency-aware preference-surface hook: it reads
+every stored instruction for a subject once, then evaluates each requested
+topic against the policy version in force and a caller-supplied `now`. An
+instruction that exists, and was granted, and is past its own window comes
+back `stale`, so a surface rendered from it re-asks rather than quietly
+continuing.
+
+```ts
+import { useStandingWants } from "@clossys/butler/web";
+```
+
+`withdraw` shares `grant`'s and `deny`'s exact call shape — one topic, one
+promise, one function on the same object. That is withdrawal parity
+enforced structurally at the API surface rather than asserted in prose.
+
+React and React DOM are optional peers of this subpath specifically.
+Importing the package root or `./inbound` never pulls in React. Importing
+`./web` asserts the installed version against the declared range at import
+time, so an absent or incompatible React fails loudly, by name, instead of
+crashing later inside a hook with no version named as the cause.
+
+## Requirements
+
+Node 20 or newer. Zero runtime dependencies. React and React DOM are
+optional peers, needed only by the `./web` subpath.
+
+## What this package is not
+
+- It carries no topics, no confidence floor, no currency window, no
+  jurisdiction logic, and no obligations. Every one of those is a value,
+  and values belong in each consumer's own repository.
+- It makes **no claim of legal compliance**. It is record machinery, not
+  advice.
+- It ships no storage and no audit implementation. Both are ports the host
+  implements, and no person-attributable record is written into this
+  repository.
+- `subjectId` and `actorId` are opaque host-owned references. Neither ever
+  carries an email address, a name, a phone number, an address, or an IP,
+  and they are separate identifiers in every signature — an actor recording
+  a subject's own decision and an actor deciding on a subject's behalf must
+  stay distinguishable in the audit trail.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/dist/audit-shape.check.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compile-time proof that `StandingAuditEvent` (`./schema.ts`) carries no
+ * raw personal-data field — no email, name, phone, address, or IP — only
+ * the opaque `subjectId` and the separately-opaque `actorId`.
+ *
+ * Named `*.check.ts`, not `*.test.ts`, so it is part of the REAL `tsc` run
+ * (`npm run typecheck`) rather than only being transpiled, never
+ * type-checked, by vitest — see this repository's own contribution
+ * guide, "Type-level assertions live in `.check.ts(x)` files" entry, and
+ * `scripts/check-typechecked-assertions.mjs` for the gate that enforces it.
+ * Nothing here is ever imported by `index.ts` or any runtime code; its only
+ * job is to fail `tsc` if the contract regresses.
+ *
+ * `ExactKeys` fails to compile unless `Keys` is EXACTLY the allowed set —
+ * neither a subset (a required field silently dropped) nor a superset (a
+ * new field silently added, personal-data-shaped or not, without a human
+ * deciding it belongs here).
+ *
+ * `subjectId` and `actorId` are both in the allowed set, deliberately and
+ * separately. Merging them into one id would still pass a personal-data
+ * scan and would still be wrong: the whole point of this package is
+ * telling "the person asked for this" apart from "something acted on its
+ * own reading", and a single conflated identifier makes that distinction
+ * unrecoverable after the fact.
+ */
+import type { StandingAuditEvent } from "./schema.js";
+type ExactKeys<Keys extends string, Allowed extends string> = [Allowed] extends [Keys] ? ([Keys] extends [Allowed] ? true : never) : never;
+declare const ALLOWED_KEYS: readonly ["subjectId", "actorId", "topic", "type", "policyVersion", "occurredAt", "previousPolicyVersion"];
+type AllowedKey = (typeof ALLOWED_KEYS)[number];
+export declare const auditEventKeysAreExactlyTheAllowedSet: ExactKeys<keyof StandingAuditEvent, AllowedKey>;
+export {};
+//# sourceMappingURL=audit-shape.check.d.ts.map

package/dist/audit-shape.check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-shape.check.d.ts","sourceRoot":"","sources":["../src/audit-shape.check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,KAAK,SAAS,CAAC,IAAI,SAAS,MAAM,EAAE,OAAO,SAAS,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,KAAK,CAAC;AAE3I,QAAA,MAAM,YAAY,4GAA6G,CAAC;AAChI,KAAK,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAMhD,eAAO,MAAM,qCAAqC,EAAE,SAAS,CAAC,MAAM,kBAAkB,EAAE,UAAU,CAAQ,CAAC"}

package/dist/audit-shape.check.js

@@ -0,0 +1,7 @@
+const ALLOWED_KEYS = ["subjectId", "actorId", "topic", "type", "policyVersion", "occurredAt", "previousPolicyVersion"];
+// If `StandingAuditEvent` ever gains or loses a key relative to
+// `ALLOWED_KEYS` above, this assignment stops compiling — including if
+// someone adds an `email`, `name`, `ip`, `phone`, or `address`-shaped
+// field, and including if `actorId` is ever folded into `subjectId`.
+export const auditEventKeysAreExactlyTheAllowedSet = true;
+//# sourceMappingURL=audit-shape.check.js.map

package/dist/audit-shape.check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-shape.check.js","sourceRoot":"","sources":["../src/audit-shape.check.ts"],"names":[],"mappings":"AA6BA,MAAM,YAAY,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,YAAY,EAAE,uBAAuB,CAAU,CAAC;AAGhI,gEAAgE;AAChE,uEAAuE;AACvE,sEAAsE;AACtE,qEAAqE;AACrE,MAAM,CAAC,MAAM,qCAAqC,GAAoD,IAAI,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * `butler-check` — one bin, three gates, dispatched on `argv[0]` matching a
+ * subcommand name EXACTLY.
+ *
+ * Dispatch is on `argv[0]`, never on `basename(process.argv[1])`. A bin-name
+ * dispatch would see `cli.js` wherever this gate is invoked by its compiled
+ * path — which is exactly how this repository's own `npm run check` invokes
+ * other packages' gates — and would silently run the wrong command, or none.
+ *
+ * Presentation only: parse argv, load JSON files, run the pure checkers in
+ * `contract.ts`, print a report, pick an exit code. Every decision worth
+ * testing lives in `contract.ts` and is tested there directly, against
+ * plain values, with no filesystem involved.
+ *
+ * EXIT CODES — the contract a consumer's CI depends on (this repository's
+ * own contribution guide, "Gate CLIs exit `0` clean, `1` findings, `2`
+ * could not run"):
+ *
+ *   0 — ran cleanly against a non-empty record set and found nothing.
+ *   1 — ran cleanly and found at least one real violation.
+ *   2 — could not run. Kept strictly distinct from `1`, because "I checked
+ *       and it is fine" and "I never checked" are different answers and a
+ *       gate that reports the second as the first is worse than no gate.
+ *
+ * `2` is genuinely reachable here, on every subcommand, and each route is
+ * tested:
+ *   - a record store that cannot be read — missing file, unreadable file,
+ *     a directory where a file was named, invalid JSON, or JSON that does
+ *     not validate against this package's own schema;
+ *   - nothing to scan — an empty record set, which is not a clean run, it
+ *     is a run that examined nothing;
+ *   - a required declared value that was not supplied — the confidence
+ *     floor, or the denial-invalidation policy. Neither has a default
+ *     anywhere in this package, and a run missing one declines rather than
+ *     inventing one of the consumer's own values;
+ *   - NO GATE SELECTED AT ALL. A bare `butler-check` with no subcommand is
+ *     a run that never happened, and it exits `2`, not `0` — see `main()`'s
+ *     own comment for why an explicitly requested `--help` is the one
+ *     argument-shaped `0` here and a dropped argument is not.
+ */
+/** Exported for `cli.test.ts` — anything wrong with the arguments themselves always maps to exit code 2, never 1. */
+export declare class CliInputError extends Error {
+}
+/**
+ * Exported (unlike a typical CLI `main`) so `cli.test.ts` can exercise the
+ * whole argv-to-exit-code contract directly, against real `mkdtemp` temp
+ * directories, without spawning a subprocess per case. Takes `argv` as a
+ * parameter rather than reading `process.argv` itself for exactly that
+ * reason — `run()` below is the only caller that reads the real
+ * `process.argv`.
+ */
+export declare function main(argv: string[]): number;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AA2EH,qHAAqH;AACrH,qBAAa,aAAc,SAAQ,KAAK;CAAG;AAkQ3C;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAyB3C"}