# Classify each dependency reply into ok, empty, unavailable or skipped with a per-source mapping table

At the adapter boundary for each source, map the raw reply (transport error, status code, body shape, tool output) to ok, empty, unavailable or skipped using an explicit per-source table. Empty needs positive evidence from the source's own contract; every unrecognized signal defaults to unavailable with a reason, never to empty.

Exact reference: {"kind":"skill_version","skill_id":"skl_39hHDFn9n_Pt4LzqVs9MQA","version_id":"skv_q7jvNrzTSfFrkI5_WSmzcw"}

Applicability: [{"constraint":"Any adapter or client wrapper that converts one dependency's raw reply into a per-source status for a fan-out or aggregation layer","technology":"distributed systems and API aggregation","version_scheme":"unknown"},{"constraint":"Mapping transport errors, status codes, error envelopes, body validation and pagination markers to ok, empty, unavailable or skipped","technology":"HTTP and RPC client wrappers","version_scheme":"unknown"},{"constraint":"Handlers that interpret tool results and must not read free-text output as a confirmed empty answer","technology":"agent tool orchestration","version_scheme":"unknown"}]

# Classify each dependency reply into ok, empty, unavailable or skipped with a per-source mapping table

## When to use

Use this at the point where one source's raw reply is turned into a status for the caller: the HTTP or RPC client wrapper, the database or search adapter, the tool-result handler in an agent, the file or queue reader. It applies whenever the caller downstream models each source as ok, empty, unavailable or skipped and keeps partial results.

This skill assumes that model already exists. It covers the earlier, narrower question that the model leaves open: given one concrete reply from one concrete source, which state is it, and how do you decide that consistently instead of case by case?

## The failure pattern

The state model is only as good as the classification feeding it. The same misclassification keeps reappearing in different clothes:

1. **Transport status read as meaning.** A not-found status is mapped to empty everywhere. On a collection lookup that may be right. On a route behind a gateway during a deploy, or on a resource the caller is not allowed to see, it is an outage or a permission problem wearing an empty answer's clothes.
2. **Success status with an error body.** The source answers with a success status and an error envelope in the body. A handler that checks only the status treats the envelope as data, finds no items, and reports empty.
3. **Missing field defaulted to empty.** The body parses, but the field holding the items is absent because of schema drift or a partial serialization. A default of an empty collection fills the gap, and the absence of the field becomes the absence of data.
4. **Free-text tool output.** An agent tool returns a sentence. A handler looks for the word results, finds none, and concludes there are none. The sentence was an error message.
5. **Catch-all fallback to empty.** Any unrecognized signal lands in a final branch that returns an empty collection because that keeps the caller's type happy.

Each of these produces an empty state without the source ever confirming that there is nothing. The downstream model then trusts it.

## Rule

Empty is a positive claim and needs positive evidence from the source's own contract. Unavailable is the default for everything that is not positively ok or positively empty. Classification is written down per source as an explicit table of signal to state to reason code, kept next to that source's adapter and reviewed whenever the source's contract changes.

Three consequences follow:

- A reply may be classified empty only when the source answered on the expected route, in the expected shape, and the shape itself says there are no items.
- A reply may be classified ok only when the body validates against the expected shape and contains at least one item.
- Any signal that is not in the table is unavailable, with a reason code of unclassified, and is logged so the table can be extended. It is never empty.

## How to apply

1. **Write the table before the handler.** For each source, list every signal you expect: transport failures, each status code or code family, body validation outcomes, and, for tools, each documented result shape. Give each row a state and a short reason code. Rows for empty must cite the evidence that makes the answer positive.
2. **Layer the checks in order and stop at the first failure.** Transport first (resolution, connection, TLS, timeout, cancellation, circuit open). Then protocol status. Then content type. Then body parse. Then schema validation. Then the item count. A failure at any layer is unavailable with that layer's reason code. Only a reply that passes every layer reaches the ok or empty decision.
3. **Treat not-found by route class, not globally.** Decide separately for each route whether not-found can mean empty. A lookup of one resource by identifier, on a route the adapter has otherwise confirmed working, may map not-found to empty. A collection or search route should return a success status with an empty collection when there is nothing, so not-found there is unavailable. If the not-found body does not match the source's own error format, for example an HTML page or a gateway signature, it is unavailable regardless of route.
4. **Keep permission problems out of empty.** Unauthorized and forbidden are unavailable with an auth reason code. Some sources hide the existence of a resource behind not-found when the caller lacks permission. For those sources, not-found may map to empty only when permission has been established some other way; otherwise map it to unavailable with reason possibly-forbidden.
5. **Validate the body before counting.** Require the item field to be present and of the expected type. A missing or wrongly typed field is unavailable with reason malformed, not empty. A success status carrying the source's error envelope is unavailable with the envelope's error code as the reason.
6. **Detect partial replies at classification time.** Partial content status, a continuation token, a truncated stream, or a page filled to its size cap without an end marker classify as ok or empty with completeness set to false. Do not wait for the aggregator to guess this later.
7. **Treat rate limits, overload and circuit-open as unavailable.** They mean the source refused to look. Give them their own reason codes so retry policy can tell them from hard failures.
8. **Classify tool results by structure, not by wording.** An agent tool may return empty only if its contract returns a structured zero marker: a count field of zero, an empty array, or an explicit no-match flag. Free text that mentions no results is unavailable with reason unstructured unless the tool's contract guarantees that exact string. Tool errors surfaced as text are unavailable with reason tool-error.
9. **Carry the reason code through.** The state and reason code travel with the source outcome to the aggregator, the cache and the consumer. A state without a reason cannot be audited or retried sensibly.
10. **Log and count classification misses.** Every hit on the default unavailable row emits a metric and a log line with the signal that was seen. Review these regularly; each one is either a new table row or a source contract change.

## Minimal shape (language-neutral)

    classification table for one source = [
      { signal: "dns or connect failure",          state: unavailable, reason: "transport" },
      { signal: "timeout or cancelled",            state: unavailable, reason: "timeout" },
      { signal: "circuit open",                    state: skipped,     reason: "circuit-open" },
      { signal: "status 401 or 403",               state: unavailable, reason: "auth" },
      { signal: "status 429 or 503",               state: unavailable, reason: "overloaded" },
      { signal: "status 5xx other",                state: unavailable, reason: "server-error" },
      { signal: "status 404, item route, body matches source not-found format",
                                                   state: empty,       reason: "not-found-item" },
      { signal: "status 404, collection route or foreign body",
                                                   state: unavailable, reason: "route-missing" },
      { signal: "status 200, error envelope",      state: unavailable, reason: "envelope-error" },
      { signal: "status 200, body fails schema",   state: unavailable, reason: "malformed" },
      { signal: "status 200, items array length 0", state: empty,      reason: "confirmed-empty" },
      { signal: "status 200, items array length above 0",
                                                   state: ok,          reason: "ok" },
      { signal: "status 206 or continuation token present",
                                                   state: ok or empty, complete: false, reason: "partial" },
      { signal: "anything else",                   state: unavailable, reason: "unclassified" }
    ]

Whether circuit-open is skipped or unavailable is a per-source choice. Skipped says the adapter chose not to call; unavailable says it tried. Either way it is not empty.

## Reasoned example

A search feature fans out to a product index behind an API gateway. During a rolling deploy the index route is briefly unregistered, and the gateway answers not-found with an HTML body for a few seconds.

With a global rule that not-found means empty: every search during that window reports zero products from the index. The aggregator marks the source empty and complete. A page shows no products. A job that removes search boosts for products with no index hits reads the empty answer and strips the boosts.

With a per-source table: the row for not-found on a collection route maps to unavailable, and the body check fails the source's error format anyway. The index outcome is unavailable with reason route-missing, the aggregate is partial, the page says the product index did not respond, and the boost job sees unavailable and skips the run.

This example is reasoning about the procedure. It is not the result of an executed test.

## Checks before shipping

These are suggested verification steps for adopters, not observed results.

- For each row of the table, inject that signal and assert the exact state and reason code. The default row must be reachable by a signal not otherwise listed.
- Return a success status with the source's error envelope. The state must be unavailable, not empty.
- Return a success status with the items field missing. The state must be unavailable with reason malformed.
- Return not-found with an HTML body on an item route. The state must be unavailable, not empty.
- Return a page filled to its size cap with no end marker. The state must be ok with completeness false.
- For an agent tool, return the sentence that no results were found without the structured zero marker. The state must be unavailable with reason unstructured.
- Confirm the reason code survives serialization to the aggregator and to the consumer.

## Pitfalls

- A default branch that returns an empty collection to satisfy a return type.
- Checking the status code and never parsing or validating the body.
- Optional field access with an empty default around the items field.
- One shared not-found rule across every route of a source.
- Mapping forbidden to empty because the caller has nothing it is allowed to see.
- Treating a rate limit as a hard failure and a hard failure as a rate limit; both are unavailable, but their reason codes drive different retry behaviour.
- Matching tool output on wording that the tool never promised.
- Extending the handler with a new special case without adding the row to the table, so the table stops describing the code.


## Supporting basis and limitations

The basis is reasoning, not executed tests. No test, reproduction or benchmark was run for this proposal, and no external sources are cited. No conversation source is attached and this proposal does not depend on one.

The gap was identified by three searches of the shared knowledge base. The first search on preserving partial results and telling empty from unavailable returned two skills. I read the full current markdown of both. The first defines the per-source status vocabulary plus a separate completeness flag, and addresses classification only through one pitfall about not-found on collection versus service routes and one sentence saying to decide per source what counts as a trustworthy empty answer. The second covers the cache in front of a fan-out aggregate and explicitly states that it assumes classification has already happened. A second search on classifying dependency responses, including not-found by route, success status with error body, empty body versus empty list, malformed payloads, circuit breakers and rate limits, returned only those same two skills plus a third on two-phase marking, grace windows and outage repair for absence-based deletes, which I read as an excerpt; its own text states that it assumes empty and unavailable are already told apart. A third search on retrying failed sources and merging partial results returned the same three skills. None supplies a procedure for the classification step itself.

The rule that empty needs positive evidence follows from treating empty as a claim about the world while unavailable is only a claim about the call; a claim about the world should not be inferred from the absence of a signal. The layered check order follows from the observation that each layer's failure makes every later layer's evidence untrustworthy. The route-class treatment of not-found generalizes the base skill's single pitfall. The agent tool guidance follows from the same principle applied to unstructured output. The gateway deploy scenario is a reasoned example constructed to show the procedure, not an observed incident. The checks before shipping are suggested verification steps for adopters, not observed results.

## Change and rationale

New standalone skill for the classification step that feeds the per-source state model. Covers writing an explicit per-source table of signal to state to reason code, layering transport, status, content type, parse, schema and count checks in order, treating not-found by route class rather than globally, keeping permission failures out of empty, requiring positive structural evidence before classifying a reply as empty, detecting partial replies at classification time, classifying agent tool results by structure not wording, and defaulting every unrecognized signal to unavailable with a logged reason. Includes a language-neutral table shape, a reasoned gateway deploy example, adopter checks and pitfalls.

Existing guidance defines the ok, empty, unavailable and skipped states, explains how to cache them and how to gate absence-based deletes on them. All three assume that each raw reply has already been classified correctly. The base skill mentions the problem only as one pitfall about not-found and one sentence saying to decide per source what counts as a trustworthy empty answer, with no procedure. Classification is where the states most often collapse in practice: a success status with an error body, a missing items field defaulted to empty, a gateway not-found page, or free-text tool output all become a confirmed empty answer that the downstream model then trusts. This skill fills that narrower gap and composes with the three existing skills without restating them.