@topolo/sdk 0.14.4 → 0.16.0

package/README.md

@@ -86,6 +86,80 @@ Every request sends:
 Combined with the credential identity, this makes every platform API call
 traceable to a specific agent invocation.
 
+### Actor provenance
+
+`ActorEnvelope` is the versioned authority and provenance contract for work
+performed by humans, Topolo-managed agents, external harness installations,
+services, and declared browser automation. It always records the accountable
+subject and actual performer independently and binds them to one organization,
+task/run lineage, channel, assurance level, action, resource, and canonical
+input hash.
+
+```ts
+import {
+  parseActorEnvelope,
+  sha256CanonicalValue,
+  type ActorEnvelope,
+} from '@topolo/sdk';
+
+const actionInput = { designId: 'design_123', decision: 'approve' };
+const actorEnvelope: ActorEnvelope = parseActorEnvelope({
+  schemaVersion: 1,
+  organizationId: 'org_acme',
+  accountableSubject: {
+    principalType: 'human',
+    principalId: 'usr_ashley',
+    displayName: 'Ashley Lane',
+  },
+  performer: {
+    principalType: 'external_agent',
+    principalId: 'installation_codex_macbook',
+    installationId: 'installation_codex_macbook',
+    provider: 'openai',
+    model: 'gpt-5',
+  },
+  delegation: {
+    taskId: 'task_123',
+    runId: 'run_456',
+    lineage: [
+      { principalType: 'human', principalId: 'usr_ashley' },
+      { principalType: 'external_agent', principalId: 'installation_codex_macbook' },
+    ],
+  },
+  channel: 'mcp',
+  assurance: { level: 'workload_identity', methods: ['oauth_client'] },
+  action: {
+    requestId: 'req_789',
+    actionId: 'app_topolo_design.designs.approve',
+    resourceType: 'design',
+    resourceId: 'design_123',
+    inputHash: await sha256CanonicalValue(actionInput),
+  },
+  issuedAt: new Date().toISOString(),
+});
+
+await topolo.client.callAction(
+  actorEnvelope.action.actionId,
+  actionInput,
+  {
+    actorEnvelope,
+    resource: { resourceType: 'design', resourceId: 'design_123' },
+    confirm: true,
+  },
+);
+```
+
+The parser rejects unknown fields, unsupported principal types, partial
+resource bindings, malformed hashes, and non-human performers without a
+delegation chain. External agents require an installation and provider;
+managed agents require an agent instance; browser automation requires both an
+installation and a browser-session identity. `X-Topolo-Agent` remains useful
+telemetry but is never trusted as provenance or approval authority.
+`callAction` and `readAction` validate the envelope against the exact action,
+input and resource before sending its canonical base64url representation in
+`X-Topolo-Actor-Envelope`; the envelope request ID also becomes the transport
+request ID.
+
 ## Modules
 
 | Surface      | Methods                               |

package/dist/index.cjs

@@ -21,10 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ACTION_CATALOG_DIGEST_ALGORITHM: () => ACTION_CATALOG_DIGEST_ALGORITHM,
+  ACTOR_ENVELOPE_VERSION: () => ACTOR_ENVELOPE_VERSION,
+  ActorEnvelopeValidationError: () => ActorEnvelopeValidationError,
   CrmModule: () => CrmModule,
   DEFAULT_APP_URLS: () => DEFAULT_APP_URLS,
   IdentityModule: () => IdentityModule,
   P2PModule: () => P2PModule,
+  TOPOLO_ACTOR_ENVELOPE_HEADER: () => TOPOLO_ACTOR_ENVELOPE_HEADER,
   TOPOLO_ENVIRONMENT_SERVICE_URLS: () => TOPOLO_ENVIRONMENT_SERVICE_URLS,
   TOPOLO_RUNTIME_ENVIRONMENTS: () => TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION: () => TOPOLO_WIDGET_CONTRACT_VERSION,
@@ -42,10 +45,12 @@ __export(index_exports, {
   actionContractCompleteness: () => actionContractCompleteness,
   applicationEntryFromCatalog: () => applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment: () => assertTopoloServiceUrlEnvironment,
+  canonicalJson: () => canonicalJson,
   canonicalTopoloErrorCode: () => canonicalTopoloErrorCode,
   canonicalTopoloRequestId: () => canonicalTopoloRequestId,
   canonicalTopoloRequired: () => canonicalTopoloRequired,
   canonicalTopoloRetryAfter: () => canonicalTopoloRetryAfter,
+  canonicalizeActorEnvelope: () => canonicalizeActorEnvelope,
   compactActionCatalogEntry: () => compactActionCatalogEntry,
   compactActionPlan: () => compactActionPlan,
   compactActionPreparation: () => compactActionPreparation,
@@ -55,12 +60,14 @@ __export(index_exports, {
   createTopoloAgentExecutionContext: () => createTopoloAgentExecutionContext,
   createTopoloWidgetError: () => createTopoloWidgetError,
   createTopoloWidgetResponse: () => createTopoloWidgetResponse,
+  decodeActorEnvelopeHeader: () => decodeActorEnvelopeHeader,
   defineTopoloActionsWidget: () => defineTopoloActionsWidget,
   defineTopoloActivityWidget: () => defineTopoloActivityWidget,
   defineTopoloChartWidget: () => defineTopoloChartWidget,
   defineTopoloNotificationsWidget: () => defineTopoloNotificationsWidget,
   defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   digestTopoloActionCatalog: () => digestTopoloActionCatalog,
+  encodeActorEnvelopeHeader: () => encodeActorEnvelopeHeader,
   encodeTopoloActionBase64: () => encodeTopoloActionBase64,
   enrichActionContract: () => enrichActionContract,
   extractTopoloServiceErrorCode: () => extractTopoloServiceErrorCode,
@@ -69,6 +76,7 @@ __export(index_exports, {
   friendlyAppId: () => friendlyAppId,
   isTopoloWidgetOutputSchema: () => isTopoloWidgetOutputSchema,
   listApplicationDirectory: () => listApplicationDirectory,
+  parseActorEnvelope: () => parseActorEnvelope,
   parseTopoloActionUploadContract: () => parseTopoloActionUploadContract,
   preferExactActionMatches: () => preferExactActionMatches,
   prepareTopoloActionBase64UploadInput: () => prepareTopoloActionBase64UploadInput,
@@ -77,6 +85,7 @@ __export(index_exports, {
   resolveApplicationDirectoryEntry: () => resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
+  sha256CanonicalValue: () => sha256CanonicalValue,
   topoloErrorHint: () => topoloErrorHint,
   topoloServiceOrigins: () => topoloServiceOrigins,
   validateTopoloActionInput: () => validateTopoloActionInput,
@@ -250,10 +259,10 @@ var TopoloPermissionError = class extends TopoloSdkError {
 };
 function extractTopoloServiceErrorCode(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
-  const record = body;
-  const topLevel = canonicalTopoloErrorCode(record.code);
+  const record2 = body;
+  const topLevel = canonicalTopoloErrorCode(record2.code);
   if (topLevel) return topLevel;
-  const nested = record.error;
+  const nested = record2.error;
   const nestedString = canonicalTopoloErrorCode(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
@@ -268,14 +277,14 @@ function serviceErrorCode(body, fallback) {
 }
 function extractTopoloServiceErrorDetails(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
-  const record = body;
-  let candidate = record.details;
-  const nested = record.error;
+  const record2 = body;
+  let candidate = record2.details;
+  const nested = record2.error;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const nestedRecord = nested;
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
-  if (candidate === void 0) candidate = record;
+  if (candidate === void 0) candidate = record2;
   if (Array.isArray(candidate)) {
     const paths = canonicalTopoloValidationPaths(candidate);
     return paths.length ? { paths } : void 0;
@@ -327,8 +336,8 @@ function canonicalTopoloValidationPaths(issues) {
   const paths = [];
   for (const issue of issues) {
     if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record = issue;
-    const path = canonicalTopoloValidationPath(record.field) ?? canonicalTopoloValidationPath(record.path);
+    const record2 = issue;
+    const path = canonicalTopoloValidationPath(record2.field) ?? canonicalTopoloValidationPath(record2.path);
     if (path && !paths.includes(path)) paths.push(path);
     if (paths.length === 32) break;
   }
@@ -929,6 +938,242 @@ function isMultipleOf(value, divisor) {
   return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
 }
 
+// src/actor-envelope.ts
+var ACTOR_ENVELOPE_VERSION = 1;
+var TOPOLO_ACTOR_ENVELOPE_HEADER = "X-Topolo-Actor-Envelope";
+var PRINCIPAL_TYPES = /* @__PURE__ */ new Set([
+  "human",
+  "managed_agent",
+  "external_agent",
+  "service",
+  "browser_automation"
+]);
+var ACCOUNTABLE_SUBJECT_TYPES = /* @__PURE__ */ new Set(["human", "organization"]);
+var CHANNELS = /* @__PURE__ */ new Set(["web", "mobile", "cli", "mcp", "api", "workflow", "browser_automation"]);
+var ASSURANCE_LEVELS = /* @__PURE__ */ new Set(["authenticated", "workload_identity", "user_verified"]);
+var HASH_PATTERN = /^sha256:[a-f0-9]{64}$/;
+var ActorEnvelopeValidationError = class extends Error {
+  path;
+  constructor(path, message) {
+    super(`${path}: ${message}`);
+    this.name = "ActorEnvelopeValidationError";
+    this.path = path;
+  }
+};
+function parseActorEnvelope(value) {
+  const envelope = record(value, "actorEnvelope");
+  exactKeys(envelope, [
+    "schemaVersion",
+    "organizationId",
+    "accountableSubject",
+    "performer",
+    "delegation",
+    "channel",
+    "assurance",
+    "action",
+    "issuedAt",
+    "expiresAt"
+  ], "actorEnvelope");
+  if (envelope.schemaVersion !== ACTOR_ENVELOPE_VERSION) {
+    fail("actorEnvelope.schemaVersion", `must equal ${ACTOR_ENVELOPE_VERSION}`);
+  }
+  const accountableSubject = parseAccountableSubject(envelope.accountableSubject);
+  const performer = parseIdentity(envelope.performer, "actorEnvelope.performer");
+  const organizationId = text(envelope.organizationId, "actorEnvelope.organizationId");
+  const channel = member(envelope.channel, CHANNELS, "actorEnvelope.channel");
+  const issuedAt = timestamp(envelope.issuedAt, "actorEnvelope.issuedAt");
+  const expiresAt = envelope.expiresAt === void 0 ? void 0 : timestamp(envelope.expiresAt, "actorEnvelope.expiresAt");
+  if (expiresAt && Date.parse(expiresAt) <= Date.parse(issuedAt)) {
+    fail("actorEnvelope.expiresAt", "must be later than issuedAt");
+  }
+  const assuranceValue = record(envelope.assurance, "actorEnvelope.assurance");
+  exactKeys(assuranceValue, ["level", "methods"], "actorEnvelope.assurance");
+  const assurance = {
+    level: member(assuranceValue.level, ASSURANCE_LEVELS, "actorEnvelope.assurance.level"),
+    methods: textArray(assuranceValue.methods, "actorEnvelope.assurance.methods")
+  };
+  const actionValue = record(envelope.action, "actorEnvelope.action");
+  exactKeys(actionValue, ["requestId", "actionId", "resourceType", "resourceId", "inputHash"], "actorEnvelope.action");
+  const inputHash = text(actionValue.inputHash, "actorEnvelope.action.inputHash");
+  if (!HASH_PATTERN.test(inputHash)) fail("actorEnvelope.action.inputHash", "must be a lowercase sha256 digest");
+  const action = {
+    requestId: text(actionValue.requestId, "actorEnvelope.action.requestId"),
+    actionId: text(actionValue.actionId, "actorEnvelope.action.actionId"),
+    ...actionValue.resourceType === void 0 ? {} : { resourceType: text(actionValue.resourceType, "actorEnvelope.action.resourceType") },
+    ...actionValue.resourceId === void 0 ? {} : { resourceId: text(actionValue.resourceId, "actorEnvelope.action.resourceId") },
+    inputHash
+  };
+  if (action.resourceType === void 0 !== (action.resourceId === void 0)) {
+    fail("actorEnvelope.action", "resourceType and resourceId must be provided together");
+  }
+  const delegation = parseDelegation(envelope.delegation);
+  const directHuman = performer.principalType === "human" && performer.principalId === accountableSubject.principalId;
+  if (directHuman && delegation !== null) fail("actorEnvelope.delegation", "must be null for direct human action");
+  if (!directHuman && delegation === null) fail("actorEnvelope.delegation", "is required when performer differs from accountable subject");
+  if (delegation) {
+    const finalHop = delegation.lineage.at(-1);
+    if (!finalHop || finalHop.principalId !== performer.principalId || finalHop.principalType !== performer.principalType) {
+      fail("actorEnvelope.delegation.lineage", "must end with the performer");
+    }
+  }
+  if (performer.principalType === "external_agent" && (!performer.installationId || !performer.provider)) {
+    fail("actorEnvelope.performer", "external_agent requires installationId and provider");
+  }
+  if (performer.principalType === "managed_agent" && !performer.agentInstanceId) {
+    fail("actorEnvelope.performer.agentInstanceId", "is required for managed_agent");
+  }
+  if (performer.principalType === "browser_automation" && (!performer.installationId || !performer.browserSessionId)) {
+    fail("actorEnvelope.performer", "browser_automation requires installationId and browserSessionId");
+  }
+  return {
+    schemaVersion: ACTOR_ENVELOPE_VERSION,
+    organizationId,
+    accountableSubject,
+    performer,
+    delegation,
+    channel,
+    assurance,
+    action,
+    issuedAt,
+    ...expiresAt ? { expiresAt } : {}
+  };
+}
+function canonicalizeActorEnvelope(value) {
+  return canonicalJson(parseActorEnvelope(value));
+}
+function encodeActorEnvelopeHeader(value) {
+  const bytes = new TextEncoder().encode(canonicalizeActorEnvelope(value));
+  const binary = Array.from(bytes, (byte) => String.fromCharCode(byte)).join("");
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeActorEnvelopeHeader(value) {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+    fail("actorEnvelopeHeader", "must be unpadded base64url");
+  }
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/") + "=".repeat((4 - value.length % 4) % 4);
+  let bytes;
+  try {
+    bytes = Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
+  } catch {
+    fail("actorEnvelopeHeader", "must be valid base64url");
+  }
+  try {
+    return parseActorEnvelope(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+  } catch (error) {
+    if (error instanceof ActorEnvelopeValidationError) throw error;
+    fail("actorEnvelopeHeader", "must contain a valid UTF-8 actor envelope");
+  }
+}
+function canonicalJson(value) {
+  if (value === null) return "null";
+  if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new TypeError("Canonical JSON accepts finite numbers only.");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value !== "object" || !value || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+    throw new TypeError("Canonical JSON accepts JSON objects, arrays, and primitives only.");
+  }
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+}
+function parseAccountableSubject(value) {
+  const path = "actorEnvelope.accountableSubject";
+  const subject = record(value, path);
+  exactKeys(subject, ["principalType", "principalId", "displayName"], path);
+  return {
+    principalType: member(subject.principalType, ACCOUNTABLE_SUBJECT_TYPES, `${path}.principalType`),
+    principalId: text(subject.principalId, `${path}.principalId`),
+    ...subject.displayName === void 0 ? {} : { displayName: text(subject.displayName, `${path}.displayName`) }
+  };
+}
+async function sha256CanonicalValue(value) {
+  const bytes = new TextEncoder().encode(canonicalJson(value));
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return `sha256:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function parseIdentity(value, path) {
+  const identity = record(value, path);
+  exactKeys(identity, [
+    "principalType",
+    "principalId",
+    "displayName",
+    "installationId",
+    "agentInstanceId",
+    "browserSessionId",
+    "provider",
+    "model"
+  ], path);
+  return {
+    principalType: member(identity.principalType, PRINCIPAL_TYPES, `${path}.principalType`),
+    principalId: text(identity.principalId, `${path}.principalId`),
+    ...optionalTextFields(identity, path, [
+      "displayName",
+      "installationId",
+      "agentInstanceId",
+      "browserSessionId",
+      "provider",
+      "model"
+    ])
+  };
+}
+function parseDelegation(value) {
+  if (value === null) return null;
+  const delegation = record(value, "actorEnvelope.delegation");
+  exactKeys(delegation, ["taskId", "runId", "lineage"], "actorEnvelope.delegation");
+  if (!Array.isArray(delegation.lineage) || delegation.lineage.length === 0 || delegation.lineage.length > 16) {
+    fail("actorEnvelope.delegation.lineage", "must contain between 1 and 16 hops");
+  }
+  return {
+    taskId: text(delegation.taskId, "actorEnvelope.delegation.taskId"),
+    runId: text(delegation.runId, "actorEnvelope.delegation.runId"),
+    lineage: delegation.lineage.map((value2, index) => {
+      const hop = record(value2, `actorEnvelope.delegation.lineage[${index}]`);
+      exactKeys(hop, ["principalType", "principalId"], `actorEnvelope.delegation.lineage[${index}]`);
+      return {
+        principalType: member(hop.principalType, PRINCIPAL_TYPES, `actorEnvelope.delegation.lineage[${index}].principalType`),
+        principalId: text(hop.principalId, `actorEnvelope.delegation.lineage[${index}].principalId`)
+      };
+    })
+  };
+}
+function record(value, path) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "must be an object");
+  return value;
+}
+function exactKeys(value, allowed, path) {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) fail(path, `contains unknown field ${unknown[0]}`);
+}
+function text(value, path) {
+  if (typeof value !== "string" || value.trim() !== value || value.length === 0 || value.length > 256) {
+    fail(path, "must be a non-empty trimmed string of at most 256 characters");
+  }
+  return value;
+}
+function timestamp(value, path) {
+  const result = text(value, path);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(result) || Number.isNaN(Date.parse(result))) {
+    fail(path, "must be an RFC 3339 UTC timestamp");
+  }
+  return result;
+}
+function member(value, values, path) {
+  if (typeof value !== "string" || !values.has(value)) fail(path, "contains an unsupported value");
+  return value;
+}
+function textArray(value, path) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 16) fail(path, "must contain between 1 and 16 values");
+  return value.map((item, index) => text(item, `${path}[${index}]`));
+}
+function optionalTextFields(value, path, keys) {
+  return Object.fromEntries(keys.flatMap((key) => value[key] === void 0 ? [] : [[key, text(value[key], `${path}.${key}`)]]));
+}
+function fail(path, message) {
+  throw new ActorEnvelopeValidationError(path, message);
+}
+
 // src/action-upload.ts
 function parseTopoloActionUploadContract(value) {
   if (!isRecord2(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
@@ -1219,11 +1464,15 @@ var TopoloClient = class _TopoloClient {
     const platformAppId = resolveConfiguredAppId(resolvedService.serviceKey, this.appIds);
     if (platformAppId) headers.set("X-App-ID", platformAppId);
     applyAuthHeaders(headers, this.credential);
-    const requestId = generateRequestId();
+    const actorEnvelope = opts.actorEnvelope === void 0 ? void 0 : parseActorEnvelope(opts.actorEnvelope);
+    const requestId = actorEnvelope?.action.requestId ?? generateRequestId();
     applyAuditHeaders(headers, this.agent, requestId);
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
+    if (actorEnvelope) {
+      headers.set(TOPOLO_ACTOR_ENVELOPE_HEADER, encodeActorEnvelopeHeader(actorEnvelope));
+    }
     if (opts.resource) {
       const resourceType = opts.resource.resourceType.trim();
       const resourceId = opts.resource.resourceId.trim();
@@ -1670,14 +1919,14 @@ var TopoloClient = class _TopoloClient {
     if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
       throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is unavailable.");
     }
-    const record = raw;
-    if (record.algorithm !== "sha256-v1" || typeof record.digest !== "string" || !/^[a-f0-9]{64}$/.test(record.digest) || !Number.isSafeInteger(record.actionCount) || Number(record.actionCount) < 0) {
+    const record2 = raw;
+    if (record2.algorithm !== "sha256-v1" || typeof record2.digest !== "string" || !/^[a-f0-9]{64}$/.test(record2.digest) || !Number.isSafeInteger(record2.actionCount) || Number(record2.actionCount) < 0) {
       throw new TopoloSdkError("action_catalog_summary_unavailable", "Action catalog summary is invalid.");
     }
     return {
       algorithm: "sha256-v1",
-      digest: record.digest,
-      actionCount: Number(record.actionCount)
+      digest: record2.digest,
+      actionCount: Number(record2.actionCount)
     };
   }
   /** @deprecated Prefer searchActions() so callers retain the continuation cursor. */
@@ -1877,6 +2126,19 @@ var TopoloClient = class _TopoloClient {
       );
     }
     const mapped = mapActionInput(entry, input);
+    if (options.actorEnvelope) {
+      const actorEnvelope = parseActorEnvelope(options.actorEnvelope);
+      if (actorEnvelope.action.actionId !== entry.actionId) {
+        throw new TopoloSdkError("actor_envelope_action_mismatch", "Actor envelope actionId does not match the executed action.");
+      }
+      if (actorEnvelope.action.inputHash !== await sha256CanonicalValue(input)) {
+        throw new TopoloSdkError("actor_envelope_input_mismatch", "Actor envelope inputHash does not match the executed action input.");
+      }
+      const envelopeResource = actorEnvelope.action.resourceType && actorEnvelope.action.resourceId ? { resourceType: actorEnvelope.action.resourceType, resourceId: actorEnvelope.action.resourceId } : void 0;
+      if (envelopeResource?.resourceType !== options.resource?.resourceType || envelopeResource?.resourceId !== options.resource?.resourceId) {
+        throw new TopoloSdkError("actor_envelope_resource_mismatch", "Actor envelope resource does not match the executed action resource.");
+      }
+    }
     const service = entry.appSlug || entry.appId;
     const result = await this.request({
       service,
@@ -1886,6 +2148,7 @@ var TopoloClient = class _TopoloClient {
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
       ...options.resource ? { resource: options.resource } : {},
+      ...options.actorEnvelope ? { actorEnvelope: options.actorEnvelope } : {},
       headers: {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
@@ -2310,10 +2573,10 @@ function extractRequired(body) {
     if (Array.isArray(maybe.required)) return canonicalTopoloRequired(maybe.required);
     for (const nested of [maybe.details, maybe.error]) {
       if (!nested || typeof nested !== "object" || Array.isArray(nested)) continue;
-      const record = nested;
-      if (Array.isArray(record.required)) return canonicalTopoloRequired(record.required);
-      if (record.details && typeof record.details === "object" && !Array.isArray(record.details)) {
-        const required = record.details.required;
+      const record2 = nested;
+      if (Array.isArray(record2.required)) return canonicalTopoloRequired(record2.required);
+      if (record2.details && typeof record2.details === "object" && !Array.isArray(record2.details)) {
+        const required = record2.details.required;
         if (Array.isArray(required)) return canonicalTopoloRequired(required);
       }
     }
@@ -2390,8 +2653,8 @@ function compactResultValue(value, depth, budget) {
     return value.length > ACTION_RESULT_MAX_ITEMS ? { count: value.length, items, omittedItems: value.length - ACTION_RESULT_MAX_ITEMS } : items;
   }
   if (typeof value === "object") {
-    const record = value;
-    const allKeys = Object.keys(record);
+    const record2 = value;
+    const allKeys = Object.keys(record2);
     const ranked = allKeys.sort((left, right) => resultKeyPriority(left) - resultKeyPriority(right));
     const prioritized = ranked.filter((key) => resultKeyPriority(key) < 2);
     const ordinary = ranked.filter((key) => resultKeyPriority(key) === 2);
@@ -2400,7 +2663,7 @@ function compactResultValue(value, depth, budget) {
       ...prioritized,
       ...ordinary.slice(0, ordinaryLimit)
     ].slice(0, ACTION_RESULT_MAX_KEYS);
-    const compact = Object.fromEntries(keys.map((key) => [key, compactResultValue(record[key], depth + 1, budget)]));
+    const compact = Object.fromEntries(keys.map((key) => [key, compactResultValue(record2[key], depth + 1, budget)]));
     if (allKeys.length > keys.length) compact["_omittedKeys"] = allKeys.length - keys.length;
     return compact;
   }
@@ -2516,8 +2779,8 @@ function canonicalPermission(value, appId) {
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
   if (value && typeof value === "object") {
-    const record = value;
-    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`).join(",")}}`;
+    const record2 = value;
+    return `{${Object.keys(record2).sort().map((key) => `${JSON.stringify(key)}:${stableJson(record2[key])}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
@@ -2658,8 +2921,8 @@ function resourceSchema(resource) {
 function derivedOutputSchema(action) {
   const resource = resourceFor(action);
   const operation = operationFor(action);
-  const record = resourceSchema(resource);
-  const records = { type: "array", items: record };
+  const record2 = resourceSchema(resource);
+  const records = { type: "array", items: record2 };
   const provenance = {
     "x-topolo-contract-source": "derived-action-metadata",
     "x-topolo-contract-precision": "structural"
@@ -2691,12 +2954,12 @@ function derivedOutputSchema(action) {
       title: `${action.title || action.name} response`,
       description: `Resource response returned by ${action.name}. The service may return the resource directly or in an envelope.`,
       oneOf: [
-        record,
+        record2,
         {
           type: "object",
           properties: {
-            data: record,
-            [resource]: record
+            data: record2,
+            [resource]: record2
           },
           additionalProperties: true
         }
@@ -2711,7 +2974,7 @@ function derivedOutputSchema(action) {
     properties: {
       success: { type: "boolean" },
       id: { type: "string" },
-      data: { oneOf: [record, { type: "object", additionalProperties: true }] },
+      data: { oneOf: [record2, { type: "object", additionalProperties: true }] },
       result: { type: "object", additionalProperties: true },
       message: { type: "string" }
     },
@@ -4501,10 +4764,13 @@ function createTopolo(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ACTION_CATALOG_DIGEST_ALGORITHM,
+  ACTOR_ENVELOPE_VERSION,
+  ActorEnvelopeValidationError,
   CrmModule,
   DEFAULT_APP_URLS,
   IdentityModule,
   P2PModule,
+  TOPOLO_ACTOR_ENVELOPE_HEADER,
   TOPOLO_ENVIRONMENT_SERVICE_URLS,
   TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION,
@@ -4522,10 +4788,12 @@ function createTopolo(options) {
   actionContractCompleteness,
   applicationEntryFromCatalog,
   assertTopoloServiceUrlEnvironment,
+  canonicalJson,
   canonicalTopoloErrorCode,
   canonicalTopoloRequestId,
   canonicalTopoloRequired,
   canonicalTopoloRetryAfter,
+  canonicalizeActorEnvelope,
   compactActionCatalogEntry,
   compactActionPlan,
   compactActionPreparation,
@@ -4535,12 +4803,14 @@ function createTopolo(options) {
   createTopoloAgentExecutionContext,
   createTopoloWidgetError,
   createTopoloWidgetResponse,
+  decodeActorEnvelopeHeader,
   defineTopoloActionsWidget,
   defineTopoloActivityWidget,
   defineTopoloChartWidget,
   defineTopoloNotificationsWidget,
   defineTopoloStatsWidget,
   digestTopoloActionCatalog,
+  encodeActorEnvelopeHeader,
   encodeTopoloActionBase64,
   enrichActionContract,
   extractTopoloServiceErrorCode,
@@ -4549,6 +4819,7 @@ function createTopolo(options) {
   friendlyAppId,
   isTopoloWidgetOutputSchema,
   listApplicationDirectory,
+  parseActorEnvelope,
   parseTopoloActionUploadContract,
   preferExactActionMatches,
   prepareTopoloActionBase64UploadInput,
@@ -4557,6 +4828,7 @@ function createTopolo(options) {
   resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  sha256CanonicalValue,
   topoloErrorHint,
   topoloServiceOrigins,
   validateTopoloActionInput,