@xemahq/agent-session-runtime 0.6.7 → 0.7.0

package/dist/lib/launch-identity/session-binding.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionBinding = createSessionBinding;
+exports.serializeSessionBinding = serializeSessionBinding;
+exports.hashSessionBinding = hashSessionBinding;
+const canonical_contract_1 = require("./canonical-contract");
+const REQUIRED_KEYS = [
+    'schemaVersion',
+    'sessionId',
+    'organizationId',
+    'projectId',
+    'userId',
+    'domainRefs',
+    'storageAllocationRef',
+    'workingFileSourceRefs',
+    'outputRouteRef',
+    'providerTokenRefs',
+    'credentialGrantRefs',
+    'databaseGrantRefs',
+    'dynamicContext',
+    'bindingRevision',
+    'bindingEpoch',
+];
+const OPTIONAL_KEYS = ['actorTokenRef', 'serviceTokenRef'];
+function createSessionBinding(input) {
+    const object = (0, canonical_contract_1.requireExactObject)(input, 'SessionBinding', REQUIRED_KEYS, OPTIONAL_KEYS);
+    if (object.schemaVersion !== 1) {
+        throw new TypeError('SessionBinding.schemaVersion must be 1.');
+    }
+    const actorTokenRef = object.actorTokenRef === undefined
+        ? undefined
+        : (0, canonical_contract_1.requireNonEmptyString)(object.actorTokenRef, 'SessionBinding.actorTokenRef');
+    const serviceTokenRef = object.serviceTokenRef === undefined
+        ? undefined
+        : (0, canonical_contract_1.requireNonEmptyString)(object.serviceTokenRef, 'SessionBinding.serviceTokenRef');
+    return Object.freeze({
+        schemaVersion: 1,
+        sessionId: (0, canonical_contract_1.requireNonEmptyString)(object.sessionId, 'SessionBinding.sessionId'),
+        organizationId: (0, canonical_contract_1.requireNonEmptyString)(object.organizationId, 'SessionBinding.organizationId'),
+        projectId: (0, canonical_contract_1.requireNonEmptyString)(object.projectId, 'SessionBinding.projectId'),
+        userId: (0, canonical_contract_1.requireNonEmptyString)(object.userId, 'SessionBinding.userId'),
+        domainRefs: (0, canonical_contract_1.requireResourceBindingRefs)(object.domainRefs, 'SessionBinding.domainRefs'),
+        storageAllocationRef: (0, canonical_contract_1.requireNonEmptyString)(object.storageAllocationRef, 'SessionBinding.storageAllocationRef'),
+        workingFileSourceRefs: (0, canonical_contract_1.requireStringRefs)(object.workingFileSourceRefs, 'SessionBinding.workingFileSourceRefs'),
+        outputRouteRef: (0, canonical_contract_1.requireNonEmptyString)(object.outputRouteRef, 'SessionBinding.outputRouteRef'),
+        ...(actorTokenRef === undefined ? {} : { actorTokenRef }),
+        ...(serviceTokenRef === undefined ? {} : { serviceTokenRef }),
+        providerTokenRefs: (0, canonical_contract_1.requireStringRefs)(object.providerTokenRefs, 'SessionBinding.providerTokenRefs'),
+        credentialGrantRefs: (0, canonical_contract_1.requireStringRefs)(object.credentialGrantRefs, 'SessionBinding.credentialGrantRefs'),
+        databaseGrantRefs: (0, canonical_contract_1.requireStringRefs)(object.databaseGrantRefs, 'SessionBinding.databaseGrantRefs'),
+        dynamicContext: (0, canonical_contract_1.requireSecretFreeJsonObject)(object.dynamicContext, 'SessionBinding.dynamicContext'),
+        bindingRevision: (0, canonical_contract_1.requireNonEmptyString)(object.bindingRevision, 'SessionBinding.bindingRevision'),
+        bindingEpoch: (0, canonical_contract_1.requireNonNegativeSafeInteger)(object.bindingEpoch, 'SessionBinding.bindingEpoch'),
+    });
+}
+function serializeSessionBinding(input) {
+    return (0, canonical_contract_1.canonicalContractJson)(createSessionBinding(input));
+}
+function hashSessionBinding(input) {
+    return (0, canonical_contract_1.hashCanonicalContract)(createSessionBinding(input));
+}
+//# sourceMappingURL=session-binding.js.map

package/dist/lib/launch-identity/session-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-binding.js","sourceRoot":"","sources":["../../../src/lib/launch-identity/session-binding.ts"],"names":[],"mappings":"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"}

package/dist/lib/launch-identity/thread-reuse-key.d.ts

@@ -0,0 +1,19 @@
+import { type ResourceBindingRef } from './canonical-contract';
+export declare enum ThreadReusePolicy {
+    ExplicitlyShareable = "explicitly-shareable"
+}
+export interface ThreadReuseKey {
+    readonly schemaVersion: 1;
+    readonly reusePolicy: ThreadReusePolicy.ExplicitlyShareable;
+    readonly organizationId: string;
+    readonly projectId: string;
+    readonly userId: string;
+    readonly runtimeTemplateHash: string;
+    readonly conversationRef: string;
+    readonly workspaceRef: string;
+    readonly domainRefs: readonly ResourceBindingRef[];
+}
+export declare function createThreadReuseKey(input: unknown): ThreadReuseKey;
+export declare function serializeThreadReuseKey(input: ThreadReuseKey): string;
+export declare function hashThreadReuseKey(input: ThreadReuseKey): string;
+//# sourceMappingURL=thread-reuse-key.d.ts.map

package/dist/lib/launch-identity/thread-reuse-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-reuse-key.d.ts","sourceRoot":"","sources":["../../../src/lib/launch-identity/thread-reuse-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EAMxB,MAAM,sBAAsB,CAAC;AAE9B,oBAAY,iBAAiB;IAC3B,mBAAmB,yBAAyB;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC,mBAAmB,CAAC;IAC5D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAmBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAwCnE;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAErE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAEhE"}

package/dist/lib/launch-identity/thread-reuse-key.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThreadReusePolicy = void 0;
+exports.createThreadReuseKey = createThreadReuseKey;
+exports.serializeThreadReuseKey = serializeThreadReuseKey;
+exports.hashThreadReuseKey = hashThreadReuseKey;
+const canonical_contract_1 = require("./canonical-contract");
+var ThreadReusePolicy;
+(function (ThreadReusePolicy) {
+    ThreadReusePolicy["ExplicitlyShareable"] = "explicitly-shareable";
+})(ThreadReusePolicy || (exports.ThreadReusePolicy = ThreadReusePolicy = {}));
+const REQUIRED_KEYS = [
+    'schemaVersion',
+    'reusePolicy',
+    'organizationId',
+    'projectId',
+    'userId',
+    'runtimeTemplateHash',
+    'conversationRef',
+    'workspaceRef',
+    'domainRefs',
+];
+function createThreadReuseKey(input) {
+    const object = (0, canonical_contract_1.requireExactObject)(input, 'ThreadReuseKey', REQUIRED_KEYS);
+    if (object.schemaVersion !== 1) {
+        throw new TypeError('ThreadReuseKey.schemaVersion must be 1.');
+    }
+    return Object.freeze({
+        schemaVersion: 1,
+        reusePolicy: (0, canonical_contract_1.requireEnumValue)(object.reusePolicy, 'ThreadReuseKey.reusePolicy', [ThreadReusePolicy.ExplicitlyShareable]),
+        organizationId: (0, canonical_contract_1.requireNonEmptyString)(object.organizationId, 'ThreadReuseKey.organizationId'),
+        projectId: (0, canonical_contract_1.requireNonEmptyString)(object.projectId, 'ThreadReuseKey.projectId'),
+        userId: (0, canonical_contract_1.requireNonEmptyString)(object.userId, 'ThreadReuseKey.userId'),
+        runtimeTemplateHash: (0, canonical_contract_1.requireSha256)(object.runtimeTemplateHash, 'ThreadReuseKey.runtimeTemplateHash'),
+        conversationRef: (0, canonical_contract_1.requireNonEmptyString)(object.conversationRef, 'ThreadReuseKey.conversationRef'),
+        workspaceRef: (0, canonical_contract_1.requireNonEmptyString)(object.workspaceRef, 'ThreadReuseKey.workspaceRef'),
+        domainRefs: (0, canonical_contract_1.requireResourceBindingRefs)(object.domainRefs, 'ThreadReuseKey.domainRefs'),
+    });
+}
+function serializeThreadReuseKey(input) {
+    return (0, canonical_contract_1.canonicalContractJson)(createThreadReuseKey(input));
+}
+function hashThreadReuseKey(input) {
+    return (0, canonical_contract_1.hashCanonicalContract)(createThreadReuseKey(input));
+}
+//# sourceMappingURL=thread-reuse-key.js.map

package/dist/lib/launch-identity/thread-reuse-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-reuse-key.js","sourceRoot":"","sources":["../../../src/lib/launch-identity/thread-reuse-key.ts"],"names":[],"mappings":";;;AA4CA,oDAwCC;AAED,0DAEC;AAED,gDAEC;AA5FD,6DAS8B;AAE9B,IAAY,iBAEX;AAFD,WAAY,iBAAiB;IAC3B,iEAA4C,CAAA;AAC9C,CAAC,EAFW,iBAAiB,iCAAjB,iBAAiB,QAE5B;AAcD,MAAM,aAAa,GAAG;IACpB,eAAe;IACf,aAAa;IACb,gBAAgB;IAChB,WAAW;IACX,QAAQ;IACR,qBAAqB;IACrB,iBAAiB;IACjB,cAAc;IACd,YAAY;CACJ,CAAC;AAOX,SAAgB,oBAAoB,CAAC,KAAc;IACjD,MAAM,MAAM,GAAG,IAAA,uCAAkB,EAAC,KAAK,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;IAE1E,IAAI,MAAM,CAAC,aAAa,KAAK,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IACjE,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,aAAa,EAAE,CAAC;QAChB,WAAW,EAAE,IAAA,qCAAgB,EAC3B,MAAM,CAAC,WAAW,EAClB,4BAA4B,EAC5B,CAAC,iBAAiB,CAAC,mBAAmB,CAAC,CACxC;QACD,cAAc,EAAE,IAAA,0CAAqB,EACnC,MAAM,CAAC,cAAc,EACrB,+BAA+B,CAChC;QACD,SAAS,EAAE,IAAA,0CAAqB,EAC9B,MAAM,CAAC,SAAS,EAChB,0BAA0B,CAC3B;QACD,MAAM,EAAE,IAAA,0CAAqB,EAAC,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC;QACrE,mBAAmB,EAAE,IAAA,kCAAa,EAChC,MAAM,CAAC,mBAAmB,EAC1B,oCAAoC,CACrC;QACD,eAAe,EAAE,IAAA,0CAAqB,EACpC,MAAM,CAAC,eAAe,EACtB,gCAAgC,CACjC;QACD,YAAY,EAAE,IAAA,0CAAqB,EACjC,MAAM,CAAC,YAAY,EACnB,6BAA6B,CAC9B;QACD,UAAU,EAAE,IAAA,+CAA0B,EACpC,MAAM,CAAC,UAAU,EACjB,2BAA2B,CAC5B;KACF,CAAC,CAAC;AACL,CAAC;AAED,SAAgB,uBAAuB,CAAC,KAAqB;IAC3D,OAAO,IAAA,0CAAqB,EAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,SAAgB,kBAAkB,CAAC,KAAqB;IACtD,OAAO,IAAA,0CAAqB,EAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/agent-session-runtime",
-  "version": "0.6.7",
+  "version": "0.7.0",
   "description": "Runtime for composing and running Xema agent sessions — workspace manifests, skill bundles, environment resolution, and drift detection.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -45,11 +45,12 @@
     "prettier": "3.6.2",
     "ts-jest": "^29.4.9",
     "typescript": "5.9.3",
-    "@xemahq/kernel-contracts": "^0.58.0"
+    "@xemahq/kernel-contracts": "^0.60.0"
   },
   "dependencies": {
+    "@xemahq/declarative-reconciler": "^0.1.1",
     "@xemahq/dsl": "^0.6.1",
-    "@xemahq/kernel-contracts": "^0.58.0"
+    "@xemahq/kernel-contracts": "^0.60.0"
   },
   "peerDependencies": {
     "@xemahq/kernel-contracts": ">=0.13.0"

package/src/index.ts

@@ -33,3 +33,4 @@ export * from './lib/environment-resolver';
 export * from './lib/drift-detector';
 export * from './lib/lifecycle-state';
 export * from './lib/dispatch-contract';
+export * from './lib/launch-identity';

package/src/lib/dispatch-contract.ts

@@ -83,15 +83,10 @@ export interface CreateAndRunDispatch {
   readonly jobRunId: string;
   /** Stable spine identity within the workflow run. */
   readonly jobKey: string;
-  /**
-   * Agent ref (`slug` = latest published, or `slug@version`)
-   * the new pipeline-owned session should bootstrap from. The dispatch
-   * service stamps this onto `Session.agentRef`; the session
-   * lifecycle resolves it via llm-registry-api's `GET /compositions/
-   * resolve/:ref` for both the agent/skill/tool tree and the workspace
-   * mount layout.
-   */
-  readonly agentRef: string;
+  /** Immutable AgentRevision selected by workflow resolution. */
+  readonly agentRevisionId: string;
+  /** SHA-256 of the selected AgentRevision content. */
+  readonly agentContentHash: string;
   readonly agentSlug: string;
   readonly promptContext: DispatchPromptContext;
 }

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

@@ -0,0 +1,318 @@
+import { canonicalJson, stableHash } from '@xemahq/declarative-reconciler';
+
+export type CanonicalJsonValue =
+  | boolean
+  | number
+  | string
+  | null
+  | readonly CanonicalJsonValue[]
+  | { readonly [key: string]: CanonicalJsonValue };
+
+export interface ResourceBindingRef {
+  readonly kind: string;
+  readonly ref: string;
+}
+
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+const SECRET_FIELD_PATTERN =
+  /(?:^|[_-])(api[_-]?key|authorization|cookie|credential|password|private[_-]?key|secret|token)(?:$|[_-])/iu;
+const SECRET_CAMEL_CASE_PATTERN =
+  /(?:apiKey|authorization|cookie|credential|password|privateKey|secret|token)/u;
+const SECRET_REFERENCE_SUFFIX_PATTERN = /Refs?$/u;
+
+export function canonicalContractJson(value: unknown): string {
+  return canonicalJson(value);
+}
+
+export function hashCanonicalContract(value: unknown): string {
+  return stableHash(value);
+}
+
+export function requireExactObject(
+  value: unknown,
+  path: string,
+  requiredKeys: readonly string[],
+  optionalKeys: readonly string[] = [],
+): Readonly<Record<string, unknown>> {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${path} must be a plain object.`);
+  }
+
+  const allowedKeys = new Set([...requiredKeys, ...optionalKeys]);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      throw new TypeError(`${path}.${key} is not a supported field.`);
+    }
+  }
+
+  for (const key of requiredKeys) {
+    if (!Object.hasOwn(value, key)) {
+      throw new TypeError(`${path}.${key} is required.`);
+    }
+  }
+
+  return value;
+}
+
+export function requireNonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${path} must be a non-empty string.`);
+  }
+  return value;
+}
+
+export function requireBoolean(value: unknown, path: string): boolean {
+  if (typeof value !== 'boolean') {
+    throw new TypeError(`${path} must be a boolean.`);
+  }
+  return value;
+}
+
+export function requireSha256(value: unknown, path: string): string {
+  const hash = requireNonEmptyString(value, path);
+  if (!SHA256_PATTERN.test(hash)) {
+    throw new TypeError(`${path} must be a lowercase SHA-256 hex digest.`);
+  }
+  return hash;
+}
+
+export function requireNonNegativeSafeInteger(
+  value: unknown,
+  path: string,
+): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new TypeError(`${path} must be a non-negative safe integer.`);
+  }
+  return value as number;
+}
+
+export function requireEnumValue<T extends string>(
+  value: unknown,
+  path: string,
+  values: readonly T[],
+): T {
+  if (typeof value !== 'string' || !values.includes(value as T)) {
+    throw new TypeError(
+      `${path} must be one of: ${values.map((entry) => `'${entry}'`).join(', ')}.`,
+    );
+  }
+  return value as T;
+}
+
+export function requireStringRefs(
+  value: unknown,
+  path: string,
+): readonly string[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${path} must be an array.`);
+  }
+
+  return Object.freeze(
+    [
+      ...new Set(
+        value.map((entry, index) =>
+          requireNonEmptyString(entry, `${path}[${index}]`),
+        ),
+      ),
+    ].sort(),
+  );
+}
+
+export function requireResourceBindingRefs(
+  value: unknown,
+  path: string,
+): readonly ResourceBindingRef[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${path} must be an array.`);
+  }
+
+  const refs = value.map((entry, index) => {
+    const entryPath = `${path}[${index}]`;
+    const object = requireExactObject(entry, entryPath, ['kind', 'ref']);
+    return Object.freeze({
+      kind: requireNonEmptyString(object.kind, `${entryPath}.kind`),
+      ref: requireNonEmptyString(object.ref, `${entryPath}.ref`),
+    });
+  });
+
+  const byCanonicalRef = new Map(
+    refs.map((entry) => [canonicalJson(entry), entry] as const),
+  );
+  return Object.freeze(
+    [...byCanonicalRef.entries()]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([, entry]) => entry),
+  );
+}
+
+export function requireSecretFreeJsonObject(
+  value: unknown,
+  path: string,
+): Readonly<Record<string, CanonicalJsonValue>> {
+  const normalized = normalizeCanonicalJson(value, path, true);
+  if (
+    normalized === null ||
+    Array.isArray(normalized) ||
+    typeof normalized !== 'object'
+  ) {
+    throw new TypeError(`${path} must be a plain JSON object.`);
+  }
+  return normalized as Readonly<Record<string, CanonicalJsonValue>>;
+}
+
+export function requireCanonicalJsonObject(
+  value: unknown,
+  path: string,
+): Readonly<Record<string, CanonicalJsonValue>> {
+  const normalized = normalizeCanonicalJson(value, path, false);
+  if (
+    normalized === null ||
+    Array.isArray(normalized) ||
+    typeof normalized !== 'object'
+  ) {
+    throw new TypeError(`${path} must be a plain JSON object.`);
+  }
+  return normalized as Readonly<Record<string, CanonicalJsonValue>>;
+}
+
+export function assertNoTenantOrSecretTemplateFields(
+  value: unknown,
+  path: string,
+): void {
+  const visited = new Set<object>();
+
+  function inspect(current: unknown, currentPath: string): void {
+    if (current === null || typeof current !== 'object') {
+      return;
+    }
+    if (visited.has(current)) {
+      throw new TypeError(`${currentPath} must not contain cycles.`);
+    }
+    visited.add(current);
+
+    if (Array.isArray(current)) {
+      current.forEach((entry, index) =>
+        inspect(entry, `${currentPath}[${index}]`),
+      );
+      return;
+    }
+    if (!isPlainObject(current)) {
+      throw new TypeError(`${currentPath} must contain only plain objects.`);
+    }
+
+    for (const [key, entry] of Object.entries(current)) {
+      if (isTenantField(key) || isSecretField(key)) {
+        throw new TypeError(
+          `${currentPath}.${key} is tenant/session/secret state and cannot enter a RuntimeTemplateKey.`,
+        );
+      }
+      inspect(entry, `${currentPath}.${key}`);
+    }
+  }
+
+  inspect(value, path);
+}
+
+function normalizeCanonicalJson(
+  value: unknown,
+  path: string,
+  rejectSecretFields: boolean,
+  visited = new Set<object>(),
+): CanonicalJsonValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`${path} must contain only finite numbers.`);
+    }
+    return value;
+  }
+  if (typeof value !== 'object') {
+    throw new TypeError(`${path} must contain only JSON values.`);
+  }
+  if (visited.has(value)) {
+    throw new TypeError(`${path} must not contain cycles.`);
+  }
+  visited.add(value);
+
+  if (Array.isArray(value)) {
+    const normalized = value.map((entry, index) =>
+      normalizeCanonicalJson(
+        entry,
+        `${path}[${index}]`,
+        rejectSecretFields,
+        visited,
+      ),
+    );
+    visited.delete(value);
+    return Object.freeze(normalized);
+  }
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${path} must contain only plain JSON objects.`);
+  }
+
+  const normalized: Record<string, CanonicalJsonValue> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (
+      rejectSecretFields &&
+      isSecretField(key) &&
+      !SECRET_REFERENCE_SUFFIX_PATTERN.test(key)
+    ) {
+      throw new TypeError(
+        `${path}.${key} appears to contain secret material; pass an opaque reference ending in Ref or Refs instead.`,
+      );
+    }
+    normalized[key] = normalizeCanonicalJson(
+      entry,
+      `${path}.${key}`,
+      rejectSecretFields,
+      visited,
+    );
+  }
+  visited.delete(value);
+  return Object.freeze(normalized);
+}
+
+function isTenantField(key: string): boolean {
+  const normalized = key.replaceAll(/[_-]/gu, '').toLowerCase();
+  return [
+    'binding',
+    'context',
+    'domain',
+    'domainid',
+    'input',
+    'organization',
+    'organizationid',
+    'org',
+    'orgid',
+    'project',
+    'projectid',
+    'session',
+    'sessionid',
+    'tenant',
+    'tenantid',
+    'thread',
+    'threadid',
+    'user',
+    'userid',
+  ].includes(normalized);
+}
+
+function isSecretField(key: string): boolean {
+  return SECRET_FIELD_PATTERN.test(key) || SECRET_CAMEL_CASE_PATTERN.test(key);
+}
+
+function isPlainObject(
+  value: unknown,
+): value is Readonly<Record<string, unknown>> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}