







With the basic structure of the queue server in place, I had to settle how the actual worker would produce and validate results. Putting a request in and claiming capacity isn't enough. AI results can drift in format, external generation can take a long time, and media results must not end up as briefly living external links. The worker had to be both the place that runs the request and the last line of defense that turns the result into a form the product can use.
I didn't cram the worker into a single function. Each task domain has a different executor. What they share is that they collect arrival signals, group them by path, pick only the latest intent, claim capacity and exclusivity, and then hand off to asynchronous execution. What happens after that, though, differs by domain. In some domains the center is message assembly and structure validation, in some it is absorbing results and turning them into assets, and in some the key is observing asynchronous completion.
There was one important principle in this structure. Results made by AI must pass through the same review flow as the editor's existing document state. A structure-preserving transformation must not break its split units, a command-type result must be a structure a machine can apply, and a catalog-based result must lie within the allowed command set. A media result must be an asset the editor can own for the long term, not an expiring external reference. The queue worker is not a proxy that passes the model's response along but a layer that normalizes results to fit the editor's contract.
The text-family executor first gathers the signals that have arrived. Then it groups them by path and picks only each path's latest intent as the target to execute. Of the many requests that came in for the same path, only the latest survives, and the rest are closed out as terminated results. This structure handles a user's rapid repeated clicks and consecutive requests naturally.
After choosing the targets, it secures capacity. If it can't get capacity, the latest intent goes back into the queue and only the old requests are closed. Even if it got capacity, failing to get path exclusivity means the same path is already being processed. In that case it returns the capacity and waits again. Only after obtaining exclusivity does it go into execution. This order is the entry condition of a state machine meant to reduce resource leaks and duplicate runs.
Actual message assembly differs by domain. Some tasks apply strong preservation constraints, some transform while keeping structural boundaries, and some raise quality while keeping the original text's style and tone. Some require generation that continues after the existing body text. They may look like similar AI requests on the surface, but the allowed freedom and validation criteria differ.
Command-interpreting tasks take different input from body-generating tasks. If you mix the problem of rewriting body text and the problem of making editable commands from the selected context into the same message, the model confuses the two goals. A visual-extraction task, even though it hangs off the text executor's path, actually has a different validation space. The executor looks at the mode and changes not only the message but also the validation strategy.
Sending every request to the LLM wasn't good design. Some requests can already be settled by rules. If the sentence a user typed exactly matches an element of the allowed command set, no generative model is needed. At that point a deterministic mapping is enough.
So I put a deterministic gate in front of the generative path. If the input is interpreted as a definite command, the result is produced immediately without calling the model. Even for the same command, if the output contract differs, the shape of the gate's result differs too. What matters is not “what was done” but keeping to the output space the front end expects.
This gate isn't a mere optimization. It reduces cost and latency, but more importantly it handles deterministic behavior deterministically. If you give the freedom of a generative model to an editing command that can be settled, you introduce uncertainty instead. Separating the deterministic path from the generative path, even within an AI feature, keeps the product stable.
The same check could be placed in the front end, but I put the same line of defense on the server too. Even with client bypasses or version differences, definite commands must be handled reliably on the server. Whether it ends at the gate or goes through the model, the cleanup rules are the same. The front end only has to look at how results are received and doesn't need to know which path it ended on internally.
In a structure-preserving transformation, the most important thing was the correspondence of split units. The editor manages the document in fixed units. Even when several units are sent at once, the result must match the original count and order again. If the model merges two units, splits one into two, or skips one in the middle, the editor can't apply the result safely.
So when merging the input array into a single string, I inserted explicit boundary markers. There is a boundary between units, and the instructions repeatedly tell the model to preserve it. When the result comes back, I split it again by the marker and check whether the number of pieces equals the expected count. If it matches, I accept it, and if not, I retry. This isn't a simple string comparison but a process of checking the bijection between input and output.
On retry I reduce the freedom. I state more strongly that the previous output broke the boundaries and how many units are expected. There are times when structural correspondence matters more than natural prose. It's especially so for AI results applied in an editor.
I don't apply the same validation to every task. Tasks where split correspondence is essential, tasks where a single prose output is enough, and tasks that need a structured object each define success differently. Only by separating validation criteria can you cut unnecessary retries and format errors. However well the AI polishes the sentences, if the unit correspondence is broken, it is a failure as an editor feature.
Command-type and extraction-type tasks must not accept natural-language answers. They must return a structure the editor can interpret directly. But generative models often add decoration, put explanations before or after, or make fields that are similar but subtly different. So I put sanitize and parse layers in the worker.
The first step of parsing is to strip the noise and find the candidate object. Then it checks that it is syntactically valid and whether it satisfies the expected shape. If it fails, it isn't accepted and is retried. The retry instruction demands “no explanation, only the agreed structure” more strongly. This is a stretch where format compliance, not writing skill, is the quality criterion.
For catalog-based tasks, I check not only that the JSON is valid but also that the returned command is an element of the allowed set. If it makes up a command that doesn't exist, the editor can't run it. In the problem of turning natural language into commands, quality is measured by catalog adherence.
Some domains have hybrid output. For a writing request the text side may be filled, and for an editing request the command side may be filled. If both are empty, it can still be seen as a valid no-op. In a workspace where one assistant can receive both writing and editing requests, fixing the output space to one side would instead leave it short on expressiveness.
Extraction tasks need schema-specific normalization on top of format validation. If parsing fails, it retries, and for some schemas I even check whether the content is thin even though the format is right. A correct structure and sufficient information are different propositions.
In AI extraction, the last attempt is not always the best. Visual information extraction in particular can have a first result that is quite complete, while a later result has cleaner formatting but misses some of it. So I keep a candidate set, score each attempt on completeness, and preserve the more complete result.
If under-extraction is suspected, the retry instruction changes too. Instead of just “return a valid structure,” it gives a completeness hint to fill in the missed areas. A retry caused by a format error and a retry caused by thin content are different problems. Even for the same retry, if the reason differs, the instruction must differ.
Even if the last attempt failed or came out worse, if an earlier, more complete candidate exists, I keep it. A partially usable result is better than a complete failure, and an earlier attempt may hold more information. This judgment is made by the worker, not the model. The worker is not a place that merely takes down the response but an execution layer that compares and adopts candidates.
The user sees just one request, but inside the server, multiple attempts, validations and candidate preservation take place. Broken responses are discarded, under-extraction is retried, and the most complete result is kept. The difference is greater the more directly omissions show to the user. In the end, the extraction worker became not a model-calling stub but an extraction pipeline that runs through observation, validation and selection.
Image and video workers are more I/O-heavy than text workers. They validate the generation request, claim capacity and exclusivity, and then call the external generator. When they get a result reference in the response, they don't use it as is. An external provider's reference can expire and is unstable as a document asset in a publishing editor. So I absorb it immediately and turn it into a static asset the product owns.
Options are normalized on the server too. Values beyond the allowed range are clamped, unspecified values follow the default policy, and a value the user deliberately left blank is distinguished from one that was never sent. Small differences like these build trust between the UI options and the actual generation results.
Editing-type media tasks require an input asset. If a required input is missing, they end with an empty result. If needed, the input's structure is compressed and attached to the generation context. Information like colors, shapes, text regions and coordinates becomes a signal that raises the accuracy of the edit request. Size limits and cleanup of temporary resources are handled along the way.
Video generation and video editing have longer flows. If the required media is missing, they don't start. Because bad input that reaches the external call wastes cost and time, cutting it at the worker's entrance is right.
What matters in the media worker is ownership of the result reference. If you put an external temporary link into the document as is, the asset may vanish when the book is reopened or sent out later. Every generated result is absorbed into the product's own storage. The editor receives not a provider URL but a static reference managed by Opkle.
A video task doesn't produce a result immediately. You first have to create the job and receive an observable job identifier. If there is no identifier or the creation itself fails, it ends right there. Once the job is created, the worker observes its status at regular intervals.
The status falls into broadly waiting, in progress, succeeded, failed, cancelled and unknown. Waiting and in progress keep waiting, and on success it gets the result reference and ends the loop. Failed, cancelled and unknown close out with an empty result. If a transient network error occurs during observation, it isn't immediately treated as a total failure. A communication error and a task failure are different events.
I also set the observation interval and the maximum wait time clearly. The capacity a long task occupies must be separated from the capacity of tasks that finish quickly. Just because a video takes long, sentence transformations and short command interpretation must not be blocked along with it. It's the same principle as keeping a long-service-time class from eroding a short class in a multi-class queue.
Even after the result reference arrives, the task isn't over. The worker reads its content and absorbs it as a product asset. Since videos can be large, I leave generous transfer and time limits. The final result is not an external link but an asset reference managed by Opkle Editor.
Once this structure is in place, video tasks also enter the editor's general asset-handling flow. The user waits through a long task, but when the result arrives it isn't a mere external link but an asset the product owns. After that, whether it is played in the preview or bundled into a book, it can be handled reliably.
One of the things I considered most important in the queue server was the cleanup path. AI tasks can fail. The external call can fail, structure validation can fail, asset absorption can fail. But if capacity or path exclusivity remains after a failure, the next request gets blocked. So I wrapped the execution part so that it always has a release section regardless of success or failure.
When a task ends, regardless of success, it clears the in-flight registration, releases path exclusivity, returns the capacity and releases the path lock too. This order repeats in every executor. Even if the work differs, the termination invariant must be the same. That way it's clear where to look in a failure situation.
An empty result is a result too. If the input is empty, a required asset is missing, nothing was generated, or absorption fails, it sends an empty termination state. What matters is that the client doesn't keep waiting. Even if it failed, the user must receive a completed state.
The real-time result store has a lifetime. It guarantees time for the UI to pick results up, but keeps results from piling up endlessly in the runtime state. Long-term records are the job of a separate log layer. Only by separating fast execution state from slow history can each focus on its own role.
Cases where only a signal remains and no real latest intent exists are also targets of cleanup. It doesn't touch identifiers that have already claimed capacity and are in progress, and closes only old requests that are no longer valid. The principle was never to leave a pending state unattended in any case.
The final worker loop is a simple structure that keeps spinning. In one tick it calls each task domain's executor in order. Each executor empties its own queue, groups by path, picks the latest intent, claims capacity and the lock, and then runs the actual work asynchronously. The loop itself doesn't do too much and only executes each executor's policy.
I keep the loop's rest interval short. If it's too long, the start delay grows when a user presses AI. The sweep that reclaims stale leases, however, isn't run every tick but at a fixed period. The ordinary loop stays light, and old registrations and locks are cleaned up periodically.
I also run one sweep when the worker starts. That's because there may be in-flight traces left by a previous process that terminated abnormally. Tasks still in the queue can simply be processed again, but if stale registry entries remain, paths can be blocked. The startup sweep is the initial cleanup to go in with a clean state.
Shutdown signals are handled too. When a signal arrives, no new loop starts, and asynchronous tasks already running are cleaned up through their own release path. Restart safety is tied to the in-flight set. If there are no tasks in progress, it can safely restart, and if there are, it can wait. Tasks not yet picked up remain in the queue, so they are not subject to loss.
By this stage the queue server was no longer a simple background process but AI runtime infrastructure. Per-path latest intent, capacity and locks, in-flight registration, retry validation, asset absorption, asynchronous observation, result lifetime, history records, stale sweep and graceful shutdown were all connected into one. In repeated tests, structure preservation, format validation and retry, the deterministic gate, latest-intent priority, termination of old requests, observation of long tasks, asset conversion, restart safety and the cleanup path all passed reliably. Opkle Editor's AI features now run not on a model call but on a worker system that can hold up continuously in a production environment.
