We added a new capability to the Cap URN model: generic caps can now express more precisely what happens to file type at runtime.

This is what the new fourth axis is for.

Why generic caps matter

Some transformations are concrete from the start:

  • PDF to text
  • audio to transcript
  • image to description

Those are easy to describe. The input is known, the output is known, and the planner can route them directly.

But some tools are more general than that.

They do not exist to convert one media type into another. They operate on structure while preserving the concrete file type of whatever they are given at runtime.

That is what we mean by a generic cap.

The simplest shape looks like this:

media: -> media:

That says:

  • this tool accepts media
  • this tool produces media

But for a generic cap, that is still not enough information.

There is an important distinction between:

  • “the output is the broad declared output”
  • “the output preserves the concrete runtime file type of the input”

Those are different semantics, and they matter for routing.

The motivating case: decimate

Take a sequence operation like decimate.

Its job is not to convert PDFs into something else, or JPEGs into something else. Its job is to take a sequence and reduce it according to some rule while preserving the actual item type.

So if you give it:

  • a list of PDFs
  • a list of images
  • a list of audio files

the output should still be:

  • PDFs
  • images
  • audio files

respectively.

That sounds obvious from a user perspective. But the old three-axis model did not let us express that distinction explicitly enough. The planner could see a generic input and a generic output, but it could not cleanly represent the fact that the runtime output still inherits the concrete media identity from the runtime input.

The practical result is that cases like decimate are now modeled directly instead of being forced into a shape that was better suited to fixed conversions.

The new axis: effect

Before this change, a cap mostly described:

  • what it accepts
  • what it declares as output
  • non-directional tags describing the operation

That was:

(i, o, u)

Now a cap is:

(i, o, e, u)

where e is the new effect axis.

The effect axis describes how the runtime output relates to the runtime input.

The important cases are:

  • effect=declared
    • the output is exactly what the cap declares
  • effect=none
    • the cap preserves runtime media identity
  • effect=patch
    • the cap transforms runtime media identity in a structured way

For generic caps like decimate, the key case is effect=none.

If a cap says:

media: -> media:

and also says:

effect=none

then a runtime input of media:pdf produces a runtime output of media:pdf.

The same logic holds for PNG, WAV, JSON, and anything else the cap can legally operate on.

What this unlocks

The immediate gain is not a prettier theory. It is better routing for a real and important class of transformations.

MachineFabric can now represent tools that are:

  • generic over input type
  • structurally meaningful
  • runtime-preserving with respect to file identity

That improves recommendation quality for cases like decimate and for any future cap that operates on files generically without converting them into a different media family.

In other words:

  • concrete conversions still work as before
  • generic runtime-preserving tools are now first-class
  • the planner no longer needs special handling to understand what those tools mean

It also clarifies identity

This change also sharpens an older ambiguity around identity.

Previously, the generic top form:

cap:in=media:;out=media:

looked like it might be identity, but it did not explicitly say that the runtime media identity was preserved.

With the new model, identity becomes explicit:

cap:effect=none

That is a cleaner and more honest statement of what identity means in a system that has to reason about runtime type preservation.

The broader point

The goal of MachineFabric is not just to chain a fixed catalog of concrete file conversions.

The goal is to let users name a destination and let the system find the right route, even when the right route passes through tools that are generic rather than narrowly format-specific.

Adding the fourth axis makes that possible in a more principled way.

It gives generic Cap URNs a precise place in the model, and it improves real user-facing cases such as decimate by making the planner better at understanding what those caps actually do.