Context Packer

Context assembly is usually a concatenation that stops when it feels full, using a character count as a stand-in for tokens. It overshoots -- the provider truncates the tail, silently dropping whatever was last, often the actual question -- or it undershoots, paying for a large window and using a third of it.

Worse, when it drops items it usually drops them BY POSITION rather than by importance, so the least relevant item survives and the most relevant is cut.

EVERY DROPPED ITEM IS RECORDED WITH A REASON. Nothing is discarded silently; a caller can see exactly what did not make it and why.

MUST-KEEP ITEMS ARE HONOURED FIRST, and if the must-keep set alone exceeds the budget that is an ERROR the caller has to handle -- not something resolved by quietly dropping one of them.

IT DOES NOT BUNDLE A TOKENIZER, and that is deliberate. Size is supplied by the caller, from their own tokenizer. A four-characters-per-token heuristic is wrong by 15 to 30 percent depending on content, and being wrong in the unsafe direction is precisely what causes the silent truncation this exists to prevent. The caller owns measurement, and the README says so plainly.

It reports the packed total and the headroom left, so a caller can see whether they are wasting a window they paid for, and supports a reserved allowance for the response -- a budget consumed entirely by input leaves no room to answer, which is a real and commonly missed failure.

Deterministic: identical input yields identical output, and ties break by a stated rule rather than by object key order.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function pack(items: readonly PackItem[], options: PackOptions): PackResult;

  export type KeepReason = "must-keep" | "fits-in-budget";
  export type DropReason = "exceeds-remaining-budget";