Breakwater

• 

Inspiration

A shipowner says a vessel was ready at 6 a.m. Vessel telemetry places it 24 nautical miles outside port limits. That disagreement changes when chargeable time begins—and can change the bill by thousands of dollars.

Shipping-delay charges, called demurrage, sit at the intersection of physical events, contracts and accounting. A trading company may owe the shipowner while recovering a different amount from a cargo buyer or seller. Each contract has its own rates, exceptions and deadlines.

The work involves more than calculating a number. Someone must investigate conflicting evidence, find missing documents, make commercial decisions, obtain approval and record the result.

I built Breakwater around that whole workflow, including what happens when a person corrects it.

What it does

Breakwater runs a simulated demurrage desk for Meridian Commodities, a fictional grain trader.

It compares documents with vessel geo-location and telemetry, calculates payable and recoverable amounts separately, prepares claims and disputes, and records balanced accounting entries.

When human judgment is needed, it asks the appropriate person:

• Voyage Operations verifies facts and finds missing evidence.
• The Trader decides whether to pursue, reduce or waive a recovery.
• The Controller reviews financial treatments and authorizes actions beyond delegation.

The interface keeps this work connected. The Desk shows company exposure and outstanding decisions. Each Voyage Room combines a map, synchronized timelines, source documents, investigation steps, memory and financial statements. Human workspaces open within that same case context.

How it learns

Breakwater learns from the difference between its investigation and the human actions that contributed to an answer.

In the demo, it cannot verify a customs hold from its permitted sources. An Operations colleague searches the customs portal, opens the release and links it to the hold.

Breakwater proposes a reusable investigation procedure. The person confirms its scope, the procedure is backtested against historical cases, and the Controller approves the new access. On a later voyage, that procedure can find the evidence without another Operations question.

A Controller’s correction can become a contract-specific rule. A Trader’s goodwill waiver remains a non-executable precedent: context for future decisions, without an instruction to repeat the discount.

Self-improvement here means changing approved future behavior. It does not mean retraining model weights, rewriting its own code or granting itself authority.

How I built it

The central design choice was to separate interpretation from calculation and authorization.

Claude reads documents, selects permitted tools and proposes actions and lessons. Jev classifies lessons by kind, scope and whether they represent discretionary judgment. Deterministic TypeScript controls money, time, permissions, memory activation and financial posting.

The main techniques are:

• Evidence-linked extraction: extracted document values carry verbatim quotes that are checked against the PDF text.
• Telemetry reconciliation: vessel positions and geofences help verify arrival claims and identify movement intervals.
• Deterministic calculations: integer cents and minutes, UTC normalization, contract-specific interval treatments and double-entry journals.
• Scoped capabilities: tools are offered according to current permissions, with access checked again during execution.
• Semantic trace comparison: learning uses contributing searches, documents, evidence links and submitted edits rather than unrelated browsing.
• Typed memory: reusable behavior is stored as constrained procedures or rule overrides, rather than unrestricted text instructions.
• Historical backtesting: proposed procedures are checked against recorded cases, including cases where escalation is the correct outcome.
• Controlled execution: task-output verification, bounded retries and idempotent writes limit incomplete work and duplicate side effects.
• Traceable decisions: financial actions preserve evidence and authority, while a SHA-256 hash chain makes audit-history changes detectable.

The interface uses Next.js, React and TypeScript. Convex stores business state, schedules work and delivers live updates. MapLibre renders vessel geography, and Luxon handles time-zone conversion.

Challenges I ran into

Two contracts can produce two correct, different amounts

The owner-side payable and customer-side recovery cannot share a single calculation. Different notice periods, allowances, rates and exceptions create a real gap that must remain visible.

Our own data can be wrong

The demo deliberately includes a contract-register omission. The Controller checks the original clause and corrects the treatment, increasing the amount owed.

That mattered to the design: the objective is a defensible financial result, not simply the lowest bill.

Learning can accidentally become authority

Finding a useful procedure does not automatically justify new access. A commercial concession does not automatically justify a reusable rule. Classification, scope confirmation, backtesting and approval therefore remain separate steps.

Financial work continues before an invoice arrives

The application handles month-end estimates, later adjustments and locked periods. Recovery deadlines also run independently: waiting for the owner’s invoice could mean missing the customer’s claim deadline.

Accomplishments that I’m proud of

I’m proud of connecting investigation, human decisions, learning and accounting in one application.

The most meaningful learning moment is visible behavior: a procedure proposed from one person’s investigation becomes approved memory and changes how a later case is handled.

I also wanted the interface to make the system inspectable. The map explains the physical discrepancy, the timeline aligns evidence with contractual time, and the financial views connect amounts to calculations and approval authority.

What I learned

Reliable automation needs clear boundaries around both actions and learning.

Exact arithmetic cannot rescue incorrect inputs. A quote establishes traceability without proving that a document is truthful. Balanced journals establish bookkeeping consistency without proving that the underlying liability is correct.

Human intervention is valuable when the system can identify what changed, preserve the supporting evidence and limit how broadly that change applies.

The most useful learning loop is one that also knows what should remain a one-off decision.

Scope and evaluation

The prototype uses a fictional company, simulated vessel telemetry, generated documents and scripted world events. Model calls, calculations, backend state, approval checks and journal writes operate against that environment. No real customs, ERP or bank integration is connected, and no cash moves.

The evaluation framework compares results against an independent answer key across 24 held-out synthetic voyages. It measures monetary exactness, dispute detection, necessary human asks and selected control violations.

The public source snapshot has not been run or tested end to end. Included test sources and evaluation machinery should not be read as a claim of current accuracy or production readiness.

What’s next

• Validate the public source snapshot and expand evaluation across more contract variations and incomplete evidence.
• Add controlled reconciliation between structured contract registers and original contract documents.
• Connect authorized external data sources and production identity systems.
• Improve review and recovery workflows when an investigation cannot complete.
• Evaluate whether approved memory reduces repeated human work without increasing incorrect generalization.

Built With

• agents
• ai
• claude
• convex
• openai
• typescript