@adea-ai/contracts 5.0.3 → 5.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.
package/README.md CHANGED
@@ -9,15 +9,16 @@ 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
- - **Control API schemas** — request/response contracts for the Control API.
17
- - **Envelopes** — standardized request/response wrappers with authentication
17
+ - **Control API schemas**: request/response contracts for the Control API.
18
+ - **Envelopes**: standardized request/response wrappers with authentication
18
19
  and versioning metadata.
19
20
  - **Pagination, versioning, and memory-writeback contracts.**
20
- - **Fixtures** — deterministic test fixtures for consumers.
21
+ - **Fixtures**: deterministic test fixtures for consumers.
21
22
 
22
23
  ## Install
23
24
 
@@ -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
35
  See [`docs/contracts.md`](../../docs/contracts.md) in the repository 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,11 +30,18 @@
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,
36
43
  * selection, or cross-host stability guarantees. Never use localeCompare
37
- * for these — its collation is locale-dependent (see the divergence fixture
44
+ * for these; its collation is locale-dependent (see the divergence fixture
38
45
  * in the tests: ['a-b','ab','a_b','Aa','a!']).
39
46
  */
40
47
  export declare function compareCodePointOrder(left: string, right: string): number;
@@ -32,52 +32,130 @@
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,
79
157
  * selection, or cross-host stability guarantees. Never use localeCompare
80
- * for these — its collation is locale-dependent (see the divergence fixture
158
+ * for these; its collation is locale-dependent (see the divergence fixture
81
159
  * in the tests: ['a-b','ab','a_b','Aa','a!']).
82
160
  */
83
161
  export function compareCodePointOrder(left, right) {
@@ -737,6 +737,47 @@ export declare const MarketplaceCatalogResponseSchema: z.ZodObject<{
737
737
  }, z.core.$strip>>;
738
738
  }, z.core.$strip>;
739
739
  }, z.core.$strip>;
740
+ export declare const MarketplaceInstallationListRequestSchema: z.ZodObject<{
741
+ caller: typeof ServiceCallerAssertionSchema;
742
+ contractVersion: typeof ContractVersionSchema;
743
+ requestId: typeof IdentifierSchemas.requestId;
744
+ workspaceId: typeof IdentifierSchemas.workspaceId;
745
+ projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"project ID">, string>>>;
746
+ correlation: typeof CorrelationMetadataSchema;
747
+ operation: z.ZodLiteral<"marketplace.installation.list">;
748
+ requestedAt: typeof TimestampSchema;
749
+ parameters: z.ZodObject<{
750
+ workspaceIdentity: typeof MarketplaceIdentitySchema;
751
+ installedBy: z.ZodOptional<z.ZodString>;
752
+ limit: z.ZodOptional<z.ZodNumber>;
753
+ cursor: z.ZodOptional<typeof CursorSchema>;
754
+ }, z.core.$strip>;
755
+ }, z.core.$strip>;
756
+ export declare const MarketplaceInstallationListResponseSchema: z.ZodObject<{
757
+ contractVersion: typeof ContractVersionSchema;
758
+ requestId: typeof IdentifierSchemas.requestId;
759
+ correlation: typeof CorrelationMetadataSchema;
760
+ data: z.ZodObject<{
761
+ installations: z.ZodArray<z.ZodObject<{
762
+ pluginId: z.ZodString;
763
+ releaseId: z.ZodString;
764
+ canonicalContentDigest: typeof Sha256DigestSchema;
765
+ installationId: z.ZodOptional<z.ZodString>;
766
+ installationInstanceId: z.ZodOptional<z.ZodString>;
767
+ packageDigest: z.ZodOptional<z.ZodString>;
768
+ state: z.ZodEnum<{
769
+ installed: "installed";
770
+ "pending-authorization": "pending-authorization";
771
+ "rejected-by-policy": "rejected-by-policy";
772
+ superseded: "superseded";
773
+ unavailable: "unavailable";
774
+ }>;
775
+ }, z.core.$strict>>;
776
+ installationsPage: z.ZodObject<{
777
+ nextCursor: z.ZodOptional<z.ZodString>;
778
+ }, z.core.$strip>;
779
+ }, z.core.$strip>;
780
+ }, z.core.$strip>;
740
781
  export declare const MarketplaceInstallRequestSchema: z.ZodObject<{
741
782
  caller: typeof ServiceCallerAssertionSchema;
742
783
  contractVersion: typeof ContractVersionSchema;
@@ -864,6 +905,8 @@ export type MarketplaceCatalogResponse = z.output<typeof MarketplaceCatalogRespo
864
905
  export type MarketplaceInstallRequest = z.input<typeof MarketplaceInstallRequestSchema>;
865
906
  export type MarketplaceInstallResponse = z.output<typeof MarketplaceInstallResponseSchema>;
866
907
  export type MarketplaceInstallation = z.output<typeof MarketplaceInstallationSchema>;
908
+ export type MarketplaceInstallationListRequest = z.input<typeof MarketplaceInstallationListRequestSchema>;
909
+ export type MarketplaceInstallationListResponse = z.output<typeof MarketplaceInstallationListResponseSchema>;
867
910
  export type MarketplaceInstallationLifecycleState = z.output<typeof MarketplaceInstallationLifecycleStateSchema>;
868
911
  export type MarketplaceInstallationGetRequest = z.input<typeof MarketplaceInstallationGetRequestSchema>;
869
912
  export type MarketplaceInstallationGetResponse = z.output<typeof MarketplaceInstallationGetResponseSchema>;
@@ -1300,6 +1343,10 @@ export interface ControlApiFixtureSet {
1300
1343
  readonly request: ExecutionAcceptanceRequest;
1301
1344
  readonly response: z.input<typeof ExecutionAcceptanceResponseSchema>;
1302
1345
  };
1346
+ readonly marketplaceInstallationList: {
1347
+ readonly request: MarketplaceInstallationListRequest;
1348
+ readonly response: z.input<typeof MarketplaceInstallationListResponseSchema>;
1349
+ };
1303
1350
  readonly marketplaceInstallationGet: {
1304
1351
  readonly request: MarketplaceInstallationGetRequest;
1305
1352
  readonly response: z.input<typeof MarketplaceInstallationGetResponseSchema>;
@@ -1699,6 +1746,7 @@ export declare const DeviceSyncLogRequestSchema: z.ZodObject<{
1699
1746
  parameters: z.ZodObject<{
1700
1747
  afterSeq: z.ZodNumber;
1701
1748
  limit: z.ZodOptional<z.ZodNumber>;
1749
+ readerKeyId: z.ZodOptional<z.ZodString>;
1702
1750
  }, z.core.$strict>;
1703
1751
  }, z.core.$strip>;
1704
1752
  export declare const DeviceSyncLogResponseSchema: z.ZodObject<{
@@ -1740,6 +1788,114 @@ export declare const DeviceSyncUsageResponseSchema: z.ZodObject<{
1740
1788
  quotaBytes: z.ZodNumber;
1741
1789
  }, z.core.$strict>;
1742
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>;
1743
1899
  export type DeviceSyncUploadRequest = z.input<typeof DeviceSyncUploadRequestSchema>;
1744
1900
  export type DeviceSyncUploadResponse = z.output<typeof DeviceSyncUploadResponseSchema>;
1745
1901
  export type DeviceSyncCommitRequest = z.input<typeof DeviceSyncCommitRequestSchema>;
@@ -1754,4 +1910,10 @@ export type DeviceSyncLogRequest = z.input<typeof DeviceSyncLogRequestSchema>;
1754
1910
  export type DeviceSyncLogResponse = z.output<typeof DeviceSyncLogResponseSchema>;
1755
1911
  export type DeviceSyncUsageRequest = z.input<typeof DeviceSyncUsageRequestSchema>;
1756
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>;
1757
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();
@@ -317,24 +321,48 @@ export const MarketplaceCatalogRequestSchema = RequestContextSchema.extend({
317
321
  cursor: CursorSchema.optional(),
318
322
  }),
319
323
  });
324
+ // One active installation as the catalog and installation list reads report it.
325
+ const MarketplaceActiveInstallationSchema = MarketplacePluginReferenceContractSchema.extend({
326
+ // Additive 3.x field: the handle for the installation get and
327
+ // uninstall operations.
328
+ installationId: z.string().min(1).max(128).optional(),
329
+ installationInstanceId: z.string().min(1).max(256).optional(),
330
+ packageDigest: Sha256DigestSchema.optional(),
331
+ state: z.enum(MarketplaceInstallationDecisionStates),
332
+ });
320
333
  export const MarketplaceCatalogResponseSchema = successResponse(z.object({
321
- catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
322
- releaseId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
334
+ catalogId: MarketplaceCatalogIdSchema,
335
+ releaseId: MarketplaceCatalogIdSchema,
323
336
  state: z.enum(['ready', 'stale']),
324
337
  artifacts: MarketplaceArtifactsSchema,
325
338
  installations: z
326
- .array(MarketplacePluginReferenceContractSchema.extend({
327
- // Additive 3.x field: the handle for the installation get and
328
- // uninstall operations.
329
- installationId: z.string().min(1).max(128).optional(),
330
- installationInstanceId: z.string().min(1).max(256).optional(),
331
- packageDigest: Sha256DigestSchema.optional(),
332
- state: z.enum(MarketplaceInstallationDecisionStates),
333
- }))
339
+ .array(MarketplaceActiveInstallationSchema)
334
340
  .max(100),
335
341
  // Additive 3.x field; absent from servers that predate installation paging.
336
342
  installationsPage: z.object({ nextCursor: CursorSchema.optional() }).optional(),
337
343
  }));
344
+ // The workspace's active installations without the catalog: a page costs a few
345
+ // kilobytes instead of re-sending the catalog artifacts.
346
+ export const MarketplaceInstallationListRequestSchema = RequestContextSchema.extend({
347
+ operation: z.literal('marketplace.installation.list'),
348
+ requestedAt: TimestampSchema,
349
+ parameters: z.object({
350
+ workspaceIdentity: MarketplaceIdentitySchema,
351
+ // Only installations whose recorded installer (the install request's
352
+ // `workspaceIdentity.userId`) matches. Omitted, every active installation.
353
+ installedBy: z.string().min(1).max(128).optional(),
354
+ // At most `limit` (default and maximum 100) per page, oldest `updatedAt`
355
+ // first, continued with `installationsPage.nextCursor`.
356
+ limit: z.number().int().min(1).max(100).optional(),
357
+ cursor: CursorSchema.optional(),
358
+ }),
359
+ });
360
+ export const MarketplaceInstallationListResponseSchema = successResponse(z.object({
361
+ installations: z
362
+ .array(MarketplaceActiveInstallationSchema)
363
+ .max(100),
364
+ installationsPage: z.object({ nextCursor: CursorSchema.optional() }),
365
+ }));
338
366
  export const MarketplaceInstallRequestSchema = CommandContextSchema.extend({
339
367
  operation: z.literal('marketplace.install.request'),
340
368
  issuedAt: TimestampSchema,
@@ -346,7 +374,7 @@ export const MarketplaceInstallRequestSchema = CommandContextSchema.extend({
346
374
  });
347
375
  export const MarketplaceInstallResponseSchema = successResponse(MarketplacePluginReferenceContractSchema.extend({
348
376
  installationId: z.string().min(1).max(128),
349
- catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
377
+ catalogId: MarketplaceCatalogIdSchema,
350
378
  installationInstanceId: z.string().min(1).max(256).optional(),
351
379
  packageDigest: Sha256DigestSchema.optional(),
352
380
  requestedHarness: z.string().min(1).max(128),
@@ -357,7 +385,7 @@ export const MarketplaceInstallResponseSchema = successResponse(MarketplacePlugi
357
385
  export const MarketplaceInstallationSchema = z.object({
358
386
  ...MarketplacePluginReferenceContractSchema.shape,
359
387
  installationId: z.string().min(1).max(128),
360
- catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
388
+ catalogId: MarketplaceCatalogIdSchema,
361
389
  installationInstanceId: z.string().min(1).max(256).optional(),
362
390
  packageDigest: Sha256DigestSchema.optional(),
363
391
  requestedHarness: z.string().min(1).max(128),
@@ -395,8 +423,8 @@ export const MarketplaceInstallPlanRequestSchema = CommandContextSchema.extend({
395
423
  operation: z.literal('marketplace.install.plan'),
396
424
  issuedAt: TimestampSchema,
397
425
  payload: z.object({
398
- pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
399
- releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
426
+ pluginId: MarketplacePluginIdSchema,
427
+ releaseId: MarketplaceReleaseIdSchema,
400
428
  instanceId: z.string().min(1).max(256),
401
429
  requestedHarness: z.string().min(1).max(128),
402
430
  workspaceIdentity: MarketplaceIdentitySchema,
@@ -494,8 +522,8 @@ export const ExecutionAcceptanceRequestSchema = CommandContextSchema.extend({
494
522
  .array(z
495
523
  .object({
496
524
  canonicalContentDigest: Sha256DigestSchema,
497
- pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
498
- releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
525
+ pluginId: MarketplacePluginIdSchema,
526
+ releaseId: MarketplaceReleaseIdSchema,
499
527
  })
500
528
  .strict())
501
529
  .max(128)
@@ -885,6 +913,29 @@ export const ControlApiFixtures = Object.freeze({
885
913
  },
886
914
  },
887
915
  },
916
+ marketplaceInstallationList: {
917
+ request: {
918
+ ...marketplaceRequestContext,
919
+ operation: 'marketplace.installation.list',
920
+ requestedAt: '2026-08-23T12:00:00.000Z',
921
+ parameters: { workspaceIdentity: marketplaceWorkspaceIdentity, limit: 1 },
922
+ },
923
+ response: {
924
+ ...responseContext,
925
+ data: {
926
+ installations: [
927
+ {
928
+ installationId: marketplaceInstallation.installationId,
929
+ pluginId: marketplaceInstallation.pluginId,
930
+ releaseId: marketplaceInstallation.releaseId,
931
+ canonicalContentDigest: marketplaceInstallation.canonicalContentDigest,
932
+ state: 'installed',
933
+ },
934
+ ],
935
+ installationsPage: { nextCursor: 'cur_0123456789abcdef' },
936
+ },
937
+ },
938
+ },
888
939
  marketplaceInstallationGet: {
889
940
  request: {
890
941
  ...marketplaceRequestContext,
@@ -1055,7 +1106,16 @@ export const DeviceSyncReleaseRequestSchema = deviceSyncCommand('device-sync.rel
1055
1106
  export const DeviceSyncReleaseResponseSchema = successResponse(SyncReleaseResponseSchema);
1056
1107
  export const DeviceSyncAppendRequestSchema = deviceSyncCommand('device-sync.append', SyncAppendRequestSchema);
1057
1108
  export const DeviceSyncAppendResponseSchema = successResponse(SyncAppendResponseSchema);
1058
- 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());
1059
1113
  export const DeviceSyncLogResponseSchema = successResponse(SyncLogPageSchema);
1060
1114
  export const DeviceSyncUsageRequestSchema = deviceSyncRead('device-sync.usage', z.object({}).strict());
1061
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);
@@ -4,7 +4,7 @@ import { z } from 'zod';
4
4
  *
5
5
  * The Control Plane owns the decision layer that resolves what runs: harness,
6
6
  * model, skills, tools/capabilities, runtime, sandbox, context package, and
7
- * delegation policy. Resolution is logistics — it selects among what harnesses
7
+ * delegation policy. Resolution is logistics; it selects among what harnesses
8
8
  * expose; it never implements routing inside a harness's model semantics
9
9
  * (owner standing directive, adea#400). Precedence for every output:
10
10
  * explicit user pin > project default > profile default > policy default.
@@ -71,8 +71,8 @@ export declare const DelegationResolutionSchema: z.ZodObject<{
71
71
  export type DelegationResolution = z.output<typeof DelegationResolutionSchema>;
72
72
  /**
73
73
  * The delegation policy a resolution carries. Children resolve through the
74
- * Control Plane identity of the parent request — the same service principal,
75
- * workspace and project — and inherit the parent's runtime, so a child never
74
+ * Control Plane identity of the parent request; the same service principal,
75
+ * workspace and project, and inherit the parent's runtime, so a child never
76
76
  * moves to another machine. Their capabilities are bounded by the parent's
77
77
  * effective sandbox capabilities. None of this is pinnable: the identity and
78
78
  * the ceiling are derived, so a pin cannot widen them.
@@ -9,7 +9,7 @@ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
9
9
  *
10
10
  * The Control Plane owns the decision layer that resolves what runs: harness,
11
11
  * model, skills, tools/capabilities, runtime, sandbox, context package, and
12
- * delegation policy. Resolution is logistics — it selects among what harnesses
12
+ * delegation policy. Resolution is logistics; it selects among what harnesses
13
13
  * expose; it never implements routing inside a harness's model semantics
14
14
  * (owner standing directive, adea#400). Precedence for every output:
15
15
  * explicit user pin > project default > profile default > policy default.
@@ -98,8 +98,8 @@ export const DelegationResolutionSchema = z
98
98
  });
99
99
  /**
100
100
  * The delegation policy a resolution carries. Children resolve through the
101
- * Control Plane identity of the parent request — the same service principal,
102
- * workspace and project — and inherit the parent's runtime, so a child never
101
+ * Control Plane identity of the parent request; the same service principal,
102
+ * workspace and project, and inherit the parent's runtime, so a child never
103
103
  * moves to another machine. Their capabilities are bounded by the parent's
104
104
  * effective sandbox capabilities. None of this is pinnable: the identity and
105
105
  * the ceiling are derived, so a pin cannot widen them.
@@ -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();
@@ -102,6 +102,12 @@ export declare const NormalizedErrorSchema: z.ZodObject<{
102
102
  details: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
103
103
  }, z.core.$strip>;
104
104
  export type NormalizedError = z.infer<typeof NormalizedErrorSchema>;
105
+ /**
106
+ * The code of a `429` answer: the caller spent its request budget. It is retryable, and the
107
+ * `Retry-After` header says how many seconds to wait first. Nothing ran, so the same request can
108
+ * be sent again as is.
109
+ */
110
+ export declare const RATE_LIMITED_ERROR_CODE = "RATE_LIMITED";
105
111
  export declare const ErrorResponseEnvelopeSchema: z.ZodObject<{
106
112
  contractVersion: z.ZodObject<{
107
113
  major: z.ZodNumber;
package/dist/envelopes.js CHANGED
@@ -83,6 +83,12 @@ export const NormalizedErrorSchema = z.object({
83
83
  .refine((details) => Object.keys(details).length <= 32)
84
84
  .optional(),
85
85
  });
86
+ /**
87
+ * The code of a `429` answer: the caller spent its request budget. It is retryable, and the
88
+ * `Retry-After` header says how many seconds to wait first. Nothing ran, so the same request can
89
+ * be sent again as is.
90
+ */
91
+ export const RATE_LIMITED_ERROR_CODE = 'RATE_LIMITED';
86
92
  export const ErrorResponseEnvelopeSchema = ResponseIdentitySchema.extend({
87
93
  error: NormalizedErrorSchema,
88
94
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/contracts",
3
- "version": "5.0.3",
3
+ "version": "5.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",
@@ -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"