@adea-ai/contracts 5.0.4 → 5.1.1

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.
package/README.md CHANGED
@@ -9,8 +9,9 @@ Plane domain, database, application, workflow, or adapter packages.
9
9
 
10
10
  ## What's inside
11
11
 
12
- - **Canonical identifiers**: opaque, prefix-qualified ULIDs (`req_`, `wsp_`,
13
- `exe_`, …) with validation schemas. Consumers may validate and compare them
12
+ - **Canonical identifiers**: opaque, prefix-qualified identifiers (`req_`, `wsp_`,
13
+ `exe_`, …: a three-letter prefix and 26 Crockford base32 characters) with
14
+ validation schemas in `IdentifierSchemas`. Consumers may validate and compare them
14
15
  but must not derive database keys, timestamps, routing decisions, or
15
16
  vendor-native identifiers from their contents.
16
17
  - **Control API schemas**: request/response contracts for the Control API.
@@ -28,12 +29,21 @@ bun add @adea-ai/contracts
28
29
  ## Usage
29
30
 
30
31
  ```ts
31
- import { EnvelopeSchemas, IdentifierSchemas, PaginationSchemas } from '@adea-ai/contracts'
32
+ import { IdentifierSchemas, PageSchema, ReadRequestEnvelopeSchema } from '@adea-ai/contracts'
32
33
  ```
33
34
 
34
- See [`docs/contracts.md`](../../docs/contracts.md) in the repository for the
35
+ See the [Control API reference](https://adea.dev/docs/reference/control-plane/api/) for the
35
36
  full contract reference, including the identifier prefix table.
36
37
 
38
+ ## Device sync compaction
39
+
40
+ `DeviceSyncCheckpoint*`, `DeviceSyncRegisterCheckpoint*` and `DeviceSyncAck*`
41
+ schemas describe `log/checkpoint`, `log/checkpoint/register` and `log/ack`.
42
+ `DeviceSyncLogRequestSchema` takes an optional `readerKeyId`, which identifies
43
+ the reader for acknowledgements and does not page. New error codes are
44
+ `SYNC_LOG_COMPACTED`, `SYNC_LOG_TRUNCATED`, `SYNC_CHECKPOINT_CONFLICT`,
45
+ `SYNC_CHECKPOINT_INVALID` and `SYNC_AUTHOR_NOT_PRIMARY`.
46
+
37
47
  ## Model funding display
38
48
 
39
49
  `ModelSelectionFunding{Request,Response,View}Schema` and `ModelFundingOwnerSchema`
@@ -51,9 +61,8 @@ Apache-2.0
51
61
  ## Published build compatibility
52
62
 
53
63
  Contracts preserve comments in their emitted JavaScript and declarations. The
54
- package overrides the root `removeComments` optimization so a clean build can
55
- reproduce the published contracts 1.23.1 payload used by strict installed-package
56
- qualification. Other packages retain the root optimization, and the unchanged
64
+ package overrides the root `removeComments` optimization so published
65
+ declarations keep their public documentation. Other packages retain the root optimization, and the unchanged
57
66
  repository distribution ceiling still applies.
58
67
 
59
68
  `src/declaration-emit.test.ts` compiles an isolated public contract through both
@@ -30,6 +30,13 @@
30
30
  * serializing to a lossy or implementation-dependent form.
31
31
  */
32
32
  export declare function canonicalJsonStringify(value: unknown): string;
33
+ /**
34
+ * Whether two values have the same canonical JSON, exactly as
35
+ * `canonicalJsonStringify(left) === canonicalJsonStringify(right)` decides it, including the
36
+ * `TypeError` for values that are not JSON-compatible plain data. Equal plain data is compared in
37
+ * place without building either string; anything else is decided by comparing the strings.
38
+ */
39
+ export declare function canonicalJsonEqual(left: unknown, right: unknown): boolean;
33
40
  /**
34
41
  * Deterministic key comparator: orders strings by Unicode code point,
35
42
  * independent of host locale/ICU. Use anywhere ordering feeds digests,
@@ -32,47 +32,125 @@
32
32
  export function canonicalJsonStringify(value) {
33
33
  return serialize(value);
34
34
  }
35
- function compareCodePoint(left, right) {
36
- return left < right ? -1 : left > right ? 1 : 0;
35
+ /**
36
+ * Whether two values have the same canonical JSON, exactly as
37
+ * `canonicalJsonStringify(left) === canonicalJsonStringify(right)` decides it, including the
38
+ * `TypeError` for values that are not JSON-compatible plain data. Equal plain data is compared in
39
+ * place without building either string; anything else is decided by comparing the strings.
40
+ */
41
+ export function canonicalJsonEqual(left, right) {
42
+ return (sameCanonical(left, right, 0) || canonicalJsonStringify(left) === canonicalJsonStringify(right));
43
+ }
44
+ // Strings made only of printable ASCII other than `"` and `\\` serialize as themselves in quotes.
45
+ const PLAIN_STRING = /^[\x20\x21\x23-\x5b\x5d-\x7e]*$/u;
46
+ // Object keys repeat across records, so their quoted forms are kept, up to a bound.
47
+ const quotedKeys = new Map();
48
+ const QUOTED_KEYS_MAX = 4096;
49
+ function quote(value) {
50
+ return PLAIN_STRING.test(value) ? `"${value}"` : JSON.stringify(value);
51
+ }
52
+ function quoteKey(key) {
53
+ let quoted = quotedKeys.get(key);
54
+ if (quoted === undefined) {
55
+ quoted = quote(key);
56
+ if (quotedKeys.size < QUOTED_KEYS_MAX)
57
+ quotedKeys.set(key, quoted);
58
+ }
59
+ return quoted;
37
60
  }
38
61
  function serialize(value) {
39
- if (value === undefined || value === null)
40
- return 'null';
41
- const type = typeof value;
42
- if (type === 'string' || type === 'boolean')
43
- return JSON.stringify(value);
44
- if (type === 'number') {
45
- if (!Number.isFinite(value))
62
+ switch (typeof value) {
63
+ case 'string':
64
+ return quote(value);
65
+ case 'number':
66
+ // `String` matches `JSON.stringify` for every finite number except `-0`.
67
+ return Number.isFinite(value) ? (value === 0 ? '0' : String(value)) : 'null';
68
+ case 'boolean':
69
+ return value ? 'true' : 'false';
70
+ case 'undefined':
46
71
  return 'null';
47
- return JSON.stringify(value);
72
+ case 'object':
73
+ break;
74
+ default:
75
+ throw new TypeError(`canonicalJsonStringify: cannot serialize ${typeof value} value`);
48
76
  }
49
- if (type === 'bigint' || type === 'function' || type === 'symbol')
50
- throw new TypeError(`canonicalJsonStringify: cannot serialize ${type} value`);
77
+ if (value === null)
78
+ return 'null';
51
79
  if (Array.isArray(value)) {
52
- let output = '[';
53
- for (let index = 0; index < value.length; index += 1) {
54
- if (index > 0)
55
- output += ',';
56
- output += serialize(value[index]);
57
- }
80
+ if (value.length === 0)
81
+ return '[]';
82
+ let output = `[${serialize(value[0])}`;
83
+ for (let index = 1; index < value.length; index += 1)
84
+ output += `,${serialize(value[index])}`;
58
85
  return `${output}]`;
59
86
  }
60
87
  const prototype = Object.getPrototypeOf(value);
61
88
  if (prototype !== Object.prototype && prototype !== null)
62
89
  throw new TypeError('canonicalJsonStringify: value is not JSON-compatible plain data');
63
90
  const record = value;
64
- const keys = Object.keys(record).toSorted(compareCodePoint);
91
+ const keys = Object.keys(record);
92
+ if (keys.length > 1)
93
+ keys.sort(compareCodePointOrder);
65
94
  let output = '{';
66
95
  let separator = '';
67
96
  for (const key of keys) {
68
97
  const entry = record[key];
69
98
  if (entry === undefined)
70
99
  continue;
71
- output += `${separator}${JSON.stringify(key)}:${serialize(entry)}`;
100
+ output += `${separator}${quoteKey(key)}:${serialize(entry)}`;
72
101
  separator = ',';
73
102
  }
74
103
  return `${output}}`;
75
104
  }
105
+ // True only when both values are the same plain JSON data, so that their canonical strings are
106
+ // equal; false means undecided here. Distinct finite numbers never share a JSON form, and `0` and
107
+ // `-0` both serialize as `0`, which `===` matches.
108
+ function sameCanonical(left, right, depth) {
109
+ if (depth > 256)
110
+ return false;
111
+ const type = typeof left;
112
+ if (type !== typeof right)
113
+ return false;
114
+ if (type === 'string' || type === 'boolean')
115
+ return left === right;
116
+ if (type === 'number')
117
+ return left === right && Number.isFinite(left);
118
+ if (type !== 'object' || left === null || right === null)
119
+ return left === null && right === null;
120
+ if (Array.isArray(left)) {
121
+ if (!Array.isArray(right) || left.length !== right.length)
122
+ return false;
123
+ for (let index = 0; index < left.length; index += 1) {
124
+ const entry = left[index];
125
+ if (entry === undefined || !sameCanonical(entry, right[index], depth + 1))
126
+ return false;
127
+ }
128
+ return true;
129
+ }
130
+ if (Array.isArray(right))
131
+ return false;
132
+ for (const candidate of [left, right]) {
133
+ const prototype = Object.getPrototypeOf(candidate);
134
+ if (prototype !== Object.prototype && prototype !== null)
135
+ return false;
136
+ }
137
+ const leftRecord = left;
138
+ const rightRecord = right;
139
+ let defined = 0;
140
+ for (const key of Object.keys(leftRecord)) {
141
+ const entry = leftRecord[key];
142
+ if (entry === undefined)
143
+ continue;
144
+ defined += 1;
145
+ if (!Object.prototype.propertyIsEnumerable.call(rightRecord, key) ||
146
+ !sameCanonical(entry, rightRecord[key], depth + 1))
147
+ return false;
148
+ }
149
+ for (const key of Object.keys(rightRecord))
150
+ if (rightRecord[key] !== undefined)
151
+ defined -= 1;
152
+ return defined === 0;
153
+ }
76
154
  /**
77
155
  * Deterministic key comparator: orders strings by Unicode code point,
78
156
  * independent of host locale/ICU. Use anywhere ordering feeds digests,
@@ -1746,6 +1746,7 @@ export declare const DeviceSyncLogRequestSchema: z.ZodObject<{
1746
1746
  parameters: z.ZodObject<{
1747
1747
  afterSeq: z.ZodNumber;
1748
1748
  limit: z.ZodOptional<z.ZodNumber>;
1749
+ readerKeyId: z.ZodOptional<z.ZodString>;
1749
1750
  }, z.core.$strict>;
1750
1751
  }, z.core.$strip>;
1751
1752
  export declare const DeviceSyncLogResponseSchema: z.ZodObject<{
@@ -1787,6 +1788,114 @@ export declare const DeviceSyncUsageResponseSchema: z.ZodObject<{
1787
1788
  quotaBytes: z.ZodNumber;
1788
1789
  }, z.core.$strict>;
1789
1790
  }, z.core.$strip>;
1791
+ export declare const DeviceSyncCheckpointRequestSchema: z.ZodObject<{
1792
+ caller: typeof ServiceCallerAssertionSchema;
1793
+ contractVersion: typeof ContractVersionSchema;
1794
+ requestId: typeof IdentifierSchemas.requestId;
1795
+ workspaceId: typeof IdentifierSchemas.workspaceId;
1796
+ projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
1797
+ correlation: typeof CorrelationMetadataSchema;
1798
+ operation: z.ZodLiteral<"device-sync.checkpoint">;
1799
+ requestedAt: typeof TimestampSchema;
1800
+ parameters: z.ZodObject<{
1801
+ readerKeyId: z.ZodOptional<z.ZodString>;
1802
+ }, z.core.$strict>;
1803
+ }, z.core.$strip>;
1804
+ export declare const DeviceSyncCheckpointResponseSchema: z.ZodObject<{
1805
+ contractVersion: typeof ContractVersionSchema;
1806
+ requestId: typeof IdentifierSchemas.requestId;
1807
+ correlation: typeof CorrelationMetadataSchema;
1808
+ data: z.ZodObject<{
1809
+ checkpoint: z.ZodNullable<z.ZodObject<{
1810
+ entryId: z.ZodString;
1811
+ authorKeyId: z.ZodString;
1812
+ objectIds: z.ZodArray<z.ZodString>;
1813
+ ckv: z.ZodNumber;
1814
+ nonce: z.ZodString;
1815
+ ciphertext: z.ZodString;
1816
+ signature: z.ZodString;
1817
+ seq: z.ZodNumber;
1818
+ createdAt: z.ZodISODateTime;
1819
+ throughSeq: z.ZodNumber;
1820
+ prevEntryId: z.ZodNullable<z.ZodString>;
1821
+ partObjectIds: z.ZodArray<z.ZodString>;
1822
+ registeredAt: z.ZodISODateTime;
1823
+ }, z.core.$strict>>;
1824
+ previous: z.ZodNullable<z.ZodObject<{
1825
+ entryId: z.ZodString;
1826
+ authorKeyId: z.ZodString;
1827
+ objectIds: z.ZodArray<z.ZodString>;
1828
+ ckv: z.ZodNumber;
1829
+ nonce: z.ZodString;
1830
+ ciphertext: z.ZodString;
1831
+ signature: z.ZodString;
1832
+ seq: z.ZodNumber;
1833
+ createdAt: z.ZodISODateTime;
1834
+ throughSeq: z.ZodNumber;
1835
+ prevEntryId: z.ZodNullable<z.ZodString>;
1836
+ partObjectIds: z.ZodArray<z.ZodString>;
1837
+ registeredAt: z.ZodISODateTime;
1838
+ }, z.core.$strict>>;
1839
+ floorSeq: z.ZodNumber;
1840
+ headSeq: z.ZodNumber;
1841
+ }, z.core.$strict>;
1842
+ }, z.core.$strip>;
1843
+ export declare const DeviceSyncRegisterCheckpointRequestSchema: z.ZodObject<{
1844
+ caller: typeof ServiceCallerAssertionSchema;
1845
+ contractVersion: typeof ContractVersionSchema;
1846
+ requestId: typeof IdentifierSchemas.requestId;
1847
+ workspaceId: typeof IdentifierSchemas.workspaceId;
1848
+ projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
1849
+ correlation: typeof CorrelationMetadataSchema;
1850
+ commandId: typeof IdentifierSchemas.commandId;
1851
+ idempotencyKey: typeof IdempotencyKeySchema;
1852
+ payloadHash: typeof PayloadHashSchema;
1853
+ operation: z.ZodLiteral<"device-sync.register-checkpoint">;
1854
+ issuedAt: typeof TimestampSchema;
1855
+ payload: z.ZodObject<{
1856
+ entryId: z.ZodString;
1857
+ throughSeq: z.ZodNumber;
1858
+ prevEntryId: z.ZodNullable<z.ZodString>;
1859
+ partObjectIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
1860
+ authorKeyId: z.ZodString;
1861
+ }, z.core.$strict>;
1862
+ }, z.core.$strip>;
1863
+ export declare const DeviceSyncRegisterCheckpointResponseSchema: z.ZodObject<{
1864
+ contractVersion: typeof ContractVersionSchema;
1865
+ requestId: typeof IdentifierSchemas.requestId;
1866
+ correlation: typeof CorrelationMetadataSchema;
1867
+ data: z.ZodObject<{
1868
+ entryId: z.ZodString;
1869
+ seq: z.ZodNumber;
1870
+ throughSeq: z.ZodNumber;
1871
+ prevEntryId: z.ZodNullable<z.ZodString>;
1872
+ }, z.core.$strict>;
1873
+ }, z.core.$strip>;
1874
+ export declare const DeviceSyncAckRequestSchema: z.ZodObject<{
1875
+ caller: typeof ServiceCallerAssertionSchema;
1876
+ contractVersion: typeof ContractVersionSchema;
1877
+ requestId: typeof IdentifierSchemas.requestId;
1878
+ workspaceId: typeof IdentifierSchemas.workspaceId;
1879
+ projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
1880
+ correlation: typeof CorrelationMetadataSchema;
1881
+ commandId: typeof IdentifierSchemas.commandId;
1882
+ idempotencyKey: typeof IdempotencyKeySchema;
1883
+ payloadHash: typeof PayloadHashSchema;
1884
+ operation: z.ZodLiteral<"device-sync.ack">;
1885
+ issuedAt: typeof TimestampSchema;
1886
+ payload: z.ZodObject<{
1887
+ appliedSeq: z.ZodNumber;
1888
+ readerKeyId: z.ZodString;
1889
+ }, z.core.$strict>;
1890
+ }, z.core.$strip>;
1891
+ export declare const DeviceSyncAckResponseSchema: z.ZodObject<{
1892
+ contractVersion: typeof ContractVersionSchema;
1893
+ requestId: typeof IdentifierSchemas.requestId;
1894
+ correlation: typeof CorrelationMetadataSchema;
1895
+ data: z.ZodObject<{
1896
+ appliedSeq: z.ZodNumber;
1897
+ }, z.core.$strict>;
1898
+ }, z.core.$strip>;
1790
1899
  export type DeviceSyncUploadRequest = z.input<typeof DeviceSyncUploadRequestSchema>;
1791
1900
  export type DeviceSyncUploadResponse = z.output<typeof DeviceSyncUploadResponseSchema>;
1792
1901
  export type DeviceSyncCommitRequest = z.input<typeof DeviceSyncCommitRequestSchema>;
@@ -1801,4 +1910,10 @@ export type DeviceSyncLogRequest = z.input<typeof DeviceSyncLogRequestSchema>;
1801
1910
  export type DeviceSyncLogResponse = z.output<typeof DeviceSyncLogResponseSchema>;
1802
1911
  export type DeviceSyncUsageRequest = z.input<typeof DeviceSyncUsageRequestSchema>;
1803
1912
  export type DeviceSyncUsageResponse = z.output<typeof DeviceSyncUsageResponseSchema>;
1913
+ export type DeviceSyncCheckpointRequest = z.input<typeof DeviceSyncCheckpointRequestSchema>;
1914
+ export type DeviceSyncCheckpointResponse = z.output<typeof DeviceSyncCheckpointResponseSchema>;
1915
+ export type DeviceSyncRegisterCheckpointRequest = z.input<typeof DeviceSyncRegisterCheckpointRequestSchema>;
1916
+ export type DeviceSyncRegisterCheckpointResponse = z.output<typeof DeviceSyncRegisterCheckpointResponseSchema>;
1917
+ export type DeviceSyncAckRequest = z.input<typeof DeviceSyncAckRequestSchema>;
1918
+ export type DeviceSyncAckResponse = z.output<typeof DeviceSyncAckResponseSchema>;
1804
1919
  export {};
@@ -5,7 +5,7 @@ import { DecisionLayerResolutionSchema, DecisionResolutionRequestSchema, ModelId
5
5
  import { CorrelationMetadataSchema } from './envelopes.js';
6
6
  import { IdentifierSchemas } from './identifiers.js';
7
7
  import { CursorSchema } from './pagination.js';
8
- import { SyncAppendRequestSchema, SyncAppendResponseSchema, SyncAuthorKeyIdSchema, SyncCommitResponseSchema, SyncDownloadRequestSchema, SyncDownloadResponseSchema, SyncLogPageSchema, SyncLogRequestSchema, SyncObjectRequestSchema, SyncReleaseResponseSchema, SyncUploadRequestSchema, SyncUploadResponseSchema, SyncUsageSchema, } from './device-sync.js';
8
+ import { SyncAppendRequestSchema, SyncAppendResponseSchema, SyncAckRequestSchema, SyncAckResponseSchema, SyncAuthorKeyIdSchema, SyncCheckpointRegisterRequestSchema, SyncCheckpointRegisterResponseSchema, SyncCheckpointRequestSchema, SyncCheckpointResponseSchema, SyncCommitResponseSchema, SyncDownloadRequestSchema, SyncDownloadResponseSchema, SyncLogPageSchema, SyncLogRequestSchema, SyncObjectRequestSchema, SyncReleaseResponseSchema, SyncUploadRequestSchema, SyncUploadResponseSchema, SyncUsageSchema, } from './device-sync.js';
9
9
  import { ContractVersionSchema } from './versioning.js';
10
10
  import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
11
11
  const IdempotencyKeySchema = z
@@ -258,10 +258,14 @@ export const ContextPackageResolutionRequestSchema = RequestContextSchema.extend
258
258
  parameters: z.object({ contextPackageId: IdentifierSchemas.contextPackageId }),
259
259
  });
260
260
  export const ContextPackageResolutionResponseSchema = successResponse(z.object({ contextPackage: ContextPackagePublicReferenceSchema }));
261
+ const MarketplacePluginIdSchema = z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/);
262
+ const MarketplaceReleaseIdSchema = z.string().regex(/^release:[a-f0-9]{64}$/);
263
+ // The catalog response's releaseId is the catalog digest, so it shares this pattern.
264
+ const MarketplaceCatalogIdSchema = z.string().regex(/^catalog:[a-f0-9]{64}$/);
261
265
  const MarketplacePluginReferenceContractSchema = z
262
266
  .object({
263
- pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
264
- releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
267
+ pluginId: MarketplacePluginIdSchema,
268
+ releaseId: MarketplaceReleaseIdSchema,
265
269
  canonicalContentDigest: Sha256DigestSchema,
266
270
  })
267
271
  .strict();
@@ -327,8 +331,8 @@ const MarketplaceActiveInstallationSchema = MarketplacePluginReferenceContractSc
327
331
  state: z.enum(MarketplaceInstallationDecisionStates),
328
332
  });
329
333
  export const MarketplaceCatalogResponseSchema = successResponse(z.object({
330
- catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
331
- releaseId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
334
+ catalogId: MarketplaceCatalogIdSchema,
335
+ releaseId: MarketplaceCatalogIdSchema,
332
336
  state: z.enum(['ready', 'stale']),
333
337
  artifacts: MarketplaceArtifactsSchema,
334
338
  installations: z
@@ -370,7 +374,7 @@ export const MarketplaceInstallRequestSchema = CommandContextSchema.extend({
370
374
  });
371
375
  export const MarketplaceInstallResponseSchema = successResponse(MarketplacePluginReferenceContractSchema.extend({
372
376
  installationId: z.string().min(1).max(128),
373
- catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
377
+ catalogId: MarketplaceCatalogIdSchema,
374
378
  installationInstanceId: z.string().min(1).max(256).optional(),
375
379
  packageDigest: Sha256DigestSchema.optional(),
376
380
  requestedHarness: z.string().min(1).max(128),
@@ -381,7 +385,7 @@ export const MarketplaceInstallResponseSchema = successResponse(MarketplacePlugi
381
385
  export const MarketplaceInstallationSchema = z.object({
382
386
  ...MarketplacePluginReferenceContractSchema.shape,
383
387
  installationId: z.string().min(1).max(128),
384
- catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
388
+ catalogId: MarketplaceCatalogIdSchema,
385
389
  installationInstanceId: z.string().min(1).max(256).optional(),
386
390
  packageDigest: Sha256DigestSchema.optional(),
387
391
  requestedHarness: z.string().min(1).max(128),
@@ -419,8 +423,8 @@ export const MarketplaceInstallPlanRequestSchema = CommandContextSchema.extend({
419
423
  operation: z.literal('marketplace.install.plan'),
420
424
  issuedAt: TimestampSchema,
421
425
  payload: z.object({
422
- pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
423
- releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
426
+ pluginId: MarketplacePluginIdSchema,
427
+ releaseId: MarketplaceReleaseIdSchema,
424
428
  instanceId: z.string().min(1).max(256),
425
429
  requestedHarness: z.string().min(1).max(128),
426
430
  workspaceIdentity: MarketplaceIdentitySchema,
@@ -518,8 +522,8 @@ export const ExecutionAcceptanceRequestSchema = CommandContextSchema.extend({
518
522
  .array(z
519
523
  .object({
520
524
  canonicalContentDigest: Sha256DigestSchema,
521
- pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
522
- releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
525
+ pluginId: MarketplacePluginIdSchema,
526
+ releaseId: MarketplaceReleaseIdSchema,
523
527
  })
524
528
  .strict())
525
529
  .max(128)
@@ -1102,7 +1106,16 @@ export const DeviceSyncReleaseRequestSchema = deviceSyncCommand('device-sync.rel
1102
1106
  export const DeviceSyncReleaseResponseSchema = successResponse(SyncReleaseResponseSchema);
1103
1107
  export const DeviceSyncAppendRequestSchema = deviceSyncCommand('device-sync.append', SyncAppendRequestSchema);
1104
1108
  export const DeviceSyncAppendResponseSchema = successResponse(SyncAppendResponseSchema);
1105
- export const DeviceSyncLogRequestSchema = deviceSyncRead('device-sync.log', SyncLogRequestSchema);
1109
+ // The Adea worker names the verified caller key on reads, so CP can tell which readers are active
1110
+ // (the prune job never strands one). Optional: a worker from before compaction sends none.
1111
+ const SyncReaderKeyIdSchema = SyncAuthorKeyIdSchema.optional();
1112
+ export const DeviceSyncLogRequestSchema = deviceSyncRead('device-sync.log', SyncLogRequestSchema.extend({ readerKeyId: SyncReaderKeyIdSchema }).strict());
1106
1113
  export const DeviceSyncLogResponseSchema = successResponse(SyncLogPageSchema);
1107
1114
  export const DeviceSyncUsageRequestSchema = deviceSyncRead('device-sync.usage', z.object({}).strict());
1108
1115
  export const DeviceSyncUsageResponseSchema = successResponse(SyncUsageSchema);
1116
+ export const DeviceSyncCheckpointRequestSchema = deviceSyncRead('device-sync.checkpoint', SyncCheckpointRequestSchema.extend({ readerKeyId: SyncReaderKeyIdSchema }).strict());
1117
+ export const DeviceSyncCheckpointResponseSchema = successResponse(SyncCheckpointResponseSchema);
1118
+ export const DeviceSyncRegisterCheckpointRequestSchema = deviceSyncCommand('device-sync.register-checkpoint', SyncCheckpointRegisterRequestSchema.extend({ authorKeyId: SyncAuthorKeyIdSchema }).strict());
1119
+ export const DeviceSyncRegisterCheckpointResponseSchema = successResponse(SyncCheckpointRegisterResponseSchema);
1120
+ export const DeviceSyncAckRequestSchema = deviceSyncCommand('device-sync.ack', SyncAckRequestSchema.extend({ readerKeyId: SyncAuthorKeyIdSchema }).strict());
1121
+ export const DeviceSyncAckResponseSchema = successResponse(SyncAckResponseSchema);
@@ -1,15 +1,20 @@
1
1
  import { z } from 'zod';
2
2
  export declare const DeviceSyncErrorCodeSchema: z.ZodEnum<{
3
+ SYNC_AUTHOR_NOT_PRIMARY: "SYNC_AUTHOR_NOT_PRIMARY";
3
4
  SYNC_AUTHOR_REVOKED: "SYNC_AUTHOR_REVOKED";
4
5
  SYNC_AUTHOR_UNKNOWN: "SYNC_AUTHOR_UNKNOWN";
5
6
  SYNC_BLOB_INVALID: "SYNC_BLOB_INVALID";
6
7
  SYNC_BLOB_TOO_LARGE: "SYNC_BLOB_TOO_LARGE";
8
+ SYNC_CHECKPOINT_CONFLICT: "SYNC_CHECKPOINT_CONFLICT";
9
+ SYNC_CHECKPOINT_INVALID: "SYNC_CHECKPOINT_INVALID";
7
10
  SYNC_DECRYPTION_FAILED: "SYNC_DECRYPTION_FAILED";
8
11
  SYNC_ENTRY_CONFLICT: "SYNC_ENTRY_CONFLICT";
9
12
  SYNC_ENTRY_INVALID: "SYNC_ENTRY_INVALID";
10
13
  SYNC_ENTRY_TOO_LARGE: "SYNC_ENTRY_TOO_LARGE";
11
14
  SYNC_KEY_UNAVAILABLE: "SYNC_KEY_UNAVAILABLE";
15
+ SYNC_LOG_COMPACTED: "SYNC_LOG_COMPACTED";
12
16
  SYNC_LOG_ROLLED_BACK: "SYNC_LOG_ROLLED_BACK";
17
+ SYNC_LOG_TRUNCATED: "SYNC_LOG_TRUNCATED";
13
18
  SYNC_OBJECT_CONFLICT: "SYNC_OBJECT_CONFLICT";
14
19
  SYNC_OBJECT_NOT_COMMITTED: "SYNC_OBJECT_NOT_COMMITTED";
15
20
  SYNC_QUOTA_EXCEEDED: "SYNC_QUOTA_EXCEEDED";
@@ -24,6 +29,12 @@ export declare const MAX_SYNC_ENTRY_BYTES: number;
24
29
  /** Entries per append and object ids per download or release. */
25
30
  export declare const MAX_SYNC_BATCH = 100;
26
31
  export declare const MAX_SYNC_LOG_PAGE = 500;
32
+ /**
33
+ * The most objects one checkpoint snapshot may span. A snapshot past one object's 256 MiB is split
34
+ * into parts: the entry header names the first, and the registration names the rest so the
35
+ * unreferenced-object sweep keeps them (32 parts is 8 GiB, about 11M heads).
36
+ */
37
+ export declare const MAX_SYNC_SNAPSHOT_PARTS = 32;
27
38
  /** The smallest sealed object: a 12-byte header, the 8-byte length prefix and one 16-byte tag. */
28
39
  export declare const MIN_SYNC_CIPHERTEXT_BYTES = 36;
29
40
  /** The sealed size of the largest (256 MiB) object; device-sync tests pin it to the blob format. */
@@ -122,6 +133,83 @@ export declare const SyncLogPageSchema: z.ZodObject<{
122
133
  }, z.core.$strict>>;
123
134
  headSeq: z.ZodNumber;
124
135
  }, z.core.$strict>;
136
+ /** `log/checkpoint`: the latest registered checkpoint, the one before it, the floor and the head. */
137
+ export declare const SyncCheckpointRequestSchema: z.ZodObject<{}, z.core.$strict>;
138
+ /** A checkpoint entry as the log stored it, with what its registration recorded. */
139
+ export declare const SyncRegisteredCheckpointSchema: z.ZodObject<{
140
+ entryId: z.ZodString;
141
+ authorKeyId: z.ZodString;
142
+ objectIds: z.ZodArray<z.ZodString>;
143
+ ckv: z.ZodNumber;
144
+ nonce: z.ZodString;
145
+ ciphertext: z.ZodString;
146
+ signature: z.ZodString;
147
+ seq: z.ZodNumber;
148
+ createdAt: z.ZodISODateTime;
149
+ throughSeq: z.ZodNumber;
150
+ prevEntryId: z.ZodNullable<z.ZodString>;
151
+ partObjectIds: z.ZodArray<z.ZodString>;
152
+ registeredAt: z.ZodISODateTime;
153
+ }, z.core.$strict>;
154
+ export type SyncRegisteredCheckpoint = z.infer<typeof SyncRegisteredCheckpointSchema>;
155
+ export declare const SyncCheckpointResponseSchema: z.ZodObject<{
156
+ checkpoint: z.ZodNullable<z.ZodObject<{
157
+ entryId: z.ZodString;
158
+ authorKeyId: z.ZodString;
159
+ objectIds: z.ZodArray<z.ZodString>;
160
+ ckv: z.ZodNumber;
161
+ nonce: z.ZodString;
162
+ ciphertext: z.ZodString;
163
+ signature: z.ZodString;
164
+ seq: z.ZodNumber;
165
+ createdAt: z.ZodISODateTime;
166
+ throughSeq: z.ZodNumber;
167
+ prevEntryId: z.ZodNullable<z.ZodString>;
168
+ partObjectIds: z.ZodArray<z.ZodString>;
169
+ registeredAt: z.ZodISODateTime;
170
+ }, z.core.$strict>>;
171
+ previous: z.ZodNullable<z.ZodObject<{
172
+ entryId: z.ZodString;
173
+ authorKeyId: z.ZodString;
174
+ objectIds: z.ZodArray<z.ZodString>;
175
+ ckv: z.ZodNumber;
176
+ nonce: z.ZodString;
177
+ ciphertext: z.ZodString;
178
+ signature: z.ZodString;
179
+ seq: z.ZodNumber;
180
+ createdAt: z.ZodISODateTime;
181
+ throughSeq: z.ZodNumber;
182
+ prevEntryId: z.ZodNullable<z.ZodString>;
183
+ partObjectIds: z.ZodArray<z.ZodString>;
184
+ registeredAt: z.ZodISODateTime;
185
+ }, z.core.$strict>>;
186
+ floorSeq: z.ZodNumber;
187
+ headSeq: z.ZodNumber;
188
+ }, z.core.$strict>;
189
+ /**
190
+ * `log/checkpoint/register`, only from the primary (the Adea worker checks that): records that the
191
+ * appended checkpoint entry `entryId` covers the log through `throughSeq`, if `prevEntryId` is
192
+ * still the latest registered checkpoint (compare-and-set).
193
+ */
194
+ export declare const SyncCheckpointRegisterRequestSchema: z.ZodObject<{
195
+ entryId: z.ZodString;
196
+ throughSeq: z.ZodNumber;
197
+ prevEntryId: z.ZodNullable<z.ZodString>;
198
+ partObjectIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
199
+ }, z.core.$strict>;
200
+ export declare const SyncCheckpointRegisterResponseSchema: z.ZodObject<{
201
+ entryId: z.ZodString;
202
+ seq: z.ZodNumber;
203
+ throughSeq: z.ZodNumber;
204
+ prevEntryId: z.ZodNullable<z.ZodString>;
205
+ }, z.core.$strict>;
206
+ /** `log/ack`: the reader has durably applied the log through `appliedSeq`. Max-merged. */
207
+ export declare const SyncAckRequestSchema: z.ZodObject<{
208
+ appliedSeq: z.ZodNumber;
209
+ }, z.core.$strict>;
210
+ export declare const SyncAckResponseSchema: z.ZodObject<{
211
+ appliedSeq: z.ZodNumber;
212
+ }, z.core.$strict>;
125
213
  export declare const SyncUsageSchema: z.ZodObject<{
126
214
  usedBytes: z.ZodNumber;
127
215
  quotaBytes: z.ZodNumber;
@@ -22,12 +22,30 @@ export const DeviceSyncErrorCodeSchema = z.enum([
22
22
  'SYNC_OBJECT_CONFLICT',
23
23
  'SYNC_ENTRY_CONFLICT',
24
24
  'SYNC_UNAVAILABLE',
25
+ // Log compaction (sync-compaction design, rollout step 1). Old clients read any code as a
26
+ // string, so these are additive.
27
+ /** A read whose `afterSeq` is below the pruned floor: bootstrap from the latest checkpoint. */
28
+ 'SYNC_LOG_COMPACTED',
29
+ /** Client side: a page that skips a seq, or ends early while the head is past the cursor. */
30
+ 'SYNC_LOG_TRUNCATED',
31
+ /** A checkpoint registration whose `prevEntryId` is no longer the latest registered one. */
32
+ 'SYNC_CHECKPOINT_CONFLICT',
33
+ /** A checkpoint that does not match its registration, or a floor past every checkpoint. */
34
+ 'SYNC_CHECKPOINT_INVALID',
35
+ /** A checkpoint (or, from now on, a rewrap) not written by the keyring's primary key. */
36
+ 'SYNC_AUTHOR_NOT_PRIMARY',
25
37
  ]);
26
38
  /** The largest sealed log entry plaintext. */
27
39
  export const MAX_SYNC_ENTRY_BYTES = 16 * 1024;
28
40
  /** Entries per append and object ids per download or release. */
29
41
  export const MAX_SYNC_BATCH = 100;
30
42
  export const MAX_SYNC_LOG_PAGE = 500;
43
+ /**
44
+ * The most objects one checkpoint snapshot may span. A snapshot past one object's 256 MiB is split
45
+ * into parts: the entry header names the first, and the registration names the rest so the
46
+ * unreferenced-object sweep keeps them (32 parts is 8 GiB, about 11M heads).
47
+ */
48
+ export const MAX_SYNC_SNAPSHOT_PARTS = 32;
31
49
  /** The smallest sealed object: a 12-byte header, the 8-byte length prefix and one 16-byte tag. */
32
50
  export const MIN_SYNC_CIPHERTEXT_BYTES = 36;
33
51
  /** The sealed size of the largest (256 MiB) object; device-sync tests pin it to the blob format. */
@@ -109,6 +127,54 @@ export const SyncLogRequestSchema = z
109
127
  export const SyncLogPageSchema = z
110
128
  .object({ entries: z.array(StoredSyncEntrySchema), headSeq: z.number().int().min(0) })
111
129
  .strict();
130
+ const SyncSeqSchema = z.number().int().min(0);
131
+ /** `log/checkpoint`: the latest registered checkpoint, the one before it, the floor and the head. */
132
+ export const SyncCheckpointRequestSchema = z.object({}).strict();
133
+ /** A checkpoint entry as the log stored it, with what its registration recorded. */
134
+ export const SyncRegisteredCheckpointSchema = StoredSyncEntrySchema.extend({
135
+ throughSeq: SyncSeqSchema,
136
+ prevEntryId: SyncEntryIdSchema.nullable(),
137
+ /** The snapshot's further part objects, after the one the entry header names. */
138
+ partObjectIds: z.array(SyncObjectIdSchema).max(MAX_SYNC_SNAPSHOT_PARTS - 1),
139
+ registeredAt: TimestampSchema,
140
+ }).strict();
141
+ export const SyncCheckpointResponseSchema = z
142
+ .object({
143
+ checkpoint: SyncRegisteredCheckpointSchema.nullable(),
144
+ /** The checkpoint before the latest, so a reader can fall back if a snapshot was released. */
145
+ previous: SyncRegisteredCheckpointSchema.nullable(),
146
+ /** Entries at or below this seq are pruned; a read after a lower seq is refused. */
147
+ floorSeq: SyncSeqSchema,
148
+ headSeq: SyncSeqSchema,
149
+ })
150
+ .strict();
151
+ /**
152
+ * `log/checkpoint/register`, only from the primary (the Adea worker checks that): records that the
153
+ * appended checkpoint entry `entryId` covers the log through `throughSeq`, if `prevEntryId` is
154
+ * still the latest registered checkpoint (compare-and-set).
155
+ */
156
+ export const SyncCheckpointRegisterRequestSchema = z
157
+ .object({
158
+ entryId: SyncEntryIdSchema,
159
+ throughSeq: SyncSeqSchema,
160
+ prevEntryId: SyncEntryIdSchema.nullable(),
161
+ partObjectIds: z
162
+ .array(SyncObjectIdSchema)
163
+ .max(MAX_SYNC_SNAPSHOT_PARTS - 1)
164
+ .optional(),
165
+ })
166
+ .strict();
167
+ export const SyncCheckpointRegisterResponseSchema = z
168
+ .object({
169
+ entryId: SyncEntryIdSchema,
170
+ seq: z.number().int().min(1),
171
+ throughSeq: SyncSeqSchema,
172
+ prevEntryId: SyncEntryIdSchema.nullable(),
173
+ })
174
+ .strict();
175
+ /** `log/ack`: the reader has durably applied the log through `appliedSeq`. Max-merged. */
176
+ export const SyncAckRequestSchema = z.object({ appliedSeq: SyncSeqSchema }).strict();
177
+ export const SyncAckResponseSchema = z.object({ appliedSeq: SyncSeqSchema }).strict();
112
178
  export const SyncUsageSchema = z
113
179
  .object({ usedBytes: z.number().int().min(0), quotaBytes: z.number().int().min(0) })
114
180
  .strict();
@@ -10,7 +10,7 @@ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
10
10
  * AgentProfiles owned by the envelope workspace and reads system entries visible to it.
11
11
  * Executable content (Skill manifest/content, AgentProfile definition) crosses the boundary
12
12
  * as JSON objects and is validated by the Control Plane's versioned catalog schemas
13
- * (`docs/profiles-and-skills.md`); this package stays free of domain dependencies.
13
+ * (https://adea.dev/docs/architecture/control-plane/profiles-and-skills/); this package stays free of domain dependencies.
14
14
  */
15
15
  declare const IdempotencyKeySchema: z.ZodString;
16
16
  declare const PayloadHashSchema: z.ZodString;
@@ -10,7 +10,7 @@ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
10
10
  * AgentProfiles owned by the envelope workspace and reads system entries visible to it.
11
11
  * Executable content (Skill manifest/content, AgentProfile definition) crosses the boundary
12
12
  * as JSON objects and is validated by the Control Plane's versioned catalog schemas
13
- * (`docs/profiles-and-skills.md`); this package stays free of domain dependencies.
13
+ * (https://adea.dev/docs/architecture/control-plane/profiles-and-skills/); this package stays free of domain dependencies.
14
14
  */
15
15
  const IdempotencyKeySchema = z
16
16
  .string()
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/contracts",
3
- "version": "5.0.4",
3
+ "version": "5.1.1",
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",
@@ -56,7 +56,7 @@
56
56
  "test": "bun test --pass-with-no-tests"
57
57
  },
58
58
  "dependencies": {
59
- "zod": "4.6.6"
59
+ "zod": "4.6.7"
60
60
  },
61
61
  "engines": {
62
62
  "node": "24.21.0"