@xemahq/agent-session-runtime 0.7.0 → 0.9.0

package/src/lib/launch-identity/canonical-contract.ts

@@ -1,4 +1,5 @@
 import { canonicalJson, stableHash } from '@xemahq/declarative-reconciler';
+import { Sha256HexSchema } from '@xemahq/kernel-contracts/content-address';
 
 export type CanonicalJsonValue =
   | boolean
@@ -13,7 +14,13 @@ export interface ResourceBindingRef {
   readonly ref: string;
 }
 
-const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+/**
+ * OCI immutable-digest prefix. The digest BODY is validated by the canonical
+ * {@link Sha256HexSchema} rather than a local `[a-f0-9]{64}` copy, so this
+ * package holds no SHA-256 grammar of its own.
+ */
+const IMAGE_DIGEST_PREFIX = 'sha256:';
+
 const SECRET_FIELD_PATTERN =
   /(?:^|[_-])(api[_-]?key|authorization|cookie|credential|password|private[_-]?key|secret|token)(?:$|[_-])/iu;
 const SECRET_CAMEL_CASE_PATTERN =
@@ -70,12 +77,39 @@ export function requireBoolean(value: unknown, path: string): boolean {
 
 export function requireSha256(value: unknown, path: string): string {
   const hash = requireNonEmptyString(value, path);
-  if (!SHA256_PATTERN.test(hash)) {
+  if (!Sha256HexSchema.safeParse(hash).success) {
     throw new TypeError(`${path} must be a lowercase SHA-256 hex digest.`);
   }
   return hash;
 }
 
+/**
+ * Validates an OCI IMMUTABLE image reference — `sha256:<64 lowercase hex>`.
+ *
+ * The single site for this rule. It was previously spelled as an identical
+ * `IMAGE_DIGEST_PATTERN` regex in both `runtime-template-key.ts` and
+ * `compiled-session-launch-plan.ts`; two copies of a security-relevant
+ * "is this reference immutable" check can drift, and each was also a private
+ * restatement of the SHA-256 grammar that `@xemahq/kernel-contracts
+ * /content-address` now owns canonically.
+ */
+export function requireImageDigest(value: unknown, path: string): string {
+  const digest = requireNonEmptyString(value, path);
+  if (!digest.startsWith(IMAGE_DIGEST_PREFIX)) {
+    throw new TypeError(
+      `${path} must be an immutable sha256 image digest.`,
+    );
+  }
+  if (
+    !Sha256HexSchema.safeParse(digest.slice(IMAGE_DIGEST_PREFIX.length)).success
+  ) {
+    throw new TypeError(
+      `${path} must be an immutable sha256 image digest.`,
+    );
+  }
+  return digest;
+}
+
 export function requireNonNegativeSafeInteger(
   value: unknown,
   path: string,

package/src/lib/launch-identity/compiled-session-launch-plan.ts

@@ -6,6 +6,7 @@ import {
   requireCanonicalJsonObject,
   requireEnumValue,
   requireExactObject,
+  requireImageDigest,
   requireNonEmptyString,
   requireSha256,
   requireStringRefs,
@@ -155,7 +156,6 @@ const BINDING_SLOT_CARDINALITIES = Object.values(
 );
 const TENANT_DEPENDENCIES = Object.values(RuntimeTemplateTenantDependency);
 const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
-const IMAGE_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
 const BINDING_SLOT_NAME_PATTERN = /^[a-z][a-z0-9]*(?:[.-][a-z][a-z0-9]*)*$/u;
 const DYNAMIC_LITERAL_PATTERN =
   /\$\{\s*(?:input|tenant|org|organization|project|user|session|thread|domain|token|secret|credential)(?:[.:[\]}]|$)/iu;
@@ -377,15 +377,7 @@ function requireRuntimeRequirements(
 ): CompiledRuntimeRequirements {
   const path = 'CompiledSessionLaunchPlan.runtimeRequirements';
   const object = requireExactObject(value, path, RUNTIME_REQUIREMENT_KEYS);
-  const imageDigest = requireNonEmptyString(
-    object.imageDigest,
-    `${path}.imageDigest`,
-  );
-  if (!IMAGE_DIGEST_PATTERN.test(imageDigest)) {
-    throw new TypeError(
-      `${path}.imageDigest must be an immutable sha256 image digest.`,
-    );
-  }
+  const imageDigest = requireImageDigest(object.imageDigest, `${path}.imageDigest`);
   const requirements = requireStaticPayload(
     object.requirements,
     `${path}.requirements`,

package/src/lib/launch-identity/index.ts

@@ -1,6 +1,8 @@
 export * from './canonical-contract';
 export * from './compiled-session-launch-plan';
 export * from './compiled-session-launch-plan-store';
+export * from './preparation-generation';
+export * from './prepared-launch-variant';
 export * from './runtime-template-key';
 export * from './session-binding';
 export * from './thread-reuse-key';

package/src/lib/launch-identity/preparation-generation.ts

@@ -0,0 +1,171 @@
+import {
+  canonicalContractJson,
+  hashCanonicalContract,
+  requireEnumValue,
+  requireExactObject,
+  requireNonEmptyString,
+  requireNonNegativeSafeInteger,
+  requireSha256,
+} from './canonical-contract';
+
+export enum PreparationGenerationStatus {
+  Validating = 'validating',
+  Materializing = 'materializing',
+  Ready = 'ready',
+  Failed = 'failed',
+  Superseded = 'superseded',
+}
+
+export interface PreparationFailure {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface PreparationGeneration {
+  readonly id: string;
+  readonly agentRevisionId: string;
+  readonly sourceGenerationHash: string;
+  readonly requiredVariantKeyHashes: readonly string[];
+  readonly status: PreparationGenerationStatus;
+  readonly failure?: PreparationFailure;
+  readonly rowVersion: number;
+}
+
+const GENERATION_KEYS = [
+  'id',
+  'agentRevisionId',
+  'sourceGenerationHash',
+  'requiredVariantKeyHashes',
+  'status',
+  'rowVersion',
+] as const;
+const GENERATION_OPTIONAL_KEYS = ['failure'] as const;
+const FAILURE_KEYS = ['code', 'message'] as const;
+const GENERATION_STATUSES = Object.values(PreparationGenerationStatus);
+
+export function createPreparationFailure(input: unknown): PreparationFailure {
+  const object = requireExactObject(input, 'PreparationFailure', FAILURE_KEYS);
+  return Object.freeze({
+    code: requireNonEmptyString(object.code, 'PreparationFailure.code'),
+    message: requireNonEmptyString(
+      object.message,
+      'PreparationFailure.message',
+    ),
+  });
+}
+
+export function createPreparationGeneration(
+  input: unknown,
+): PreparationGeneration {
+  const object = requireExactObject(
+    input,
+    'PreparationGeneration',
+    GENERATION_KEYS,
+    GENERATION_OPTIONAL_KEYS,
+  );
+  const status = requireEnumValue(
+    object.status,
+    'PreparationGeneration.status',
+    GENERATION_STATUSES,
+  );
+  const failure = requireFailureForStatus(
+    object.failure,
+    Object.hasOwn(object, 'failure'),
+    status,
+    'PreparationGeneration',
+  );
+
+  return Object.freeze({
+    id: requireNonEmptyString(object.id, 'PreparationGeneration.id'),
+    agentRevisionId: requireNonEmptyString(
+      object.agentRevisionId,
+      'PreparationGeneration.agentRevisionId',
+    ),
+    sourceGenerationHash: requireSha256(
+      object.sourceGenerationHash,
+      'PreparationGeneration.sourceGenerationHash',
+    ),
+    requiredVariantKeyHashes: requireSortedUniqueHashes(
+      object.requiredVariantKeyHashes,
+      'PreparationGeneration.requiredVariantKeyHashes',
+    ),
+    status,
+    ...(failure === undefined ? {} : { failure }),
+    rowVersion: requireNonNegativeSafeInteger(
+      object.rowVersion,
+      'PreparationGeneration.rowVersion',
+    ),
+  });
+}
+
+export function serializePreparationGeneration(
+  input: PreparationGeneration,
+): string {
+  return canonicalContractJson(createPreparationGeneration(input));
+}
+
+export function hashPreparationGeneration(
+  input: PreparationGeneration,
+): string {
+  return hashCanonicalContract(createPreparationGeneration(input));
+}
+
+export function requirePreparationFailureForStatus(
+  value: unknown,
+  hasFailure: boolean,
+  failed: boolean,
+  path: string,
+): PreparationFailure | undefined {
+  if (failed) {
+    if (!hasFailure) {
+      throw new TypeError(`${path}.failure is required when status is failed.`);
+    }
+    return createPreparationFailure(value);
+  }
+  if (hasFailure) {
+    throw new TypeError(
+      `${path}.failure is only supported when status is failed.`,
+    );
+  }
+  return undefined;
+}
+
+function requireFailureForStatus(
+  value: unknown,
+  hasFailure: boolean,
+  status: PreparationGenerationStatus,
+  path: string,
+): PreparationFailure | undefined {
+  return requirePreparationFailureForStatus(
+    value,
+    hasFailure,
+    status === PreparationGenerationStatus.Failed,
+    path,
+  );
+}
+
+function requireSortedUniqueHashes(
+  value: unknown,
+  path: string,
+): readonly string[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${path} must be an array.`);
+  }
+
+  const hashes = value.map((entry, index) =>
+    requireSha256(entry, `${path}[${index}]`),
+  );
+  for (let index = 1; index < hashes.length; index += 1) {
+    const previous = hashes[index - 1];
+    const current = hashes[index];
+    if (previous === undefined || current === undefined) {
+      throw new TypeError(`${path} contains an invalid sparse entry.`);
+    }
+    if (previous >= current) {
+      throw new TypeError(
+        `${path} must contain unique hashes in ascending lexical order.`,
+      );
+    }
+  }
+  return Object.freeze(hashes);
+}

package/src/lib/launch-identity/prepared-launch-variant.ts

@@ -0,0 +1,263 @@
+import { WorkerRuntimeKind } from '@xemahq/kernel-contracts/worker-runtime';
+
+import {
+  canonicalContractJson,
+  hashCanonicalContract,
+  requireEnumValue,
+  requireExactObject,
+  requireImageDigest,
+  requireNonEmptyString,
+  requireNonNegativeSafeInteger,
+  requireSha256,
+} from './canonical-contract';
+import {
+  requirePreparationFailureForStatus,
+  type PreparationFailure,
+} from './preparation-generation';
+import {
+  RuntimeTemplateTenantDependency,
+  RuntimeTemplateTrustPolicy,
+} from './runtime-template-key';
+
+export enum PreparedLaunchVariantStatus {
+  Materializing = 'materializing',
+  Ready = 'ready',
+  Failed = 'failed',
+  Retired = 'retired',
+}
+
+export type PreparedLaunchTenantDependency =
+  | {
+      readonly kind: RuntimeTemplateTenantDependency.OrganizationNeutral;
+    }
+  | {
+      readonly kind: RuntimeTemplateTenantDependency.OrganizationBound;
+      readonly organizationScopeHash: string;
+    };
+
+export interface PreparedLaunchVariantKey {
+  readonly schemaVersion: 1;
+  readonly runtimeKind: WorkerRuntimeKind;
+  readonly runtimeRevision: string;
+  readonly imageDigest: `sha256:${string}`;
+  readonly layoutProfileRef: string;
+  readonly staticDependencyClosureHash: string;
+  readonly tenantDependency: PreparedLaunchTenantDependency;
+  readonly trustPolicy: RuntimeTemplateTrustPolicy;
+  readonly policyGenerationHash: string;
+  readonly region: string;
+}
+
+export interface PreparedLaunchVariant {
+  readonly id: string;
+  readonly preparationGenerationId: string;
+  readonly key: PreparedLaunchVariantKey;
+  readonly keyHash: string;
+  readonly compiledLaunchPlanHash: string;
+  readonly preparedRuntimeTemplateHash: string;
+  readonly preparedRuntimeTemplateRef: string;
+  readonly status: PreparedLaunchVariantStatus;
+  readonly failure?: PreparationFailure;
+  readonly rowVersion: number;
+}
+
+const KEY_KEYS = [
+  'schemaVersion',
+  'runtimeKind',
+  'runtimeRevision',
+  'imageDigest',
+  'layoutProfileRef',
+  'staticDependencyClosureHash',
+  'tenantDependency',
+  'trustPolicy',
+  'policyGenerationHash',
+  'region',
+] as const;
+const VARIANT_KEYS = [
+  'id',
+  'preparationGenerationId',
+  'key',
+  'keyHash',
+  'compiledLaunchPlanHash',
+  'preparedRuntimeTemplateHash',
+  'preparedRuntimeTemplateRef',
+  'status',
+  'rowVersion',
+] as const;
+const VARIANT_OPTIONAL_KEYS = ['failure'] as const;
+const RUNTIME_KINDS = Object.values(WorkerRuntimeKind);
+const TENANT_DEPENDENCY_KINDS = Object.values(RuntimeTemplateTenantDependency);
+const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
+const VARIANT_STATUSES = Object.values(PreparedLaunchVariantStatus);
+
+export function createPreparedLaunchVariantKey(
+  input: unknown,
+): PreparedLaunchVariantKey {
+  const object = requireExactObject(
+    input,
+    'PreparedLaunchVariantKey',
+    KEY_KEYS,
+  );
+  if (object.schemaVersion !== 1) {
+    throw new TypeError('PreparedLaunchVariantKey.schemaVersion must be 1.');
+  }
+
+  return Object.freeze({
+    schemaVersion: 1,
+    runtimeKind: requireEnumValue(
+      object.runtimeKind,
+      'PreparedLaunchVariantKey.runtimeKind',
+      RUNTIME_KINDS,
+    ),
+    runtimeRevision: requireNonEmptyString(
+      object.runtimeRevision,
+      'PreparedLaunchVariantKey.runtimeRevision',
+    ),
+    imageDigest: requireImageDigest(
+      object.imageDigest,
+      'PreparedLaunchVariantKey.imageDigest',
+    ) as `sha256:${string}`,
+    layoutProfileRef: requireNonEmptyString(
+      object.layoutProfileRef,
+      'PreparedLaunchVariantKey.layoutProfileRef',
+    ),
+    staticDependencyClosureHash: requireSha256(
+      object.staticDependencyClosureHash,
+      'PreparedLaunchVariantKey.staticDependencyClosureHash',
+    ),
+    tenantDependency: requireTenantDependency(object.tenantDependency),
+    trustPolicy: requireEnumValue(
+      object.trustPolicy,
+      'PreparedLaunchVariantKey.trustPolicy',
+      TRUST_POLICIES,
+    ),
+    policyGenerationHash: requireSha256(
+      object.policyGenerationHash,
+      'PreparedLaunchVariantKey.policyGenerationHash',
+    ),
+    region: requireNonEmptyString(
+      object.region,
+      'PreparedLaunchVariantKey.region',
+    ),
+  });
+}
+
+export function serializePreparedLaunchVariantKey(
+  input: PreparedLaunchVariantKey,
+): string {
+  return canonicalContractJson(createPreparedLaunchVariantKey(input));
+}
+
+export function hashPreparedLaunchVariantKey(
+  input: PreparedLaunchVariantKey,
+): string {
+  return hashCanonicalContract(createPreparedLaunchVariantKey(input));
+}
+
+export function createPreparedLaunchVariant(
+  input: unknown,
+): PreparedLaunchVariant {
+  const object = requireExactObject(
+    input,
+    'PreparedLaunchVariant',
+    VARIANT_KEYS,
+    VARIANT_OPTIONAL_KEYS,
+  );
+  const key = createPreparedLaunchVariantKey(object.key);
+  const keyHash = requireSha256(
+    object.keyHash,
+    'PreparedLaunchVariant.keyHash',
+  );
+  if (keyHash !== hashPreparedLaunchVariantKey(key)) {
+    throw new TypeError(
+      'PreparedLaunchVariant.keyHash must equal the canonical key hash.',
+    );
+  }
+  const status = requireEnumValue(
+    object.status,
+    'PreparedLaunchVariant.status',
+    VARIANT_STATUSES,
+  );
+  const failure = requirePreparationFailureForStatus(
+    object.failure,
+    Object.hasOwn(object, 'failure'),
+    status === PreparedLaunchVariantStatus.Failed,
+    'PreparedLaunchVariant',
+  );
+
+  return Object.freeze({
+    id: requireNonEmptyString(object.id, 'PreparedLaunchVariant.id'),
+    preparationGenerationId: requireNonEmptyString(
+      object.preparationGenerationId,
+      'PreparedLaunchVariant.preparationGenerationId',
+    ),
+    key,
+    keyHash,
+    compiledLaunchPlanHash: requireSha256(
+      object.compiledLaunchPlanHash,
+      'PreparedLaunchVariant.compiledLaunchPlanHash',
+    ),
+    preparedRuntimeTemplateHash: requireSha256(
+      object.preparedRuntimeTemplateHash,
+      'PreparedLaunchVariant.preparedRuntimeTemplateHash',
+    ),
+    preparedRuntimeTemplateRef: requireNonEmptyString(
+      object.preparedRuntimeTemplateRef,
+      'PreparedLaunchVariant.preparedRuntimeTemplateRef',
+    ),
+    status,
+    ...(failure === undefined ? {} : { failure }),
+    rowVersion: requireNonNegativeSafeInteger(
+      object.rowVersion,
+      'PreparedLaunchVariant.rowVersion',
+    ),
+  });
+}
+
+export function serializePreparedLaunchVariant(
+  input: PreparedLaunchVariant,
+): string {
+  return canonicalContractJson(createPreparedLaunchVariant(input));
+}
+
+export function hashPreparedLaunchVariant(
+  input: PreparedLaunchVariant,
+): string {
+  return hashCanonicalContract(createPreparedLaunchVariant(input));
+}
+
+function requireTenantDependency(
+  input: unknown,
+): PreparedLaunchTenantDependency {
+  const base = requireExactObject(
+    input,
+    'PreparedLaunchVariantKey.tenantDependency',
+    ['kind'],
+    ['organizationScopeHash'],
+  );
+  const kind = requireEnumValue(
+    base.kind,
+    'PreparedLaunchVariantKey.tenantDependency.kind',
+    TENANT_DEPENDENCY_KINDS,
+  );
+  if (kind === RuntimeTemplateTenantDependency.OrganizationNeutral) {
+    if (Object.hasOwn(base, 'organizationScopeHash')) {
+      throw new TypeError(
+        'PreparedLaunchVariantKey.tenantDependency.organizationScopeHash is forbidden for organization-neutral variants.',
+      );
+    }
+    return Object.freeze({ kind });
+  }
+  if (!Object.hasOwn(base, 'organizationScopeHash')) {
+    throw new TypeError(
+      'PreparedLaunchVariantKey.tenantDependency.organizationScopeHash is required for organization-bound variants.',
+    );
+  }
+  return Object.freeze({
+    kind,
+    organizationScopeHash: requireSha256(
+      base.organizationScopeHash,
+      'PreparedLaunchVariantKey.tenantDependency.organizationScopeHash',
+    ),
+  });
+}

package/src/lib/launch-identity/runtime-template-key.ts

@@ -4,6 +4,7 @@ import {
   hashCanonicalContract,
   requireEnumValue,
   requireExactObject,
+  requireImageDigest,
   requireNonEmptyString,
   requireSha256,
 } from './canonical-contract';
@@ -57,7 +58,6 @@ const REQUIRED_KEYS = [
 
 const TENANT_DEPENDENCIES = Object.values(RuntimeTemplateTenantDependency);
 const TRUST_POLICIES = Object.values(RuntimeTemplateTrustPolicy);
-const IMAGE_DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
 
 /**
  * Validates and canonicalizes the immutable execution dimensions used to
@@ -72,15 +72,10 @@ export function createRuntimeTemplateKey(input: unknown): RuntimeTemplateKey {
     throw new TypeError('RuntimeTemplateKey.schemaVersion must be 1.');
   }
 
-  const imageDigest = requireNonEmptyString(
+  const imageDigest = requireImageDigest(
     object.imageDigest,
     'RuntimeTemplateKey.imageDigest',
   );
-  if (!IMAGE_DIGEST_PATTERN.test(imageDigest)) {
-    throw new TypeError(
-      'RuntimeTemplateKey.imageDigest must be an immutable sha256 image digest.',
-    );
-  }
 
   return Object.freeze({
     schemaVersion: 1,