Architecture Over Autonomy: Inside the Engineering of intent-longbox v0.2.1

Executive Overview

In the fast-evolving landscape of software engineering, artificial intelligence is frequently deployed as an all-encompassing oracle. Developers are tempted to hand over end-to-end responsibilities to multimodal large language models (LLMs), trusting them to parse messy real-world data, reason through complex domain logic, and output authoritative conclusions.

However, building software for physical retail inventory exposes the fragility of this approach. Nowhere is this more apparent than in the comic book aftermarket, where a first-print variant and a common reprint feature the exact same cover art yet carry radically different market valuations.

Enter intent-longbox, a photo-to-listing pipeline designed to automate inventory cataloging for brick-and-mortar comic shops. Reaching version v0.2.1 on September 1, 2026, after an intense development cycle consisting of eleven initial commits, the project offers a masterclass in pragmatic software design. Rather than relying on AI as a magical source of truth, intent-longbox treats LLMs as probabilistic rankers sitting downstream from deterministic systems.

By prioritizing strict database governance (via an append-only architecture enforced by PostgreSQL triggers), leveraging arithmetic barcode decoding for post-1990 inventory, and deploying an innovative "evidence contradiction gate" to cross-validate model outputs against hard facts, the project has established a blueprint for reliable AI integration. Tested thoroughly in a dockerized environment with a pilot deployment at Gotham City Limit, intent-longbox proves that the most resilient AI applications are those that don’t trust AI blindly.

Detailed Chronology & System Architecture

The Development Timeline and Governance Setup

The creation of intent-longbox was characterized by rigorous upfront planning rather than reckless coding. The project kicked off at 18:07 with a /repo-dress pass, establishing fundamental open-source governance files: LICENSE, SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, AGENTS.md, and CI workflows.

Minutes later, at 18:12, the core planning documentation was committed. This included six master planning documents (comprising a business case, a Product Requirements Document with items R1 through R20 tagged via MoSCoW methodology, system architecture designs, user journey maps, and technical specifications), alongside an index and an overarching project instruction file (CLAUDE.md). This brought the 000-docs/ directory to eight filed documents, including competitor analyses and an approved build plan.

From there, development moved through an isolated beads workspace prefixed with longbox, culminating in five automated release commits that brought version.txt from v0.1.0 to v0.2.1.

The Pipeline Flow: Deterministic First, Probabilistic Second

The core design philosophy of intent-longbox was settled by early architectural research: LLM vision alone is fundamentally unviable for issue-exact and variant-exact comic book identification. Instead, every successful incumbent in this space utilizes image-similarity retrieval against a reference cover corpus. The model’s role is strictly that of a ranker.

The processing pipeline is structured to place deterministic operations before probabilistic ones:

barcode decode ⟶ candidate retrieval ⟶ LLM re-rank ⟶ human confirm ⟶ condition + price ⟶ Shopify draft

Crucially, nothing publishes without human intervention. The final output lands in Shopify strictly as a DRAFT for store owner review.

Barcode Parsing and Arithmetic Identification

For post-1990 comic books, the identification problem is largely solved before any AI model is invoked. Modern comics feature a 12-digit UPC-A barcode that identifies the series, accompanied by a 5-digit UPC supplement encoding the specific issue number, cover variant, and printing run:

const supp = digits.slice(12);
return 
  ok: true,
  upc,
  supplement: 
    raw: supp,
    issue: Number(supp.slice(0, 3)),
    cover: Number(supp[3]),
    printing: Number(supp[4]),
  ,
;

When this supplement is readable, the variant question is answered entirely through arithmetic. The LLM is never queried, eliminating latency, cost, and hallucination risks entirely for a large portion of modern inventory.

For pre-1990 stock, damaged barcodes, or un-barcoded variants, the system falls back to vision models, paired with mandatory human confirmation. This fallback mechanism represents the system’s primary open tracking decision as pilot testing gets underway.

Supporting Context & Metrics

The Database Refuses to Mutate: The Hickey Model in PostgreSQL

Data integrity is paramount when dealing with financial assets and inventory cataloging. In intent-longbox, every event in a scanning session is recorded as an immutable row, turning database tables into a true audit trail rather than a mutable current-state cache.

The database schema includes:

• scan_session (serving as the root identity)
• candidate_set (holding deterministic results and similarity k-NN)
• llm_rerank (capturing provider metadata, model IDs, prompt hashes, verbatim responses, confidence bands, contradiction flags, token usage, and costs)
• human_confirmation, condition_assessment, pricing_snapshot, shopify_draft, and cost_log

To prevent accidental updates or hotfixes from subverting this audit trail, code discipline alone was deemed insufficient. As a result, immutability is enforced directly at the database layer using PostgreSQL triggers:

CREATE OR REPLACE FUNCTION forbid_mutation() RETURNS trigger AS $$
BEGIN
  RAISE EXCEPTION 'table % is append-only (Hickey model): % not allowed', TG_TABLE_NAME, TG_OP;
END;
$$ LANGUAGE plpgsql;

DO $$
DECLARE t text;
BEGIN
  FOREACH t IN ARRAY ARRAY[
    'corpus_version','scan_photo','candidate_set','llm_rerank','human_confirmation',
    'condition_assessment','pricing_snapshot','shopify_draft','cost_log'
  ] LOOP
    EXECUTE format(
      'CREATE TRIGGER %I_append_only BEFORE UPDATE OR DELETE ON %I FOR EACH ROW EXECUTE FUNCTION forbid_mutation()',
      t, t);
  END LOOP;
END $$;

Attempting an UPDATE operation on any of these tables—such as cost_log—immediately halts execution with an explicit exception: table cost_log is append-only (Hickey model).

Furthermore, condition assessment is strictly bounded. Numeric grades (such as a CGC 9.4) do not exist anywhere in the schema, API, prompts, or UI copy. Instead, books are evaluated using coarse grade range labels:

grade_range_low  text NOT NULL CHECK (grade_range_low  IN ('PR','FR','GD','VG','FN','VF','NM')),
grade_range_high text NOT NULL CHECK (grade_range_high IN ('PR','FR','GD','VG','FN','VF','NM')),

A phone camera photo does not entitle an automated system to claim a precise numeric grade. Restricting the type system prevents engineers or models from inventing false precision under deadline pressure.

The Evidence Contradiction Gate

Self-reported confidence scores from LLMs are notoriously unreliable; models are often most fluent precisely when they are confidently incorrect. To mitigate this, the VisionProvider interface requires structured evidence alongside any identification answer:

/** REQUIRED structured evidence. The contradiction gate's raw material (R7). */
export interface Evidence  null;
  price_box_text: string 

The system prompt explicitly commands the model to report what it can physically read on the cover. The backend service (src/services/rerank.ts) then cross-validates these fields against the top candidate’s metadata:

if (evidence.price_box_text !== null && top.year !== undefined) 
  const priceMatch = evidence.price_box_text.match(/(d+)s*[¢c]

If a contradiction is detected—such as a 12-cent price box appearing on a 1988 book, or a 1960s publisher logo paired with a modern publication year—the model is penalized by having its confidence band downgraded from high to medium:

export function applyContradiction(band: Band, contradiction: boolean): Band 
  if (!contradiction) return band;
  return band === "high" ? "medium" : band;

In the mobile UI, these bands dictate workflow: high allows a one-tap confirmation, medium presents a candidate grid requiring a forced selection, and low drops down to a manual search. By forcing a contradiction downgrade, the system turns a potentially disastrous automated error into a minor inconvenience for the human operator, preventing bad inventory entries.

Official Statements & Technical Resilience

Multi-Source Pricing Isolation

Pricing comic inventory requires aggregating live market data from disparate APIs. intent-longbox handles pricing via a modular PricingProvider interface supporting adapters for eBay Browse (OAuth2 client-credentials app token) and PriceCharting.

To prevent a single lagging API from blocking the entire pipeline, queries are executed asynchronously using Promise.allSettled:

const settled = await Promise.allSettled(args.providers.map((p) => p.getComps(args.query, shopCtx)));

If a pricing provider fails, the error is logged in the outcome list without writing a blank snapshot row, allowing secondary providers to successfully price the book.

When multiple pricing sources return data, precedence is handled deterministically: historical fair market value (historical_fmv) takes precedence over live asking prices (live_asks), because an asking price represents a wish rather than a completed transaction. If neither source returns valid data, the shop’s policy floor price is applied.

Comprehensive Testing and Metrics

At the close of development, the test suite stood in a pristine state:

• Code Quality: pnpm lint, format:check, and typecheck all passed cleanly.
• Test Coverage: Unit tests grew from 92 to 118, achieving 99.67% line coverage against a strict 80% floor.
• Integration Testing: 14 integration and smoke tests passed successfully against a dockerized postgres:16 instance.
• Database Migrations: Migration 002 safely extends shop credential enums while leaving migration 001 untouched.

Future Outlook & Roadmap

Despite its robust architectural foundation, intent-longbox v0.2.1 represents a starting point rather than a finished product. Several crucial milestones remain on the roadmap:

1. Similarity Index Integration: The candidate retrieval leg currently relies on barcode decoding and vision fallbacks without a dedicated image-similarity index. Evaluating commercial APIs like Ximilar or building a self-hosted cover-image embedding index is a top priority to improve pre-1990 and un-barcoded book matching.
2. Pricing Source Productionization: Both pricing adapters currently function as stubs pending live API credentials and rate-limit verification.
3. Automated Eval Suites: Phase 2 objectives include populating the human_confirmation table with real-world scan data to build a robust static evaluation regression set for continuous CI testing.
4. Pilot Execution: While simulated test suites and containerized environments have validated the codebase’s logic, the software has yet to undergo sustained, high-volume real-world usage in the pilot shop, Gotham City Limit.

Conclusion

The evolution of intent-longbox offers a compelling blueprint for modern software architecture in the era of generative AI. By rejecting the siren song of autonomous end-to-end LLM pipelines and instead anchoring AI outputs within deterministic guardrails, immutable audit logs, and strict validation checks, the project successfully bridges the gap between probabilistic machine learning and the unforgiving realities of physical retail inventory management.