@ricajs/contracts 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/LICENSE +661 -0
  2. package/README.md +153 -2
  3. package/action-review.d.ts +120 -0
  4. package/action-review.js +40 -0
  5. package/auto-review.d.ts +32 -0
  6. package/auto-review.js +14 -0
  7. package/commitments.d.ts +87 -0
  8. package/commitments.js +33 -0
  9. package/deployment-plugins.d.ts +7 -0
  10. package/deployment-plugins.js +2 -0
  11. package/health.d.ts +7 -0
  12. package/health.js +1 -0
  13. package/local-users.d.ts +17 -0
  14. package/local-users.js +6 -0
  15. package/management.d.ts +640 -0
  16. package/management.js +235 -0
  17. package/memory.d.ts +14 -0
  18. package/memory.js +1 -0
  19. package/model-provider.d.ts +40 -0
  20. package/model-provider.js +10 -0
  21. package/package.json +93 -3
  22. package/plans.d.ts +50 -0
  23. package/plans.js +20 -0
  24. package/platform-reader.d.ts +26 -0
  25. package/platform-reader.js +9 -0
  26. package/platform-reply-executor.d.ts +13 -0
  27. package/platform-reply-executor.js +3 -0
  28. package/plugin-status.d.ts +277 -0
  29. package/plugin-status.js +54 -0
  30. package/run-continuity.d.ts +84 -0
  31. package/run-continuity.js +1 -0
  32. package/schedules.d.ts +46 -0
  33. package/schedules.js +18 -0
  34. package/simulation-follow-up.d.ts +35 -0
  35. package/simulation-follow-up.js +29 -0
  36. package/simulation-observability.d.ts +223 -0
  37. package/simulation-observability.js +85 -0
  38. package/simulation-platform.d.ts +33 -0
  39. package/simulation-platform.js +7 -0
  40. package/source/action-review.ts +45 -0
  41. package/source/auto-review.ts +22 -0
  42. package/source/commitments.ts +39 -0
  43. package/source/deployment-plugins.ts +4 -0
  44. package/source/health.ts +4 -0
  45. package/source/local-users.ts +8 -0
  46. package/source/management.ts +246 -0
  47. package/source/memory.ts +15 -0
  48. package/source/model-provider.ts +29 -0
  49. package/source/package.json +43 -0
  50. package/source/plans.ts +22 -0
  51. package/source/platform-reader.ts +27 -0
  52. package/source/platform-reply-executor.ts +10 -0
  53. package/source/plugin-status.ts +67 -0
  54. package/source/run-continuity.ts +60 -0
  55. package/source/schedules.ts +22 -0
  56. package/source/simulation-follow-up.ts +35 -0
  57. package/source/simulation-observability.ts +94 -0
  58. package/source/simulation-platform.ts +39 -0
@@ -0,0 +1,94 @@
1
+ import { z } from '@hono/zod-openapi'
2
+
3
+ import { listQuery, resourceId } from './management.js'
4
+ import { maxSimulatedTextLength } from './model-provider.js'
5
+
6
+ const timestamp = z.iso.datetime({ offset: true })
7
+ export const consoleSimulationInput = z.strictObject({
8
+ accountId: resourceId,
9
+ message: z.string().trim().min(1).max(maxSimulatedTextLength).refine((value) => !value.includes('\0')),
10
+ })
11
+ export const simulationRunQuery = listQuery.extend({
12
+ state: z.enum(['QUEUED', 'CONTEXT_READY', 'DRAFTED', 'CANCELED', 'WAITING_APPROVAL', 'READY', 'REJECTED',
13
+ 'EXPIRED', 'EXECUTING', 'RECONCILING', 'SIMULATED', 'BLOCKED']).optional(),
14
+ identityId: resourceId.optional(),
15
+ accountId: resourceId.optional(),
16
+ from: z.iso.date().optional(),
17
+ through: z.iso.date().optional(),
18
+ }).refine(({ from, through }) => (!from || from >= '0001-01-01') && (!through || through >= '0001-01-01')
19
+ && (!from || !through || from <= through), 'Choose a valid inclusive UTC date range')
20
+
21
+ export const simulationRunSummary = z.object({
22
+ id: resourceId, state: z.string(), identityId: resourceId, accountId: resourceId,
23
+ platform: z.string(), createdAt: timestamp,
24
+ })
25
+ const evidence = z.discriminatedUnion('available', [
26
+ z.object({ rank: z.number().int(), available: z.literal(true), memoryId: z.uuid(), revision: z.number().int() }),
27
+ z.object({ rank: z.number().int(), available: z.literal(false) }),
28
+ ])
29
+
30
+ export const runReplayView = z.object({
31
+ id: z.uuid(), state: z.string(), stateVersion: z.number().int(), stateReason: z.string().nullable(),
32
+ mode: z.literal('SIMULATION'), identityId: z.uuid(), accountId: z.uuid(),
33
+ coreVersion: z.number().int(), identityVersion: z.number().int(),
34
+ bindingVersion: z.number().int(), authEpoch: z.number().int(),
35
+ occurredAt: timestamp, createdAt: timestamp, contextTimezone: z.string().nullable(),
36
+ inbound: z.object({ kind: z.enum(['POST', 'REPLY', 'MENTION']), receivedAt: timestamp }),
37
+ draft: z.object({ createdAt: timestamp, modelId: z.string().nullable(), modelVersion: z.string().nullable() }).nullable(),
38
+ systemPrompts: z.object({ core: z.string().nullable(), identity: z.string().nullable() }).nullable(),
39
+ transcript: z.object({ message: z.string(), draft: z.string().nullable(), reviewReason: z.string() }).nullable(),
40
+ goalRefs: z.array(z.object({ id: z.uuid(), version: z.number().int() })),
41
+ referencesExpiredAt: timestamp.nullable(),
42
+ beliefRefs: z.array(z.object({ id: z.uuid(), version: z.number().int() })).max(8),
43
+ snapshots: z.array(z.object({
44
+ id: z.uuid(), purpose: z.enum(['INTERNAL_CONTEXT', 'DECISION_SUPPORT', 'PUBLIC_REFERENCE', 'PRIVATE_REPLY']),
45
+ rankingVersion: z.number().int(), createdAt: timestamp, evidence: z.array(evidence),
46
+ })),
47
+ proposal: z.object({
48
+ id: z.uuid(), policyVersion: z.number().int(), adapterId: z.string(), adapterVersion: z.string(),
49
+ adapterContractVersion: z.number().int().positive(),
50
+ modelId: z.string().nullable(), modelVersion: z.string().nullable(),
51
+ createdAt: timestamp, reviewedAt: timestamp.nullable(), permittedAt: timestamp.nullable(),
52
+ reviewDecision: z.enum(['APPROVE', 'REJECT']).nullable(),
53
+ attemptStatus: z.enum(['PERMITTED', 'UNKNOWN', 'CONFIRMED', 'NOT_SENT']).nullable(), receiptAt: timestamp.nullable(),
54
+ }).nullable(),
55
+ schedule: z.object({
56
+ scheduleId: z.uuid(), scheduleVersion: z.number().int(), scheduledAt: timestamp, commitmentId: z.uuid().nullable(),
57
+ }).nullable(),
58
+ })
59
+
60
+ export const dailyMetricsQuery = z.object({ from: z.iso.date(), through: z.iso.date() }).refine(({ from, through }) => {
61
+ const span = Date.parse(through) - Date.parse(from)
62
+ return from >= '0001-01-01' && span >= 0 && span <= 30 * 86_400_000
63
+ }, 'Choose an inclusive range of up to 31 UTC days')
64
+
65
+ const count = z.number().int().nonnegative()
66
+ export const simulationDailyRow = z.object({
67
+ utcDay: z.iso.date(), proposals: count, approvals: count, rejections: count, duplicateFlags: count,
68
+ draftLatencyMs: count.nullable(), receipts: count, peakAccountReceipts: count, flaggedReceipts: count,
69
+ receiptsWithoutApproval: count, reservedUnits: count, modelCalls: count, budgetDenials: count,
70
+ })
71
+ export const simulationDailyMetricsView = z.object({
72
+ days: z.array(simulationDailyRow).max(31),
73
+ alerts: z.array(z.enum(['FLAGGED_RECEIPTS', 'UNAPPROVED_RECEIPTS', 'MODEL_BUDGET_EXHAUSTED',
74
+ 'RECEIPT_VOLUME_DRIFT', 'REVIEW_RATE_DRIFT'])),
75
+ })
76
+
77
+ export const outboxQuarantineQuery = z.object({ after: z.uuid().optional() })
78
+ export const quarantinedOutboxEvent = z.object({
79
+ id: z.uuid(), runId: z.uuid(), type: z.enum(['RunQueued.v1', 'SimulatedDraftQueued.v1']),
80
+ generation: z.number().int().nonnegative(), attempts: z.literal(4), quarantinedAt: timestamp,
81
+ })
82
+ export const outboxQuarantineView = z.object({
83
+ items: z.array(quarantinedOutboxEvent), nextCursor: z.uuid().nullable(),
84
+ })
85
+
86
+ const backlog = z.object({ count: z.number().int().nonnegative(), oldestAt: timestamp.nullable() })
87
+
88
+ export const simulationBacklogView = z.object({
89
+ observedAt: timestamp,
90
+ outbox: backlog.extend({ enqueued: count, quarantined: count }),
91
+ approvals: backlog,
92
+ reconciliation: backlog,
93
+ schedules: backlog,
94
+ })
@@ -0,0 +1,39 @@
1
+ import { z } from '@hono/zod-openapi'
2
+ import type { Plugin } from '@ricajs/plugin-host'
3
+
4
+ export const simulationPlatformId = z.enum(['mock-a', 'mock-b'])
5
+ export const isSimulationPlatform = (platform: string) => simulationPlatformId.safeParse(platform).success
6
+
7
+ export type NormalizedPlatformEvent = Readonly<{
8
+ remoteAccountId: string
9
+ remoteConversationKey: string
10
+ remoteContactKey?: string
11
+ sourceKey: string
12
+ messageText: string
13
+ kind: 'POST' | 'REPLY' | 'MENTION'
14
+ occurredAt: Date
15
+ }>
16
+
17
+ export type PlatformAdapter = Readonly<{
18
+ normalize(payload: unknown): NormalizedPlatformEvent
19
+ }>
20
+
21
+ export type ResolveSimulationPlatform = (id: string) => Plugin<PlatformAdapter> | undefined
22
+ type SimulationAdapterBinding = Readonly<{
23
+ adapterId: string
24
+ adapterVersion: string
25
+ adapterContractVersion: number
26
+ }>
27
+
28
+ type ActiveSimulationAdapter = Readonly<{
29
+ adapterId: string
30
+ adapterVersion: string
31
+ adapterContractVersion: number
32
+ }>
33
+
34
+ export type ResolveSimulationAdapter = (platformId: string) => ActiveSimulationAdapter | undefined
35
+
36
+ export function matchesSimulationAdapter(expected: SimulationAdapterBinding, actual: ActiveSimulationAdapter | undefined) {
37
+ return actual !== undefined && expected.adapterId === actual.adapterId
38
+ && expected.adapterVersion === actual.adapterVersion && expected.adapterContractVersion === actual.adapterContractVersion
39
+ }