# Printing & Local Agent Foundation v51

## Principle
Printing is an asynchronous hardware side effect.
Business truth remains in PostgreSQL even when every printer is offline.

## Printer model
Printers are tenant-scoped and optionally branch-scoped.
Roles:
- receipt
- kitchen
- bar
- pickup
- label
- a4
- fiscal
- generic

Drivers:
- ESC/POS
- Windows queue
- ZPL
- TSPL
- raster
- fiscal
- generic

## Routing
A routing rule maps:
`event_type + document_type -> printer OR printer_group`

Printer groups support priority/failover structure.

## Print jobs
Job states:
`pending -> claimed -> printing -> printed`

Failure path:
`claimed/printing -> retry -> claimed ... -> failed`

Jobs use:
- tenant idempotency key
- immutable event history
- agent lease ownership
- attempt limits
- delayed retry
- explicit source identity

## Local Agent
The agent is a hardware bridge only.
It does not contain sales, stock, customer, or payment truth.

Supported backend platform identities:
- Windows
- Android
- iOS
- Linux

Pairing uses a short-lived single-use secret. Only SHA-256 hashes are stored in the database.

Agent calls are outbound-to-cloud:
- pair
- heartbeat
- claim job
- mark printing
- mark printed
- mark failed

No inbound static IP or local web server is required.

## Important boundary
`Send Kitchen` remains a restaurant business action.
The printing module can later subscribe to the KDS ticket event and create a kitchen print job.
A printer failure never rolls back the KDS ticket.

Likewise, a Sale remains committed if receipt printing fails.

## Deferred
- actual C# Windows Agent executable
- Kotlin Android foreground-service agent
- iOS active companion
- WebSocket push; HTTPS long polling is the first fallback-compatible contract
- document/receipt template designer
- ESC/POS Arabic renderer
- Windows spooler adapter
- printer auto-discovery
- round-robin group runtime selection
- cash drawer / scale / customer display / buzzer