Tally

Elevator pitch

Demurrage is the daily fee ocean carriers charge when a container remains at the terminal past its free time. The invoice arrives weeks later, after the events that determine whether each day was actually chargeable.

Tally records that evidence as it happens, then makes every charge prove itself—recommending approval, preparing a dispute, or refusing to conclude when memory is incomplete.

Inspiration

Demurrage is the daily fee an ocean carrier charges when a container remains at the terminal beyond its allotted free time.

A carrier sends the invoice three weeks after the container left the port: seven charged days, but no explanation of which days were assessed, no attached tariff, and no record of whether the terminal was even accessible while the clock was running.

The invoice is a claim about a period the reviewer can no longer directly observe.

To judge it, someone must reconstruct:

which tariff applied on those dates;
when free time began and ended;
whether the container was actually available;
whether closures, labor actions, equipment outages, appointment failures, or other exceptions made any day unchargeable.

That evidence is scattered across booking systems, terminal portals, emails, shared drives, and human memory. Some of it has changed. Some of it is already gone.

The reviewer has three bad options: pay without proving the charge, spend hours rebuilding enough evidence to dispute it, or approve it and discover later that it was wrong.

The mistake is treating this as a document problem.

By the time the invoice arrives, the answer is not in the document. It is in the operational record that existed weeks earlier. A late-arriving claim can only be judged from evidence already in memory.

Tally starts before the invoice exists. It records shipment events, applicable tariffs, and exact source versions as they occur. When a charge arrives, Tally reconstructs every billed day and decides whether the evidence supports approval, dispute, or no conclusion at all.

When the record is incomplete, Tally refuses to guess—and explains why.

What it does

Tally records the evidence needed to judge demurrage before an invoice arrives, reconstructs every charged day when one does, and recommends approval, dispute, or no conclusion based on the completeness of that memory.

Remember

As a shipment moves through the terminal, Tally records the operational events that will later determine whether a demurrage charge is valid: container availability, free-time boundaries, gate-out, terminal conditions, and the tariff in effect.

Each event retains both when it occurred and when it entered memory. Exact source versions are preserved so the record can later be replayed without silently drifting.

Reconstruct

When a carrier invoice arrives, Tally extracts the container, bill of lading, charged period, daily rate, and total from the PDF.

It retrieves the pre-invoice operational memory for that shipment and rebuilds every billed day. Vector retrieval finds candidate tariff clauses; deterministic code—not the model—verifies the effective date, terminal scope, exact language, and applicable rate.

Each charged day is then evaluated against the retained shipment events and verified rule.

Decide

Tally reaches one of three outcomes:

Approve for payment — every charged day and the invoiced rate are supported by the recorded evidence.
Dispute — the retained evidence or verified tariff contradicts part of the carrier’s claim. Tally computes the supported amount and prepares the disputed difference.
Needs evidence — a required event, source, day, or governing rule cannot be verified. Tally refuses to conclude and identifies exactly what is missing.

In the canonical case, the carrier bills seven days at $350 per day. Tally confirms that all seven days are chargeable, but the governing tariff permits only $250 per day. It recommends disputing the $700 difference.

Act

A human reviews the original invoice, the governing tariff, and the day-level derivation before authorizing the financial outcome.

Tally then seals the recommendation to its supporting events, tariff clause, exact source versions, and reviewer approval. Correspondence is composed only from that sealed record and includes an evidence manifest containing the invoice, applicable clause, charged-day calculation, and decision record.

Before anything is sent, Tally re-verifies the complete evidence set. If any source, approval, binding, or integrity check fails, nothing goes out.

What survives is a decision that can be defended—cited to the evidence that authorized it and the human who approved it.

How CockroachDB powers Tally

Tally’s central claim is that memory determines whether it is allowed to act.

CockroachDB makes that possible by combining decision-critical state that would otherwise be divided across a transactional database, vector store, workflow engine, revision ledger, audit system, and event pipeline.

Exact source files remain in versioned Amazon S3. CockroachDB binds their version and integrity references into the same operational memory as the shipment events, reconstruction, recommendation, approval, and final decision seal.

Point in the workflow	What CockroachDB does	Why Tally depends on it
Pre-invoice shipment memory	CockroachDB stores shipment events with both occurred and recorded timestamps. Managed MCP exposes a governed, read-only view constrained to what was recorded before the invoice arrived.	A late-recorded event cannot silently rewrite what Tally was allowed to know when it judged the claim.
Governing-tariff retrieval	Distributed Vector Indexing searches 1,024-dimensional Titan embeddings over verified tariff clauses. Every candidate carries source-version and integrity digests.	Retrieval discovers possible matches; deterministic code decides applicability. Similarity cannot override an invalid date, scope, phrase, or rate.
One operational system	CockroachDB holds shipment memory, tariff vectors, durable tasks, attempts, reconstruction revisions, recommendations, approvals, product events, and the outbox.	Tally does not have to reconcile a separate vector database, workflow engine, audit ledger, and transactional store before it can defend a decision.
Immutable revisions	Reconstructions and recommendations are inserted as new monotonic versions rather than overwriting earlier conclusions.	New evidence can change the answer without erasing what Tally previously believed or why.
Atomic decision seal	One serializable transaction commits the human approval, decision seal, evidence references, invoice-state projection, audit event, and outbox entry.	Either the entire authorized decision commits or none of it does. Double approval and partial sealing are prevented.
Verified delivery	Fresh send-gate checks run inside the send transaction before the correspondence provider is called.	A missing source, stale approval, superseded seal, or failed integrity check blocks delivery before any external action occurs.

CockroachDB does not merely store Tally’s answer. It unifies the memory, retrieval, workflow, revision history, and approval state required to produce one—and atomically seals the evidence that authorized it.

How we built it

Tally is built as an evidence-first decision pipeline.

Agents interpret unstructured material and retrieve relevant records. Deterministic services verify sources, reconstruct each charged day, and decide whether the evidence is sufficient for a recommendation. A human authorizes the financial consequence. CockroachDB preserves the durable state connecting every step.

Architecture

Pre-invoice shipment memory
shipment events · tariffs · exact source versions
                 │
Carrier invoice PDF
        ↓
Authenticated intake + content-hash deduplication
        ↓
Exact source preservation in versioned S3
        ↓
Bedrock claim extraction
        ↓
Managed MCP reconstruction of pre-invoice memory
        ↓
Distributed Vector Indexing retrieves tariff candidates
        ↓
Deterministic applicability and per-day validation
        ↓
Immutable recommendation revision
APPROVE · DISPUTE · NEEDS EVIDENCE
        ↓
Human authorization
        ↓
Serializable decision seal + outbox
        ↓
Send-gate re-verification
        ↓
Correspondence out

Capture and preserve

Shipment events, tariffs, and invoice PDFs enter through authenticated intake.

Exact source files are retained in versioned S3. Their version identifiers and SHA-256 digests are stored in CockroachDB so Tally can later prove which exact bytes supported a decision.

Duplicate imports are coalesced through content hashing, request idempotency, and database constraints. Operational events carry both occurred_at and recorded_at timestamps. Reconstruction uses the invoice’s arrival as a knowledge cutoff, distinguishing what happened from what was actually present in memory before the claim arrived.

Interpret

Amazon Bedrock reads the invoice and produces a structured claim set: container, bill of lading, charged period, rate, and total.

Every claim must anchor to exact language in the retained document. If the claimed text cannot be located, the field is rejected instead of accepted as a confident guess.

Amazon Titan Text Embeddings V2 also produces the vectors used for tariff-clause retrieval.

The model interprets and retrieves. It does not decide whether a tariff governs the invoice or whether Tally has enough evidence to conclude.

Verify and reason

Durable workers perform reconstruction, rule qualification, and daily judgment.

The reconstruction worker uses CockroachDB Managed MCP to retrieve shipment memory recorded before the invoice cutoff. The cutoff is enforced in the query and checked again by deterministic code.

Distributed Vector Indexing retrieves verified tariff candidates across differing terminology. Deterministic validation then checks effective date, terminal scope, exact phrase, and rate. A top-ranked candidate that fails any applicability check is rejected.

The judgment worker evaluates every billed day against the retained shipment events and verified tariff. Its result is inserted as an immutable recommendation revision. Re-running the case against new evidence creates a new version rather than editing the previous answer.

Authorize and act

A recommendation cannot leave Tally without human authorization.

Approval creates a sealed decision that binds the recommendation to the reconstruction, verified rule, claim set, source references, and reviewer. CockroachDB commits the approval, seal, invoice-state update, audit event, and outbox entry atomically under serializable isolation.

Before correspondence is sent, the send gate performs fresh checks of the approved memory, vector-clause binding, exact S3 source, and current decision seal. The provider is never called if any gate fails.

End to end

INV-1048.pdf claims seven demurrage days at $350 per day, totaling $2,450.

Tally preserves the exact PDF, extracts the claim, and reconstructs the period from shipment events recorded before the invoice arrived. Managed MCP returns the container’s availability, free-time boundaries, and gate-out history.

Distributed Vector Indexing retrieves the governing tariff candidate. Deterministic validation confirms a $250 daily rate effective June 1 for demurrage at Oakland.

All seven days are supported by the retained events, but each carries a $100 rate discrepancy. Tally creates an immutable recommendation to dispute $700.

The reviewer inspects the original invoice, tariff clause, and a charged-day derivation, then authorizes the outcome. Tally seals the decision, re-verifies the complete evidence set, and sends the adjustment request with its evidence manifest.

Trust and failure guarantees

Missing or unverifiable evidence produces NEEDS_EVIDENCE, not a guessed answer. Failed source verification cannot reach delivery. Duplicate imports do not create duplicate work. Re-runs create new recommendation revisions instead of overwriting history.

The UI renders persisted backend state over server-sent events. Reveal timing may be paced for presentation, but every displayed status, recommendation, and terminal outcome comes from durable product state.

Challenges we ran into

Judging the past requires knowing what was knowable then

Reconstructing a dispute after the fact makes it easy to cite information that arrived later and produce a rigorous-looking answer that was impossible at the time.

Tally separates when an event occurred from when it entered memory. Every reconstruction uses the invoice’s arrival as a hard knowledge cutoff, enforced in both retrieval and deterministic validation. Later evidence cannot silently rewrite the pre-invoice record.

Making incomplete memory withhold authority

A missing source is not evidence that nothing happened.

Early designs could advance even when a required input was unresolved, turning partial memory into false certainty. We introduced an explicit authority gate: missing or unverifiable evidence produces NEEDS_EVIDENCE with a named reason, and no financial recommendation can proceed until the record is sufficient.

Letting retrieval discover without letting similarity decide

Tariffs and invoices often express the same concept with different language, making vector retrieval useful.

But the closest clause is not necessarily the governing clause. Distributed Vector Indexing retrieves candidates; deterministic code separately verifies effective date, terminal scope, exact language, and rate. A top-ranked candidate that fails any applicability check is rejected.

Accomplishments we are proud of

Three real terminal outcomes: the product retains separate invoices in APPROVED_FOR_PAYMENT, NEEDS_EVIDENCE, and DISPUTED states.
Seven sourced charged days: the canonical dispute resolves each billed day to retained shipment events and the applicable tariff.
Deterministic tariff applicability: vector retrieval finds candidates, but only verified date, scope, language, and rate checks can qualify one.
A cited $700 dispute: Tally compares seven days at the carrier’s $350 rate with the verified $250 tariff and computes the supported correction.
Immutable decision history: new evidence creates new recommendation versions rather than rewriting prior conclusions.
Atomic human authorization: approval, seal, product state, audit event, and outbox commit together.
No unsupported delivery: any failed source, evidence, seal, or approval check blocks the outbound request.
Durable product state: tasks, attempts, recommendations, events, and reconnectable progress survive beyond a browser session.

What we learned

The invoice is the end of the story

We entered the hackathon with no background in ocean freight and initially treated demurrage as an invoice-review problem.

Learning the domain changed the architecture. Charge validity depends on operational evidence that existed days or weeks before the invoice and may later change or disappear. Tally therefore begins before the claim exists.

Agentic memory has to earn the right to answer

Good retrieval is not enough.

For consequential decisions, memory’s job is not to produce the best available answer. It must determine whether the system has sufficient evidence—and sufficient authority—to answer at all.

Humans and machines need different responsibilities

The human is not merely a safety net.

The model interprets. Deterministic code validates. Memory determines sufficiency. The reviewer owns the financial consequence. Clear boundaries make each layer stronger.

Every end state is a product state

NEEDS_EVIDENCE, source-verification failure, and send-gate refusal are not secondary error handling.

They are legitimate outcomes. Designing them as first-class states prevented Tally from converting missing evidence into false certainty.

What is next for Tally

Prevention before invoicing

Today, Tally preserves evidence so a later charge can be judged. That same memory can warn operators before free time expires—while they still have time to resolve a hold, document an access failure, or move the container.

Broader evidence coverage

The current build demonstrates one carrier and terminal workflow. Extending the evidence layer across additional terminal systems, carrier tariffs, and appointment sources would apply the same authority model to more shipments without weakening verification.

Additional charge types

Detention, per diem, chassis, and container-return charges follow the same pattern: the claim arrives after the events required to judge it. The evidence-first architecture remains the same; only the domain rules change.

Production dispute delivery

The current build delivers to a demonstration inbox. A production release would add carrier-specific delivery, tracked receipts, response handling, and settlement correspondence while preserving the same evidence-gated send behavior.

Built With

amazon-bedrock
amazon-web-services
aws-app-runner
cockroachdb
cockroachdb-cloud-managed-mcp-server
cockroachdb-distributed-vector-indexing
python