hostapi

package
v0.0.0-...-e12325a Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 73 Imported by: 0

Documentation

Overview

Package hostapi 实现 sforum.host/v1 宿主面(F2.2)。

插件不得 import 核心内部业务包;应通过 RPC 调用本面的方法。 每次调用都校验 extension 的 capability 授权。

Index

Constants

View Source
const (
	HostCacheCoreProviderID = "core.cache.redis"
	HostCacheFallbackClosed = "closed"
	// HostCacheFallbackNext remains a recognized compatibility value, but v1
	// execution rejects it until a durable cross-provider generation/tombstone
	// protocol can prevent deleted or invalidated data from resurfacing.
	HostCacheFallbackNext        = "next"
	HostCacheMaximumKeyBytes     = 512
	HostCacheMaximumValueBytes   = 1 << 20
	HostCacheMaximumTags         = 64
	HostCacheMinimumTTL          = time.Millisecond
	HostCacheMaximumTTL          = 24 * time.Hour
	HostCacheMinimumLockTTL      = 100 * time.Millisecond
	HostCacheMaximumLockTTL      = 30 * time.Second
	HostCacheDefaultRememberWait = 2 * time.Second
)
View Source
const (
	// QuerySelfEmailRegistryID 是 stable 定义在 Query Registry 的显式投影 id,
	// 也是插件实际调用的 query id。
	QuerySelfEmailRegistryID              = "core.query.identity.self_email"
	QuerySelfEmailRegistryContractVersion = QuerySelfEmailRegistryID + "@1"
	QuerySelfEmailRegistryPlanVersion     = QuerySelfEmailRegistryID + ".plan@1"
	// ProtocolV2ConsentQueryScope 与 shortcode 投影的 "content" 区分:这一面只在
	// 宿主发起的 route/admin 调用里签发。
	ProtocolV2ConsentQueryScope = "route"
	// ProtocolV2ConsentQueryMaxCost 是单次读取的成本预算:字段 3 × 1 + 基础 10 +
	// 单行 1 = 14,远低于 50,留出 Query Registry 成本口径变化的余量。
	ProtocolV2ConsentQueryMaxCost = 50
)

同意式(consent-gated)读取面的 Host 定义。

设计边界(见 knowledge/decisions/2026-10-18-consented-email-surface.md):

  • public.users 的 email 永远不进入 sforum_core_v1 视图,也不进入任何公开 稳定查询;它只出现在这一条 ConsentGated 定义里。
  • 定义本身没有 filters/sorts:actor 由 host 签发的单次 query actor 委派解出 后注入 context,插件请求里没有任何 userId 参数可注入。
  • actorless 稳定入口(query_id = sforum.core.identity.self_email)一律拒绝; 唯一可执行路径是它在 Query Registry 的显式投影 (core.query.identity.self_email),那里必须携带 actor_delegation。
View Source
const (
	// ProtocolV2ConsentQueryRateLimitMax 是 (actor, extension) 维度的读取上限:
	// 60 次/分钟。阈值按站点规模可调,但 Host 侧上限先按此默认值落地。
	ProtocolV2ConsentQueryRateLimitMax = 60
	// ProtocolV2ConsentQueryRateLimitWindow 是限流窗口。
	ProtocolV2ConsentQueryRateLimitWindow = time.Minute
	// ProtocolV2ConsentQueryAuditAction 是每次成功读取写入的稳定审计动作。
	// 它不带值:metadata 只有标识与行数。
	ProtocolV2ConsentQueryAuditAction = audit.ActionIdentityEmailConsentRead
)
View Source
const (
	// QueryRegistryCoreExtensionID is the sealed Host publication owner for
	// stable Protocol V2 queries projected into Query Registry.
	QueryRegistryCoreExtensionID      = "core.query"
	QueryRegistryCoreExtensionVersion = "1.0.0"
)
View Source
const (
	ProtocolV2QueryFilterValueSchemaID = "sforum.query.filter.value"
	ProtocolV2QueryFilterValueSchemaV1 = "1"
)
View Source
const (
	ServiceDependencyRequired = "required"
	ServiceDependencyOptional = "optional"
)
View Source
const (
	ServiceActionAdd     = "add"
	ServiceActionBefore  = "before"
	ServiceActionAfter   = "after"
	ServiceActionWrap    = "wrap"
	ServiceActionReplace = "replace"
)
View Source
const (
	ShortcodeProjectionExtensionID = "sforum-shortcodes"
	ShortcodeProjectionMaxBatch    = 32

	QueryShortcodePublicUsersBatch      = "sforum.core.shortcode.public_users.batch"
	QueryShortcodePublicTopicsBatch     = "sforum.core.shortcode.public_topics.batch"
	QueryShortcodePublicCommentsBatch   = "sforum.core.shortcode.public_comments.batch"
	QueryShortcodePublicCategoriesBatch = "sforum.core.shortcode.public_categories.batch"
	QueryShortcodeFriendLinksList       = "sforum.core.shortcode.friend_links.list"
	QueryShortcodeAuthorDecisionsBatch  = "sforum.core.shortcode.author_decisions.batch"
	QueryShortcodeReplyEligibilityBatch = "sforum.core.shortcode.reply_eligibility.batch"

	QueryShortcodePublicUserSchema       = "sforum.core.shortcode.public_user"
	QueryShortcodePublicTopicSchema      = "sforum.core.shortcode.public_topic"
	QueryShortcodePublicCommentSchema    = "sforum.core.shortcode.public_comment"
	QueryShortcodePublicCategorySchema   = "sforum.core.shortcode.public_category"
	QueryShortcodeFriendLinkSchema       = "sforum.core.shortcode.friend_link"
	QueryShortcodeAuthorDecisionSchema   = "sforum.core.shortcode.author_decision"
	QueryShortcodeReplyEligibilitySchema = "sforum.core.shortcode.reply_eligibility"

	ShortcodeProjectionContractVersion = "1"
	ShortcodeProjectionSchemaVersion   = "1"
)
View Source
const (
	// Version 是 Host API 主版本标识。
	Version = "sforum.host/v1"

	// DefaultTimeout 单次 Host 调用默认超时。
	DefaultTimeout = 3 * time.Second
)
View Source
const (
	MethodPing                   = "Ping"
	MethodCheckPermission        = "CheckPermission"
	MethodGetSettings            = "GetSettings"
	MethodEnqueueOwnJob          = "EnqueueOwnJob"
	MethodAppendAudit            = "AppendAudit"
	MethodGetUserSafe            = "GetUserSafe"
	MethodListExtensionInventory = "ListExtensionInventory"
)

Method 名常量,与 RPC 路径对齐。

View Source
const (
	VersionV2                = "sforum.host/v2"
	QueryOwnSettingsID       = "sforum.extensions.settings.own"
	QueryOwnSettingsVersion  = "1"
	QueryOwnSettingsSchemaID = "sforum.extensions.settings.own.result"
	QueryOwnSettingsSchemaV1 = "1"
	// QueryExtensionInventoryID 是 extensions.read 对应的稳定去敏清单查询。
	QueryExtensionInventoryID       = "sforum.core.extensions.inventory.list"
	QueryExtensionInventoryVersion  = "1"
	QueryExtensionInventorySchemaID = "sforum.core.extensions.inventory"
	QueryExtensionInventorySchemaV1 = "1"
	IdentitySafeUserSchemaID        = "sforum.identity.user.safe"
	IdentitySafeUserSchemaV1        = "1"
	PermissionPolicyID              = "sforum.identity.rbac@1"
	JobPayloadSchemaVersionV1       = "1"
	AuditMetadataSchemaVersion      = "1"
)
View Source
const (
	CommandAICompleteID            = "sforum.ai.complete"
	CommandAICompleteVersion       = "1"
	CommandAICompleteInputSchema   = "sforum.ai.complete.input"
	CommandAICompleteOutputSchema  = "sforum.ai.complete.result"
	CommandAICompleteSchemaVersion = "1"

	ProtocolV2AICompleteMaxPurposeLen = 128
	ProtocolV2AICompleteMaxLocaleLen  = 32
)

插件发起 AI 补全的边界。

契约刻意镜像 ai.CompletionRequest 但去掉 ProfileRef:插件只能声明用途与成本 等级,具体用哪个供应商与模型由站点配置决定。让插件寻址 profile 等于把成本与 质量的最终决定权交给插件代码,运营者将无法再用控制台约束它。

View Source
const (
	CommandAttachmentExtensionClaimID             = "sforum.attachments.extension.claim"
	CommandAttachmentExtensionClaimVersion        = "1"
	CommandAttachmentExtensionClaimInputSchema    = "sforum.attachments.extension.claim.input"
	CommandAttachmentExtensionClaimOutputSchema   = "sforum.attachments.extension.claim.result"
	CommandAttachmentExtensionReleaseID           = "sforum.attachments.extension.release"
	CommandAttachmentExtensionReleaseVersion      = "1"
	CommandAttachmentExtensionReleaseInputSchema  = "sforum.attachments.extension.release.input"
	CommandAttachmentExtensionReleaseOutputSchema = "sforum.attachments.extension.release.result"
	CommandAttachmentExtensionListID              = "sforum.attachments.extension.list"
	CommandAttachmentExtensionListVersion         = "1"
	CommandAttachmentExtensionListInputSchema     = "sforum.attachments.extension.list.input"
	CommandAttachmentExtensionListOutputSchema    = "sforum.attachments.extension.list.result"
	CommandAttachmentExtensionSchemaVersion       = "1"
)

三条命令让扩展复用 Core 附件体系(上传、对象存储、出图、变体、回收), 而不是把图片塞进自己的业务表或自建 bytea 存储:

claim   —— 把某个已上传附件登记成「本扩展拥有的公开资产」,强制公开并重算计数
release —— 删掉引用并重算计数,让孤儿回收正常生效
list    —— 只读对账:列出本扩展全部存活引用

命令目录是数据驱动的,proto/SDK 生成物不变;`host_commands` 已是合法 grant。

View Source
const (
	CommandAttachmentStatusSetID          = "sforum.attachments.status.set"
	CommandAttachmentStatusSetVersion     = "1"
	CommandAttachmentStatusInputSchemaID  = "sforum.attachments.status.input"
	CommandAttachmentStatusOutputSchemaID = "sforum.attachments.status.result"
	CommandAttachmentStatusSchemaVersion  = "1"
)
View Source
const (
	CommandBadgesFactRecordID            = "badges.fact.record"
	CommandBadgesFactRecordVersion       = "1"
	CommandBadgesFactRecordInputSchema   = "sforum.badges.fact.record.input"
	CommandBadgesFactRecordOutputSchema  = "sforum.badges.fact.record.result"
	CommandBadgesFactRecordSchemaVersion = "1"

	// BadgeFactRecordDeniedAuditAction 是域层拒绝的审计 action。
	// 字面量冻结:文档(docs/extensions/badge-plugin-facts.md)、测试与运维查询都按它对齐。
	BadgeFactRecordDeniedAuditAction = "extension.badge_fact_record.denied"
)

badges.fact.record:插件向宿主上报一条「用户维度的事实」。

事实是徽章条件的数据来源,所以这条命令同时是**计数的唯一写口**:插件不能自己 记账(没有可信执行环境),只能通过这里上报,由宿主写 `badge_facts` + 累计计数 并把 `source_extension_id` 记成运行时身份。拒绝必须可追责——域层拒绝会尽力追加 一条审计(见 protocolV2AuditBadgeFactDenied),能力缺失则由共享闸门在事务前拒绝、 **不落审计**(全仓统一,spec §9 Errata 3 第 4 条)。

View Source
const (
	BadgeFactReasonCapabilityDenied  = "capability_denied"
	BadgeFactReasonKeyNotDeclared    = "fact_key_not_declared"
	BadgeFactReasonInvalidUserID     = "invalid_user_id"
	BadgeFactReasonInvalidDelta      = "invalid_delta"
	BadgeFactReasonInvalidOccurredAt = "invalid_occurred_at"
	BadgeFactReasonWriteFailed       = "fact_write_failed"
)

冻结的拒绝原因(spec §9 Errata 3 第 2 条)。SDK/文档/测试逐字对齐这一组; 新增原因必须回到 spec 裁决,不许在实现里就地发明。

View Source
const (
	CommandTopicVisibilitySetID          = "sforum.forum.topic.visibility.set"
	CommandTopicVisibilitySetVersion     = "1"
	CommandTopicVisibilityInputSchemaID  = "sforum.forum.topic.visibility.input"
	CommandTopicVisibilityOutputSchemaID = "sforum.forum.topic.visibility.result"
	CommandTopicVisibilitySchemaVersion  = "1"
)
View Source
const (
	CommandEntitlementsMutateID               = "sforum.entitlements.mutate"
	CommandEntitlementsMutateVersion          = "1"
	CommandEntitlementsMutationInputSchemaID  = "sforum.entitlements.mutation.input"
	CommandEntitlementsMutationOutputSchemaID = "sforum.entitlements.mutation.result"
	CommandEntitlementsMutationSchemaVersion  = "1"
)
View Source
const (
	CommandEventsEmitID            = "sforum.events.emit"
	CommandEventsEmitVersion       = "1"
	CommandEventsEmitInputSchema   = "sforum.events.emit.input"
	CommandEventsEmitOutputSchema  = "sforum.events.emit.result"
	CommandEventsEmitSchemaVersion = "1"

	// ProtocolV2EventsEmitMaxNameLen 与 Manifest 侧的事件名约束保持同一量级。
	ProtocolV2EventsEmitMaxNameLen      = 160
	ProtocolV2EventsEmitMaxPayloadBytes = 64 * 1024
	// ProtocolV2EventsEmitMaxPayloadKeys 防止一个巨大扁平对象把订阅方的
	// hook input 与 delivery 记录一起撑大。
	ProtocolV2EventsEmitMaxPayloadKeys = 64
)

插件发布自身事件的边界。

View Source
const (
	CommandExtensionPluginDisableID           = "sforum.extensions.plugin.disable"
	CommandExtensionPluginDisableVersion      = "1"
	CommandExtensionPluginDisableInputSchema  = "sforum.extensions.plugin.disable.input"
	CommandExtensionPluginDisableOutputSchema = "sforum.extensions.plugin.disable.result"
	CommandExtensionPluginDisableSchemaV1     = "1"

	CommandExtensionSettingsResetID           = "sforum.extensions.settings.reset"
	CommandExtensionSettingsResetVersion      = "1"
	CommandExtensionSettingsResetInputSchema  = "sforum.extensions.settings.reset.input"
	CommandExtensionSettingsResetOutputSchema = "sforum.extensions.settings.reset.result"
	CommandExtensionSettingsResetSchemaV1     = "1"

	CommandExtensionSettingsUpdateID           = "sforum.extensions.settings.update"
	CommandExtensionSettingsUpdateVersion      = "1"
	CommandExtensionSettingsUpdateInputSchema  = "sforum.extensions.settings.update.input"
	CommandExtensionSettingsUpdateOutputSchema = "sforum.extensions.settings.update.result"
	CommandExtensionSettingsUpdateSchemaV1     = "1"

	CommandExtensionSettingsActionID           = "sforum.extensions.settings.action"
	CommandExtensionSettingsActionVersion      = "1"
	CommandExtensionSettingsActionInputSchema  = "sforum.extensions.settings.action.input"
	CommandExtensionSettingsActionOutputSchema = "sforum.extensions.settings.action.result"
	CommandExtensionSettingsActionSchemaV1     = "1"
)
View Source
const (
	CommandIdentityUserStatusSetID          = "sforum.identity.user.status.set"
	CommandIdentityUserStatusSetVersion     = "1"
	CommandIdentityUserStatusInputSchemaID  = "sforum.identity.user.status.input"
	CommandIdentityUserStatusOutputSchemaID = "sforum.identity.user.status.result"
	CommandIdentityUserStatusSchemaVersion  = "1"
)
View Source
const (
	CommandEntityMetaValuesUpsertID       = "sforum.entity_meta.values.upsert"
	CommandEntityMetaValuesUpsertVersion  = "1"
	CommandEntityMetaValuesInputSchemaID  = "sforum.entity_meta.values.input"
	CommandEntityMetaValuesOutputSchemaID = "sforum.entity_meta.values.result"
	CommandEntityMetaValuesSchemaVersion  = "1"
)
View Source
const (
	CommandModerationDecisionSubmitID       = "sforum.moderation.decision.submit"
	CommandModerationDecisionSubmitVersion  = "1"
	CommandModerationDecisionInputSchemaID  = "sforum.moderation.decision.input"
	CommandModerationDecisionOutputSchemaID = "sforum.moderation.decision.result"
	CommandModerationDecisionSchemaVersion  = "1"
)
View Source
const (
	CommandNotificationsEmitID            = "notifications.emit"
	CommandNotificationsEmitVersion       = "1"
	CommandNotificationsEmitInputSchema   = "sforum.notifications.emit.input"
	CommandNotificationsEmitOutputSchema  = "sforum.notifications.emit.result"
	CommandNotificationsEmitSchemaVersion = "1"

	ProtocolV2NotificationEmitMaxRecipients     = 50
	ProtocolV2NotificationEmitMaxPayloadBytes   = 16 * 1024
	ProtocolV2NotificationEmitMaxSchemaBytes    = 64 * 1024
	ProtocolV2NotificationEmitRequestsPerMinute = 60
)
View Source
const (
	ProtocolV2DatabaseOwnSchema = "own_schema"

	ProtocolV2DatabaseString = "string"
	ProtocolV2DatabaseInt64  = "int64"
	ProtocolV2DatabaseNumber = "number"
	ProtocolV2DatabaseBool   = "bool"
)
View Source
const (
	DatabaseTraceAllowed  = QueryTraceAllowed
	DatabaseTraceDenied   = QueryTraceDenied
	DatabaseTraceStale    = QueryTraceStale
	DatabaseTraceError    = QueryTraceError
	DatabaseTraceCancel   = QueryTraceCancel
	DatabaseTraceDeadline = QueryTraceDeadline
)
View Source
const (
	QuerySafeUserByID               = "sforum.core.safe_user.by_id"
	QueryPublicTopicsList           = "sforum.core.public_topics.list"
	QueryPublicTopicByID            = "sforum.core.public_topic.by_id"
	QueryPublicAttachmentByPublicID = "sforum.core.public_attachment.by_public_id"
	QuerySiteStats                  = "sforum.core.site_stats.current"
	QueryPublicCommentsList         = "sforum.core.public_comments.list"
	QuerySafeUserByUsername         = "sforum.core.safe_user.by_username"
	QuerySafeUsersBatch             = "sforum.core.safe_users.batch"
	QueryPublicCategoriesList       = "sforum.core.public_categories.list"
	// QueryPublicReactionsList 是点赞关系的公开读面(谁赞了哪个可见目标)。
	QueryPublicReactionsList = "sforum.core.public_reactions.list"
	// QueryPublicBookmarksList 是公开收藏关系的读面。视图只含 visibility='public'
	// 的行,私密收藏与提醒字段永不出现。
	QueryPublicBookmarksList = "sforum.core.public_bookmarks.list"
	// QueryPublicBadgesList 是启用中徽章目录的公开读面(forum_badges 视图)。
	QueryPublicBadgesList = "sforum.core.public_badges.list"
	// QueryPublicUserBadgesList 是徽章授予关系的公开读面:只含 active 用户 × 启用徽章,
	// granted_by / grant_reason 永不出现。
	QueryPublicUserBadgesList = "sforum.core.public_user_badges.list"
	// QueryPublicUserActivityList 是用户活动统计的公开读面。阅读类指标未采集,
	// 视图不输出,查询也不声明它们。
	QueryPublicUserActivityList = "sforum.core.public_user_activity.list"
	// QueryPublicUserBadgeFactsList 是插件事实累计值的公开读面(forum_user_badge_facts)。
	// 只含 active 用户的 total;delta 行、dedupe_key、来源扩展都不出现。
	QueryPublicUserBadgeFactsList = "sforum.core.public_user_badge_facts.list"
	// QueryPublicTrustLevelCatalogList 是信任等级档位目录的公开读面(M4b-3)。
	// 真源是 options 的 trust.levels 单键 JSON;公开面**不含** rule 与 limits。
	QueryPublicTrustLevelCatalogList = "sforum.core.public_trust_level_catalog.list"
	// QueryPublicUserTrustLevelGet 是单用户当前等级的公开读面(M4b-3)。
	// **现算**(TrustLevels.Evaluate),不读变更账本——账本只是快照,不是权威。
	QueryPublicUserTrustLevelGet = "sforum.core.public_user_trust_level.get"
	// QuerySelfEmail 只由 host 签发的 actor 委派驱动执行;actorless 稳定入口
	// 一律拒绝(见 consent_query_definitions.go)。
	QuerySelfEmail                       = "sforum.core.identity.self_email"
	QueryStableCorePlanVersion           = "1"
	QuerySafeUserResultSchemaID          = "sforum.core.safe_user"
	QueryPublicTopicResultSchemaID       = "sforum.core.public_topic"
	QueryPublicAttachmentSchemaID        = "sforum.core.public_attachment_metadata"
	QuerySiteStatsResultSchemaID         = "sforum.core.site_stats"
	QueryPublicCommentResultSchemaID     = "sforum.core.public_comment"
	QuerySafeUserAvatarSchemaID          = "sforum.core.safe_user_avatar"
	QueryPublicCategorySchemaID          = "sforum.core.public_category"
	QueryPublicReactionSchemaID          = "sforum.core.public_reaction"
	QueryPublicBookmarkSchemaID          = "sforum.core.public_bookmark"
	QueryPublicBadgeSchemaID             = "sforum.core.public_badge"
	QueryPublicUserBadgeSchemaID         = "sforum.core.public_user_badge"
	QueryPublicUserActivitySchemaID      = "sforum.core.public_user_activity"
	QueryPublicUserBadgeFactSchemaID     = "sforum.core.public_user_badge_fact"
	QueryPublicTrustLevelSchemaID        = "sforum.core.public_trust_level"
	QueryPublicTrustLevelCatalogSchemaID = "sforum.core.public_trust_level_catalog"
	QuerySelfEmailSchemaID               = "sforum.core.self_email"
	QueryStableCoreResultSchemaV1        = "1"
	QueryInt64ParameterSchemaID          = "sforum.core.query.int64"
	QueryTextParameterSchemaID           = "sforum.core.query.text"
	QueryStableCoreParameterSchemaV1     = "1"
)
View Source
const BadgeFactRecordPolicyID = "sforum.badges.fact.record@1"

BadgeFactRecordPolicyID 是这条命令的**策略标识**。

注意它和命令 ID 的关系:命令 ID `badges.fact.record` **不带 `@N`**(稳定标识, 版本走 CommandVersion),而 PolicyId **带 `@N`**(策略是版本化契约,审计与 前端按 PolicyId 判定「宿主承诺了什么」)。两者并存不是笔误——把它们「统一」 成同一种写法,要么让命令变成 unknown command,要么让审计丢失策略版本。

View Source
const (
	HostCacheDefaultSlowThreshold = 250 * time.Millisecond
)
View Source
const (
	HostCacheInspectorSchemaVersion = "sforum.cache-inspector@1"
)
View Source
const HostCacheProviderMaximumCallTimeout = 5 * time.Second
View Source
const PluginJobKind = "extension.plugin_job"

PluginJobKind 是 River 上的宿主统一 job kind;真实插件 kind 放在 payload 内。

View Source
const (
	ProtocolV2ActorDelegationAudience = "sforum.host-command.v2"
)
View Source
const (
	ProtocolV2DatabaseDefaultSlowThreshold = ProtocolV2QueryDefaultSlowThreshold
)
View Source
const (
	ProtocolV2QueryDefaultSlowThreshold = time.Second
)
View Source
const (
	ProtocolV2QueryDelegationAudience = "sforum.host-query.v2"
)
View Source
const (
	// ProtocolV2SessionDelegationAudience is distinct from the command and query
	// audiences so a token minted for one capability can never be replayed at
	// another service.
	ProtocolV2SessionDelegationAudience = "sforum.host-session.v2"
)

Variables

View Source
var (
	ErrHostCacheInspectorInvalid  = errors.New("host cache inspector request is invalid")
	ErrHostCacheInspectorConflict = errors.New("host cache registry changed during inspection")
)
View Source
var (
	ErrHostCacheInvalid             = errors.New("host cache request is invalid")
	ErrHostCacheDenied              = errors.New("host cache caller is denied")
	ErrHostCacheScopeRequired       = errors.New("host cache requires Host-attested isolation scope")
	ErrHostCacheStale               = errors.New("host cache runtime or declaration is stale")
	ErrHostCacheProviderUnavailable = errors.New("host cache provider is unavailable")
	ErrHostCacheProviderInvalid     = errors.New("host cache provider resolution is invalid")
	ErrHostCacheConflict            = errors.New("host cache revision conflicts with the stored value")
	ErrHostCachePoisoned            = errors.New("host cache provider returned an invalid value")
	ErrHostCacheLockNotOwned        = errors.New("host cache lock is expired or owned by another caller")
)
View Source
var (
	// ErrPluginJobEnqueueStale 表示调用者已不是当前活动的 exact runtime。
	ErrPluginJobEnqueueStale = errors.New("hostapi: plugin job enqueue runtime is stale")
	// ErrPluginJobEnqueueDraining 表示 runtime 已关闭新的作业入队入口。
	ErrPluginJobEnqueueDraining = errors.New("hostapi: plugin job enqueue runtime is draining")
	// ErrPluginJobEnqueueUnavailable 表示宿主未能执行 runtime admission。
	ErrPluginJobEnqueueUnavailable = errors.New("hostapi: plugin job enqueue admission is unavailable")
)
View Source
var (
	ErrPluginJobLifecycleUnavailable = errors.New("plugin job lifecycle store is unavailable")
	ErrPluginJobLifecycleIsolation   = errors.New("plugin job lifecycle row belongs to another extension")
	ErrPluginJobMigrationPending     = errors.New("plugin job migration ledger entry has no replacement job")
	ErrPluginJobMigrationConflict    = errors.New("plugin job migration ledger entry conflicts with the requested migration")
	ErrPluginJobMigratorUnavailable  = errors.New("plugin job payload migrator is unavailable")
	ErrPluginJobLifecyclePlanDrift   = errors.New("plugin job lifecycle plan changed after preparation")
)
View Source
var (
	ErrProtocolV2SessionDelegationInvalid     = errors.New("hostapi: session delegation is invalid")
	ErrProtocolV2SessionDelegationRetired     = errors.New("hostapi: session delegation was already retired")
	ErrProtocolV2SessionDelegationUnavailable = errors.New("hostapi: session delegation ledger is unavailable")
)
View Source
var (
	// ErrProtocolV2QueryCapabilityDenied 表示精确制品未声明该读取面的能力。
	ErrProtocolV2QueryCapabilityDenied = errors.New("hostapi: query capability is denied")
	// ErrProtocolV2QueryRateLimited 表示 (actor, extension) 超出同意式读取配额。
	ErrProtocolV2QueryRateLimited = errors.New("hostapi: consent query is rate limited")
	// ErrProtocolV2QueryConsentGateUnavailable 表示门控依赖(能力解析/审计/限流)
	// 不可用;此时一律 fail closed,不返回任何数据。
	ErrProtocolV2QueryConsentGateUnavailable = errors.New("hostapi: consent query gate is unavailable")
)
View Source
var (
	// ErrQueryRegistryCoreUnsupported 表示某条 stable Host Query 无法在不发明
	// Manifest 字段或 relation 支持的前提下投影进 Query Registry。
	ErrQueryRegistryCoreUnsupported = errors.New("hostapi: core Query Registry definition is unsupported")
	// ErrQueryRegistryCoreInvalid 表示目录构造输入(例如 cursor secret)无效。
	ErrQueryRegistryCoreInvalid = errors.New("hostapi: core Query Registry catalog is invalid")
)
View Source
var (
	ErrProtocolV2QueryDelegationInvalid   = errors.New("hostapi: query actor delegation is invalid")
	ErrProtocolV2QueryDelegationReplayed  = errors.New("hostapi: query actor delegation was already consumed")
	ErrProtocolV2QueryReplayUnavailable   = errors.New("hostapi: query delegation replay ledger is unavailable")
	ErrProtocolV2QueryActorDenied         = errors.New("hostapi: query actor is denied")
	ErrProtocolV2QueryCallerStale         = errors.New("hostapi: query caller runtime is stale")
	ErrProtocolV2QueryRegistryUnavailable = errors.New("hostapi: Query Registry outlet is unavailable")
)
View Source
var (
	ErrServiceProviderStale                = errors.New("hostapi: service provider runtime is stale")
	ErrServiceProviderDraining             = errors.New("hostapi: service provider runtime is draining")
	ErrServiceProviderAdmissionUnavailable = errors.New("hostapi: service provider admission is unavailable")
)
View Source
var (
	ErrInvalidServiceRegistration = errors.New("invalid service registration")
	ErrInvalidServiceConstraint   = errors.New("invalid service version constraint")
	ErrServiceNotFound            = errors.New("service not found")
)
View Source
var (
	ErrCapabilityDenied = errors.New("hostapi: capability denied")
	ErrInvalidRequest   = errors.New("hostapi: invalid request")
	ErrNotFound         = errors.New("hostapi: not found")
	ErrTimeout          = errors.New("hostapi: timeout")
	ErrUnavailable      = errors.New("hostapi: unavailable")
)

稳定错误码(插件侧可映射)。

View Source
var ErrContentRegistryAdmissionInvalid = errors.New("hostapi: content registry admission is invalid")
View Source
var ErrContentRegistryPermissionDenied = errors.New("hostapi: content registry permission denied")
View Source
var ErrProtocolV2ActorDelegationInvalid = errors.New("hostapi: actor delegation is invalid")
View Source
var ErrProtocolV2AttachmentNotFound = errors.New("hostapi: attachment not found")
View Source
var ErrProtocolV2QueryRuntimeStale = errors.New("Host Query exact runtime identity is stale")
View Source
var ErrProtocolV2SessionSafeMode = errors.New("hostapi: plugin session state is read-only in Safe Mode")

ErrProtocolV2SessionSafeMode is returned to a write while the Host is in Safe Mode. Reads intentionally do not surface it: they miss.

View Source
var ErrServiceRuntimeSetConflict = errors.New("service runtime set changed while publication was prepared")
View Source
var ErrShortcodePolicyProjectionUnavailable = errors.New("hostapi: shortcode policy projection unavailable")
View Source
var ErrShortcodeProjectionActorUnavailable = errors.New("hostapi: shortcode projection actor is unavailable")

Functions

func ContextWithProtocolV2RuntimeIdentity

func ContextWithProtocolV2RuntimeIdentity(ctx context.Context, identity *protocolv2.ExtensionIdentity) context.Context

ContextWithProtocolV2RuntimeIdentity is called only after the runtime-scoped broker has authenticated its token and exact immutable identity. Host API implementations must use this value instead of trusting request protobufs.

func IsProtocolV2ConsentGatedQuery

func IsProtocolV2ConsentGatedQuery(registryQueryID string) bool

IsProtocolV2ConsentGatedQuery 判断一个 **Query Registry query id** 是否指向 consent-gated Host 定义。除这条显式映射外不接受任何命名推断。

func IsShortcodeProjectionActorPolicy

func IsShortcodeProjectionActorPolicy(value string) bool

IsShortcodeProjectionActorPolicy identifies the sealed Host-only decision policy. It is not a grantable RBAC permission and must never enter role data.

func NewProtocolV2QueryRegistryProviderResolver

func NewProtocolV2QueryRegistryProviderResolver(
	runtime ProtocolV2QueryRuntime,
	bindings []QueryRegistryProtocolV2Binding,
) (queryregistry.ExecutableProviderResolver, error)

NewProtocolV2QueryRegistryProviderResolver reuses the production HostAPI v2 allowlisted definitions and executor. Authority remains owned by QueryRegistry permission/release checks; this adapter therefore accepts only sealed Core plans and never acts as a plugin-to-plugin transport.

func NewQueryRegistryCoreCostPolicy

func NewQueryRegistryCoreCostPolicy() queryregistry.CostPolicy

NewQueryRegistryCoreCostPolicy returns the deterministic Host-owned cost policy with conservative weights and absolute bounds.

func NewQueryRegistryCoreCursorCodec

func NewQueryRegistryCoreCursorCodec(secret []byte) (queryregistry.CursorCodec, error)

NewQueryRegistryCoreCursorCodec wraps NewHMACCursorCodec with caller-supplied secret material. This package never invents or stores the secret.

func NewQueryRegistryTraceAdapter

func NewQueryRegistryTraceAdapter(sink QueryTraceSink) queryregistry.ExecutionTraceSink

NewQueryRegistryTraceAdapter lets the execution slice share the existing Host Query structured trace sink without exposing payloads or cache material.

func ProtocolV2CommandActorUserID

func ProtocolV2CommandActorUserID(ctx context.Context) (int64, bool)

ProtocolV2CommandActorUserID returns only the Host-verified actor installed by the command engine. RequestContext.actor is never consulted.

func ProtocolV2RuntimeIdentityFromContext

func ProtocolV2RuntimeIdentityFromContext(ctx context.Context) *protocolv2.ExtensionIdentity

ProtocolV2RuntimeIdentityFromContext returns a clone of the broker-attested identity. Absence means the call did not pass through a runtime binding.

func ShortcodeProjectionQueryIDs

func ShortcodeProjectionQueryIDs() []string

ShortcodeProjectionQueryIDs is the complete frozen M4 grant set. Returning a copy prevents later milestones from mutating the Host-owned allowlist.

Types

type CapabilitySource

type CapabilitySource interface {
	// CapabilitiesFor 返回启用插件的有效能力集合。
	CapabilitiesFor(ctx context.Context, extensionID string) (capabilities.Set, error)
	// DeclaredJobKinds 返回插件 manifest 中声明的 job names。
	DeclaredJobKinds(ctx context.Context, extensionID string) ([]string, error)
}

CapabilitySource 解析扩展当前授予的能力。

type Client

type Client struct {
	BaseURL     string
	Token       string
	ExtensionID string
	HTTP        *http.Client
}

Client 是插件侧最小 Host API 客户端(也可作 SDK stub)。

func ClientFromEnv

func ClientFromEnv() (*Client, error)

ClientFromEnv 从插件进程环境变量构造客户端。

func (*Client) Call

func (c *Client) Call(ctx context.Context, method string, payload map[string]any) (Response, error)

Call 发起一次 Host API 调用。

type Config

type Config struct {
	Capabilities     CapabilitySource
	Permissions      PermissionChecker
	Settings         SettingsStore
	Jobs             JobEnqueuer
	JobAdmission     PluginJobEnqueueAdmission
	ServiceAdmission ServiceProviderAdmission
	Users            UserReader
	Inventory        ExtensionInventoryReader
	Auditor          audit.Writer
}

Config 注入依赖;未注入的可选面在对应方法上返回 unavailable。

type ContentRegistryAdmission

type ContentRegistryAdmission struct {
	// contains filtered or unexported fields
}

func (*ContentRegistryAdmission) AcquireContentExecution

type ContentRegistryAdmissionBackend

type ContentRegistryAdmissionBackend interface {
	AcquireContentRegistryRuntime(context.Context, ContentRegistryRuntimeIdentity) (ContentRegistryRuntimeLease, error)
}

type ContentRegistryPermissionBackend

type ContentRegistryPermissionBackend interface {
	AuthorizeContentRegistry(context.Context, ContentRegistryPermissionDecision) error
}

ContentRegistryPermissionBackend must derive the actor from Host request state. The content executor supplies resource/contract facts, never grants.

type ContentRegistryPermissionDecision

type ContentRegistryPermissionDecision struct {
	TargetID                string
	TargetContractVersion   string
	TargetSchema            string
	TargetExtensionID       string
	TargetExtensionVersion  string
	TargetPackageDigest     string
	TargetVersionID         int64
	TargetRuntimeInstanceID string
	TargetCore              bool
	ContentID               string
	ContractVersion         string
	Schema                  string
	Action                  string
	Operation               string
	ExtensionID             string
	ExtensionVersion        string
	PackageDigest           string
	VersionID               int64
	RuntimeInstanceID       string
	ResourceID              string
	Locale                  string
	Scope                   string
}

type ContentRegistryPermissionRecheck

type ContentRegistryPermissionRecheck struct {
	// contains filtered or unexported fields
}

func (*ContentRegistryPermissionRecheck) AuthorizeContent

type ContentRegistryRuntimeIdentity

type ContentRegistryRuntimeIdentity struct {
	TargetID                string
	TargetContractVersion   string
	TargetSchema            string
	TargetExtensionID       string
	TargetExtensionVersion  string
	TargetPackageDigest     string
	TargetVersionID         int64
	TargetRuntimeInstanceID string
	TargetCore              bool
	ExtensionID             string
	ExtensionVersion        string
	PackageDigest           string
	VersionID               int64
	RuntimeInstanceID       string
	ContentID               string
	ContractVersion         string
	Kind                    string
	Schema                  string
	HandlerReference        string
	RendererReference       string
	MigrationReference      string
	Action                  string
	Operation               string
}

ContentRegistryRuntimeIdentity is the cycle-free HostAPI projection that the production Extensions adapter must resolve against Manager.AcquireRuntimeCall. Until that adapter dispatches HandlerReference through the returned exact lease, the in-process Content executor remains a non-production leaf.

type ContentRegistryRuntimeLease

type ContentRegistryRuntimeLease interface {
	Context() context.Context
	Release()
}

type DatabaseTrace

type DatabaseTrace struct {
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	OperationID      string
	StatementVersion string
	OperationKind    string
	ShapeDigest      string
	Duration         time.Duration
	Rows             int
	AffectedRows     uint64
	Outcome          DatabaseTraceOutcome
	Slow             bool
}

DatabaseTrace 只包含有界的宿主元数据。SQL、参数、结果、凭据、幂等键和错误文本 均不得进入 trace sink。

type DatabaseTraceOutcome

type DatabaseTraceOutcome = QueryTraceOutcome

type DatabaseTraceSink

type DatabaseTraceSink interface {
	RecordDatabaseTrace(DatabaseTrace)
}

func NewSlogDatabaseTraceSink

func NewSlogDatabaseTraceSink(logger *slog.Logger) DatabaseTraceSink

type ExactHostCacheProviderResolver

type ExactHostCacheProviderResolver struct {
	// contains filtered or unexported fields
}

ExactHostCacheProviderResolver converts one immutable provider selection into a backend that can invoke only that exact selection. HostCacheService still owns Safe Mode, Core fallback, and both owner/provider admission leases.

func (*ExactHostCacheProviderResolver) ResolveHostCacheProvider

func (*ExactHostCacheProviderResolver) ValidateHostCacheProvider

func (r *ExactHostCacheProviderResolver) ValidateHostCacheProvider(
	ctx context.Context,
	request HostCacheProviderRequest,
	resolution HostCacheProviderResolution,
	candidate HostCacheProviderCandidate,
) error

type ExtensionInventoryReader

type ExtensionInventoryReader interface {
	// ListRedactedInventory 返回不含 packagePath/settings/trust/凭证的清单行。
	ListRedactedInventory(ctx context.Context) ([]map[string]any, error)
}

ExtensionInventoryReader 提供去敏扩展清单(extensions.read)。

type Gateway

type Gateway struct {
	// contains filtered or unexported fields
}

Gateway 在 loopback 上暴露 Host API,供插件子进程调用(F2.2)。 每个已启动插件持有独立 token;请求必须带 X-SForum-Extension-Id 与 Bearer token。

func NewGateway

func NewGateway(service *Service) *Gateway

NewGateway 创建未启动的网关;Start 后才监听。

func (*Gateway) AcquireProtocolV2ServiceRuntimeSet

func (g *Gateway) AcquireProtocolV2ServiceRuntimeSet(publications []ServiceRuntimePublication) (*ServiceRuntimeSetLease, error)

AcquireProtocolV2ServiceRuntimeSet pins a verified complete graph against lifecycle writers until the caller releases the lease.

func (*Gateway) AcquireProtocolV2ServiceRuntimeSetContext

func (g *Gateway) AcquireProtocolV2ServiceRuntimeSetContext(ctx context.Context, publications []ServiceRuntimePublication) (*ServiceRuntimeSetLease, error)

AcquireProtocolV2ServiceRuntimeSetContext is the cancellable form used by coordinated runtime-set transitions.

func (*Gateway) BaseURL

func (g *Gateway) BaseURL() string

BaseURL 返回 loopback 根地址。

func (*Gateway) BindCommandCapabilitySource

func (g *Gateway) BindCommandCapabilitySource(source CapabilitySource)

BindCommandCapabilitySource 注入进程能力源,供 extensions.manage 等命令门禁使用。 可在 catalog 冻结后调用,仅替换能力解析依赖,不改命令集合。

func (*Gateway) BindProtocolV2CacheService

func (g *Gateway) BindProtocolV2CacheService(server *ProtocolV2CacheServiceServer) error

BindProtocolV2CacheService installs the production cache boundary before any plugin broker is registered. Each broker retains this exact server pointer for its lifetime; changing cache contracts requires a new Gateway boot.

func (*Gateway) BindProtocolV2CommandRuntime

func (g *Gateway) BindProtocolV2CommandRuntime(runtime ProtocolV2CommandRuntime) error

BindProtocolV2CommandRuntime installs one immutable Host-owned command catalog. RegisterProtocolV2 freezes the catalog; replacement then requires a new Gateway/server boot so running brokers never observe contract drift.

func (*Gateway) BindProtocolV2DatabaseRuntime

func (g *Gateway) BindProtocolV2DatabaseRuntime(runtime ProtocolV2DatabaseRuntime) error

BindProtocolV2DatabaseRuntime installs one exact-artifact statement catalog. Broker registration freezes it so SQL and authority bindings cannot drift under an already-running plugin process.

func (*Gateway) BindProtocolV2FileService

func (g *Gateway) BindProtocolV2FileService(server *ProtocolV2FileServiceServer) error

BindProtocolV2FileService installs the production Plugin Files boundary.

func (*Gateway) BindProtocolV2HttpService

func (g *Gateway) BindProtocolV2HttpService(server *ProtocolV2HttpServiceServer) error

BindProtocolV2HttpService installs the production Host HTTP boundary.

func (*Gateway) BindProtocolV2ProviderBroker

func (g *Gateway) BindProtocolV2ProviderBroker(provider ProtocolV2ProviderBroker) error

func (*Gateway) BindProtocolV2QueryRegistryService

func (g *Gateway) BindProtocolV2QueryRegistryService(service *ProtocolV2QueryRegistryService) error

BindProtocolV2QueryRegistryService installs the actor-delegated Query Registry outlet exactly once. Broker registration freezes the pointer for the Gateway lifetime; bootstrap must construct the complete execution runtime before binding it.

func (*Gateway) BindProtocolV2QueryRuntime

func (g *Gateway) BindProtocolV2QueryRuntime(runtime ProtocolV2QueryRuntime) error

BindProtocolV2QueryRuntime installs the immutable stable-query catalog once. Broker registration freezes the snapshot for the lifetime of this Gateway.

func (*Gateway) BindProtocolV2SecretService

func (g *Gateway) BindProtocolV2SecretService(server *ProtocolV2SecretServiceServer) error

BindProtocolV2SecretService installs the production Secret Store boundary.

func (*Gateway) BindProtocolV2SessionService

func (g *Gateway) BindProtocolV2SessionService(server *ProtocolV2SessionServiceServer) error

BindProtocolV2SessionService installs the S9 plugin session-state boundary before any plugin broker is registered, so every broker for this boot serves the same session contract.

func (*Gateway) Close

func (g *Gateway) Close() error

Close 停止监听。

func (*Gateway) IssueProtocolV2ActorDelegations

func (g *Gateway) IssueProtocolV2ActorDelegations(
	ctx context.Context,
	request ProtocolV2ActorDelegationBundleRequest,
) ([]ProtocolV2ActorDelegationGrant, error)

IssueProtocolV2ActorDelegations derives command scopes from the immutable Host catalog instead of duplicating them in a route, controller, or manifest.

func (*Gateway) IssueProtocolV2QueryActorDelegation

func (g *Gateway) IssueProtocolV2QueryActorDelegation(
	ctx context.Context,
	request ProtocolV2QueryActorDelegationRequest,
) (ProtocolV2QueryActorDelegationGrant, error)

IssueProtocolV2QueryActorDelegation exposes only the Host-side issuer. The signed token is delivered to one plugin invocation and can be consumed once.

func (*Gateway) IssueProtocolV2ShortcodeProjectionDelegations

func (g *Gateway) IssueProtocolV2ShortcodeProjectionDelegations(
	ctx context.Context,
	request ProtocolV2ShortcodeProjectionDelegationRequest,
) ([]ProtocolV2QueryActorDelegationGrant, error)

func (*Gateway) MintProtocolV2SessionDelegation

func (g *Gateway) MintProtocolV2SessionDelegation(
	ctx context.Context,
	identity *protocolv2.ExtensionIdentity,
	scope ProtocolV2SessionScope,
) (string, error)

MintProtocolV2SessionDelegation 让 Gateway 本身成为 S9 会话委派的签发者。

生产装配把裸 Gateway 作为 `HostAPIRegistrar` 传给 ProtocolStarter (bootstrap/app.go),protocolV2Client 通过类型断言解析 S9 签发方;缺这两个 方法时带会话范围的宿主发起调用会直接失败。语义与延迟策略照旧:只在绑定了 会话服务的 Gateway 上可用,未绑定时 fail closed,不静默降级。

func (*Gateway) PrepareProtocolV2ServiceRuntimeSet

func (g *Gateway) PrepareProtocolV2ServiceRuntimeSet(publications []ServiceRuntimePublication) (*ServiceRuntimeSetTransaction, error)

PrepareProtocolV2ServiceRuntimeSet validates a complete desired runtime graph without changing reader visibility. Commit publishes the graph once.

func (*Gateway) ProtocolV2ActorDelegationIssuer

func (g *Gateway) ProtocolV2ActorDelegationIssuer() ProtocolV2ActorDelegationIssuer

ProtocolV2ActorDelegationIssuer exposes only the boot-scoped issuer used by Host-owned route/admin adapters. It is nil until a delegated command catalog is bound and never crosses the plugin transport boundary.

func (*Gateway) ProtocolV2ServiceRegistry

func (g *Gateway) ProtocolV2ServiceRegistry() *ServiceRegistry

ProtocolV2ServiceRegistry exposes the shared immutable-snapshot registry to runtime assembly and host-owned inspectors.

func (*Gateway) ProtocolV2ServiceRuntimeSetMatches

func (g *Gateway) ProtocolV2ServiceRuntimeSetMatches(publications []ServiceRuntimePublication) (bool, error)

ProtocolV2ServiceRuntimeSetMatches verifies exact complete-set visibility without incrementing discovery revisions.

func (*Gateway) PublishProtocolV2DatabaseRuntime

func (g *Gateway) PublishProtocolV2DatabaseRuntime(runtime ProtocolV2DatabaseRuntime) error

PublishProtocolV2DatabaseRuntime replaces the snapshot used only by future broker registrations. Already-registered brokers retain their immutable engine pointer, so an upgrade cannot change SQL beneath an active process.

func (*Gateway) PublishProtocolV2ServiceRuntime

func (g *Gateway) PublishProtocolV2ServiceRuntime(publication ServiceRuntimePublication) error

PublishProtocolV2ServiceRuntime atomically exposes one exact runtime as both a service provider and a dependency-authorized caller.

func (*Gateway) RegisterExtension

func (g *Gateway) RegisterExtension(extensionID string) (token string, env []string, err error)

RegisterExtension 为插件签发 token,返回应注入子进程的环境变量。

func (*Gateway) RegisterProtocolV2

func (g *Gateway) RegisterProtocolV2(server grpc.ServiceRegistrar)

RegisterProtocolV2 exposes typed Host services only on the caller's runtime-bound go-plugin broker server.

func (*Gateway) ReplaceProtocolV2Services

func (g *Gateway) ReplaceProtocolV2Services(extensionID string, registrations []ServiceRegistration) error

ReplaceProtocolV2Services atomically publishes one runtime's complete handshake service declaration set.

func (*Gateway) RetireProtocolV2SessionDelegation

func (g *Gateway) RetireProtocolV2SessionDelegation(token string) error

RetireProtocolV2SessionDelegation 在调用结算时收回签发台账记录(幂等)。

func (*Gateway) Start

func (g *Gateway) Start() error

Start 绑定 127.0.0.1:0 并开始服务。

func (*Gateway) UnregisterExtension

func (g *Gateway) UnregisterExtension(extensionID string)

UnregisterExtension 撤销 token。

func (*Gateway) UnregisterProtocolV2ServiceInstance

func (g *Gateway) UnregisterProtocolV2ServiceInstance(extensionID, instanceID string) bool

UnregisterProtocolV2ServiceInstance removes services only when the current registry snapshot still belongs to the stopping runtime instance.

func (*Gateway) UnregisterProtocolV2Services

func (g *Gateway) UnregisterProtocolV2Services(extensionID string)

UnregisterProtocolV2Services removes all services owned by one runtime.

type HostCacheCaller

type HostCacheCaller struct {
	ExtensionID       string
	ExtensionVersion  string
	ArtifactDigest    string
	VersionID         int64
	RuntimeInstanceID string
	Attested          bool
	Core              bool
	// contains filtered or unexported fields
}

type HostCacheDeleteRequest

type HostCacheDeleteRequest struct {
	HostCacheRequestBase
	Key string
}

type HostCacheGetRequest

type HostCacheGetRequest struct {
	HostCacheRequestBase
	Key    string
	Schema HostCacheSchema
}

type HostCacheGetResult

type HostCacheGetResult struct {
	Found    bool
	Value    []byte
	Revision string
}

type HostCacheIncrementRequest

type HostCacheIncrementRequest struct {
	HostCacheRequestBase
	Key   string
	Delta int64
	TTL   time.Duration
}

type HostCacheInspectionArtifact

type HostCacheInspectionArtifact struct {
	ExtensionID       string `json:"extensionId"`
	ExtensionVersion  string `json:"extensionVersion"`
	PackageDigest     string `json:"packageDigest"`
	VersionID         int64  `json:"versionId,omitempty"`
	RuntimeInstanceID string `json:"runtimeInstanceId,omitempty"`
	Core              bool   `json:"core,omitempty"`
}

type HostCacheInspectionContribution

type HostCacheInspectionContribution struct {
	HostCacheInspectionDeclaration
	Artifact HostCacheInspectionArtifact `json:"artifact"`
}

type HostCacheInspectionDeclaration

type HostCacheInspectionDeclaration struct {
	ID              string   `json:"id"`
	ContractVersion string   `json:"contractVersion"`
	Namespace       string   `json:"namespace"`
	Policy          string   `json:"policy"`
	Provider        string   `json:"provider,omitempty"`
	Invalidators    []string `json:"invalidators,omitempty"`
}

type HostCacheInspectionMetrics

type HostCacheInspectionMetrics struct {
	Operation             string `json:"operation,omitempty"`
	Samples               uint64 `json:"samples"`
	Hits                  uint64 `json:"hits"`
	Misses                uint64 `json:"misses"`
	Allowed               uint64 `json:"allowed"`
	Denied                uint64 `json:"denied"`
	Stale                 uint64 `json:"stale"`
	Conflicts             uint64 `json:"conflicts"`
	Errors                uint64 `json:"errors"`
	Canceled              uint64 `json:"canceled"`
	Deadlines             uint64 `json:"deadlines"`
	Slow                  uint64 `json:"slow"`
	Affected              uint64 `json:"affected"`
	TotalDurationMicros   uint64 `json:"totalDurationMicros"`
	AverageDurationMicros uint64 `json:"averageDurationMicros"`
	P95DurationMicros     uint64 `json:"p95DurationMicros"`
}

type HostCacheInspectionPublication

type HostCacheInspectionPublication struct {
	Artifact HostCacheInspectionArtifact      `json:"artifact"`
	Caches   []HostCacheInspectionDeclaration `json:"caches"`
}

type HostCacheInspectionRegistrySnapshot

type HostCacheInspectionRegistrySnapshot struct {
	SchemaVersion string                            `json:"schemaVersion"`
	Revision      uint64                            `json:"revision"`
	Digest        string                            `json:"digest"`
	SafeMode      bool                              `json:"safeMode"`
	Publications  []HostCacheInspectionPublication  `json:"publications"`
	Caches        []HostCacheInspectionContribution `json:"caches"`
}

HostCacheInspectionRegistrySnapshot is a redacted Registry disclosure. It deliberately has no field capable of carrying cache tag names.

type HostCacheInspectionSnapshot

type HostCacheInspectionSnapshot struct {
	SchemaVersion   string                              `json:"schemaVersion"`
	Registry        HostCacheInspectionRegistrySnapshot `json:"registry"`
	RetainedFrom    uint64                              `json:"retainedFromSequence,omitempty"`
	RetainedThrough uint64                              `json:"retainedThroughSequence,omitempty"`
	Metrics         HostCacheInspectionMetrics          `json:"metrics"`
	Operations      []HostCacheInspectionMetrics        `json:"operations"`
	Traces          []HostCacheInspectionTrace          `json:"traces"`
	Invalidations   []HostCacheInspectionTrace          `json:"invalidations"`
}

type HostCacheInspectionTrace

type HostCacheInspectionTrace struct {
	Sequence          uint64                `json:"sequence"`
	ExtensionID       string                `json:"extensionId,omitempty"`
	ExtensionVersion  string                `json:"extensionVersion,omitempty"`
	ArtifactDigest    string                `json:"artifactDigest,omitempty"`
	RuntimeInstanceID string                `json:"runtimeInstanceId,omitempty"`
	VersionID         int64                 `json:"versionId,omitempty"`
	CacheID           string                `json:"cacheId,omitempty"`
	ContractVersion   string                `json:"contractVersion,omitempty"`
	RegistryRevision  uint64                `json:"registryRevision,omitempty"`
	RegistryCurrent   bool                  `json:"registryCurrent"`
	ProviderRevision  uint64                `json:"providerRevision,omitempty"`
	ProviderID        string                `json:"providerId,omitempty"`
	ProviderExtension string                `json:"providerExtension,omitempty"`
	ProviderArtifact  string                `json:"providerArtifact,omitempty"`
	ProviderRuntime   string                `json:"providerRuntime,omitempty"`
	ProviderVersionID int64                 `json:"providerVersionId,omitempty"`
	Operation         string                `json:"operation"`
	TagDigest         string                `json:"tagDigest,omitempty"`
	TagCount          int                   `json:"tagCount,omitempty"`
	InvalidatorID     string                `json:"invalidatorId,omitempty"`
	Outcome           HostCacheTraceOutcome `json:"outcome"`
	DurationMicros    uint64                `json:"durationMicros"`
	Attempts          int                   `json:"attempts,omitempty"`
	Hit               bool                  `json:"hit,omitempty"`
	Affected          uint64                `json:"affected,omitempty"`
	Slow              bool                  `json:"slow,omitempty"`
}

HostCacheInspectionTrace is the metadata-only public view of one operation. Cache keys, values, tag names, lock tokens, and request payloads never enter it.

type HostCacheInspector

type HostCacheInspector struct {
	// contains filtered or unexported fields
}

func NewHostCacheInspector

func NewHostCacheInspector(limit int) *HostCacheInspector

func (*HostCacheInspector) Inspect

Inspect returns a revision-consistent Registry and trace snapshot. Traces are newest-first; metrics cover the complete retained ring rather than the page.

func (*HostCacheInspector) RecordHostCacheTrace

func (i *HostCacheInspector) RecordHostCacheTrace(trace HostCacheTrace)

func (*HostCacheInspector) Snapshot

func (i *HostCacheInspector) Snapshot() []HostCacheTrace

type HostCacheInvalidateTagsRequest

type HostCacheInvalidateTagsRequest struct {
	HostCacheRequestBase
	Tags []string
}

type HostCacheInvalidatorRequest

type HostCacheInvalidatorRequest struct {
	HostCacheRequestBase
	InvalidatorID string
}

type HostCacheLock

type HostCacheLock struct {
	// contains filtered or unexported fields
}

func (*HostCacheLock) Release

func (l *HostCacheLock) Release(ctx context.Context) (err error)

func (*HostCacheLock) Renew

func (l *HostCacheLock) Renew(ctx context.Context, ttl time.Duration) (err error)

type HostCacheLockRequest

type HostCacheLockRequest struct {
	HostCacheRequestBase
	Key string
	TTL time.Duration
}

type HostCacheProviderArtifact

type HostCacheProviderArtifact struct {
	ExtensionID       string
	ExtensionVersion  string
	ArtifactDigest    string
	VersionID         int64
	RuntimeInstanceID string
}

HostCacheProviderArtifact is the exact executable artifact selected for one cache provider. VersionID keeps the durable extension-version row in the identity; RuntimeInstanceID keeps one physical process in the identity.

type HostCacheProviderBinding

type HostCacheProviderBinding struct {
	SelectionRevision uint64
	ProviderID        string
	ProviderContract  string
	ProviderArtifact  HostCacheProviderArtifact
	CacheID           string
	CacheContract     string
	CacheOwner        cacheregistry.Artifact
	CallTimeout       time.Duration
}

HostCacheProviderBinding is immutable input to every remote backend call. The remote transport must not resolve a provider again: doing so could send a mutation to a newer process after the Host admitted the selected process.

type HostCacheProviderCandidate

type HostCacheProviderCandidate struct {
	ProviderID       string
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	VersionID        int64
	RuntimeInstance  string
	Core             bool
	Backend          HostCacheBackend
}

type HostCacheProviderRemote

HostCacheProviderRemote is the semantic boundary for an exact Protocol V2 cache provider. No implementation is supplied until the cache.provider wire schemas are frozen. Implementations must honor ctx cancellation and must use binding as-is instead of entering provider discovery again.

type HostCacheProviderRequest

type HostCacheProviderRequest struct {
	DeclaredProvider string
	CacheID          string
	ContractVersion  string
	Owner            cacheregistry.Artifact
	SafeMode         bool
}

type HostCacheProviderResolution

type HostCacheProviderResolution struct {
	Revision   uint64
	Fallback   string
	Candidates []HostCacheProviderCandidate
}

type HostCacheProviderResolver

type HostCacheProviderResolver interface {
	ResolveHostCacheProvider(context.Context, HostCacheProviderRequest) (HostCacheProviderResolution, error)
	ValidateHostCacheProvider(context.Context, HostCacheProviderRequest, HostCacheProviderResolution, HostCacheProviderCandidate) error
}

HostCacheProviderResolver adapts the existing durable provider-slot selection layer. Validate closes the selection/admission TOCTOU before a runtime lease is entered; that lease pins the in-flight provider call.

type HostCacheProviderSelection

type HostCacheProviderSelection struct {
	Binding  HostCacheProviderBinding
	Fallback string
}

type HostCacheProviderSelectionSource

type HostCacheProviderSelectionSource interface {
	ResolveHostCacheProviderSelection(context.Context, HostCacheProviderRequest) (HostCacheProviderSelection, error)
	ValidateHostCacheProviderSelection(context.Context, HostCacheProviderRequest, HostCacheProviderSelection) error
}

HostCacheProviderSelectionSource adapts the durable provider selection and immutable runtime catalog. Validate must compare the full selection, including both artifact identities and the source revision.

type HostCacheRememberRequest

type HostCacheRememberRequest struct {
	HostCacheSetRequest
	LockTTL time.Duration
	Wait    time.Duration
	Load    func(context.Context) ([]byte, error)
}

type HostCacheRequestBase

type HostCacheRequestBase struct {
	Caller    HostCacheCaller
	CacheID   string
	Namespace string
	Scope     HostCacheScope
}

type HostCacheSchema

type HostCacheSchema struct {
	ID      string
	Version string
}

type HostCacheScope

type HostCacheScope struct {
	ActorFingerprint      string
	PermissionFingerprint string
	Locale                string
}

type HostCacheService

type HostCacheService struct {
	// contains filtered or unexported fields
}

func NewHostCacheService

func NewHostCacheService(
	registry *cacheregistry.Registry,
	core HostCacheBackend,
	resolver HostCacheProviderResolver,
	options ...HostCacheServiceOption,
) (*HostCacheService, error)

func (*HostCacheService) AcquireLock

func (s *HostCacheService) AcquireLock(
	ctx context.Context,
	request HostCacheLockRequest,
) (lock *HostCacheLock, acquired bool, err error)

func (*HostCacheService) Delete

func (s *HostCacheService) Delete(ctx context.Context, request HostCacheDeleteRequest) (deleted bool, err error)

func (*HostCacheService) Get

func (s *HostCacheService) Get(ctx context.Context, request HostCacheGetRequest) (result HostCacheGetResult, err error)

func (*HostCacheService) Increment

func (s *HostCacheService) Increment(ctx context.Context, request HostCacheIncrementRequest) (value int64, err error)

func (*HostCacheService) InvalidateDeclared

func (s *HostCacheService) InvalidateDeclared(
	ctx context.Context,
	request HostCacheInvalidatorRequest,
) (invalidated uint64, err error)

InvalidateDeclared executes one declaration-bound invalidator against every tag owned by that cache contract. Event adapters remain Host-owned: callers cannot supply physical tags or use an invalidator declared by another cache.

func (*HostCacheService) InvalidateTags

func (s *HostCacheService) InvalidateTags(
	ctx context.Context,
	request HostCacheInvalidateTagsRequest,
) (invalidated uint64, err error)

func (*HostCacheService) Remember

func (s *HostCacheService) Remember(ctx context.Context, request HostCacheRememberRequest) (result HostCacheGetResult, err error)

func (*HostCacheService) Set

func (s *HostCacheService) Set(ctx context.Context, request HostCacheSetRequest) (revision string, err error)

type HostCacheServiceOption

type HostCacheServiceOption interface {
	// contains filtered or unexported methods
}

func WithHostCacheInstallationID

func WithHostCacheInstallationID(installationID string) HostCacheServiceOption

WithHostCacheInstallationID supplies the deployment-specific cache boundary. The raw id is never placed in Redis keys; only its SHA-256 digest is used.

func WithHostCacheRuntimeAdmission

func WithHostCacheRuntimeAdmission(admission ServiceProviderAdmission) HostCacheServiceOption

WithHostCacheRuntimeAdmission binds every plugin-owned operation and every executable provider call to the existing exact-instance runtime gate.

func WithHostCacheTraceSink

func WithHostCacheTraceSink(sink HostCacheTraceSink) HostCacheServiceOption

type HostCacheSetRequest

type HostCacheSetRequest struct {
	HostCacheRequestBase
	Key              string
	Schema           HostCacheSchema
	Value            []byte
	TTL              time.Duration
	Tags             []string
	ExpectedRevision string
}

type HostCacheStoredValue

type HostCacheStoredValue struct {
	Value         []byte   `json:"value"`
	SchemaID      string   `json:"schemaId"`
	SchemaVersion string   `json:"schemaVersion"`
	Revision      string   `json:"revision"`
	Tags          []string `json:"tags,omitempty"`
}

HostCacheStoredValue is the provider-neutral value envelope. Tags are Host-derived physical tag keys; callers never supply them directly.

type HostCacheTrace

type HostCacheTrace struct {
	Sequence          uint64
	ExtensionID       string
	ExtensionVersion  string
	ArtifactDigest    string
	RuntimeInstanceID string
	VersionID         int64
	CacheID           string
	ContractVersion   string
	RegistryRevision  uint64
	ProviderRevision  uint64
	ProviderID        string
	ProviderExtension string
	ProviderArtifact  string
	ProviderRuntime   string
	ProviderVersionID int64
	Operation         string
	TagDigest         string
	TagCount          int
	InvalidatorID     string
	Outcome           HostCacheTraceOutcome
	Duration          time.Duration
	Attempts          int
	Hit               bool
	Affected          uint64
	Slow              bool
}

HostCacheTrace contains only bounded Host-owned attribution. User keys, values, tag names, lock tokens, request payloads, and error strings are never recorded.

type HostCacheTraceOutcome

type HostCacheTraceOutcome string
const (
	HostCacheTraceHit      HostCacheTraceOutcome = "hit"
	HostCacheTraceMiss     HostCacheTraceOutcome = "miss"
	HostCacheTraceAllowed  HostCacheTraceOutcome = "allowed"
	HostCacheTraceDenied   HostCacheTraceOutcome = "denied"
	HostCacheTraceStale    HostCacheTraceOutcome = "stale"
	HostCacheTraceConflict HostCacheTraceOutcome = "conflict"
	HostCacheTraceError    HostCacheTraceOutcome = "error"
	HostCacheTraceCancel   HostCacheTraceOutcome = "cancel"
	HostCacheTraceDeadline HostCacheTraceOutcome = "deadline"
)

type HostCacheTraceSink

type HostCacheTraceSink interface {
	RecordHostCacheTrace(HostCacheTrace)
}

func NewMultiHostCacheTraceSink

func NewMultiHostCacheTraceSink(sinks ...HostCacheTraceSink) HostCacheTraceSink

func NewSlogHostCacheTraceSink

func NewSlogHostCacheTraceSink(logger *slog.Logger) HostCacheTraceSink

type HostRedisCacheBackend

type HostRedisCacheBackend struct {
	// contains filtered or unexported fields
}

HostRedisCacheBackend uses the shared production go-redis client. The caller owns the client lifecycle, matching Support/Cache.RedisCache.

func NewHostRedisCacheBackend

func NewHostRedisCacheBackend(client *redis.Client) (*HostRedisCacheBackend, error)

func (*HostRedisCacheBackend) AcquireLock

func (b *HostRedisCacheBackend) AcquireLock(
	ctx context.Context,
	key string,
	owner string,
	ttl time.Duration,
) (bool, error)

func (*HostRedisCacheBackend) Delete

func (b *HostRedisCacheBackend) Delete(ctx context.Context, key, tagPrefix string) (bool, error)

func (*HostRedisCacheBackend) Get

func (*HostRedisCacheBackend) Increment

func (b *HostRedisCacheBackend) Increment(
	ctx context.Context,
	key string,
	delta int64,
	ttl time.Duration,
) (int64, error)

func (*HostRedisCacheBackend) InvalidateTags

func (b *HostRedisCacheBackend) InvalidateTags(
	ctx context.Context,
	tags []string,
	tagPrefix string,
) (uint64, error)

func (*HostRedisCacheBackend) ReleaseLock

func (b *HostRedisCacheBackend) ReleaseLock(ctx context.Context, key, owner string) (bool, error)

func (*HostRedisCacheBackend) RenewLock

func (b *HostRedisCacheBackend) RenewLock(
	ctx context.Context,
	key string,
	owner string,
	ttl time.Duration,
) (bool, error)

func (*HostRedisCacheBackend) Set

func (b *HostRedisCacheBackend) Set(
	ctx context.Context,
	key string,
	value HostCacheStoredValue,
	ttl time.Duration,
	expectedRevision string,
	tagPrefix string,
) error

func (*HostRedisCacheBackend) SetAndReleaseLock

func (b *HostRedisCacheBackend) SetAndReleaseLock(
	ctx context.Context,
	key string,
	value HostCacheStoredValue,
	ttl time.Duration,
	expectedRevision string,
	tagPrefix string,
	lockKey string,
	owner string,
) error

type JobEnqueuer

type JobEnqueuer interface {
	// EnqueuePluginJob 仅允许 extension 声明过的 kind。
	EnqueuePluginJob(ctx context.Context, extensionID, kind string, payload map[string]any) error
}

JobEnqueuer 入队插件声明的 job kind。

type PermissionChecker

type PermissionChecker interface {
	// HasPermission 在用户存在时返回是否持有 permission。
	HasPermission(ctx context.Context, userID int64, permission string) (bool, error)
}

PermissionChecker 查询 actor 是否拥有权限。

type PluginJobArgs

type PluginJobArgs struct {
	EnvelopeVersion      int            `json:"envelopeVersion,omitempty"`
	ExtensionID          string         `json:"extensionId"`
	ExtensionVersion     string         `json:"extensionVersion,omitempty"`
	ArtifactDigest       string         `json:"artifactDigest,omitempty"`
	TrustGrantID         string         `json:"trustGrantId,omitempty"`
	JobName              string         `json:"kind"`
	JobContractVersion   string         `json:"jobContractVersion,omitempty"`
	PayloadSchemaID      string         `json:"payloadSchemaId,omitempty"`
	PayloadSchemaVersion string         `json:"payloadSchemaVersion,omitempty"`
	RetryPolicy          string         `json:"retryPolicy,omitempty"`
	MaxAttempts          int            `json:"maxAttempts,omitempty"`
	RetryDelaySeconds    int            `json:"retryDelaySeconds,omitempty"`
	ConcurrencyLimit     int            `json:"concurrencyLimit,omitempty"`
	Payload              map[string]any `json:"payload,omitempty"`
	EnqueuedAt           time.Time      `json:"enqueuedAt"`
}

PluginJobArgs 入队载荷:仅允许插件 manifest 声明过的 JobName。

func (PluginJobArgs) Contract

func (PluginJobArgs) InsertOpts

func (a PluginJobArgs) InsertOpts() river.InsertOpts

func (PluginJobArgs) Kind

func (PluginJobArgs) Kind() string

Kind 返回 River 注册用的固定 kind(非插件声明的 JobName)。

type PluginJobCompatibilityError

type PluginJobCompatibilityError struct {
	Decision supportjobs.PluginJobDecision
}

func (*PluginJobCompatibilityError) Error

type PluginJobContractSource

type PluginJobContractSource interface {
	PluginJobContract(context.Context, string, string) (supportjobs.PluginJobContract, error)
}

type PluginJobEnqueueAdmission

type PluginJobEnqueueAdmission interface {
	AcquirePluginJobEnqueue(context.Context, PluginJobEnqueueIdentity) (PluginJobEnqueueLease, error)
}

type PluginJobEnqueueIdentity

type PluginJobEnqueueIdentity struct {
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	InstanceID       string
}

PluginJobEnqueueIdentity 是协议认证后的 exact runtime 身份。 HostAPI 仅拥有最小契约,避免反向依赖 Extensions runtime 实现。

type PluginJobEnqueueLease

type PluginJobEnqueueLease interface {
	Context() context.Context
	Release()
}

PluginJobEnqueueLease 保证 admission 与最终 River INSERT 处于同一 drain 边界。

type PluginJobEnqueueLeaseFailure

type PluginJobEnqueueLeaseFailure interface {
	PluginJobEnqueueFailure() error
}

PluginJobEnqueueLeaseFailure 允许生产 adapter 将 runtime 自身的强制 drain 与普通调用者取消区分开;测试或第三方实现无需实现该可选接口。

type PluginJobExecutor

type PluginJobExecutor interface {
	ExecutePluginJob(context.Context, supportjobs.PluginJobInvocation) error
}

type PluginJobLifecycleCoordinator

type PluginJobLifecycleCoordinator struct {
	Store PluginJobLifecycleStore
}

func (*PluginJobLifecycleCoordinator) Reconcile

func (*PluginJobLifecycleCoordinator) ReconcileExpected

ReconcileExpected performs lock -> plan -> expected-plan fence -> execute in one River transaction. A retry after an unknown Host evidence commit may prove an earlier cancel/migration from durable River and migration-ledger facts; it never replays an unproven side effect.

type PluginJobLifecycleExecution

type PluginJobLifecycleExecution struct {
	JobID            int64
	Action           supportjobs.PluginJobAction
	Reason           string
	MigrationID      string
	ReplacementJobID int64
}

type PluginJobLifecycleExpectedDecision

type PluginJobLifecycleExpectedDecision struct {
	JobID       int64
	Action      supportjobs.PluginJobAction
	Reason      string
	MigrationID string
}

type PluginJobLifecycleExpectedPlan

type PluginJobLifecycleExpectedPlan struct {
	ExtensionID string
	Entries     []PluginJobLifecycleExpectedDecision
}

PluginJobLifecycleExpectedPlan is the sanitized durable fence prepared while enqueue and schedule admission are closed. It deliberately contains no args or payload bytes.

type PluginJobLifecycleInput

type PluginJobLifecycleInput struct {
	ExtensionID string
	// SourceContracts 与 TargetContracts 必须来自启动时冻结的完整 Manifest。
	// 显式空 map 表示没有声明;nil 表示调用方没有提供权威快照。
	SourceContracts        map[string]PluginJobRuntimeContract
	TargetContracts        map[string]PluginJobRuntimeContract
	SourceRuntimeAvailable bool
	Migrations             []supportjobs.PluginJobMigration
	Migrators              map[string]PluginJobPayloadMigrator
}

type PluginJobLifecyclePlan

type PluginJobLifecyclePlan struct {
	ExtensionID      string
	Entries          []PluginJobLifecyclePlanEntry
	IgnoredFinalized int
}

func PlanPluginJobLifecycle

func PlanPluginJobLifecycle(input PluginJobLifecycleInput, rows []PluginJobLifecycleRow) (PluginJobLifecyclePlan, error)

PlanPluginJobLifecycle 对锁定的行生成稳定、可审计的升级动作,不产生副作用。

type PluginJobLifecyclePlanEntry

type PluginJobLifecyclePlanEntry struct {
	Row      PluginJobLifecycleRow
	Args     PluginJobArgs
	Target   PluginJobRuntimeContract
	Decision supportjobs.PluginJobDecision
}

type PluginJobLifecycleResult

type PluginJobLifecycleResult struct {
	Plan       PluginJobLifecyclePlan
	Executions []PluginJobLifecycleExecution
	Committed  bool
}

type PluginJobLifecycleRiverClient

type PluginJobLifecycleRiverClient interface {
	InsertTx(context.Context, pgx.Tx, river.JobArgs, *river.InsertOpts) (*rivertype.JobInsertResult, error)
	JobCancelTx(context.Context, pgx.Tx, int64) (*rivertype.JobRow, error)
}

PluginJobLifecycleRiverClient 是 lifecycle adapter 使用的 River 公共事务面。 保持这个接口很小,避免 Host 依赖 River driver 的私有 SQL 或 schema 细节。

type PluginJobLifecycleRow

type PluginJobLifecycleRow struct {
	JobID       int64
	Kind        string
	State       rivertype.JobState
	EncodedArgs json.RawMessage
	Attempt     int
	MaxAttempts int
	Queue       string
	Priority    int
	ScheduledAt time.Time
	Tags        []string
}

PluginJobLifecycleRow 是由存储适配器在事务内锁定的 River 行快照。 适配器只能枚举 extension.plugin_job,且必须先按 extensionId 缩小范围。

type PluginJobLifecycleStore

type PluginJobLifecycleStore interface {
	WithPluginJobLifecycleTx(context.Context, func(PluginJobLifecycleTx) error) error
}

type PluginJobLifecycleTx

type PluginJobLifecycleTx interface {
	LockPluginJobs(context.Context, string) ([]PluginJobLifecycleRow, error)
	ClaimPluginJobMigration(context.Context, PluginJobMigrationLedgerEntry) (PluginJobMigrationClaim, error)
	InsertPluginJob(context.Context, PluginJobArgs, *river.InsertOpts) (int64, error)
	CompletePluginJobMigration(context.Context, PluginJobMigrationLedgerEntry, int64) error
	CancelPluginJob(context.Context, int64) error
}

PluginJobLifecycleTx 只暴露 Host ledger 与 River 的公开事务操作。 Insert/Cancel 必须使用 River 的 InsertTx/JobCancelTx;实现不得直接更新 River 的 args/encoded_args 私有存储列。Claim 必须回传持久化后的完整 ledger identity,Complete 必须用同一 identity 条件化链接 replacement。

type PluginJobMigrationClaim

type PluginJobMigrationClaim struct {
	Claimed  bool
	NewJobID int64
	Ledger   PluginJobMigrationLedgerEntry
}

type PluginJobMigrationLedgerEntry

type PluginJobMigrationLedgerEntry struct {
	OldJobID           int64
	ExtensionID        string
	MigrationID        string
	SourceContract     supportjobs.PluginJobContract
	SourceTrustGrantID string
	TargetContract     supportjobs.PluginJobContract
	TargetTrustGrantID string
}

type PluginJobPayloadMigrationInput

type PluginJobPayloadMigrationInput struct {
	MigrationID string
	Source      supportjobs.PluginJobContract
	Target      supportjobs.PluginJobContract
	Payload     map[string]any
}

type PluginJobPayloadMigrator

type PluginJobPayloadMigrator interface {
	MigratePluginJobPayload(context.Context, PluginJobPayloadMigrationInput) (map[string]any, error)
}

PluginJobPayloadMigrator 只迁移 schema-owned payload。不可执行外部副作用; exact artifact、trust grant 与完整信封始终由 Host 重建。

type PluginJobRuntimeContract

type PluginJobRuntimeContract struct {
	Contract     supportjobs.PluginJobContract
	TrustGrantID string
}

type PluginJobRuntimeResolver

type PluginJobRuntimeResolver interface {
	ResolvePluginJobRuntime(context.Context, string, string) (PluginJobRuntimeContract, error)
}

type PluginJobWorker

type PluginJobWorker struct {
	river.WorkerDefaults[PluginJobArgs]
	Resolver PluginJobRuntimeResolver
	Executor PluginJobExecutor
	Limiter  *supportjobs.PluginJobConcurrencyLimiter
	// contains filtered or unexported fields
}

PluginJobWorker resolves the live exact contract before any plugin code is invoked. Legacy or incompatible rows are permanently cancelled.

func (*PluginJobWorker) NextRetry

func (w *PluginJobWorker) NextRetry(job *river.Job[PluginJobArgs]) time.Time

func (*PluginJobWorker) Work

type PluginScheduleTriggerWorker

PluginScheduleTriggerWorker converts a Host-owned periodic marker into the exact declared plugin job while holding the same admission lease used by disable and upgrade drain.

func (*PluginScheduleTriggerWorker) Work

type PostgresPluginJobLifecycleStore

type PostgresPluginJobLifecycleStore struct {
	// contains filtered or unexported fields
}

func NewPostgresPluginJobLifecycleStore

func NewPostgresPluginJobLifecycleStore(
	pool *pgxpool.Pool,
	riverClient PluginJobLifecycleRiverClient,
) *PostgresPluginJobLifecycleStore

func (*PostgresPluginJobLifecycleStore) WithPluginJobLifecycleTx

func (s *PostgresPluginJobLifecycleStore) WithPluginJobLifecycleTx(
	ctx context.Context,
	fn func(PluginJobLifecycleTx) error,
) error

type PostgresProtocolV2CommandBackend

type PostgresProtocolV2CommandBackend struct {
	// contains filtered or unexported fields
}

PostgresProtocolV2CommandBackend stores command audit and replay evidence in the same transaction as domain writes. It has no command catalog of its own.

func NewPostgresProtocolV2CommandBackend

func NewPostgresProtocolV2CommandBackend(pool *pgxpool.Pool) *PostgresProtocolV2CommandBackend

func (*PostgresProtocolV2CommandBackend) AppendAudit

func (b *PostgresProtocolV2CommandBackend) AppendAudit(
	ctx context.Context,
	tx pgx.Tx,
	event protocolV2CommandAudit,
) (string, error)

func (*PostgresProtocolV2CommandBackend) AuthorizeActorDelegation

func (b *PostgresProtocolV2CommandBackend) AuthorizeActorDelegation(
	ctx context.Context,
	tx pgx.Tx,
	scope protocolV2CommandScope,
	delegation protocolV2VerifiedActorDelegation,
	fingerprint string,
	receiptExists bool,
	requiredPermissions []string,
) (int64, error)

func (*PostgresProtocolV2CommandBackend) Begin

func (*PostgresProtocolV2CommandBackend) LockIdempotency

func (b *PostgresProtocolV2CommandBackend) LockIdempotency(
	ctx context.Context,
	tx pgx.Tx,
	scope protocolV2CommandScope,
) (*protocolV2CommandReceipt, error)

func (*PostgresProtocolV2CommandBackend) ResolveHostCommandScope

func (b *PostgresProtocolV2CommandBackend) ResolveHostCommandScope(
	ctx context.Context,
	tx pgx.Tx,
	requested protocolV2CommandScope,
) (protocolV2CommandScope, error)

func (*PostgresProtocolV2CommandBackend) ResolveScope

func (b *PostgresProtocolV2CommandBackend) ResolveScope(
	ctx context.Context,
	tx pgx.Tx,
	requested protocolV2CommandScope,
) (protocolV2CommandScope, error)

func (*PostgresProtocolV2CommandBackend) SaveResult

func (b *PostgresProtocolV2CommandBackend) SaveResult(
	ctx context.Context,
	tx pgx.Tx,
	scope protocolV2CommandScope,
	receipt protocolV2CommandReceipt,
) error

func (*PostgresProtocolV2CommandBackend) WithTrustLevelSource

WithTrustLevelSource 注入信任等级来源(装配层调用,与 identity store 同一实例)。

type PostgresProtocolV2CommandRuntimeConfig

type PostgresProtocolV2CommandRuntimeConfig struct {
	Pool               *pgxpool.Pool
	ActorDelegations   *ProtocolV2ActorDelegationAuthority
	Jobs               *supportjobs.Dispatcher
	Moderation         *moderation.PostgresStore
	AttachmentStatuses ProtocolV2AttachmentStatusMutator
	// AttachmentExtensions 是扩展复用 Core 附件(claim/release/list)的领域边界。
	AttachmentExtensions ProtocolV2AttachmentExtensionRuntime
	IdentityAuthority    ProtocolV2IdentityAuthorityMutationGate
	// Events 是插件发布自身事件的宿主事件总线。为 nil 时事件发布命令报告
	// 不可用而不是被静默省略 —— 目录是密封的,缺依赖必须显式可见。
	Events ProtocolV2EventPublisher
	// AI 是插件发起补全的宿主网关。同样为 nil 时报告不可用:让插件悄悄退回
	// 自建出站就等于把成本重新放回账外。
	AI ProtocolV2AIGateway
	// TrustLevels 是信任等级来源(与 identity store 同一实例)。nil 时插件命令
	// 授权看不到已挣得权限——装配层必须注入,否则「HTTP 放行、插件 403」(D22)。
	TrustLevels identity.TrustLevelSource
	// BadgeFactKeys 返回某扩展自己声明的事实 key。nil 时 fail-closed
	// (所有权无法证明 ⇒ 一律 `fact_key_not_declared`),绝不放行。
	BadgeFactKeys ProtocolV2BadgeFactDeclarationReader
	// BadgeFacts 是插件事实的写口(`*badges.PostgresStore` 满足)。
	//
	// 为 nil 时命令**仍然注册**、但一律拒绝 `fact_write_failed`:目录是密封的,
	// 少一个依赖不能让调用方拿到 unknown command(那会让插件以为是版本不支持)。
	BadgeFacts ProtocolV2BadgeFactRecorder
}

type PostgresProtocolV2HostCommandBackend

type PostgresProtocolV2HostCommandBackend struct {
	*PostgresProtocolV2CommandBackend
}

PostgresProtocolV2HostCommandBackend adds the legacy manifest/trust authority gate required by Host Commands. The underlying backend deliberately remains authority-neutral because DatabaseService reuses its transaction receipts for independently approved own-schema operations.

func NewPostgresProtocolV2HostCommandBackend

func NewPostgresProtocolV2HostCommandBackend(pool *pgxpool.Pool) *PostgresProtocolV2HostCommandBackend

func (*PostgresProtocolV2HostCommandBackend) ResolveScope

func (b *PostgresProtocolV2HostCommandBackend) ResolveScope(
	ctx context.Context,
	tx pgx.Tx,
	requested protocolV2CommandScope,
) (protocolV2CommandScope, error)

func (*PostgresProtocolV2HostCommandBackend) WithTrustLevelSource

WithTrustLevelSource 在 **wrapper 上重新声明**,并返回 wrapper 本身。

这不是重复代码,是结构约束:`WithTrustLevelSource` 同时定义在被嵌入的 PostgresProtocolV2CommandBackend 上、返回中性类型。Go 的方法提升会让

NewPostgresProtocolV2HostCommandBackend(pool).WithTrustLevelSource(src)

返回**中性 backend**,于是 newProtocolV2CommandEngineWithInvalidationJobs 拿到的是 不做 host_commands 授权检查的那个实现 —— 闸门静默失效(f63ad2cf9 引入的 P0: 任何已启用扩展都能执行权益等域命令)。重新声明后链式写法只能得到 wrapper, 「记住别这么写」变成「这么写不出来」。

type ProtocolV2AIGateway

type ProtocolV2AIGateway interface {
	Execute(ctx context.Context, request supportai.CompletionRequest) (supportai.CompletionResult, error)
}

ProtocolV2AIGateway 是命令与 AI 网关之间的窄接口。它刻意与 *supportai.Gateway 的 Execute 同形:命令不需要知道闸门、记账与 trace 的 内部结构,只需要把一次中立请求交给它。

type ProtocolV2ActorDelegationAuthority

type ProtocolV2ActorDelegationAuthority struct {
	// contains filtered or unexported fields
}

ProtocolV2ActorDelegationAuthority owns one boot-scoped signing key. A Host restart intentionally invalidates outstanding short-lived delegations.

func NewProtocolV2ActorDelegationAuthority

func NewProtocolV2ActorDelegationAuthority() (*ProtocolV2ActorDelegationAuthority, error)

func (*ProtocolV2ActorDelegationAuthority) IssueActorDelegation

type ProtocolV2ActorDelegationBundleIssuer

type ProtocolV2ActorDelegationBundleIssuer interface {
	IssueProtocolV2ActorDelegations(context.Context, ProtocolV2ActorDelegationBundleRequest) ([]ProtocolV2ActorDelegationGrant, error)
}

ProtocolV2ActorDelegationBundleIssuer is the narrow production capability consumed by Host-owned route and admin transports.

type ProtocolV2ActorDelegationBundleRequest

type ProtocolV2ActorDelegationBundleRequest struct {
	ActorUserID    int64
	PermissionKeys []string
	Runtime        *protocolv2.ExtensionIdentity
	IdempotencyKey string
}

ProtocolV2ActorDelegationBundleRequest is authored only by a Host route or admin adapter. Permission keys are an issuance-time filter; Execute still reloads the actor and permissions inside the command transaction.

type ProtocolV2ActorDelegationGrant

type ProtocolV2ActorDelegationGrant struct {
	CommandID      string
	CommandVersion string
	IdempotencyKey string
	Token          string
}

ProtocolV2ActorDelegationGrant carries one command-bound token to the exact plugin invocation that may use it.

type ProtocolV2ActorDelegationIssuer

type ProtocolV2ActorDelegationIssuer interface {
	IssueActorDelegation(context.Context, ProtocolV2ActorDelegationRequest) (string, error)
}

ProtocolV2ActorDelegationIssuer is the narrow in-process capability exposed to Host-owned route/admin adapters. It is never registered as a plugin RPC.

type ProtocolV2ActorDelegationRequest

type ProtocolV2ActorDelegationRequest struct {
	ActorUserID    int64
	Runtime        *protocolv2.ExtensionIdentity
	CommandID      string
	CommandVersion string
	IdempotencyKey string
}

ProtocolV2ActorDelegationRequest is created only from a Host-authenticated route or admin invocation. Issuance does not replace the transaction-time actor and permission check performed when the command executes.

type ProtocolV2AttachmentExtensionRuntime

type ProtocolV2AttachmentExtensionRuntime interface {
	ExtensionAttachmentPolicy(ctx context.Context) (extensionreference.Policy, error)
	PrepareClaim(ctx context.Context, tx pgx.Tx, input extensionreference.ClaimInput) (*extensionreference.ClaimPlan, error)
	ApplyClaim(ctx context.Context, tx pgx.Tx, plan *extensionreference.ClaimPlan) (extensionreference.Claim, error)
	Count(ctx context.Context, tx pgx.Tx, input extensionreference.ReleaseInput) (int, error)
	Release(ctx context.Context, tx pgx.Tx, input extensionreference.ReleaseInput) (extensionreference.Release, error)
	List(ctx context.Context, tx pgx.Tx, input extensionreference.ListInput) (extensionreference.List, error)
}

ProtocolV2AttachmentExtensionRuntime 是扩展附件引用命令的领域边界。 约束(站点上限/引用上限)来自 attachments 服务,引用行读写来自 Attachments/ExtensionReference store;bootstrap 把两者合成一个适配器注入, 这样 Host Command 目录本身不依赖任何附件存储实现。

type ProtocolV2AttachmentStatusMutator

type ProtocolV2AttachmentStatusMutator interface {
	MutateProtocolV2AttachmentStatus(context.Context, pgx.Tx, int64, string) (ProtocolV2AttachmentStatusResult, error)
}

type ProtocolV2AttachmentStatusResult

type ProtocolV2AttachmentStatusResult struct {
	ID             int64
	Status         string
	ReferenceCount int
	UpdatedAt      time.Time
}

type ProtocolV2BadgeFactDeclarationReader

type ProtocolV2BadgeFactDeclarationReader interface {
	BadgeFactKeys(ctx context.Context, extensionID string) ([]string, error)
}

ProtocolV2BadgeFactDeclarationReader 返回某扩展**自己声明**的 factKey。

为 nil 时 fail-closed(所有权无法证明 ⇒ 一律拒绝):装配漏接不该变成「谁都能写」。

type ProtocolV2BadgeFactRecorder

type ProtocolV2BadgeFactRecorder interface {
	RecordFact(ctx context.Context, input badges.FactInput) (badges.FactResult, error)
}

ProtocolV2BadgeFactRecorder 是 `Models/Badges` 写口的窄接口(*PostgresStore 满足)。

命令**不自己写 SQL**:事实行与累计计数必须同事务,那份语义只有 `RecordFact` 一处维护;另写一份就会得到「窗口条件看得到、累计条件看不到」的分裂。

type ProtocolV2CacheServiceServer

type ProtocolV2CacheServiceServer struct {
	hostv2.UnimplementedCacheServiceServer
	// contains filtered or unexported fields
}

ProtocolV2CacheServiceServer exposes declaration-bound cache operations to an exact broker-attested runtime. Cross-RPC lock tokens are opaque Host handles; backend owner tokens and executable callbacks never cross the broker.

func NewProtocolV2CacheServiceServer

func NewProtocolV2CacheServiceServer(service *HostCacheService) (*ProtocolV2CacheServiceServer, error)

func (*ProtocolV2CacheServiceServer) AcquireLock

func (*ProtocolV2CacheServiceServer) Delete

func (*ProtocolV2CacheServiceServer) Get

func (*ProtocolV2CacheServiceServer) Increment

func (*ProtocolV2CacheServiceServer) InvalidateTags

func (*ProtocolV2CacheServiceServer) ReleaseLock

func (*ProtocolV2CacheServiceServer) RenewLock

func (*ProtocolV2CacheServiceServer) Set

func (*ProtocolV2CacheServiceServer) SetAndReleaseLock

type ProtocolV2CommandRuntime

type ProtocolV2CommandRuntime interface {
	// contains filtered or unexported methods
}

ProtocolV2CommandRuntime is a sealed Host-owned command catalog. P5's PostgreSQL command package constructs one and binds it before broker boot.

func NewPostgresProtocolV2CommandRuntime

func NewPostgresProtocolV2CommandRuntime(config PostgresProtocolV2CommandRuntimeConfig) (ProtocolV2CommandRuntime, error)

NewPostgresProtocolV2CommandRuntime publishes the complete immutable domain catalog. Missing dependencies fail boot instead of silently omitting a command and creating different API/worker capabilities.

type ProtocolV2ConsentQueryEvent

type ProtocolV2ConsentQueryEvent struct {
	ActorUserID      int64
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	QueryID          string
	PlanVersion      string
	RequestID        string
	Rows             int
}

ProtocolV2ConsentQueryEvent is the audit payload for one successful consent read. It deliberately has no field for the returned values.

type ProtocolV2DatabaseColumn

type ProtocolV2DatabaseColumn struct {
	Name     string
	Nullable bool
}

ProtocolV2DatabaseColumn is the complete allowlist for a returned row.

type ProtocolV2DatabaseExecuteDefinition

type ProtocolV2DatabaseExecuteDefinition struct {
	ExtensionID           string
	ExtensionVersion      string
	PackageDigest         string
	OperationID           string
	StatementVersion      string
	SQL                   string
	Parameters            []ProtocolV2DatabaseParameter
	ResultSchemaID        string
	ResultSchemaVersion   string
	ReturningColumns      []ProtocolV2DatabaseColumn
	MaxAffectedRows       uint64
	QueryInvalidationTags []string
	Timeout               time.Duration
}

ProtocolV2DatabaseExecuteDefinition always runs under the plugin runtime role. ReturningColumns may describe at most one RETURNING row.

type ProtocolV2DatabaseParameter

type ProtocolV2DatabaseParameter struct {
	SchemaID      string
	SchemaVersion string
	Field         string
	Kind          string
	Nullable      bool
	MaxBytes      int
}

ProtocolV2DatabaseParameter declares one positional argument. The document must contain exactly Field and use the declared schema and scalar kind.

type ProtocolV2DatabaseQueryDefinition

type ProtocolV2DatabaseQueryDefinition struct {
	ExtensionID         string
	ExtensionVersion    string
	PackageDigest       string
	OperationID         string
	StatementVersion    string
	Scope               string
	SQL                 string
	Parameters          []ProtocolV2DatabaseParameter
	ResultSchemaID      string
	ResultSchemaVersion string
	Columns             []ProtocolV2DatabaseColumn
	MaxRows             int
	Timeout             time.Duration
}

ProtocolV2DatabaseQueryDefinition is Host-owned configuration. SQL is frozen when the runtime is constructed and is never accepted over RPC.

type ProtocolV2DatabaseRuntime

type ProtocolV2DatabaseRuntime interface {
	DatabaseService() hostv2.DatabaseServiceServer
	// contains filtered or unexported methods
}

ProtocolV2DatabaseRuntime exposes only the generated service interface; its immutable statement catalog cannot be mutated after construction.

func NewPostgresProtocolV2DatabaseRuntime

func NewPostgresProtocolV2DatabaseRuntime(
	pool *pgxpool.Pool,
	queries []ProtocolV2DatabaseQueryDefinition,
	executes []ProtocolV2DatabaseExecuteDefinition,
	options ...ProtocolV2DatabaseRuntimeOption,
) (ProtocolV2DatabaseRuntime, error)

NewPostgresProtocolV2DatabaseRuntime freezes the Host-owned operation catalog and binds it to the exact-artifact PostgreSQL authority resolver.

type ProtocolV2DatabaseRuntimeOption

type ProtocolV2DatabaseRuntimeOption interface {
	// contains filtered or unexported methods
}

func WithProtocolV2DatabaseQueryInvalidationJobs

func WithProtocolV2DatabaseQueryInvalidationJobs(dispatcher *supportjobs.Dispatcher) ProtocolV2DatabaseRuntimeOption

type ProtocolV2EventPublisher

type ProtocolV2EventPublisher interface {
	EmitFromExtension(ctx context.Context, extensionID string, envelope appevents.Envelope) appevents.Result
}

ProtocolV2EventPublisher 是命令与扩展运行时事件总线之间的窄接口。 它刻意只有一个方法:命令不需要知道投递、重试与 delivery 记录的任何细节。

type ProtocolV2FileServiceServer

type ProtocolV2FileServiceServer struct {
	hostv2.UnimplementedFileServiceServer
	// contains filtered or unexported fields
}

ProtocolV2FileServiceServer exposes PluginFiles under exact runtime ownership.

func NewProtocolV2FileServiceServer

func NewProtocolV2FileServiceServer(files *pluginfiles.Service) (*ProtocolV2FileServiceServer, error)

NewProtocolV2FileServiceServer builds the Protocol V2 File boundary.

func (*ProtocolV2FileServiceServer) Delete

Delete removes a relative path for the attested extension.

func (*ProtocolV2FileServiceServer) Read

Read streams file bytes for the attested extension only.

func (*ProtocolV2FileServiceServer) Stat

Stat returns metadata without absolute host paths.

func (*ProtocolV2FileServiceServer) Write

Write accepts a client stream and stores under the extension namespace.

type ProtocolV2HttpServiceServer

type ProtocolV2HttpServiceServer struct {
	hostv2.UnimplementedHttpServiceServer
	// contains filtered or unexported fields
}

ProtocolV2HttpServiceServer exposes HostHTTP with SSRF and SecretStore injection.

func NewProtocolV2HttpServiceServer

func NewProtocolV2HttpServiceServer(client *hosthttp.Client) (*ProtocolV2HttpServiceServer, error)

NewProtocolV2HttpServiceServer builds the Protocol V2 HTTP boundary.

func (*ProtocolV2HttpServiceServer) Do

Do executes a policy-checked outbound request. PolicyId may be a secret ref (sforum.secret://ns/id) for credential injection.

func (*ProtocolV2HttpServiceServer) Stream

Stream is not implemented for the unary-safe production path (fail closed).

type ProtocolV2IdentityAuthorityMutationGate

type ProtocolV2IdentityAuthorityMutationGate interface {
	RunSessionPolicyMutation(context.Context, func() error) error
}

type ProtocolV2ProviderBroker

type ProtocolV2ProviderBroker interface {
	InvokeProtocolV2Provider(context.Context, ProtocolV2ProviderInvocation) (ProtocolV2ProviderResult, error)
}

type ProtocolV2ProviderCaller

type ProtocolV2ProviderCaller struct {
	ExtensionID       string
	ExtensionVersion  string
	ArtifactDigest    string
	RuntimeInstanceID string
}

type ProtocolV2ProviderError

type ProtocolV2ProviderError struct {
	Reason   string
	Err      error
	Attempts int
}

func (*ProtocolV2ProviderError) Error

func (e *ProtocolV2ProviderError) Error() string

func (*ProtocolV2ProviderError) Unwrap

func (e *ProtocolV2ProviderError) Unwrap() error

type ProtocolV2ProviderInvocation

type ProtocolV2ProviderInvocation struct {
	Caller          ProtocolV2ProviderCaller
	SlotID          string
	ContractVersion string
	Operation       string
	InputSchema     string
	Input           map[string]any
}

type ProtocolV2ProviderResult

type ProtocolV2ProviderResult struct {
	ProviderID        string
	ProviderExtension string
	RuntimeInstanceID string
	ResponseSchema    string
	Output            map[string]any
	Attempts          int
}

type ProtocolV2QueryActorAuthority

type ProtocolV2QueryActorAuthority interface {
	ResolveProtocolV2QueryActor(context.Context, int64) (ProtocolV2QueryActorProjection, error)
	AuthorizeProtocolV2QueryActor(context.Context, int64, queryregistry.PermissionClaim) (ProtocolV2QueryActorProjection, error)
}

ProtocolV2QueryActorAuthority resolves the actor at issuance and performs the authoritative live permission check at every Query Registry fence.

type ProtocolV2QueryActorDelegationGrant

type ProtocolV2QueryActorDelegationGrant struct {
	QueryID             string
	ContractVersion     string
	PlanVersion         string
	ResultSchemaID      string
	ResultSchemaVersion string
	Scope               string
	Token               string
}

ProtocolV2QueryActorDelegationGrant is copied into RequestContext only for the exact plugin invocation that may consume it.

type ProtocolV2QueryActorDelegationIssuer

type ProtocolV2QueryActorDelegationIssuer interface {
	IssueProtocolV2QueryActorDelegation(context.Context, ProtocolV2QueryActorDelegationRequest) (ProtocolV2QueryActorDelegationGrant, error)
}

type ProtocolV2QueryActorDelegationRequest

type ProtocolV2QueryActorDelegationRequest struct {
	ActorUserID int64
	Runtime     *protocolv2.ExtensionIdentity
	QueryID     string
	Locale      string
	Scope       string
	MaxCost     int
}

ProtocolV2QueryActorDelegationRequest is created only by a Host-authenticated route/admin adapter. The Host identity authority derives every fingerprint; callers select only the actor, exact runtime, and intended query outlet.

type ProtocolV2QueryActorProjection

type ProtocolV2QueryActorProjection struct {
	ActorUserID       int64
	Authenticated     bool
	ActorFingerprint  string
	PolicyFingerprint string
}

ProtocolV2QueryActorProjection is derived by Host identity policy. The two fingerprints are opaque cache/authority isolation material, never bearer credentials and never values supplied by a plugin.

type ProtocolV2QueryAuthority

type ProtocolV2QueryAuthority struct {
	ExactArtifact bool
	CoreViews     bool
	Capabilities  []string
}

ProtocolV2QueryAuthority is resolved from Host-owned exact artifact and trust state. CoreViews remains a separate bit so future additive grants do not require trusting RequestContext.granted_authority or changing the query engine. Capabilities is the exact artifact's effective capability key set, used only by ConsentGated definitions (never by ordinary stable queries).

type ProtocolV2QueryAuthorityResolver

type ProtocolV2QueryAuthorityResolver interface {
	ResolveProtocolV2QueryAuthority(context.Context, *protocolv2.ExtensionIdentity) (ProtocolV2QueryAuthority, error)
}

func NewPostgresProtocolV2QueryAuthorityResolver

func NewPostgresProtocolV2QueryAuthorityResolver(pool *pgxpool.Pool) ProtocolV2QueryAuthorityResolver

type ProtocolV2QueryCallerAdmission

type ProtocolV2QueryCallerAdmission interface {
	AuthorizeProtocolV2QueryCaller(context.Context, *protocolv2.ExtensionIdentity) error
}

ProtocolV2QueryCallerAdmission rechecks the authenticated broker runtime. Implementations must fail while the exact artifact is revoked, quarantined, draining, disabled, or no longer the active runtime instance.

type ProtocolV2QueryCapabilityAuthority

type ProtocolV2QueryCapabilityAuthority interface {
	AuthorizeProtocolV2QueryCapability(
		context.Context,
		*protocolv2.ExtensionIdentity,
		string,
	) error
}

ProtocolV2QueryCapabilityAuthority resolves the exact-artifact capability set. Implementations must fail while the artifact is not the active exact runtime; the capability is never trusted from the plugin request.

type ProtocolV2QueryConsentGate

type ProtocolV2QueryConsentGate struct {
	Capabilities ProtocolV2QueryCapabilityAuthority
	Auditor      audit.Writer
	Limiter      ProtocolV2QueryRateLimiter
	// Capability overrides the required capability key. Empty means
	// capabilities.UsersEmailRead.
	Capability string
	RateMax    int
	RateWindow time.Duration
}

ProtocolV2QueryConsentGate is the Host-owned policy for ConsentGated definitions: exact-artifact capability, per-(actor, extension) rate limit, and one audit event per successful read. It owns no SQL and no cache.

func (*ProtocolV2QueryConsentGate) Authorize

func (g *ProtocolV2QueryConsentGate) Authorize(
	ctx context.Context,
	identity *protocolv2.ExtensionIdentity,
	actorUserID int64,
	queryID string,
) error

Authorize enforces capability + the (actor, extension) rate limit before any row is read. Anonymous actors are denied: a consent read always has an actor.

func (*ProtocolV2QueryConsentGate) AuthorizeCapability

func (g *ProtocolV2QueryConsentGate) AuthorizeCapability(
	ctx context.Context,
	identity *protocolv2.ExtensionIdentity,
) error

AuthorizeCapability checks only the exact-artifact capability. Issuance uses it so a plugin without the capability never receives a delegation at all.

func (*ProtocolV2QueryConsentGate) Record

Record appends the single audit event for one successful read. A missing auditor fails closed: the Host never returns consent data it cannot audit.

type ProtocolV2QueryDelegationAuthority

type ProtocolV2QueryDelegationAuthority struct {
	// contains filtered or unexported fields
}

ProtocolV2QueryDelegationAuthority owns a boot-scoped signing key and replay ledger. Tokens cannot survive a Host restart or move to another Gateway.

func NewProtocolV2QueryDelegationAuthority

func NewProtocolV2QueryDelegationAuthority() (*ProtocolV2QueryDelegationAuthority, error)

type ProtocolV2QueryRateLimiter

type ProtocolV2QueryRateLimiter interface {
	Allow(ctx context.Context, key string, max int, window time.Duration) (bool, error)
}

ProtocolV2QueryRateLimiter is the narrow counter boundary for consent reads. A nil limiter means "not configured" and allows the read (dev/test); callers never see a partial count.

type ProtocolV2QueryRegistryOption

type ProtocolV2QueryRegistryOption interface {
	// contains filtered or unexported methods
}

ProtocolV2QueryRegistryOption mutates the outlet policy at construction.

func WithProtocolV2QueryConsentGate

func WithProtocolV2QueryConsentGate(gate *ProtocolV2QueryConsentGate) ProtocolV2QueryRegistryOption

WithProtocolV2QueryConsentGate installs the capability + rate-limit + audit gate used by ConsentGated definitions (for example the self-email read).

type ProtocolV2QueryRegistryOptions

type ProtocolV2QueryRegistryOptions struct {
	ConsentGate *ProtocolV2QueryConsentGate
}

ProtocolV2QueryRegistryOptions collects optional Host-owned policy for the Query Registry Protocol V2 outlet.

type ProtocolV2QueryRegistryService

type ProtocolV2QueryRegistryService struct {
	// contains filtered or unexported fields
}

ProtocolV2QueryRegistryService is the explicit Protocol V2 outlet for the bounded Query Registry executor. It is immutable after construction.

func (*ProtocolV2QueryRegistryService) IssueProtocolV2QueryActorDelegation

type ProtocolV2QueryRuntime

type ProtocolV2QueryRuntime interface {
	// contains filtered or unexported methods
}

func NewPostgresProtocolV2QueryRuntime

func NewPostgresProtocolV2QueryRuntime(
	pool *pgxpool.Pool,
	authority ProtocolV2QueryAuthorityResolver,
	options ...ProtocolV2QueryRuntimeOption,
) (ProtocolV2QueryRuntime, error)

type ProtocolV2QueryRuntimeOption

type ProtocolV2QueryRuntimeOption interface {
	// contains filtered or unexported methods
}

func WithProtocolV2QueryTraceSink

func WithProtocolV2QueryTraceSink(sink QueryTraceSink) ProtocolV2QueryRuntimeOption

func WithTrustLevelQuerySource

func WithTrustLevelQuerySource(source TrustLevelQuerySource) ProtocolV2QueryRuntimeOption

WithTrustLevelQuerySource 把读面注入查询运行时(bootstrap 装配用)。

type ProtocolV2SecretServiceServer

type ProtocolV2SecretServiceServer struct {
	hostv2.UnimplementedSecretServiceServer
	// contains filtered or unexported fields
}

ProtocolV2SecretServiceServer exposes SecretStore.Resolve to exact runtimes and the settings write half (Put/Clear) to runtimes that declare the same secret fields.

func NewProtocolV2SecretServiceServer

func NewProtocolV2SecretServiceServer(secrets *secretstore.Service, settings *settingslifecycle.Service) (*ProtocolV2SecretServiceServer, error)

NewProtocolV2SecretServiceServer builds the Protocol V2 Secret boundary.

func (*ProtocolV2SecretServiceServer) BindCapabilitySource

func (s *ProtocolV2SecretServiceServer) BindCapabilitySource(source CapabilitySource)

BindCapabilitySource late-binds the capability resolver used to gate secret writes.

func (*ProtocolV2SecretServiceServer) Clear

Clear removes one declared settings secret and leaves every other field untouched.

func (*ProtocolV2SecretServiceServer) Put

Put stores one settings secret the caller's manifest declares.

The write goes through SettingsLifecycle so the Secret Store reference, the settings document CAS revision and the migration path stay in one place: a plugin writing its own token must be indistinguishable, to the admin settings page, from an operator typing it.

func (*ProtocolV2SecretServiceServer) Resolve

Resolve decrypts a secret for the broker-attested extension namespace only.

type ProtocolV2SessionDelegationAuthority

type ProtocolV2SessionDelegationAuthority struct {
	// contains filtered or unexported fields
}

ProtocolV2SessionDelegationAuthority owns one boot-scoped signing key and the mint ledger. A Host restart intentionally invalidates every outstanding delegation: they are short-lived and the plugin contract states that session state is ephemeral and a miss must be tolerated (S2).

func NewProtocolV2SessionDelegationAuthority

func NewProtocolV2SessionDelegationAuthority() (*ProtocolV2SessionDelegationAuthority, error)

func (*ProtocolV2SessionDelegationAuthority) MintProtocolV2SessionDelegation

func (a *ProtocolV2SessionDelegationAuthority) MintProtocolV2SessionDelegation(
	ctx context.Context,
	runtime *protocolv2.ExtensionIdentity,
	scope ProtocolV2SessionScope,
) (string, error)

MintProtocolV2SessionDelegation signs one delegation and records the scope it stands for. Callers must retire the returned token when the invocation that carries it settles; `defer` in the transport is the intended shape.

func (*ProtocolV2SessionDelegationAuthority) Resolve

Resolve validates one echoed delegation against the broker-attested runtime and returns the Host's own record of the scope it stands for. It does not remove the record: one invocation may legitimately perform several get/set/delete operations, and the transport retires the delegation when the invocation settles.

func (*ProtocolV2SessionDelegationAuthority) RetireProtocolV2SessionDelegation

func (a *ProtocolV2SessionDelegationAuthority) RetireProtocolV2SessionDelegation(token string) error

RetireProtocolV2SessionDelegation drops the mint record. It is idempotent: an unknown or already-retired token is not an error, because every transport defers it and a failed invocation must not turn into a second failure.

type ProtocolV2SessionDelegationIssuer

type ProtocolV2SessionDelegationIssuer interface {
	MintProtocolV2SessionDelegation(context.Context, *protocolv2.ExtensionIdentity, ProtocolV2SessionScope) (string, error)
	RetireProtocolV2SessionDelegation(string) error
}

ProtocolV2SessionDelegationIssuer is the narrow in-process capability the Host-owned route/admin transports use to obtain a session delegation for one invocation. It is never registered as a plugin RPC: a plugin cannot mint one.

type ProtocolV2SessionScope

type ProtocolV2SessionScope struct {
	// SessionFingerprint is sha256hex of the session identifier the Host chose
	// for this session (the stable `sid` when authenticated, the cookie session
	// id for an anonymous session). The raw identifier never leaves AuthSession.
	SessionFingerprint string
	// IdleExpiresAt / AbsoluteExpiresAt are the Core session's two lifetime
	// boundaries. Plugin state can never outlive them.
	IdleExpiresAt     time.Time
	AbsoluteExpiresAt time.Time
	// ActorUserID is 0 for an anonymous session.
	ActorUserID int64
}

ProtocolV2SessionScope is the Host-resolved Core session scope of one HTTP request. It is Host-only data: it is never placed on the wire and never reaches a plugin. Both deadlines are zero when the Host cannot bound that side of the session lifetime; the store treats an unknown bound as "cannot tighten further", never as "unlimited".

type ProtocolV2SessionServiceOption

type ProtocolV2SessionServiceOption func(*ProtocolV2SessionServiceServer) error

func WithProtocolV2SessionAdmission

func WithProtocolV2SessionAdmission(admission ServiceProviderAdmission) ProtocolV2SessionServiceOption

WithProtocolV2SessionAdmission installs the exact-runtime admission check.

func WithProtocolV2SessionSafeMode

func WithProtocolV2SessionSafeMode(enabled bool) ProtocolV2SessionServiceOption

WithProtocolV2SessionSafeMode marks the whole service Safe Mode: reads miss, writes are refused.

type ProtocolV2SessionServiceServer

type ProtocolV2SessionServiceServer struct {
	hostv2.UnimplementedPluginSessionServiceServer
	// contains filtered or unexported fields
}

ProtocolV2SessionServiceServer serves the S7 surface: three operations whose requests carry only a namespace key (+ value/ttl on Set). The extension identity comes from the broker-attested runtime, the session scope from the S9 delegation, and the installation from the Host. A caller-supplied extension id, user id, or session id is not merely ignored — the request shape has no such field, so it cannot be smuggled in.

func NewProtocolV2SessionServiceServer

func NewProtocolV2SessionServiceServer(
	store *pluginsessionstate.Store,
	delegations *ProtocolV2SessionDelegationAuthority,
	installationID string,
	options ...ProtocolV2SessionServiceOption,
) (*ProtocolV2SessionServiceServer, error)

func (*ProtocolV2SessionServiceServer) Delete

func (*ProtocolV2SessionServiceServer) Get

func (*ProtocolV2SessionServiceServer) Set

type ProtocolV2ShortcodeProjectionDelegationBundleIssuer

type ProtocolV2ShortcodeProjectionDelegationBundleIssuer interface {
	IssueProtocolV2ShortcodeProjectionDelegations(
		context.Context,
		ProtocolV2ShortcodeProjectionDelegationRequest,
	) ([]ProtocolV2QueryActorDelegationGrant, error)
}

type ProtocolV2ShortcodeProjectionDelegationRequest

type ProtocolV2ShortcodeProjectionDelegationRequest struct {
	ActorUserID int64
	Runtime     *protocolv2.ExtensionIdentity
	Locale      string
	Scope       string
}

ProtocolV2ShortcodeProjectionDelegationRequest is Host-authored for one exact content-runtime call. ActorUserID zero represents an anonymous viewer.

type QueryRegistryCoreCatalog

type QueryRegistryCoreCatalog struct {
	// contains filtered or unexported fields
}

QueryRegistryCoreCatalog is the Host-owned production projection of the stable Protocol V2 query definitions into Query Registry primitives.

func NewQueryRegistryCoreCatalog

func NewQueryRegistryCoreCatalog() (*QueryRegistryCoreCatalog, error)

NewQueryRegistryCoreCatalog builds sealed Core publications, explicit Protocol V2 bindings, JSON result schemas, and the deterministic cost policy from stableCoreProtocolV2QueryDefinitions. It does not publish or execute.

func NewQueryRegistryCoreRegistry

func NewQueryRegistryCoreRegistry(options QueryRegistryCoreOptions) (*queryregistry.Registry, *QueryRegistryCoreCatalog, error)

NewQueryRegistryCoreRegistry constructs a Query Registry preloaded with the Core catalog, Host cost policy, and optional HMAC cursor codec.

func (*QueryRegistryCoreCatalog) Artifact

Artifact returns the exact sealed Core catalog identity.

func (*QueryRegistryCoreCatalog) Bindings

Bindings returns a detached Protocol V2 provider mapping snapshot.

func (*QueryRegistryCoreCatalog) CostMaximum

func (c *QueryRegistryCoreCatalog) CostMaximum() int

CostMaximum returns the normalized site budget sealed by this catalog.

func (*QueryRegistryCoreCatalog) CostPolicy

CostPolicy returns the immutable Host-owned policy sealed by this catalog.

func (*QueryRegistryCoreCatalog) Publication

Publication returns a detached copy so callers cannot mutate the catalog after its artifact digest has been sealed.

func (*QueryRegistryCoreCatalog) Schemas

Schemas returns detached bindings, including copies of every schema body.

type QueryRegistryCoreOptions

type QueryRegistryCoreOptions struct {
	// CursorSecret is optional HMAC key material for cursor-capable registries.
	// When empty, NewQueryRegistryCoreRegistry omits the cursor codec and
	// cursor pagination stays fail-closed.
	CursorSecret []byte
	// CostMaximum is the site-owned plan budget. Zero selects the recommended
	// default; positive values may not exceed the Host hard maximum.
	CostMaximum int
}

QueryRegistryCoreOptions configures catalog construction. Cursor secret is never generated or persisted here; callers supply it from Host config.

type QueryRegistryProtocolV2Binding

type QueryRegistryProtocolV2Binding struct {
	QueryID         string
	ContractVersion string
	PlanVersion     string
	ResultSchema    string
	Artifact        queryregistry.Artifact
	HostQueryID     string
	HostPlanVersion string
}

QueryRegistryProtocolV2Binding maps one Query Registry core declaration to one existing HostAPI v2 definition. The two identities are explicit because the frozen catalogs use different namespaces and must never be matched by a naming convention.

type QueryTrace

type QueryTrace struct {
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	QueryID          string
	PlanVersion      string
	ShapeDigest      string
	Duration         time.Duration
	Rows             int
	Outcome          QueryTraceOutcome
	Slow             bool
}

QueryTrace deliberately excludes request parameters, result documents, SQL, credentials, and error text. Sinks receive only bounded Host-owned metadata.

type QueryTraceOutcome

type QueryTraceOutcome string
const (
	QueryTraceAllowed  QueryTraceOutcome = "allowed"
	QueryTraceDenied   QueryTraceOutcome = "denied"
	QueryTraceStale    QueryTraceOutcome = "stale"
	QueryTraceError    QueryTraceOutcome = "error"
	QueryTraceCancel   QueryTraceOutcome = "cancel"
	QueryTraceDeadline QueryTraceOutcome = "deadline"
)

type QueryTraceSink

type QueryTraceSink interface {
	RecordQueryTrace(QueryTrace)
}

func NewSlogQueryTraceSink

func NewSlogQueryTraceSink(logger *slog.Logger) QueryTraceSink

type Request

type Request struct {
	Method      string `json:"method"`
	ExtensionID string `json:"extensionId"`
	TimeoutMS   int    `json:"timeoutMs,omitempty"`
	// Payload 为方法特定字段(扁平 map,避免反射复杂化)。
	Payload map[string]any `json:"payload,omitempty"`
}

Request 是插件 → 宿主的统一信封。

type ResolvedService

type ResolvedService struct {
	ServiceID  string
	Revision   uint64
	Winner     ServiceRegistration
	Candidates []ServiceRegistration
	// contains filtered or unexported fields
}

ResolvedService is one effective version plus all same-version candidates. Candidate zero is always the deterministic winner.

func (ResolvedService) Authorize

func (ResolvedService) AuthorizeDependency

func (s ResolvedService) AuthorizeDependency(caller ServiceCaller) ServiceDependencyDecision

func (ResolvedService) HasConflict

func (s ResolvedService) HasConflict() bool

type Response

type Response struct {
	OK      bool           `json:"ok"`
	Reason  string         `json:"reason,omitempty"`
	Message string         `json:"message,omitempty"`
	Data    map[string]any `json:"data,omitempty"`
}

Response 是宿主 → 插件的统一信封。

type RiverJobEnqueuer

type RiverJobEnqueuer struct {
	Dispatcher *supportjobs.Dispatcher
	Contracts  PluginJobContractSource
}

RiverJobEnqueuer 把插件 job 写入 River 队列。默认是 default 队列;清单里 声明 queue: ai 的任务进入 AI 慢速通道。Contracts 可缺省(v1 路径的回退)。

func (*RiverJobEnqueuer) EnqueuePluginJob

func (e *RiverJobEnqueuer) EnqueuePluginJob(ctx context.Context, extensionID, kind string, payload map[string]any) error

func (*RiverJobEnqueuer) EnqueueVersionedPluginJob

func (e *RiverJobEnqueuer) EnqueueVersionedPluginJob(
	ctx context.Context,
	contract supportjobs.PluginJobContract,
	trustGrantID string,
	payload map[string]any,
) error

EnqueueVersionedPluginJob persists the exact runtime and manifest contract that authorized a protocol-v2 enqueue request.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service 是 Host API v1 实现。

func New

func New(config Config) *Service

func (*Service) BindCapabilitySource

func (s *Service) BindCapabilitySource(source CapabilitySource)

BindCapabilitySource 在 bootstrap 二阶段注入(避免与 Extensions.Service 循环构造)。

func (*Service) BindExtensionInventory

func (s *Service) BindExtensionInventory(source ExtensionInventoryReader)

BindExtensionInventory 在 bootstrap 二阶段注入去敏清单源。

func (*Service) BindPermissions

func (s *Service) BindPermissions(checker PermissionChecker)

BindPermissions 注入权限查询。

func (*Service) BindPluginJobAdmission

func (s *Service) BindPluginJobAdmission(admission PluginJobEnqueueAdmission)

BindPluginJobAdmission 在 runtime 构造完成后接入 exact-instance admission。

func (*Service) BindServiceProviderAdmission

func (s *Service) BindServiceProviderAdmission(admission ServiceProviderAdmission)

BindServiceProviderAdmission 在 runtime 构造完成后接入 exact-instance service admission。

func (*Service) BindUsers

func (s *Service) BindUsers(reader UserReader)

BindUsers 注入安全用户读取。

func (*Service) Call

func (s *Service) Call(ctx context.Context, req Request) Response

Call 执行一次 Host API 调用。

type ServiceAuthorityDecision

type ServiceAuthorityDecision struct {
	Allowed  bool
	Required []string
	Granted  []string
	Missing  []string
}

ServiceAuthorityDecision is deterministic and safe to include in audit data.

func CheckServiceAuthority

func CheckServiceAuthority(required, granted []string) ServiceAuthorityDecision

type ServiceBidiStream

type ServiceBidiStream interface {
	Context() context.Context
	Send(*protocolv2.TypedDocument) error
	Recv() (*protocolv2.TypedDocument, error)
	CloseSend() error
}

ServiceBidiStream is the transport-neutral stream after the Host has consumed and validated the opening frame. Context cancellation must interrupt Recv.

type ServiceCaller

type ServiceCaller struct {
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	TrustGrantID     string
	RuntimeEpoch     uint64
	InstanceID       string
	GrantedAuthority []string
	Attested         bool
}

ServiceCaller carries the broker-attested exact identity and authority used by both dependency admission and provider authority checks.

type ServiceCapability

type ServiceCapability struct {
	ID      string
	Version string
}

type ServiceConflict

type ServiceConflict struct {
	ServiceID  string
	Version    string
	Candidates []ServiceRegistration
}

ServiceConflict keeps every deterministic candidate for operator inspection.

type ServiceDependency

type ServiceDependency struct {
	ExtensionID       string
	Capability        string
	VersionConstraint string
	Kind              string
}

ServiceDependency is the exact runtime copy of one callable manifest edge. Conflict/provides declarations are represented separately because they do not grant a caller permission to invoke a provider.

type ServiceDependencyDecision

type ServiceDependencyDecision struct {
	Allowed           bool
	Reason            string
	DependencyTarget  string
	VersionConstraint string
	ProviderVersion   string
	Candidates        []string
}

type ServiceExtensionSnapshot

type ServiceExtensionSnapshot struct {
	Revision      uint64
	ExtensionID   string
	InstanceID    string
	Registrations []ServiceRegistration
}

ServiceExtensionSnapshot is a caller-owned view of one extension's complete exact-runtime service set. An extension with no declared services has no snapshot entry; the immutable Manifest remains the authority for that case.

type ServiceProvider

ServiceProvider invokes one unary plugin service. ErrorDetail represents a remote application failure, while error is reserved for broker/transport failures that the Host should expose as unavailable.

type ServiceProviderAdmission

type ServiceProviderAdmission interface {
	AcquireServiceProvider(context.Context, ServiceProviderIdentity) (ServiceProviderAdmissionLease, error)
}

type ServiceProviderAdmissionLease

type ServiceProviderAdmissionLease interface {
	Context() context.Context
	Release()
}

ServiceProviderAdmissionLease 覆盖一次 unary 调用或完整 provider stream。

type ServiceProviderAdmissionLeaseFailure

type ServiceProviderAdmissionLeaseFailure interface {
	ServiceProviderAdmissionFailure() error
}

ServiceProviderAdmissionLeaseFailure 由 runtime adapter 区分 caller 取消和强制 drain。

type ServiceProviderIdentity

type ServiceProviderIdentity struct {
	ExtensionID string
	InstanceID  string
}

ServiceProviderIdentity 固定 registry Winner 对应的 exact runtime。

type ServiceRegistration

type ServiceRegistration struct {
	ExtensionID string
	InstanceID  string
	Action      string
	TargetID    string
	Priority    int
	Descriptor  *protocolv2.ServiceDescriptor
	Provider    ServiceProvider
}

ServiceRegistration joins one handshake descriptor with its exact runtime instance and Manifest composition metadata.

type ServiceRegistry

type ServiceRegistry struct {
	// contains filtered or unexported fields
}

ServiceRegistry publishes immutable read snapshots. A failed extension replacement never changes the active snapshot or revision.

func NewServiceRegistry

func NewServiceRegistry() *ServiceRegistry

func (*ServiceRegistry) AcquireRuntimeSet

func (r *ServiceRegistry) AcquireRuntimeSet(publications []ServiceRuntimePublication) (*ServiceRuntimeSetLease, error)

AcquireRuntimeSet verifies the exact complete graph and holds the writer boundary until Release. Lock-free readers continue using the immutable snapshot while raw lifecycle writers wait for the coordinated commit.

func (*ServiceRegistry) AcquireRuntimeSetContext

func (r *ServiceRegistry) AcquireRuntimeSetContext(ctx context.Context, publications []ServiceRuntimePublication) (*ServiceRuntimeSetLease, error)

AcquireRuntimeSetContext verifies and pins the exact complete graph while allowing a queued writer-fence wait to stop with the caller context.

func (*ServiceRegistry) Conflicts

func (r *ServiceRegistry) Conflicts() []ServiceConflict

func (*ServiceRegistry) ExtensionSnapshot

func (r *ServiceRegistry) ExtensionSnapshot(extensionID string) (ServiceExtensionSnapshot, bool, error)

func (*ServiceRegistry) List

func (r *ServiceRegistry) List(serviceID, versionConstraint string) ([]ResolvedService, error)

List returns one effective provider for each matching service/version pair. Results are sorted by service id, version descending, then provider order.

func (*ServiceRegistry) PrepareRuntimeSet

func (r *ServiceRegistry) PrepareRuntimeSet(publications []ServiceRuntimePublication) (*ServiceRuntimeSetTransaction, error)

PrepareRuntimeSet validates the complete desired Protocol V2 runtime set. The resulting transaction replaces every runtime, dependency and service registration in the registry; omitted extensions are deliberately removed.

func (*ServiceRegistry) ReplaceExtension

func (r *ServiceRegistry) ReplaceExtension(extensionID string, registrations []ServiceRegistration) error

ReplaceExtension validates the complete contribution set before atomically replacing every service owned by extensionID.

func (*ServiceRegistry) ReplaceRuntime

func (r *ServiceRegistry) ReplaceRuntime(publication ServiceRuntimePublication) error

ReplaceRuntime validates and atomically publishes one runtime's identity, dependency contract, capabilities, and complete service set.

func (*ServiceRegistry) ReplaceRuntimeSet

func (r *ServiceRegistry) ReplaceRuntimeSet(publications []ServiceRuntimePublication) error

ReplaceRuntimeSet is the one-shot complete-set compatibility entrypoint. Callers that coordinate other registries should use PrepareRuntimeSet and defer Commit until their remaining validation has succeeded.

func (*ServiceRegistry) ReplaceRuntimeSetContext

func (r *ServiceRegistry) ReplaceRuntimeSetContext(ctx context.Context, publications []ServiceRuntimePublication) error

ReplaceRuntimeSetContext is the cancellable complete-set compatibility entrypoint. Cancellation only applies before the immutable snapshot swap.

func (*ServiceRegistry) Resolve

func (r *ServiceRegistry) Resolve(serviceID, versionConstraint string) (ResolvedService, error)

Resolve selects the highest matching semantic version and then the deterministic provider winner for that exact version.

func (*ServiceRegistry) ResolveExact

func (r *ServiceRegistry) ResolveExact(serviceID, version string) (ResolvedService, error)

ResolveExact matches the descriptor's original version string. SemVer constraints deliberately ignore build metadata for precedence, but an invocation is artifact-facing and must not cross build identities.

func (*ServiceRegistry) Revision

func (r *ServiceRegistry) Revision() uint64

func (*ServiceRegistry) RuntimeSetMatches

func (r *ServiceRegistry) RuntimeSetMatches(publications []ServiceRuntimePublication) (bool, error)

RuntimeSetMatches verifies the complete exact runtime graph without changing the revision. It is used by idempotent full-set convergence after ambiguous acknowledgements or instance-bound compensation.

func (*ServiceRegistry) UnregisterExtension

func (r *ServiceRegistry) UnregisterExtension(extensionID string) bool

UnregisterExtension atomically removes one runtime's complete service set. It returns false without advancing the revision when nothing was registered.

func (*ServiceRegistry) UnregisterProtocolV2ServiceInstance

func (r *ServiceRegistry) UnregisterProtocolV2ServiceInstance(extensionID, instanceID string) bool

UnregisterProtocolV2ServiceInstance removes an extension's complete service set only when it still belongs to instanceID. This prevents a stale runtime shutdown from removing the replacement runtime's registrations.

type ServiceRuntimePublication

type ServiceRuntimePublication struct {
	ExtensionID      string
	ExtensionVersion string
	ArtifactDigest   string
	TrustGrantID     string
	RuntimeEpoch     uint64
	InstanceID       string
	Dependencies     []ServiceDependency
	Provides         []ServiceCapability
	Registrations    []ServiceRegistration
}

ServiceRuntimePublication atomically binds discovery registrations to the caller/provider identity and dependency graph frozen at process startup.

type ServiceRuntimeSetLease

type ServiceRuntimeSetLease struct {
	// contains filtered or unexported fields
}

ServiceRuntimeSetLease prevents service writers from changing a verified complete runtime graph while another host-owned registry commit finishes.

func (*ServiceRuntimeSetLease) Release

func (l *ServiceRuntimeSetLease) Release()

func (*ServiceRuntimeSetLease) ReplaceRuntimeSet

func (l *ServiceRuntimeSetLease) ReplaceRuntimeSet(publications []ServiceRuntimePublication) error

ReplaceRuntimeSet swaps to another complete graph without releasing the writer fence. It is the rollback half of an aggregate runtime transition.

type ServiceRuntimeSetTransaction

type ServiceRuntimeSetTransaction struct {
	// contains filtered or unexported fields
}

ServiceRuntimeSetTransaction is a validated, complete desired runtime graph. Preparing never changes reader visibility; Commit publishes one immutable snapshot only when no independent writer changed the captured base graph.

func (*ServiceRuntimeSetTransaction) Abort

func (t *ServiceRuntimeSetTransaction) Abort()

Abort closes a prepared transaction without changing the active snapshot. It is safe to call more than once and after a failed Commit.

func (*ServiceRuntimeSetTransaction) Commit

func (t *ServiceRuntimeSetTransaction) Commit() error

Commit publishes the prepared graph at one revision. A stale transaction fails closed and leaves the independently published graph untouched.

func (*ServiceRuntimeSetTransaction) CommitAndAcquire

func (t *ServiceRuntimeSetTransaction) CommitAndAcquire() (*ServiceRuntimeSetLease, error)

CommitAndAcquire publishes the prepared graph and retains the registry writer fence. The caller must Release the returned lease.

func (*ServiceRuntimeSetTransaction) CommitAndAcquireContext

func (t *ServiceRuntimeSetTransaction) CommitAndAcquireContext(ctx context.Context) (*ServiceRuntimeSetLease, error)

CommitAndAcquireContext publishes the graph and retains the writer fence. A canceled waiter leaves the transaction reusable until Abort is called.

func (*ServiceRuntimeSetTransaction) CommitContext

func (t *ServiceRuntimeSetTransaction) CommitContext(ctx context.Context) error

CommitContext publishes the prepared graph unless the writer-fence wait is canceled first.

type ServiceStreamingProvider

type ServiceStreamingProvider interface {
	Stream(context.Context, *protocolv2.RequestContext, string, string, string, ServiceBidiStream) (*protocolv2.ErrorDetail, error)
}

ServiceStreamingProvider forwards a validated bidirectional service stream. As with Invoke, ErrorDetail is a remote failure and error is a transport failure. CloseSend preserves the caller's half-close across the broker.

type SettingsStore

type SettingsStore interface {
	ListSettings(ctx context.Context, extensionID string) (map[string]string, error)
}

SettingsStore 读写扩展自身 settings。

type ShortcodePolicyProjection

type ShortcodePolicyProjection struct {
	// contains filtered or unexported fields
}

ShortcodePolicyProjection executes the frozen M4 projections for Host-owned protected-shortcode policy. It does not expose the Query Registry outlet to plugins and never caches actor-sensitive rows.

func NewPostgresShortcodePolicyProjection

func NewPostgresShortcodePolicyProjection(pool *pgxpool.Pool) *ShortcodePolicyProjection

func (*ShortcodePolicyProjection) AuthorDecision

func (p *ShortcodePolicyProjection) AuthorDecision(
	ctx context.Context,
	actorUserID int64,
	resourceType string,
	resourceID int64,
) (authenticated, resourceAuthor, topicAuthor, found bool, err error)

func (*ShortcodePolicyProjection) PublicCommentTopicID

func (p *ShortcodePolicyProjection) PublicCommentTopicID(ctx context.Context, commentID int64) (int64, bool, error)

func (*ShortcodePolicyProjection) ReplyEligibility

func (p *ShortcodePolicyProjection) ReplyEligibility(
	ctx context.Context,
	actorUserID int64,
	topicID int64,
) (authenticated, eligible, found bool, err error)

type TrustLevelQuerySource

type TrustLevelQuerySource interface {
	TrustLevelCatalog(ctx context.Context) ([]map[string]any, error)
	UserTrustLevel(ctx context.Context, userID int64) ([]map[string]any, error)
}

TrustLevelQuerySource 是两条信任等级 HostQuery(M4b-3)的读面。

为什么是「计算」而不是视图查询:见 knowledge/decisions/2026-11-14-hostquery-computed-definitions.md。 一句话——档位目录只存在于 web_options 的 trust.levels 单键 JSON 里, 而单用户等级必须现算(账本 user_trust_levels 是快照,不是权威)。

它返回**未归一化**的行(字段名 → 值):归一化、投影、分页、schema 校验都由 执行器统一做,这一层不许自己造响应。

func NewTrustLevelQuerySource

func NewTrustLevelQuerySource(
	resolver *trustlevels.Resolver,
	optionService *options.Service,
	pool *pgxpool.Pool,
) TrustLevelQuerySource

NewTrustLevelQuerySource 构造读面。resolver 必须与 HTTP 装载路径同一个实例, 否则同一个人会在两条路径上得到两个答案(D22)。

type UserReader

type UserReader interface {
	// GetUserSafe 返回非密钥用户字段;不存在时 ErrNotFound。
	// actorUserID 与 declaredFields 用于扩展用户字段的实时权限与 Schema 校验;
	// 核心字段不依赖 actor。无 actor 的扩展字段读取必须失败关闭。
	GetUserSafe(ctx context.Context, userID int64, actorUserID int64, declaredFields []string) (map[string]any, error)
}

UserReader 读取安全用户字段。

type VersionedPluginJobEnqueuer

type VersionedPluginJobEnqueuer interface {
	EnqueueVersionedPluginJob(context.Context, supportjobs.PluginJobContract, string, map[string]any) error
}

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL