docs(spec): annotate schema-only event/subscription/connector enums as not-yet-enforced (#3197)#3212
Merged
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 102 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
…s not-yet-enforced (#3197) Per-surface confirmation of the #3197 audit, then option (c) for every surviving row: explicit 'not yet enforced / not yet implemented' notes in the schemas' doc comments and .describe() texts, plus regenerated reference docs. No runtime behavior or schema shape changes. - GraphQLSubscriptionConfigSchema: no subscription transport; HTTP entry serves query/mutation only - websocket.zod.ts module + WebSocketMessageType: no WS server mounted (#2462); future wire contract - RealtimeEventType: zero runtime importers; engine emits data.record.* literals that don't match the enum; field.changed never emitted - connector.zod.ts webhooks/triggers: registerConnector reads only actions; events/trigger defs parse but are never dispatched or polled - trigger-registry.zod.ts ConnectorTriggerSchema/TriggerRegistrySchema: unconsumed; 'stream' exists only here - NotificationChannelSchema + NotificationChannel contract type: implemented channels are inbox/email/sms; others dead-letter; enum says 'in-app' but the registered channel id is 'inbox' SubscriptionEventType (audit row 5) was already removed by the feed-contract retirement (#1959) — nothing left to annotate. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ToaDWi9wbS2cHNWVyqgkrL
os-zhuang
force-pushed
the
claude/enum-audit-schema-only-9b28ed
branch
from
July 18, 2026 13:29
42bf3a7 to
e439ab2
Compare
os-zhuang
marked this pull request as ready for review
July 18, 2026 13:29
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
概述
处理 #3197(PD #10 events 枚举审计的伞形跟踪 issue)。按 issue 要求先逐面确认了六条审计线索(全部在当前 main 上重新验证),然后对每个存续的 surface 采用选项 (c):在 schema 的文档注释和
.describe()中加入明确的「尚未实现 / 尚未强制执行」说明,使作者不再被静默吞掉的元数据误导。不改变任何运行时行为或 schema 形状,纯文档性变更。逐面确认结果
api/graphql.zod.ts)GraphQLSubscriptionConfigSchema无任何运行时 importer;HTTP 入口仅处理 query/mutation(kernel.graphql未赋值时 501),无订阅传输层events的.describe()注明integration/connector.zod.ts)AutomationEngine.registerConnector(engine.ts:873-891)只读parsed.actions,webhooks解析后整体存储但从不派发WebhookConfigSchemaJSDoc +events/webhooks字段.describe()注明connector.zod.ts:546只有polling/webhook;stream只存在于trigger-registry.zod.ts:367)。def.triggers无行为性消费者,唯一运行时触点是 ADR-0097 §5 的 authoring-time 拒绝规则ConnectorTriggerSchemaJSDoc +triggers字段.describe()注明RealtimeEventType(api/realtime.zod.ts)data.record.created/updated/deleted(与本枚举成员record.*甚至不匹配);field.changed从未被发出.describe()注明data/subscription.zod.ts)SubscriptionEventType/RecordSubscriptionSchema已随 feed 契约退役(#1959)整体删除,无需处理。存续的NotificationChannelSchema(现位于system/notification.zod.ts)确认:实际注册的投递通道仅inbox/email/sms;push/slack/teams/webhook无实现,未注册通道会被 dispatcher 死信api/websocket.zod.ts)websockets: false;handleUpgrade刻意未实现,#2462;conformance 测试主动断言无传输层)WebSocketMessageTypeJSDoc 注明顺带发现(供后续决策,未在本 PR 内动)
NotificationChannelSchema命名漂移:枚举含in-app,而 service-messaging 实际注册的通道 id 是inbox(且inbox不在枚举中)。将来把该枚举接入运行时前需要先对齐。已写入注释。RealtimeEventType的成员命名(record.*)与实际发出的事件名(data.record.*,来自DataEventType)不一致 — 将来若要接线,大概率应直接收敛到DataEventType而不是保留两套。验证
pnpm gen:schema/gen:docs/gen:api-surface/gen:spec-changes已重新生成,check:docs/check:api-surface/check:spec-changes全部通过。@objectstack/specpatch changeset。Closes #3197 的选项 (c) 路径;若维护者希望对某个 surface 改走 (a) 实现或 (b) 裁剪,可在该 issue 上按面拆分后续任务。
🤖 Generated with Claude Code
https://claude.ai/code/session_01ToaDWi9wbS2cHNWVyqgkrL
Generated by Claude Code