@adea-ai/contracts 3.0.0 → 3.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.
@@ -0,0 +1,128 @@
1
+ import { z } from 'zod';
2
+ export declare const DeviceSyncErrorCodeSchema: z.ZodEnum<{
3
+ SYNC_AUTHOR_REVOKED: "SYNC_AUTHOR_REVOKED";
4
+ SYNC_AUTHOR_UNKNOWN: "SYNC_AUTHOR_UNKNOWN";
5
+ SYNC_BLOB_INVALID: "SYNC_BLOB_INVALID";
6
+ SYNC_BLOB_TOO_LARGE: "SYNC_BLOB_TOO_LARGE";
7
+ SYNC_DECRYPTION_FAILED: "SYNC_DECRYPTION_FAILED";
8
+ SYNC_ENTRY_CONFLICT: "SYNC_ENTRY_CONFLICT";
9
+ SYNC_ENTRY_INVALID: "SYNC_ENTRY_INVALID";
10
+ SYNC_ENTRY_TOO_LARGE: "SYNC_ENTRY_TOO_LARGE";
11
+ SYNC_KEY_UNAVAILABLE: "SYNC_KEY_UNAVAILABLE";
12
+ SYNC_LOG_ROLLED_BACK: "SYNC_LOG_ROLLED_BACK";
13
+ SYNC_OBJECT_CONFLICT: "SYNC_OBJECT_CONFLICT";
14
+ SYNC_OBJECT_NOT_COMMITTED: "SYNC_OBJECT_NOT_COMMITTED";
15
+ SYNC_QUOTA_EXCEEDED: "SYNC_QUOTA_EXCEEDED";
16
+ SYNC_REQUEST_EXPIRED: "SYNC_REQUEST_EXPIRED";
17
+ SYNC_REQUEST_INVALID: "SYNC_REQUEST_INVALID";
18
+ SYNC_SIGNATURE_INVALID: "SYNC_SIGNATURE_INVALID";
19
+ SYNC_UNAVAILABLE: "SYNC_UNAVAILABLE";
20
+ }>;
21
+ export type DeviceSyncErrorCode = z.infer<typeof DeviceSyncErrorCodeSchema>;
22
+ /** The largest sealed log entry plaintext. */
23
+ export declare const MAX_SYNC_ENTRY_BYTES: number;
24
+ /** Entries per append and object ids per download or release. */
25
+ export declare const MAX_SYNC_BATCH = 100;
26
+ export declare const MAX_SYNC_LOG_PAGE = 500;
27
+ /** The smallest sealed object: a 12-byte header, the 8-byte length prefix and one 16-byte tag. */
28
+ export declare const MIN_SYNC_CIPHERTEXT_BYTES = 36;
29
+ /** The sealed size of the largest (256 MiB) object; device-sync tests pin it to the blob format. */
30
+ export declare const MAX_SYNC_CIPHERTEXT_BYTES = 276828300;
31
+ export declare const SyncAuthorKeyIdSchema: z.ZodString;
32
+ export declare const SyncObjectIdSchema: z.ZodString;
33
+ export declare const SyncEntryIdSchema: z.ZodString;
34
+ /** What the server stores and serves for one entry, signed by its author over these fields. */
35
+ export declare const SignedSyncEntrySchema: z.ZodObject<{
36
+ entryId: z.ZodString;
37
+ authorKeyId: z.ZodString;
38
+ objectIds: z.ZodArray<z.ZodString>;
39
+ ckv: z.ZodNumber;
40
+ nonce: z.ZodString;
41
+ ciphertext: z.ZodString;
42
+ signature: z.ZodString;
43
+ }, z.core.$strict>;
44
+ export type SignedSyncEntry = z.infer<typeof SignedSyncEntrySchema>;
45
+ export declare const StoredSyncEntrySchema: z.ZodObject<{
46
+ entryId: z.ZodString;
47
+ authorKeyId: z.ZodString;
48
+ objectIds: z.ZodArray<z.ZodString>;
49
+ ckv: z.ZodNumber;
50
+ nonce: z.ZodString;
51
+ ciphertext: z.ZodString;
52
+ signature: z.ZodString;
53
+ seq: z.ZodNumber;
54
+ createdAt: z.ZodISODateTime;
55
+ }, z.core.$strict>;
56
+ export type StoredSyncEntry = z.infer<typeof StoredSyncEntrySchema>;
57
+ export declare const SyncUploadRequestSchema: z.ZodObject<{
58
+ objectId: z.ZodString;
59
+ size: z.ZodNumber;
60
+ ciphertextSha256: z.ZodString;
61
+ }, z.core.$strict>;
62
+ export declare const SyncUploadResponseSchema: z.ZodObject<{
63
+ objectId: z.ZodString;
64
+ url: z.ZodURL;
65
+ headers: z.ZodRecord<z.ZodString, z.ZodString>;
66
+ expiresAt: z.ZodISODateTime;
67
+ }, z.core.$strict>;
68
+ export declare const SyncObjectRequestSchema: z.ZodObject<{
69
+ objectId: z.ZodString;
70
+ }, z.core.$strict>;
71
+ export declare const SyncCommitResponseSchema: z.ZodObject<{
72
+ objectId: z.ZodString;
73
+ size: z.ZodNumber;
74
+ }, z.core.$strict>;
75
+ export declare const SyncDownloadRequestSchema: z.ZodObject<{
76
+ objectIds: z.ZodArray<z.ZodString>;
77
+ }, z.core.$strict>;
78
+ export declare const SyncDownloadResponseSchema: z.ZodObject<{
79
+ downloads: z.ZodArray<z.ZodObject<{
80
+ objectId: z.ZodString;
81
+ url: z.ZodURL;
82
+ size: z.ZodNumber;
83
+ }, z.core.$strict>>;
84
+ missing: z.ZodArray<z.ZodString>;
85
+ expiresAt: z.ZodISODateTime;
86
+ }, z.core.$strict>;
87
+ export declare const SyncReleaseResponseSchema: z.ZodObject<{
88
+ released: z.ZodNumber;
89
+ }, z.core.$strict>;
90
+ export declare const SyncAppendRequestSchema: z.ZodObject<{
91
+ entries: z.ZodArray<z.ZodObject<{
92
+ entryId: z.ZodString;
93
+ authorKeyId: z.ZodString;
94
+ objectIds: z.ZodArray<z.ZodString>;
95
+ ckv: z.ZodNumber;
96
+ nonce: z.ZodString;
97
+ ciphertext: z.ZodString;
98
+ signature: z.ZodString;
99
+ }, z.core.$strict>>;
100
+ }, z.core.$strict>;
101
+ export declare const SyncAppendResponseSchema: z.ZodObject<{
102
+ entries: z.ZodArray<z.ZodObject<{
103
+ entryId: z.ZodString;
104
+ seq: z.ZodNumber;
105
+ }, z.core.$strict>>;
106
+ }, z.core.$strict>;
107
+ export declare const SyncLogRequestSchema: z.ZodObject<{
108
+ afterSeq: z.ZodNumber;
109
+ limit: z.ZodOptional<z.ZodNumber>;
110
+ }, z.core.$strict>;
111
+ export declare const SyncLogPageSchema: z.ZodObject<{
112
+ entries: z.ZodArray<z.ZodObject<{
113
+ entryId: z.ZodString;
114
+ authorKeyId: z.ZodString;
115
+ objectIds: z.ZodArray<z.ZodString>;
116
+ ckv: z.ZodNumber;
117
+ nonce: z.ZodString;
118
+ ciphertext: z.ZodString;
119
+ signature: z.ZodString;
120
+ seq: z.ZodNumber;
121
+ createdAt: z.ZodISODateTime;
122
+ }, z.core.$strict>>;
123
+ headSeq: z.ZodNumber;
124
+ }, z.core.$strict>;
125
+ export declare const SyncUsageSchema: z.ZodObject<{
126
+ usedBytes: z.ZodNumber;
127
+ quotaBytes: z.ZodNumber;
128
+ }, z.core.$strict>;
@@ -0,0 +1,115 @@
1
+ // Encrypted device sync (adea-ai/control-plane#1566): the wire bodies only. Every field is an
2
+ // opaque id, a padded size, an author key id or ciphertext. The crypto lives in
3
+ // @adea-ai/runtime-gateway-protocol/device-sync, which re-exports these schemas; this
4
+ // module has no other import so browser bundles stay small.
5
+ import { z } from 'zod';
6
+ const TimestampSchema = z.iso.datetime();
7
+ export const DeviceSyncErrorCodeSchema = z.enum([
8
+ 'SYNC_BLOB_INVALID',
9
+ 'SYNC_BLOB_TOO_LARGE',
10
+ 'SYNC_DECRYPTION_FAILED',
11
+ 'SYNC_KEY_UNAVAILABLE',
12
+ 'SYNC_ENTRY_INVALID',
13
+ 'SYNC_ENTRY_TOO_LARGE',
14
+ 'SYNC_SIGNATURE_INVALID',
15
+ 'SYNC_AUTHOR_UNKNOWN',
16
+ 'SYNC_AUTHOR_REVOKED',
17
+ 'SYNC_REQUEST_INVALID',
18
+ 'SYNC_REQUEST_EXPIRED',
19
+ 'SYNC_LOG_ROLLED_BACK',
20
+ 'SYNC_QUOTA_EXCEEDED',
21
+ 'SYNC_OBJECT_NOT_COMMITTED',
22
+ 'SYNC_OBJECT_CONFLICT',
23
+ 'SYNC_ENTRY_CONFLICT',
24
+ 'SYNC_UNAVAILABLE',
25
+ ]);
26
+ /** The largest sealed log entry plaintext. */
27
+ export const MAX_SYNC_ENTRY_BYTES = 16 * 1024;
28
+ /** Entries per append and object ids per download or release. */
29
+ export const MAX_SYNC_BATCH = 100;
30
+ export const MAX_SYNC_LOG_PAGE = 500;
31
+ /** The smallest sealed object: a 12-byte header, the 8-byte length prefix and one 16-byte tag. */
32
+ export const MIN_SYNC_CIPHERTEXT_BYTES = 36;
33
+ /** The sealed size of the largest (256 MiB) object; device-sync tests pin it to the blob format. */
34
+ export const MAX_SYNC_CIPHERTEXT_BYTES = 276_828_300;
35
+ const SyncBase64UrlSchema = z
36
+ .string()
37
+ .min(1)
38
+ .regex(/^[A-Za-z0-9_-]+$/);
39
+ export const SyncAuthorKeyIdSchema = z.string().regex(/^(?:spk|dpk)_[a-f0-9]{32}$/);
40
+ export const SyncObjectIdSchema = z.string().regex(/^sob_[a-f0-9]{32}$/);
41
+ export const SyncEntryIdSchema = z.string().regex(/^sen_[a-f0-9]{32}$/);
42
+ const SyncSha256Schema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
43
+ /** What the server stores and serves for one entry, signed by its author over these fields. */
44
+ export const SignedSyncEntrySchema = z
45
+ .object({
46
+ entryId: SyncEntryIdSchema,
47
+ authorKeyId: SyncAuthorKeyIdSchema,
48
+ objectIds: z.array(SyncObjectIdSchema).max(1),
49
+ ckv: z.number().int().min(1),
50
+ nonce: SyncBase64UrlSchema.length(16),
51
+ ciphertext: SyncBase64UrlSchema.max(Math.ceil(((MAX_SYNC_ENTRY_BYTES + 16) * 4) / 3)),
52
+ signature: SyncBase64UrlSchema.length(86),
53
+ })
54
+ .strict();
55
+ export const StoredSyncEntrySchema = SignedSyncEntrySchema.extend({
56
+ seq: z.number().int().min(1),
57
+ createdAt: TimestampSchema,
58
+ }).strict();
59
+ export const SyncUploadRequestSchema = z
60
+ .object({
61
+ objectId: SyncObjectIdSchema,
62
+ size: z.number().int().min(MIN_SYNC_CIPHERTEXT_BYTES).max(MAX_SYNC_CIPHERTEXT_BYTES),
63
+ ciphertextSha256: SyncSha256Schema,
64
+ })
65
+ .strict();
66
+ const PresignedSyncUrlSchema = z.url().max(4096);
67
+ export const SyncUploadResponseSchema = z
68
+ .object({
69
+ objectId: SyncObjectIdSchema,
70
+ url: PresignedSyncUrlSchema,
71
+ headers: z.record(z.string(), z.string()),
72
+ expiresAt: TimestampSchema,
73
+ })
74
+ .strict();
75
+ export const SyncObjectRequestSchema = z.object({ objectId: SyncObjectIdSchema }).strict();
76
+ export const SyncCommitResponseSchema = z
77
+ .object({ objectId: SyncObjectIdSchema, size: z.number().int().min(1) })
78
+ .strict();
79
+ export const SyncDownloadRequestSchema = z
80
+ .object({ objectIds: z.array(SyncObjectIdSchema).min(1).max(MAX_SYNC_BATCH) })
81
+ .strict();
82
+ export const SyncDownloadResponseSchema = z
83
+ .object({
84
+ downloads: z.array(z
85
+ .object({
86
+ objectId: SyncObjectIdSchema,
87
+ url: PresignedSyncUrlSchema,
88
+ size: z.number().int().min(1),
89
+ })
90
+ .strict()),
91
+ missing: z.array(SyncObjectIdSchema),
92
+ expiresAt: TimestampSchema,
93
+ })
94
+ .strict();
95
+ export const SyncReleaseResponseSchema = z.object({ released: z.number().int().min(0) }).strict();
96
+ export const SyncAppendRequestSchema = z
97
+ .object({ entries: z.array(SignedSyncEntrySchema).min(1).max(MAX_SYNC_BATCH) })
98
+ .strict();
99
+ export const SyncAppendResponseSchema = z
100
+ .object({
101
+ entries: z.array(z.object({ entryId: SyncEntryIdSchema, seq: z.number().int().min(1) }).strict()),
102
+ })
103
+ .strict();
104
+ export const SyncLogRequestSchema = z
105
+ .object({
106
+ afterSeq: z.number().int().min(0),
107
+ limit: z.number().int().min(1).max(MAX_SYNC_LOG_PAGE).optional(),
108
+ })
109
+ .strict();
110
+ export const SyncLogPageSchema = z
111
+ .object({ entries: z.array(StoredSyncEntrySchema), headSeq: z.number().int().min(0) })
112
+ .strict();
113
+ export const SyncUsageSchema = z
114
+ .object({ usedBytes: z.number().int().min(0), quotaBytes: z.number().int().min(0) })
115
+ .strict();
package/dist/index.d.ts CHANGED
@@ -5,6 +5,7 @@ export * from './canonical-json.js';
5
5
  export * from './control-api.js';
6
6
  export * from './context-providers.js';
7
7
  export * from './decision-resolution.js';
8
+ export * from './device-sync.js';
8
9
  export * from './envelopes.js';
9
10
  export * from './execution-scope.js';
10
11
  export * from './fixtures.js';
package/dist/index.js CHANGED
@@ -9,6 +9,7 @@ export * from './canonical-json.js';
9
9
  export * from './control-api.js';
10
10
  export * from './context-providers.js';
11
11
  export * from './decision-resolution.js';
12
+ export * from './device-sync.js';
12
13
  export * from './envelopes.js';
13
14
  export * from './execution-scope.js';
14
15
  export * from './fixtures.js';
@@ -1,4 +1,5 @@
1
1
  import { z } from 'zod';
2
+ import { CursorSchema } from './pagination.js';
2
3
  export declare const ModelFundingSourceSchema: z.ZodEnum<{
3
4
  byo_api: "byo_api";
4
5
  external_subscription: "external_subscription";
@@ -165,6 +166,8 @@ export type ModelExecutionTarget = z.output<typeof ModelExecutionTargetSchema>;
165
166
  export type ModelChoice = z.output<typeof ModelChoiceSchema>;
166
167
  export type WorkspaceModelDefaults = z.output<typeof WorkspaceModelDefaultsSchema>;
167
168
  export type ModelReadinessReason = z.output<typeof ModelReadinessReasonSchema>;
169
+ /** The most connections one `model-connections.list` page carries; the default page size. */
170
+ export declare const MODEL_CONNECTIONS_PAGE_MAX = 32;
168
171
  export declare const ModelConnectionListRequestSchema: z.ZodObject<{
169
172
  contractVersion: z.ZodObject<{
170
173
  major: z.ZodNumber;
@@ -201,6 +204,8 @@ export declare const ModelConnectionListRequestSchema: z.ZodObject<{
201
204
  pi_model_runtime: "pi_model_runtime";
202
205
  }>;
203
206
  }, z.core.$strict>;
207
+ limit: z.ZodOptional<z.ZodNumber>;
208
+ cursor: z.ZodOptional<typeof CursorSchema>;
204
209
  }, z.core.$strict>;
205
210
  }, z.core.$strict>;
206
211
  export declare const ModelDefaultsGetRequestSchema: z.ZodObject<{
@@ -378,6 +383,9 @@ export declare const ModelConnectionListResponseSchema: z.ZodObject<{
378
383
  }, z.core.$strict>;
379
384
  }, z.core.$strict>>;
380
385
  }, z.core.$strict>>;
386
+ connectionsPage: z.ZodObject<{
387
+ nextCursor: z.ZodOptional<z.ZodString>;
388
+ }, z.core.$strict>;
381
389
  }, z.core.$strict>;
382
390
  }, z.core.$strict>;
383
391
  export declare const ModelDefaultsResponseSchema: z.ZodObject<{
@@ -2,6 +2,7 @@ import { z } from 'zod';
2
2
  import { ReadRequestEnvelopeSchema, StateChangingCommandEnvelopeSchema, SuccessResponseEnvelopeSchema, } from './envelopes.js';
3
3
  import { ServiceCallerAssertionSchema } from './authentication.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
+ import { CursorSchema } from './pagination.js';
5
6
  const Ref = z
6
7
  .string()
7
8
  .min(1)
@@ -130,9 +131,17 @@ const Read = ReadRequestEnvelopeSchema.omit({ projectId: true }).extend({
130
131
  const Command = StateChangingCommandEnvelopeSchema.omit({ projectId: true }).extend({
131
132
  caller: ServiceCallerAssertionSchema,
132
133
  });
134
+ /** The most connections one `model-connections.list` page carries; the default page size. */
135
+ export const MODEL_CONNECTIONS_PAGE_MAX = 32;
133
136
  export const ModelConnectionListRequestSchema = Read.extend({
134
137
  operation: z.literal('model-connections.list'),
135
- parameters: z.strictObject({ target: ModelExecutionTargetSchema }),
138
+ parameters: z.strictObject({
139
+ target: ModelExecutionTargetSchema,
140
+ // Additive paging of `connections`, in connection-ref order: at most `limit` (default and
141
+ // maximum MODEL_CONNECTIONS_PAGE_MAX) per response, continued with `connectionsPage.nextCursor`.
142
+ limit: z.number().int().min(1).max(MODEL_CONNECTIONS_PAGE_MAX).optional(),
143
+ cursor: CursorSchema.optional(),
144
+ }),
136
145
  }).strict();
137
146
  export const ModelDefaultsGetRequestSchema = Read.extend({
138
147
  operation: z.literal('model-defaults.get'),
@@ -170,7 +179,8 @@ export const ModelConnectionListResponseSchema = SuccessResponseEnvelopeSchema.e
170
179
  }))
171
180
  .max(256),
172
181
  }))
173
- .max(128),
182
+ .max(MODEL_CONNECTIONS_PAGE_MAX),
183
+ connectionsPage: z.strictObject({ nextCursor: CursorSchema.optional() }),
174
184
  }),
175
185
  }).strict();
176
186
  export const ModelDefaultsResponseSchema = SuccessResponseEnvelopeSchema.extend({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/contracts",
3
- "version": "3.0.0",
3
+ "version": "3.1.0",
4
4
  "description": "Runtime-independent service boundary between Adea and the Control Plane: canonical identifiers, envelopes, Control API schemas, pagination, and versioning.",
5
5
  "keywords": [
6
6
  "agents",
@@ -32,11 +32,14 @@
32
32
  "./canonical-json": {
33
33
  "types": "./dist/canonical-json.d.ts",
34
34
  "default": "./dist/canonical-json.js"
35
+ },
36
+ "./device-sync": {
37
+ "types": "./dist/device-sync.d.ts",
38
+ "default": "./dist/device-sync.js"
35
39
  }
36
40
  },
37
41
  "publishConfig": {
38
- "access": "public",
39
- "provenance": true
42
+ "access": "public"
40
43
  },
41
44
  "scripts": {
42
45
  "build": "tsc -p tsconfig.json",