@adea-ai/contracts 5.0.1 → 5.0.3

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.
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { IdentifierSchemas } from './identifiers.js';
3
- const TimestampSchema = z.iso.datetime();
3
+ import { TimestampSchema } from './primitives.js';
4
4
  const ServicePrincipalIdSchema = z
5
5
  .string()
6
6
  .min(5)
@@ -1,7 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { IdentifierSchemas } from './identifiers.js';
3
- const TimestampSchema = z.iso.datetime();
4
- const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
3
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
5
4
  const SemverSchema = z.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/);
6
5
  const ProviderIdSchema = z.string().regex(/^ctp_[0-9A-HJKMNP-TV-Z]{26}$/);
7
6
  const ConnectionIdSchema = z.string().regex(/^ctc_[0-9A-HJKMNP-TV-Z]{26}$/);
@@ -27,7 +26,7 @@ export const ContextProviderConnectionSchema = z.object({
27
26
  providerId: ProviderIdSchema,
28
27
  workspaceId: IdentifierSchemas.workspaceId,
29
28
  principalRef: z.string().min(1).max(256),
30
- scopeDigest: DigestSchema,
29
+ scopeDigest: Sha256DigestSchema,
31
30
  executionLocations: z.array(z.enum(['cloud', 'runtime_node'])).min(1),
32
31
  reachability: z.enum(['direct', 'remote']).default('remote'),
33
32
  state: z.enum(['active', 'revoked']),
@@ -54,9 +53,9 @@ export const ContextContributionSchema = z.object({
54
53
  tokenCount: z.number().int().nonnegative(),
55
54
  observedAt: TimestampSchema,
56
55
  expiresAt: TimestampSchema.optional(),
57
- scopeDigest: DigestSchema,
56
+ scopeDigest: Sha256DigestSchema,
58
57
  revision: z.string().min(1).max(256),
59
- contentDigest: DigestSchema,
58
+ contentDigest: Sha256DigestSchema,
60
59
  degraded: z.boolean(),
61
60
  provenance: z.array(z.object({
62
61
  sourceRef: z.string().min(1).max(1_024),
@@ -66,7 +65,7 @@ export const ContextContributionSchema = z.object({
66
65
  providerMetadata: z
67
66
  .object({
68
67
  bundleId: z.string().min(1).max(256),
69
- bundleDigest: DigestSchema,
68
+ bundleDigest: Sha256DigestSchema,
70
69
  corpusRevision: z.string().min(1).max(256),
71
70
  memoryRevision: z.string().min(1).max(256).optional(),
72
71
  embeddingVersion: z.string().min(1).max(128).optional(),
@@ -4,8 +4,7 @@ import { CorrelationMetadataSchema } from './envelopes.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { CursorSchema } from './pagination.js';
6
6
  import { ContractVersionSchema } from './versioning.js';
7
- declare const TimestampSchema: z.ZodISODateTime;
8
- declare const DigestSchema: z.ZodString;
7
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
9
8
  declare const IdempotencyKeySchema: z.ZodString;
10
9
  declare const PayloadHashSchema: z.ZodString;
11
10
  export declare const ProjectStateReferenceSchema: z.ZodObject<{
@@ -16,7 +15,7 @@ export declare const ProjectStateReferenceSchema: z.ZodObject<{
16
15
  export type ProjectStateReference = z.output<typeof ProjectStateReferenceSchema>;
17
16
  export declare const ContextPackagePublicReferenceSchema: z.ZodObject<{
18
17
  contextPackageId: typeof IdentifierSchemas.contextPackageId;
19
- contentDigest: typeof DigestSchema;
18
+ contentDigest: typeof Sha256DigestSchema;
20
19
  schemaVersion: z.ZodNumber;
21
20
  compilerVersion: z.ZodString;
22
21
  }, z.core.$strip>;
@@ -43,12 +42,12 @@ export type ContextAuthoringInputs = z.output<typeof ContextAuthoringInputsSchem
43
42
  export declare const PolicySnapshotPublicReferenceSchema: z.ZodObject<{
44
43
  policySnapshotId: z.ZodString;
45
44
  revision: z.ZodNumber;
46
- contentDigest: typeof DigestSchema;
45
+ contentDigest: typeof Sha256DigestSchema;
47
46
  }, z.core.$strip>;
48
47
  export type PolicySnapshotPublicReference = z.output<typeof PolicySnapshotPublicReferenceSchema>;
49
48
  export declare const ExecutionPlanPublicReferenceSchema: z.ZodObject<{
50
49
  executionPlanId: typeof IdentifierSchemas.executionPlanId;
51
- contentDigest: typeof DigestSchema;
50
+ contentDigest: typeof Sha256DigestSchema;
52
51
  }, z.core.$strip>;
53
52
  export type ExecutionPlanPublicReference = z.output<typeof ExecutionPlanPublicReferenceSchema>;
54
53
  export declare const ServiceAuthenticationRequestSchema: z.ZodObject<{
@@ -417,7 +416,7 @@ export declare const ProfileResolutionResponseSchema: z.ZodObject<{
417
416
  version: z.ZodNumber;
418
417
  revision: z.ZodNumber;
419
418
  schemaVersion: z.ZodNumber;
420
- contentDigest: typeof DigestSchema;
419
+ contentDigest: typeof Sha256DigestSchema;
421
420
  lifecycle: z.ZodLiteral<"published">;
422
421
  }, z.core.$strip>;
423
422
  skillVersionIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<import("./identifiers.js").OpaqueIdentifier<"skill-version ID">, string>>>;
@@ -661,7 +660,7 @@ export declare const ContextPackageResolutionResponseSchema: z.ZodObject<{
661
660
  data: z.ZodObject<{
662
661
  contextPackage: z.ZodObject<{
663
662
  contextPackageId: typeof IdentifierSchemas.contextPackageId;
664
- contentDigest: typeof DigestSchema;
663
+ contentDigest: typeof Sha256DigestSchema;
665
664
  schemaVersion: z.ZodNumber;
666
665
  compilerVersion: z.ZodString;
667
666
  }, z.core.$strip>;
@@ -721,7 +720,7 @@ export declare const MarketplaceCatalogResponseSchema: z.ZodObject<{
721
720
  installations: z.ZodArray<z.ZodObject<{
722
721
  pluginId: z.ZodString;
723
722
  releaseId: z.ZodString;
724
- canonicalContentDigest: typeof DigestSchema;
723
+ canonicalContentDigest: typeof Sha256DigestSchema;
725
724
  installationId: z.ZodOptional<z.ZodString>;
726
725
  installationInstanceId: z.ZodOptional<z.ZodString>;
727
726
  packageDigest: z.ZodOptional<z.ZodString>;
@@ -753,7 +752,7 @@ export declare const MarketplaceInstallRequestSchema: z.ZodObject<{
753
752
  payload: z.ZodObject<{
754
753
  pluginId: z.ZodString;
755
754
  releaseId: z.ZodString;
756
- canonicalContentDigest: typeof DigestSchema;
755
+ canonicalContentDigest: typeof Sha256DigestSchema;
757
756
  requestedHarness: z.ZodString;
758
757
  installationInstanceId: z.ZodOptional<z.ZodString>;
759
758
  workspaceIdentity: typeof MarketplaceIdentitySchema;
@@ -766,7 +765,7 @@ export declare const MarketplaceInstallResponseSchema: z.ZodObject<{
766
765
  data: z.ZodObject<{
767
766
  pluginId: z.ZodString;
768
767
  releaseId: z.ZodString;
769
- canonicalContentDigest: typeof DigestSchema;
768
+ canonicalContentDigest: typeof Sha256DigestSchema;
770
769
  installationId: z.ZodString;
771
770
  catalogId: z.ZodString;
772
771
  installationInstanceId: z.ZodOptional<z.ZodString>;
@@ -784,7 +783,7 @@ export declare const MarketplaceInstallResponseSchema: z.ZodObject<{
784
783
  export declare const MarketplaceInstallationSchema: z.ZodObject<{
785
784
  pluginId: z.ZodString;
786
785
  releaseId: z.ZodString;
787
- canonicalContentDigest: typeof DigestSchema;
786
+ canonicalContentDigest: typeof Sha256DigestSchema;
788
787
  installationId: z.ZodString;
789
788
  catalogId: z.ZodString;
790
789
  installationInstanceId: z.ZodOptional<z.ZodString>;
@@ -819,7 +818,7 @@ export declare const MarketplaceInstallationGetResponseSchema: z.ZodObject<{
819
818
  installation: z.ZodObject<{
820
819
  pluginId: z.ZodString;
821
820
  releaseId: z.ZodString;
822
- canonicalContentDigest: typeof DigestSchema;
821
+ canonicalContentDigest: typeof Sha256DigestSchema;
823
822
  installationId: z.ZodString;
824
823
  catalogId: z.ZodString;
825
824
  installationInstanceId: z.ZodOptional<z.ZodString>;
@@ -1040,7 +1039,7 @@ export declare const ExecutionAcceptanceRequestSchema: z.ZodObject<{
1040
1039
  agentId: typeof IdentifierSchemas.agentId;
1041
1040
  executionPlan: z.ZodObject<{
1042
1041
  executionPlanId: typeof IdentifierSchemas.executionPlanId;
1043
- contentDigest: typeof DigestSchema;
1042
+ contentDigest: typeof Sha256DigestSchema;
1044
1043
  schemaVersion: z.ZodNumber;
1045
1044
  }, z.core.$strip>;
1046
1045
  modelId: z.ZodOptional<z.ZodString>;
@@ -1063,7 +1062,7 @@ export declare const ExecutionAcceptanceResponseSchema: z.ZodObject<{
1063
1062
  executionId: typeof IdentifierSchemas.executionId;
1064
1063
  executionPlan: z.ZodObject<{
1065
1064
  executionPlanId: typeof IdentifierSchemas.executionPlanId;
1066
- contentDigest: typeof DigestSchema;
1065
+ contentDigest: typeof Sha256DigestSchema;
1067
1066
  schemaVersion: z.ZodNumber;
1068
1067
  }, z.core.$strip>;
1069
1068
  status: z.ZodEnum<{
@@ -7,8 +7,7 @@ import { IdentifierSchemas } from './identifiers.js';
7
7
  import { CursorSchema } from './pagination.js';
8
8
  import { SyncAppendRequestSchema, SyncAppendResponseSchema, SyncAuthorKeyIdSchema, SyncCommitResponseSchema, SyncDownloadRequestSchema, SyncDownloadResponseSchema, SyncLogPageSchema, SyncLogRequestSchema, SyncObjectRequestSchema, SyncReleaseResponseSchema, SyncUploadRequestSchema, SyncUploadResponseSchema, SyncUsageSchema, } from './device-sync.js';
9
9
  import { ContractVersionSchema } from './versioning.js';
10
- const TimestampSchema = z.iso.datetime();
11
- const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
10
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
12
11
  const IdempotencyKeySchema = z
13
12
  .string()
14
13
  .min(16)
@@ -51,7 +50,7 @@ export const ProjectStateReferenceSchema = z.object({
51
50
  });
52
51
  export const ContextPackagePublicReferenceSchema = z.object({
53
52
  contextPackageId: IdentifierSchemas.contextPackageId,
54
- contentDigest: DigestSchema,
53
+ contentDigest: Sha256DigestSchema,
55
54
  schemaVersion: z.number().int().positive(),
56
55
  compilerVersion: z.string().min(1).max(64),
57
56
  });
@@ -76,11 +75,11 @@ export const ContextAuthoringInputsSchema = z.strictObject({
76
75
  export const PolicySnapshotPublicReferenceSchema = z.object({
77
76
  policySnapshotId: z.string().min(1).max(256),
78
77
  revision: z.number().int().positive(),
79
- contentDigest: DigestSchema,
78
+ contentDigest: Sha256DigestSchema,
80
79
  });
81
80
  export const ExecutionPlanPublicReferenceSchema = z.object({
82
81
  executionPlanId: IdentifierSchemas.executionPlanId,
83
- contentDigest: DigestSchema,
82
+ contentDigest: Sha256DigestSchema,
84
83
  });
85
84
  export const ServiceAuthenticationRequestSchema = RequestContextSchema.extend({
86
85
  operation: z.literal('authentication.verify'),
@@ -131,7 +130,7 @@ export const ProfileResolutionResponseSchema = successResponse(z.object({
131
130
  version: z.number().int().positive(),
132
131
  revision: z.number().int().positive(),
133
132
  schemaVersion: z.number().int().positive(),
134
- contentDigest: DigestSchema,
133
+ contentDigest: Sha256DigestSchema,
135
134
  lifecycle: z.literal('published'),
136
135
  }),
137
136
  skillVersionIds: z.array(IdentifierSchemas.skillVersionId).max(128),
@@ -263,7 +262,7 @@ const MarketplacePluginReferenceContractSchema = z
263
262
  .object({
264
263
  pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
265
264
  releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
266
- canonicalContentDigest: DigestSchema,
265
+ canonicalContentDigest: Sha256DigestSchema,
267
266
  })
268
267
  .strict();
269
268
  const MarketplaceIdentitySchema = z.object({
@@ -329,7 +328,7 @@ export const MarketplaceCatalogResponseSchema = successResponse(z.object({
329
328
  // uninstall operations.
330
329
  installationId: z.string().min(1).max(128).optional(),
331
330
  installationInstanceId: z.string().min(1).max(256).optional(),
332
- packageDigest: DigestSchema.optional(),
331
+ packageDigest: Sha256DigestSchema.optional(),
333
332
  state: z.enum(MarketplaceInstallationDecisionStates),
334
333
  }))
335
334
  .max(100),
@@ -349,7 +348,7 @@ export const MarketplaceInstallResponseSchema = successResponse(MarketplacePlugi
349
348
  installationId: z.string().min(1).max(128),
350
349
  catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
351
350
  installationInstanceId: z.string().min(1).max(256).optional(),
352
- packageDigest: DigestSchema.optional(),
351
+ packageDigest: Sha256DigestSchema.optional(),
353
352
  requestedHarness: z.string().min(1).max(128),
354
353
  state: z.enum(MarketplaceInstallationDecisionStates),
355
354
  }));
@@ -360,7 +359,7 @@ export const MarketplaceInstallationSchema = z.object({
360
359
  installationId: z.string().min(1).max(128),
361
360
  catalogId: z.string().regex(/^catalog:[a-f0-9]{64}$/),
362
361
  installationInstanceId: z.string().min(1).max(256).optional(),
363
- packageDigest: DigestSchema.optional(),
362
+ packageDigest: Sha256DigestSchema.optional(),
364
363
  requestedHarness: z.string().min(1).max(128),
365
364
  state: MarketplaceInstallationLifecycleStateSchema,
366
365
  installedBy: z.string().min(1).max(256),
@@ -494,7 +493,7 @@ export const ExecutionAcceptanceRequestSchema = CommandContextSchema.extend({
494
493
  marketplacePluginReferences: z
495
494
  .array(z
496
495
  .object({
497
- canonicalContentDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
496
+ canonicalContentDigest: Sha256DigestSchema,
498
497
  pluginId: z.string().regex(/^plugin:[a-z0-9-]+:[a-z0-9][a-z0-9-]{1,127}$/),
499
498
  releaseId: z.string().regex(/^release:[a-f0-9]{64}$/),
500
499
  })
@@ -3,6 +3,7 @@ import { ServiceCallerAssertionSchema } from './authentication.js';
3
3
  import { CorrelationMetadataSchema } from './envelopes.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { ContractVersionSchema } from './versioning.js';
6
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
6
7
  /**
7
8
  * Decision-layer contract (control-plane#558).
8
9
  *
@@ -29,8 +30,6 @@ import { ContractVersionSchema } from './versioning.js';
29
30
  * Spec: docs/architecture/decision-558-resolution-contract.md.
30
31
  */
31
32
  export const DECISION_RESOLUTION_CONTRACT_VERSION = Object.freeze({ major: 1, minor: 2 });
32
- const TimestampSchema = z.iso.datetime();
33
- const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
34
33
  const CapabilityNameSchema = z
35
34
  .string()
36
35
  .min(1)
@@ -284,6 +283,6 @@ export const DecisionLayerResolutionSchema = z
284
283
  .strict(),
285
284
  trace: z.record(z.string(), ResolvedOutputSchema),
286
285
  diagnostics: z.array(DecisionResolutionDiagnosticSchema).max(16),
287
- resolutionDigest: DigestSchema,
286
+ resolutionDigest: Sha256DigestSchema,
288
287
  })
289
288
  .strict();
@@ -3,7 +3,7 @@
3
3
  // @adea-ai/runtime-gateway-protocol/device-sync, which re-exports these schemas; this
4
4
  // module has no other import so browser bundles stay small.
5
5
  import { z } from 'zod';
6
- const TimestampSchema = z.iso.datetime();
6
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
7
7
  export const DeviceSyncErrorCodeSchema = z.enum([
8
8
  'SYNC_BLOB_INVALID',
9
9
  'SYNC_BLOB_TOO_LARGE',
@@ -39,7 +39,6 @@ const SyncBase64UrlSchema = z
39
39
  export const SyncAuthorKeyIdSchema = z.string().regex(/^(?:spk|dpk)_[a-f0-9]{32}$/);
40
40
  export const SyncObjectIdSchema = z.string().regex(/^sob_[a-f0-9]{32}$/);
41
41
  export const SyncEntryIdSchema = z.string().regex(/^sen_[a-f0-9]{32}$/);
42
- const SyncSha256Schema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
43
42
  /** What the server stores and serves for one entry, signed by its author over these fields. */
44
43
  export const SignedSyncEntrySchema = z
45
44
  .object({
@@ -60,7 +59,7 @@ export const SyncUploadRequestSchema = z
60
59
  .object({
61
60
  objectId: SyncObjectIdSchema,
62
61
  size: z.number().int().min(MIN_SYNC_CIPHERTEXT_BYTES).max(MAX_SYNC_CIPHERTEXT_BYTES),
63
- ciphertextSha256: SyncSha256Schema,
62
+ ciphertextSha256: Sha256DigestSchema,
64
63
  })
65
64
  .strict();
66
65
  const PresignedSyncUrlSchema = z.url().max(4096);
@@ -0,0 +1,5 @@
1
+ export declare function sha256Hex(data: string | Uint8Array): string;
2
+ /** `sha256:` and the hex digest, the form Sha256DigestSchema accepts. */
3
+ export declare function sha256Digest(data: string | Uint8Array): `sha256:${string}`;
4
+ export declare function canonicalSha256Hex(value: unknown): string;
5
+ export declare function canonicalSha256Digest(value: unknown): `sha256:${string}`;
package/dist/digest.js ADDED
@@ -0,0 +1,15 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { canonicalJsonStringify } from './canonical-json.js';
3
+ export function sha256Hex(data) {
4
+ return createHash('sha256').update(data).digest('hex');
5
+ }
6
+ /** `sha256:` and the hex digest, the form Sha256DigestSchema accepts. */
7
+ export function sha256Digest(data) {
8
+ return `sha256:${sha256Hex(data)}`;
9
+ }
10
+ export function canonicalSha256Hex(value) {
11
+ return sha256Hex(canonicalJsonStringify(value));
12
+ }
13
+ export function canonicalSha256Digest(value) {
14
+ return sha256Digest(canonicalJsonStringify(value));
15
+ }
package/dist/envelopes.js CHANGED
@@ -2,7 +2,7 @@ import { z } from 'zod';
2
2
  import { ServiceCallerAssertionSchema } from './authentication.js';
3
3
  import { IdentifierSchemas } from './identifiers.js';
4
4
  import { ContractVersionSchema } from './versioning.js';
5
- const TimestampSchema = z.iso.datetime();
5
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
6
6
  const OperationSchema = z
7
7
  .string()
8
8
  .min(1)
@@ -149,7 +149,7 @@ export const ArtifactReferenceSchema = z.object({
149
149
  artifactId: IdentifierSchemas.artifactId,
150
150
  version: z.number().int().positive(),
151
151
  mediaType: z.string().min(1).max(128),
152
- digest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
152
+ digest: Sha256DigestSchema,
153
153
  sizeBytes: z.number().int().nonnegative(),
154
154
  locator: z.string().min(1).max(512),
155
155
  });
@@ -4,6 +4,13 @@ export type OpaqueIdentifier<Kind extends string> = string & {
4
4
  };
5
5
  /** Opaque identifiers use a fixed canonical suffix after their three-character kind prefix. */
6
6
  export declare const OPAQUE_IDENTIFIER_SUFFIX_LENGTH = 26;
7
+ /** Encodes the low 130 bits of a hex value as a canonical opaque suffix. */
8
+ export declare function opaqueSuffixFromHex(hex: string): string;
9
+ /** Encodes the first 128 bits of a `sha256:` digest, most significant bit first. */
10
+ export declare function opaqueSuffixFromDigest(digest: string): string;
11
+ export declare function randomOpaqueSuffix(): string;
12
+ /** The identifier of another kind that shares `identifier`'s suffix, e.g. an execution's workflow. */
13
+ export declare function siblingIdentifier(prefix: string, identifier: string): string;
7
14
  export declare const IdentifierSchemas: {
8
15
  readonly requestId: z.ZodPipe<z.ZodString, z.ZodTransform<OpaqueIdentifier<"request ID">, string>>;
9
16
  readonly commandId: z.ZodPipe<z.ZodString, z.ZodTransform<OpaqueIdentifier<"command ID">, string>>;
@@ -76,3 +83,4 @@ export type ModelCallId = z.output<(typeof IdentifierSchemas)['modelCallId']>;
76
83
  export type MemoryWriteProposalId = z.output<(typeof IdentifierSchemas)['memoryWriteProposalId']>;
77
84
  export type EventId = z.output<(typeof IdentifierSchemas)['eventId']>;
78
85
  export type TraceId = z.output<(typeof IdentifierSchemas)['traceId']>;
86
+ export declare function workflowIdForExecution(executionId: string): string;
@@ -7,6 +7,43 @@ const opaqueIdentifier = (prefix, kind) => z
7
7
  // nosemgrep: javascript.lang.security.audit.detect-non-literal-regexp.detect-non-literal-regexp -- pattern built from a repo constant or escaped value, anchored; not attacker input
8
8
  new RegExp(`^${prefix}_[0-9A-HJKMNP-TV-Z]{${OPAQUE_IDENTIFIER_SUFFIX_LENGTH}}$`), `Expected a canonical opaque ${kind}`)
9
9
  .transform((value) => value);
10
+ const CROCKFORD_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
11
+ /** Encodes the low 130 bits of a hex value as a canonical opaque suffix. */
12
+ export function opaqueSuffixFromHex(hex) {
13
+ let value = BigInt(`0x${hex}`);
14
+ let encoded = '';
15
+ for (let index = 0; index < OPAQUE_IDENTIFIER_SUFFIX_LENGTH; index += 1) {
16
+ encoded = CROCKFORD_ALPHABET[Number(value & 31n)] + encoded;
17
+ value >>= 5n;
18
+ }
19
+ return encoded;
20
+ }
21
+ /** Encodes the first 128 bits of a `sha256:` digest, most significant bit first. */
22
+ export function opaqueSuffixFromDigest(digest) {
23
+ const hex = digest.slice('sha256:'.length, 'sha256:'.length + 32);
24
+ let bits = 0;
25
+ let value = 0;
26
+ let output = '';
27
+ for (let index = 0; index < hex.length; index += 2) {
28
+ value = (value << 8) | Number.parseInt(hex.slice(index, index + 2), 16);
29
+ bits += 8;
30
+ while (bits >= 5) {
31
+ output += CROCKFORD_ALPHABET[(value >>> (bits - 5)) & 31];
32
+ bits -= 5;
33
+ }
34
+ }
35
+ if (bits > 0)
36
+ output += CROCKFORD_ALPHABET[(value << (5 - bits)) & 31];
37
+ return output.slice(0, OPAQUE_IDENTIFIER_SUFFIX_LENGTH);
38
+ }
39
+ export function randomOpaqueSuffix() {
40
+ const bytes = crypto.getRandomValues(new Uint8Array(16));
41
+ return opaqueSuffixFromHex(Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(''));
42
+ }
43
+ /** The identifier of another kind that shares `identifier`'s suffix, e.g. an execution's workflow. */
44
+ export function siblingIdentifier(prefix, identifier) {
45
+ return `${prefix}_${identifier.slice(-OPAQUE_IDENTIFIER_SUFFIX_LENGTH)}`;
46
+ }
10
47
  export const IdentifierSchemas = {
11
48
  requestId: opaqueIdentifier('req', 'request ID'),
12
49
  commandId: opaqueIdentifier('cmd', 'command ID'),
@@ -44,3 +81,6 @@ export const IdentifierSchemas = {
44
81
  eventId: opaqueIdentifier('evt', 'event ID'),
45
82
  traceId: opaqueIdentifier('trc', 'trace ID'),
46
83
  };
84
+ export function workflowIdForExecution(executionId) {
85
+ return siblingIdentifier('wfl', executionId);
86
+ }
package/dist/index.d.ts CHANGED
@@ -12,6 +12,7 @@ export * from './fixtures.js';
12
12
  export * from './identifiers.js';
13
13
  export * from './memory-writeback.js';
14
14
  export * from './pagination.js';
15
+ export * from './primitives.js';
15
16
  export * from './runtime-discovery.js';
16
17
  export * from './versioning.js';
17
18
  export * from './workspace-catalog.js';
package/dist/index.js CHANGED
@@ -16,6 +16,7 @@ export * from './fixtures.js';
16
16
  export * from './identifiers.js';
17
17
  export * from './memory-writeback.js';
18
18
  export * from './pagination.js';
19
+ export * from './primitives.js';
19
20
  export * from './runtime-discovery.js';
20
21
  export * from './versioning.js';
21
22
  export * from './workspace-catalog.js';
@@ -1,9 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { IdentifierSchemas } from './identifiers.js';
3
- const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
3
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
4
4
  const ProviderIdSchema = z.string().regex(/^ctp_[0-9A-HJKMNP-TV-Z]{26}$/);
5
5
  const ConnectionIdSchema = z.string().regex(/^ctc_[0-9A-HJKMNP-TV-Z]{26}$/);
6
- const TimestampSchema = z.iso.datetime();
7
6
  export const MemoryWritePolicySchema = z.object({
8
7
  mode: z.enum(['disabled', 'proposal_only', 'approval_required']).default('disabled'),
9
8
  maximumBytes: z.number().int().positive().max(65_536),
@@ -16,7 +15,7 @@ export const MemoryWriteProposalSchema = z
16
15
  providerId: ProviderIdSchema,
17
16
  connectionId: ConnectionIdSchema,
18
17
  workspaceId: IdentifierSchemas.workspaceId,
19
- scopeDigest: DigestSchema,
18
+ scopeDigest: Sha256DigestSchema,
20
19
  memoryType: z.enum(['fact', 'preference', 'observation', 'summary']),
21
20
  content: z.string().min(1).max(65_536),
22
21
  retention: z.enum(['session', 'project', 'durable']),
@@ -31,7 +30,7 @@ export const MemoryWriteProposalSchema = z
31
30
  artifactRefs: z.array(IdentifierSchemas.artifactId).max(64),
32
31
  }),
33
32
  dedupeHint: z.string().min(1).max(256),
34
- contentDigest: DigestSchema,
33
+ contentDigest: Sha256DigestSchema,
35
34
  state: z.enum([
36
35
  'proposed',
37
36
  'awaiting_approval',
@@ -3,6 +3,7 @@ import { ReadRequestEnvelopeSchema, StateChangingCommandEnvelopeSchema, SuccessR
3
3
  import { ServiceCallerAssertionSchema } from './authentication.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { CursorSchema } from './pagination.js';
6
+ import { TimestampSchema } from './primitives.js';
6
7
  const Ref = z
7
8
  .string()
8
9
  .min(1)
@@ -61,7 +62,7 @@ export const ModelConnectionSchema = z
61
62
  grantRef: Ref,
62
63
  revision: Revision,
63
64
  status: z.enum(['active', 'revoked']),
64
- expiresAt: z.iso.datetime(),
65
+ expiresAt: TimestampSchema,
65
66
  }),
66
67
  })
67
68
  .refine(fundingMatches, { message: 'Authentication and funding provenance must agree' });
@@ -3,6 +3,7 @@ import { IdentifierSchemas } from './identifiers.js';
3
3
  import { ReadRequestEnvelopeSchema, SuccessResponseEnvelopeSchema } from './envelopes.js';
4
4
  import { ServiceCallerAssertionSchema } from './authentication.js';
5
5
  import { ModelConnectionSchema, ModelFundingSourceSchema, ModelReadinessReasonSchema, ModelSelectionRefSchema, } from './model-connections.js';
6
+ import { TimestampSchema } from './primitives.js';
6
7
  const Ref = z
7
8
  .string()
8
9
  .min(1)
@@ -38,7 +39,7 @@ export const ModelSelectionFundingViewSchema = z.discriminatedUnion('state', [
38
39
  fundingOwner: ModelFundingOwnerSchema,
39
40
  authorizationRef: Ref,
40
41
  authorityRevision: Revision,
41
- expiresAt: z.iso.datetime(),
42
+ expiresAt: TimestampSchema,
42
43
  }),
43
44
  z.strictObject({
44
45
  ...Binding,
@@ -3,6 +3,7 @@ import { IdentifierSchemas } from './identifiers.js';
3
3
  import { ReadRequestEnvelopeSchema, SuccessResponseEnvelopeSchema } from './envelopes.js';
4
4
  import { ServiceCallerAssertionSchema } from './authentication.js';
5
5
  import { PiLeadPublicationSchema } from './pi-lead-publication.js';
6
+ import { TimestampSchema } from './primitives.js';
6
7
  /** One short, plain-text conclusion attested by the canonical child result producer.
7
8
  * Arbitrary runtime JSON and artifact references are never publication content. */
8
9
  export const PiChildConclusionSchema = z
@@ -56,9 +57,9 @@ export const PiChildPublicationSchema = z
56
57
  .max(256)
57
58
  .regex(/^[A-Za-z0-9][A-Za-z0-9._:/-]*$/)
58
59
  .optional(),
59
- occurredAt: z.iso.datetime(),
60
+ occurredAt: TimestampSchema,
60
61
  authorityRevision: z.number().int().positive(),
61
- expiresAt: z.iso.datetime(),
62
+ expiresAt: TimestampSchema,
62
63
  })
63
64
  .superRefine((value, context) => {
64
65
  if (value.state === 'completed'
@@ -3,6 +3,7 @@ import { IdentifierSchemas } from './identifiers.js';
3
3
  import { ReadRequestEnvelopeSchema, SuccessResponseEnvelopeSchema } from './envelopes.js';
4
4
  import { ServiceCallerAssertionSchema } from './authentication.js';
5
5
  import { ModelSelectionRefSchema } from './model-connections.js';
6
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
6
7
  /** A lock-safe current delivery check. It grants no admission, spending or credential authority. */
7
8
  export const PiLeadPublicationSchema = z.strictObject({
8
9
  schemaVersion: z.literal('pi-lead-publication/v1'),
@@ -19,8 +20,8 @@ export const PiLeadPublicationSchema = z.strictObject({
19
20
  .string()
20
21
  .regex(/^user:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i),
21
22
  authorityRevision: z.number().int().positive(),
22
- resultContentDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/),
23
- expiresAt: z.iso.datetime(),
23
+ resultContentDigest: Sha256DigestSchema,
24
+ expiresAt: TimestampSchema,
24
25
  });
25
26
  export const PiLeadPublicationRequestSchema = ReadRequestEnvelopeSchema.omit({ projectId: true })
26
27
  .extend({
@@ -0,0 +1,4 @@
1
+ import { z } from 'zod';
2
+ export declare const Sha256DigestSchema: z.ZodString;
3
+ export declare function isSha256Digest(value: unknown): value is string;
4
+ export declare const TimestampSchema: z.ZodISODateTime;
@@ -0,0 +1,7 @@
1
+ import { z } from 'zod';
2
+ const SHA256_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/;
3
+ export const Sha256DigestSchema = z.string().regex(SHA256_DIGEST_PATTERN);
4
+ export function isSha256Digest(value) {
5
+ return typeof value === 'string' && SHA256_DIGEST_PATTERN.test(value);
6
+ }
7
+ export const TimestampSchema = z.iso.datetime();
@@ -4,7 +4,7 @@ import { CorrelationMetadataSchema } from './envelopes.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { ContractVersionSchema } from './versioning.js';
6
6
  import { CursorSchema, PageSchema } from './pagination.js';
7
- declare const TimestampSchema: z.ZodISODateTime;
7
+ import { TimestampSchema } from './primitives.js';
8
8
  declare const CapabilityNameSchema: z.ZodString;
9
9
  declare const DiagnosticCodeSchema: z.ZodString;
10
10
  declare const SemanticVersionSchema: z.ZodString;
@@ -4,7 +4,7 @@ import { CorrelationMetadataSchema } from './envelopes.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { ContractVersionSchema } from './versioning.js';
6
6
  import { CursorSchema, PageSchema } from './pagination.js';
7
- const TimestampSchema = z.iso.datetime();
7
+ import { TimestampSchema } from './primitives.js';
8
8
  const CapabilityNameSchema = z
9
9
  .string()
10
10
  .min(1)
@@ -1,4 +1,5 @@
1
1
  import { z } from 'zod';
2
+ import { TimestampSchema } from './primitives.js';
2
3
  export const ContractVersionSchema = z
3
4
  .object({
4
5
  major: z.number().int().positive(),
@@ -48,8 +49,8 @@ export function negotiateContractVersion(localVersions, remoteVersions) {
48
49
  }
49
50
  export const ContractDeprecationSchema = z
50
51
  .object({
51
- deprecatedAt: z.iso.datetime(),
52
- sunsetAt: z.iso.datetime().optional(),
52
+ deprecatedAt: TimestampSchema,
53
+ sunsetAt: TimestampSchema.optional(),
53
54
  replacement: ContractVersionSchema.optional(),
54
55
  documentationUrl: z.url().optional(),
55
56
  })
@@ -4,6 +4,7 @@ import { CorrelationMetadataSchema } from './envelopes.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { CursorSchema } from './pagination.js';
6
6
  import { ContractVersionSchema } from './versioning.js';
7
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
7
8
  /**
8
9
  * Workspace catalog administration (additive within contract major 3). Adea manages Skills and
9
10
  * AgentProfiles owned by the envelope workspace and reads system entries visible to it.
@@ -11,8 +12,6 @@ import { ContractVersionSchema } from './versioning.js';
11
12
  * as JSON objects and is validated by the Control Plane's versioned catalog schemas
12
13
  * (`docs/profiles-and-skills.md`); this package stays free of domain dependencies.
13
14
  */
14
- declare const TimestampSchema: z.ZodISODateTime;
15
- declare const DigestSchema: z.ZodString;
16
15
  declare const IdempotencyKeySchema: z.ZodString;
17
16
  declare const PayloadHashSchema: z.ZodString;
18
17
  declare const DisplayNameSchema: z.ZodString;
@@ -49,7 +48,7 @@ export declare const WorkspaceSkillVersionSummarySchema: z.ZodObject<{
49
48
  semanticVersion: z.ZodString;
50
49
  revision: z.ZodNumber;
51
50
  lifecycle: typeof WorkspaceCatalogLifecycleSchema;
52
- contentDigest: typeof DigestSchema;
51
+ contentDigest: typeof Sha256DigestSchema;
53
52
  createdAt: typeof TimestampSchema;
54
53
  lifecycleMetadata: z.ZodObject<{
55
54
  publishedAt: z.ZodOptional<typeof TimestampSchema>;
@@ -66,7 +65,7 @@ export declare const WorkspaceSkillVersionSchema: z.ZodObject<{
66
65
  semanticVersion: z.ZodString;
67
66
  revision: z.ZodNumber;
68
67
  lifecycle: typeof WorkspaceCatalogLifecycleSchema;
69
- contentDigest: typeof DigestSchema;
68
+ contentDigest: typeof Sha256DigestSchema;
70
69
  createdAt: typeof TimestampSchema;
71
70
  lifecycleMetadata: z.ZodObject<{
72
71
  publishedAt: z.ZodOptional<typeof TimestampSchema>;
@@ -93,7 +92,7 @@ export declare const WorkspaceAgentProfileVersionSummarySchema: z.ZodObject<{
93
92
  revision: z.ZodNumber;
94
93
  schemaVersion: z.ZodNumber;
95
94
  lifecycle: typeof WorkspaceCatalogLifecycleSchema;
96
- contentDigest: typeof DigestSchema;
95
+ contentDigest: typeof Sha256DigestSchema;
97
96
  createdAt: typeof TimestampSchema;
98
97
  lifecycleMetadata: z.ZodObject<{
99
98
  publishedAt: z.ZodOptional<typeof TimestampSchema>;
@@ -111,7 +110,7 @@ export declare const WorkspaceAgentProfileVersionSchema: z.ZodObject<{
111
110
  revision: z.ZodNumber;
112
111
  schemaVersion: z.ZodNumber;
113
112
  lifecycle: typeof WorkspaceCatalogLifecycleSchema;
114
- contentDigest: typeof DigestSchema;
113
+ contentDigest: typeof Sha256DigestSchema;
115
114
  createdAt: typeof TimestampSchema;
116
115
  lifecycleMetadata: z.ZodObject<{
117
116
  publishedAt: z.ZodOptional<typeof TimestampSchema>;
@@ -201,7 +200,7 @@ export declare const WorkspaceSkillPublishResponseSchema: z.ZodObject<{
201
200
  semanticVersion: z.ZodString;
202
201
  revision: z.ZodNumber;
203
202
  lifecycle: typeof WorkspaceCatalogLifecycleSchema;
204
- contentDigest: typeof DigestSchema;
203
+ contentDigest: typeof Sha256DigestSchema;
205
204
  createdAt: typeof TimestampSchema;
206
205
  lifecycleMetadata: z.ZodObject<{
207
206
  publishedAt: z.ZodOptional<typeof TimestampSchema>;
@@ -4,6 +4,7 @@ import { CorrelationMetadataSchema } from './envelopes.js';
4
4
  import { IdentifierSchemas } from './identifiers.js';
5
5
  import { CursorSchema } from './pagination.js';
6
6
  import { ContractVersionSchema } from './versioning.js';
7
+ import { Sha256DigestSchema, TimestampSchema } from './primitives.js';
7
8
  /**
8
9
  * Workspace catalog administration (additive within contract major 3). Adea manages Skills and
9
10
  * AgentProfiles owned by the envelope workspace and reads system entries visible to it.
@@ -11,8 +12,6 @@ import { ContractVersionSchema } from './versioning.js';
11
12
  * as JSON objects and is validated by the Control Plane's versioned catalog schemas
12
13
  * (`docs/profiles-and-skills.md`); this package stays free of domain dependencies.
13
14
  */
14
- const TimestampSchema = z.iso.datetime();
15
- const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
16
15
  const IdempotencyKeySchema = z
17
16
  .string()
18
17
  .min(16)
@@ -90,7 +89,7 @@ export const WorkspaceSkillVersionSummarySchema = z
90
89
  semanticVersion: z.string().min(1).max(256),
91
90
  revision: z.number().int().positive(),
92
91
  lifecycle: WorkspaceCatalogLifecycleSchema,
93
- contentDigest: DigestSchema,
92
+ contentDigest: Sha256DigestSchema,
94
93
  createdAt: TimestampSchema,
95
94
  lifecycleMetadata: LifecycleMetadataSchema.extend({
96
95
  supersededByVersionId: IdentifierSchemas.skillVersionId.optional(),
@@ -118,7 +117,7 @@ export const WorkspaceAgentProfileVersionSummarySchema = z
118
117
  revision: z.number().int().positive(),
119
118
  schemaVersion: z.number().int().positive(),
120
119
  lifecycle: WorkspaceCatalogLifecycleSchema,
121
- contentDigest: DigestSchema,
120
+ contentDigest: Sha256DigestSchema,
122
121
  createdAt: TimestampSchema,
123
122
  lifecycleMetadata: LifecycleMetadataSchema.extend({
124
123
  supersededByVersionId: IdentifierSchemas.profileVersionId.optional(),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adea-ai/contracts",
3
- "version": "5.0.1",
3
+ "version": "5.0.3",
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",
@@ -33,9 +33,17 @@
33
33
  "types": "./dist/canonical-json.d.ts",
34
34
  "default": "./dist/canonical-json.js"
35
35
  },
36
+ "./digest": {
37
+ "types": "./dist/digest.d.ts",
38
+ "default": "./dist/digest.js"
39
+ },
36
40
  "./device-sync": {
37
41
  "types": "./dist/device-sync.d.ts",
38
42
  "default": "./dist/device-sync.js"
43
+ },
44
+ "./primitives": {
45
+ "types": "./dist/primitives.d.ts",
46
+ "default": "./dist/primitives.js"
39
47
  }
40
48
  },
41
49
  "publishConfig": {