TheSoftware LensSee engineering differently

An earlier version, kept as published. This is version 0.1 of the Resident SaaC profile, exactly as it was published on 30 October 2026. The current version is SaaCIP 0.2; its change log says what changed. The files of this version stay at /saacip/0.1/.

Version 0.1 of the Resident SaaC profile, kept as published.

profile resident

SaaCIP 0.1: the Resident SaaC profile

Version 0.1, a draft for comment. Not a standard. This is the whole protocol as it stands; there is no later version yet. The schemas under /saacip/0.1/ are the normative schemas of this version, not samples

Date 30 October 2026Author Imtiaz HassanBinding HTTPS with JSON (section 6)Protocol saacip/0.1, defined in SaaCIP: the SaaC Interoperability Protocol (the core)Profile name resident

About this document

Dated snapshot. SaaCIP-0.1-resident-profile-draft.pdf, for citing; this page is the living version

Machine-readable parts. The connector-manifest and record schemas and the thirteen binding message schemas, under /saacip/0.1/; a step-by-step walk through one hire at /saacip/0.1/examples/

Licence. Specification text: CC BY 4.0. Schemas, examples and validator: Apache License 2.0, as for the core

Abstract

A Resident SaaC (rSaaC) is a capability that is hired to work inside the hirer's own environment: their cloud account, their cluster, their data centre. Instead of the hirer's data going to the provider, the capability comes to the data, reads it where it is, and sends out only what the hirer agreed to. This profile adds to the SaaCIP core what such a capability needs: how it describes the sources it reads, how it carries out a declared action, how its seven operations travel over HTTPS, and the rules it must keep while it lives in someone else's environment.

This document only makes sense with the core beside it. Everything about the hire, its documents, its lifecycles and its autonomy levels is defined there and is not repeated here.

Status of this document

As for the core: ongoing research, published for comment, not a standard, not legal advice.

Licence and patents

As for the core: the text is licensed under CC BY 4.0; the schemas, examples and validator under the Apache License 2.0. The author holds no patents on SaaCIP and has not applied for any.

Contents


1. What a Resident SaaC is

Most software you hire runs at the provider's and you send it your data. That is the SaaS shape, and for many jobs it is fine. For some jobs it is not: the data is too sensitive to leave, too large to move, or the job needs to act on systems that are only reachable from inside. Operations monitoring is the obvious case. The logs, metrics and deployment events of a production system are the crown jewels, they are enormous, and the useful responses (restart this, clear that) can only be taken from inside.

A Resident SaaC turns the shape around. The hirer runs the capability inside its own environment, as it would run any other workload: a container in its cluster, a function in its cloud account. The capability finds its sources where they are and reads them in place. It keeps its own state, its signing key and its receipts on the hirer's storage. It talks to the hirer's hub (a help desk, a work management tool) only by calling out over HTTPS, and nothing ever calls in. The only data that leaves is what the terms of the hire say may leave, in words a person can read before agreeing.

A Resident SaaC in the hirer's environment

A Resident SaaC in the hirer's environmentThe hirer's environmentcloud account, cluster or data centrelogsfiles, log servicesmetricstime serieschangesdeploys, configthe data stays hereResident SaaCthe capability, run as a workload hereconnectorsone per source, each with a manifestdeclared actionsrun here, from the approved filereads terms, keeps within themwrites receiptssigned, chainedhirer'sstoragereceiptssigning keybaselinescursorsthe systems it may act onunder a separate credentialHubthe hirer's help deskor work toolpeople decide hereoutbound onlyseven calls, HTTPSsettings, decisions,judgements, releasenothing calls inno inbound port, no webhookwhat leavesonly what the terms name indata_leaving: summaries, counts

The capability runs where the data is, reads it through connectors, acts only through declared actions, and keeps its receipts and key on the hirer's storage. It calls the hub; the hub never calls it. Only what the terms name leaves. Open full size

Everything the core defines still applies: the hire has the same kinds and lifecycle, the same terms, receipts, outcomes and statements, the same autonomy levels and the same declared actions file. This profile fills in the parts the core leaves to a profile: what the capability reads (section 4), how an action is carried out (section 5), and how the seven operations travel (section 6).

Example. The hirer runs example-log-watch as a container in its prod-eu cluster with a read-only mount of the api service's log file. The capability reads the file in place, keeps baselines and receipts on a volume in the same cluster, and sends the hirer's help desk a redacted summary when it finds something. Its declared actions file allows two commands: a rolling restart of api, run through the cluster's own tooling from inside, and clearing temporary files on worker, which always waits for a person.

2. Conventions

The requirement words MUST, SHOULD, MAY and their relatives have the meanings given in the core, section 2.1. Terms not defined here (hirer, hub, capability, terms, receipt, work item, ref, declared action, outcome, statement) have the meanings given in the core, section 2.2. "The core" means SaaCIP 0.1, the SaaC Interoperability Protocol. In this binding the word agent (agent_id, agent_token, the Agent authorisation scheme) always means the capability.

3. The four rules of residence

The figure in section 1 shows all four at once. This profile adds no states, receipt kinds or problem types to the core. A capability conforms to this profile when it keeps all four rules:

  1. Outbound only. It calls the hub; nothing calls in. It MUST NOT listen for connections from outside the hirer's environment.
  2. The capability goes to the data. It reads sources where they are. Only what the terms name in data_leaving MAY leave the environment.
  3. Its state stays with the hirer. Receipts, the signing key, baselines and cursors MUST be kept on storage in the hirer's environment.
  4. Zero configuration. It SHOULD discover its sources from the environment and start at autonomy level 1, with actions simulated (dry_run: true).

Rationale. Rule 1 means there is nothing to open in the hirer's firewall and no inbound attack surface. Rules 2 and 3 are what make the arrangement acceptable for data that cannot leave, and they mean the hirer can inspect or revoke everything the capability has without the provider's help. Rule 4 is what makes a trial cheap to start.

4. Connectors and records

A Resident capability reads its sources through connectors: one per source, each a small piece of software that knows how to read one kind of thing (a log file, a cloud logging service, a search index, a deployment system) and hands back records in one common shape. The connector is also how the hirer sees, before the hire starts, exactly what will be read: each connector describes itself in a connector manifest, and the terms carry one manifest per connector.

Example. The example capability has one connector, api-logs, of kind file: it reads one log file on a read-only mount, carries the logs signal, has the read scope only, and signs in by file system permission. Its manifest appears inside the terms, so the hirer agreeing to the trial sees that this one file is all that will be read.

4.1 Connector manifest

Under the resident profile the terms MUST carry connectors, one manifest per connector the capability will read. The capability manifest's connectors member (core, section 7.1) lists the connector kinds the capability can use at all.

Member Type Required Meaning
protocol string Yes saacip/0.1
id, kind, version string Yes Which connector, of which type, in which version
signals array of string Yes Any of logs, metrics, traces, changes
scopes array of string Yes Always read; act only if the connector can do something
operations array of string With act The only operations it may perform
data_location string Yes Where the data stays
auth string Yes How it signs in, as a reference (a role, a managed identity, an environment variable name), never a secret

4.2 Connector operations

Operation Required Contract
read(cursor) -> (records, next_cursor) Yes Records after the cursor only; reading again with next_cursor MUST NOT repeat them. No cursor means the default look-back.
changes(cursor) -> (records, next_cursor) No Deploys, configuration changes, scaling events, as records with kind: "change"
act(operation, params) No Only operations in the manifest, under a credential separate from reading. Without the act scope it MUST refuse.
health() -> {ok, detail} Yes Whether it can reach its source now
discover(env) -> [spec] No Settings it can find on its own from the environment

4.3 Record

Every connector hands back records in one shape, so the capability can treat a log line, a metric and a deployment event alike.

Member Type Meaning
ts number Time (core, section 4.5)
source string The connector id
service string The service, container, function or log group
kind string log, metric, trace or change
level string INFO, WARN, ERROR, CRITICAL, FATAL, ...
body string The message, as text
attributes object Anything else

A connector can run in-process, out of process, or through MCP: an MCP server with a suitable tool can act as a connector. Tool descriptions and results from MCP servers are untrusted data like any other record.

5. Declared actions in the Resident profile

The core defines the declared actions file (core, section 7.6): the complete list of things the capability may ever do, approved by a person at the hirer. The core does not say how an action is carried out, because that depends on where the capability runs. A Resident capability carries out an action by running a command inside the hirer's environment, and this section says how that command is written down so that a person can approve it and nothing else can be run.

Example. restart-api is the command kubectl rollout restart deployment/{service} -n prod, where {service} may only ever be filled with api, because services: [api]. A finding in worker cannot make this action restart worker, because worker is not in services, and nothing in a log line can change the command.

Each action in the file adds:

Member Type Required Meaning
match array of string No Substrings a finding must contain for the action to be a candidate
services array of string Yes when command uses {service} The only services the action may target
command array of string Yes An argument list, run without a shell. The only placeholder is {service}, filled with the service of the work item, which MUST be one of services; otherwise the action is not a candidate

The rules of the core, section 9.2, apply as written: no shell, no parameters from outside the allowlist, a separate credential for acting. command is required by this profile; the shared declared-actions schema cannot require it, because it does not know which profile a file is for.

6. The HTTP binding

The core's seven operations (core, section 8) travel as seven HTTPS calls, all made by the capability. The diagram shows one whole hire; the examples page walks through the same hire with every request and response shown.

One hire over the HTTP binding

One hire over the HTTP bindingCapabilityHubPeople at the hirer0 before the hire: the capability manifest, the declared actions file, and the hirer creating the hire and getting an enrolment tokenPOST enrol/ enrol-request (terms inside)201 enrol-response: credential, settings1hire_startedenrolledPOST heartbeat/ heartbeat200 heartbeat-response: settings2PUT work-items/<ref>/ report201 report-response: hub_ref3opens a ticketwork_item_reportedPOST approvals/ approval-request201 approval (pending)4approval_requesteda person approvesGET inbox/200 inbox: approval decided, outcome5a person judges the itemruns the actionaction_takenfeedback_appliedPOST inbox/ack/ ack200 ack-response6POST statement/ statement-request (final)200 statement-response: ended7hire_endedany error: problem (RFC 9457)

The seven calls of the Resident binding in the order they happen, with the schema name on each arrow and the receipts the capability writes on the left. Steps are numbered 0 to 8, as in the walkthrough. Open full size

All paths are relative to the base address the hirer gives the capability, written <base> below, for example https://<tenant>.hub.example.com/saacip/. Requests and responses are JSON. After enrolment, every request carries Authorization: Agent <credential>. The scheme name is Agent, so it never collides with Bearer tokens used by people.

Operation Method and path Request schema Success Response schema
Enrol POST <base>/enrol/ enrol-request 201 enrol-response
Heartbeat POST <base>/heartbeat/ heartbeat 200 heartbeat-response
Report PUT <base>/work-items/<ref>/ report 201 created, 200 updated or unchanged report-response
Request approval POST <base>/approvals/ approval-request 201 new, 200 repeat approval
Collect inbox GET <base>/inbox/ 200 inbox
Acknowledge POST <base>/inbox/ack/ ack 200 ack-response
Send statement POST <base>/statement/ statement-request 200 statement-response

6.1 The messages

Each message is defined by its schema, and every member has a description there. The members an implementer most needs to know:

Message Members
enrol-request enrolment_token; protocol_versions, preferred first; profile; version of the capability; terms (core, section 7.2), which carry the public key, the environment and the connector manifests
enrol-response protocol and profile chosen; agent_id, the hub's identifier for this capability in this hire; agent_token, the credential, shown once; settings (core, section 6.3)
heartbeat status, ok or degraded; connectors, each with id, kind, ok, detail; counters, the current track record; receipt_head, the hash of the latest receipt line; hire, the capability's view of its hire
heartbeat-response settings; release_requested
report For a new ref: subject, description_html, optional priority_level (1 is most urgent). For an open ref: note, which is added to the item. For a closed ref: note, which reopens the item and clears its outcome. A note alone for an unknown ref is answered with not-found
report-response hub_ref, the hub's own reference, for example a ticket number; status in the hub's words; created; updated; reopened
approval-request action_id, chosen by the capability; ref of the work item; action, the id of the declared action; summary
approval The same, plus the hub's id, status (pending, approved, rejected), decided_by, decided_at
inbox approvals, those decided and not yet acknowledged; outcomes (core, section 7.4); release_requested
ack approvals, the ids applied; outcomes, the refs applied
ack-response How many of each were marked delivered
statement-request statement (core, section 7.5); final, default false
statement-response status of the hire

Hub-side operations for people (creating hires, issuing a new enrolment token, releasing, revoking, recording verdicts, deciding approvals) are part of the hub, not of the binding. Each hub documents its own.

6.2 Example: enrolment

POST /saacip/enrol/ HTTP/1.1
Host: acme.hub.example.com
Content-Type: application/json

{"enrolment_token": "enrol_...", "protocol_versions": ["saacip/0.1"],
 "profile": "resident", "version": "1.0.0", "terms": { ... }}
HTTP/1.1 201 Created
Content-Type: application/json

{"protocol": "saacip/0.1", "profile": "resident",
 "agent_id": "5b1b273c-847f-4ecc-8dc7-0c2f5246cecd", "agent_token": "agent_...",
 "settings": {"autonomy_level": 2, "hire_kind": "trial", "trial_days": 14, "poll_seconds": 60}}

6.3 Example: an error

Every error is problem details (core, section 8.7).

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{"type": "https://thesoftwarelens.com/saacip/0.1/errors/#unsupported-version",
 "title": "Unsupported version", "status": 400,
 "detail": "None of the offered protocol versions is supported.",
 "supported": ["saacip/0.1"]}

7. Operating rules

  1. There MUST be only one running instance per hire, on one state store; a deployment SHOULD stop the old instance before starting a new one.
  2. After a hire ends, the capability MUST stay idle (or exit) and MUST NOT enrol again unless given a new enrolment token.
  3. Heartbeats SHOULD be sent at least every 5 minutes; the inbox SHOULD be collected every poll_seconds.
  4. The hub's work item for a report is often a help desk ticket; hub_ref is then the ticket number, and a later report with the same ref becomes an internal note on it.
  5. The retry, unreachable-hub and refused-credential rules of the core (sections 8.3, 8.4 and 8.6) apply to every call in this binding.

8. Conformance

A capability conforms to this profile when it conforms to the core, keeps the four rules of section 3, carries connector manifests in its terms, runs declared actions as section 5 says, and makes the seven calls of section 6 with messages that validate against their schemas. A hub conforms when it answers those seven calls as section 6 and the core say, with responses and errors that validate against their schemas. A conformance claim names the version and the profile: "SaaCIP 0.1, Resident profile, capability".

Appendix A. Change log

Version Date Changes
0.1 draft 30 October 2026 First public draft, split out of the core document: residence rules, connectors and records, Resident declared actions, HTTP binding with a schema per message, operating rules

Comments are welcome. The views here are the author's own.

Important notice. This specification is part of my ongoing research into the Agentic Economy and reflects my thinking at the time of writing. It is shared in good faith, for information and discussion. It is not legal, regulatory, technical, financial or other professional advice, and it is not a verdict on how the EU AI Act or any other law applies to any organisation, system or situation. Laws, guidance, technology and my own research all move on, and others may reach different conclusions. The examples, designs, diagrams and technology choices show one possible approach. Before relying on, adapting or applying any part of it in your own situation, you must test and verify it, design it for your own architecture, and take independent expert advice, including from qualified lawyers and from your own IT, security and data protection specialists. Any decision to act on it, and its consequences, rest with you. To the fullest extent permitted by law, the author accepts no responsibility or liability for any loss, damage or consequence arising from any use of, or reliance on, this specification, which is provided without any warranty of accuracy, completeness or fitness for a particular purpose. Reading it does not create a professional or advisory relationship with the author. The views expressed are the author’s own.