Skip to content

Portolan site map — version 0 ​

Status: draft, version 0. The machine-readable schema is packages/protocol/src/map/schema.ts ($id: https://portolan.dev/schema/map-v0.json); this document explains it.

A map is JSON. A loader validates it against the schema, then runs the cross-field rules in packages/protocol/src/map/load.ts. A map that passes both is what the runtime executes. Unknown fields are rejected: a typo should fail loudly, not silently disable an op.

Top level ​

FieldTypeRequiredMeaning
sitestring, ^[a-z0-9][a-z0-9-]*$, ≤64yesSite id; also the directory name under maps/.
originsstring[], ≥1, each http(s)://yesOrigins the map may address, in preference order.
versioninteger ≥1yesMap version. A session pins one.
statesState[], ≥1yesNamed states an op can start or end in.
opsOp[], ≥1yesThe operations an agent may call.
entitiesobject of JSON SchemayesNamed return shapes shared by ops.
authAuthnoThe signed-out state and the op that signs in.
compiled_fromstring[]yesTrace or run ids this map was learned from.
verified_atstring, ≥1yesISO timestamp of the last verification run.

Auth ​

FieldTypeRequiredMeaning
statestate idyesThe state that means "signed out".
login_opop idyesThe op that signs in.

State ​

FieldTypeRequiredMeaning
id^[a-z][a-z0-9_]*$yesState id, unique in the map.
urlstringnoURLPattern-style path, e.g. /p/:id.
marksLocator[]yesEvery locator must be present to be in this state. Empty means the URL alone identifies it.
notLocator[]noEvery locator must be absent.

Op ​

FieldTypeRequiredMeaning
nameop idyesUnique. This is what call takes.
versioninteger ≥1yesOp revision.
summarystring, 1–200yesOne line for the agent's map view.
paramsJSON SchemayesValidated before execution.
returnsJSON SchemayesThe result is validated against it.
fromstate id[], ≥1yesStates the op may start in.
tostate id[], ≥1yesStates it may end in.
postPostCheck[]yesChecked after the impl runs.
effectread | write | irreversibleyesDrives the safety path.
outcome_checkop idnoA read op that proves whether a write happened.
confirmbooleannoMust be true for irreversible.
implsImpl[], ≥1yesIn preference order; only verified impls run.
statusverified | degraded | brokenyesHealth of the op.

Write rules ​

The loader enforces these beyond the schema:

  • An irreversible op must set confirm: true.
  • An irreversible op may use only webmcp or ui impls.
  • A write op may not use a url impl.
  • A write op with an http impl must set outcome_check.
  • outcome_check must name a read op.
  • Every from, to, post.state, and await_state state must exist.
  • Op names and state ids are unique.

Locator ​

A locator is semantic, never a CSS selector and never a ref. Use exactly one of role, label, or test_id:

FieldTypeMeaning
rolestringAccessible role, e.g. button, textbox.
labelstringForm label, resolved like getByLabel.
test_idstringA stable automation hook the app publishes.
namestringAccessible name; requires role.
name_restringAccessible-name regex; requires role.
ctxstringHuman hint for disambiguation.
ordinalinteger ≥0Which match to use.
attrname | value | text | hrefWhich value to read in an extractor.
attributestringRead an arbitrary DOM attribute, e.g. data-status.
patternstringRegex applied to the extracted string; capture group 1 (or the whole match) becomes the value.

name and name_re are mutually exclusive. A bad pattern fails the load.

Extractor ​

The result of an impl. Exactly one kind:

kindRequired fieldsMeaning
fieldsfields (name → locator, ≥1)Scalar fields.
rowscontainer, row, cols (≥1)A list of rows.
compositefields and/or rowsScalars plus one row list under rows.as.
jsonpath?Dot path into the last HTTP body; empty means the whole body.
download—The downloaded file is the result.
none—The result is an empty object.

Impl ​

In preference order. The first verified impl that fits the state runs.

tierFieldsMeaning
webmcptoolCall a page-provided tool.
urlroute, extractNavigate to a route template. Read-only.
httpsteps, extractRun requests inside the page, with its cookies.
uisteps, extractAct through the semantic UI.

A url route must start with / or http. {param} placeholders are filled and URL-encoded.

HttpStep ​

FieldTypeRequiredMeaning
methodGET | POST | PUT | PATCH | DELETE | HEADyesHTTP method.
urlstringyesRoute template or absolute URL.
headersobject of stringnoHeader templates.
bodyanynoBody template; strings fill {param} recursively.
bindobject of stringnoCapture a value from this response for later steps; the value is a dot path.

UiStep ​

doFieldsMeaning
click | check | unchecktargetAct on a locator.
fill | selecttarget, valueSet a value; {param} is filled.
presskeyPress a key.
await_statestate, timeout_ms?Wait for a state.

PostCheck ​

kindFieldsMeaning
urlpatternThe path matches the regex.
statestateThe page is in this state.
existslocatorThe locator is present.
absentlocatorThe locator is not present.
textlocator, containsThe locator's text contains the string.

Example: read-only ​

json
{
  "site": "acme",
  "origins": ["https://acme.example"],
  "version": 1,
  "states": [
    {
      "id": "home",
      "url": "/",
      "marks": [{ "role": "textbox", "name": "Search" }]
    },
    {
      "id": "results",
      "url": "/search",
      "marks": [{ "test_id": "product-grid" }]
    }
  ],
  "ops": [
    {
      "name": "search",
      "version": 1,
      "summary": "Search the catalog.",
      "params": {
        "type": "object",
        "properties": { "query": { "type": "string", "minLength": 1 } },
        "required": ["query"],
        "additionalProperties": false
      },
      "returns": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": { "type": "string" },
            "name": { "type": "string" }
          },
          "required": ["id", "name"],
          "additionalProperties": false
        }
      },
      "from": ["home", "results"],
      "to": ["results"],
      "post": [{ "kind": "state", "state": "results" }],
      "effect": "read",
      "impls": [
        {
          "tier": "url",
          "route": "/search?q={query}",
          "extract": {
            "kind": "rows",
            "container": { "test_id": "product-grid" },
            "row": { "role": "article" },
            "cols": {
              "id": { "role": "link", "attribute": "href", "pattern": "/p/([^/]+)$" },
              "name": { "role": "link" }
            }
          }
        }
      ],
      "status": "verified"
    }
  ],
  "entities": {},
  "compiled_from": ["trace-1"],
  "verified_at": "2026-11-09T00:00:00.000Z"
}

Example: writes ​

json
{
  "site": "shop",
  "origins": ["https://shop.example"],
  "version": 3,
  "states": [
    { "id": "product", "url": "/p/:id", "marks": [{ "test_id": "product-detail" }] },
    { "id": "cart", "url": "/cart", "marks": [{ "test_id": "cart-table" }] },
    { "id": "order", "url": "/order/:id", "marks": [{ "test_id": "order-id" }] }
  ],
  "ops": [
    {
      "name": "add_to_cart",
      "version": 1,
      "summary": "Add a variant to the cart.",
      "params": {
        "type": "object",
        "properties": {
          "variant_id": { "type": "string", "minLength": 1 },
          "qty": { "type": "integer", "minimum": 1 }
        },
        "required": ["variant_id", "qty"],
        "additionalProperties": false
      },
      "returns": { "type": "object", "properties": {}, "additionalProperties": false },
      "from": ["product"],
      "to": ["cart"],
      "post": [{ "kind": "state", "state": "cart" }],
      "effect": "write",
      "impls": [
        {
          "tier": "ui",
          "steps": [
            { "do": "select", "target": { "label": "Size" }, "value": "{variant_id}" },
            { "do": "fill", "target": { "label": "Quantity" }, "value": "{qty}" },
            { "do": "click", "target": { "role": "button", "name": "Add to cart" } },
            { "do": "await_state", "state": "cart" }
          ],
          "extract": { "kind": "none" }
        }
      ],
      "status": "verified"
    },
    {
      "name": "submit_order",
      "version": 1,
      "summary": "Submit the cart as an order.",
      "params": {
        "type": "object",
        "properties": { "cart_id": { "type": "string", "minLength": 1 } },
        "required": ["cart_id"],
        "additionalProperties": false
      },
      "returns": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"],
        "additionalProperties": false
      },
      "from": ["cart"],
      "to": ["order"],
      "post": [],
      "effect": "write",
      "outcome_check": "order_status",
      "impls": [
        {
          "tier": "http",
          "steps": [
            {
              "method": "POST",
              "url": "/api/orders",
              "headers": { "content-type": "application/json" },
              "body": { "cart_id": "{cart_id}" },
              "bind": { "order_id": "order.id" }
            }
          ],
          "extract": { "kind": "json", "path": "order" }
        }
      ],
      "status": "verified"
    },
    {
      "name": "order_status",
      "version": 1,
      "summary": "Read an order's status.",
      "params": {
        "type": "object",
        "properties": { "order_id": { "type": "string", "minLength": 1 } },
        "required": ["order_id"],
        "additionalProperties": false
      },
      "returns": {
        "type": "object",
        "properties": { "order_id": { "type": "string" }, "state": { "type": "string" } },
        "required": ["order_id", "state"],
        "additionalProperties": false
      },
      "from": ["order"],
      "to": ["order"],
      "post": [],
      "effect": "read",
      "impls": [
        {
          "tier": "http",
          "steps": [{ "method": "GET", "url": "/api/orders/{order_id}" }],
          "extract": { "kind": "json", "path": "" }
        }
      ],
      "status": "verified"
    },
    {
      "name": "checkout",
      "version": 1,
      "summary": "Place the order.",
      "params": {
        "type": "object",
        "properties": { "email": { "type": "string", "minLength": 3 } },
        "required": ["email"],
        "additionalProperties": false
      },
      "returns": {
        "type": "object",
        "properties": { "order_id": { "type": "string" } },
        "required": ["order_id"],
        "additionalProperties": false
      },
      "from": ["cart"],
      "to": ["order"],
      "post": [{ "kind": "state", "state": "order" }],
      "effect": "irreversible",
      "confirm": true,
      "impls": [
        {
          "tier": "ui",
          "steps": [
            { "do": "fill", "target": { "label": "Email" }, "value": "{email}" },
            { "do": "click", "target": { "role": "button", "name": "Place order" } },
            { "do": "await_state", "state": "order" }
          ],
          "extract": {
            "kind": "fields",
            "fields": { "order_id": { "test_id": "order-id", "attr": "text" } }
          }
        }
      ],
      "status": "verified"
    }
  ],
  "entities": {
    "Order": {
      "type": "object",
      "properties": { "order_id": { "type": "string" } },
      "required": ["order_id"],
      "additionalProperties": false
    }
  },
  "compiled_from": ["trace-2", "trace-3"],
  "verified_at": "2026-11-09T00:00:00.000Z"
}

The write example is deliberately conservative: add_to_cart is a ui write, submit_order is an http write with an outcome_check, and checkout is irreversible with confirm: true and a ui impl. The loader rejects any other combination.

Versioning ​

version on the map and on each op is the compatibility contract. A client pins a map version when it opens a session; a new version is a new file (maps/<site>/v<n>.json). A breaking change to this document is a new map schema version, not an edit to v0.

Released under Apache-2.0 · MIT · CC-BY-4.0