@tiinex/core 0.1.1

package/src/tooling/portable/handoff/coldConsumerEntrypoint.js

@@ -0,0 +1,185 @@
+import { packageFileBytes, sha256Hex } from '../../../export/package.bytes.js';
+import { inspectHandoffCarrierProjection } from './carrierProjection.js';
+import { inspectHandoffPointerEntrypoints } from './pointerEntrypoint.js';
+import { inspectRecipientFacingV2Topology } from './recipientV2.inspect.js';
+import { RECIPIENT_V2_READ_PATH } from './recipientV2.topology.js';
+
+export const HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH = 'tiinex.package/START.md';
+export const HANDOFF_COLD_CONSUMER_PROJECTION_SCHEMA_ID = 'tiinex.portable.handoff-cold-consumer-projection.v1';
+export const HANDOFF_COLD_CONSUMER_ENTRYPOINT_INSPECTION_SCHEMA_ID = 'tiinex.portable.handoff-cold-consumer-entrypoint.inspection.v1';
+
+const BEGIN = '<!-- tiinex.handoff-start.projection.begin -->';
+const END = '<!-- tiinex.handoff-start.projection.end -->';
+const BOUNDARY = 'Package-local cold-consumer orientation only. This projection is generated from qualified package control/workspace bytes and has no Handoff, Parent, assignment, acceptance, completion, filename, or package-identity authority.';
+
+export function buildHandoffColdConsumerProjection(input = {}) {
+  const carrier = input.carrierProjection || input.projection || {};
+  const workspaces = Object.freeze((carrier.workspaces || []).map((workspace) => Object.freeze({
+    id: String(workspace.id || ''),
+    title: String(workspace.title || workspace.id || ''),
+    slug: String(workspace.slug || ''),
+    qualification: String(workspace.qualification || 'unresolved')
+  })));
+  const routes = Object.freeze((carrier.routes || []).map((route) => Object.freeze({
+    id: String(route.id || ''),
+    state: String(route.state || ''),
+    workspaceId: String(route.workspaceId || ''),
+    workspaceRelativeHandoffPath: String(route.workspaceRelativePath || ''),
+    packagePath: String(route.packagePath || ''),
+    sha256: String(route.sha256 || ''),
+    from: String(route.parties?.from || ''),
+    to: String(route.parties?.to || '')
+  })));
+  const qualifiedRoutes = routes.filter((route) => route.state === 'qualified');
+  const single = carrier.status === 'ready' && qualifiedRoutes.length === 1 ? qualifiedRoutes[0] : null;
+  return deepFreeze({
+    schema: HANDOFF_COLD_CONSUMER_PROJECTION_SCHEMA_ID,
+    version: 1,
+    status: carrier.status === 'ready' ? 'ready' : 'blocked',
+    boundary: BOUNDARY,
+    controls: Object.freeze({
+      start: HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH,
+      carrier: 'tiinex.package/handoff-carrier.json',
+      closure: 'tiinex.package/handoff-closure.json',
+      fileMap: 'tiinex.package/file-map.json',
+      manifest: 'tiinex.package/manifest.json'
+    }),
+    preferredPath: Object.freeze({
+      ingressKind: 'routed-handoff-package',
+      firstSemanticOperation: 'orient-handoff-package',
+      groundingOperation: 'ground-cold-consumer',
+      qualificationOperation: 'qualify-cold-start',
+      minimalHostBootstrapActions: 1,
+      nativeFallback: 'explicit-and-justified-only',
+      providerSpecificSemanticAuthority: false
+    }),
+    workspaces,
+    routes,
+    selection: Object.freeze({
+      policy: String(carrier.selection?.policy || ''),
+      qualifiedRouteCount: Number(carrier.selection?.qualifiedRouteCount || 0),
+      implicitRouteId: single?.id || ''
+    }),
+    authority: Object.freeze({
+      semanticAuthority: 'none',
+      packageTruthRequired: true,
+      routeBindingAuthority: 'correlated-carrier-and-closure-package-truth-only'
+    })
+  });
+}
+
+export function renderHandoffColdConsumerEntrypoint(input = {}) {
+  const projection = input.projection || buildHandoffColdConsumerProjection(input);
+  const workspaceLines = projection.workspaces.length
+    ? projection.workspaces.map((workspace) => `- \`${workspace.id}\` — ${workspace.title} (${workspace.qualification})`).join('\n')
+    : '- none qualified';
+  const routeLines = projection.routes.length
+    ? projection.routes.map((route) => `- \`${route.id}\` → workspace \`${route.workspaceId}\` / \`${route.workspaceRelativeHandoffPath}\` (${route.state})`).join('\n')
+    : '- none qualified';
+  const next = projection.selection.implicitRouteId
+    ? `Continue from the single qualified route \`${projection.selection.implicitRouteId}\`.`
+    : projection.selection.qualifiedRouteCount > 1
+      ? 'Select exactly one qualified route by route id before projecting recipient-facing output.'
+      : 'No qualified route is available; inspect the package control findings and fail closed.';
+  return `# Tiinex Handoff Package Start\n\nThis file is a generated orientation aid for a cold consumer. Read it without executing package code. The structured projection below is non-authoritative and must correlate with the package-local carrier, closure, file map, manifest, and carried workspace bytes.\n\n## Preferred Tiinex Ingress\n\nAfter the host has surfaced this package to qualified portable Tooling, invoke \`orient-handoff-package\` as the first semantic operation. Before that takeover, at most one minimal host/bootstrap ingress action is allowed. Do not perform arbitrary ZIP/filesystem archaeology first when qualified Tiinex orientation is available. Ground the recipient/participants/interaction with \`ground-cold-consumer\` before substantive work; native tools remain valid after takeover and as explicit justified fallback.\n\n## Workspaces\n\n${workspaceLines}\n\n## Routes\n\n${routeLines}\n\n## Next\n\n${next}\n\n${BEGIN}\n\`\`\`json\n${stablePrettyJson(projection)}\n\`\`\`\n${END}\n`;
+}
+
+export function inspectHandoffColdConsumerEntrypoint(bundle = {}, options = {}) {
+  const findings = [];
+  const file = findFile(bundle, HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH);
+  const parsed = file ? parseProjectionFromMarkdown(decodeUtf8(packageFileBytes(file))) : null;
+  if (!file) findings.push(finding('error', 'portable.handoff-start.missing', 'Handoff package is missing the package-local cold-consumer START entrypoint.'));
+  else if (!parsed) findings.push(finding('error', 'portable.handoff-start.projection.unparseable', 'Handoff START entrypoint does not contain one bounded parseable structured projection.'));
+  if (parsed && parsed.schema !== HANDOFF_COLD_CONSUMER_PROJECTION_SCHEMA_ID) findings.push(finding('error', 'portable.handoff-start.schema.invalid', 'Handoff START projection schema/version is unsupported.'));
+  if (parsed && parsed.boundary !== BOUNDARY) findings.push(finding('error', 'portable.handoff-start.boundary.invalid', 'Handoff START projection lost its non-authoritative package-orientation boundary.'));
+
+  const carrierInspection = options.carrierInspection || inspectHandoffCarrierProjection(bundle);
+  if (carrierInspection.status !== 'valid') findings.push(finding('error', 'portable.handoff-start.carrier.invalid', 'Handoff START cannot qualify because the package carrier projection does not independently correlate with current package truth.'));
+  if (parsed && carrierInspection.projection) {
+    const expected = buildHandoffColdConsumerProjection({ carrierProjection: carrierInspection.projection });
+    for (const field of ['status', 'controls', 'workspaces', 'routes', 'selection', 'authority']) {
+      if (stableJson(parsed[field]) !== stableJson(expected[field])) findings.push(finding('error', `portable.handoff-start.${field}.mismatch`, `Handoff START ${field} diverges from independently recomputed package truth.`));
+    }
+    if (Object.prototype.hasOwnProperty.call(parsed, 'preferredPath') && stableJson(parsed.preferredPath) !== stableJson(expected.preferredPath)) findings.push(finding('error', 'portable.handoff-start.preferredPath.mismatch', 'Handoff START preferredPath diverges from independently recomputed portable cold-start guidance.'));
+    if (parsed.authority?.semanticAuthority !== 'none' || parsed.authority?.packageTruthRequired !== true) findings.push(finding('error', 'portable.handoff-start.authority.promotion', 'Handoff START projection promotes orientation text into semantic authority.'));
+  }
+
+  return deepFreeze({
+    schema: HANDOFF_COLD_CONSUMER_ENTRYPOINT_INSPECTION_SCHEMA_ID,
+    status: findings.some((item) => item.severity === 'error') ? 'invalid' : 'valid',
+    path: HANDOFF_COLD_CONSUMER_ENTRYPOINT_PATH,
+    projection: parsed,
+    carrierInspection,
+    findings: Object.freeze(findings),
+    findingSummary: Object.freeze({ findings: findings.length, errors: findings.filter((item) => item.severity === 'error').length })
+  });
+}
+
+export function orientColdConsumerFromHandoffPackage(input = {}) {
+  const bundle = input.bundle || input;
+  if ((bundle.files || []).some((file) => String(file.path || '') === RECIPIENT_V2_READ_PATH)) {
+    const v2 = inspectRecipientFacingV2Topology(bundle);
+    const projection = v2.coldConsumerProjection || null;
+    const routeMetadata = new Map((v2.routes || []).map((route) => [`${String(route.workspaceId || '')}\u0000${String(route.workspaceRelativeHandoffPath || '')}`, route]));
+    const carrierRouteById = new Map((v2.carrierProjection?.routes || []).map((route) => [String(route.id || ''), route]));
+    const workspaceArchiveById = new Map((v2.workspaces || []).map((workspace) => {
+      const archivePath = String(workspace.workspaceArchivePath || '');
+      const archiveFile = (bundle.files || []).find((file) => String(file.path || '') === archivePath);
+      return [String(workspace.workspaceId || ''), Object.freeze({ path: archivePath, sha256: archiveFile ? sha256Hex(packageFileBytes(archiveFile)) : '' })];
+    }));
+    const routes = Object.freeze((projection?.routes || []).map((route) => {
+      const metadata = routeMetadata.get(`${String(route.workspaceId || '')}\u0000${String(route.workspaceRelativeHandoffPath || '')}`) || {};
+      const archive = workspaceArchiveById.get(String(route.workspaceId || '')) || {};
+      const carrierRoute = carrierRouteById.get(String(route.id || '')) || {};
+      const handoffSha256 = String(route.sha256 || '');
+      const handoffPath = String(route.workspaceRelativeHandoffPath || '');
+      return Object.freeze({ ...route, sha256: handoffSha256, sha256Target: handoffPath, handoffSha256, archiveSha256: String(archive.sha256 || ''), archivePackagePath: String(archive.path || route.packagePath || ''), requiredClosure: carrierRoute.requiredClosure || null, pointerPath: String(metadata.pointerPath || ''), endpointRolePointers: Object.freeze([...(metadata.endpointRolePointers || [])]), participantRolePointers: Object.freeze([...(metadata.participantRolePointers || [])]) });
+    }));
+    return deepFreeze({ schema: 'tiinex.portable.handoff-cold-consumer-orientation.v1', status: v2.status === 'valid' && projection?.status === 'ready' ? 'ready' : 'blocked', entrypoint: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-orientation.inspection.v1', status: v2.status, path: RECIPIENT_V2_READ_PATH, projection, findings: v2.findings }), pointerEntrypoints: Object.freeze({ schema: 'tiinex.portable.handoff-v2.recipient-pointer.inspection.v1', status: v2.status, entries: v2.routes, findings: v2.findings }), workspaces: projection?.workspaces || Object.freeze([]), carrierLineage: v2.carrierProjection?.lineage || null, routes, endpointRoles: v2.endpointRoles || Object.freeze([]), participantRoles: v2.participantRoles || Object.freeze([]), selection: projection?.selection || null, operationBoundary: orientationOperationBoundary(v2.bootstrapInspection), boundary: 'Read-only recipient-facing v2 orientation from qualified visible Tiinex artifacts and exact payload bytes; no legacy control JSON, filename, or adjacency authority.' });
+  }
+  const inspection = inspectHandoffColdConsumerEntrypoint(bundle);
+  const pointerEntrypoints = inspectHandoffPointerEntrypoints(bundle);
+  const projection = inspection.projection || null;
+  return deepFreeze({
+    schema: 'tiinex.portable.handoff-cold-consumer-orientation.v1',
+    status: inspection.status === 'valid' && pointerEntrypoints.status === 'valid' && projection?.status === 'ready' ? 'ready' : 'blocked',
+    entrypoint: inspection,
+    pointerEntrypoints,
+    workspaces: projection?.workspaces || Object.freeze([]),
+    routes: projection?.routes || Object.freeze([]),
+    selection: projection?.selection || null,
+    operationBoundary: orientationOperationBoundary(null),
+    boundary: 'Read-only package orientation. Received package code is not executed; START and package-root Pointer projections must independently correlate with package truth and never override it.'
+  });
+}
+
+function orientationOperationBoundary(bootstrapInspection = null) {
+  return Object.freeze({
+    operationClass: 'local-package-orientation',
+    inputScope: 'caller-provided-package-bytes',
+    readOnly: true,
+    packageContentExecution: false,
+    sourceMutation: false,
+    remoteMutation: false,
+    bootstrapInspection: String(bootstrapInspection?.status || 'unavailable'),
+    hostBehaviorAuthority: 'none'
+  });
+}
+
+function parseProjectionFromMarkdown(markdown = '') {
+  const text = String(markdown || '');
+  const begin = text.indexOf(BEGIN);
+  const end = text.indexOf(END);
+  if (begin < 0 || end < 0 || end <= begin || text.indexOf(BEGIN, begin + BEGIN.length) >= 0 || text.indexOf(END, end + END.length) >= 0) return null;
+  const bounded = text.slice(begin + BEGIN.length, end).trim();
+  const match = bounded.match(/^```json\s*\n([\s\S]*?)\n```$/);
+  if (!match) return null;
+  try { return JSON.parse(match[1]); } catch { return null; }
+}
+function findFile(bundle = {}, path = '') { return (bundle.files || []).find((file) => String(file.path || '') === String(path || '')) || null; }
+function decodeUtf8(data) { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { return ''; } }
+function stablePrettyJson(value) { return JSON.stringify(sortJson(value), null, 2); }
+function stableJson(value) { return JSON.stringify(sortJson(value)); }
+function sortJson(value) { if (Array.isArray(value)) return value.map(sortJson); if (!value || typeof value !== 'object') return value; return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortJson(value[key])])); }
+function finding(severity, code, message, extra = {}) { return Object.freeze({ severity, code, message, ...extra }); }
+function deepFreeze(value) { if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value; if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) return value; for (const child of Object.values(value)) deepFreeze(child); return Object.freeze(value); }

package/src/tooling/portable/handoff/coldStartQualification.contract.js

@@ -0,0 +1,184 @@
+import { discoverPortableHostCapabilities } from '../host/host.capabilities.js';
+import { deepFreeze, normalizeToken } from './coldStartQualification.shared.js';
+
+export const PORTABLE_COLD_START_INGRESS_CONTRACT_SCHEMA_ID = 'tiinex.portable.cold-start-ingress-contract.v1';
+
+export const PORTABLE_COLD_CONSUMER_GROUNDING_SCHEMA_ID = 'tiinex.portable.cold-consumer-grounding.v1';
+
+export const PORTABLE_COLD_START_QUALIFICATION_SCHEMA_ID = 'tiinex.portable.cold-start-qualification.v1';
+
+export const PORTABLE_COLD_START_HOST_PROJECTION_SCHEMA_ID = 'tiinex.portable.cold-start-host-projection.v1';
+
+export const COLD_START_INGRESS_KINDS = Object.freeze({
+  HANDOFF: 'routed-handoff-package',
+  WORKSPACE: 'workspace-bootstrap',
+  DEGRADED_CAPTURE: 'degraded-capture'
+});
+
+const INGRESS_PROFILES = deepFreeze({
+  [COLD_START_INGRESS_KINDS.HANDOFF]: {
+    firstSemanticOperation: 'orient-handoff-package',
+    requiredBeforeSubstantive: ['orient-handoff-package', 'ground-cold-consumer'],
+    orientationOperation: 'orient-handoff-package',
+    frontierOperation: 'orient-handoff-package',
+    minimalNativeBootstrapActions: 1,
+    description: 'A received routed Handoff package enters through qualified package orientation before arbitrary artifact archaeology.'
+  },
+  [COLD_START_INGRESS_KINDS.WORKSPACE]: {
+    firstSemanticOperation: 'discover-tooling',
+    requiredBeforeSubstantive: ['discover-tooling', 'search-lineage', 'ground-cold-consumer'],
+    orientationOperation: 'search-lineage',
+    frontierOperation: 'search-lineage',
+    minimalNativeBootstrapActions: 1,
+    description: 'A workspace with a qualified Tiinex bootstrap discovers host/session capabilities, then searches loaded lineage before arbitrary artifact reads.'
+  },
+  [COLD_START_INGRESS_KINDS.DEGRADED_CAPTURE]: {
+    firstSemanticOperation: '',
+    requiredBeforeSubstantive: [],
+    orientationOperation: '',
+    frontierOperation: '',
+    minimalNativeBootstrapActions: 0,
+    description: 'A Tooling-unavailable environment may preserve attributed contributions only; durable semantic qualification waits for a later Tooling-capable turn.'
+  }
+});
+
+export function describePortableColdStartIngress(input = {}) {
+  const kind = normalizeIngressKind(input.ingressKind || input.kind || COLD_START_INGRESS_KINDS.HANDOFF);
+  const profile = INGRESS_PROFILES[kind];
+  return deepFreeze({
+    schema: PORTABLE_COLD_START_INGRESS_CONTRACT_SCHEMA_ID,
+    version: 1,
+    ingressKind: kind,
+    profile,
+    metrics: Object.freeze([
+      'nativeActionsBeforeTiinexTakeover',
+      'unexpectedNativeActionsBeforeTiinexTakeover',
+      'arbitraryFilesReadBeforeOrientation',
+      'tiinexCallsToOrientation',
+      'totalActionsToOrientation',
+      'bytesToOrientation',
+      'timeToOrientationMs',
+      'candidateArtifactsInspectedBeforeOrientation',
+      'fallbackUsed',
+      'fallbackJustified'
+    ]),
+    qualification: Object.freeze({
+      recoveryIsNotPreferredPath: true,
+      qualifiedToolingAvailabilityMustBeObserved: true,
+      cli: 'qualify-cold-start <handoff-package.zip> --route <Continue-from> --pre-takeover minimal-bootstrap-only|none|native-archaeology',
+      evidenceBoundary: 'Tooling generates orientation/grounding receipts itself in one-shot mode. Pre-takeover native-host behavior remains caller/host evidence unless the host supplies independent instrumentation.',
+      firstSemanticOperationMustMatchProfile: true,
+      nativePreTakeoverUse: `At most ${profile.minimalNativeBootstrapActions} explicit minimal host/bootstrap ingress action(s); arbitrary semantic archaeology before Tiinex takeover does not qualify.`,
+      groundingBeforeSubstantiveWork: kind !== COLD_START_INGRESS_KINDS.DEGRADED_CAPTURE,
+      fallback: 'Explicit and justified only. Valid fallback may preserve recovery while remaining non-preferred when qualified Tiinex orientation was available.'
+    }),
+    authority: Object.freeze({
+      providerSpecificSemanticAuthority: false,
+      hostProjectionAuthority: false,
+      packagePlacementAuthority: false,
+      canonicalHandoffRoleSchemaProcessTruthPreserved: true,
+      providerNameGrantsCapability: false,
+      capabilityAdvertisementIsExerciseEvidence: false
+    }),
+    semanticSeparations: Object.freeze({
+      lineageLeafIsWorkflowFrontier: false,
+      lineageLeafIsTaskState: false,
+      workflowFrontierIsTaskState: false,
+      boundary: 'Lineage topology, current workflow frontier, and Task lifecycle state remain separate qualified observations; cold-start discovery must not collapse them into one currentness boolean.'
+    }),
+    traceability: Object.freeze({
+      operations: Object.freeze(['orient-handoff-package', 'search-lineage', 'discover-tooling', 'ground-cold-consumer', 'plan-host-action', 'accept-host-receipt']),
+      schemas: Object.freeze(['tiinex.handoff.v1', 'tiinex.party.role.v1']),
+      capabilityBinding: 'tiinex.portable.tooling-discovery.v1'
+    })
+  });
+}
+
+export function projectPortableColdStartHostGuidance(input = {}, options = {}) {
+  const ingressKind = normalizeIngressKind(input.ingressKind || input.kind || COLD_START_INGRESS_KINDS.HANDOFF);
+  const contract = describePortableColdStartIngress({ ingressKind });
+  const discovery = discoverPortableHostCapabilities(capabilityDiscoveryInput(input), options);
+  const capabilities = discovery.profile?.capabilities || {};
+  const packageReadable = Boolean(capabilities.materialAccess?.attachments || capabilities.materialAccess?.projectSources || capabilities.materialAccess?.filesystemRead || capabilities.materialAccess?.archiveRead);
+  const processReady = Boolean(capabilities.execution?.javascript || capabilities.execution?.shell || capabilities.execution?.process);
+  const requirements = ingressKind === COLD_START_INGRESS_KINDS.DEGRADED_CAPTURE
+    ? [requirement('contribution-capture', true, 'Preserve contribution and speaker attribution without Tooling-dependent mutation claims.')]
+    : [
+      requirement('package-or-workspace-readable', packageReadable, 'The host can surface explicitly supplied package/workspace bytes to portable Tooling.'),
+      requirement('portable-tooling-invocation', processReady || input.toolingInvocationAvailable === true, 'The host can invoke already-qualified portable Tooling or an equivalent registered Tooling entrypoint.'),
+      requirement('human-confirmation', Boolean(capabilities.interaction?.humanConfirmation), 'Explicit human confirmation is available when an operation requires it.', true),
+      requirement('artifact-return', Boolean(capabilities.interaction?.artifactReturn), 'The host can return generated local artifacts/results to the human.', true),
+      requirement('copyable-text-presentation', Boolean(capabilities.interaction?.copyableTextPresentation), 'The host can present exact copyable routing/result text when required.', true)
+    ];
+  const requiredMissing = requirements.filter((entry) => !entry.optional && !entry.satisfied);
+  return deepFreeze({
+    schema: PORTABLE_COLD_START_HOST_PROJECTION_SCHEMA_ID,
+    version: 1,
+    status: requiredMissing.length ? 'degraded' : 'ready',
+    ingressKind,
+    contract,
+    capabilityInstance: discovery.profile?.capabilityInstance || null,
+    capabilityDiscovery: discovery,
+    requirements: Object.freeze(requirements),
+    steps: Object.freeze(contract.profile.requiredBeforeSubstantive.map((operation, index) => Object.freeze({
+      order: index + 1,
+      operation,
+      authority: 'canonical-portable-operation-contract',
+      hostSpecificToolNameRequired: false
+    }))),
+    traceability: Object.freeze({
+      operationContract: 'tiinex.portable.operation.catalog.v1',
+      capabilityContract: 'tiinex.portable.tooling-discovery.v1',
+      handoffSchema: 'tiinex.handoff.v1',
+      roleSchema: 'tiinex.party.role.v1'
+    }),
+    authority: Object.freeze({
+      semanticAuthority: 'none',
+      providerSpecificSemanticAuthority: false,
+      providerNameGrantsCapability: false,
+      capabilityAdvertisementIsExerciseEvidence: false,
+      trustSensitiveExerciseStillRequiresAcceptedReceipt: true
+    }),
+    degraded: Object.freeze({
+      requiredMissing: Object.freeze(requiredMissing.map((entry) => entry.capability)),
+      fallbackMustBeExplicit: true,
+      hiddenNetworkAccess: false,
+      remoteWrite: false,
+      authenticationMayBeRequestedOnlyThroughDeclaredCapability: true
+    }),
+    boundary: 'Non-authoritative host/bootstrap projection derived from portable ingress and capability contracts. Hosts may render this into CLI, LLM, Viewer, IDE, or future provider-specific instruction formats without adding semantic rules.'
+  });
+}
+
+export function capabilityDiscoveryInput(input = {}) {
+  const host = input.host && typeof input.host === 'object' ? input.host : {};
+  return {
+    ...host,
+    tools: input.tools || input.availableTools || host.tools || host.availableTools || [],
+    capabilities: input.capabilities || input.hostCapabilities || host.capabilities,
+    provider: input.provider || host.provider,
+    hostIdentity: input.hostIdentity || input.hostContext || host.hostIdentity || host.host || nestedHostIdentity(host),
+    session: input.session || input.sessionContext || host.session,
+    capabilityInstanceId: input.capabilityInstanceId || host.capabilityInstanceId || ''
+  };
+}
+
+function nestedHostIdentity(host = {}) {
+  if (!host || typeof host !== 'object') return undefined;
+  const id = String(host.id || host.identifier || host.slug || '').trim();
+  const name = String(host.name || host.label || id || '').trim();
+  return id || name ? Object.freeze({ id, name }) : undefined;
+}
+
+function requirement(capability, satisfied, meaning, optional = false) {
+  return deepFreeze({ capability, satisfied: Boolean(satisfied), optional: Boolean(optional), meaning });
+}
+
+export function normalizeIngressKind(value) {
+  const normalized = normalizeToken(value).replace(/_/g, '-');
+  if (Object.prototype.hasOwnProperty.call(INGRESS_PROFILES, normalized)) return normalized;
+  if (['handoff', 'handoff-package', 'routed-handoff'].includes(normalized)) return COLD_START_INGRESS_KINDS.HANDOFF;
+  if (['workspace', 'workspace-with-bootstrap'].includes(normalized)) return COLD_START_INGRESS_KINDS.WORKSPACE;
+  if (['voice', 'stt', 'capture'].includes(normalized)) return COLD_START_INGRESS_KINDS.DEGRADED_CAPTURE;
+  return COLD_START_INGRESS_KINDS.HANDOFF;
+}