@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 +18 -9
- package/dist/canonical-json.d.ts +8 -1
- package/dist/canonical-json.js +99 -21
- package/dist/control-api.d.ts +162 -0
- package/dist/control-api.js +80 -20
- package/dist/decision-resolution.d.ts +3 -3
- package/dist/decision-resolution.js +3 -3
- package/dist/device-sync.d.ts +88 -0
- package/dist/device-sync.js +66 -0
- package/dist/envelopes.d.ts +6 -0
- package/dist/envelopes.js +6 -0
- package/package.json +2 -2
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
|
|
13
|
-
`exe_`,
|
|
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
|
|
17
|
-
- **Envelopes
|
|
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
|
|
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 {
|
|
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
|
|
55
|
-
|
|
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
|
package/dist/canonical-json.d.ts
CHANGED
|
@@ -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
|
|
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;
|
package/dist/canonical-json.js
CHANGED
|
@@ -32,52 +32,130 @@
|
|
|
32
32
|
export function canonicalJsonStringify(value) {
|
|
33
33
|
return serialize(value);
|
|
34
34
|
}
|
|
35
|
-
|
|
36
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
72
|
+
case 'object':
|
|
73
|
+
break;
|
|
74
|
+
default:
|
|
75
|
+
throw new TypeError(`canonicalJsonStringify: cannot serialize ${typeof value} value`);
|
|
48
76
|
}
|
|
49
|
-
if (
|
|
50
|
-
|
|
77
|
+
if (value === null)
|
|
78
|
+
return 'null';
|
|
51
79
|
if (Array.isArray(value)) {
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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)
|
|
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}${
|
|
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
|
|
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) {
|
package/dist/control-api.d.ts
CHANGED
|
@@ -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 {};
|
package/dist/control-api.js
CHANGED
|
@@ -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:
|
|
264
|
-
releaseId:
|
|
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:
|
|
322
|
-
releaseId:
|
|
334
|
+
catalogId: MarketplaceCatalogIdSchema,
|
|
335
|
+
releaseId: MarketplaceCatalogIdSchema,
|
|
323
336
|
state: z.enum(['ready', 'stale']),
|
|
324
337
|
artifacts: MarketplaceArtifactsSchema,
|
|
325
338
|
installations: z
|
|
326
|
-
.array(
|
|
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:
|
|
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:
|
|
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:
|
|
399
|
-
releaseId:
|
|
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:
|
|
498
|
-
releaseId:
|
|
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
|
-
|
|
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
|
|
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
|
|
75
|
-
* workspace and project
|
|
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
|
|
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
|
|
102
|
-
* workspace and project
|
|
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.
|
package/dist/device-sync.d.ts
CHANGED
|
@@ -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;
|
package/dist/device-sync.js
CHANGED
|
@@ -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();
|
package/dist/envelopes.d.ts
CHANGED
|
@@ -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
|
+
"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.
|
|
59
|
+
"zod": "4.6.7"
|
|
60
60
|
},
|
|
61
61
|
"engines": {
|
|
62
62
|
"node": "24.21.0"
|