Skip to content

Add the verdict state machine - #2

Merged
Aditya292248 merged 1 commit into
mainfrom
pr2-verdict
Nov 1, 2026
Merged

Aditya292248 merged 1 commit into
mainfrom
pr2-verdict

Conversation

@Aditya292248

Copy link
Copy Markdown
Owner

What

  • src/types.ts: discriminated unions for lookup results, claims, verdict states, events and
    reason codes.
  • src/verdict.ts: nextVerdict(prev, event, aliases), a pure function with no I/O or clock.
    It maps the current verdict and one event (lookup result, claim, lookup or claim deadline,
    error) to the next verdict.
  • test/verdict.test.ts: one test per transition, plus checks over every event sequence up
    to length 3 (1,463 sequences) for the three invariants.
  • docs/adr/0003-claim-only-downgrades.md, and the state machine with its invariants in
    ARCHITECTURE.md.

Why

This is the security core, and it needs no API to build or test. OWNER_KNOWN is where the
person being called will be told whose agent it is; MISMATCH is where they will be warned
that the agent claimed someone else (see "Notifications" in ARCHITECTURE.md). It encodes
fail closed and
monotonic verdicts (ADR 0002) and the rule that a caller's
claim can only lower a verdict (ADR 0003).

Decisions a reviewer may question:

  • Deadlines are named (lookup or claim). A late lookup timer firing in OWNER_KNOWN
    must not close the claim window early.
  • Claims heard during IDENTIFYING are kept. Otherwise a caller who lies before the
    lookup finishes would end up as VERIFIED_NO_CLAIM.
  • VERIFIED and VERIFIED_NO_CLAIM can still drop to MISMATCH on a later claim for
    someone else. Only MISMATCH and UNVERIFIED are final.
  • Aliases are keyed by sub-account ID, not by name, and matching is exact and
    case-insensitive.

How to test

npm ci
npm test            # 41 tests, 0 failures
npm run typecheck
npm run lint
npm run format

Not in this PR

  • Claim extraction from the transcript (PR 3). Claims arrive here as an already-extracted
    name.
  • The AgentPhone client and call lookup (PR 4), and the timers and orchestrator that send
    events (PR 5).
  • Where aliases come from. nextVerdict takes them as an argument; config does not have them
    yet.
  • claim_timeout is defined but only produced once the orchestrator exists.
  • The notifier. For the demo it will print a proof-page link to the terminal; SMS or iMessage
    comes later.

A pure nextVerdict(prev, event, aliases) over lookup results, claims,
named deadlines and errors. Encodes fail closed, monotonic verdicts and
claims that only downgrade, with a transition table and checks over
every event sequence up to length 3.

Adds ADR 0003 and documents the state machine and notifications in
ARCHITECTURE.md.
@Aditya292248
Aditya292248 merged commit 8483884 into main Nov 1, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant