Service API Schema（统一 OpenAPI）

1. 目标

本页是 OpenAPI binding 的说明视图（informative）；其中复述的强制规则以 sync/service-http-binding.md 与 sync/api-conventions.md 为权威来源。

service-api-schema.mdx 是 Arkret canonical operation 的说明性服务清单。 HTTP/JSON 是参考绑定；同一操作应能无语义损失映射到其它 transport（gRPC、WebSocket、SSE、MQ、libp2p、IPC）。

本文件同时承担：

• operation_id 稳定性与分层说明
• 各服务角色最小能力边界
• OpenAPI 与 transport 映射的一致性锚点

请求/响应形状、错误、分页、幂等、同步语义由 api-conventions.md、service-surface.md、client-sync.md、service-http-binding.md 共同约束。

规范权威关系：

• artifacts/registry/contract-registry.json#operation_registry 是 operation contract 的 canonical source。
• artifacts/registry/operation-registry.json 是由 canonical source 生成的机器视图，供实现、SDK、lint 与 transport adapter 直接消费。
• arkret-service-api.openapi.yaml 是 HTTP binding 的规范性 shape 文档；它必须与 operation registry 对齐，但不是第二套 operation namespace。
• 本文是说明性地图与治理说明；完整枚举以 canonical source 与生成物为准。

2. 统一约定

• 所有 canonical operation 均使用 encoding.md 的 canonical JSON 与签名输入规则。
• 关键行为不由路径决定，而由 operation_id 与数据语义决定。
• Arkret operation registry 和 feature discovery 使用带版本的 operation_id。OpenAPI 3.2 标准字段 operationId 标识稳定 endpoint family，其值等于对应 operation_id 去掉末尾 .vN 后的无版本 identity；每个 canonical Arkret HTTP 请求 MUST 通过 Arkret-Operation 明确选择 exact versioned operation_id，不得因 endpoint 当前只有一个候选而省略。RFC 10008 HTTP QUERY 使用 Path Item 的标准 query: 字段。
• 服务发现使用 canonical ServiceDescribe shape；响应 core shape 包含：
  • service_id
  • trust_domain
  • service_kind
  • protocol_version
  • supported_profiles
  • supported_operation_bundles
  • transport_bindings
  • supported_features
  • auth_metadata
  • limits
  • plaintext_visibility
  • rate_limit_policy
  • development_mode
  • supported_features
  • verified_profiles
  • supported_features
  • interop_surfaces Arkret v1 领域 reducer 是固定合同，不通过 ServiceDescribe 协商。supported_features 只声明可选运行时功能，supported_schema_profiles 通过已登记扩展或具体 operation 合同表达。

2.1 操作分组

统一 API schema 按 canonical operation 分组。HTTP 路径只是默认 binding：

HTTP 路径的第一段是 trust-surface classifier（信任面分类器），用于表达调用方与服务之间的信任关系和攻击面类别；它不是授权结论。尤其是 root 只表示身份信任根（DID / key log / receipt），不是管理员/root user 权限；open 只表示外部协议互通面，不表示 public / no-auth access。

| 分组 | operation_id 前缀 | 默认 HTTP 命名空间 | | --- | --- | --- | | 服务发现 | ak.server.* | /_arkret/describe | | 身份信任根与 registry | ak.root.identity.* | /_arkret/root/identity/* | | 安全事务 | ak.self.security_transaction.* | /_arkret/self/security-transactions/* | | Events | ak.self.events.* | /_arkret/self/events/* | | Federation peer events | ak.peer.events.* | /_arkret/peer/events/* | | 加密信号扩展 | ak.self.signal.command.send.v1、ak.self.signal.stream.subscribe.v1、可选 ak.peer.signal.command.relay.v1 | /_arkret/self/signal*、/_arkret/peer/signal | | 账号自服务与聚合同步 | ak.self.account.read.viewer.v1、ak.self.account.command.update_profile.v1、ak.self.account.stream.subscribe.v1、ak.self.account.read.describe.v1、ak.self.account.command.revoke_cursor.v1 | /_arkret/self/account/* | | Realm snapshot 入口 | ak.self.realm_state_snapshot.* | /_arkret/self/realm-state-snapshot/* | | Federation peer snapshot 入口 | ak.peer.snapshot.* | /_arkret/peer/snapshot/* | | 目录发现 | ak.find.directory.* | /_arkret/find/directory/* | | Blob / media | ak.self.blob.* | /_arkret/self/blob/* | | 推送 | ak.edge.push.* | /_arkret/edge/push/* | | 设备加密 | ak.self.device_messages.*、ak.self.keys.* | /_arkret/self/device_messages/*、/_arkret/self/keys/* | | 授权 | ak.self.authz.* | /_arkret/self/authz/* | | 媒体服务 | ak.self.media.*、ak.self.call.media.exchange.issue_token.v1 | /_arkret/self/rtc/ice-config、/_arkret/self/rtc/token | | 审核 | ak.self.moderation.* | /_arkret/self/moderation/* | | Applet | ak.edge.applet.* | /_arkret/edge/applet/* | | MIMI 外部协议互操作 | ak.open.mimi.* | /_arkret/open/mimi/* | | 账户注册、登录与设备配对 | ak.gate.account.* | /_arkret/gate/account/* |

3. OpenAPI 参考快照（非穷尽示例）

以下 YAML 片段只用于说明 shape 和命名规则，不构成完整 operation 枚举。完整 HTTP operation 集合以 arkret-service-api.openapi.yaml 和生成的 operation registry 为准；新增 operation 时应先更新 canonical catalog，再更新生成物。

openapi: 3.2.0
info:
  title: Arkret Service API
  version: 1.0.0
  x-conformance-profile: ak.profile.core_event_store.v1
servers:
  - url: https://{host}
    variables:
      host: { default: localhost }

paths:
  /_arkret/describe:
    get:
      operationId: ak.server.read.describe
      responses:
        '200': { description: service profile }

  /_arkret/root/identity/resolve:
    post:
      operationId: ak.root.identity.read.resolve
  /_arkret/root/identity/describe:
    get:
      operationId: ak.root.identity.registry.read.describe
  /_arkret/root/identity/document:
    get:
      operationId: ak.root.identity.document.resource.get
  /_arkret/root/identity/log:
    get:
      operationId: ak.root.identity.log.read.list
  /_arkret/root/identity/submit-did-operation:
    post:
      operationId: ak.root.identity.command.submit_did_operation
  /_arkret/root/identity/receipts:
    get:
      operationId: ak.root.identity.receipts.read.list

  /_arkret/self/security-transactions:
    post:
      operationId: ak.self.security_transaction.command.create
  /_arkret/self/security-transactions/{transaction_id}:
    get:
      operationId: ak.self.security_transaction.resource.get
  /_arkret/self/security-transactions/{transaction_id}/continue:
    post:
      operationId: ak.self.security_transaction.command.continue

  /_arkret/self/events:
    post:
      operationId: ak.self.events.command.submit
  /_arkret/self/streams/scan:
    post:
      operationId: ak.self.events.read.scan
  /_arkret/self/realms/{realm_id}/streams:
    get:
      operationId: ak.self.realm.read.streams
  /_arkret/self/committed-events/subscribe:
    get:
      operationId: ak.self.events.stream.subscribe
  /_arkret/self/committed-events/{event_id}:
    get:
      operationId: ak.self.events.resource.get
  /_arkret/self/signal:
    post:
      operationId: ak.self.signal.command.send
  /_arkret/self/signal/subscribe:
    get:
      operationId: ak.self.signal.stream.subscribe
  /_arkret/peer/signal:
    post:
      operationId: ak.peer.signal.command.relay

  /_arkret/peer/events:
    post:
      operationId: ak.peer.events.command.submit
  /_arkret/peer/streams/scan:
    post:
      operationId: ak.peer.events.read.scan

  /_arkret/self/account/viewer:
    get:
      operationId: ak.self.account.read.viewer
  /_arkret/self/account/profile:
    post:
      operationId: ak.self.account.command.update_profile
  /_arkret/self/account/subscribe:
    get:
      operationId: ak.self.account.stream.subscribe
  /_arkret/self/account/describe:
    get:
      operationId: ak.self.account.read.describe
  /_arkret/self/account/cursor/revoke:
    post:
      operationId: ak.self.account.command.revoke_cursor
  /_arkret/self/realm-state-snapshot/head:
    get:
      operationId: ak.self.realm_state_snapshot.read.manifest_head

  /_arkret/find/directory/describe:
    get:
      operationId: ak.find.directory.read.describe
  /_arkret/find/directory/search-realms:
    post:
      operationId: ak.find.directory.read.search_realms
  /_arkret/find/directory/resolve-realm:
    post:
      operationId: ak.find.directory.read.resolve_realm
  /_arkret/self/blob/upload:
    post:
      operationId: ak.self.blob.upload.create
  /_arkret/self/blob/get:
    head:
      operationId: ak.self.blob.resource.head
    get:
      operationId: ak.self.blob.resource.get

  /_arkret/edge/push/register-device:
    post:
      operationId: ak.edge.push.command.register_device
  /_arkret/edge/push/unregister-device:
    post:
      operationId: ak.edge.push.command.unregister_device
  /_arkret/edge/push/notify:
    post:
      operationId: ak.edge.push.command.notify

  /_arkret/self/device_messages:
    post:
      operationId: ak.self.device_messages.command.send
    get:
      operationId: ak.self.device_messages.read.list
  /_arkret/self/keys/upload:
    post:
      operationId: ak.self.keys.upload.create
  /_arkret/self/keys/query:
    post:
      operationId: ak.self.keys.read.lookup
  /_arkret/self/keys/claim:
    post:
      operationId: ak.self.keys.command.claim
  /_arkret/self/keys/keypackages/upload:
    post:
      operationId: ak.self.keys.keypackages.upload.create
  /_arkret/self/keys/keypackages/claim:
    post:
      operationId: ak.self.keys.keypackages.command.claim
  /_arkret/self/keys/keypackages/consume:
    post:
      operationId: ak.self.keys.keypackages.command.consume
  /_arkret/self/keys/keypackages/revoke:
    post:
      operationId: ak.self.keys.keypackages.command.revoke
  /_arkret/self/keys/backups/{backup_id}:
    put:
      operationId: ak.self.keys.backups.resource.replace
    delete:
      operationId: ak.self.keys.backups.resource.delete
  /_arkret/self/keys/backups/{backup_id}/unlock:
    post:
      operationId: ak.self.keys.backups.command.unlock
  /_arkret/self/keys/backups:
    get:
      operationId: ak.self.keys.backups.read.list

  /_arkret/gate/account/register:
    post:
      operationId: ak.gate.account.command.register
  /_arkret/gate/account/session-grants:
    post:
      operationId: ak.gate.account.command.issue_session_grant
  /_arkret/gate/account/session-grants/revoke:
    post:
      operationId: ak.gate.account.command.revoke_session
  /_arkret/gate/account/logout:
    post:
      operationId: ak.gate.account.command.logout
  /_arkret/gate/account/device-pair:
    post:
      operationId: ak.gate.account.command.pair_device
  /_arkret/self/authz/check:
    post:
      operationId: ak.self.authz.read.check
  /_arkret/self/authz/effective-grants:
    get:
      operationId: ak.self.authz.grants.read.effective
  /_arkret/self/authz/invites:
    get:
      operationId: ak.self.authz.invites.read.list
  /_arkret/self/rtc/ice-config:
    post:
      operationId: ak.self.media.read.ice_config
  /_arkret/self/rtc/token:
    post:
      operationId: ak.self.call.media.exchange.issue_token
  /_arkret/self/moderation/report:
    post:
      operationId: ak.self.moderation.command.report

  /_arkret/edge/applet/ping:
    get:
      operationId: ak.edge.applet.read.ping
  /_arkret/edge/applet/describe:
    get:
      operationId: ak.edge.applet.read.describe
  /_arkret/edge/applet/transactions:
    post:
      operationId: ak.edge.applet.command.transaction
  /_arkret/edge/applet/actors/{actor_id}:
    get:
      operationId: ak.edge.applet.actor.read.resolve
  /_arkret/edge/applet/realms/{realm_id_or_alias}:
    get:
      operationId: ak.edge.applet.realm.read.resolve
  /_arkret/edge/applet/protocols/{protocol}:
    get:
      operationId: ak.edge.applet.read.protocol_metadata
  /_arkret/edge/applet/third_party/users:
    get:
      operationId: ak.edge.applet.third_party_users.read.list
  /_arkret/edge/applet/third_party/locations:
    get:
      operationId: ak.edge.applet.third_party_locations.read.list

4. Canonical 操作与 transport 映射

| operation_id | HTTP 参考绑定 | 其他 transport 映射 | | --- | --- | --- | | ak.root.identity.read.resolve.v1 | POST /_arkret/root/identity/resolve | gRPC ResolveIdentity / MQ root.identity.query.resolve | | ak.root.identity.command.submit_did_operation.v1 | POST /_arkret/root/identity/submit-did-operation | gRPC SubmitDidOperation / libp2p stream | | ak.root.identity.document.resource.get.v1 / ak.root.identity.log.read.list.v1 / ak.root.identity.receipts.read.list.v1 | GET /_arkret/root/identity/document, GET /_arkret/root/identity/log, GET /_arkret/root/identity/receipts | gRPC Identity Registry / witness query | | ak.self.security_transaction.command.create.v1 / resource.get / command.continue | POST /_arkret/self/security-transactions、GET /_arkret/self/security-transactions/{transaction_id}、POST .../{transaction_id}/continue | gRPC SelfSecurityTransactions/Create / Get / Continue；durable transaction resource，不依赖短期 HTTP cache | | ak.self.events.command.submit.v1 | POST /_arkret/self/events | gRPC SelfEvents/Submit / 队列 self.events.command.submit | | ak.self.committed_event.resource.get.v1 / ak.self.committed_event.read.scan.v1 | resource.get 使用 GET /_arkret/self/committed-events/{event_id}；scan 使用 POST /_arkret/self/streams/scan | gRPC SelfEvents/Get / SelfStreams/Scan | | ak.self.realm.read.streams.v1 | GET /_arkret/self/realms/{realm_id}/streams | gRPC SelfRealm/Streams / MQ self.realm.query.streams；ACL 过滤、可分页的流枚举，是 scan 与有界订阅窗口都给不出的发现面 | | ak.self.committed_event.stream.subscribe.v1 | GET /_arkret/self/committed-events/subscribe (application/x-ndjson) | pubsub topic carrying the same NDJSON frame objects | | ak.peer.events.command.submit.v1 | POST /_arkret/peer/events | gRPC PeerEvents/Submit / 队列 peer.events.command.submit | | ak.self.account.read.viewer.v1 | GET /_arkret/self/account/viewer | gRPC SelfAccount/Viewer / MQ self.account.query.viewer；响应使用 signed handle claim / ref / digest，不返回未签名裸 handle 作为账号权威字段。 | | ak.self.account.command.update_profile.v1 | POST /_arkret/self/account/profile | gRPC SelfAccount/UpdateProfile / MQ self.account.command.update_profile；closed {profile_event} 只承载 holder-signed ak.profile.create\|ak.profile.update，create ID 从 Event 派生；Event preconditions 为空，update 并发只使用可选 signed payload.expected_state_digest，patch 仅限 display/avatar/profile_fields；exact replay 不重复 account-aggregate delta。 | | ak.self.account.stream.subscribe.v1 | GET /_arkret/self/account/subscribe | HTTP Accept: application/x-ndjson carries account-aggregate frames(delta / catchup_complete / checkpoint / heartbeat / dropped / resync_required / unauthorized);dropped / resync_required MAY carry reconnect_after_ms | | ak.self.account.command.revoke_cursor.v1 | POST /_arkret/self/account/cursor/revoke | gRPC SelfAccount/CursorRevoke / MQ self.account.command.revoke_cursor | | ak.gate.account.command.register.v1 | POST /_arkret/gate/account/register | gRPC GateAccount/Register / MQ gate.account.command.register；request 字段为 principal_id，handle 经 signed claim 链路。 | | ak.gate.account.command.request_erasure.v1 | POST /_arkret/gate/account/erasure-requests | gRPC GateAccount/RequestErasure / MQ gate.account.command.request_erasure；由 Account Authority 在 gate 面直接受理，closed {request_id} 只记录擦除意图，Authority 在同一服务内继续其既有 erasure_pending 签发流程；响应是受理确认（status=accepted + recorded_at，可选 withdrawal_window_ends_at），不是完成回执；record 签发后不可逆，完成状态经既有 account-status 查询面获得。 | | ak.gate.account.command.revoke_session.v1 | POST /_arkret/gate/account/session-grants/revoke | gRPC GateAccount/SessionRevoke / MQ gate.account.command.revoke_session | | ak.gate.account.command.logout.v1 | POST /_arkret/gate/account/logout | Account Authority hard logout 的唯一客户端入口；内部可调用 logout_auth_session，不提供 gRPC/MQ client binding | | ak.self.signal.command.send.v1 | POST /_arkret/self/signal | gRPC SelfSignal/Send / MQ self.signal.command.send；承载 ak.schema.signal_envelope.v1，不写 durable Event | | ak.self.signal.stream.subscribe.v1 | GET /_arkret/self/signal/subscribe | gRPC SelfSignal/Subscribe / MQ self.signal.stream.subscribe；encrypted-only live receive rail，无 backfill / durable delivery | | ak.peer.signal.command.relay.v1 | POST /_arkret/peer/signal | gRPC PeerSignal/Relay / MQ peer.signal.command.relay；可选 profile 的单跳 encrypted relay，opaque outcome、无 durable state、无自动重试 | | ak.self.realm_state_snapshot.read.manifest_head.v1 | GET /_arkret/self/realm-state-snapshot/head | snapshot manifest | | ak.self.space.read.list.v1 / ak.self.strand.read.list.v1 / ak.self.morph.read.list.v1 / ak.self.morph.resource.get.v1 | GET /_arkret/self/realms/{realm_id}/spaces, GET /_arkret/self/realms/{realm_id}/strands, GET /_arkret/self/realms/{realm_id}/morphs, GET /_arkret/self/realms/{realm_id}/morphs/{morph_id} | gRPC SelfSpace/List / SelfStrand/List / SelfMorph/List / SelfMorph/Get; MQ self.space.query.list / self.strand.query.list / self.morph.query.list / self.morph.resource.get | | ak.self.blob.upload.create.v1 / ak.self.blob.resource.head.v1 / ak.self.blob.resource.get.v1 | POST /_arkret/self/blob/upload, HEAD/GET /_arkret/self/blob/get | Object-store signed URL binding / gRPC blob service | | ak.edge.push.command.register_device.v1 / ak.edge.push.command.notify.v1 | POST /_arkret/edge/push/register-device, POST /_arkret/edge/push/notify | APNs/FCM adapter / MQ wakeup topic | | ak.self.device_messages.command.send.v1 / ak.self.device_messages.read.list.v1 | POST /_arkret/self/device_messages, GET /_arkret/self/device_messages | MQ device topic / 本地 IPC | | ak.self.keys.upload.create.v1 / ak.self.keys.read.lookup.v1 / ak.self.keys.command.claim.v1 | POST /_arkret/self/keys/upload, POST /_arkret/self/keys/query, POST /_arkret/self/keys/claim | E2EE key service binding | | ak.self.keys.backups.resource.replace.v1 / ak.self.keys.backups.read.list.v1 / ak.self.keys.backups.command.unlock.v1 / ak.self.keys.backups.resource.delete.v1 | PUT /_arkret/self/keys/backups/{backup_id}, GET /_arkret/self/keys/backups, POST /_arkret/self/keys/backups/{backup_id}/unlock, DELETE /_arkret/self/keys/backups/{backup_id} | Encrypted key backup storage binding | | ak.self.authz.read.check.v1 / ak.self.authz.grants.read.effective.v1 / ak.self.authz.invites.read.list.v1 | POST /_arkret/self/authz/check, GET /_arkret/self/authz/effective-grants, GET /_arkret/self/authz/invites | gRPC / policy 插件回调 | | ak.self.media.read.ice_config.v1 | POST /_arkret/self/rtc/ice-config | Realtime Media Services / TURN credential adapter | | ak.self.call.media.exchange.issue_token.v1 | POST /_arkret/self/rtc/token | Realtime Media Services token 兑换 / gRPC Call/MediaTokenExchange | | ak.self.moderation.command.report.v1 | POST /_arkret/self/moderation/report | Closed {report_event}；direct-holder signed Event，Event-derived report ID，exact-replay moderation queue workflow | | ak.self.applet.install.command.preview.v1 / ak.self.applet.command.install.v1 / ak.self.applet.revoke.command.preview.v1 / ak.self.applet.command.revoke.v1 | POST /_arkret/self/applets/install/preview, POST /_arkret/self/applets/install, POST /_arkret/self/applets/{applet_id}/revoke/preview, POST /_arkret/self/applets/{applet_id}/revoke | Applet self/admin aggregate operation；install fan-out registration/grant facts；revoke 以 caller-signed Event saga 撤销 grant/membership，并持久化 external/local step ledger | | ak.edge.applet.command.transaction.v1 / ak.edge.applet.actor.read.resolve.v1 / ak.edge.applet.realm.read.resolve.v1 | POST /_arkret/edge/applet/transactions, GET /_arkret/edge/applet/actors/{actor_id}, GET /_arkret/edge/applet/realms/{realm_id_or_alias} | Applet webhook / bridge adapter |

4.1 Generated Full Inventory

下表由站点构建期从 spec/v1/artifacts/registry/contract-registry.json#operation_registry 直接渲染。canonical 数据是注册表本身；本表只是按 surface group 分组的浏览视图。 单 operation 详情见 /catalog/operations/<id>/，HTTP 形状交互式视图见 /openapi/。

service_discovery · surface class core

Base interoperable surfaces used for documentation and lint; v1 support does not imply wire reachability without explicit supported_operation_bundles advertisement.

operation_id	HTTP	gRPC	MQ
ak.server.read.describe.v1	GET /_arkret/describe	Server/Describe	server.query.describe

identity_registry · surface class core

Base interoperable surfaces used for documentation and lint; v1 support does not imply wire reachability without explicit supported_operation_bundles advertisement.

operation_id	HTTP	gRPC	MQ
ak.root.identity.registry.read.describe.v1	GET /_arkret/root/identity/describe	RootIdentity/DescribeRegistry	root.identity.registry.query.describe
ak.root.identity.read.resolve.v1	POST /_arkret/root/identity/resolve	RootIdentity/Resolve	root.identity.query.resolve
ak.root.identity.document.resource.get.v1	GET /_arkret/root/identity/document	RootIdentity/GetDocument	root.identity.document.resource.get
ak.root.identity.log.read.list.v1	GET /_arkret/root/identity/log	RootIdentity/GetLog	root.identity.log.query.list
ak.root.identity.receipts.read.list.v1	GET /_arkret/root/identity/receipts	RootIdentity/GetReceipts	root.identity.receipts.query.list
ak.root.identity.command.submit_did_operation.v1	POST /_arkret/root/identity/submit-did-operation	RootIdentity/SubmitDidOperation	root.identity.command.submit_did_operation
ak.root.identity.service_registration.command.ensure.v1	POST /_arkret/root/identity/service-registrations:ensure	RootIdentity/EnsureServiceRegistration	root.identity.service_registration.command.ensure
ak.root.identity.service_registration.resource.get.v1	GET /_arkret/root/identity/service-registrations	RootIdentity/GetServiceRegistration	root.identity.service_registration.resource.get
ak.root.identity.organization_registration.command.prepare.v1	POST /_arkret/root/identity/organization-registrations:prepare	RootIdentity/PrepareOrganizationRegistration	root.identity.organization_registration.command.prepare
ak.root.identity.organization_registration.command.ensure.v1	POST /_arkret/root/identity/organization-registrations:ensure	RootIdentity/EnsureOrganizationRegistration	root.identity.organization_registration.command.ensure
ak.root.identity.organization_registration.resource.get.v1	GET /_arkret/root/identity/organization-registrations	RootIdentity/GetOrganizationRegistration	root.identity.organization_registration.resource.get
ak.root.identity.organization_registration.command.refresh.v1	POST /_arkret/root/identity/organization-registrations:refresh	RootIdentity/RefreshOrganizationRegistration	root.identity.organization_registration.command.refresh
ak.root.identity.organization_registration.command.revoke.v1	POST /_arkret/root/identity/organization-registrations:revoke	RootIdentity/RevokeOrganizationRegistration	root.identity.organization_registration.command.revoke
ak.root.identity.recovery_policy.resource.get.v1	GET /_arkret/root/identity/recovery-policy	RootIdentity/RecoveryPolicyGet	root.identity.recovery_policy.resource.get
ak.root.identity.recovery_policy.command.publish.v1	POST /_arkret/root/identity/recovery-policy	RootIdentity/RecoveryPolicyPublish	root.identity.recovery_policy.command.publish
ak.root.identity.recovery_session.command.create.v1	POST /_arkret/root/identity/recovery-sessions	RootIdentity/RecoverySessionCreate	root.identity.recovery_session.command.create
ak.root.identity.recovery_session.resource.get.v1	GET /_arkret/root/identity/recovery-sessions/{recovery_session_id}	RootIdentity/RecoverySessionGet	root.identity.recovery_session.resource.get
ak.root.identity.recovery_session.command.submit_proof.v1	POST /_arkret/root/identity/recovery-sessions/{recovery_session_id}/proofs	RootIdentity/RecoverySessionSubmitProof	root.identity.recovery_session.command.submit_proof

security_transactions · surface class core

Base interoperable surfaces used for documentation and lint; v1 support does not imply wire reachability without explicit supported_operation_bundles advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.security_transaction.command.create.v1	POST /_arkret/self/security-transactions	SelfSecurityTransactions/Create	self.security_transaction.command.create
ak.self.security_transaction.resource.get.v1	GET /_arkret/self/security-transactions/{transaction_id}	SelfSecurityTransactions/Get	self.security_transaction.resource.get
ak.self.security_transaction.command.continue.v1	POST /_arkret/self/security-transactions/{transaction_id}/continue	SelfSecurityTransactions/Continue	self.security_transaction.command.continue

events_sync · surface class core

Base interoperable surfaces used for documentation and lint; v1 support does not imply wire reachability without explicit supported_operation_bundles advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.events.command.submit.v1	POST /_arkret/self/events	SelfEvents/Submit	self.events.command.submit
ak.self.committed_event.resource.get.v1	GET /_arkret/self/committed-events/{event_id}	SelfCommittedEvent/Get	self.committed_event.resource.get
ak.self.events.read.delivery_status.v1	QUERY /_arkret/self/events/delivery-status	SelfEvents/DeliveryStatus	self.events.read.delivery_status
ak.self.committed_event.read.scan.v1	POST /_arkret/self/streams/scan	SelfStreams/Scan	self.streams.read.scan
ak.self.committed_event.stream.subscribe.v1	GET /_arkret/self/committed-events/subscribe	SelfCommittedEvent/Subscribe	self.committed_event.stream.subscribe
ak.self.account.read.describe.v1	GET /_arkret/self/account/describe	SelfAccount/Describe	self.account.query.describe
ak.self.account.read.viewer.v1	GET /_arkret/self/account/viewer	SelfAccount/Viewer	self.account.query.viewer
ak.self.account.command.update_profile.v1	POST /_arkret/self/account/profile	SelfAccount/UpdateProfile	self.account.command.update_profile
ak.self.actor_profile.read.resolve.v1	POST /_arkret/self/actor-profiles/query	SelfActorProfile/Resolve	self.actor_profile.query.resolve
ak.self.account.stream.subscribe.v1	GET /_arkret/self/account/subscribe	SelfAccount/Subscribe	self.account.stream.subscribe
ak.self.account.command.revoke_cursor.v1	POST /_arkret/self/account/cursor/revoke	SelfAccount/CursorRevoke	self.account.command.revoke_cursor
ak.self.realm_state_snapshot.read.by_ref.v1	GET /_arkret/self/realm-state-snapshot/{snapshot_id}	SelfRealmStateSnapshot/ByRef	self.realm_state_snapshot.query.by_ref
ak.self.realm_state_snapshot.read.manifest_head.v1	GET /_arkret/self/realm-state-snapshot/head	SelfRealmStateSnapshot/Head	self.realm_state_snapshot.query.manifest_head
ak.self.strand.watch.read.current.v1	POST /_arkret/self/strands/watch/current	SelfStrandWatch/Current	self.strand.watch.query.current
ak.self.current_principal.read.resolve.v1	POST /_arkret/self/account/current-principal	SelfCurrentPrincipal/Resolve	self.current_principal.query.resolve
ak.self.current_results.read.exact.v1	POST /_arkret/self/current-results/exact	SelfCurrentResults/ReadExact	self.current_results.query.exact
ak.self.realm.read.streams.v1	GET /_arkret/self/realms/{realm_id}/streams	SelfRealm/Streams	self.realm.query.streams

peer_federation · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.peer.events.command.submit.v1	POST /_arkret/peer/events	PeerEvents/Submit	peer.events.command.submit
ak.peer.account_status.read.resolve.v1	POST /_arkret/peer/account-status/resolve	PeerAccountStatus/Resolve	peer.account_status.query.resolve
ak.peer.account_status.command.submit.v1	POST /_arkret/peer/account-status	PeerAccountStatus/Submit	peer.account_status.command.submit
ak.peer.erasure_receipt.command.submit.v1	POST /_arkret/peer/erasure-receipts	PeerErasureReceipts/Submit	peer.erasure_receipt.command.submit
ak.peer.erasure_receipt.resource.get.v1	GET /_arkret/peer/erasure-receipts/{receipt_id}	PeerErasureReceipts/Get	peer.erasure_receipt.resource.get
ak.peer.mls.read.group_state_material.v1	POST /_arkret/peer/mls/group-state-material	PeerMls/GroupStateMaterial	peer.mls.query.group_state_material
ak.peer.mls.command.attest_add.v1	POST /_arkret/peer/mls/add-authority-attestations	PeerMls/AttestAdd	peer.mls.command.attest_add
ak.peer.mls.read.roster_authority.v1	POST /_arkret/peer/mls/roster-authority/query	PeerMls/RosterAuthority	peer.mls.query.roster_authority
ak.peer.committed_event.read.scan.v1	POST /_arkret/peer/streams/scan	PeerStreams/Scan	peer.streams.read.scan
ak.peer.invites.command.submit.v1	POST /_arkret/peer/invites	PeerInvites/Submit	peer.invites.command.submit
ak.peer.contacts.command.submit.v1	POST /_arkret/peer/contacts	PeerContacts/Submit	peer.contacts.command.submit
ak.peer.keys.keypackages.command.claim.v1	POST /_arkret/peer/keys/keypackages/claim	PeerKeys/KeyPackagesClaim	peer.keys.keypackages.command.claim
ak.peer.keys.keypackages.read.claim.v1	POST /_arkret/peer/keys/keypackages/claims/query	PeerKeys/KeyPackagesClaimQuery	peer.keys.keypackages.query.claim
ak.peer.keys.read.lookup.v1	POST /_arkret/peer/keys/query	PeerKeys/Query	peer.keys.query.lookup
ak.peer.signal.command.relay.v1	POST /_arkret/peer/signal	PeerSignal/Relay	peer.signal.command.relay

realm_join_intake · surface class core

Base interoperable surfaces used for documentation and lint; v1 support does not imply wire reachability without explicit supported_operation_bundles advertisement.

operation_id	HTTP	gRPC	MQ
ak.peer.realm_join.read.bootstrap.v1	POST /_arkret/peer/realm-joins/bootstrap	PeerRealmJoin/Bootstrap	peer.realm_join.query.bootstrap
ak.peer.realm_join.read.preview.v1	POST /_arkret/peer/realm-joins/preview	PeerRealmJoin/Preview	peer.realm_join.query.preview
ak.self.messages.command.prepare.v1	POST /_arkret/self/messages/prepare	SelfMessages/Prepare	self.messages.command.prepare
ak.self.realm_join.command.prepare.v1	POST /_arkret/self/realm-joins/prepare	SelfRealmJoin/Prepare	self.realm_join.command.prepare
ak.self.realm_join.read.preview.v1	POST /_arkret/self/realm-joins/preview	SelfRealmJoin/Preview	self.realm_join.query.preview

directory_discovery · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.find.directory.read.describe.v1	GET /_arkret/find/directory/describe	FindDirectory/Describe	find.directory.query.describe
ak.find.directory.read.search_realms.v1	POST /_arkret/find/directory/search-realms	FindDirectory/SearchRealms	find.directory.query.search_realms
ak.find.directory.read.resolve_realm.v1	POST /_arkret/find/directory/resolve-realm	FindDirectory/ResolveRealm	find.directory.query.resolve_realm

contact_lifecycle · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.contact.command.request.v1	POST /_arkret/self/contacts/request	SelfContact/Request	self.contact.command.request
ak.self.contact.command.checkpoint.v1	POST /_arkret/self/contacts/continuity-checkpoint	SelfContact/ContinuityCheckpoint	self.contact.command.checkpoint
ak.self.contact.command.respond.v1	POST /_arkret/self/contacts/respond	SelfContact/Respond	self.contact.command.respond
ak.self.contact.command.reject.v1	POST /_arkret/self/contacts/reject	SelfContact/Reject	self.contact.command.reject
ak.self.contact.command.scope_update.v1	POST /_arkret/self/contacts/scope-update	SelfContact/ScopeUpdate	self.contact.command.scope_update
ak.self.contact.read.list.v1	GET /_arkret/self/contacts	SelfContact/List	self.contact.query.list
ak.self.contact.command.tombstone.v1	POST /_arkret/self/contacts/tombstone	SelfContact/Tombstone	self.contact.command.tombstone
ak.self.invites.command.dispatch.v1	POST /_arkret/self/invites/dispatch	SelfInvites/Dispatch	self.invites.command.dispatch
ak.self.invite_receive_policy.resource.get.v1	GET /_arkret/self/invite-receive-policy	SelfInviteReceivePolicy/Get	self.invite_receive_policy.resource.get
ak.self.invite_receive_policy.resource.replace.v1	PUT /_arkret/self/invite-receive-policy	SelfInviteReceivePolicy/Replace	self.invite_receive_policy.resource.replace
ak.self.invite_locator.command.issue.v1	POST /_arkret/self/invite-locators	SelfInviteLocator/Issue	self.invite_locator.command.issue
ak.self.invite_locator.command.rotate.v1	POST /_arkret/self/invite-locators/rotate	SelfInviteLocator/Rotate	self.invite_locator.command.rotate
ak.self.invite_locator.command.revoke.v1	POST /_arkret/self/invite-locators/revoke	SelfInviteLocator/Revoke	self.invite_locator.command.revoke
ak.self.direct_conversation.read.resolve.v1	POST /_arkret/self/direct-conversations/resolve	SelfDirectConversation/Resolve	self.direct_conversation.query.resolve

circle_management · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.circle.command.create.v1	POST /_arkret/self/circles	SelfCircle/Create	self.circle.command.create
ak.self.circle.read.list.v1	GET /_arkret/self/circles	SelfCircle/List	self.circle.query.list
ak.self.circle.resource.get.v1	GET /_arkret/self/circles/{circle_id}	SelfCircle/Get	self.circle.resource.get
ak.self.circle.member.command.add.v1	POST /_arkret/self/circles/{circle_id}/members	SelfCircle/MemberAdd	self.circle.member.command.add
ak.self.circle.member.resource.delete.v1	DELETE /_arkret/self/circles/{circle_id}/members/{actor_id}	SelfCircle/MemberRemove	self.circle.member.resource.delete
ak.self.circle.command.rotate_scope.v1	POST /_arkret/self/circles/{circle_id}/scope-rotate	SelfCircle/ScopeRotate	self.circle.command.rotate_scope

realm_governance_links · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.realm_link.read.list.v1	GET /_arkret/self/realms/{realm_id}/links	SelfRealmLink/List	self.realm_link.query.list
ak.self.realm_organization.read.list.v1	GET /_arkret/self/realms/{realm_id}/organizations	SelfRealmOrganization/List	self.realm_organization.query.list

realm_read · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.realm.resource.get.v1	GET /_arkret/self/realms/{realm_id}	SelfRealm/Get	self.realm.resource.get
ak.self.realm.read.export.v1	GET /_arkret/self/realms/{realm_id}/export	SelfRealm/Export	self.realm.query.export
ak.self.mls.read.group_state_material.v1	POST /_arkret/self/mls/group-state-material/query	SelfMls/GroupStateMaterial	self.mls.query.group_state_material
ak.self.mls.read.roster_authority.v1	POST /_arkret/self/mls/roster-authority/query	SelfMls/RosterAuthority	self.mls.query.roster_authority

consent_management · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.consent.read.list.v1	GET /_arkret/self/consent/results	SelfConsent/List	self.consent.query.list
ak.self.consent.resource.get.v1	GET /_arkret/self/consent/result	SelfConsent/Get	self.consent.resource.get
ak.self.consent.command.grant.v1	POST /_arkret/self/consent/results/grant	SelfConsent/Grant	self.consent.command.grant
ak.self.consent.command.revoke.v1	POST /_arkret/self/consent/results/revoke	SelfConsent/Revoke	self.consent.command.revoke
ak.self.consent.command.request.v1	POST /_arkret/self/consent/request	SelfConsent/Request	self.consent.command.request

account_data · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.account_data.read.list.v1	GET /_arkret/self/account_data	SelfAccountData/List	self.account_data.query.list
ak.self.account_data.resource.get.v1	GET /_arkret/self/account_data/{account_data_key}	SelfAccountData/Get	self.account_data.resource.get
ak.self.account_data.resource.replace.v1	PUT /_arkret/self/account_data/{account_data_key}	SelfAccountData/Replace	self.account_data.resource.replace
ak.self.account_data.resource.delete.v1	DELETE /_arkret/self/account_data/{account_data_key}	SelfAccountData/Delete	self.account_data.resource.delete

read_cursor · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.read_cursor.command.advance.v1	POST /_arkret/self/read-cursors	SelfReadCursor/Advance	self.read_cursor.command.advance
ak.self.read_cursor.read.list.v1	GET /_arkret/self/read-cursors	SelfReadCursor/List	self.read_cursor.query.list

actor_private_events · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.actor_private_events.command.submit.v1	POST /_arkret/self/actor-private-events	SelfActorPrivateEvents/Submit	self.actor_private_events.command.submit

blob_storage · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.blob.upload.create.v1	POST /_arkret/self/blob/upload	SelfBlob/Upload	self.blob.upload.create
ak.self.blob.resource.head.v1	HEAD /_arkret/self/blob/get	SelfBlob/Head	self.blob.resource.head
ak.self.blob.resource.get.v1	GET /_arkret/self/blob/get	SelfBlob/Get	self.blob.resource.get
ak.self.blob.command.presign.v1	POST /_arkret/self/blob/presign	SelfBlob/Presign	self.blob.command.presign

realtime_media · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.media.read.ice_config.v1	POST /_arkret/self/rtc/ice-config	SelfMedia/IceConfig	self.media.query.ice_config
ak.self.signal.command.send.v1	POST /_arkret/self/signal	SelfSignal/Send	self.signal.command.send
ak.self.signal.stream.subscribe.v1	GET /_arkret/self/signal/subscribe	SelfSignal/Subscribe	self.signal.stream.subscribe
ak.self.call.media.exchange.issue_token.v1	POST /_arkret/self/rtc/token	SelfCallMedia/TokenExchange	self.call.media.exchange.issue_token
ak.self.media_service_binding.read.resolve.v1	POST /_arkret/self/media-service-bindings/query	SelfMediaServiceBinding/Resolve	self.media_service_binding.query.resolve

authz_policy · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.authz.read.check.v1	POST /_arkret/self/authz/check	SelfAuthz/Check	self.authz.query.check
ak.self.authz.grants.read.effective.v1	GET /_arkret/self/authz/effective-grants	SelfAuthz/GetEffectiveGrants	self.authz.grants.query.effective
ak.self.authz.invites.read.list.v1	GET /_arkret/self/authz/invites	SelfAuthz/GetInvites	self.authz.invites.query.list

moderation_reports · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.moderation.command.report.v1	POST /_arkret/self/moderation/report	SelfModeration/Report	self.moderation.command.report

device_and_keys · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.device_messages.command.send.v1	POST /_arkret/self/device_messages	SelfDeviceMessages/Send	self.device_messages.command.send
ak.self.device_messages.read.list.v1	GET /_arkret/self/device_messages	SelfDeviceMessages/Get	self.device_messages.query.list
ak.self.device_messages.command.ack.v1	POST /_arkret/self/device_messages/ack	SelfDeviceMessages/Ack	self.device_messages.command.ack
ak.self.keys.upload.create.v1	POST /_arkret/self/keys/upload	SelfKeys/Upload	self.keys.upload.create
ak.self.keys.read.lookup.v1	POST /_arkret/self/keys/query	SelfKeys/Query	self.keys.query.lookup
ak.self.signer_keys.read.resolve.v1	POST /_arkret/self/signer-keys/query	SelfSignerKeys/Resolve	self.signer_keys.query.resolve
ak.self.keys.command.claim.v1	POST /_arkret/self/keys/claim	SelfKeys/Claim	self.keys.command.claim
ak.self.keys.keypackages.upload.create.v1	POST /_arkret/self/keys/keypackages/upload	SelfKeys/KeyPackagesUpload	self.keys.keypackages.upload.create
ak.self.keys.keypackages.command.claim.v1	POST /_arkret/self/keys/keypackages/claim	SelfKeys/KeyPackagesClaim	self.keys.keypackages.command.claim
ak.self.keys.keypackages.command.consume.v1	POST /_arkret/self/keys/keypackages/consume	SelfKeys/KeyPackagesConsume	self.keys.keypackages.command.consume
ak.self.keys.keypackages.command.revoke.v1	POST /_arkret/self/keys/keypackages/revoke	SelfKeys/KeyPackagesRevoke	self.keys.keypackages.command.revoke
ak.self.keys.keypackages.read.claim.v1	POST /_arkret/self/keys/keypackages/claims/query	SelfKeys/KeyPackagesClaimQuery	self.keys.keypackages.query.claim
ak.self.keys.backups.resource.replace.v1	PUT /_arkret/self/keys/backups/{backup_id}	SelfKeys/BackupsReplace	self.keys.backups.resource.replace
ak.self.keys.backups.read.list.v1	GET /_arkret/self/keys/backups	SelfKeys/BackupsList	self.keys.backups.query.list
ak.self.keys.backups.command.unlock.v1	POST /_arkret/self/keys/backups/{backup_id}/unlock	SelfKeys/BackupsUnlock	self.keys.backups.command.unlock
ak.self.keys.backups.command.issue_delete_challenge.v1	POST /_arkret/self/keys/backups/{backup_id}/delete-challenge	SelfKeys/BackupsIssueDeleteChallenge	self.keys.backups.command.issue_delete_challenge
ak.self.keys.backups.command.issue_unlock_challenge.v1	POST /_arkret/self/keys/backups/{backup_id}/unlock-challenge	SelfKeys/BackupsIssueUnlockChallenge	self.keys.backups.command.issue_unlock_challenge
ak.self.keys.backups.resource.delete.v1	DELETE /_arkret/self/keys/backups/{backup_id}	SelfKeys/BackupsDelete	self.keys.backups.resource.delete

push · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.edge.push.command.apply_registration.v1	POST /_arkret/edge/push/registrations:apply
ak.edge.push.command.register_device.v1	POST /_arkret/edge/push/register-device	EdgePush/RegisterDevice	edge.push.command.register_device
ak.edge.push.command.unregister_device.v1	POST /_arkret/edge/push/unregister-device	EdgePush/UnregisterDevice	edge.push.command.unregister_device
ak.edge.push.command.notify.v1	POST /_arkret/edge/push/notify	EdgePush/Notify	edge.push.command.notify

realm_object_read · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.space.read.list.v1	GET /_arkret/self/realms/{realm_id}/spaces	SelfSpace/List	self.space.query.list
ak.self.strand.read.list.v1	GET /_arkret/self/realms/{realm_id}/strands	SelfStrand/List	self.strand.query.list
ak.self.morph.read.list.v1	GET /_arkret/self/realms/{realm_id}/morphs	SelfMorph/List	self.morph.query.list
ak.self.morph.resource.get.v1	GET /_arkret/self/realms/{realm_id}/morphs/{morph_id}	SelfMorph/Get	self.morph.resource.get

applet · surface class interop_bridge

Adapter surfaces that bridge Arkret to external protocols (MIMI Internet-Drafts, third-party Applet hosts). Implementations advertise these only when the external protocol is supported; bridge operations are not part of any core or extension profile and frequently mirror an in-spec operation via bridges_to.

operation_id	HTTP	gRPC	MQ
ak.edge.applet.read.ping.v1	GET /_arkret/edge/applet/ping	EdgeApplet/Ping	edge.applet.query.ping
ak.edge.applet.read.describe.v1	GET /_arkret/edge/applet/describe	EdgeApplet/Describe	edge.applet.query.describe
ak.edge.applet.command.transaction.v1	POST /_arkret/edge/applet/transactions	EdgeApplet/Transaction	edge.applet.command.transaction
ak.edge.applet.actor.read.resolve.v1	GET /_arkret/edge/applet/actors/{actor_id}	EdgeApplet/ResolveActor	edge.applet.actor.query.resolve
ak.edge.applet.realm.read.resolve.v1	GET /_arkret/edge/applet/realms/{realm_id_or_alias}	EdgeApplet/ResolveRealm	edge.applet.realm.query.resolve
ak.edge.applet.read.protocol_metadata.v1	GET /_arkret/edge/applet/protocols/{protocol}	EdgeApplet/ProtocolMetadata	edge.applet.query.protocol_metadata
ak.edge.applet.managed_actor.command.author.v1	POST /_arkret/edge/applet/managed-actors/author	EdgeApplet/ManagedActorAuthor	edge.applet.managed_actor.command.author
ak.edge.applet.third_party_users.read.list.v1	GET /_arkret/edge/applet/third_party/users	EdgeApplet/ThirdPartyUsers	edge.applet.third_party_users.query.list
ak.edge.applet.third_party_locations.read.list.v1	GET /_arkret/edge/applet/third_party/locations	EdgeApplet/ThirdPartyLocations	edge.applet.third_party_locations.query.list

applet_install · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.applet.install.command.preview.v1	POST /_arkret/self/applets/install/preview	SelfApplet/InstallPreview	self.applet.install.command.preview
ak.self.applet.command.install.v1	POST /_arkret/self/applets/install	SelfApplet/Install	self.applet.command.install
ak.self.applet.revoke.command.preview.v1	POST /_arkret/self/applets/{applet_id}/revoke/preview	SelfApplet/RevokePreview	self.applet.revoke.command.preview
ak.self.applet.command.revoke.v1	POST /_arkret/self/applets/{applet_id}/revoke	SelfApplet/Revoke	self.applet.command.revoke
ak.self.applet.authority.read.material.v1	POST /_arkret/self/applets/{applet_id}/authority/material	SelfManagement/AppletAuthorityReadMaterial	self.applet.authority.read.material

applet_ghost · surface class interop_bridge

Adapter surfaces that bridge Arkret to external protocols (MIMI Internet-Drafts, third-party Applet hosts). Implementations advertise these only when the external protocol is supported; bridge operations are not part of any core or extension profile and frequently mirror an in-spec operation via bridges_to.

operation_id	HTTP	gRPC	MQ
ak.self.applet.ghost.command.preview.v1	POST /_arkret/self/applets/{applet_id}/ghosts/provision/preview	SelfApplet/GhostPreview	self.applet.ghost.command.preview
ak.self.applet.ghost.command.provision.v1	POST /_arkret/self/applets/{applet_id}/ghosts/provision	SelfApplet/GhostProvision	self.applet.ghost.command.provision
ak.self.applet.bot.command.preview.v1	POST /_arkret/self/applets/{applet_id}/bots/provision/preview	SelfApplet/BotPreview	self.applet.bot.command.preview
ak.self.applet.bot.command.provision.v1	POST /_arkret/self/applets/{applet_id}/bots/provision	SelfApplet/BotProvision	self.applet.bot.command.provision

mimi_interop · surface class interop_bridge

Adapter surfaces that bridge Arkret to external protocols (MIMI Internet-Drafts, third-party Applet hosts). Implementations advertise these only when the external protocol is supported; bridge operations are not part of any core or extension profile and frequently mirror an in-spec operation via bridges_to.

operation_id	HTTP	gRPC	MQ
ak.open.mimi.read.provider_directory.v1	GET /_arkret/open/mimi/provider-directory	OpenMimi/ProviderDirectory	open.mimi.query.provider_directory
ak.open.mimi.exchange.request_key_material.v1	POST /_arkret/open/mimi/key-material	OpenMimi/KeyMaterial	open.mimi.exchange.request_key_material
ak.open.mimi.command.submit_message.v1	POST /_arkret/open/mimi/strands/{strand_id}/messages	OpenMimi/SubmitMessage	open.mimi.command.submit_message
ak.open.mimi.command.update_room.v1	POST /_arkret/open/mimi/strands/{strand_id}/update	OpenMimi/RoomUpdate	open.mimi.command.update_room
ak.open.mimi.command.request_consent.v1	POST /_arkret/open/mimi/consent/request	OpenMimi/RequestConsent	open.mimi.command.request_consent
ak.open.mimi.command.update_consent.v1	POST /_arkret/open/mimi/consent/update	OpenMimi/UpdateConsent	open.mimi.command.update_consent
ak.open.mimi.read.identifiers.v1	POST /_arkret/open/mimi/identifiers/query	OpenMimi/IdentifierQuery	open.mimi.query.identifiers
ak.open.mimi.command.notify.v1	POST /_arkret/open/mimi/strands/{strand_id}/notify	OpenMimi/Notify	open.mimi.command.notify
ak.open.mimi.command.report_abuse.v1	POST /_arkret/open/mimi/report-abuse	OpenMimi/ReportAbuse	open.mimi.command.report_abuse
ak.open.mimi.command.proxy_download.v1	POST /_arkret/open/mimi/proxy-download	OpenMimi/ProxyDownload	open.mimi.command.proxy_download

agent_pairing_handoff · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.open.agent_pairing.read.resolve.v1	POST /_arkret/open/agent-pairing/resolve	OpenAgentPairing/Resolve	open.agent_pairing.query.resolve
ak.open.agent_pairing.command.submit_runtime_key_request.v1	POST /_arkret/open/agent-pairing/runtime-key-requests	OpenAgentPairing/SubmitRuntimeKeyRequest	open.agent_pairing.command.submit_runtime_key_request
ak.open.agent_pairing.read.runtime_key_request_status.v1	POST /_arkret/open/agent-pairing/runtime-key-requests/status	OpenAgentPairing/RuntimeKeyRequestStatus	open.agent_pairing.query.runtime_key_request_status

device_pairing_handoff · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.open.device_pairing.command.stage.v1	POST /_arkret/open/device-pairing/requests	OpenDevicePairing/Stage	open.device_pairing.command.stage
ak.open.device_pairing.read.resolve.v1	POST /_arkret/open/device-pairing/resolve	OpenDevicePairing/Resolve	open.device_pairing.query.resolve
ak.open.device_pairing.read.status.v1	POST /_arkret/open/device-pairing/requests/status	OpenDevicePairing/Status	open.device_pairing.query.status

invite_locator_handoff · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.open.invite_locator.read.resolve.v1	POST /_arkret/open/invite-locators/resolve	OpenInviteLocator/Resolve	open.invite_locator.query.resolve

third_party_invite_handoff · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.open.third_party_invite.command.activate.v1	POST /_arkret/open/third-party-invites/activate	OpenThirdPartyInvite/Activate	open.third_party_invite.command.activate
ak.open.third_party_invite.command.present_token.v1	POST /_arkret/open/third-party-invites/present	OpenThirdPartyInvite/PresentToken	open.third_party_invite.command.present_token
ak.open.third_party_invite.command.provision.v1	POST /_arkret/open/third-party-invites/provision	OpenThirdPartyInvite/Provision	open.third_party_invite.command.provision
ak.open.third_party_invite.read.provisioning_status.v1	POST /_arkret/open/third-party-invites/status	OpenThirdPartyInvite/ProvisioningStatus	open.third_party_invite.query.provisioning_status
ak.self.third_party_invite.read.acceptance_attestation.v1	POST /_arkret/self/third-party-invites/acceptance-attestation	SelfThirdPartyInvite/AcceptanceAttestation	self.third_party_invite.query.acceptance_attestation

identity_resolution · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.open.identity.read.resolution.v1	GET /_arkret/open/principals/{principal_id}/resolution	OpenIdentity/Resolution	open.identity.query.resolution
ak.self.identity.read.resolution_audit.v1	POST /_arkret/self/identity/resolution-audit/query	SelfIdentity/ResolutionAudit	self.identity.query.resolution_audit
ak.open.service.read.resolution.v1	GET /_arkret/open/services/{service_id}/resolution	OpenService/Resolution	open.service.query.resolution

account_auth · surface class deployment_local

Deployment-specific, operator, or product-local surfaces that MUST NOT be assumed from core protocol support alone.

operation_id	HTTP	gRPC	MQ
ak.gate.account.exchange.create_handoff.v1	POST /_arkret/gate/account/authentication-handoffs
ak.gate.account.read.onboarding.v1	GET /_arkret/gate/account/onboarding
ak.gate.account.command.issue_identity_binding_challenge.v1	POST /_arkret/gate/account/identity-binding-challenges
ak.gate.account.command.issue_did_binding_challenge.v1	POST /_arkret/gate/account/did-binding-challenges
ak.gate.account.command.abandon_identity_creation.v1	POST /_arkret/gate/account/identity-abandonments
ak.gate.account.command.register.v1	POST /_arkret/gate/account/register	GateAccount/Register	gate.account.command.register
ak.gate.account.command.finalize_device_pairing.v1	POST /_arkret/gate/account/device-pairing/finalizations	GateAccount/FinalizeDevicePairing	gate.account.command.finalize_device_pairing
ak.gate.account.command.pair_device.v1	POST /_arkret/gate/account/device-pair	GateAccount/DevicePair	gate.account.command.pair_device
ak.gate.account.read.claim_device_pairing_code.v1	POST /_arkret/gate/account/device-pairing/code-claims	GateAccount/ClaimDevicePairingCode	gate.account.query.claim_device_pairing_code
ak.gate.account.command.issue_session_grant.v1	POST /_arkret/gate/account/session-grants	GateAccount/IssueSessionGrant	gate.account.command.issue_session_grant
ak.gate.account.command.refresh_session_grant.v1	POST /_arkret/gate/account/session-grants/refresh
ak.gate.account.command.issue_recovery_completion_grant.v1	POST /_arkret/gate/account/recovery-session-grants/issue
ak.gate.account.command.logout.v1	POST /_arkret/gate/account/logout
ak.gate.account.command.request_erasure.v1	POST /_arkret/gate/account/erasure-requests	GateAccount/RequestErasure	gate.account.command.request_erasure
ak.gate.account.command.revoke_session.v1	POST /_arkret/gate/account/session-grants/revoke	GateAccount/SessionRevoke	gate.account.command.revoke_session

agent_runtime · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.gate.account.command.pair_agent_key.v1	POST /_arkret/gate/account/agent-key-pair	GateAccount/AgentKeyPair	gate.account.command.pair_agent_key
ak.self.agent.command.provision.v1	POST /_arkret/self/agents	SelfAgent/Provision	self.agent.command.provision
ak.self.agent.command.renew_pairing.v1	POST /_arkret/self/agents/{agent_id}/renew-pairing	SelfAgent/RenewPairing	self.agent.command.renew_pairing
ak.self.agent.read.list.v1	GET /_arkret/self/agents	SelfAgent/List	self.agent.query.list
ak.self.agent.resource.get.v1	GET /_arkret/self/agents/{agent_id}	SelfAgent/Get	self.agent.resource.get
ak.self.agent.command.pause.v1	POST /_arkret/self/agents/{agent_id}/pause	SelfAgent/Pause	self.agent.command.pause
ak.self.agent.command.resume.v1	POST /_arkret/self/agents/{agent_id}/resume	SelfAgent/Resume	self.agent.command.resume
ak.self.agent.command.deactivate.v1	POST /_arkret/self/agents/{agent_id}/deactivate	SelfAgent/Deactivate	self.agent.command.deactivate
ak.self.agent.sidecar.command.ensure.v1	POST /_arkret/self/agent-sidecars:ensure	SelfAgent/SidecarEnsure	self.agent.sidecar.command.ensure
ak.self.agent.sidecar.resource.get.v1	GET /_arkret/self/agent-sidecars/{sidecar_id}	SelfAgent/SidecarGet	self.agent.sidecar.resource.get
ak.self.agent.sidecar.read.list.v1	GET /_arkret/self/agent-sidecars	SelfAgent/SidecarList	self.agent.sidecar.query.list
ak.self.agent.participation.resource.replace.v1	PUT /_arkret/self/agents/{agent_id}/participation	SelfAgent/ParticipationReplace	self.agent.participation.resource.replace
ak.self.agent.participation.resource.get.v1	GET /_arkret/self/agents/{agent_id}/participation	SelfAgent/ParticipationGet	self.agent.participation.resource.get

authority_commit · surface class core

Base interoperable surfaces used for documentation and lint; v1 support does not imply wire reachability without explicit supported_operation_bundles advertisement.

operation_id	HTTP	gRPC	MQ
ak.open.realm_authority.read.bundle.v1	POST /_arkret/open/realm-authority/bundle	OpenRealmAuthority/Bundle	open.realm_authority.read.bundle
ak.peer.realm_authority.command.handoff.v1	POST /_arkret/peer/realm-authority/handoff	PeerRealmAuthority/Handoff	peer.realm_authority.command.handoff

management_review · surface class extension

Optional interoperable surfaces that are part of the Arkret specification but require explicit discovery/profile advertisement.

operation_id	HTTP	gRPC	MQ
ak.self.management_review.command.request.v1	POST /_arkret/self/management-reviews/requests	SelfManagement/Management_ReviewCommandRequest	self.management_review.command.request
ak.self.management_review.command.decide.v1	POST /_arkret/self/management-reviews/decisions	SelfManagement/Management_ReviewCommandDecide	self.management_review.command.decide
ak.self.management_review.read.status.v1	POST /_arkret/self/management-reviews/status	SelfManagement/Management_ReviewReadStatus	self.management_review.read.status

5. 落地要求

• 任何新增、重命名或删除 operation_id 的提案，必须先更新 artifacts/registry/contract-registry.json 中的 operation_registry，再生成 registry / OpenAPI / 文档视图。
• 任何节点都应能发布一份可下载的 OpenAPI 文档（建议路径 /.well-known/arkret/openapi.yaml），并在 service DID metadata 中声明版本和 hash。
• 实现必须保持 operation_id 在演进中稳定；若请求字段名变更，必须通过 profile、schema 版本或 feature discovery 明确协商。
• OpenAPI 只定义形态，不定义核心语义。核心语义仍由本协议对象模型、授权状态、签名、同步与加密规范给出。
• 实现不得因为支持 core Event / Account aggregate 就默认声称支持目录、MIMI、账户登录、管理员或 E2EE key-management surface；这些能力必须通过当前角色 ServiceDescribe.supported_operation_bundles 中的精确 carrier row、supported_profiles 或两者同时显式声明。
• 所有 path 都是 /_arkret/<信任段>/... 形态的绝对路径，不含版本段；servers 只声明 https://{host}。生成 OpenAPI 时无需 path-level servers 覆盖，协议版本通过 *.describe 的精确 supported_operation_bundles 交集（可选 Arkret-Protocol-Version header）判定，不放进 path。
• GET /_arkret/self/account/subscribe（ak.self.account.stream.subscribe.v1）是客户端账号视角聚合同步入口（跨 Realm delta + to_device + account_data + device_lists + unread / notification counts），HTTP binding 使用 NDJSON frame stream；presence 是有界 TTL 的 encrypted Signal，走 Signal live rail，不进入 account aggregate。POST /_arkret/self/streams/scan（ak.self.committed_event.read.scan.v1）是单条 stream 的位置化读取 / 历史回补，按 after_position 或 before_position 恰选一个方向，边界是该 caller 的允许区间而不是物理整流；它要求调用方已经持有 stream_ref，因此流的发现由 GET /_arkret/self/realms/{realm_id}/streams（ak.self.realm.read.streams.v1）承担：ACL 过滤、可分页、只列已建立 Commit 链的流，使有界订阅窗口之外的流仍然可发现、可读取、不饥饿；GET /_arkret/self/committed-events/subscribe（ak.self.committed_event.stream.subscribe.v1，可携 bounded catch-up replay）是按 selector 的事件流订阅。ak.self.account.stream.subscribe.v1 与 ak.self.committed_event.stream.subscribe.v1 是对称但不等价的订阅（account-aggregate vs per-Realm event log）；三类操作的 selector、auth、frame schema 与 freshness 行为不同，不得互相替代，也不得新增未声明的 canonical account / events endpoint。
• 生成的 OpenAPI 引用统一 error envelope，覆盖 404 unrecognized_endpoint、405 method_not_allowed、429 rate_limited 与 503 temporarily_unavailable 的标准响应。
• OpenAPI security scheme 不定义 query string token 认证；受保护 endpoint 使用 header / signature / mTLS / signed proof body 等认证方式。
• Blob / media endpoint 的 schema 显式声明 Content-Type、Content-Disposition、Range、Content-Range、Location 和缓存头行为，避免通过 header 泄露不可见资源。