Architecture: Encapsulate Queue admission in QueueManager.enqueue to eliminate canEnqueue seam leak

[jonbaldie]

Candidate Summary

• Recommendation Strength: Strong
• Modules Involved: src/manager.ts, src/handler.ts
• Domain Context: Queue Manager, Queue, Enqueue, Item Lifecycle
• Architecture Vocabulary: module, interface, depth, seam, leverage, locality

Problem & Evidence

Currently, Queue Manager exposes a query method canEnqueue(name: string): boolean alongside the mutating method enqueue(name: string, payload: T): Manager<T>.

In src/handler.ts:

if (!mgr.canEnqueue(queueName)) {
    return new Response("Queue full or too many queues", { status: 507 });
}
mgr.enqueue(queueName, json.payload);

This creates an awkward two-step handshake across the seam for every caller attempting to enqueue a payload:

1. Duplicated validation & limit checks: canEnqueue validates the queue name, checks canCreateQueue(), and inspects queueDepthLimit. Then enqueue repeats validateName, find(name), canCreateQueue(), and queue.length >= this.queueDepthLimit.
2. Leaky error contract: enqueue throws generic untyped Error("Queue count limit reached") and Error("Queue depth limit reached"). In src/handler.ts, enqueueHandler only catches SyntaxError, UnsupportedNumberError, and QueueNameTooLongError in enqueueErrorResponse. If mgr.enqueue throws a capacity limit error (e.g. under concurrent operations), the error is unhandled by the error response mapper and becomes an uncaught 500 Internal Server Error instead of a 507.
3. Callers are forced to know internal ordering invariants (they must call canEnqueue first) because enqueue does not provide a typed domain error contract for capacity admission failure.

Test Evidence (/deintrovert-tests)

In tests/manager_test.ts, unit tests test canEnqueue in isolation as a separate query seam, verifying boolean flags rather than observing the SUT's atomic state transitions and mutations. In tests/handler_test.ts, the handler is tested with full HTTP requests to verify 507 responses. Deleting canEnqueue aligns the test surface with the public interface: tests exercise enqueue directly and assert on the resulting queue state and thrown domain errors.

The Deletion Test

Applying the deletion test to canEnqueue: deleting canEnqueue concentrates complexity rather than scattering it. Queue Manager becomes a deeper module: callers interact solely with enqueue(), which owns admission control atomically.

Proposed Change

1. Define a domain error in src/manager.ts:

export class QueueCapacityExceededError extends Error {
    constructor(message = "Queue full or too many queues") {
        super(message);
        this.name = "QueueCapacityExceededError";
    }
}

2. Have QueueManager.enqueue(name, payload) throw QueueCapacityExceededError whenever queueDepthLimit or queueCountLimit would be exceeded.
3. Remove canEnqueue from QueueManager's public interface.
4. In src/handler.ts, call mgr.enqueue(queueName, json.payload) directly in enqueueHandler, and catch QueueCapacityExceededError in enqueueErrorResponse to return HTTP 507.

Benefits

• Leverage: Callers learn and invoke a single method enqueue instead of coordinating query-then-mutate handshakes.
• Locality: Capacity validation, name validation, and queue lifecycle management concentrate inside QueueManager.
• Testability: The interface is the test surface. Tests verify capacity limits by exercising enqueue and observing genuine state transitions.

[jonbaldie]

This was generated by AI during triage.

Verification: Confirmed in src/manager.ts and src/handler.ts. Currently, QueueManager exposes canEnqueue(name: string): boolean, forcing callers to execute a two-step validation check before enqueue(). enqueue() duplicates validation checks and throws generic untyped Error instances on capacity exhaustion. In src/handler.ts, enqueueErrorResponse() does not catch generic Error, meaning any capacity error thrown directly by enqueue() escapes as an uncaught 500 Internal Server Error rather than HTTP 507.

Redundancy check: Searched QueueManager, enqueueHandler, tests/manager_test.ts, and tests/handler_test.ts. canEnqueue remains part of the public interface and no unified capacity domain error exists. No matching .out-of-scope/ record exists.

Agent Brief

Category: enhancement
Summary: Encapsulate Queue admission control within QueueManager.enqueue and remove the canEnqueue public seam.

Current behavior:
Callers must coordinate a two-step query-then-mutate handshake via mgr.canEnqueue(queueName) and mgr.enqueue(queueName, payload). enqueue repeats name and capacity checks, and throws untyped generic Error instances ("Queue count limit reached", "Queue depth limit reached"). In src/handler.ts, enqueueHandler relies on canEnqueue for 507 responses, while enqueueErrorResponse leaves generic capacity errors unmapped, causing 500 status on unhandled errors.

Desired behavior:
QueueManager.enqueue owns admission control atomically. When capacity limits (queueDepthLimit or queueCountLimit) are exceeded, it throws a typed QueueCapacityExceededError. canEnqueue is removed from QueueManagers public interface. src/handler.ts calls mgr.enqueue() directly and catches QueueCapacityExceededError in enqueueErrorResponse to return HTTP 507.

Key interfaces:

• QueueCapacityExceededError in src/manager.ts: exported domain error thrown when queue depth or count limit is reached.
• QueueManager.enqueue(name: string, payload: T): Manager<T>: executes atomic admission check and throws QueueCapacityExceededError on limit violations; canEnqueue is deleted.
• src/handler.ts: enqueueHandler calls mgr.enqueue(queueName, json.payload) directly without prior canEnqueue check; enqueueErrorResponse handles QueueCapacityExceededError and returns 507 with "Queue full or too many queues".

Acceptance criteria:
[ ] QueueCapacityExceededError is defined and exported from src/manager.ts.
[ ] QueueManager.enqueue throws QueueCapacityExceededError when queueCountLimit or queueDepthLimit is exceeded.
[ ] canEnqueue is removed from QueueManager.
[ ] src/handler.ts calls mgr.enqueue directly and returns status 507 with body "Queue full or too many queues" when QueueCapacityExceededError is caught.
[ ] All unit, handler, and e2e tests pass without relying on canEnqueue.
[ ] Tests verify capacity rejection and HTTP 507 status through public interfaces.

Out of scope:

• Changing queue capacity configuration parsing or default limits.
• Modifying payload validation, JSON parsing, or rate limiting.
• Altering dequeue, peek, or persistence behaviors.